@nomos-arc/arc 0.1.0

package/src/adapters/pty.ts

@@ -0,0 +1,159 @@
+import * as pty from 'node-pty';
+import type { Logger } from 'winston';
+import { NomosError } from '../core/errors.js';
+import { stripAnsi } from '../utils/ansi.js';
+import type { PtySpawnOptions, ExecutionResult } from '../types/index.js';
+
+export class PtyAdapter {
+  constructor(private readonly logger: Logger) {}
+
+  async execute(options: PtySpawnOptions): Promise<ExecutionResult> {
+    // C5 fix: TTY pre-check for supervised mode
+    if (options.mode === 'supervised' && !process.stdin.isTTY) {
+      throw new NomosError(
+        'no_tty',
+        'Supervised mode requires an interactive terminal. ' +
+          'Use --mode=auto for non-interactive environments (CI, vitest).',
+      );
+    }
+
+    const startTime = Date.now();
+    const outputBuffer: string[] = [];
+    let bytesBuffered = 0;
+    let bytesDropped = 0;
+    let killed = false;
+    let killReason: ExecutionResult['killReason'];
+
+    // Phase 1a: Tee Stream — no pattern matching, no response_map.
+    // PTY output is piped directly to developer terminal and captured for logging.
+
+    // C1 fix: cmd and args always separate — never shell-interpolated
+    // RT2-3.1 fix: Process Group Killing — use detached process group so we can
+    // kill the entire process tree (including grandchildren like bash, editors).
+    const proc = pty.spawn(options.cmd, options.args, {
+      name: 'xterm-256color',
+      cols: 120,
+      rows: 40,
+      cwd: options.cwd,
+      env: options.env,
+    });
+
+    // RT2-3.1 fix: Helper to kill the entire process group.
+    // Using -proc.pid sends SIGTERM to the process GROUP (negative PID),
+    // which terminates all children spawned by the PTY subprocess.
+    const killProcessGroup = () => {
+      try {
+        process.kill(-proc.pid, 'SIGTERM');
+      } catch {
+        // Process group may already be dead — fall back to direct kill
+        try { proc.kill(); } catch {}
+      }
+    };
+
+    // RT2-3.1 fix: stdin cleanup extracted into a helper so it runs on ALL exit paths
+    // (normal exit, timeout kill, AND unexpected throw). This resolves the stdin
+    // listener leak audit finding — previously, an error between listener registration
+    // and onExit would leave the listener attached, causing erratic terminal behavior.
+    let stdinListener: ((data: Buffer) => void) | null = null;
+    const cleanupStdin = () => {
+      try { if (process.stdin.isTTY) process.stdin.setRawMode(false); } catch {}
+      process.stdin.pause();
+      if (stdinListener) {
+        process.stdin.removeListener('data', stdinListener);
+        stdinListener = null;
+      }
+    };
+
+    return new Promise<ExecutionResult>((resolve, reject) => {
+      let heartbeatTimer: ReturnType<typeof setTimeout>;
+      let totalTimer: ReturnType<typeof setTimeout>;
+
+      // RT2-3.1 fix: try/catch wrapper around entire Promise body.
+      // On unexpected throw: kill process group, restore stdin, reject promise.
+      try {
+        const resetHeartbeat = () => {
+          clearTimeout(heartbeatTimer);
+          heartbeatTimer = setTimeout(() => {
+            this.logger.warn(
+              `Heartbeat timeout (${options.heartbeat_timeout_ms}ms). Killing process group.`,
+            );
+            killProcessGroup();
+            killed = true;
+            killReason = 'heartbeat_timeout';
+          }, options.heartbeat_timeout_ms);
+        };
+
+        totalTimer = setTimeout(() => {
+          this.logger.warn(
+            `Total timeout (${options.total_timeout_ms}ms). Killing process group.`,
+          );
+          killProcessGroup();
+          killed = true;
+          killReason = 'total_timeout';
+        }, options.total_timeout_ms);
+
+        resetHeartbeat();
+
+        proc.onData((data: string) => {
+          // Forward to developer in real-time (supervised and auto modes both show output)
+          process.stdout.write(data);
+
+          // Buffer for log capture
+          const bytes = Buffer.byteLength(data, 'utf8');
+          if (bytesBuffered < options.max_output_bytes) {
+            if (bytesBuffered + bytes > options.max_output_bytes) {
+              // E3 fix: warn on overflow, track dropped bytes
+              const remaining = options.max_output_bytes - bytesBuffered;
+              outputBuffer.push(data.slice(0, remaining));
+              bytesDropped += bytes - remaining;
+              bytesBuffered = options.max_output_bytes;
+              this.logger.warn(
+                `Output exceeded ${options.max_output_bytes} byte limit. ` +
+                  `Further output will not be captured. Consider increasing max_output_bytes in config.`,
+              );
+            } else {
+              outputBuffer.push(data);
+              bytesBuffered += bytes;
+            }
+          } else {
+            bytesDropped += bytes;
+          }
+
+          resetHeartbeat();
+        });
+
+        // Bidirectional piping for supervised mode
+        if (process.stdin.isTTY) {
+          process.stdin.setRawMode(true);
+        }
+        process.stdin.resume();
+        stdinListener = (data: Buffer) => { proc.write(data.toString()); };
+        process.stdin.on('data', stdinListener);
+
+        proc.onExit(({ exitCode }) => {
+          clearTimeout(heartbeatTimer);
+          clearTimeout(totalTimer);
+          cleanupStdin();
+
+          const rawOutput = outputBuffer.join('');
+          resolve({
+            exitCode: exitCode ?? 1,
+            rawOutput,
+            strippedOutput: stripAnsi(rawOutput),
+            duration_ms: Date.now() - startTime,
+            killed,
+            killReason,
+          });
+        });
+
+      } catch (err) {
+        // RT2-3.1 fix: unexpected throw — kill process group, clean up stdin, reject
+        clearTimeout(heartbeatTimer!);
+        clearTimeout(totalTimer!);
+        killProcessGroup();
+        cleanupStdin();
+        reject(err);
+      }
+    });
+  }
+}

