@vexdo/cli 0.1.0

package/src/prompts/arbiter.ts

@@ -0,0 +1,21 @@
+export const ARBITER_SYSTEM_PROMPT = `You are a technical arbiter receiving: spec, diff, and reviewer comments.
+
+Rules:
+- Treat the spec as the single source of truth, not reviewer opinion.
+- Explicitly check each reviewer comment against the spec:
+  - If a comment correctly identifies a spec violation, include it in the decision.
+  - If a comment conflicts with the spec or invents requirements, flag it and escalate.
+  - If comments are ambiguous, escalate.
+- Never resolve architectural decisions autonomously; escalate instead.
+- When decision is fix, feedback_for_codex must be concrete and actionable: what to change, where, and how.
+
+Decision rules:
+- submit: no critical/important comments that reflect real spec violations.
+- fix: clear spec violations with actionable fixes; include feedback_for_codex.
+- escalate: any reviewer/spec conflict, architectural ambiguity, or if max-iteration-like uncertainty would require escalation.
+
+Output requirements:
+- Output ONLY valid JSON with schema:
+  { "decision", "reasoning", "feedback_for_codex", "summary" }
+- feedback_for_codex is required when decision="fix" and must be omitted otherwise.
+- Never output prose outside the JSON.`;

package/src/prompts/reviewer.ts

@@ -0,0 +1,20 @@
+export const REVIEWER_SYSTEM_PROMPT = `You are a strict code reviewer evaluating a git diff against a provided spec.
+
+Rules:
+- Treat the spec (acceptance criteria + architectural constraints) as the ONLY source of truth.
+- Never invent requirements that are not explicitly present in the spec.
+- Evaluate whether the diff violates the spec; distinguish real violations from stylistic preferences.
+- For each issue, provide exact file and line number when visible in the diff.
+- Severity definitions (strict):
+  - critical: breaks an acceptance criterion or architectural constraint.
+  - important: likely to cause bugs or maintenance issues directly related to the spec.
+  - minor: code quality issue not blocking the spec.
+  - noise: style/preference, spec-neutral.
+- If the diff fully satisfies the spec, return no comments.
+
+Output requirements:
+- Output ONLY valid JSON.
+- JSON schema:
+  { "comments": [ { "severity", "file", "line", "comment", "suggestion" } ] }
+- If no issues: { "comments": [] }
+- Never output prose outside the JSON.`;

package/src/types/index.ts

@@ -0,0 +1,96 @@
+export type CommentSeverity = 'critical' | 'important' | 'minor' | 'noise';
+
+export type ArbiterDecision = 'fix' | 'submit' | 'escalate';
+
+export type StepStatus = 'pending' | 'in_progress' | 'done' | 'failed' | 'escalated';
+
+export type TaskStatus = 'in_progress' | 'review' | 'done' | 'blocked' | 'escalated';
+
+export interface ServiceConfig {
+  name: string;
+  path: string;
+}
+
+export interface ReviewConfig {
+  model: string;
+  max_iterations: number;
+  auto_submit: boolean;
+}
+
+export interface CodexConfig {
+  model: string;
+}
+
+export interface VexdoConfig {
+  version: 1;
+  services: ServiceConfig[];
+  review: ReviewConfig;
+  codex: CodexConfig;
+}
+
+export interface TaskStep {
+  service: string;
+  spec: string;
+  depends_on?: string[];
+}
+
+export interface Task {
+  id: string;
+  title: string;
+  steps: TaskStep[];
+  depends_on?: string[];
+}
+
+export interface ReviewComment {
+  severity: CommentSeverity;
+  file?: string;
+  line?: number;
+  comment: string;
+  suggestion?: string;
+}
+
+export interface ReviewResult {
+  comments: ReviewComment[];
+}
+
+export interface ArbiterResult {
+  decision: ArbiterDecision;
+  reasoning: string;
+  feedback_for_codex?: string;
+  summary: string;
+}
+
+export interface StepState {
+  service: string;
+  status: StepStatus;
+  iteration: number;
+  branch?: string;
+  lastReviewComments?: ReviewComment[];
+  lastArbiterResult?: ArbiterResult;
+}
+
+export interface VexdoState {
+  taskId: string;
+  taskTitle: string;
+  taskPath: string;
+  status: TaskStatus;
+  steps: StepState[];
+  startedAt: string;
+  updatedAt: string;
+}
+
+export interface StartOptions {
+  dryRun?: boolean;
+  verbose?: boolean;
+  resume?: boolean;
+}
+
+export interface IterationLog {
+  taskId: string;
+  service: string;
+  iteration: number;
+  diff: string;
+  review: ReviewResult;
+  arbiter: ArbiterResult;
+  timestamp: string;
+}

