chore(codex): bootstrap PR for issue #144

.github/scripts/__tests__/api-helpers.test.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const { calculateBackoffDelay } = require('../api-helpers');
+
+function withStubbedRandom(value, fn) {
+  const originalRandom = Math.random;
+  Math.random = () => value;
+  try {
+    fn();
+  } finally {
+    Math.random = originalRandom;
+  }
+}
+
+test('calculateBackoffDelay applies positive jitter within expected range', () => {
+  withStubbedRandom(1, () => {
+    const delay = calculateBackoffDelay(1, 1000, 30000);
+    assert.equal(delay, 2500);
+  });
+});
+
+test('calculateBackoffDelay applies negative jitter within expected range', () => {
+  withStubbedRandom(0, () => {
+    const delay = calculateBackoffDelay(1, 1000, 30000);
+    assert.equal(delay, 1500);
+  });
+});

.github/scripts/__tests__/error-classifier.test.js

@@ -0,0 +1,105 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  ERROR_CATEGORIES,
+  classifyError,
+  suggestRecoveryAction,
+} = require('../error_classifier.js');
+
+test('classifyError returns transient for rate limit errors', () => {
+  const result = classifyError({ status: 429, message: 'Rate limit exceeded' });
+  assert.equal(result.category, ERROR_CATEGORIES.transient);
+  assert.match(result.recovery, /retry/i);
+});
+
+test('classifyError returns transient for timeout messages', () => {
+  const result = classifyError({ message: 'Request timed out after 30s' });
+  assert.equal(result.category, ERROR_CATEGORIES.transient);
+});
+
+test('classifyError returns auth for credential failures', () => {
+  const result = classifyError({ status: 401, message: 'Bad credentials' });
+  assert.equal(result.category, ERROR_CATEGORIES.auth);
+});
+
+test('classifyError uses error code for transient failures', () => {
+  const result = classifyError({ code: 'ETIMEDOUT' });
+  assert.equal(result.category, ERROR_CATEGORIES.transient);
+});
+
+test('classifyError uses error code for network lookup failures', () => {
+  const result = classifyError({ code: 'ENOTFOUND' });
+  assert.equal(result.category, ERROR_CATEGORIES.transient);
+});
+
+test('classifyError returns resource for not found errors', () => {
+  const result = classifyError({ status: 404, message: 'Not Found' });
+  assert.equal(result.category, ERROR_CATEGORIES.resource);
+});
+
+test('classifyError returns auth for unauthorized messages', () => {
+  const result = classifyError({ message: 'Unauthorized' });
+  assert.equal(result.category, ERROR_CATEGORIES.auth);
+});
+
+test('classifyError returns logic for validation errors', () => {
+  const result = classifyError({ status: 422, message: 'Validation failed' });
+  assert.equal(result.category, ERROR_CATEGORIES.logic);
+});
+
+test('classifyError inspects nested API error details', () => {
+  const result = classifyError({
+    status: 400,
+    response: { data: { errors: [{ message: 'Missing required field: title' }] } },
+  });
+  assert.equal(result.category, ERROR_CATEGORIES.logic);
+});
+
+test('classifyError returns unknown when no signals are present', () => {
+  const result = classifyError({ message: '' });
+  assert.equal(result.category, ERROR_CATEGORIES.unknown);
+});
+
+test('suggestRecoveryAction falls back to unknown guidance', () => {
+  const result = suggestRecoveryAction('missing');
+  assert.equal(result, suggestRecoveryAction(ERROR_CATEGORIES.unknown));
+});
+
+test('classifyError provides category-specific recovery guidance', () => {
+  const cases = [
+    {
+      error: { status: 429, message: 'Rate limit exceeded' },
+      category: ERROR_CATEGORIES.transient,
+      recoveryPattern: /retry/i,
+    },
+    {
+      error: { status: 401, message: 'Bad credentials' },
+      category: ERROR_CATEGORIES.auth,
+      recoveryPattern: /credentials|token|permission/i,
+    },
+    {
+      error: { status: 404, message: 'Not found' },
+      category: ERROR_CATEGORIES.resource,
+      recoveryPattern: /resource|repository|branch|workflow/i,
+    },
+    {
+      error: { status: 422, message: 'Validation failed' },
+      category: ERROR_CATEGORIES.logic,
+      recoveryPattern: /request|inputs|logic/i,
+    },
+    {
+      error: { message: '' },
+      category: ERROR_CATEGORIES.unknown,
+      recoveryPattern: /logs|retry|escalate/i,
+    },
+  ];
+
+  for (const entry of cases) {
+    const result = classifyError(entry.error);
+    assert.equal(result.category, entry.category);
+    assert.match(result.recovery, entry.recoveryPattern);
+  }
+});