package/src/adapters/stdio.ts

@@ -0,0 +1,113 @@
+import { spawn, type ChildProcess } from 'child_process';
+import type { Logger } from 'winston';
+import { stripAnsi } from '../utils/ansi.js';
+import { NomosError } from '../core/errors.js';
+import type { StdioSpawnOptions, ExecutionResult } from '../types/index.js';
+
+export class StdioAdapter {
+  constructor(private readonly logger: Logger) {}
+
+  async execute(options: StdioSpawnOptions): Promise<ExecutionResult> {
+    const startTime = Date.now();
+    let killed = false;
+    let killReason: ExecutionResult['killReason'];
+
+    // C1 fix: shell is NEVER set to true — args passed directly, never interpolated
+    const proc = spawn(options.cmd, options.args, {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: false,
+    });
+
+    return new Promise<ExecutionResult>((resolve, reject) => {
+      const stdoutChunks: Buffer[] = [];
+      const stderrChunks: Buffer[] = [];
+      let bytesBuffered = 0;
+
+      const killProcess = (p: ChildProcess) => {
+        // W4 fix: platform-aware kill
+        if (process.platform === 'win32') {
+          spawn('taskkill', ['/pid', String(p.pid), '/f', '/t'], { shell: false });
+        } else {
+          p.kill('SIGTERM');
+          setTimeout(() => { if (!p.killed) p.kill('SIGKILL'); }, 3000);
+        }
+      };
+
+      let heartbeatTimer: ReturnType<typeof setTimeout>;
+      let totalTimer: ReturnType<typeof setTimeout>;
+
+      const resetHeartbeat = () => {
+        clearTimeout(heartbeatTimer);
+        heartbeatTimer = setTimeout(() => {
+          killed = true;
+          killReason = 'heartbeat_timeout';
+          killProcess(proc);
+        }, options.heartbeat_timeout_ms);
+      };
+
+      totalTimer = setTimeout(() => {
+        killed = true;
+        killReason = 'total_timeout';
+        killProcess(proc);
+      }, options.total_timeout_ms);
+
+      resetHeartbeat();
+
+      proc.stdout!.on('data', (chunk: Buffer) => {
+        resetHeartbeat();
+        if (bytesBuffered < options.max_output_bytes) {
+          stdoutChunks.push(chunk);
+          bytesBuffered += chunk.length;
+        }
+      });
+
+      proc.stderr!.on('data', (chunk: Buffer) => { stderrChunks.push(chunk); });
+
+      // M-5 fix: Handle stdin errors (broken pipe) and backpressure (large prompts)
+      proc.stdin!.on('error', (err) => {
+        reject(new NomosError(
+          'review_failed',
+          `Failed to write to reviewer stdin: ${err.message}`,
+        ));
+      });
+
+      const ok = proc.stdin!.write(options.stdinData);
+      if (!ok) {
+        // Backpressure: large review prompts (200KB+ diff + rules) can exceed the stdin
+        // buffer. Without drain handling, data is silently truncated.
+        proc.stdin!.once('drain', () => { proc.stdin!.end(); });
+      } else {
+        proc.stdin!.end();
+      }
+
+      proc.on('close', (exitCode) => {
+        clearTimeout(heartbeatTimer);
+        clearTimeout(totalTimer);
+
+        const rawOutput = Buffer.concat(stdoutChunks).toString('utf8');
+        const stderrOutput = Buffer.concat(stderrChunks).toString('utf8');
+
+        if (stderrOutput && (exitCode ?? 0) > 0) {
+          this.logger.error(`Reviewer stderr: ${stderrOutput.trim()}`);
+        }
+
+        resolve({
+          exitCode: exitCode ?? 1,
+          rawOutput,
+          strippedOutput: stripAnsi(rawOutput),
+          duration_ms: Date.now() - startTime,
+          killed,
+          killReason,
+        });
+      });
+
+      proc.on('error', (err) => {
+        clearTimeout(heartbeatTimer);
+        clearTimeout(totalTimer);
+        reject(new NomosError('review_failed', `Reviewer process error: ${err.message}`));
+      });
+    });
+  }
+}

