@vexdo/cli 0.1.0

package/src/lib/git.ts

@@ -0,0 +1,119 @@
+import { execFile as execFileCb } from 'node:child_process';
+
+const GIT_TIMEOUT_MS = 30_000;
+
+/** Error thrown when a git command fails. */
+export class GitError extends Error {
+  command: string;
+  exitCode: number;
+  stderr: string;
+
+  constructor(args: string[], exitCode: number, stderr: string) {
+    super(`git ${args.join(' ')} failed (exit ${String(exitCode)}): ${stderr}`);
+    this.name = 'GitError';
+    this.command = `git ${args.join(' ')}`;
+    this.exitCode = exitCode;
+    this.stderr = stderr;
+  }
+}
+
+/**
+ * Run a git command in a specific working directory.
+ */
+export async function exec(args: string[], cwd: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFileCb('git', args, { cwd, timeout: GIT_TIMEOUT_MS, encoding: 'utf8' }, (error, stdout, stderr) => {
+      if (error) {
+        const exitCode = typeof error.code === 'number' ? error.code : -1;
+        reject(new GitError(args, exitCode, (stderr || error.message).trim()));
+        return;
+      }
+      resolve(stdout.trimEnd());
+    });
+  });
+}
+
+/**
+ * Get the current branch name.
+ */
+export async function getCurrentBranch(cwd: string): Promise<string> {
+  return exec(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+}
+
+/**
+ * Check whether a local branch exists.
+ */
+export async function branchExists(name: string, cwd: string): Promise<boolean> {
+  try {
+    await exec(['rev-parse', '--verify', '--quiet', `refs/heads/${name}`], cwd);
+    return true;
+  } catch (error) {
+    if (error instanceof GitError && error.exitCode === 1) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Create and checkout a new branch.
+ */
+export async function createBranch(name: string, cwd: string): Promise<void> {
+  if (await branchExists(name, cwd)) {
+    throw new GitError(['checkout', '-b', name], 128, `branch '${name}' already exists`);
+  }
+  await exec(['checkout', '-b', name], cwd);
+}
+
+/**
+ * Checkout an existing branch.
+ */
+export async function checkoutBranch(name: string, cwd: string): Promise<void> {
+  await exec(['checkout', name], cwd);
+}
+
+/**
+ * Get the git diff for the working directory.
+ */
+export async function getDiff(cwd: string, base?: string): Promise<string> {
+  if (base) {
+    return exec(['diff', `${base}..HEAD`], cwd);
+  }
+  return exec(['diff', 'HEAD'], cwd);
+}
+
+/**
+ * Get porcelain status output.
+ */
+export async function getStatus(cwd: string): Promise<string> {
+  return exec(['status', '--porcelain'], cwd);
+}
+
+/**
+ * Return whether the repository has uncommitted changes.
+ */
+export async function hasUncommittedChanges(cwd: string): Promise<boolean> {
+  const status = await getStatus(cwd);
+  return status.length > 0;
+}
+
+/**
+ * Stage all changes.
+ */
+export async function stageAll(cwd: string): Promise<void> {
+  await exec(['add', '-A'], cwd);
+}
+
+/**
+ * Commit staged changes.
+ */
+export async function commit(message: string, cwd: string): Promise<void> {
+  await exec(['commit', '-m', message], cwd);
+}
+
+/**
+ * Build the task branch name for a service.
+ */
+export function getBranchName(taskId: string, service: string): string {
+  return `vexdo/${taskId}/${service}`;
+}

package/src/lib/logger.ts

@@ -0,0 +1,147 @@
+import ora from 'ora';
+import type { Ora } from 'ora';
+import pc from 'picocolors';
+
+import type { ReviewComment } from '../types/index.js';
+
+let verboseEnabled = false;
+
+function safeLog(method: 'log' | 'error', message: string): void {
+  try {
+    if (method === 'error') {
+      console.error(message);
+    } else {
+      console.log(message);
+    }
+  } catch {
+    // never throw
+  }
+}
+
+export function setVerbose(enabled: boolean): void {
+  verboseEnabled = enabled;
+}
+
+export function info(message: string): void {
+  safeLog('log', `${pc.cyan('→')} ${message}`);
+}
+
+export function success(message: string): void {
+  safeLog('log', `${pc.green('✓')} ${message}`);
+}
+
+export function warn(message: string): void {
+  safeLog('log', `${pc.yellow('⚠')} ${message}`);
+}
+
+export function error(message: string): void {
+  safeLog('error', `${pc.red('✖')} ${message}`);
+}
+
+export function debug(message: string): void {
+  if (!verboseEnabled) {
+    return;
+  }
+  safeLog('log', `${pc.gray('•')} ${message}`);
+}
+
+export function header(title: string): void {
+  safeLog('log', `${pc.bold(pc.white(title))}\n${pc.gray('─'.repeat(title.length))}`);
+}
+
+export function step(n: number, total: number, title: string): void {
+  safeLog('log', `${pc.bold(`Step ${String(n)}/${String(total)}:`)} ${title}`);
+}
+
+export function iteration(n: number, max: number): void {
+  safeLog('log', pc.gray(`Iteration ${String(n)}/${String(max)}`));
+}
+
+export function fatal(message: string, hint?: string): void {
+  safeLog('error', `${pc.bold(pc.red('Error:'))} ${message}`);
+  if (hint) {
+    safeLog('error', `${pc.gray('Hint:')} ${hint}`);
+  }
+}
+
+export function spinner(text: string): Ora {
+  try {
+    return ora({ text });
+  } catch {
+    return ora({ text: '' });
+  }
+}
+
+export function escalation(context: {
+  taskId: string;
+  service: string;
+  iteration: number;
+  spec: string;
+  diff: string;
+  reviewComments: ReviewComment[];
+  arbiterReasoning: string;
+  summary: string;
+}): void {
+  const lines = [
+    pc.bold(pc.red('Escalation triggered')),
+    `${pc.gray('Task:')} ${context.taskId}`,
+    `${pc.gray('Service:')} ${context.service}`,
+    `${pc.gray('Iteration:')} ${String(context.iteration)}`,
+    `${pc.gray('Summary:')} ${context.summary}`,
+    '',
+    pc.bold('Spec:'),
+    context.spec,
+    '',
+    pc.bold('Arbiter reasoning:'),
+    context.arbiterReasoning,
+    '',
+    pc.bold('Review comments:'),
+  ];
+
+  for (const comment of context.reviewComments) {
+    const sevColor =
+      comment.severity === 'critical'
+        ? pc.red
+        : comment.severity === 'important'
+          ? pc.yellow
+          : comment.severity === 'minor'
+            ? pc.cyan
+            : pc.gray;
+    const location = comment.file ? ` (${comment.file}${comment.line ? `:${String(comment.line)}` : ''})` : '';
+    lines.push(`- ${sevColor(comment.severity.toUpperCase())}${location}: ${comment.comment}`);
+    if (comment.suggestion) {
+      lines.push(`  ${pc.gray(`Suggestion: ${comment.suggestion}`)}`);
+    }
+  }
+
+  lines.push('', pc.bold('Diff:'), context.diff, '', pc.gray('Hint: run `vexdo abort` to clear state.'));
+
+  safeLog('error', lines.join('\n'));
+}
+
+export function reviewSummary(comments: ReviewComment[]): void {
+  const counts = {
+    critical: 0,
+    important: 0,
+    minor: 0,
+    noise: 0,
+  };
+
+  for (const comment of comments) {
+    counts[comment.severity] += 1;
+  }
+
+  safeLog(
+    'log',
+    `${pc.bold('Review:')} ${String(counts.critical)} critical ${String(counts.important)} important ${String(counts.minor)} minor`,
+  );
+
+  for (const comment of comments) {
+    if (comment.severity === 'noise') {
+      continue;
+    }
+
+    const location = comment.file ? ` (${comment.file}${comment.line ? `:${String(comment.line)}` : ''})` : '';
+    safeLog('log', `- ${comment.severity}${location}: ${comment.comment}`);
+  }
+}

package/src/lib/requirements.ts

@@ -0,0 +1,18 @@
+import * as codex from './codex.js';
+import * as gh from './gh.js';
+
+export function requireAnthropicApiKey(): string {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) {
+    throw new Error('ANTHROPIC_API_KEY is required');
+  }
+  return apiKey;
+}
+
+export async function requireCodexAvailable(): Promise<void> {
+  await codex.checkCodexAvailable();
+}
+
+export async function requireGhAvailable(): Promise<void> {
+  await gh.checkGhAvailable();
+}

package/src/lib/review-loop.ts

@@ -0,0 +1,154 @@
+import path from 'node:path';
+
+import * as codex from './codex.js';
+import type { ClaudeClient } from './claude.js';
+import * as git from './git.js';
+import * as logger from './logger.js';
+import * as state from './state.js';
+import type {
+  ArbiterResult,
+  ReviewComment,
+  StepState,
+  Task,
+  TaskStep,
+  VexdoConfig,
+} from '../types/index.js';
+
+export interface ReviewLoopOptions {
+  taskId: string;
+  task: Task;
+  step: TaskStep;
+  stepState: StepState;
+  projectRoot: string;
+  config: VexdoConfig;
+  claude: ClaudeClient;
+  dryRun?: boolean;
+  verbose?: boolean;
+}
+
+export interface ReviewLoopResult {
+  decision: 'submit' | 'escalate';
+  finalIteration: number;
+  lastReviewComments: ReviewComment[];
+  lastArbiterResult: ArbiterResult;
+}
+
+export async function runReviewLoop(opts: ReviewLoopOptions): Promise<ReviewLoopResult> {
+  if (opts.dryRun) {
+    logger.info(`[dry-run] Would run review loop for service ${opts.step.service}`);
+    return {
+      decision: 'submit',
+      finalIteration: opts.stepState.iteration,
+      lastReviewComments: [],
+      lastArbiterResult: {
+        decision: 'submit',
+        reasoning: 'Dry run: skipped reviewer and arbiter calls.',
+        summary: 'Dry run mode; submitting without external calls.',
+      },
+    };
+  }
+
+  const serviceConfig = opts.config.services.find((service) => service.name === opts.step.service);
+  if (!serviceConfig) {
+    throw new Error(`Unknown service in step: ${opts.step.service}`);
+  }
+
+  const serviceRoot = path.resolve(opts.projectRoot, serviceConfig.path);
+  let iteration = opts.stepState.iteration;
+
+  for (;;) {
+    logger.iteration(iteration + 1, opts.config.review.max_iterations);
+
+    const diff = await git.getDiff(serviceRoot);
+    if (!diff.trim()) {
+      return {
+        decision: 'submit',
+        finalIteration: iteration,
+        lastReviewComments: [],
+        lastArbiterResult: {
+          decision: 'submit',
+          reasoning: 'No changes in git diff for service directory.',
+          summary: 'No diff detected, nothing to review.',
+        },
+      };
+    }
+
+    const review = await opts.claude.runReviewer({
+      spec: opts.step.spec,
+      diff,
+      model: opts.config.review.model,
+    });
+
+    logger.reviewSummary(review.comments);
+
+    const arbiter = await opts.claude.runArbiter({
+      spec: opts.step.spec,
+      diff,
+      reviewComments: review.comments,
+      model: opts.config.review.model,
+    });
+
+    state.saveIterationLog(opts.projectRoot, opts.taskId, opts.step.service, iteration, {
+      diff,
+      review,
+      arbiter,
+    });
+
+    opts.stepState.lastReviewComments = review.comments;
+    opts.stepState.lastArbiterResult = arbiter;
+
+    if (arbiter.decision === 'submit') {
+      return {
+        decision: 'submit',
+        finalIteration: iteration,
+        lastReviewComments: review.comments,
+        lastArbiterResult: arbiter,
+      };
+    }
+
+    if (arbiter.decision === 'escalate') {
+      return {
+        decision: 'escalate',
+        finalIteration: iteration,
+        lastReviewComments: review.comments,
+        lastArbiterResult: arbiter,
+      };
+    }
+
+    if (iteration >= opts.config.review.max_iterations) {
+      return {
+        decision: 'escalate',
+        finalIteration: iteration,
+        lastReviewComments: review.comments,
+        lastArbiterResult: {
+          decision: 'escalate',
+          reasoning: 'Max review iterations reached while arbiter still requested fixes.',
+          summary: 'Escalated because maximum iterations were exhausted.',
+        },
+      };
+    }
+
+    if (!arbiter.feedback_for_codex) {
+      return {
+        decision: 'escalate',
+        finalIteration: iteration,
+        lastReviewComments: review.comments,
+        lastArbiterResult: {
+          decision: 'escalate',
+          reasoning: 'Arbiter returned fix decision without feedback_for_codex.',
+          summary: 'Escalated because fix instructions were missing.',
+        },
+      };
+    }
+
+    await codex.exec({
+      spec: arbiter.feedback_for_codex,
+      model: opts.config.codex.model,
+      cwd: serviceRoot,
+      verbose: opts.verbose,
+    });
+
+    iteration += 1;
+    opts.stepState.iteration = iteration;
+  }
+}

package/src/lib/state.ts

@@ -0,0 +1,121 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { ArbiterResult, ReviewResult, StepState, VexdoState } from '../types/index.js';
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+export function getStateDir(projectRoot: string): string {
+  return path.join(projectRoot, '.vexdo');
+}
+
+export function getStatePath(projectRoot: string): string {
+  return path.join(getStateDir(projectRoot), 'state.json');
+}
+
+export function getLogsDir(projectRoot: string, taskId: string): string {
+  return path.join(getStateDir(projectRoot), 'logs', taskId);
+}
+
+export function ensureLogsDir(projectRoot: string, taskId: string): string {
+  const logsDir = getLogsDir(projectRoot, taskId);
+  fs.mkdirSync(logsDir, { recursive: true });
+  return logsDir;
+}
+
+export function loadState(projectRoot: string): VexdoState | null {
+  const statePath = getStatePath(projectRoot);
+  if (!fs.existsSync(statePath)) {
+    return null;
+  }
+
+  const raw = fs.readFileSync(statePath, 'utf8');
+  try {
+    return JSON.parse(raw) as VexdoState;
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Corrupt state file at ${statePath}: ${message}`);
+  }
+}
+
+export function saveState(projectRoot: string, state: VexdoState): void {
+  const stateDir = getStateDir(projectRoot);
+  fs.mkdirSync(stateDir, { recursive: true });
+
+  const nextState: VexdoState = {
+    ...state,
+    updatedAt: nowIso(),
+  };
+
+  fs.writeFileSync(getStatePath(projectRoot), JSON.stringify(nextState, null, 2) + '\n', 'utf8');
+}
+
+export function clearState(projectRoot: string): void {
+  const statePath = getStatePath(projectRoot);
+  if (fs.existsSync(statePath)) {
+    fs.rmSync(statePath);
+  }
+}
+
+export function hasActiveTask(projectRoot: string): boolean {
+  const state = loadState(projectRoot);
+  return state?.status === 'in_progress' || state?.status === 'review';
+}
+
+export function createState(
+  taskId: string,
+  taskTitle: string,
+  taskPath: string,
+  steps: StepState[],
+): VexdoState {
+  const timestamp = nowIso();
+  return {
+    taskId,
+    taskTitle,
+    taskPath,
+    status: 'in_progress',
+    steps: [...steps],
+    startedAt: timestamp,
+    updatedAt: timestamp,
+  };
+}
+
+export function updateStep(
+  state: VexdoState,
+  service: string,
+  updates: Partial<Omit<StepState, 'service'>>,
+): VexdoState {
+  return {
+    ...state,
+    steps: state.steps.map((step) => {
+      if (step.service !== service) {
+        return step;
+      }
+      return {
+        ...step,
+        ...updates,
+      };
+    }),
+    updatedAt: nowIso(),
+  };
+}
+
+export function saveIterationLog(
+  projectRoot: string,
+  taskId: string,
+  service: string,
+  iteration: number,
+  payload: { diff: string; review: ReviewResult; arbiter: ArbiterResult },
+): void {
+  const logsDir = ensureLogsDir(projectRoot, taskId);
+  const base = `${service}-iteration-${String(iteration)}`;
+  fs.writeFileSync(path.join(logsDir, `${base}-diff.txt`), payload.diff, 'utf8');
+  fs.writeFileSync(path.join(logsDir, `${base}-review.json`), JSON.stringify(payload.review, null, 2) + '\n', 'utf8');
+  fs.writeFileSync(
+    path.join(logsDir, `${base}-arbiter.json`),
+    JSON.stringify(payload.arbiter, null, 2) + '\n',
+    'utf8',
+  );
+}

package/src/lib/submit-task.ts

@@ -0,0 +1,43 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import * as gh from './gh.js';
+import * as logger from './logger.js';
+import { clearState, saveState } from './state.js';
+import { ensureTaskDirectory, moveTaskFileAtomically } from './tasks.js';
+import type { VexdoConfig, VexdoState } from '../types/index.js';
+
+export async function submitActiveTask(projectRoot: string, config: VexdoConfig, state: VexdoState): Promise<void> {
+  for (const step of state.steps) {
+    if (step.status !== 'done' && step.status !== 'in_progress') {
+      continue;
+    }
+
+    const service = config.services.find((item) => item.name === step.service);
+    if (!service) {
+      throw new Error(`Unknown service in state: ${step.service}`);
+    }
+
+    const servicePath = path.resolve(projectRoot, service.path);
+    const body = `Task: ${state.taskId}\nService: ${step.service}`;
+    const url = await gh.createPr({
+      title: `${state.taskTitle} [${step.service}]`,
+      body,
+      base: 'main',
+      cwd: servicePath,
+    });
+
+    logger.success(`PR created: ${url}`);
+  }
+
+  state.status = 'done';
+  saveState(projectRoot, state);
+
+  const doneDir = ensureTaskDirectory(projectRoot, 'done');
+  if (fs.existsSync(state.taskPath)) {
+    state.taskPath = moveTaskFileAtomically(state.taskPath, doneDir);
+    saveState(projectRoot, state);
+  }
+
+  clearState(projectRoot);
+}

package/src/lib/tasks.ts

@@ -0,0 +1,94 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { load as parseYaml } from 'js-yaml';
+
+import type { StepState, Task, TaskStep, VexdoConfig } from '../types/index.js';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function requireString(value: unknown, field: string): string {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`${field} must be a non-empty string`);
+  }
+
+  return value;
+}
+
+function parseTaskStep(value: unknown, index: number, config: VexdoConfig): TaskStep {
+  if (!isRecord(value)) {
+    throw new Error(`steps[${String(index)}] must be an object`);
+  }
+
+  const service = requireString(value.service, `steps[${String(index)}].service`);
+  const spec = requireString(value.spec, `steps[${String(index)}].spec`);
+
+  if (!config.services.some((item) => item.name === service)) {
+    throw new Error(`steps[${String(index)}].service references unknown service '${service}'`);
+  }
+
+  const dependsOnRaw = value.depends_on;
+  let depends_on: string[] | undefined;
+
+  if (dependsOnRaw !== undefined) {
+    if (!Array.isArray(dependsOnRaw) || !dependsOnRaw.every((dep) => typeof dep === 'string' && dep.trim().length > 0)) {
+      throw new Error(`steps[${String(index)}].depends_on must be an array of non-empty strings`);
+    }
+    depends_on = dependsOnRaw;
+  }
+
+  return {
+    service,
+    spec,
+    depends_on,
+  };
+}
+
+export function loadAndValidateTask(taskPath: string, config: VexdoConfig): Task {
+  const raw = fs.readFileSync(taskPath, 'utf8');
+
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(raw);
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid task YAML: ${message}`);
+  }
+
+  if (!isRecord(parsed)) {
+    throw new Error('task must be a YAML object');
+  }
+
+  const id = requireString(parsed.id, 'id');
+  const title = requireString(parsed.title, 'title');
+
+  if (!Array.isArray(parsed.steps) || parsed.steps.length === 0) {
+    throw new Error('steps must be a non-empty array');
+  }
+
+  const steps = parsed.steps.map((step, index) => parseTaskStep(step, index, config));
+
+  return { id, title, steps };
+}
+
+export function buildInitialStepState(task: Task): StepState[] {
+  return task.steps.map((step) => ({
+    service: step.service,
+    status: 'pending',
+    iteration: 0,
+  }));
+}
+
+export function ensureTaskDirectory(projectRoot: string, taskState: 'backlog' | 'in_progress' | 'review' | 'done' | 'blocked'): string {
+  const dir = path.join(projectRoot, 'tasks', taskState);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function moveTaskFileAtomically(taskPath: string, destinationDir: string): string {
+  const destinationPath = path.join(destinationDir, path.basename(taskPath));
+  fs.renameSync(taskPath, destinationPath);
+  return destinationPath;
+}