@agile-vibe-coding/avc 0.1.1 → 0.2.3

package/cli/build-docs.js

@@ -25,6 +25,13 @@ export class DocumentationBuilder {
     return fs.existsSync(this.docsDir);
   }
 
+  /**
+   * Check if synced project docs directory exists inside documentation
+   */
+  hasProjectDocs() {
+    return fs.existsSync(path.join(this.docsDir, 'project'));
+  }
+
   /**
    * Get documentation server port from avc.json config
    * Returns default port 4173 if not configured
@@ -40,7 +47,7 @@ export class DocumentationBuilder {
       const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
       return config.settings?.documentation?.port || 4173;
     } catch (error) {
-      console.warn(`⚠️  Could not read port from avc.json: ${error.message}`);
+      console.warn(`Could not read port from avc.json: ${error.message}`);
       return 4173;
     }
   }
@@ -197,13 +204,9 @@ export class DocumentationBuilder {
     const port = this.getPort();
 
     try {
-      // Build the documentation asynchronously to avoid blocking
-      await execAsync('npx vitepress build', {
-        cwd: this.docsDir
-      });
-
-      // Start the preview server
-      const serverProcess = spawn('npx', ['vitepress', 'preview', '--port', String(port)], {
+      // Start the dev server — no initial build needed, vitepress dev builds on-demand
+      // and hot-reloads the browser whenever source .md files change
+      const serverProcess = spawn('npx', ['vitepress', 'dev', '--port', String(port)], {
         cwd: this.docsDir,
         stdio: 'pipe'
       });
@@ -256,6 +259,22 @@ export class DocumentationBuilder {
     }
   }
 
+  /**
+   * Ensure ignoreDeadLinks: true is present in the VitePress config.
+   * Patches existing project configs that were created before this option was added.
+   */
+  _ensureIgnoreDeadLinks() {
+    const configPath = path.join(this.docsDir, '.vitepress', 'config.mts');
+    if (!fs.existsSync(configPath)) return;
+    const content = fs.readFileSync(configPath, 'utf8');
+    if (content.includes('ignoreDeadLinks')) return;
+    const patched = content.replace(
+      /defineConfig\(\{/,
+      'defineConfig({\n  ignoreDeadLinks: true,'
+    );
+    fs.writeFileSync(configPath, patched, 'utf8');
+  }
+
   /**
    * Build documentation without starting server
    */
@@ -264,6 +283,8 @@ export class DocumentationBuilder {
       throw new Error('Documentation not found. Run /init first to create documentation structure.');
     }
 
+    this._ensureIgnoreDeadLinks();
+
     try {
       // Build asynchronously to avoid blocking the event loop
       await execAsync('npx vitepress build', {

package/cli/ceremony-history.js

@@ -0,0 +1,369 @@
+/**
+ * Ceremony History Tracker - Records all ceremony executions with status and metadata
+ *
+ * Tracks when ceremonies are run, their outcomes, and preserves historical data.
+ * Helps detect abrupt terminations and provides audit trail.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+export class CeremonyHistory {
+  constructor(avcPath = path.join(process.cwd(), '.avc')) {
+    this.avcPath = avcPath;
+    this.historyPath = path.join(avcPath, 'ceremonies-history.json');
+    this.data = null;
+  }
+
+  /**
+   * Initialize ceremony history file if it doesn't exist
+   */
+  init() {
+    // Ensure .avc directory exists
+    if (!fs.existsSync(this.avcPath)) {
+      fs.mkdirSync(this.avcPath, { recursive: true });
+    }
+
+    if (!fs.existsSync(this.historyPath)) {
+      const initialData = {
+        version: "1.0",
+        lastUpdated: new Date().toISOString(),
+        ceremonies: {}
+      };
+      this._writeData(initialData);
+    }
+  }
+
+  /**
+   * Load ceremony history from disk
+   */
+  load() {
+    if (fs.existsSync(this.historyPath)) {
+      this.data = JSON.parse(fs.readFileSync(this.historyPath, 'utf8'));
+    } else {
+      this.init();
+      this.data = JSON.parse(fs.readFileSync(this.historyPath, 'utf8'));
+    }
+    return this.data;
+  }
+
+  /**
+   * Write data to disk atomically
+   */
+  _writeData(data) {
+    try {
+      const tempPath = this.historyPath + '.tmp';
+      fs.writeFileSync(tempPath, JSON.stringify(data, null, 2), 'utf8');
+      fs.renameSync(tempPath, this.historyPath);
+    } catch (error) {
+      // Fallback to direct write if atomic write fails
+      try {
+        fs.writeFileSync(this.historyPath, JSON.stringify(data, null, 2), 'utf8');
+      } catch (fallbackError) {
+        console.error(`Failed to write ceremony history: ${fallbackError.message}`);
+        console.error(`Path: ${this.historyPath}`);
+        throw fallbackError;
+      }
+    }
+  }
+
+  /**
+   * Start a new ceremony execution
+   * @param {string} ceremonyName - e.g., 'sponsor-call'
+   * @param {string} stage - Initial stage (default: 'questionnaire')
+   * @returns {string} Execution ID
+   */
+  startExecution(ceremonyName, stage = 'questionnaire') {
+    this.load();
+
+    const now = new Date();
+    const timestamp = now.toISOString()
+      .replace(/T/, '-')
+      .replace(/:/g, '-')
+      .replace(/\..+/, '');
+
+    const executionId = `${ceremonyName}-${timestamp}`;
+
+    // Initialize ceremony entry if doesn't exist
+    if (!this.data.ceremonies[ceremonyName]) {
+      this.data.ceremonies[ceremonyName] = {
+        executions: [],
+        totalExecutions: 0,
+        lastRun: null,
+        lastSuccess: null
+      };
+    }
+
+    // Create execution record
+    const execution = {
+      id: executionId,
+      startTime: now.toISOString(),
+      endTime: null,
+      status: 'in-progress',
+      stage: stage,
+      answers: null,
+      filesGenerated: [],
+      tokenUsage: null,
+      duration: null,
+      outcome: null
+    };
+
+    // Add to executions array
+    this.data.ceremonies[ceremonyName].executions.push(execution);
+    this.data.ceremonies[ceremonyName].lastRun = now.toISOString();
+    this.data.lastUpdated = now.toISOString();
+
+    this._writeData(this.data);
+
+    return executionId;
+  }
+
+  /**
+   * Update an existing execution
+   * @param {string} ceremonyName - Ceremony name
+   * @param {string} executionId - Execution ID
+   * @param {Object} updates - Fields to update
+   */
+  updateExecution(ceremonyName, executionId, updates) {
+    this.load();
+
+    if (!this.data.ceremonies[ceremonyName]) {
+      throw new Error(`Ceremony '${ceremonyName}' not found in history`);
+    }
+
+    const execution = this.data.ceremonies[ceremonyName].executions.find(
+      e => e.id === executionId
+    );
+
+    if (!execution) {
+      throw new Error(`Execution '${executionId}' not found for ceremony '${ceremonyName}'`);
+    }
+
+    // Update fields
+    Object.assign(execution, updates);
+    this.data.lastUpdated = new Date().toISOString();
+
+    this._writeData(this.data);
+  }
+
+  /**
+   * Complete an execution
+   * @param {string} ceremonyName - Ceremony name
+   * @param {string} executionId - Execution ID
+   * @param {string} outcome - 'success', 'user-cancelled', or 'abrupt-termination'
+   * @param {Object} metadata - Additional data (answers, filesGenerated, tokenUsage, etc.)
+   */
+  completeExecution(ceremonyName, executionId, outcome, metadata = {}) {
+    this.load();
+
+    if (!this.data.ceremonies[ceremonyName]) {
+      throw new Error(`Ceremony '${ceremonyName}' not found in history`);
+    }
+
+    const execution = this.data.ceremonies[ceremonyName].executions.find(
+      e => e.id === executionId
+    );
+
+    if (!execution) {
+      throw new Error(`Execution '${executionId}' not found for ceremony '${ceremonyName}'`);
+    }
+
+    const now = new Date();
+    const startTime = new Date(execution.startTime);
+    const duration = now - startTime;
+
+    // Determine status based on outcome
+    let status;
+    switch (outcome) {
+      case 'success':
+        status = 'completed';
+        break;
+      case 'user-cancelled':
+        status = 'cancelled';
+        break;
+      case 'abrupt-termination':
+        status = 'aborted';
+        break;
+      default:
+        status = 'completed';
+    }
+
+    // Update execution
+    execution.status = status;
+    execution.endTime = now.toISOString();
+    execution.outcome = outcome;
+    execution.duration = duration;
+
+    // Merge metadata
+    if (metadata.answers) execution.answers = metadata.answers;
+    if (metadata.filesGenerated) execution.filesGenerated = metadata.filesGenerated;
+    if (metadata.tokenUsage) execution.tokenUsage = metadata.tokenUsage;
+    if (metadata.cost) execution.cost = metadata.cost;
+    if (metadata.model) execution.model = metadata.model;
+    if (metadata.stage) execution.stage = metadata.stage;
+    if (metadata.error) execution.error = metadata.error;
+    if (metadata.note) execution.note = metadata.note;
+
+    // Update ceremony totals
+    this.data.ceremonies[ceremonyName].totalExecutions =
+      this.data.ceremonies[ceremonyName].executions.length;
+
+    if (outcome === 'success') {
+      this.data.ceremonies[ceremonyName].lastSuccess = now.toISOString();
+    }
+
+    this.data.lastUpdated = now.toISOString();
+
+    this._writeData(this.data);
+  }
+
+  /**
+   * Archive answers to an execution (before LLM generation starts)
+   * @param {string} ceremonyName - Ceremony name
+   * @param {string} executionId - Execution ID
+   * @param {Object} answers - Questionnaire answers
+   */
+  archiveAnswers(ceremonyName, executionId, answers) {
+    this.updateExecution(ceremonyName, executionId, {
+      answers: { ...answers }
+    });
+  }
+
+  /**
+   * Get the most recent execution for a ceremony
+   * @param {string} ceremonyName - Ceremony name
+   * @returns {Object|null} Execution record or null
+   */
+  getLastExecution(ceremonyName) {
+    this.load();
+
+    if (!this.data.ceremonies[ceremonyName]) {
+      return null;
+    }
+
+    const executions = this.data.ceremonies[ceremonyName].executions;
+    if (executions.length === 0) {
+      return null;
+    }
+
+    // Return most recent (last in array)
+    return executions[executions.length - 1];
+  }
+
+  /**
+   * Get a specific execution by ID
+   * @param {string} ceremonyName - Ceremony name
+   * @param {string} executionId - Execution ID
+   * @returns {Object|null} Execution record or null
+   */
+  getExecutionById(ceremonyName, executionId) {
+    this.load();
+
+    if (!this.data.ceremonies[ceremonyName]) {
+      return null;
+    }
+
+    return this.data.ceremonies[ceremonyName].executions.find(
+      e => e.id === executionId
+    ) || null;
+  }
+
+  /**
+   * Get all executions for a ceremony
+   * @param {string} ceremonyName - Ceremony name
+   * @returns {Array} Array of execution records (newest first)
+   */
+  getAllExecutions(ceremonyName) {
+    this.load();
+
+    if (!this.data.ceremonies[ceremonyName]) {
+      return [];
+    }
+
+    // Return copy, sorted by startTime descending
+    return [...this.data.ceremonies[ceremonyName].executions]
+      .sort((a, b) => new Date(b.startTime) - new Date(a.startTime));
+  }
+
+  /**
+   * Detect if the last execution was abruptly terminated
+   * @param {string} ceremonyName - Ceremony name
+   * @returns {boolean} True if abrupt termination detected
+   */
+  detectAbruptTermination(ceremonyName) {
+    const lastExecution = this.getLastExecution(ceremonyName);
+
+    if (!lastExecution) {
+      return false;
+    }
+
+    // Check if last execution is still in-progress and in LLM generation stage
+    return lastExecution.status === 'in-progress' &&
+           lastExecution.stage === 'llm-generation';
+  }
+
+  /**
+   * Clean up abrupt termination (mark as aborted)
+   * @param {string} ceremonyName - Ceremony name
+   */
+  cleanupAbruptTermination(ceremonyName) {
+    const lastExecution = this.getLastExecution(ceremonyName);
+
+    if (!lastExecution || lastExecution.status !== 'in-progress') {
+      return;
+    }
+
+    this.completeExecution(ceremonyName, lastExecution.id, 'abrupt-termination', {
+      note: 'Process was interrupted during LLM generation',
+      stage: lastExecution.stage
+    });
+  }
+
+  /**
+   * Get ceremony statistics
+   * @param {string} ceremonyName - Ceremony name
+   * @returns {Object} Statistics object
+   */
+  getStats(ceremonyName) {
+    this.load();
+
+    if (!this.data.ceremonies[ceremonyName]) {
+      return {
+        totalExecutions: 0,
+        successful: 0,
+        cancelled: 0,
+        aborted: 0,
+        lastRun: null,
+        lastSuccess: null
+      };
+    }
+
+    const ceremony = this.data.ceremonies[ceremonyName];
+    const executions = ceremony.executions;
+
+    return {
+      totalExecutions: ceremony.totalExecutions,
+      successful: executions.filter(e => e.outcome === 'success').length,
+      cancelled: executions.filter(e => e.outcome === 'user-cancelled').length,
+      aborted: executions.filter(e => e.outcome === 'abrupt-termination').length,
+      lastRun: ceremony.lastRun,
+      lastSuccess: ceremony.lastSuccess
+    };
+  }
+
+  /**
+   * Check if a ceremony has completed successfully at least once
+   * @param {string} ceremonyName - Ceremony name
+   * @returns {boolean} True if ceremony has a successful completion
+   */
+  hasSuccessfulCompletion(ceremonyName) {
+    this.load();
+
+    if (!this.data.ceremonies[ceremonyName]) {
+      return false;
+    }
+
+    // Check if lastSuccess is set (indicates at least one successful execution)
+    return this.data.ceremonies[ceremonyName].lastSuccess !== null;
+  }
+}

package/cli/command-logger.js

@@ -11,15 +11,27 @@
 import fs from 'fs';
 import path from 'path';
 
+/** Format a Date as a local ISO-8601 string (with timezone offset, e.g. 2026-03-04T18:05:16.554+01:00) */
+function localISO(date = new Date()) {
+  const p = n => String(n).padStart(2, '0');
+  const ms = String(date.getMilliseconds()).padStart(3, '0');
+  const tz = -date.getTimezoneOffset();
+  const sign = tz >= 0 ? '+' : '-';
+  const tzH = p(Math.floor(Math.abs(tz) / 60));
+  const tzM = p(Math.abs(tz) % 60);
+  return `${date.getFullYear()}-${p(date.getMonth()+1)}-${p(date.getDate())}T${p(date.getHours())}:${p(date.getMinutes())}:${p(date.getSeconds())}.${ms}${sign}${tzH}:${tzM}`;
+}
+
 class CommandLogger {
-  constructor(commandName, projectRoot = process.cwd()) {
+  constructor(commandName, projectRoot = process.cwd(), inkMode = false) {
     this.commandName = commandName;
     this.projectRoot = projectRoot;
     this.logsDir = path.join(projectRoot, '.avc', 'logs');
+    this.inkMode = inkMode; // Don't forward to console if in Ink mode
 
     // Create timestamp for this command execution
     const now = new Date();
-    const timestamp = now.toISOString()
+    const timestamp = localISO(now)
       .replace(/T/, '-')
       .replace(/:/g, '-')
       .replace(/\..+/, '');
@@ -54,7 +66,7 @@ class CommandLogger {
       const header = [
         '='.repeat(80),
         `AVC Command Log: ${this.commandName}`,
-        `Timestamp: ${new Date().toISOString()}`,
+        `Timestamp: ${localISO()}`,
         `Project: ${this.projectRoot}`,
         `Log File: ${this.logFileName}`,
         '='.repeat(80),
@@ -75,19 +87,32 @@ class CommandLogger {
     if (!this.logFilePath) return;
 
     try {
-      const timestamp = new Date().toISOString();
+      const timestamp = localISO();
       const message = args.map(arg => {
+        if (arg === undefined) return 'undefined';
+        if (arg === null) return 'null';
         if (typeof arg === 'object') {
-          return JSON.stringify(arg, null, 2);
+          try {
+            // Handle circular references and non-serializable objects
+            return JSON.stringify(arg, (key, value) => {
+              if (typeof value === 'function') return '[Function]';
+              if (typeof value === 'symbol') return value.toString();
+              return value;
+            }, 2);
+          } catch (jsonError) {
+            return `[Object: ${arg.constructor?.name || 'Unknown'}]`;
+          }
         }
         return String(arg);
       }).join(' ');
 
-      const logEntry = `[${timestamp}] [${level}] ${message}\n`;
+      // Preserve formatting but ensure single newline at end
+      const logEntry = `[${timestamp}] [${level}] ${message}${message.endsWith('\n') ? '' : '\n'}`;
 
       fs.appendFileSync(this.logFilePath, logEntry, 'utf8');
     } catch (error) {
-      // Silently fail if we can't write to log
+      // Write error to stderr so it doesn't get captured in loop
+      process.stderr.write(`[CommandLogger] Failed to write log: ${error.message}\n`);
     }
   }
 
@@ -98,25 +123,37 @@ class CommandLogger {
     // Intercept console.log
     console.log = (...args) => {
       this.writeLog('INFO', ...args);
-      this.originalLog(...args); // Still output to console
+      // Only forward to console if NOT in Ink mode
+      if (!this.inkMode) {
+        this.originalLog(...args);
+      }
     };
 
     // Intercept console.error
     console.error = (...args) => {
       this.writeLog('ERROR', ...args);
-      this.originalError(...args);
+      // Only forward to console if NOT in Ink mode
+      if (!this.inkMode) {
+        this.originalError(...args);
+      }
     };
 
     // Intercept console.warn
     console.warn = (...args) => {
       this.writeLog('WARN', ...args);
-      this.originalWarn(...args);
+      // Only forward to console if NOT in Ink mode
+      if (!this.inkMode) {
+        this.originalWarn(...args);
+      }
     };
 
     // Intercept console.info
     console.info = (...args) => {
       this.writeLog('INFO', ...args);
-      this.originalInfo(...args);
+      // Only forward to console if NOT in Ink mode
+      if (!this.inkMode) {
+        this.originalInfo(...args);
+      }
     };
   }
 
@@ -136,7 +173,7 @@ class CommandLogger {
         const footer = [
           '',
           '='.repeat(80),
-          `Command completed: ${new Date().toISOString()}`,
+          `Command completed: ${localISO()}`,
           `Log saved: ${this.logFilePath}`,
           '='.repeat(80)
         ].join('\n');

package/cli/components/static-output.js

@@ -0,0 +1,63 @@
+import React from 'react';
+import { Static, Text, Box } from 'ink';
+
+/**
+ * Badge config for message types (inspired by jest example's backgroundColor badges)
+ */
+const BADGE = {
+  ERROR:   { bg: 'red',    fg: 'white', label: ' ERR ' },
+  WARNING: { bg: 'yellow', fg: 'black', label: ' WRN ' },
+  SUCCESS: { bg: 'green',  fg: 'black', label: ' OK  ' },
+  INFO:    { bg: 'blue',   fg: 'white', label: ' INF ' },
+};
+
+/**
+ * StaticOutput - Renders output items using Ink's built-in Static component.
+ *
+ * Ink's <Static> commits each item to the terminal once and never touches
+ * it again. Items are NOT part of Ink's height-tracking calculation, so
+ * they never cause ghost renders when the interactive section changes height.
+ *
+ * Items with a `type` field get a colored background badge prefix
+ * (ERR/WRN/OK/INF) inspired by the jest example's test status chips.
+ *
+ * @param {Object} props
+ * @param {{id: number, content: string, type?: string}[]} props.items
+ * @returns {React.Element|null}
+ */
+export const StaticOutput = ({ items }) => {
+  if (!items || items.length === 0) return null;
+
+  return React.createElement(Static, { items },
+    (item) => {
+      const badge = item.type ? BADGE[item.type] : null;
+
+      if (badge) {
+        // Strip the "TYPE: " prefix from content — badge already shows the type visually
+        const displayContent = item.content.replace(/^(ERROR|WARNING|SUCCESS|INFO): /, '');
+        const lines = displayContent.split('\n');
+
+        if (lines.length === 1) {
+          // Single-line: badge + text side by side
+          return React.createElement(Box, { key: item.id, flexDirection: 'row', gap: 1 },
+            React.createElement(Text, { backgroundColor: badge.bg, color: badge.fg }, badge.label),
+            React.createElement(Text, null, displayContent)
+          );
+        }
+
+        // Multi-line: badge on first line only, subsequent lines fully left-aligned
+        return React.createElement(Box, { key: item.id, flexDirection: 'column' },
+          React.createElement(Box, { flexDirection: 'row', gap: 1 },
+            React.createElement(Text, { backgroundColor: badge.bg, color: badge.fg }, badge.label),
+            React.createElement(Text, null, lines[0])
+          ),
+          ...lines.slice(1).map((line, i) =>
+            React.createElement(Text, { key: i }, line)
+          )
+        );
+      }
+
+      return React.createElement(Text, { key: item.id }, item.content);
+    }
+  );
+};