package/test/config.test.ts

@@ -0,0 +1,124 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { findProjectRoot, loadConfig } from '../src/lib/config.js';
+
+const tempDirs: string[] = [];
+
+function makeTempDir(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'vexdo-config-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function writeConfig(dir: string, content: string): void {
+  fs.writeFileSync(path.join(dir, '.vexdo.yml'), content, 'utf8');
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe('findProjectRoot', () => {
+  it('finds a parent directory containing .vexdo.yml', () => {
+    const root = makeTempDir();
+    const nested = path.join(root, 'a', 'b', 'c');
+    fs.mkdirSync(nested, { recursive: true });
+    writeConfig(root, 'version: 1\nservices:\n  - name: api\n    path: ./api\n');
+
+    expect(findProjectRoot(nested)).toBe(root);
+  });
+
+  it('returns null when no config exists', () => {
+    const dir = makeTempDir();
+    expect(findProjectRoot(dir)).toBeNull();
+  });
+});
+
+describe('loadConfig', () => {
+  it('loads valid config', () => {
+    const root = makeTempDir();
+    writeConfig(
+      root,
+      `version: 1
+services:
+  - name: api
+    path: ./services/api
+review:
+  model: custom-review
+  max_iterations: 7
+  auto_submit: true
+codex:
+  model: custom-codex
+`,
+    );
+
+    const result = loadConfig(root);
+
+    expect(result).toEqual({
+      version: 1,
+      services: [{ name: 'api', path: './services/api' }],
+      review: { model: 'custom-review', max_iterations: 7, auto_submit: true },
+      codex: { model: 'custom-codex' },
+    });
+  });
+
+  it('applies defaults for review and codex', () => {
+    const root = makeTempDir();
+    writeConfig(
+      root,
+      `version: 1
+services:
+  - name: api
+    path: ./services/api
+`,
+    );
+
+    const result = loadConfig(root);
+
+    expect(result.review).toEqual({
+      model: 'claude-haiku-4-5-20251001',
+      max_iterations: 3,
+      auto_submit: false,
+    });
+    expect(result.codex).toEqual({ model: 'gpt-4o' });
+  });
+
+  it('throws when config file is missing', () => {
+    const root = makeTempDir();
+    expect(() => loadConfig(root)).toThrowError(/Configuration file not found/);
+  });
+
+  it('throws for wrong version', () => {
+    const root = makeTempDir();
+    writeConfig(root, 'version: 2\nservices:\n  - name: api\n    path: ./api\n');
+
+    expect(() => loadConfig(root)).toThrowError('version must be 1');
+  });
+
+  it('throws for empty services', () => {
+    const root = makeTempDir();
+    writeConfig(root, 'version: 1\nservices: []\n');
+
+    expect(() => loadConfig(root)).toThrowError('services must be a non-empty array');
+  });
+
+  it('throws for missing service name', () => {
+    const root = makeTempDir();
+    writeConfig(root, 'version: 1\nservices:\n  - path: ./api\n');
+
+    expect(() => loadConfig(root)).toThrowError('services[0].name must be a non-empty string');
+  });
+
+  it('throws for invalid yaml', () => {
+    const root = makeTempDir();
+    writeConfig(root, 'version: 1\nservices:\n  - name: api\n    path: [\n');
+
+    expect(() => loadConfig(root)).toThrowError(/Invalid YAML/);
+  });
+});

package/test/state.test.ts

@@ -0,0 +1,147 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import {
+  clearState,
+  createState,
+  getStatePath,
+  hasActiveTask,
+  loadState,
+  saveIterationLog,
+  saveState,
+  updateStep,
+} from '../src/lib/state.js';
+import type { TaskStatus, VexdoState } from '../src/types/index.js';
+
+const tempDirs: string[] = [];
+
+function makeTempDir(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'vexdo-state-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe('state', () => {
+  it('returns null when absent', () => {
+    const root = makeTempDir();
+    expect(loadState(root)).toBeNull();
+  });
+
+  it('save/load roundtrip works', () => {
+    const root = makeTempDir();
+    const created = createState('task-1', 'Task 1', '/tmp/task.yml', [
+      { service: 'api', status: 'pending', iteration: 0 },
+    ]);
+
+    saveState(root, created);
+    const loaded = loadState(root);
+
+    expect(loaded).not.toBeNull();
+    expect(loaded?.taskId).toBe('task-1');
+    expect(loaded?.taskTitle).toBe('Task 1');
+    expect(loaded?.steps[0]?.service).toBe('api');
+  });
+
+  it('throws on corrupt JSON', () => {
+    const root = makeTempDir();
+    const statePath = getStatePath(root);
+    fs.mkdirSync(path.dirname(statePath), { recursive: true });
+    fs.writeFileSync(statePath, '{ not-json', 'utf8');
+
+    expect(() => loadState(root)).toThrowError(/Corrupt state file/);
+  });
+
+  it('clearState removes file and is idempotent', () => {
+    const root = makeTempDir();
+    const state = createState('task-1', 'Task 1', '/tmp/task.yml', []);
+    saveState(root, state);
+
+    clearState(root);
+    clearState(root);
+
+    expect(loadState(root)).toBeNull();
+  });
+
+  it('hasActiveTask handles all statuses', () => {
+    const root = makeTempDir();
+    const statuses: TaskStatus[] = ['in_progress', 'review', 'done', 'blocked', 'escalated'];
+
+    for (const status of statuses) {
+      const base: VexdoState = {
+        taskId: 'id',
+        taskTitle: 'title',
+        taskPath: '/tmp/task.yml',
+        status,
+        steps: [],
+        startedAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      };
+      saveState(root, base);
+      const expected = status === 'in_progress' || status === 'review';
+      expect(hasActiveTask(root)).toBe(expected);
+    }
+  });
+
+  it('createState sets expected fields', () => {
+    const state = createState('task-1', 'Task 1', '/tmp/task.yml', [
+      { service: 'api', status: 'pending', iteration: 0 },
+    ]);
+
+    expect(state.taskId).toBe('task-1');
+    expect(state.taskTitle).toBe('Task 1');
+    expect(state.taskPath).toBe('/tmp/task.yml');
+    expect(state.status).toBe('in_progress');
+    expect(state.startedAt).toBeTruthy();
+    expect(state.updatedAt).toBe(state.startedAt);
+  });
+
+  it('updateStep is immutable', () => {
+    const original = createState('task-1', 'Task 1', '/tmp/task.yml', [
+      { service: 'api', status: 'pending', iteration: 0 },
+      { service: 'web', status: 'pending', iteration: 0 },
+    ]);
+
+    const updated = updateStep(original, 'api', {
+      status: 'in_progress',
+      iteration: 1,
+    });
+
+    expect(updated).not.toBe(original);
+    expect(updated.steps).not.toBe(original.steps);
+    expect(updated.steps[0]).not.toBe(original.steps[0]);
+    expect(updated.steps[1]).toBe(original.steps[1]);
+    expect(original.steps[0]?.status).toBe('pending');
+    expect(updated.steps[0]?.status).toBe('in_progress');
+    expect(updated.steps[0]?.iteration).toBe(1);
+  });
+
+  it('saveIterationLog creates diff, review, and arbiter files', () => {
+    const root = makeTempDir();
+
+    saveIterationLog(root, 'task-1', 'api', 2, {
+      diff: 'diff content',
+      review: {
+        comments: [{ severity: 'important', comment: 'Needs work' }],
+      },
+      arbiter: {
+        decision: 'fix',
+        reasoning: 'Please address comments',
+        summary: 'One important issue',
+      },
+    });
+
+    const logsDir = path.join(root, '.vexdo', 'logs', 'task-1');
+    expect(fs.existsSync(path.join(logsDir, 'api-iteration-2-diff.txt'))).toBe(true);
+    expect(fs.existsSync(path.join(logsDir, 'api-iteration-2-review.json'))).toBe(true);
+    expect(fs.existsSync(path.join(logsDir, 'api-iteration-2-arbiter.json'))).toBe(true);
+  });
+});

