@lyupro/codex-bridge 0.1.3 → 0.2.0

package/cli/prune-plan.mjs

@@ -0,0 +1,205 @@
+/** Builds a read-only prune plan from run inventory data and folder-name ages. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { listProjectRuns, listProjects, recursiveSize } from './runs-inventory.mjs';
+import { parseOlderThan } from './prune-args.mjs';
+import { runsRoot } from '../src/runner/runs-root.mjs';
+import { runIsOlderThan, TRANSPORT_FILES } from '../src/retention.mjs';
+
+export { runIsOlderThan, TRANSPORT_FILES };
+
+function safeFolderName(value) {
+  return typeof value === 'string'
+    && value.trim()
+    && value !== '.'
+    && value !== '..'
+    && !path.isAbsolute(value)
+    && path.dirname(value) === '.';
+}
+
+function normalizeOlderThan(value) {
+  if (!value) return null;
+  if (typeof value === 'string') {
+    const parsed = parseOlderThan(value);
+    return parsed.error ? null : parsed;
+  }
+  return value;
+}
+
+function fileDetails(runDir) {
+  return TRANSPORT_FILES.flatMap((name) => {
+    const target = path.join(runDir, name);
+    try {
+      const stat = fs.lstatSync(target);
+      if (!stat.isFile()) return [];
+      return [{ name, path: target, bytes: stat.size }];
+    } catch {
+      return [];
+    }
+  });
+}
+
+function sumBytes(items) {
+  return items.every((item) => Number.isFinite(item.bytes))
+    ? items.reduce((sum, item) => sum + item.bytes, 0)
+    : null;
+}
+
+function gentleAction(root, project, run) {
+  const runDir = path.join(root, project, run.run);
+  const files = fileDetails(runDir);
+  if (!files.length) return null;
+  return {
+    kind: 'run',
+    mode: 'gentle',
+    project,
+    run: run.run,
+    path: runDir,
+    files,
+    targets: files.map((file) => file.path),
+    bytes: sumBytes(files),
+  };
+}
+
+function runPurgeAction(root, project, run) {
+  const runDir = path.join(root, project, run.run);
+  return {
+    kind: 'run',
+    mode: 'purge',
+    project,
+    run: run.run,
+    path: runDir,
+    files: [],
+    targets: [runDir],
+    bytes: recursiveSize(runDir),
+  };
+}
+
+function projectPurgeAction(root, project, runs) {
+  const projectDir = path.join(root, project);
+  return {
+    kind: 'project',
+    mode: 'purge',
+    project,
+    run: null,
+    path: projectDir,
+    files: [],
+    targets: [projectDir],
+    bytes: recursiveSize(projectDir),
+    runs: runs.map((run) => run.run),
+  };
+}
+
+function selectedRuns(runs, olderThan, now) {
+  return olderThan ? runs.filter((run) => runIsOlderThan(run.run, olderThan, now)) : runs;
+}
+
+/**
+ * A live run is never a prune target. Its events.jsonl is the verdict being written: delete it and
+ * the run ends with "artifacts disagree" over work that was actually done — the exact loss this
+ * package spent Plan_15 and Plan_16 removing. The inventory already marks liveness through
+ * hooks/live-runs.mjs, so this costs nothing and asks no second opinion.
+ */
+function withoutLiveRuns(runs) {
+  // By the pid probe, not by status.json: an abandoned run also reads `running` there, and those
+  // are exactly the folders worth cleaning.
+  return runs.filter((run) => run.live !== true);
+}
+
+function projectNames(root) {
+  return listProjects(root).map((project) => project.project);
+}
+
+function projectRuns(root, project) {
+  return listProjectRuns(root, project);
+}
+
+function broadProjectPlan(root, project, args, age, now) {
+  const all = projectRuns(root, project);
+  if (all === null) return { error: `codex-bridge prune: unknown project "${project}"` };
+  const live = all.filter((run) => run.live === true);
+  if (args.purge && live.length) {
+    return {
+      actions: [],
+      note: `${live.length} run(s) in "${project}" are still going; a project purge would delete a run that is writing right now`,
+    };
+  }
+  const runs = withoutLiveRuns(all);
+  const selected = selectedRuns(runs, age, now);
+  if (args.purge) {
+    // A whole-project purge must not let a recent or undated run hide behind an old one. Saying
+    // why matters as much as refusing: an empty plan without a reason reads as a broken command,
+    // and the operator's next move is to try again harder.
+    if (selected.length !== runs.length) {
+      return {
+        actions: [],
+        note: `${runs.length - selected.length} of ${runs.length} runs in "${project}" are newer than the age filter, so the whole-project purge is refused; drop --older-than to purge the folder, or prune the old runs one by one`,
+      };
+    }
+    return { actions: [projectPurgeAction(root, project, runs)] };
+  }
+  return {
+    actions: selected.map((run) => gentleAction(root, project, run)).filter(Boolean),
+  };
+}
+
+function namedRunPlan(root, project, runName, args, age, now) {
+  const runs = projectRuns(root, project);
+  if (runs === null) return { error: `codex-bridge prune: unknown project "${project}"` };
+  const run = runs.find((entry) => entry.run === runName);
+  if (!run) return { error: `codex-bridge prune: unknown run "${runName}" in project "${project}"` };
+  if (run.live === true) {
+    return {
+      error: `codex-bridge prune: run "${runName}" is still going; its events.jsonl is the verdict being written`,
+    };
+  }
+  if (age && !runIsOlderThan(run.run, age, now)) return { actions: [] };
+  const action = args.purge
+    ? runPurgeAction(root, project, run)
+    : gentleAction(root, project, run);
+  return { actions: action ? [action] : [] };
+}
+
+/** Purely decides what prune would remove; it never writes or deletes a filesystem entry. */
+export function prunePlan(args = {}, options = {}) {
+  const root = path.resolve(options.runsRootPath || args.runsRootPath || runsRoot());
+  const now = options.now ?? Date.now();
+  const scope = args.allProjects ? 'all-projects' : args.runName ? 'run' : 'project';
+  const age = normalizeOlderThan(args.olderThan);
+
+  let actions = [];
+  let note = null;
+  if (args.allProjects) {
+    for (const project of projectNames(root)) {
+      const result = broadProjectPlan(root, project, { ...args, purge: false }, age, now);
+      if (result.error) return result;
+      actions.push(...result.actions);
+    }
+  } else if (!safeFolderName(args.projectName)) {
+    return { error: 'codex-bridge prune: a bare project folder name is required' };
+  } else if (args.runName) {
+    if (!safeFolderName(args.runName)) {
+      return { error: 'codex-bridge prune: a bare run folder name is required' };
+    }
+    const result = namedRunPlan(root, args.projectName, args.runName, args, age, now);
+    if (result.error) return result;
+    actions = result.actions;
+  } else {
+    const result = broadProjectPlan(root, args.projectName, args, age, now);
+    if (result.error) return result;
+    actions = result.actions;
+    note = result.note ?? null;
+  }
+
+  return {
+    root,
+    scope,
+    mode: args.purge ? 'purge' : 'gentle',
+    project: args.projectName || null,
+    run: args.runName || null,
+    olderThan: age,
+    actions,
+    note,
+    bytes: sumBytes(actions),
+  };
+}

