openairev 0.2.0

package/src/session/chain-manager.js

@@ -0,0 +1,292 @@
+import { writeFileSync, readFileSync, existsSync, readdirSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+export function getChainsDir(cwd = process.cwd()) {
+  return join(cwd, '.openairev', 'chains');
+}
+
+// Valid stages and their allowed transitions
+const TRANSITIONS = {
+  analyze:        ['awaiting_user', 'planning', 'implementation'],
+  awaiting_user:  ['planning', 'implementation', 'analyze'],
+  planning:       ['plan_review'],
+  plan_review:    ['plan_fix', 'implementation', 'error'],
+  plan_fix:       ['plan_review'],
+  implementation: ['code_review'],
+  code_review:    ['code_fix', 'implementation', 'done', 'error'],
+  code_fix:       ['code_review'],
+  done:           [],
+};
+
+/**
+ * Create a new chain with full workflow state.
+ */
+export function createChain({ executor, reviewer, topic, maxRounds, specRef, cwd = process.cwd() }) {
+  const dir = getChainsDir(cwd);
+  mkdirSync(dir, { recursive: true });
+
+  const chain = {
+    chain_id: `chain_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+    created: new Date().toISOString(),
+    updated: new Date().toISOString(),
+    status: 'active',
+    stage: 'analyze',
+    task: {
+      user_request: topic || null,
+      spec_ref: specRef || null,
+    },
+    participants: {
+      executor,
+      reviewer,
+    },
+    max_rounds: maxRounds,
+    phase_index: 0,
+    phases: [],
+    artifacts: {
+      analysis: null,
+      plan: null,
+      plan_review: null,
+      current_diff_ref: null,
+    },
+    rounds: [],
+    questions: [],
+    sessions: {
+      executor: {},
+      reviewer: {},
+    },
+  };
+
+  saveChain(chain, cwd);
+  return chain;
+}
+
+/**
+ * Transition chain to a new stage. Validates the transition is allowed.
+ */
+export function transitionTo(chain, newStage, cwd = process.cwd()) {
+  const allowed = TRANSITIONS[chain.stage];
+  if (!allowed || !allowed.includes(newStage)) {
+    throw new Error(`Invalid transition: ${chain.stage} → ${newStage}. Allowed: ${allowed?.join(', ')}`);
+  }
+
+  chain.stage = newStage;
+  chain.updated = new Date().toISOString();
+
+  // Set chain status based on stage
+  if (newStage === 'done') {
+    chain.status = 'completed';
+  } else if (newStage === 'awaiting_user') {
+    chain.status = 'blocked';
+  } else if (newStage === 'error') {
+    chain.status = 'error';
+  } else {
+    chain.status = 'active';
+  }
+
+  saveChain(chain, cwd);
+  return chain;
+}
+
+/**
+ * Record a completed review round (plan or code).
+ */
+export function addRound(chain, { kind, review, toolResults, phaseId, cwd = process.cwd() }) {
+  chain.updated = new Date().toISOString();
+
+  chain.rounds.push({
+    round: chain.rounds.length + 1,
+    kind: kind || 'code_review',
+    phase_id: phaseId || chain.phases[chain.phase_index]?.id || null,
+    timestamp: new Date().toISOString(),
+    review: {
+      verdict: review.verdict,
+    },
+    tool_results: toolResults || null,
+    result: review.verdict?.status || null,
+  });
+
+  // Update reviewer session ID
+  if (review.session_id) {
+    chain.sessions.reviewer[kind || 'code_review'] = review.session_id;
+  }
+
+  saveChain(chain, cwd);
+  return chain;
+}
+
+/**
+ * Set an artifact on the chain.
+ */
+export function setArtifact(chain, key, value, cwd = process.cwd()) {
+  chain.artifacts[key] = value;
+  chain.updated = new Date().toISOString();
+  saveChain(chain, cwd);
+}
+
+/**
+ * Set executor session ID for the current stage.
+ */
+export function setExecutorSession(chain, sessionId, stage, cwd = process.cwd()) {
+  chain.sessions.executor[stage || chain.stage] = sessionId;
+  chain.updated = new Date().toISOString();
+  saveChain(chain, cwd);
+}
+
+/**
+ * Get the executor session ID for a given stage (or latest).
+ */
+export function getExecutorSession(chain, stage) {
+  if (stage) return chain.sessions.executor[stage] || null;
+  // Return the most recently set session
+  const stages = Object.keys(chain.sessions.executor);
+  return stages.length > 0 ? chain.sessions.executor[stages[stages.length - 1]] : null;
+}
+
+/**
+ * Get the reviewer session ID for a given review kind (or latest).
+ */
+export function getReviewerSession(chain, kind) {
+  if (kind) return chain.sessions.reviewer[kind] || null;
+  const kinds = Object.keys(chain.sessions.reviewer);
+  return kinds.length > 0 ? chain.sessions.reviewer[kinds[kinds.length - 1]] : null;
+}
+
+/**
+ * Add a question that blocks the chain.
+ */
+export function addQuestion(chain, question, cwd = process.cwd()) {
+  chain.questions.push({
+    id: `q${chain.questions.length + 1}`,
+    question,
+    answer: null,
+    status: 'pending',
+  });
+  chain.updated = new Date().toISOString();
+  saveChain(chain, cwd);
+  return chain.questions[chain.questions.length - 1];
+}
+
+/**
+ * Answer a pending question. If all answered, chain can proceed.
+ */
+export function answerQuestion(chain, questionId, answer, cwd = process.cwd()) {
+  const q = chain.questions.find(q => q.id === questionId);
+  if (!q) throw new Error(`Question not found: ${questionId}`);
+  q.answer = answer;
+  q.status = 'answered';
+  chain.updated = new Date().toISOString();
+  saveChain(chain, cwd);
+  return q;
+}
+
+/**
+ * Check if chain has unanswered questions.
+ */
+export function hasPendingQuestions(chain) {
+  return chain.questions.some(q => q.status === 'pending');
+}
+
+/**
+ * Add or update phases on the chain.
+ */
+export function setPhases(chain, phases, cwd = process.cwd()) {
+  chain.phases = phases.map((p, i) => ({
+    id: p.id || `phase_${i + 1}`,
+    name: p.name,
+    goal: p.goal || null,
+    status: p.status || 'pending',
+  }));
+  chain.phase_index = 0;
+  chain.updated = new Date().toISOString();
+  saveChain(chain, cwd);
+}
+
+/**
+ * Advance to the next phase. Returns true if there's a next phase.
+ */
+export function advancePhase(chain, cwd = process.cwd()) {
+  if (chain.phase_index < chain.phases.length - 1) {
+    chain.phases[chain.phase_index].status = 'approved';
+    chain.phase_index += 1;
+    chain.phases[chain.phase_index].status = 'in_progress';
+    chain.updated = new Date().toISOString();
+    saveChain(chain, cwd);
+    return true;
+  }
+  // Final phase done
+  if (chain.phases.length > 0) {
+    chain.phases[chain.phase_index].status = 'approved';
+    saveChain(chain, cwd);
+  }
+  return false;
+}
+
+/**
+ * Get current phase, or null if no phases defined.
+ */
+export function getCurrentPhase(chain) {
+  if (!chain.phases || chain.phases.length === 0) return null;
+  return chain.phases[chain.phase_index] || null;
+}
+
+/**
+ * Close chain with a final status.
+ */
+export function closeChain(chain, status, cwd = process.cwd()) {
+  chain.status = status;
+  chain.stage = status === 'completed' ? 'done' : chain.stage;
+  chain.updated = new Date().toISOString();
+  chain.final_verdict = chain.rounds.length > 0
+    ? chain.rounds[chain.rounds.length - 1].review.verdict
+    : null;
+  saveChain(chain, cwd);
+}
+
+/**
+ * Load a chain by ID.
+ */
+export function loadChain(chainId, cwd = process.cwd()) {
+  const filePath = join(getChainsDir(cwd), `${chainId}.json`);
+  if (!existsSync(filePath)) return null;
+  return JSON.parse(readFileSync(filePath, 'utf-8'));
+}
+
+/**
+ * List all chains, optionally filtered by status.
+ */
+export function listChains(cwd = process.cwd(), { status, limit = 20 } = {}) {
+  const dir = getChainsDir(cwd);
+  if (!existsSync(dir)) return [];
+
+  return readdirSync(dir)
+    .filter(f => f.endsWith('.json'))
+    .map(f => {
+      try {
+        return JSON.parse(readFileSync(join(dir, f), 'utf-8'));
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .filter(c => !status || c.status === status)
+    .sort((a, b) => new Date(b.updated) - new Date(a.updated))
+    .slice(0, limit);
+}
+
+/**
+ * Get the most recent active or blocked chain.
+ */
+export function getActiveChain(cwd = process.cwd()) {
+  const chains = listChains(cwd, { limit: 20 });
+  return chains.find(c => c.status === 'active' || c.status === 'blocked') || null;
+}
+
+let dirEnsured = false;
+function saveChain(chain, cwd) {
+  const dir = getChainsDir(cwd);
+  if (!dirEnsured) {
+    mkdirSync(dir, { recursive: true });
+    dirEnsured = true;
+  }
+  writeFileSync(join(dir, `${chain.chain_id}.json`), JSON.stringify(chain, null, 2));
+}

package/src/session/chain-manager.test.js

@@ -0,0 +1,188 @@
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, rmSync } from 'fs';
+import { join } from 'path';
+import {
+  createChain, transitionTo, addRound, closeChain, loadChain,
+  listChains, getActiveChain, setExecutorSession, getExecutorSession,
+  addQuestion, answerQuestion, hasPendingQuestions,
+  setPhases, advancePhase, getCurrentPhase, setArtifact,
+} from './chain-manager.js';
+
+const TMP = join(process.cwd(), '.test-tmp-chains');
+
+describe('chain-manager', () => {
+  beforeEach(() => {
+    mkdirSync(TMP, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(TMP, { recursive: true, force: true });
+  });
+
+  it('creates a chain with workflow state', () => {
+    const chain = createChain({
+      executor: 'claude_code',
+      reviewer: 'codex',
+      topic: 'auth middleware',
+      maxRounds: 3,
+      cwd: TMP,
+    });
+
+    assert.ok(chain.chain_id.startsWith('chain_'));
+    assert.equal(chain.status, 'active');
+    assert.equal(chain.stage, 'analyze');
+    assert.equal(chain.participants.executor, 'claude_code');
+    assert.equal(chain.participants.reviewer, 'codex');
+    assert.equal(chain.max_rounds, 3);
+    assert.equal(chain.task.user_request, 'auth middleware');
+    assert.deepEqual(chain.rounds, []);
+    assert.deepEqual(chain.phases, []);
+    assert.deepEqual(chain.questions, []);
+  });
+
+  it('creates chain with spec ref', () => {
+    const chain = createChain({
+      executor: 'codex', reviewer: 'claude_code', maxRounds: 1,
+      specRef: 'openspec/changes/070_add-admin-dashboard-ui/',
+      cwd: TMP,
+    });
+    assert.equal(chain.task.spec_ref, 'openspec/changes/070_add-admin-dashboard-ui/');
+  });
+
+  it('transitions between valid stages', () => {
+    const chain = createChain({ executor: 'a', reviewer: 'b', maxRounds: 3, cwd: TMP });
+
+    transitionTo(chain, 'planning', TMP);
+    assert.equal(chain.stage, 'planning');
+    assert.equal(chain.status, 'active');
+
+    transitionTo(chain, 'plan_review', TMP);
+    assert.equal(chain.stage, 'plan_review');
+
+    transitionTo(chain, 'implementation', TMP);
+    assert.equal(chain.stage, 'implementation');
+
+    transitionTo(chain, 'code_review', TMP);
+    transitionTo(chain, 'code_fix', TMP);
+    transitionTo(chain, 'code_review', TMP);
+    transitionTo(chain, 'done', TMP);
+    assert.equal(chain.status, 'completed');
+  });
+
+  it('rejects invalid transitions', () => {
+    const chain = createChain({ executor: 'a', reviewer: 'b', maxRounds: 1, cwd: TMP });
+    assert.throws(() => transitionTo(chain, 'code_review', TMP), /Invalid transition/);
+  });
+
+  it('sets blocked status on awaiting_user', () => {
+    const chain = createChain({ executor: 'a', reviewer: 'b', maxRounds: 1, cwd: TMP });
+    transitionTo(chain, 'awaiting_user', TMP);
+    assert.equal(chain.status, 'blocked');
+    assert.equal(chain.stage, 'awaiting_user');
+  });
+
+  it('manages questions', () => {
+    const chain = createChain({ executor: 'a', reviewer: 'b', maxRounds: 1, cwd: TMP });
+
+    addQuestion(chain, 'Should auth apply to all routes?', TMP);
+    assert.equal(chain.questions.length, 1);
+    assert.equal(hasPendingQuestions(chain), true);
+
+    answerQuestion(chain, 'q1', 'Only /api/* routes', TMP);
+    assert.equal(chain.questions[0].status, 'answered');
+    assert.equal(chain.questions[0].answer, 'Only /api/* routes');
+    assert.equal(hasPendingQuestions(chain), false);
+  });
+
+  it('manages phases', () => {
+    const chain = createChain({ executor: 'a', reviewer: 'b', maxRounds: 3, cwd: TMP });
+
+    setPhases(chain, [
+      { name: 'Auth middleware', goal: 'Implement middleware' },
+      { name: 'Tests', goal: 'Write tests' },
+    ], TMP);
+
+    assert.equal(chain.phases.length, 2);
+    assert.equal(chain.phase_index, 0);
+    assert.equal(getCurrentPhase(chain).name, 'Auth middleware');
+
+    const hasMore = advancePhase(chain, TMP);
+    assert.equal(hasMore, true);
+    assert.equal(chain.phase_index, 1);
+    assert.equal(getCurrentPhase(chain).name, 'Tests');
+    assert.equal(chain.phases[0].status, 'approved');
+
+    const hasMore2 = advancePhase(chain, TMP);
+    assert.equal(hasMore2, false);
+    assert.equal(chain.phases[1].status, 'approved');
+  });
+
+  it('adds rounds with kind', () => {
+    const chain = createChain({ executor: 'a', reviewer: 'b', maxRounds: 3, cwd: TMP });
+    transitionTo(chain, 'planning', TMP);
+    transitionTo(chain, 'plan_review', TMP);
+
+    addRound(chain, {
+      kind: 'plan_review',
+      review: { verdict: { status: 'approved', confidence: 0.9 }, session_id: 'rev-1' },
+      cwd: TMP,
+    });
+
+    assert.equal(chain.rounds.length, 1);
+    assert.equal(chain.rounds[0].kind, 'plan_review');
+    assert.equal(chain.rounds[0].result, 'approved');
+    assert.equal(chain.sessions.reviewer.plan_review, 'rev-1');
+  });
+
+  it('sets and gets executor sessions per stage', () => {
+    const chain = createChain({ executor: 'a', reviewer: 'b', maxRounds: 1, cwd: TMP });
+
+    setExecutorSession(chain, 'sess-1', 'analyze', TMP);
+    setExecutorSession(chain, 'sess-2', 'implementation', TMP);
+
+    assert.equal(getExecutorSession(chain, 'analyze'), 'sess-1');
+    assert.equal(getExecutorSession(chain, 'implementation'), 'sess-2');
+  });
+
+  it('sets artifacts', () => {
+    const chain = createChain({ executor: 'a', reviewer: 'b', maxRounds: 1, cwd: TMP });
+    setArtifact(chain, 'plan', 'Build the thing in 3 steps', TMP);
+    const loaded = loadChain(chain.chain_id, TMP);
+    assert.equal(loaded.artifacts.plan, 'Build the thing in 3 steps');
+  });
+
+  it('persists and loads chain', () => {
+    const chain = createChain({ executor: 'a', reviewer: 'b', maxRounds: 2, cwd: TMP });
+    const loaded = loadChain(chain.chain_id, TMP);
+    assert.equal(loaded.chain_id, chain.chain_id);
+    assert.equal(loaded.stage, 'analyze');
+  });
+
+  it('lists and filters chains', () => {
+    createChain({ executor: 'a', reviewer: 'b', maxRounds: 1, cwd: TMP });
+    const c2 = createChain({ executor: 'a', reviewer: 'b', maxRounds: 1, cwd: TMP });
+    closeChain(c2, 'completed', TMP);
+
+    const active = listChains(TMP, { status: 'active' });
+    assert.equal(active.length, 1);
+
+    const all = listChains(TMP);
+    assert.equal(all.length, 2);
+  });
+
+  it('getActiveChain finds active or blocked', () => {
+    const c1 = createChain({ executor: 'a', reviewer: 'b', maxRounds: 1, cwd: TMP });
+    transitionTo(c1, 'awaiting_user', TMP); // blocked
+
+    const active = getActiveChain(TMP);
+    assert.ok(active);
+    assert.equal(active.status, 'blocked');
+  });
+
+  it('returns null when no chains exist', () => {
+    assert.equal(getActiveChain(TMP), null);
+    assert.deepEqual(listChains(TMP), []);
+    assert.equal(loadChain('nonexistent', TMP), null);
+  });
+});

package/src/session/session-manager.js

@@ -0,0 +1,66 @@
+import { writeFileSync, readFileSync, existsSync, readdirSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+export function getSessionsDir(cwd = process.cwd()) {
+  return join(cwd, '.openairev', 'sessions');
+}
+
+/**
+ * Save a review session to disk.
+ */
+export function saveSession(session, cwd = process.cwd()) {
+  const dir = getSessionsDir(cwd);
+  mkdirSync(dir, { recursive: true });
+
+  const filename = `${session.id}.json`;
+  writeFileSync(join(dir, filename), JSON.stringify(session, null, 2));
+  return filename;
+}
+
+/**
+ * Load a session by ID.
+ */
+export function loadSession(sessionId, cwd = process.cwd()) {
+  const filePath = join(getSessionsDir(cwd), `${sessionId}.json`);
+  if (!existsSync(filePath)) return null;
+  return JSON.parse(readFileSync(filePath, 'utf-8'));
+}
+
+/**
+ * List all sessions, sorted by most recent.
+ */
+export function listSessions(cwd = process.cwd(), limit = 20) {
+  const dir = getSessionsDir(cwd);
+  if (!existsSync(dir)) return [];
+
+  return readdirSync(dir)
+    .filter(f => f.endsWith('.json'))
+    .map(f => {
+      try {
+        const data = JSON.parse(readFileSync(join(dir, f), 'utf-8'));
+        return data;
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => new Date(b.created) - new Date(a.created))
+    .slice(0, limit);
+}
+
+/**
+ * Create a new session object.
+ */
+export function createSession({ executor, reviewer, diff_ref, task }) {
+  return {
+    id: `review_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+    created: new Date().toISOString(),
+    status: 'in_progress',
+    executor,
+    reviewer,
+    diff_ref: diff_ref || null,
+    task: task || null,
+    iterations: [],
+    final_verdict: null,
+  };
+}

package/src/session/session-manager.test.js

@@ -0,0 +1,72 @@
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, rmSync } from 'fs';
+import { join } from 'path';
+import { createSession, saveSession, loadSession, listSessions } from './session-manager.js';
+
+const TMP = join(process.cwd(), '.test-tmp-sessions');
+
+describe('session-manager', () => {
+  beforeEach(() => {
+    mkdirSync(TMP, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(TMP, { recursive: true, force: true });
+  });
+
+  it('creates session with correct structure', () => {
+    const session = createSession({
+      executor: 'claude_code',
+      reviewer: 'codex',
+          });
+
+    assert.ok(session.id.startsWith('review_'));
+    assert.equal(session.status, 'in_progress');
+    assert.equal(session.executor, 'claude_code');
+    assert.equal(session.reviewer, 'codex');
+    assert.deepEqual(session.iterations, []);
+    assert.equal(session.final_verdict, null);
+  });
+
+  it('saves and loads session', () => {
+    const session = createSession({ executor: 'a', reviewer: 'b', depth: 1 });
+    saveSession(session, TMP);
+
+    const loaded = loadSession(session.id, TMP);
+    assert.equal(loaded.id, session.id);
+    assert.equal(loaded.executor, 'a');
+  });
+
+  it('lists sessions sorted by newest first', async () => {
+    const s1 = createSession({ executor: 'a', reviewer: 'b', depth: 1 });
+    s1.created = '2026-01-01T00:00:00Z';
+    saveSession(s1, TMP);
+
+    const s2 = createSession({ executor: 'a', reviewer: 'b', depth: 1 });
+    s2.created = '2026-03-01T00:00:00Z';
+    saveSession(s2, TMP);
+
+    const list = listSessions(TMP);
+    assert.equal(list.length, 2);
+    assert.equal(list[0].id, s2.id); // newest first
+  });
+
+  it('respects limit', () => {
+    for (let i = 0; i < 5; i++) {
+      saveSession(createSession({ executor: 'a', reviewer: 'b', depth: 1 }), TMP);
+    }
+    const list = listSessions(TMP, 3);
+    assert.equal(list.length, 3);
+  });
+
+  it('returns null for nonexistent session', () => {
+    assert.equal(loadSession('nonexistent', TMP), null);
+  });
+
+  it('returns empty array when no sessions dir', () => {
+    const empty = join(TMP, 'empty');
+    mkdirSync(empty, { recursive: true });
+    assert.deepEqual(listSessions(empty), []);
+  });
+});

package/src/tools/git-tools.js

@@ -0,0 +1,27 @@
+import { execFileSync } from 'child_process';
+
+/**
+ * Get the current git diff. Tries staged first, then unstaged.
+ * Returns empty string if no changes found.
+ */
+export function getDiff(ref) {
+  if (ref) {
+    return gitExec(['diff', ref]);
+  }
+
+  const staged = gitExec(['diff', '--cached']);
+  if (staged.trim()) return staged;
+
+  const unstaged = gitExec(['diff']);
+  if (unstaged.trim()) return unstaged;
+
+  return '';
+}
+
+function gitExec(args) {
+  try {
+    return execFileSync('git', args, { encoding: 'utf-8', maxBuffer: 5 * 1024 * 1024 });
+  } catch (e) {
+    throw new Error(`git ${args[0]} failed: ${e.message}`);
+  }
+}

package/src/tools/tool-runner.js

@@ -0,0 +1,47 @@
+import { execSync } from 'child_process';
+
+/**
+ * Run configured tool gates and return results.
+ * Uses explicit commands from config, or falls back to defaults.
+ */
+export function runToolGates(tools, cwd = process.cwd(), toolCommands = {}) {
+  const results = {};
+
+  for (const tool of tools) {
+    const cmd = toolCommands[tool];
+    switch (tool) {
+      case 'run_tests':
+        results.tests = runCommand(cmd || 'npm test', cwd);
+        break;
+      case 'run_lint':
+        results.lint = runCommand(cmd || 'npm run lint', cwd);
+        break;
+      case 'run_typecheck':
+        results.typecheck = runCommand(cmd || 'npx tsc --noEmit', cwd);
+        break;
+      default:
+        if (cmd) {
+          results[tool] = runCommand(cmd, cwd);
+        }
+        break;
+    }
+  }
+
+  return results;
+}
+
+function runCommand(cmd, cwd) {
+  try {
+    const output = execSync(cmd, {
+      cwd,
+      encoding: 'utf-8',
+      timeout: 120_000,
+      stdio: 'pipe',
+      shell: true,
+    });
+    return { passed: true, output: output.trim().slice(-500) || 'OK' };
+  } catch (e) {
+    const output = (e.stdout || '') + (e.stderr || '') || e.message;
+    return { passed: false, output: output.trim().slice(-500) };
+  }
+}