package/test/unit/claude.test.ts

@@ -0,0 +1,117 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { messagesCreateMock, anthropicCtorMock } = vi.hoisted(() => {
+  const create = vi.fn();
+  const ctor = vi.fn(() => ({
+    messages: {
+      create,
+    },
+  }));
+
+  return {
+    messagesCreateMock: create,
+    anthropicCtorMock: ctor,
+  };
+});
+
+vi.mock('@anthropic-ai/sdk', () => ({
+  default: anthropicCtorMock,
+}));
+
+import { ClaudeClient, ClaudeError } from '../../src/lib/claude.js';
+
+describe('ClaudeClient', () => {
+  beforeEach(() => {
+    messagesCreateMock.mockReset();
+    anthropicCtorMock.mockClear();
+  });
+
+  it('runReviewer parses valid JSON response correctly', async () => {
+    messagesCreateMock.mockResolvedValue({
+      content: [{ type: 'text', text: '{"comments":[{"severity":"important","comment":"bad","file":"a.ts","line":4}]}' }],
+    });
+
+    const client = new ClaudeClient('test-key');
+    const result = await client.runReviewer({ spec: 'spec', diff: 'diff', model: 'claude' });
+
+    expect(result).toEqual({
+      comments: [{ severity: 'important', comment: 'bad', file: 'a.ts', line: 4 }],
+    });
+  });
+
+  it('runReviewer strips markdown code fences before parsing', async () => {
+    messagesCreateMock.mockResolvedValue({
+      content: [
+        {
+          type: 'text',
+          text: '```json\n{"comments":[{"severity":"minor","comment":"nit"}]}\n```',
+        },
+      ],
+    });
+
+    const client = new ClaudeClient('test-key');
+    const result = await client.runReviewer({ spec: 'spec', diff: 'diff', model: 'claude' });
+
+    expect(result.comments).toHaveLength(1);
+    expect(result.comments[0]).toMatchObject({ severity: 'minor', comment: 'nit' });
+  });
+
+  it('runReviewer retries on network error and succeeds within 3 attempts', async () => {
+    messagesCreateMock
+      .mockRejectedValueOnce(new Error('network down'))
+      .mockRejectedValueOnce(new Error('timeout'))
+      .mockResolvedValueOnce({ content: [{ type: 'text', text: '{"comments":[]}' }] });
+
+    const client = new ClaudeClient('test-key');
+    const resultPromise = client.runReviewer({ spec: 'spec', diff: 'diff', model: 'claude' });
+
+    await expect(resultPromise).resolves.toEqual({ comments: [] });
+    expect(messagesCreateMock).toHaveBeenCalledTimes(3);
+  });
+
+  it('runReviewer throws ClaudeError after 3 failures', async () => {
+    messagesCreateMock.mockRejectedValue(new Error('always down'));
+
+    const client = new ClaudeClient('test-key');
+    await expect(client.runReviewer({ spec: 'spec', diff: 'diff', model: 'claude' })).rejects.toMatchObject({
+      name: 'ClaudeError',
+      attempt: 3,
+      message: expect.stringContaining('Claude API failed after 3 attempts'),
+    });
+  });
+
+  it('runReviewer does NOT retry on 401', async () => {
+    const unauthorized = Object.assign(new Error('unauthorized'), { status: 401 });
+    messagesCreateMock.mockRejectedValue(unauthorized);
+
+    const client = new ClaudeClient('test-key');
+    await expect(client.runReviewer({ spec: 'spec', diff: 'diff', model: 'claude' })).rejects.toBeInstanceOf(ClaudeError);
+    expect(messagesCreateMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('runArbiter parses valid JSON response correctly', async () => {
+    messagesCreateMock.mockResolvedValue({
+      content: [
+        {
+          type: 'text',
+          text: '{"decision":"fix","reasoning":"spec violation","feedback_for_codex":"change src/a.ts","summary":"Need fix"}',
+        },
+      ],
+    });
+
+    const client = new ClaudeClient('test-key');
+    const result = await client.runArbiter({
+      spec: 'spec',
+      diff: 'diff',
+      model: 'claude',
+      reviewComments: [{ severity: 'critical', comment: 'broken' }],
+    });
+
+    expect(result).toEqual({
+      decision: 'fix',
+      reasoning: 'spec violation',
+      feedback_for_codex: 'change src/a.ts',
+      summary: 'Need fix',
+    });
+  });
+});

package/test/unit/codex.test.ts

@@ -0,0 +1,67 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { execFileMock } = vi.hoisted(() => ({
+  execFileMock: vi.fn(),
+}));
+const { debugMock } = vi.hoisted(() => ({
+  debugMock: vi.fn(),
+}));
+
+vi.mock('node:child_process', () => ({
+  execFile: execFileMock,
+}));
+
+vi.mock('../../src/lib/logger.js', () => ({
+  debug: debugMock,
+}));
+
+import { CodexError, CodexNotFoundError, checkCodexAvailable, exec } from '../../src/lib/codex.js';
+
+beforeEach(() => {
+  execFileMock.mockReset();
+  debugMock.mockReset();
+});
+
+describe('checkCodexAvailable', () => {
+  it('resolves when codex --version exits 0', async () => {
+    execFileMock.mockImplementation((_cmd, _args, _opts, cb) => cb(null, '1.0.0', ''));
+
+    await expect(checkCodexAvailable()).resolves.toBeUndefined();
+    expect(execFileMock).toHaveBeenCalledWith('codex', ['--version'], expect.any(Object), expect.any(Function));
+  });
+
+  it('throws CodexNotFoundError when codex not found', async () => {
+    const error = Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+    execFileMock.mockImplementation((_cmd, _args, _opts, cb) => cb(error, '', ''));
+
+    await expect(checkCodexAvailable()).rejects.toBeInstanceOf(CodexNotFoundError);
+  });
+});
+
+describe('codex.exec', () => {
+  it('resolves CodexResult on success', async () => {
+    execFileMock.mockImplementation((_cmd, _args, _opts, cb) => cb(null, 'done\n', 'warn\n'));
+
+    await expect(exec({ spec: 'do it', model: 'gpt-4o', cwd: '/repo' })).resolves.toEqual({
+      stdout: 'done',
+      stderr: 'warn',
+      exitCode: 0,
+    });
+  });
+
+  it('throws CodexError on non-zero exit', async () => {
+    const error = Object.assign(new Error('bad'), { code: 9 });
+    execFileMock.mockImplementation((_cmd, _args, _opts, cb) => cb(error, 'partial', 'failed'));
+
+    await expect(exec({ spec: 'do it', model: 'gpt-4o', cwd: '/repo' })).rejects.toBeInstanceOf(CodexError);
+  });
+
+  it('verbose mode passes output to logger.debug', async () => {
+    execFileMock.mockImplementation((_cmd, _args, _opts, cb) => cb(null, 'out', 'err'));
+
+    await exec({ spec: 'do it', model: 'gpt-4o', cwd: '/repo', verbose: true });
+
+    expect(debugMock).toHaveBeenCalledWith('out');
+    expect(debugMock).toHaveBeenCalledWith('err');
+  });
+});

package/test/unit/gh.test.ts

@@ -0,0 +1,49 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { execFileMock } = vi.hoisted(() => ({
+  execFileMock: vi.fn(),
+}));
+
+vi.mock('node:child_process', () => ({
+  execFile: execFileMock,
+}));
+
+import { GhNotFoundError, checkGhAvailable, createPr, getPrUrl } from '../../src/lib/gh.js';
+
+beforeEach(() => {
+  execFileMock.mockReset();
+});
+
+describe('checkGhAvailable', () => {
+  it('resolves when gh is present', async () => {
+    execFileMock.mockImplementation((_cmd, _args, _opts, cb) => cb(null, 'gh version', ''));
+
+    await expect(checkGhAvailable()).resolves.toBeUndefined();
+  });
+
+  it('throws GhNotFoundError when gh not found', async () => {
+    const error = Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+    execFileMock.mockImplementation((_cmd, _args, _opts, cb) => cb(error, '', ''));
+
+    await expect(checkGhAvailable()).rejects.toBeInstanceOf(GhNotFoundError);
+  });
+});
+
+describe('gh helpers', () => {
+  it('createPr returns URL from stdout', async () => {
+    execFileMock.mockImplementation((_cmd, _args, _opts, cb) => cb(null, 'https://github.com/org/repo/pull/1\n', ''));
+
+    await expect(createPr({ title: 't', body: 'b', cwd: '/repo' })).resolves.toBe(
+      'https://github.com/org/repo/pull/1',
+    );
+  });
+
+  it('getPrUrl returns URL or null', async () => {
+    execFileMock.mockImplementationOnce((_cmd, _args, _opts, cb) => cb(null, 'https://github.com/org/repo/pull/2\n', ''));
+    await expect(getPrUrl('branch', '/repo')).resolves.toBe('https://github.com/org/repo/pull/2');
+
+    const error = Object.assign(new Error('none'), { code: 1 });
+    execFileMock.mockImplementationOnce((_cmd, _args, _opts, cb) => cb(error, '', ''));
+    await expect(getPrUrl('branch', '/repo')).resolves.toBeNull();
+  });
+});