throughline 0.3.24 → 0.3.25

package/src/codex-sidecar.mjs

@@ -0,0 +1,246 @@
+import { spawnSync } from 'node:child_process';
+
+export const CODEX_SIDECAR_WORKFLOWS = Object.freeze([
+  'review',
+  'explore',
+  'work',
+  'opinion',
+  'risk-check',
+]);
+
+export const CODEX_SIDECAR_STATUS = Object.freeze({
+  DISABLED: 'disabled',
+  UNAVAILABLE: 'unavailable',
+  CONFIGURED: 'configured',
+  OPERATIONAL: 'operational',
+  WORK_CAPABLE: 'work-capable',
+});
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+function resolveCommand({ command, env }) {
+  return command ?? env.THROUGHLINE_CODEX_SIDECAR_BIN ?? 'codex-sidecar';
+}
+
+export function shouldShellWrapSidecarCommand(platform = process.platform) {
+  return platform === 'win32';
+}
+
+export function runCodexSidecarCommand(command, args, options = {}) {
+  return spawnSync(command, args, {
+    ...options,
+    shell: shouldShellWrapSidecarCommand(),
+  });
+}
+
+export function inferWorkflowForPreset(preset) {
+  if (CODEX_SIDECAR_WORKFLOWS.includes(preset)) return preset;
+  if (preset === 'summarize-l1') return 'explore';
+  return 'review';
+}
+
+/**
+ * Run codex-sidecar diagnostics without treating command presence as success.
+ *
+ * configured means diagnostics exited 0 for this repository. Any spawn failure
+ * or non-zero diagnostics result is explicit unavailable, not a hidden fallback.
+ *
+ * @param {{
+ *   projectPath: string,
+ *   preset?: string,
+ *   command?: string,
+ *   env?: NodeJS.ProcessEnv,
+ *   timeoutMs?: number,
+ * }} params
+ */
+export function diagnoseCodexSidecar({
+  projectPath,
+  preset = 'review',
+  command = null,
+  env = process.env,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+}) {
+  if (!projectPath) {
+    throw new Error('diagnoseCodexSidecar: projectPath is required');
+  }
+
+  if (env.THROUGHLINE_CODEX_SIDECAR_DISABLED === '1') {
+    return {
+      status: CODEX_SIDECAR_STATUS.DISABLED,
+      reason: 'disabled_by_env',
+      command: null,
+      projectPath,
+      preset,
+    };
+  }
+
+  const resolvedCommand = resolveCommand({ command, env });
+  const args = ['diagnostics', '--project', projectPath, '--preset', preset];
+  const result = runCodexSidecarCommand(resolvedCommand, args, {
+    encoding: 'utf8',
+    env,
+    timeout: timeoutMs,
+  });
+
+  if (result.error) {
+    return {
+      status: CODEX_SIDECAR_STATUS.UNAVAILABLE,
+      reason: result.error.code === 'ENOENT' ? 'command_not_found' : 'spawn_failed',
+      command: resolvedCommand,
+      args,
+      projectPath,
+      preset,
+      error: result.error.message,
+      stdout: result.stdout ?? '',
+      stderr: result.stderr ?? '',
+    };
+  }
+
+  if (result.status !== 0) {
+    return {
+      status: CODEX_SIDECAR_STATUS.UNAVAILABLE,
+      reason: 'diagnostics_failed',
+      command: resolvedCommand,
+      args,
+      projectPath,
+      preset,
+      exitCode: result.status,
+      signal: result.signal ?? null,
+      stdout: result.stdout ?? '',
+      stderr: result.stderr ?? '',
+    };
+  }
+
+  return {
+    status: CODEX_SIDECAR_STATUS.CONFIGURED,
+    reason: 'diagnostics_passed',
+    command: resolvedCommand,
+    args,
+    projectPath,
+    preset,
+    exitCode: 0,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}
+
+/**
+ * Build and execute a codex-sidecar dry-run request.
+ *
+ * This intentionally does not treat command presence as success. Callers get a
+ * structured failed result on spawn / parse / non-zero cases.
+ *
+ * @param {{
+ *   projectPath: string,
+ *   workflow?: string,
+ *   preset?: string,
+ *   contextFile?: string | null,
+ *   prompt?: string | null,
+ *   turnTimeoutMs?: number | null,
+ *   command?: string | null,
+ *   env?: NodeJS.ProcessEnv,
+ *   timeoutMs?: number,
+ * }} params
+ */
+export function runCodexSidecarDryRun({
+  projectPath,
+  workflow = null,
+  preset = 'review',
+  contextFile = null,
+  prompt = null,
+  turnTimeoutMs = null,
+  command = null,
+  env = process.env,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+}) {
+  if (!projectPath) {
+    throw new Error('runCodexSidecarDryRun: projectPath is required');
+  }
+
+  const resolvedWorkflow = workflow ?? inferWorkflowForPreset(preset);
+  if (!CODEX_SIDECAR_WORKFLOWS.includes(resolvedWorkflow)) {
+    throw new Error(
+      `runCodexSidecarDryRun: workflow must be one of ${CODEX_SIDECAR_WORKFLOWS.join(', ')}`,
+    );
+  }
+
+  const resolvedCommand = resolveCommand({ command, env });
+  const args = [
+    resolvedWorkflow,
+    '--project',
+    projectPath,
+    '--preset',
+    preset,
+    '--dry-run',
+  ];
+  if (contextFile) {
+    args.push('--context-file', contextFile);
+  }
+  if (turnTimeoutMs !== null) {
+    if (!Number.isInteger(turnTimeoutMs) || turnTimeoutMs < 1) {
+      throw new Error('runCodexSidecarDryRun: turnTimeoutMs must be a positive integer');
+    }
+    args.push('--turn-timeout-ms', String(turnTimeoutMs));
+  }
+  if (prompt) {
+    args.push(prompt);
+  }
+
+  const result = runCodexSidecarCommand(resolvedCommand, args, {
+    encoding: 'utf8',
+    env,
+    timeout: timeoutMs,
+  });
+
+  if (result.error) {
+    return {
+      status: 'failed',
+      reason: result.error.code === 'ENOENT' ? 'command_not_found' : 'spawn_failed',
+      command: resolvedCommand,
+      args,
+      projectPath,
+      workflow: resolvedWorkflow,
+      preset,
+      error: result.error.message,
+      stdout: result.stdout ?? '',
+      stderr: result.stderr ?? '',
+    };
+  }
+
+  if (result.status !== 0) {
+    return {
+      status: 'failed',
+      reason: 'dry_run_failed',
+      command: resolvedCommand,
+      args,
+      projectPath,
+      workflow: resolvedWorkflow,
+      preset,
+      exitCode: result.status,
+      signal: result.signal ?? null,
+      stdout: result.stdout ?? '',
+      stderr: result.stderr ?? '',
+    };
+  }
+
+  try {
+    return {
+      ...JSON.parse(result.stdout),
+      command: resolvedCommand,
+      args,
+    };
+  } catch (err) {
+    return {
+      status: 'failed',
+      reason: 'invalid_json',
+      command: resolvedCommand,
+      args,
+      projectPath,
+      workflow: resolvedWorkflow,
+      preset,
+      error: err instanceof Error ? err.message : String(err),
+      stdout: result.stdout ?? '',
+      stderr: result.stderr ?? '',
+    };
+  }
+}

package/src/codex-sidecar.test.mjs

@@ -0,0 +1,172 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  CODEX_SIDECAR_STATUS,
+  diagnoseCodexSidecar,
+  inferWorkflowForPreset,
+  runCodexSidecarDryRun,
+  shouldShellWrapSidecarCommand,
+} from './codex-sidecar.mjs';
+
+function makeExecutable(dir, name, body) {
+  const path = join(dir, name);
+  writeFileSync(path, body);
+  chmodSync(path, 0o755);
+  return path;
+}
+
+test('diagnoseCodexSidecar: disabled env is explicit disabled status', () => {
+  const result = diagnoseCodexSidecar({
+    projectPath: '/repo',
+    env: { ...process.env, THROUGHLINE_CODEX_SIDECAR_DISABLED: '1' },
+  });
+
+  assert.equal(result.status, CODEX_SIDECAR_STATUS.DISABLED);
+  assert.equal(result.reason, 'disabled_by_env');
+});
+
+test('diagnoseCodexSidecar: missing command is unavailable, not configured', () => {
+  const result = diagnoseCodexSidecar({
+    projectPath: '/repo',
+    command: '/definitely/missing/codex-sidecar',
+  });
+
+  assert.equal(result.status, CODEX_SIDECAR_STATUS.UNAVAILABLE);
+  assert.equal(result.reason, 'command_not_found');
+});
+
+test('diagnoseCodexSidecar: non-zero diagnostics is unavailable', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-sidecar-fail-'));
+  try {
+    const bin = makeExecutable(
+      dir,
+      'fake-sidecar',
+      '#!/usr/bin/env bash\nprintf "bad config" >&2\nexit 7\n',
+    );
+    const result = diagnoseCodexSidecar({
+      projectPath: '/repo',
+      command: bin,
+    });
+
+    assert.equal(result.status, CODEX_SIDECAR_STATUS.UNAVAILABLE);
+    assert.equal(result.reason, 'diagnostics_failed');
+    assert.equal(result.exitCode, 7);
+    assert.match(result.stderr, /bad config/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('diagnoseCodexSidecar: zero diagnostics is configured', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-sidecar-ok-'));
+  try {
+    const bin = makeExecutable(
+      dir,
+      'fake-sidecar',
+      '#!/usr/bin/env bash\nprintf "ok diagnostics for $*\\n"\nexit 0\n',
+    );
+    const result = diagnoseCodexSidecar({
+      projectPath: '/repo',
+      preset: 'review',
+      command: bin,
+    });
+
+    assert.equal(result.status, CODEX_SIDECAR_STATUS.CONFIGURED);
+    assert.equal(result.reason, 'diagnostics_passed');
+    assert.match(result.stdout, /diagnostics --project \/repo --preset review/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('inferWorkflowForPreset: maps known presets without guessing unavailable workflows', () => {
+  assert.equal(inferWorkflowForPreset('review'), 'review');
+  assert.equal(inferWorkflowForPreset('risk-check'), 'risk-check');
+  assert.equal(inferWorkflowForPreset('summarize-l1'), 'explore');
+  assert.equal(inferWorkflowForPreset('custom-review-preset'), 'review');
+});
+
+test('shouldShellWrapSidecarCommand: wraps npm bin shims on Windows only', () => {
+  assert.equal(shouldShellWrapSidecarCommand('win32'), true);
+  assert.equal(shouldShellWrapSidecarCommand('linux'), false);
+  assert.equal(shouldShellWrapSidecarCommand('darwin'), false);
+});
+
+test('runCodexSidecarDryRun: emits a dry-run request for review preset', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-sidecar-dry-run-'));
+  try {
+    const argsFile = join(dir, 'args.txt');
+    const bin = makeExecutable(
+      dir,
+      'fake-sidecar',
+      `#!/usr/bin/env bash
+printf '%s\\n' "$@" > "${argsFile}"
+printf '{"status":"dry-run","workflow":"review","normalizedRequest":{"dryRun":true}}\\n'
+`,
+    );
+    const result = runCodexSidecarDryRun({
+      projectPath: '/repo',
+      preset: 'review',
+      command: bin,
+      prompt: 'review prompt',
+      turnTimeoutMs: 12345,
+    });
+
+    assert.equal(result.status, 'dry-run');
+    assert.equal(result.workflow, 'review');
+    const argv = readFileSync(argsFile, 'utf8').trim().split('\n');
+    assert.deepEqual(argv, [
+      'review',
+      '--project',
+      '/repo',
+      '--preset',
+      'review',
+      '--dry-run',
+      '--turn-timeout-ms',
+      '12345',
+      'review prompt',
+    ]);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('runCodexSidecarDryRun: infers risk-check workflow from preset', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-sidecar-risk-dry-run-'));
+  try {
+    const argsFile = join(dir, 'args.txt');
+    const bin = makeExecutable(
+      dir,
+      'fake-sidecar',
+      `#!/usr/bin/env bash
+printf '%s\\n' "$@" > "${argsFile}"
+printf '{"status":"dry-run","workflow":"risk-check","normalizedRequest":{"dryRun":true}}\\n'
+`,
+    );
+    const result = runCodexSidecarDryRun({
+      projectPath: '/repo',
+      preset: 'risk-check',
+      command: bin,
+      contextFile: '/tmp/context.json',
+    });
+
+    assert.equal(result.status, 'dry-run');
+    assert.equal(result.workflow, 'risk-check');
+    const argv = readFileSync(argsFile, 'utf8').trim().split('\n');
+    assert.deepEqual(argv, [
+      'risk-check',
+      '--project',
+      '/repo',
+      '--preset',
+      'risk-check',
+      '--dry-run',
+      '--context-file',
+      '/tmp/context.json',
+    ]);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/codex-summarize.test.mjs

@@ -0,0 +1,143 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+
+function makeTempHome() {
+  return mkdtempSync(join(tmpdir(), 'tl-codex-summarize-home-'));
+}
+
+function makeTempProject() {
+  return mkdtempSync(join(tmpdir(), 'tl-codex-summarize-project-'));
+}
+
+function makeFakeCodexCli(dir) {
+  const script = join(dir, 'fake-codex-cli.mjs');
+  writeFileSync(
+    script,
+    `#!/usr/bin/env node
+let stdin = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { stdin += chunk; });
+process.stdin.on('end', () => {
+  if (process.argv[2] !== 'exec') process.exit(7);
+  if (!stdin.includes('[assistant]: assistant turn 1')) process.exit(8);
+  process.stdout.write('fake codex l1 summary\\n');
+});
+`,
+  );
+  chmodSync(script, 0o755);
+  return script;
+}
+
+async function seedDb(home, project, turnCount = 21) {
+  const originalHome = process.env.HOME;
+  const originalUserProfile = process.env.USERPROFILE;
+  process.env.HOME = home;
+  process.env.USERPROFILE = home;
+  try {
+    const mod = await import(`./db.mjs?codexSummarize=${Date.now()}-${Math.random()}`);
+    const db = mod.getDb();
+    db.prepare(
+      `INSERT INTO sessions (session_id, project_path, status, created_at, updated_at)
+       VALUES ('codex:thread-summary', ?, 'active', 1, 2)`,
+    ).run(project);
+    const insert = db.prepare(
+      `INSERT INTO bodies
+         (session_id, origin_session_id, turn_number, role, text, token_count, created_at)
+       VALUES ('codex:thread-summary', 'codex:thread-summary', ?, ?, ?, 3, ?)`,
+    );
+    for (let turn = 1; turn <= turnCount; turn++) {
+      insert.run(turn, 'user', `user turn ${turn}`, turn * 100);
+      insert.run(turn, 'assistant', `assistant turn ${turn}`, turn * 100 + 1);
+    }
+    db.close();
+  } finally {
+    if (originalHome === undefined) delete process.env.HOME;
+    else process.env.HOME = originalHome;
+    if (originalUserProfile === undefined) delete process.env.USERPROFILE;
+    else process.env.USERPROFILE = originalUserProfile;
+  }
+}
+
+function runSummarize(home, project, args = [], extraEnv = {}) {
+  return spawnSync(
+    process.execPath,
+    [join(REPO_ROOT, 'bin/throughline.mjs'), 'codex-summarize', ...args],
+    {
+      cwd: project,
+      env: {
+        ...process.env,
+        HOME: home,
+        USERPROFILE: home,
+        ...extraEnv,
+      },
+      encoding: 'utf8',
+    },
+  );
+}
+
+test('codex-summarize writes L1 skeleton through Codex CLI backend', async () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  try {
+    await seedDb(home, project, 21);
+    const fake = makeFakeCodexCli(project);
+    const result = runSummarize(
+      home,
+      project,
+      ['--session', 'codex:thread-summary', '--json'],
+      { THROUGHLINE_CODEX_CLI_BIN: fake },
+    );
+
+    assert.equal(result.status, 0, result.stderr);
+    const payload = JSON.parse(result.stdout);
+    assert.equal(payload.status, 'summarized');
+    assert.equal(payload.reason, 'codex_cli_l1_written');
+    assert.equal(payload.summarized[0].turnNumber, 1);
+    assert.equal(payload.summarized[0].source, 'codex-cli');
+
+    const originalHome = process.env.HOME;
+    const originalUserProfile = process.env.USERPROFILE;
+    process.env.HOME = home;
+    process.env.USERPROFILE = home;
+    try {
+      const mod = await import(`./db.mjs?codexSummarizeAssert=${Date.now()}-${Math.random()}`);
+      const db = mod.getDb();
+      const row = db.prepare('SELECT summary FROM skeletons WHERE turn_number = 1').get();
+      assert.equal(row.summary, 'fake codex l1 summary');
+      db.close();
+    } finally {
+      if (originalHome === undefined) delete process.env.HOME;
+      else process.env.HOME = originalHome;
+      if (originalUserProfile === undefined) delete process.env.USERPROFILE;
+      else process.env.USERPROFILE = originalUserProfile;
+    }
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('codex-summarize skips sessions inside the L2 window', async () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  try {
+    await seedDb(home, project, 20);
+    const result = runSummarize(home, project, ['--session', 'codex:thread-summary', '--json']);
+
+    assert.equal(result.status, 0, result.stderr);
+    const payload = JSON.parse(result.stdout);
+    assert.equal(payload.status, 'skipped');
+    assert.equal(payload.reason, 'within_l2_window');
+    assert.deepEqual(payload.summarized, []);
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});

package/src/codex-thread-identity.mjs

@@ -0,0 +1,23 @@
+export function resolveCodexThreadIdentity({ codexThreadId = null } = {}, env = process.env) {
+  if (codexThreadId) {
+    return {
+      codexThreadId,
+      codexThreadIdSource: 'arg:--codex-thread-id',
+    };
+  }
+
+  for (const name of ['THROUGHLINE_CODEX_THREAD_ID', 'CODEX_THREAD_ID']) {
+    const value = typeof env[name] === 'string' ? env[name].trim() : '';
+    if (value) {
+      return {
+        codexThreadId: value,
+        codexThreadIdSource: `env:${name}`,
+      };
+    }
+  }
+
+  return {
+    codexThreadId: null,
+    codexThreadIdSource: null,
+  };
+}