@agile-vibe-coding/avc 0.1.0 → 0.2.3

package/cli/build-docs.js

@@ -0,0 +1,298 @@
+import { execSync, spawn, exec } from 'child_process';
+import { promisify } from 'util';
+import path from 'path';
+import fs from 'fs';
+import net from 'net';
+import http from 'http';
+
+const execAsync = promisify(exec);
+
+/**
+ * Build and serve VitePress documentation
+ * Builds the docs and starts a local preview server
+ */
+export class DocumentationBuilder {
+  constructor(projectRoot = process.cwd()) {
+    this.projectRoot = projectRoot;
+    this.docsDir = path.join(projectRoot, '.avc', 'documentation');
+    this.distDir = path.join(this.docsDir, '.vitepress', 'dist');
+  }
+
+  /**
+   * Check if documentation directory exists
+   */
+  hasDocumentation() {
+    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
+   */
+  getPort() {
+    const configPath = path.join(this.projectRoot, '.avc', 'avc.json');
+
+    if (!fs.existsSync(configPath)) {
+      return 4173; // Default port
+    }
+
+    try {
+      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}`);
+      return 4173;
+    }
+  }
+
+  /**
+   * Check if a port is in use
+   * @param {number} port - Port number to check
+   * @returns {Promise<boolean>} - True if port is in use
+   */
+  async isPortInUse(port) {
+    return new Promise((resolve) => {
+      const server = net.createServer();
+
+      server.once('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+          resolve(true); // Port is in use
+        } else {
+          resolve(false);
+        }
+      });
+
+      server.once('listening', () => {
+        server.close();
+        resolve(false); // Port is available
+      });
+
+      server.listen(port, '127.0.0.1');
+    });
+  }
+
+  /**
+   * Check if the server on this port is serving our AVC documentation
+   * Makes HTTP request and checks for specific AVC metatag to positively identify
+   * @param {number} port - Port number to check
+   * @returns {Promise<boolean>} - True if it's confirmed to be AVC documentation server
+   */
+  async isDocumentationServer(port) {
+    return new Promise((resolve) => {
+      const req = http.get(`http://localhost:${port}/`, {
+        timeout: 2000
+      }, (res) => {
+        let data = '';
+
+        res.on('data', (chunk) => {
+          data += chunk;
+        });
+
+        res.on('end', () => {
+          // ONLY return true if we find the specific AVC documentation metatag
+          // This ensures we only kill processes we're 100% certain about
+          const hasAvcMetatag = data.includes('<meta name="avc-documentation" content="true">') ||
+                                data.includes('name="avc-documentation"') ||
+                                data.includes('name="generator" content="Agile Vibe Coding"');
+          resolve(hasAvcMetatag);
+        });
+      });
+
+      req.on('error', () => {
+        resolve(false); // Can't connect or verify
+      });
+
+      req.on('timeout', () => {
+        req.destroy();
+        resolve(false);
+      });
+    });
+  }
+
+  /**
+   * Find which process is using a port
+   * Works cross-platform (Linux, macOS, Windows)
+   * @param {number} port - Port number to check
+   * @returns {Promise<{pid: number, command: string} | null>} - Process info or null if not found
+   */
+  async findProcessUsingPort(port) {
+    try {
+      let command;
+      let parseOutput;
+
+      if (process.platform === 'win32') {
+        // Windows: netstat -ano | findstr :PORT
+        command = `netstat -ano | findstr :${port}`;
+        parseOutput = (output) => {
+          const lines = output.split('\n');
+          for (const line of lines) {
+            if (line.includes(`0.0.0.0:${port}`) || line.includes(`127.0.0.1:${port}`) || line.includes(`[::]:${port}`)) {
+              const parts = line.trim().split(/\s+/);
+              const pid = parseInt(parts[parts.length - 1]);
+              if (pid && !isNaN(pid)) {
+                return { pid, command: 'Unknown' }; // Windows netstat doesn't show command
+              }
+            }
+          }
+          return null;
+        };
+      } else {
+        // Linux/macOS: lsof -i :PORT
+        command = `lsof -i :${port} -t -sTCP:LISTEN`;
+        parseOutput = (output) => {
+          const pid = parseInt(output.trim());
+          if (pid && !isNaN(pid)) {
+            // Try to get process name
+            try {
+              const psOutput = execSync(`ps -p ${pid} -o comm=`, { encoding: 'utf8' });
+              return { pid, command: psOutput.trim() };
+            } catch {
+              return { pid, command: 'Unknown' };
+            }
+          }
+          return null;
+        };
+      }
+
+      const output = execSync(command, { encoding: 'utf8', stdio: 'pipe' });
+      return parseOutput(output);
+
+    } catch (error) {
+      // Command failed (port not in use or lsof not available)
+      return null;
+    }
+  }
+
+  /**
+   * Kill a process by PID
+   * Works cross-platform (Linux, macOS, Windows)
+   * @param {number} pid - Process ID to kill
+   * @returns {Promise<boolean>} - True if successfully killed, false otherwise
+   */
+  async killProcess(pid) {
+    try {
+      if (process.platform === 'win32') {
+        // Windows: taskkill /F /PID <pid>
+        execSync(`taskkill /F /PID ${pid}`, { stdio: 'pipe' });
+      } else {
+        // Linux/macOS: kill -9 <pid>
+        execSync(`kill -9 ${pid}`, { stdio: 'pipe' });
+      }
+      return true;
+    } catch (error) {
+      // Failed to kill (permission denied, process not found, etc.)
+      return false;
+    }
+  }
+
+  /**
+   * Build and serve the documentation
+   * Returns the server URL
+   */
+  async buildAndServe() {
+    if (!this.hasDocumentation()) {
+      throw new Error('Documentation not found. Run /init first to create documentation structure.');
+    }
+
+    const port = this.getPort();
+
+    try {
+      // 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'
+      });
+
+      // Wait for server to be ready
+      return new Promise((resolve, reject) => {
+        let serverReady = false;
+
+        serverProcess.stdout.on('data', (data) => {
+          const output = data.toString();
+          console.log(output);
+
+          // Check if server is ready
+          if (output.includes(`http://localhost:${port}`) || output.includes(`localhost:${port}`)) {
+            if (!serverReady) {
+              serverReady = true;
+              resolve({
+                url: `http://localhost:${port}`,
+                process: serverProcess
+              });
+            }
+          }
+        });
+
+        serverProcess.stderr.on('data', (data) => {
+          console.error(data.toString());
+        });
+
+        serverProcess.on('error', (error) => {
+          reject(error);
+        });
+
+        serverProcess.on('exit', (code) => {
+          if (code !== 0 && !serverReady) {
+            reject(new Error(`Server exited with code ${code}`));
+          }
+        });
+
+        // Timeout after 10 seconds
+        setTimeout(() => {
+          if (!serverReady) {
+            serverProcess.kill();
+            reject(new Error('Server start timeout'));
+          }
+        }, 10000);
+      });
+
+    } catch (error) {
+      throw new Error(`Failed to build documentation: ${error.message}`);
+    }
+  }
+
+  /**
+   * 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
+   */
+  async build() {
+    if (!this.hasDocumentation()) {
+      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', {
+        cwd: this.docsDir
+      });
+
+    } catch (error) {
+      throw new Error(`Failed to build documentation: ${error.message}`);
+    }
+  }
+}

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;
+  }
+}