@jaimevalasek/aioson 1.6.0 → 1.7.0

package/src/commands/feature-close.js

@@ -0,0 +1,165 @@
+'use strict';
+
+/**
+ * aioson feature:close — close a feature after QA sign-off.
+ *
+ * Updates spec-{slug}.md (adds QA sign-off block), features.md (sets status to done),
+ * and project-pulse.md (removes from active work).
+ *
+ * Usage:
+ *   aioson feature:close . --feature=checkout --verdict=PASS
+ *   aioson feature:close . --feature=checkout --verdict=PASS --residual="Email delivery not tested E2E"
+ *   aioson feature:close . --feature=checkout --verdict=FAIL --notes="Auth edge case missing"
+ */
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { contextDir, readFileSafe, parseFrontmatter } = require('../preflight-engine');
+
+function nowDate() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+async function updateSpecFile(specPath, verdict, residual, date) {
+  const content = await readFileSafe(specPath);
+  if (!content) return false;
+
+  const signOff = [
+    '',
+    '## QA Sign-off',
+    '',
+    `- **Date:** ${date}`,
+    `- **Verdict:** ${verdict}`,
+    residual ? `- **Residual:** ${residual}` : null,
+    `- **Gate D (execution):** ${verdict === 'PASS' ? 'approved' : 'rejected'}`,
+    ''
+  ].filter((l) => l !== null).join('\n');
+
+  // Update gate_execution in frontmatter first (on original content)
+  const newStatus = verdict === 'PASS' ? 'approved' : 'rejected';
+  const fm = parseFrontmatter(content);
+  let baseContent = content;
+  if (Object.keys(fm).length > 0) {
+    baseContent = content.replace(
+      /^---\r?\n[\s\S]*?\r?\n---/,
+      (block) => {
+        if (block.includes('gate_execution')) {
+          return block.replace(/gate_execution:\s*.+/, `gate_execution: ${newStatus}`);
+        }
+        return block.replace(/^---\r?\n/, `---\ngate_execution: ${newStatus}\n`);
+      }
+    );
+  }
+
+  // Now apply QA sign-off on top of the frontmatter-updated content
+  if (baseContent.includes('## QA Sign-off')) {
+    const updated = baseContent.replace(
+      /## QA Sign-off[\s\S]*?(?=\n##|\s*$)/,
+      signOff.trimStart()
+    );
+    await fs.writeFile(specPath, updated, 'utf8');
+  } else {
+    await fs.writeFile(specPath, baseContent + signOff, 'utf8');
+  }
+
+  return true;
+}
+
+async function updateFeaturesFile(featuresPath, slug, verdict, date) {
+  const content = await readFileSafe(featuresPath);
+  if (!content) return false;
+
+  const status = verdict === 'PASS' ? 'done' : 'qa_failed';
+
+  // Try to find and update the feature row
+  const updated = content.replace(
+    new RegExp(`(\\|[^|]*${slug}[^|]*\\|[^|]*\\|)[^|]*(\\|)`, 'g'),
+    (match, before, after) => `${before} ${status} (${date}) ${after}`
+  );
+
+  if (updated !== content) {
+    await fs.writeFile(featuresPath, updated, 'utf8');
+    return true;
+  }
+
+  // Append if not found
+  const line = `| ${slug} | ${verdict === 'PASS' ? 'done' : 'qa_failed'} | ${date} | QA ${verdict} |`;
+  await fs.appendFile(featuresPath, `\n${line}\n`, 'utf8');
+  return true;
+}
+
+async function runFeatureClose({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const slug = options.feature ? String(options.feature) : null;
+  const verdict = options.verdict ? String(options.verdict).toUpperCase() : null;
+  const residual = options.residual ? String(options.residual) : null;
+  const notes = options.notes ? String(options.notes) : null;
+
+  if (!slug) {
+    if (options.json) return { ok: false, reason: 'missing_feature' };
+    logger.log('--feature=<slug> is required.');
+    return { ok: false };
+  }
+
+  if (!verdict || !['PASS', 'FAIL'].includes(verdict)) {
+    if (options.json) return { ok: false, reason: 'invalid_verdict' };
+    logger.log('--verdict=PASS or --verdict=FAIL is required.');
+    return { ok: false };
+  }
+
+  const today = nowDate();
+  const dir = contextDir(targetDir);
+  const updates = [];
+
+  // 1. Update spec file
+  const specPath = path.join(dir, `spec-${slug}.md`);
+  const specUpdated = await updateSpecFile(specPath, verdict, residual || notes, today);
+  if (specUpdated) {
+    updates.push(`spec-${slug}.md: added QA sign-off (${today}, ${verdict})`);
+  } else {
+    updates.push(`spec-${slug}.md: not found (skipped)`);
+  }
+
+  // 2. Update features.md
+  const featuresPath = path.join(dir, 'features.md');
+  const featuresContent = await readFileSafe(featuresPath);
+  if (featuresContent) {
+    await updateFeaturesFile(featuresPath, slug, verdict, today);
+    updates.push(`features.md: ${slug} → ${verdict === 'PASS' ? 'done' : 'qa_failed'} (${today})`);
+  } else {
+    updates.push('features.md: not found (skipped)');
+  }
+
+  // 3. Update project-pulse.md
+  const pulsePath = path.join(dir, 'project-pulse.md');
+  const pulseContent = await readFileSafe(pulsePath);
+  if (pulseContent) {
+    const fm = parseFrontmatter(pulseContent);
+    const status = verdict === 'PASS' ? 'closed' : 'qa_failed';
+    const updatedPulse = pulseContent
+      .replace(/active_feature:\s*.+/, `active_feature: (none)`)
+      .replace(/active_work:\s*".+"/, `active_work: ""`)
+      .replace(/last_agent:\s*.+/, `last_agent: qa`)
+      .replace(/last_gate:\s*.+/, `last_gate: Gate D: ${verdict === 'PASS' ? 'approved' : 'rejected'}`);
+    await fs.writeFile(pulsePath, updatedPulse, 'utf8');
+    updates.push('project-pulse.md: updated active work');
+  }
+
+  const result = {
+    ok: true,
+    feature: slug,
+    verdict,
+    date: today,
+    residual: residual || notes || null,
+    updates
+  };
+
+  if (options.json) return result;
+
+  logger.log(`Feature closure — ${slug}:`);
+  for (const u of updates) logger.log(`  ${u}`);
+
+  return result;
+}
+
+module.exports = { runFeatureClose };

package/src/commands/gate-check.js

@@ -0,0 +1,228 @@
+'use strict';
+
+/**
+ * aioson gate:check — check if a phase gate is approved for a feature.
+ *
+ * Reads spec-{slug}.md frontmatter and artifact chain to verify gate status.
+ * Returns PASS or BLOCKED with evidence. No LLM calls.
+ *
+ * Usage:
+ *   aioson gate:check . --feature=checkout --gate=C
+ *   aioson gate:check . --feature=checkout --gate=D
+ *   aioson gate:check . --feature=checkout --gate=C --json
+ */
+
+const path = require('node:path');
+const {
+  contextDir,
+  readFileSafe,
+  fileExists,
+  parseGatesFromSpec,
+  parseFrontmatter,
+  GATE_NAMES,
+  GATE_ALIASES
+} = require('../preflight-engine');
+
+const BAR = '━'.repeat(35);
+
+const GATE_PREREQUISITES = {
+  A: [],
+  B: ['A'],
+  C: ['A', 'B'],
+  D: ['A', 'B', 'C']
+};
+
+const GATE_REQUIRED_ARTIFACTS = {
+  A: (slug) => [`requirements-${slug}.md`],
+  B: (slug) => ['architecture.md'],
+  C: (slug) => [`implementation-plan-${slug}.md`],
+  D: (slug) => [] // Gate D validated by QA sign-off in spec
+};
+
+const GATE_DESCRIPTIONS = {
+  A: 'requirements',
+  B: 'design',
+  C: 'plan',
+  D: 'execution'
+};
+
+async function checkGate(targetDir, slug, gateLetter) {
+  const dir = contextDir(targetDir);
+  const specFile = path.join(dir, `spec-${slug}.md`);
+  const specContent = await readFileSafe(specFile);
+  const gates = specContent ? parseGatesFromSpec(specContent) : {};
+  const fm = specContent ? parseFrontmatter(specContent) : {};
+
+  const gateName = GATE_NAMES[gateLetter];
+  const gateStatus = gates[gateName] || 'pending';
+  const prerequisites = GATE_PREREQUISITES[gateLetter] || [];
+
+  const evidence = [];
+  const missing = [];
+
+  // Check prerequisites
+  for (const prereq of prerequisites) {
+    const prereqName = GATE_NAMES[prereq];
+    const prereqStatus = gates[prereqName] || 'pending';
+    if (prereqStatus === 'approved') {
+      evidence.push({ type: 'prereq', gate: prereq, name: prereqName, status: 'approved', ok: true });
+    } else {
+      evidence.push({ type: 'prereq', gate: prereq, name: prereqName, status: prereqStatus, ok: false });
+      missing.push(`Gate ${prereq} (${prereqName}) not approved: ${prereqStatus}`);
+    }
+  }
+
+  // Check required artifacts
+  const requiredFiles = GATE_REQUIRED_ARTIFACTS[gateLetter](slug);
+  for (const fileName of requiredFiles) {
+    const filePath = path.join(dir, fileName);
+    const exists = await fileExists(filePath);
+    if (exists) {
+      let detail = null;
+      const content = await readFileSafe(filePath);
+      if (content) {
+        const fileFm = parseFrontmatter(content);
+        if (fileFm.status) detail = `status: ${fileFm.status}`;
+      }
+      evidence.push({ type: 'artifact', file: fileName, exists: true, detail, ok: true });
+    } else {
+      evidence.push({ type: 'artifact', file: fileName, exists: false, ok: false });
+      missing.push(`${fileName} not found`);
+    }
+  }
+
+  // Gate D: check for QA sign-off in spec
+  if (gateLetter === 'D') {
+    if (specContent && specContent.includes('## QA Sign-off')) {
+      // Check verdict
+      const passMatch = specContent.match(/\*\*Verdict:\*\*\s*(PASS|FAIL)/i);
+      const passVerdict = passMatch ? passMatch[1].toUpperCase() : null;
+      if (passVerdict === 'PASS') {
+        evidence.push({ type: 'qa_signoff', verdict: 'PASS', ok: true });
+      } else if (passVerdict === 'FAIL') {
+        evidence.push({ type: 'qa_signoff', verdict: 'FAIL', ok: false });
+        missing.push('QA sign-off verdict: FAIL');
+      } else {
+        evidence.push({ type: 'qa_signoff', verdict: null, ok: false });
+        missing.push('QA sign-off found but verdict unclear');
+      }
+    } else {
+      // Check spec last_checkpoint for completion indicators
+      const checkpoint = fm.last_checkpoint || '';
+      if (checkpoint.toLowerCase().includes('complet') || checkpoint.toLowerCase().includes('done')) {
+        evidence.push({ type: 'checkpoint', value: checkpoint, ok: true });
+      } else {
+        evidence.push({ type: 'qa_signoff', exists: false, ok: false });
+        missing.push('No QA sign-off in spec file');
+      }
+    }
+
+    // Also check spec version for explicit gate_execution
+    if (gates.execution && gates.execution !== 'pending') {
+      const gateD = gates.execution;
+      evidence.push({ type: 'gate_field', field: 'gate_execution', value: gateD, ok: gateD === 'approved' });
+      if (gateD !== 'approved') missing.push(`gate_execution: ${gateD}`);
+    }
+  }
+
+  const allOk = missing.length === 0;
+  const result = allOk ? 'PASS' : 'BLOCKED';
+
+  let recommendation = '';
+  if (result === 'PASS') {
+    const nextAgents = { A: '@architect', B: '@dev or @pm', C: '@dev', D: 'feature complete' };
+    recommendation = `${nextAgents[gateLetter] || 'proceed'} can proceed`;
+  } else {
+    const fixAgents = { A: 'complete requirements (@analyst)', B: 'complete design (@architect)', C: 'approve implementation plan', D: 'complete implementation and run @qa' };
+    recommendation = `BLOCKED — ${fixAgents[gateLetter] || 'resolve missing items'} first`;
+  }
+
+  return {
+    gate: gateLetter,
+    gate_name: gateName,
+    feature: slug,
+    status: gateStatus,
+    result,
+    evidence,
+    missing,
+    recommendation
+  };
+}
+
+async function runGateCheck({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const slug = options.feature ? String(options.feature) : null;
+  let gateLetter = options.gate ? String(options.gate).toUpperCase() : null;
+
+  if (!slug) {
+    if (options.json) return { ok: false, reason: 'missing_feature' };
+    logger.log('--feature=<slug> is required.');
+    return { ok: false };
+  }
+
+  if (!gateLetter) {
+    if (options.json) return { ok: false, reason: 'missing_gate' };
+    logger.log('--gate=<A|B|C|D> is required.');
+    return { ok: false };
+  }
+
+  // Allow gate name aliases (requirements → A, etc.)
+  if (GATE_ALIASES[gateLetter.toLowerCase()]) {
+    gateLetter = GATE_ALIASES[gateLetter.toLowerCase()];
+  }
+
+  if (!GATE_NAMES[gateLetter]) {
+    if (options.json) return { ok: false, reason: 'invalid_gate', gate: gateLetter };
+    logger.log(`Invalid gate: ${gateLetter}. Use A, B, C, or D.`);
+    return { ok: false };
+  }
+
+  const check = await checkGate(targetDir, slug, gateLetter);
+
+  const result = { ok: check.result === 'PASS', ...check };
+
+  if (options.json) return result;
+
+  logger.log('');
+  logger.log(`Gate ${gateLetter} (${check.gate_name}) — ${slug}`);
+  logger.log(BAR);
+  logger.log(`Status: ${check.status}`);
+
+  const prereqs = check.evidence.filter((e) => e.type === 'prereq');
+  if (prereqs.length > 0) {
+    logger.log('Prerequisites met:');
+    for (const p of prereqs) {
+      const icon = p.ok ? '  ✓' : '  ✗';
+      logger.log(`${icon} Gate ${p.gate} (${p.name}): ${p.status}`);
+    }
+  }
+
+  const artifacts = check.evidence.filter((e) => e.type === 'artifact');
+  if (artifacts.length > 0) {
+    logger.log('Artifacts:');
+    for (const a of artifacts) {
+      const icon = a.ok ? '  ✓' : '  ✗';
+      const detail = a.detail ? ` (${a.detail})` : '';
+      logger.log(`${icon} ${a.file}${a.ok ? ' exists' : ' missing'}${detail}`);
+    }
+  }
+
+  const qaEvidence = check.evidence.filter((e) => e.type === 'qa_signoff' || e.type === 'checkpoint' || e.type === 'gate_field');
+  if (qaEvidence.length > 0) {
+    for (const q of qaEvidence) {
+      const icon = q.ok ? '  ✓' : '  ✗';
+      if (q.type === 'qa_signoff') logger.log(`${icon} QA sign-off: ${q.exists === false ? 'missing' : `verdict ${q.verdict || 'unclear'}`}`);
+      if (q.type === 'checkpoint') logger.log(`  ✓ last_checkpoint: "${q.value}"`);
+      if (q.type === 'gate_field') logger.log(`${icon} gate_execution: ${q.value}`);
+    }
+  }
+
+  logger.log('');
+  const resultIcon = check.result === 'PASS' ? '✓' : '✗';
+  logger.log(`Result: ${resultIcon} ${check.result} — ${check.recommendation}`);
+  logger.log('');
+
+  return result;
+}
+
+module.exports = { runGateCheck };

package/src/commands/hooks-emit.js

@@ -0,0 +1,253 @@
+'use strict';
+
+/**
+ * aioson hooks:emit [projectDir] --agent=<name> --source=<tool>
+ *
+ * Called by Claude Code / Antigravity / Codex hooks on every tool use.
+ * Reads the hook payload from stdin (JSON), maps it to an AIOSON runtime event,
+ * and writes it to the active live session in SQLite + events.ndjson.
+ *
+ * If no live session exists, auto-starts one (--no-launch mode) before emitting.
+ *
+ * Designed to be fast (< 50ms hot path) and never block the agent.
+ */
+
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const { execFileSync } = require('node:child_process');
+const {
+  openRuntimeDb,
+  resolveRuntimePaths,
+  readAgentSession,
+  appendRunEvent,
+  startTask,
+  startRun,
+  writeAgentSession
+} = require('../runtime-store');
+
+const HOOKS_EMIT_VERSION = '1';
+
+// Tool name → event_type mapping
+const TOOL_EVENT_MAP = {
+  Write: 'artifact',
+  Edit: 'artifact',
+  MultiEdit: 'artifact',
+  Bash: 'step_done',
+  Task: 'note',
+  TodoWrite: 'note',
+  WebSearch: 'note',
+  WebFetch: 'note'
+};
+
+// Tools to skip — too noisy, no meaningful event
+const SKIP_TOOLS = new Set(['Read', 'Glob', 'Grep', 'LS', 'NotebookRead', 'mcp__']);
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    if (process.stdin.isTTY) { resolve(null); return; }
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => {
+      try { resolve(JSON.parse(data)); }
+      catch { resolve(null); }
+    });
+    // Timeout: don't block if stdin is empty
+    setTimeout(() => resolve(null), 500);
+  });
+}
+
+function buildEventFromPayload(payload, source) {
+  if (!payload) return null;
+
+  const toolName = payload.tool_name || payload.toolName || null;
+  if (!toolName) return null;
+
+  // Skip noisy read-only tools
+  if (SKIP_TOOLS.has(toolName) || [...SKIP_TOOLS].some((p) => toolName.startsWith(p))) {
+    return null;
+  }
+
+  const eventType = TOOL_EVENT_MAP[toolName] || 'note';
+  const input = payload.tool_input || payload.toolInput || {};
+
+  let message = `[${source}] ${toolName}`;
+  let filePath = null;
+
+  if (toolName === 'Write' || toolName === 'Edit' || toolName === 'MultiEdit') {
+    filePath = input.file_path || input.path || null;
+    message = filePath ? `${toolName}: ${path.basename(filePath)}` : `${toolName}`;
+  } else if (toolName === 'Bash') {
+    const cmd = String(input.command || input.cmd || '').trim().slice(0, 80);
+    message = cmd ? `$ ${cmd}` : 'Bash';
+  } else if (toolName === 'Task') {
+    const desc = String(input.description || input.prompt || '').slice(0, 80);
+    message = desc || 'Task launched';
+  } else if (toolName === 'TodoWrite') {
+    message = 'Task list updated';
+  }
+
+  return {
+    eventType,
+    message,
+    filePath,
+    toolName,
+    sessionId: payload.session_id || payload.sessionId || null
+  };
+}
+
+async function ensureOrCreateLiveSession(targetDir, agentName, source, runtimeDir) {
+  // Fast path: check existing session file
+  const session = await readAgentSession(runtimeDir, agentName);
+  if (session && !session.finished && session.source === 'live' && session.runKey) {
+    return session.runKey;
+  }
+
+  // No session — auto-start one inline (no-launch mode)
+  const now = nowIso();
+  const sessionKey = `hooks-${agentName}-${Date.now()}`;
+  const title = `[hooks] ${agentName} via ${source}`;
+
+  const { db } = await openRuntimeDb(targetDir);
+  try {
+    const taskKey = startTask(db, {
+      sessionKey,
+      title,
+      status: 'running',
+      createdBy: agentName,
+      taskKind: 'live_session',
+      metaJson: { tool_session: source, path: targetDir, auto_started: true }
+    });
+
+    const runKey = startRun(db, {
+      taskKey,
+      agentName,
+      agentKind: 'official',
+      sessionKey,
+      source: 'live',
+      title,
+      eventType: 'session_started',
+      phase: 'live',
+      message: `Auto-started by hooks:emit (${source})`,
+      payload: { tool_session: source, path: targetDir, hooks_version: HOOKS_EMIT_VERSION }
+    });
+
+    await writeAgentSession(runtimeDir, agentName, {
+      runKey,
+      taskKey,
+      sessionKey,
+      startedAt: now,
+      finished: false,
+      source: 'live'
+    });
+
+    // Write state.json for dashboard live view
+    const stateDir = path.join(runtimeDir, 'live', sessionKey);
+    await fs.mkdir(stateDir, { recursive: true });
+    await fs.writeFile(path.join(stateDir, 'state.json'), JSON.stringify({
+      session_key: sessionKey,
+      run_key: runKey,
+      task_key: taskKey,
+      agent_name: agentName,
+      tool_session: source,
+      status: 'running',
+      started_at: now,
+      updated_at: now,
+      auto_started: true,
+      last_events: [{ ts: now, type: 'session_started', summary: `Auto-started by hooks:emit (${source})` }]
+    }, null, 2), 'utf8');
+
+    return runKey;
+  } finally {
+    db.close();
+  }
+}
+
+async function appendLiveEventFile(runtimeDir, runKey, event) {
+  // Find the session dir for this runKey
+  try {
+    const liveRoot = path.join(runtimeDir, 'live');
+    const entries = await fs.readdir(liveRoot).catch(() => []);
+    for (const entry of entries) {
+      const statePath = path.join(liveRoot, entry, 'state.json');
+      try {
+        const state = JSON.parse(await fs.readFile(statePath, 'utf8'));
+        if (state.run_key === runKey) {
+          const eventsPath = path.join(liveRoot, entry, 'events.ndjson');
+          await fs.appendFile(eventsPath, JSON.stringify(event) + '\n', 'utf8');
+
+          // Update state.json updated_at + last_events
+          state.updated_at = event.ts;
+          const lastEvents = state.last_events || [];
+          lastEvents.push({ ts: event.ts, type: event.type, summary: event.summary || event.message });
+          state.last_events = lastEvents.slice(-10); // keep last 10
+          await fs.writeFile(statePath, JSON.stringify(state, null, 2), 'utf8');
+          break;
+        }
+      } catch { /* skip */ }
+    }
+  } catch { /* non-fatal */ }
+}
+
+async function runHooksEmit({ args, options = {} }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const agentName = options.agent ? String(options.agent).replace(/^@/, '') : 'dev';
+  const source = options.source ? String(options.source).trim() : 'claude';
+
+  // Silence all output — hooks must be silent
+  const logger = { log: () => {}, error: () => {} };
+
+  try {
+    const { runtimeDir } = resolveRuntimePaths(targetDir);
+
+    // Read hook payload from stdin
+    const payload = await readStdin();
+    const event = buildEventFromPayload(payload, source);
+
+    // Skip if no meaningful event (read-only tools, etc.)
+    if (!event) return { ok: true, skipped: true };
+
+    const now = nowIso();
+
+    // Ensure live session exists (fast path: session file read)
+    const runKey = await ensureOrCreateLiveSession(targetDir, agentName, source, runtimeDir);
+
+    // Write to SQLite
+    const { db } = await openRuntimeDb(targetDir, { mustExist: true });
+    try {
+      appendRunEvent(db, {
+        runKey,
+        eventType: event.eventType,
+        phase: 'live',
+        status: 'running',
+        message: event.message,
+        payload: event.filePath ? { file: event.filePath, tool: event.toolName } : { tool: event.toolName },
+        createdAt: now
+      });
+    } finally {
+      db.close();
+    }
+
+    // Append to events.ndjson for real-time dashboard view
+    await appendLiveEventFile(runtimeDir, runKey, {
+      ts: now,
+      type: event.eventType,
+      message: event.message,
+      tool: event.toolName,
+      file: event.filePath || undefined,
+      source,
+      agent: agentName
+    });
+
+    return { ok: true, runKey, event: event.eventType, message: event.message };
+  } catch {
+    // Never fail — hooks must not block the agent
+    return { ok: false };
+  }
+}
+
+module.exports = { runHooksEmit };