package/src/cli.ts

@@ -0,0 +1,83 @@
+import { Command } from 'commander';
+import { createRequire } from 'module';
+import { NomosError } from './core/errors.js';
+import { registerInitCommand } from './commands/init.js';
+import { registerPlanCommand } from './commands/plan.js';
+import { registerReviewCommand } from './commands/review.js';
+import { registerRunCommand } from './commands/run.js';
+import { registerStatusCommand } from './commands/status.js';
+import { registerApplyCommand } from './commands/apply.js';
+import { registerDiscardCommand } from './commands/discard.js';
+import { registerListCommand } from './commands/list.js';
+import { registerCertificateCommand } from './commands/certificate.js';
+import { registerMapCommand } from './commands/map.js';
+import { registerShowCommand } from './commands/show.js';
+import { registerIndexCommand } from './commands/index.js';
+import { registerSearchCommand } from './commands/search.js';
+import { registerAuthCommand } from './commands/auth.js';
+import { registerDriftCommand } from './commands/drift.js';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+
+const program = new Command();
+program.name('arc').description('The Architect — AI Orchestrator CLI').version(pkg.version);
+
+// RTV-5 fix: SIGINT handler uses process.exitCode (not process.exit) to avoid racing
+// with the orchestrator's state-transition catch block.
+//
+// Flow on Ctrl+C:
+//   1. SIGINT fires → stdin restored, process.exitCode = 130
+//   2. Child process receives SIGINT → PTY onExit fires → ptyAdapter.execute() resolves
+//   3. Orchestrator's catch block runs: await stateManager.transition(taskId, 'stalled', ...)
+//   4. State written successfully (no race — process.exit() was NOT called yet)
+//   5. catch block re-throws error → main() catches it
+//   6. main() sees process.exitCode === 130 → calls process.exit(130)
+//
+// This is a non-destructive exit: state is persisted, task is recoverable via arc plan.
+process.on('SIGINT', () => {
+  process.exitCode = 130;  // mark the intended exit code
+  try {
+    if (process.stdin.isTTY) process.stdin.setRawMode(false);
+  } catch {}
+  process.stdin.pause();
+  // Do NOT call process.exit() here. Let the orchestrator's catch block complete first.
+});
+
+[
+  registerInitCommand,
+  registerPlanCommand,
+  registerReviewCommand,
+  registerRunCommand,
+  registerStatusCommand,
+  registerApplyCommand,
+  registerDiscardCommand,
+  registerListCommand,
+  registerCertificateCommand,
+  registerMapCommand,
+  registerShowCommand,
+  registerIndexCommand,
+  registerSearchCommand,
+  registerAuthCommand,
+  registerDriftCommand,
+].forEach(fn => fn(program));
+
+async function main() {
+  try {
+    await program.parseAsync();
+  } catch (err) {
+    // RTV-5: If SIGINT was received, honour the 130 exit code
+    if (process.exitCode === 130) {
+      console.error('\n[nomos:warn] Interrupted. Task state preserved (stalled).');
+      process.exit(130);
+    }
+    if (err instanceof NomosError) {
+      console.error(`[nomos:error] ${err.message}`);
+      process.exit(1);
+    }
+    console.error(`[nomos:error] Unexpected error: ${err}`);
+    process.exit(1);
+  }
+}
+
+main();

package/src/commands/apply.ts

@@ -0,0 +1,47 @@
+import type { Command } from 'commander';
+import { createOrchestrator } from '../core/factory.js';
+import { NomosError } from '../core/errors.js';
+
+export function registerApplyCommand(program: Command): void {
+  program
+    .command('apply <task>')
+    .description('Merge approved task shadow branch into main and clean up')
+    .action(async (task: string) => {
+      try {
+        const { orchestrator } = await createOrchestrator();
+
+        // orchestrator.apply() returns void and never throws on merge conflict —
+        // it transitions the task to 'merge_conflict' status and returns cleanly.
+        // We re-read state to detect the outcome.
+        await orchestrator.apply(task);
+        const finalState = await orchestrator.status(task);
+
+        if (finalState.meta.status === 'merge_conflict') {
+          // RTV-15 fix: exit code 3 for merge conflict — recoverable, not an error.
+          // Conflict details were logged by the orchestrator.
+          console.error(
+            `[nomos:conflict] Merge conflict detected in task '${task}'.\n` +
+            `  Resolve conflicts in your working tree, then run: arc apply ${task}`
+          );
+          process.exit(3);
+        }
+
+        console.log(`Task '${task}' merged to main. Shadow branch cleaned up.`);
+        process.exit(0);
+      } catch (err) {
+        if (err instanceof NomosError) {
+          if (err.code === 'invalid_transition') {
+            console.error(
+              `[nomos:error] ${err.message}\n` +
+              `  Check current status with: arc status ${task}`
+            );
+          } else {
+            console.error(`[nomos:error] ${err.message}`);
+          }
+        } else {
+          console.error(`[nomos:error] Unexpected error: ${err}`);
+        }
+        process.exit(1);
+      }
+    });
+}