@nomos-arc/arc 0.1.0

package/test/e2e/lifecycle.test.ts

@@ -0,0 +1,330 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { describe, it, beforeEach, afterEach, expect, vi } from 'vitest';
+import simpleGit from 'simple-git';
+import { createOrchestrator } from '../../src/core/factory.js';
+import { NomosError } from '../../src/core/errors.js';
+import type { Orchestrator } from '../../src/core/orchestrator.js';
+
+// E5 fix: use path.resolve(import.meta.url pathname, ...) to get fixture paths.
+// fixturesDir is in the REPO, not in tempDir. These are separate locations.
+const fixturesDir = path.resolve(new URL(import.meta.url).pathname, '../../fixtures');
+
+// Use the local tsx binary via absolute path so subprocesses spawned in the worktree CWD
+// (which has no node_modules) do not trigger an npx download prompt.
+const projectRoot = path.resolve(new URL(import.meta.url).pathname, '../../..');
+const tsxBin = path.join(projectRoot, 'node_modules', '.bin', 'tsx');
+
+// Counter file path must match the one used in mock-reviewer-retry.ts
+const counterFile = path.join(os.tmpdir(), 'nomos-mock-reviewer-retry-count.txt');
+
+vi.setConfig({ testTimeout: 60000 });
+
+let tempDir: string;
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Initialise a project in dir, overwrite config, and return a ready orchestrator.
+ * Avoids process.chdir() — passes projectRoot explicitly (E5 fix).
+ *
+ * Also commits all scaffold files to main and extends .gitignore so that
+ * state/log files don't appear as untracked. This is required for apply()
+ * to pass the dirty-tree check (simple-git's isClean() includes untracked files).
+ */
+async function setupProject(dir: string, config: object): Promise<Orchestrator> {
+  const { orchestrator: initOrch } = await createOrchestrator({ skipConfig: true, projectRoot: dir });
+  await initOrch.initProject();
+
+  // Overwrite default config with test-specific mock config
+  fs.writeFileSync(path.join(dir, '.nomos-config.json'), JSON.stringify(config, null, 2));
+
+  // Extend .gitignore so state/lock/log files created at runtime don't show as untracked
+  const gitignorePath = path.join(dir, '.gitignore');
+  const existing = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf8') : '';
+  const extra = ['tasks-management/state/', 'tasks-management/state/*.lock']
+    .filter(e => !existing.includes(e))
+    .join('\n');
+  if (extra) fs.appendFileSync(gitignorePath, '\n' + extra + '\n');
+
+  // Commit all scaffold files so main's working tree is clean for apply()
+  const git = simpleGit(dir);
+  await git.add('.');
+  await git.commit('arc init: scaffold project');
+
+  const { orchestrator } = await createOrchestrator({ projectRoot: dir });
+  return orchestrator;
+}
+
+function makePlannerBinary(fixtureName: string, overrides: Record<string, unknown> = {}) {
+  return {
+    cmd: tsxBin,
+    args: [path.join(fixturesDir, fixtureName)],
+    pty: true,
+    total_timeout_ms: 30000,
+    heartbeat_timeout_ms: 20000,
+    max_output_bytes: 1048576,
+    usage_pattern: 'Tokens used:\\s*(\\d+)',
+    ...overrides,
+  };
+}
+
+function makeReviewerBinary(fixtureName: string) {
+  return {
+    cmd: tsxBin,
+    args: [path.join(fixturesDir, fixtureName)],
+    pty: false,
+    total_timeout_ms: 30000,
+    heartbeat_timeout_ms: 20000,
+    max_output_bytes: 524288,
+    usage_pattern: null,
+  };
+}
+
+// ── Lifecycle ─────────────────────────────────────────────────────────────────
+
+beforeEach(async () => {
+  // Clean retry counter so mock-reviewer-retry starts fresh in every test
+  try { fs.unlinkSync(counterFile); } catch {}
+
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nomos-e2e-'));
+
+  // E5 fix: NEVER use process.chdir() — pass projectRoot explicitly everywhere.
+  const git = simpleGit(tempDir);
+  await git.init();
+  await git.addConfig('user.email', 'test@test.com');
+  await git.addConfig('user.name', 'Test');
+  fs.writeFileSync(path.join(tempDir, 'README.md'), '# Test Project');
+  fs.mkdirSync(path.join(tempDir, 'src'));
+  await git.add('.');
+  await git.commit('initial commit');
+  // Ensure branch is always 'main' — mergeToMain checks for this branch by name
+  await git.raw(['branch', '-M', 'main']);
+});
+
+afterEach(() => {
+  try { fs.unlinkSync(counterFile); } catch {}
+  fs.rmSync(tempDir, { recursive: true, force: true });
+});
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe('E2E: Full Lifecycle', () => {
+
+  // Test 1 — Happy path: init → plan → review → apply
+  it('runs the full init → plan → review → apply lifecycle', async () => {
+    const orchestrator = await setupProject(tempDir, {
+      binaries: {
+        planner: makePlannerBinary('mock-planner.ts'),
+        reviewer: makeReviewerBinary('mock-reviewer.ts'),
+      },
+    });
+    const git = simpleGit(tempDir);
+
+    // Verify initProject created required artifacts
+    expect(fs.existsSync(path.join(tempDir, 'tasks-management/rules/global.md'))).toBe(true);
+    expect(fs.existsSync(path.join(tempDir, '.nomos-config.json'))).toBe(true);
+
+    // Init task
+    await orchestrator.initTask('my-task');
+    expect(fs.existsSync(path.join(tempDir, 'tasks-management/tasks/my-task.md'))).toBe(true);
+    expect(fs.existsSync(path.join(tempDir, 'tasks-management/state/my-task.json'))).toBe(true);
+    // Commit task file to main so working tree is clean for apply().
+    // The shadow branch also has this file (same content) → clean merge.
+    await git.add('tasks-management/tasks/my-task.md');
+    await git.commit('test: commit task definition to main');
+
+    // Plan
+    await orchestrator.plan('my-task', 'auto');
+    const stateAfterPlan = await orchestrator.status('my-task');
+    expect(stateAfterPlan.meta.status).toBe('pending_review');
+    expect(stateAfterPlan.history).toHaveLength(1);
+    expect(stateAfterPlan.history[0].tokens_source).toBe('metered');  // RTV-4
+    // Commit plan diff to main so working tree is clean for apply().
+    // The shadow branch also has this file (same content) → clean merge.
+    await git.add('tasks-management/plans/my-task-v1.diff');
+    await git.commit('test: commit plan diff to main');
+
+    // Review
+    await orchestrator.review('my-task', 'auto');
+    const stateAfterReview = await orchestrator.status('my-task');
+    expect(stateAfterReview.meta.status).toBe('approved');
+    expect(stateAfterReview.meta.approval_reason).toBe('score_threshold');  // RTV-6
+    expect(stateAfterReview.history[stateAfterReview.history.length - 1]?.review?.score).toBe(0.92);
+
+    // Apply — working tree is clean; shadow branch merges cleanly into main
+    await orchestrator.apply('my-task');
+    const finalState = await orchestrator.status('my-task');
+    expect(finalState.meta.status).toBe('merged');
+  });
+
+  // Test 2 — Subprocess timeout → stalled or failed
+  it('transitions to stalled when planner heartbeat times out', async () => {
+    const orchestrator = await setupProject(tempDir, {
+      binaries: {
+        planner: makePlannerBinary('mock-planner-hang.ts', { heartbeat_timeout_ms: 2000 }),
+        reviewer: makeReviewerBinary('mock-reviewer.ts'),
+      },
+    });
+
+    await orchestrator.initTask('hang-task');
+    await orchestrator.plan('hang-task', 'auto');  // returns (does not throw) per M-7 pattern
+
+    const state = await orchestrator.status('hang-task');
+    expect(['stalled', 'failed']).toContain(state.meta.status);
+  });
+
+  // Test 3 — Budget guard: second plan throws budget_exceeded
+  it('rejects second plan when token budget is exhausted', async () => {
+    // score_threshold: 0.99 forces refinement (mock-reviewer returns 0.92 < 0.99)
+    // max_tokens_per_task: 1000 is exceeded by mock-planner's 5000 metered tokens
+    const orchestrator = await setupProject(tempDir, {
+      binaries: {
+        planner: makePlannerBinary('mock-planner.ts'),
+        reviewer: makeReviewerBinary('mock-reviewer.ts'),
+      },
+      convergence: { score_threshold: 0.99, max_iterations: 3 },
+      budget: { max_tokens_per_task: 1000 },
+    });
+
+    await orchestrator.initTask('budget-task');
+
+    // First plan succeeds and records 5000 metered tokens
+    await orchestrator.plan('budget-task', 'auto');
+    const afterPlan = await orchestrator.status('budget-task');
+    expect(afterPlan.meta.status).toBe('pending_review');
+
+    // Review → 0.92 < 0.99 threshold and version 1 < max_iterations 3 → refinement
+    await orchestrator.review('budget-task', 'auto');
+    const afterReview = await orchestrator.status('budget-task');
+    expect(afterReview.meta.status).toBe('refinement');
+
+    // Second plan → budget check fires (5000+ tokens used >= 1000 limit)
+    const planError = await orchestrator.plan('budget-task', 'auto').catch(e => e);
+    expect(planError).toBeInstanceOf(NomosError);
+    expect((planError as NomosError).code).toBe('budget_exceeded');
+
+    const finalState = await orchestrator.status('budget-task');
+    expect(finalState.meta.status).toBe('failed');
+  });
+
+  // Test 4 — Discard lifecycle
+  it('discard removes worktree, branch, and sets state to discarded', async () => {
+    const orchestrator = await setupProject(tempDir, {
+      binaries: {
+        planner: makePlannerBinary('mock-planner.ts'),
+        reviewer: makeReviewerBinary('mock-reviewer.ts'),
+      },
+    });
+
+    await orchestrator.initTask('task2');
+    await orchestrator.discard('task2');
+
+    const state = await orchestrator.status('task2');
+    expect(state.meta.status).toBe('discarded');
+  });
+
+  // Test 5 — Apply guard: cannot apply a task that is not approved
+  it('throws invalid_transition when applying a non-approved task', async () => {
+    const orchestrator = await setupProject(tempDir, {
+      binaries: {
+        planner: makePlannerBinary('mock-planner.ts'),
+        reviewer: makeReviewerBinary('mock-reviewer.ts'),
+      },
+    });
+
+    await orchestrator.initTask('task3');
+    // task3 is in 'init' status — apply should throw
+    const err = await orchestrator.apply('task3').catch(e => e);
+    expect(err).toBeInstanceOf(NomosError);
+    expect((err as NomosError).code).toBe('invalid_transition');
+    expect((err as NomosError).message).toMatch(/init/);
+  });
+
+  // Test 6 — Supervised mode TTY guard (BLK-1)
+  it('throws no_tty when supervised mode is used without a TTY', async () => {
+    const orchestrator = await setupProject(tempDir, {
+      binaries: {
+        planner: makePlannerBinary('mock-planner.ts'),
+        reviewer: makeReviewerBinary('mock-reviewer.ts'),
+      },
+    });
+
+    await orchestrator.initTask('task-tty');
+    // vitest runs without a TTY → PtyAdapter.execute throws no_tty for supervised mode
+    const err = await orchestrator.plan('task-tty', 'supervised').catch(e => e);
+    expect(err).toBeInstanceOf(NomosError);
+    expect((err as NomosError).code).toBe('no_tty');
+  });
+
+  // Test 7 — Review retry on bad JSON → failed
+  it('transitions to failed when reviewer always returns invalid JSON', async () => {
+    const orchestrator = await setupProject(tempDir, {
+      binaries: {
+        planner: makePlannerBinary('mock-planner.ts'),
+        reviewer: makeReviewerBinary('mock-reviewer-bad.ts'),
+      },
+    });
+
+    await orchestrator.initTask('bad-review-task');
+    await orchestrator.plan('bad-review-task', 'auto');
+
+    // review() returns state, never throws (M-7 fix)
+    await orchestrator.review('bad-review-task', 'auto');
+
+    const state = await orchestrator.status('bad-review-task');
+    expect(state.meta.status).toBe('failed');
+
+    // Raw review log must exist even on parse failure
+    const version = state.current_version;
+    const rawLogPath = path.join(
+      tempDir, 'tasks-management', 'logs',
+      `bad-review-task-v${version}-review-raw.log`,
+    );
+    expect(fs.existsSync(rawLogPath)).toBe(true);
+  });
+
+  // Test 8 — Review retry succeeds on second attempt (via temp-file counter)
+  it('succeeds on retry when reviewer returns valid JSON on second attempt', async () => {
+    // beforeEach already deleted counterFile — clean slate guaranteed
+    const orchestrator = await setupProject(tempDir, {
+      binaries: {
+        planner: makePlannerBinary('mock-planner.ts'),
+        reviewer: makeReviewerBinary('mock-reviewer-retry.ts'),
+      },
+    });
+
+    await orchestrator.initTask('retry-task');
+    await orchestrator.plan('retry-task', 'auto');
+    await orchestrator.review('retry-task', 'auto');
+
+    const state = await orchestrator.status('retry-task');
+    // mock-reviewer-retry returns score: 0.85 on retry
+    // 0.85 < default threshold 0.9 and version 1 < max_iterations 3 → refinement
+    // (approved would also be valid if threshold were lower — spec allows both)
+    expect(['approved', 'refinement']).toContain(state.meta.status);
+  });
+
+  // Test 9 — approval_reason is max_iterations_reached when iterations exhausted (RTV-6)
+  it('sets approval_reason to max_iterations_reached when max iterations hit', async () => {
+    // max_iterations: 1 — after one plan cycle (version becomes 1), review fires
+    // max_iterations_reached because current_version (1) >= maxVersion (1)
+    const orchestrator = await setupProject(tempDir, {
+      binaries: {
+        planner: makePlannerBinary('mock-planner.ts'),
+        reviewer: makeReviewerBinary('mock-reviewer.ts'),
+      },
+      convergence: { score_threshold: 0.99, max_iterations: 1 },
+    });
+
+    await orchestrator.initTask('iter-task');
+    await orchestrator.plan('iter-task', 'auto');
+    await orchestrator.review('iter-task', 'auto');
+
+    const state = await orchestrator.status('iter-task');
+    expect(state.meta.status).toBe('approved');
+    expect(state.meta.approval_reason).toBe('max_iterations_reached');
+  });
+
+});

package/test/fixtures/mock-planner-hang.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// Writes initial output then hangs — used to test heartbeat/total timeout
+process.stdout.write('Starting plan...\n');
+// Never exits — timeout test relies on this hanging indefinitely
+setInterval(() => {}, 60000);

package/test/fixtures/mock-planner.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// Simulates: claude -p "<prompt>" running inside a worktree
+// Reads prompt from -p arg, creates a file, commits it, prints token usage.
+import simpleGit from 'simple-git';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const pIdx = process.argv.indexOf('-p');
+const prompt = pIdx !== -1 ? process.argv[pIdx + 1] : '';
+
+// Write ANSI-colored output (to test ANSI stripping in PtyAdapter)
+process.stdout.write('\x1b[32m✓\x1b[0m Generating plan...\n');
+process.stdout.write(`Received prompt (${prompt.length} chars)\n`);
+
+// Create a file in the current working directory (the worktree)
+const outputFile = path.join(process.cwd(), 'src', 'mock-output.ts');
+fs.mkdirSync(path.dirname(outputFile), { recursive: true });
+fs.writeFileSync(outputFile, `// mock implementation\nexport const result = 'plan';\n`);
+
+// L-5 fix: commit using simple-git, not shell git commands
+const git = simpleGit(process.cwd());
+await git.add('.');
+await git.commit('mock planner: add implementation');
+
+process.stdout.write('Tokens used: 5000\n');
+process.exit(0);

package/test/fixtures/mock-reviewer-bad.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Always returns invalid JSON — used to test review retry and failure handling
+let input = '';
+process.stdin.on('data', (chunk: Buffer) => { input += chunk.toString(); });
+process.stdin.on('end', () => {
+  process.stdout.write('I cannot review this because reasons');
+  process.exit(0);
+});

package/test/fixtures/mock-reviewer-retry.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// First call: returns invalid JSON. Second call (retry): returns valid JSON.
+// Uses a temp file as an invocation counter — since each retry is a NEW subprocess,
+// in-process state cannot be used. The temp file path is derived from the process CWD.
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+const counterFile = path.join(os.tmpdir(), 'nomos-mock-reviewer-retry-count.txt');
+
+let input = '';
+process.stdin.on('data', (chunk: Buffer) => { input += chunk.toString(); });
+process.stdin.on('end', () => {
+  // Read and increment call counter
+  let count = 0;
+  try { count = parseInt(fs.readFileSync(counterFile, 'utf8'), 10); } catch {}
+  count++;
+  fs.writeFileSync(counterFile, String(count));
+
+  if (count === 1) {
+    // First invocation: return bad JSON
+    process.stdout.write('I cannot review this because reasons');
+  } else {
+    // Second invocation (retry): clean up counter and return valid JSON
+    try { fs.unlinkSync(counterFile); } catch {}
+    const review = {
+      score: 0.85,
+      summary: "Plan looks good after retry. Implementation steps are clear.",
+      issues: []
+    };
+    process.stdout.write(JSON.stringify(review));
+  }
+  process.exit(0);
+});

package/test/fixtures/mock-reviewer.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// Simulates: codex -q --full-auto receiving review prompt via stdin
+let input = '';
+process.stdin.on('data', (chunk: Buffer) => { input += chunk.toString(); });
+process.stdin.on('end', () => {
+  const review = {
+    score: 0.92,
+    summary: "Plan is well-structured with clear implementation steps and good error handling.",
+    issues: [{
+      severity: "low",
+      category: "maintainability",
+      description: "Consider adding more inline documentation.",
+      suggestion: "Add JSDoc comments to exported functions."
+    }]
+  };
+  process.stdout.write(JSON.stringify(review));
+  process.exit(0);
+});

package/test/fixtures/sample-project/src/circular-a.ts

@@ -0,0 +1,6 @@
+// Circular dependency test: circular-a ↔ circular-b
+import { fromB } from './circular-b';
+
+export function fromA(): string {
+  return `A(${fromB()})`;
+}

package/test/fixtures/sample-project/src/circular-b.ts

@@ -0,0 +1,6 @@
+// Circular dependency test: circular-b ↔ circular-a
+import { fromA } from './circular-a';
+
+export function fromB(): string {
+  return `B(${fromA()})`;
+}

package/test/fixtures/sample-project/src/config.ts

@@ -0,0 +1,15 @@
+// App configuration
+import type { Result } from './types';
+import { ok, fail } from './utils/index';
+
+export interface AppConfig {
+  port: number;
+  dbUrl: string;
+}
+
+export function loadAppConfig(): Result<AppConfig> {
+  const port = Number(process.env['PORT'] ?? '3000');
+  const dbUrl = process.env['DATABASE_URL'];
+  if (!dbUrl) return fail('DATABASE_URL is required');
+  return ok({ port, dbUrl });
+}

package/test/fixtures/sample-project/src/main.ts

@@ -0,0 +1,19 @@
+// Entry point — imports everything, no one imports this
+import { createUser, getUser } from './services/user-service';
+import { createProduct, getProduct } from './services/product-service';
+import { loadAppConfig } from './config';
+import { formatDate } from './utils/index';
+
+async function main() {
+  const cfg = loadAppConfig();
+  if (!cfg.ok) {
+    console.error(cfg.error);
+    process.exit(1);
+  }
+  console.log(`Starting on port ${cfg.value.port}, date: ${formatDate(new Date())}`);
+  const user = createUser({ id: '1', name: 'Alice', email: 'alice@example.com' });
+  const product = createProduct({ id: 'p1', name: 'Widget', price: 9.99 });
+  console.log(getUser('1'), getProduct('p1'), user, product);
+}
+
+main();

package/test/fixtures/sample-project/src/services/product-service.ts

@@ -0,0 +1,20 @@
+// Product service
+import type { Product, Result } from '../types';
+import { ok, fail } from '../utils/index';
+
+const store = new Map<string, Product>();
+
+export function createProduct(data: unknown): Result<Product> {
+  const obj = data as Record<string, unknown>;
+  if (typeof obj['id'] !== 'string') return fail('Missing id');
+  if (typeof obj['name'] !== 'string') return fail('Missing name');
+  if (typeof obj['price'] !== 'number') return fail('Missing price');
+  const product: Product = { id: obj['id'], name: obj['name'], price: obj['price'] };
+  store.set(product.id, product);
+  return ok(product);
+}
+
+export function getProduct(id: string): Result<Product> {
+  const product = store.get(id);
+  return product ? ok(product) : fail(`Product ${id} not found`);
+}

package/test/fixtures/sample-project/src/services/user-service.ts

@@ -0,0 +1,18 @@
+// User service
+import type { User, Result } from '../types';
+import { ok, fail } from '../utils/index';
+import { validateUser } from '../utils/validate';
+
+const store = new Map<string, User>();
+
+export function createUser(data: unknown): Result<User> {
+  const validated = validateUser(data);
+  if (!validated.ok) return fail(validated.error);
+  store.set(validated.value.id, validated.value);
+  return ok(validated.value);
+}
+
+export function getUser(id: string): Result<User> {
+  const user = store.get(id);
+  return user ? ok(user) : fail(`User ${id} not found`);
+}

package/test/fixtures/sample-project/src/types.ts

@@ -0,0 +1,14 @@
+// Core types used throughout the project
+export interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+export interface Product {
+  id: string;
+  name: string;
+  price: number;
+}
+
+export type Result<T> = { ok: true; value: T } | { ok: false; error: string };

package/test/fixtures/sample-project/src/utils/index.ts

@@ -0,0 +1,14 @@
+// Shared utilities
+import type { Result } from '../types';
+
+export function ok<T>(value: T): Result<T> {
+  return { ok: true, value };
+}
+
+export function fail<T>(error: string): Result<T> {
+  return { ok: false, error };
+}
+
+export function formatDate(date: Date): string {
+  return date.toISOString().split('T')[0]!;
+}

package/test/fixtures/sample-project/src/utils/validate.ts

@@ -0,0 +1,12 @@
+// Validation helpers
+import type { User, Result } from '../types';
+import { fail, ok } from './index';
+
+export function validateUser(u: unknown): Result<User> {
+  if (typeof u !== 'object' || u === null) return fail('Not an object');
+  const obj = u as Record<string, unknown>;
+  if (typeof obj['id'] !== 'string') return fail('Missing id');
+  if (typeof obj['name'] !== 'string') return fail('Missing name');
+  if (typeof obj['email'] !== 'string') return fail('Missing email');
+  return ok(obj as unknown as User);
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test"]
+}

package/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: [
+      'src/**/__tests__/**/*.test.ts',
+      'test/**/*.test.ts',
+    ],
+    testTimeout: 10000,
+    hookTimeout: 10000,
+  },
+});