package/cli/prune.mjs

@@ -0,0 +1,278 @@
+/** Confirms, executes, and reports the destructive actions in a prune plan. */
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { normalizePath } from '../src/hooks/live-runs.mjs';
+import { parsePruneArgs } from './prune-args.mjs';
+import { prunePlan } from './prune-plan.mjs';
+import { recursiveSize } from './runs-inventory.mjs';
+
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes)) return 'unknown';
+  if (bytes >= 1024 ** 3) return `${(bytes / 1024 ** 3).toFixed(1)} GB`;
+  if (bytes >= 1024 ** 2) return `${(bytes / 1024 ** 2).toFixed(1)} MB`;
+  if (bytes >= 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${bytes} B`;
+}
+
+function ageText(olderThan) {
+  if (!olderThan) return null;
+  return olderThan.kind === 'date' ? olderThan.date : `${olderThan.amount}${olderThan.unit}`;
+}
+
+function commandText(args) {
+  const scope = args.allProjects
+    ? '--all-projects'
+    : [args.projectName, args.runName].filter(Boolean).join(' ');
+  const flags = [];
+  if (args.purge) flags.push('--purge');
+  if (args.olderThanExplicit) flags.push('--older-than', ageText(args.olderThan));
+  flags.push('-f');
+  return ['codex-bridge prune', scope, ...flags].join(' ');
+}
+
+function actionPayload(action) {
+  return {
+    kind: action.kind,
+    mode: action.mode,
+    project: action.project,
+    run: action.run,
+    targets: action.targets,
+    bytes: action.bytes,
+  };
+}
+
+function basePayload(plan) {
+  return {
+    scope: plan.scope,
+    mode: plan.mode,
+    project: plan.project,
+    run: plan.run,
+    olderThan: ageText(plan.olderThan),
+    note: plan.note ?? null,
+    actions: plan.actions.map(actionPayload),
+    bytes: plan.bytes,
+  };
+}
+
+function planLines(plan, args) {
+  const lines = [
+    `Prune plan: ${plan.mode} ${plan.scope}.`,
+    plan.olderThan ? `Age filter: older than ${ageText(plan.olderThan)} (folder name date).` : 'Age filter: none.',
+  ];
+  for (const action of plan.actions) {
+    for (const target of action.targets) lines.push(`Would remove ${target}`);
+  }
+  if (!plan.actions.length) {
+    lines.push(plan.note ? `Nothing would be removed: ${plan.note}.` : 'Nothing would be removed.');
+  }
+  lines.push(`Space to free: ${formatBytes(plan.bytes)}.`);
+  lines.push('Nothing was deleted.');
+  lines.push(`To execute: ${commandText(args)}`);
+  return lines.join('\n');
+}
+
+function reportLines(payload, status) {
+  const lines = [
+    status === 'completed'
+      ? 'Prune completed.'
+      : status === 'cancelled'
+        ? 'Prune cancelled; no files were deleted.'
+        : 'Prune failed.',
+  ];
+  if (payload.removed.length) {
+    lines.push('Removed:');
+    for (const target of payload.removed) lines.push(`  ${target}`);
+  } else {
+    lines.push('Removed: nothing.');
+  }
+  lines.push(`Space freed: ${formatBytes(payload.bytesFreed)}.`);
+  if (payload.failed?.length) {
+    lines.push('Failed:');
+    for (const failure of payload.failed) lines.push(`  ${failure.target}: ${failure.error}`);
+  }
+  return lines.join('\n');
+}
+
+function output(value, json) {
+  return json ? JSON.stringify(value, null, 2) : value.error || reportLines(value, value.status);
+}
+
+function result(exitCode, text) {
+  return { exitCode, output: text };
+}
+
+// One spelling only. A guard that answers to several option names is a guard with several ways
+// to be switched off by accident.
+function tty(options) {
+  if (options.isTTY !== undefined) return Boolean(options.isTTY);
+  return Boolean((options.stdin || process.stdin).isTTY);
+}
+
+async function defaultPrompt(question, options = {}) {
+  const input = options.stdin || process.stdin;
+  const outputStream = options.promptOutput || process.stderr;
+  const interfaceHandle = readline.createInterface({ input, output: outputStream });
+  try {
+    const answer = await interfaceHandle.question(`${question} [y/N] `);
+    return /^(y|yes)$/i.test(answer.trim());
+  } finally {
+    interfaceHandle.close();
+  }
+}
+
+function accepted(answer) {
+  return answer === true || /^(y|yes)$/i.test(String(answer ?? '').trim());
+}
+
+// The package compares paths through one function, and this guard is the last thing standing
+// between a bug and rm -r. Raw string comparison is case-sensitive: a runs root spelled
+// `C:\Users\...` against a target resolved as `c:\users\...` would put every target "outside the
+// root", and the deletion would fail with a reason that names the wrong problem.
+function targetInsideRoot(target, root) {
+  const normalizedRoot = normalizePath(root);
+  const normalizedTarget = normalizePath(target);
+  if (!normalizedRoot || !normalizedTarget) return false;
+  return normalizedTarget !== normalizedRoot && normalizedTarget.startsWith(`${normalizedRoot}/`);
+}
+
+/**
+ * Refuses a target reached through a link. Independent review found that lexical containment alone
+ * is satisfiable: replace `<root>/<project>` with a junction to an external directory and a target
+ * that still spells out as inside the root deletes what is outside it. The package deliberately
+ * does not resolve paths (`realpath` returns `\\?\` and UNC forms on Windows and creates a new
+ * class of mismatch), so the check is the cheap half instead: every segment from the root down to
+ * the target must be a real directory, verified with lstat right before deletion.
+ */
+function linkedSegment(target, root) {
+  const normalizedRoot = normalizePath(root);
+  let current = path.resolve(target);
+  while (normalizePath(current) !== normalizedRoot) {
+    try {
+      if (fs.lstatSync(current).isSymbolicLink()) return current;
+    } catch {
+      return null; // Already gone: rmSync will report it honestly.
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+  return null;
+}
+
+function currentTargetBytes(target, mode) {
+  if (mode === 'purge') {
+    // The inventory's recursive measurement is the same accounting used by projects and keeps
+    // the report honest when a purge contains nested files.
+    return recursiveSize(target);
+  }
+  try {
+    return fs.lstatSync(target).size;
+  } catch {
+    return null;
+  }
+}
+
+async function confirmAll(plan, args, options) {
+  const prompt = options.prompt || defaultPrompt;
+  for (const action of plan.actions) {
+    const question = action.mode === 'purge'
+      ? `Delete folder ${action.path}?`
+      : `Delete archived transport from ${action.project}/${action.run}?\n  ${action.targets.join('\n  ')}`;
+    let answer;
+    try {
+      answer = await prompt(question, action, options);
+    } catch (err) {
+      return { error: `codex-bridge prune: confirmation failed: ${err.message}` };
+    }
+    if (!accepted(answer)) return { declined: true };
+  }
+  return { declined: false };
+}
+
+function bytesAfterRemoval(values) {
+  return values.every((value) => Number.isFinite(value))
+    ? values.reduce((sum, value) => sum + value, 0)
+    : null;
+}
+
+async function execute(plan, options) {
+  const removed = [];
+  const sizes = [];
+  const failed = [];
+  for (const action of plan.actions) {
+    for (const target of action.targets) {
+      if (!targetInsideRoot(target, plan.root)) {
+        failed.push({ target, error: 'target is outside the configured runs root' });
+        continue;
+      }
+      const linked = linkedSegment(target, plan.root);
+      if (linked) {
+        failed.push({ target, error: `refusing to delete through a link: ${linked}` });
+        continue;
+      }
+      const bytes = currentTargetBytes(target, action.mode);
+      try {
+        fs.rmSync(target, { recursive: action.mode === 'purge', force: false });
+        removed.push(target);
+        sizes.push(bytes);
+      } catch (err) {
+        failed.push({ target, error: err.message });
+      }
+    }
+  }
+  const payload = {
+    ...basePayload(plan),
+    status: failed.length ? 'failed' : 'completed',
+    removed,
+    bytesFreed: bytesAfterRemoval(sizes),
+    failed,
+  };
+  return { payload, exitCode: failed.length ? 1 : 0 };
+}
+
+/** Runs prune with force, TTY, and confirmation guards around the shared read-only plan. */
+export async function prune(argv = [], options = {}) {
+  const args = parsePruneArgs(argv);
+  if (args.error) {
+    const payload = { status: 'error', error: args.error };
+    return result(2, argv.includes('--json') ? output(payload, true) : payload.error);
+  }
+
+  const plan = prunePlan(args, options);
+  if (plan.error) {
+    const payload = { status: 'error', error: plan.error };
+    return result(1, output(payload, args.json));
+  }
+  if (!args.force) {
+    return result(0, args.json
+      ? JSON.stringify({ status: 'plan', ...basePayload(plan), command: commandText(args) }, null, 2)
+      : planLines(plan, args));
+  }
+  if (!plan.actions.length) {
+    const payload = { status: 'completed', ...basePayload(plan), removed: [], bytesFreed: 0, failed: [] };
+    return result(0, output(payload, args.json));
+  }
+  if (!tty(options)) {
+    const message = 'No TTY: refusing deletion because deletion is an operator action; no files were changed.';
+    const payload = { status: 'refused', ...basePayload(plan), error: message, removed: [], bytesFreed: 0 };
+    return result(1, output(payload, args.json));
+  }
+
+  const confirmation = await confirmAll(plan, args, options);
+  if (confirmation.error) {
+    const payload = { status: 'error', ...basePayload(plan), error: confirmation.error, removed: [], bytesFreed: 0 };
+    return result(1, output(payload, args.json));
+  }
+  if (confirmation.declined) {
+    const payload = { status: 'cancelled', ...basePayload(plan), removed: [], bytesFreed: 0 };
+    return result(1, output(payload, args.json));
+  }
+
+  const executed = await execute(plan, options);
+  return result(executed.exitCode, args.json
+    ? output(executed.payload, true)
+    : reportLines(executed.payload, executed.payload.status));
+}
+
+export { defaultPrompt };

package/cli/read.mjs

@@ -0,0 +1,103 @@
+/** Renders a run's structured Codex transport as a readable event-by-event report. */
+import { readEvents } from '../src/meta/events.mjs';
+import { runsRoot } from '../src/runner/runs-root.mjs';
+import { resolveRunFolder } from './run-lookup.mjs';
+
+const result = (exitCode, output) => ({ exitCode, output });
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value);
+
+const inline = (value, max = 300) => String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, max);
+
+function compactJson(value, max = 300) {
+  let text;
+  try {
+    text = JSON.stringify(value);
+  } catch {
+    text = String(value);
+  }
+  return inline(text, max) || '{}';
+}
+
+function itemSection(item) {
+  const type = typeof item?.type === 'string' && item.type ? item.type : 'unknown item';
+  if (type === 'agent_message') {
+    return `${type}\n${String(item.text ?? item.message ?? '')}`.trimEnd();
+  }
+  if (type === 'error') {
+    return `${type}\n${inline(item.message) || compactJson(item)}`;
+  }
+  const shortText = ['text', 'message', 'summary', 'output', 'command', 'result']
+    .map((key) => item?.[key])
+    .find((value) => typeof value === 'string' && value.trim());
+  return `${type}\n${shortText ? inline(shortText) : compactJson(item)}`;
+}
+
+function usageSection(usage) {
+  if (!record(usage)) return 'turn.completed\nUsage: unavailable';
+  const numbers = Object.entries(usage)
+    .map(([key, value]) => `${key}=${String(value)}`)
+    .join(', ');
+  return `turn.completed\nUsage: ${numbers || 'unavailable'}`;
+}
+
+function serviceSection(event) {
+  if (event.type === 'thread.started') {
+    return `${event.type} · Thread ID: ${event.thread_id ?? 'unknown'}`;
+  }
+  if (event.type === 'item.started' && typeof event.item?.type === 'string' && event.item.type) {
+    return `${event.type} · Item: ${event.item.type}`;
+  }
+  return event.type;
+}
+
+function transportSection(event, transportError) {
+  const nested = record(event.error) ? event.error : {};
+  const status = event.status ?? nested.status ?? nested.status_code
+    ?? event.codex_error_info?.http_status ?? nested.codex_error_info?.http_status;
+  const directMessage = typeof event.message === 'string'
+    ? event.message
+    : typeof nested.message === 'string' ? nested.message : '';
+  const details = transportError?.event === event ? transportError : null;
+  const message = details?.message || directMessage || details?.reason || 'unknown transport failure';
+  const resolvedStatus = details?.status ?? status ?? 'unknown';
+  return `${event.type}\nStatus: ${resolvedStatus}\nMessage: ${inline(message)}`;
+}
+
+function renderEvent(event, transportError) {
+  switch (event.type) {
+    case 'thread.started':
+    case 'turn.started':
+    case 'item.started':
+      return serviceSection(event);
+    case 'item.completed':
+      return itemSection(event.item);
+    case 'turn.completed':
+      return usageSection(event.usage);
+    case 'error':
+    case 'turn.failed':
+      return transportSection(event, transportError);
+    default:
+      // Unknown events stay visible in full: a future CLI event must never disappear silently.
+      return `${String(event.type || 'unknown event')}: ${compactJson(event, Infinity)}`;
+  }
+}
+
+export function read({ run, cwd = process.cwd(), runsRootPath = runsRoot() } = {}) {
+  const lookup = resolveRunFolder({ command: 'read', run, cwd, runsRootPath });
+  if (lookup.error) return result(1, lookup.error);
+
+  const eventData = readEvents(lookup.runDir);
+  // Two different failures, told apart because they send the operator to different places: a
+  // run from before the event stream existed has no file, while a run killed before the CLI
+  // spoke has an empty one. Reporting both as "predates this change" would hide the second.
+  if (!eventData.hasStream) {
+    return result(1, `Run ${lookup.runDir} has no events.jsonl; it predates the event stream.`);
+  }
+  if (!eventData.hasEvents) {
+    return result(
+      1,
+      `Run ${lookup.runDir} has an empty events.jsonl: Codex wrote no event before the run ended.`,
+    );
+  }
+  return result(0, eventData.events.map((event) => renderEvent(event, eventData.transport_error)).join('\n\n'));
+}

package/cli/run-lookup.mjs

@@ -0,0 +1,59 @@
+/** Resolves a run argument and confirms that it names an existing run directory. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { git } from '../src/runner/git-state.mjs';
+import { resolveProjectRunsDir } from '../src/runner/project-dir.mjs';
+import { runsRoot } from '../src/runner/runs-root.mjs';
+
+function projectRoot(cwd) {
+  const result = git(cwd, ['rev-parse', '--show-toplevel']);
+  return result.status === 0 && result.stdout.trim() ? result.stdout.trim() : cwd;
+}
+
+function refusal(command, message) {
+  return { runDir: null, error: `codex-bridge ${command}: ${message}` };
+}
+
+/**
+ * Resolves the same bare-name lookup for every run command. Keeping the existence check here
+ * prevents a read command from reading a path that stop would reject, and the command parameter keeps
+ * malformed-input advice from naming the command the operator did not invoke.
+ */
+export function resolveRunFolder({
+  command = 'stop',
+  run,
+  cwd = process.cwd(),
+  runsRootPath = runsRoot(),
+} = {}) {
+  const commandName = String(command || 'stop');
+  const value = String(run ?? '').trim();
+  if (!value || value === '.' || value === '..') {
+    return refusal(commandName, `${commandName} requires a run folder (full path or bare folder name)`);
+  }
+
+  let runDir;
+  try {
+    if (path.isAbsolute(value)) runDir = path.resolve(value);
+    else {
+      if (path.dirname(value) !== '.') {
+        return refusal(commandName, 'a bare run folder name or a full path is required');
+      }
+      const projectRuns = resolveProjectRunsDir(runsRootPath, projectRoot(cwd), { create: false });
+      runDir = path.join(projectRuns.dir, value);
+    }
+  } catch (err) {
+    return refusal(commandName, err.message);
+  }
+
+  let isDirectory = false;
+  try {
+    isDirectory = fs.statSync(runDir).isDirectory();
+  } catch {}
+  if (!isDirectory) {
+    return {
+      runDir: null,
+      error: `Run folder not found: ${runDir}. Pass a full path or a bare run folder name from the current project's runs directory.`,
+    };
+  }
+  return { runDir, error: null };
+}