.github/scripts/__tests__/error-diagnostics.test.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  collectErrorDiagnostics,
+  sanitizeObject,
+} = require('../error_diagnostics');
+
+test('collectErrorDiagnostics captures allowed env values and error info', () => {
+  const env = {
+    GITHUB_REPOSITORY: 'octo/workflows',
+    GITHUB_RUN_ID: '123',
+    GITHUB_WORKFLOW: 'Codex',
+    ERROR_CATEGORY: 'auth',
+    ERROR_MESSAGE: 'Bad credentials',
+  };
+  const diagnostics = collectErrorDiagnostics({ env });
+
+  assert.equal(diagnostics.run.GITHUB_REPOSITORY, 'octo/workflows');
+  assert.equal(diagnostics.run.GITHUB_RUN_ID, '123');
+  assert.equal(diagnostics.run.GITHUB_WORKFLOW, 'Codex');
+  assert.equal(diagnostics.error.ERROR_CATEGORY, 'auth');
+  assert.equal(diagnostics.error.ERROR_MESSAGE, 'Bad credentials');
+});
+
+test('collectErrorDiagnostics sanitizes extra payloads', () => {
+  const env = {
+    GITHUB_REPOSITORY: 'octo/workflows',
+  };
+  const extra = {
+    step: 'classify-error',
+    token: 'secret-value',
+    nested: {
+      credential_hint: 'should-drop',
+      info: 'safe',
+    },
+  };
+  const diagnostics = collectErrorDiagnostics({ env, extra });
+
+  assert.equal(diagnostics.extra.step, 'classify-error');
+  assert.equal(diagnostics.extra.nested.info, 'safe');
+  assert.equal(diagnostics.extra.token, undefined);
+  assert.equal(diagnostics.extra.nested.credential_hint, undefined);
+});
+
+test('sanitizeObject removes secret-like keys from payloads', () => {
+  const payload = {
+    safe: true,
+    TokenValue: 'redact',
+    inner: {
+      credential: 'drop',
+      ok: 'keep',
+    },
+  };
+  const sanitized = sanitizeObject(payload);
+
+  assert.deepEqual(sanitized, { safe: true, inner: { ok: 'keep' } });
+});

.github/scripts/__tests__/failure-comment-formatter.test.js

@@ -0,0 +1,119 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  COMMENT_MARKER,
+  formatFailureComment,
+  isFailureComment,
+} = require('../failure_comment_formatter.js');
+
+test('formatFailureComment includes marker for deduplication', () => {
+  const result = formatFailureComment({
+    mode: 'keepalive',
+    exitCode: '1',
+    errorCategory: 'transient',
+    errorType: 'infrastructure',
+    recovery: 'Retry after a short delay.',
+    summary: 'Request timed out',
+    runUrl: 'https://github.com/test/repo/actions/runs/123',
+  });
+
+  assert.ok(result.includes(COMMENT_MARKER));
+});
+
+test('formatFailureComment includes all required fields', () => {
+  const result = formatFailureComment({
+    mode: 'autofix',
+    exitCode: '2',
+    errorCategory: 'auth',
+    errorType: 'auth',
+    recovery: 'Check credentials.',
+    summary: 'Bad credentials',
+    runUrl: 'https://github.com/test/repo/actions/runs/456',
+  });
+
+  assert.ok(result.includes('autofix'));
+  assert.ok(result.includes('`2`'));
+  assert.ok(result.includes('`auth`'));
+  assert.ok(result.includes('Check credentials.'));
+  assert.ok(result.includes('Bad credentials'));
+  assert.ok(result.includes('[View logs]'));
+});
+
+test('formatFailureComment truncates long summaries', () => {
+  const longSummary = 'x'.repeat(1000);
+  const result = formatFailureComment({
+    mode: 'verifier',
+    exitCode: '1',
+    errorCategory: 'unknown',
+    errorType: 'codex',
+    recovery: 'Check output.',
+    summary: longSummary,
+    runUrl: '',
+  });
+
+  // Should be truncated to 500 chars + "..."
+  assert.ok(result.includes('x'.repeat(500)));
+  assert.ok(result.includes('...'));
+  assert.ok(!result.includes('x'.repeat(600)));
+});
+
+test('formatFailureComment handles missing runUrl gracefully', () => {
+  const result = formatFailureComment({
+    mode: 'keepalive',
+    exitCode: '1',
+    errorCategory: 'resource',
+    errorType: 'infrastructure',
+    recovery: 'Check resource.',
+    summary: 'Not found',
+    runUrl: '',
+  });
+
+  assert.ok(result.includes('N/A'));
+});
+
+test('formatFailureComment uses defaults for missing params', () => {
+  const result = formatFailureComment({});
+
+  assert.ok(result.includes('unknown'));
+  assert.ok(result.includes('No output captured'));
+  assert.ok(result.includes('Check logs for details.'));
+});
+
+test('isFailureComment returns true for comments with marker', () => {
+  const body = `${COMMENT_MARKER}\n## Some content`;
+  assert.equal(isFailureComment(body), true);
+});
+
+test('isFailureComment returns false for comments without marker', () => {
+  const body = '## Some other comment';
+  assert.equal(isFailureComment(body), false);
+});
+
+test('isFailureComment handles null and undefined', () => {
+  assert.equal(isFailureComment(null), false);
+  assert.equal(isFailureComment(undefined), false);
+  assert.equal(isFailureComment(''), false);
+});
+
+test('formatFailureComment produces valid markdown table', () => {
+  const result = formatFailureComment({
+    mode: 'keepalive',
+    exitCode: '1',
+    errorCategory: 'logic',
+    errorType: 'codex',
+    recovery: 'Fix logic error.',
+    summary: 'Validation failed',
+    runUrl: 'https://example.com/run/789',
+  });
+
+  // Check table structure
+  assert.ok(result.includes('| Field | Value |'));
+  assert.ok(result.includes('|-------|-------|'));
+  assert.ok(result.includes('| Exit Code |'));
+  assert.ok(result.includes('| Error Category |'));
+  assert.ok(result.includes('| Error Type |'));
+  assert.ok(result.includes('| Run |'));
+});