@agile-vibe-coding/avc 0.1.0 → 0.2.3

package/cli/command-logger.js

@@ -0,0 +1,245 @@
+/**
+ * Command Logger - Creates individual log files for each command execution
+ *
+ * Each command creates a timestamped log file in .avc/logs/ directory:
+ * - init-2026-01-31-13-05-23.log
+ * - sponsor-call-2026-01-31-13-10-45.log
+ * - status-2026-01-31-13-15-30.log
+ * - remove-2026-01-31-13-20-15.log
+ */
+
+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(), 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 = localISO(now)
+      .replace(/T/, '-')
+      .replace(/:/g, '-')
+      .replace(/\..+/, '');
+
+    this.logFileName = `${commandName}-${timestamp}.log`;
+    this.logFilePath = path.join(this.logsDir, this.logFileName);
+
+    // Store original console methods
+    this.originalLog = console.log;
+    this.originalError = console.error;
+    this.originalWarn = console.warn;
+    this.originalInfo = console.info;
+
+    // Buffer for logs
+    this.logBuffer = [];
+
+    // Initialize log file
+    this.initializeLogFile();
+  }
+
+  /**
+   * Initialize log file and directory
+   */
+  initializeLogFile() {
+    try {
+      // Create logs directory if it doesn't exist
+      if (!fs.existsSync(this.logsDir)) {
+        fs.mkdirSync(this.logsDir, { recursive: true });
+      }
+
+      // Write header to log file
+      const header = [
+        '='.repeat(80),
+        `AVC Command Log: ${this.commandName}`,
+        `Timestamp: ${localISO()}`,
+        `Project: ${this.projectRoot}`,
+        `Log File: ${this.logFileName}`,
+        '='.repeat(80),
+        ''
+      ].join('\n');
+
+      fs.writeFileSync(this.logFilePath, header, 'utf8');
+    } catch (error) {
+      // If we can't create the log file, just continue without logging
+      this.logFilePath = null;
+    }
+  }
+
+  /**
+   * Write a log entry to the file
+   */
+  writeLog(level, ...args) {
+    if (!this.logFilePath) return;
+
+    try {
+      const timestamp = localISO();
+      const message = args.map(arg => {
+        if (arg === undefined) return 'undefined';
+        if (arg === null) return 'null';
+        if (typeof arg === 'object') {
+          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(' ');
+
+      // 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) {
+      // Write error to stderr so it doesn't get captured in loop
+      process.stderr.write(`[CommandLogger] Failed to write log: ${error.message}\n`);
+    }
+  }
+
+  /**
+   * Start capturing console output
+   */
+  start() {
+    // Intercept console.log
+    console.log = (...args) => {
+      this.writeLog('INFO', ...args);
+      // 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);
+      // 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);
+      // 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);
+      // Only forward to console if NOT in Ink mode
+      if (!this.inkMode) {
+        this.originalInfo(...args);
+      }
+    };
+  }
+
+  /**
+   * Stop capturing console output and write footer
+   */
+  stop() {
+    // Restore original console methods
+    console.log = this.originalLog;
+    console.error = this.originalError;
+    console.warn = this.originalWarn;
+    console.info = this.originalInfo;
+
+    // Write footer
+    if (this.logFilePath) {
+      try {
+        const footer = [
+          '',
+          '='.repeat(80),
+          `Command completed: ${localISO()}`,
+          `Log saved: ${this.logFilePath}`,
+          '='.repeat(80)
+        ].join('\n');
+
+        fs.appendFileSync(this.logFilePath, footer, 'utf8');
+      } catch (error) {
+        // Silently fail
+      }
+    }
+  }
+
+  /**
+   * Get the path to the log file
+   */
+  getLogPath() {
+    return this.logFilePath;
+  }
+
+  /**
+   * Clean up old log files (keep last N logs per command)
+   */
+  static cleanupOldLogs(projectRoot = process.cwd(), keepCount = 10) {
+    const logsDir = path.join(projectRoot, '.avc', 'logs');
+
+    if (!fs.existsSync(logsDir)) return;
+
+    try {
+      const files = fs.readdirSync(logsDir);
+
+      // Group files by command name
+      const filesByCommand = {};
+      files.forEach(file => {
+        if (!file.endsWith('.log')) return;
+
+        const commandName = file.split('-')[0];
+        if (!filesByCommand[commandName]) {
+          filesByCommand[commandName] = [];
+        }
+
+        filesByCommand[commandName].push({
+          name: file,
+          path: path.join(logsDir, file),
+          mtime: fs.statSync(path.join(logsDir, file)).mtime
+        });
+      });
+
+      // For each command, keep only the latest N files
+      Object.keys(filesByCommand).forEach(commandName => {
+        const files = filesByCommand[commandName];
+
+        // Sort by modification time (newest first)
+        files.sort((a, b) => b.mtime - a.mtime);
+
+        // Delete old files
+        files.slice(keepCount).forEach(file => {
+          try {
+            fs.unlinkSync(file.path);
+          } catch (error) {
+            // Ignore deletion errors
+          }
+        });
+      });
+    } catch (error) {
+      // Silently fail
+    }
+  }
+}
+
+export { CommandLogger };

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

package/cli/console-output-manager.js

@@ -0,0 +1,94 @@
+/**
+ * ConsoleOutputManager - Unified console output handling for Ink REPL
+ *
+ * Provides consistent console interception across all commands:
+ * - Filters [DEBUG] messages (file only, not displayed in UI)
+ * - Streams output to OutputBuffer for Static component rendering
+ * - Works with CommandLogger for file logging (without console duplication)
+ *
+ * Usage:
+ *   const manager = new ConsoleOutputManager();
+ *   manager.start();
+ *   try {
+ *     await someOperation(); // console.log calls will be captured
+ *   } finally {
+ *     manager.stop();
+ *   }
+ */
+
+import { outputBuffer } from './output-buffer.js';
+
+class ConsoleOutputManager {
+  constructor() {
+    this.originalLog = console.log;
+    this.originalError = console.error;
+    this.originalWarn = console.warn;
+    this.isActive = false;
+  }
+
+  /**
+   * Start intercepting console output
+   */
+  start() {
+    if (this.isActive) return;
+    this.isActive = true;
+
+    // Intercept console.log
+    console.log = (...args) => {
+      const message = args.join(' ');
+
+      // Filter [DEBUG] messages - they go to file only via CommandLogger
+      // Don't display them in the UI
+      if (message.includes('[DEBUG]')) {
+        // Forward to CommandLogger for file logging
+        // CommandLogger is already intercepting, so just call its version
+        this.originalLog(...args);
+        return;
+      }
+
+      // User-facing messages: append directly to buffer
+      outputBuffer.append(message + '\n');
+
+      // Also forward to CommandLogger for file logging
+      // CommandLogger is in inkMode, so it won't forward to real console
+      this.originalLog(...args);
+    };
+
+    // Intercept console.error
+    console.error = (...args) => {
+      const message = args.join(' ');
+
+      // Display errors in UI with error prefix
+      outputBuffer.append(`ERROR: ${message}\n`);
+
+      // Also forward to CommandLogger for file logging
+      this.originalError(...args);
+    };
+
+    // Intercept console.warn
+    console.warn = (...args) => {
+      const message = args.join(' ');
+
+      // Display warnings in UI with warning prefix
+      outputBuffer.append(`WARNING: ${message}\n`);
+
+      // Also forward to CommandLogger for file logging
+      this.originalWarn(...args);
+    };
+  }
+
+  /**
+   * Stop intercepting and restore original console
+   */
+  stop() {
+    if (!this.isActive) return;
+    this.isActive = false;
+
+    // Restore original console methods
+    console.log = this.originalLog;
+    console.error = this.originalError;
+    console.warn = this.originalWarn;
+  }
+}
+
+export default ConsoleOutputManager;

package/cli/docs-sync.js

@@ -0,0 +1,306 @@
+import fs from 'fs';
+import path from 'path';
+import chokidar from 'chokidar';
+
+const WORK_ITEMS_START = '// @@AVC-WORK-ITEMS-START@@';
+const WORK_ITEMS_END = '// @@AVC-WORK-ITEMS-END@@';
+
+/**
+ * Syncs .avc/project/ work-item hierarchy (epics + stories + doc.md files)
+ * into the VitePress documentation site at .avc/documentation/.
+ *
+ * Responsibilities:
+ *  1. Read .avc/project/ hierarchy via work.json files
+ *  2. Copy changed doc.md files into documentation/project/{epic}/{story}/index.md
+ *  3. Regenerate the VitePress sidebar between marker comments in config.mts
+ */
+export class DocsSyncProcessor {
+  constructor(projectRoot = process.cwd()) {
+    this.projectRoot = projectRoot;
+    this.avcDir = path.join(projectRoot, '.avc');
+    this.projectPath = path.join(this.avcDir, 'project');
+    this.docsDir = path.join(this.avcDir, 'documentation');
+    this.projectDocsDir = path.join(this.docsDir, 'project');
+    this.configPath = path.join(this.docsDir, '.vitepress', 'config.mts');
+    this.avcConfigPath = path.join(this.avcDir, 'avc.json');
+  }
+
+  /**
+   * Read the epic/story hierarchy from .avc/project/ work.json files.
+   * Returns array sorted by ID, each entry: { id, name, docPath, stories: [{ id, name, docPath }] }
+   */
+  readHierarchy() {
+    if (!fs.existsSync(this.projectPath)) {
+      return [];
+    }
+
+    const entries = fs.readdirSync(this.projectPath, { withFileTypes: true });
+    const epics = [];
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+
+      const epicId = entry.name;
+      const workJsonPath = path.join(this.projectPath, epicId, 'work.json');
+
+      if (!fs.existsSync(workJsonPath)) continue;
+
+      let workJson;
+      try {
+        workJson = JSON.parse(fs.readFileSync(workJsonPath, 'utf8'));
+      } catch {
+        continue;
+      }
+
+      if (workJson.type !== 'epic') continue;
+
+      const epicDocPath = path.join(this.projectPath, epicId, 'doc.md');
+      const stories = [];
+
+      // Scan subdirectories for stories
+      const epicDir = path.join(this.projectPath, epicId);
+      const storyEntries = fs.readdirSync(epicDir, { withFileTypes: true });
+
+      for (const storyEntry of storyEntries) {
+        if (!storyEntry.isDirectory()) continue;
+
+        const storyId = storyEntry.name;
+        const storyWorkJsonPath = path.join(epicDir, storyId, 'work.json');
+
+        if (!fs.existsSync(storyWorkJsonPath)) continue;
+
+        let storyWorkJson;
+        try {
+          storyWorkJson = JSON.parse(fs.readFileSync(storyWorkJsonPath, 'utf8'));
+        } catch {
+          continue;
+        }
+
+        if (storyWorkJson.type !== 'story') continue;
+
+        const storyDocPath = path.join(epicDir, storyId, 'doc.md');
+        stories.push({
+          id: storyId,
+          name: storyWorkJson.name || storyId,
+          docPath: storyDocPath,
+        });
+      }
+
+      stories.sort((a, b) => a.id.localeCompare(b.id));
+
+      epics.push({
+        id: epicId,
+        name: workJson.name || epicId,
+        docPath: epicDocPath,
+        stories,
+      });
+    }
+
+    epics.sort((a, b) => a.id.localeCompare(b.id));
+    return epics;
+  }
+
+  /**
+   * Copy src to dest if source is newer than dest (mtime-based incremental skip).
+   * Returns 'copied' or 'skipped'.
+   */
+  syncFile(src, dest) {
+    if (!fs.existsSync(src)) {
+      return 'skipped';
+    }
+
+    if (fs.existsSync(dest)) {
+      const srcStat = fs.statSync(src);
+      const destStat = fs.statSync(dest);
+      if (destStat.mtimeMs >= srcStat.mtimeMs) {
+        return 'skipped';
+      }
+    }
+
+    fs.copyFileSync(src, dest);
+    return 'copied';
+  }
+
+  /**
+   * Write a stub index.md for an epic/story that has no doc.md yet.
+   */
+  _writeStub(destPath, name) {
+    const content = `# ${name}\n\n_Documentation pending._\n`;
+    fs.writeFileSync(destPath, content, 'utf8');
+  }
+
+  /**
+   * Main sync orchestration. Reads hierarchy, copies files, regenerates sidebar config.
+   * @param {Function} [progressCallback] - optional (message) => void
+   * @returns {{ epics: number, stories: number, copied: number, skipped: number }}
+   */
+  async sync(progressCallback = null) {
+    if (!fs.existsSync(this.docsDir)) {
+      throw new Error('Documentation directory not found. Run /init first to create documentation structure.');
+    }
+
+    const report = (msg) => { if (progressCallback) progressCallback(msg); };
+    const hierarchy = this.readHierarchy();
+
+    let epicCount = 0;
+    let storyCount = 0;
+    let copiedCount = 0;
+    let skippedCount = 0;
+
+    // Sync project root doc.md → documentation/index.md
+    const projectDocSrc = path.join(this.projectPath, 'doc.md');
+    const projectDocDest = path.join(this.docsDir, 'index.md');
+    if (fs.existsSync(projectDocSrc)) {
+      const result = this.syncFile(projectDocSrc, projectDocDest);
+      if (result === 'copied') copiedCount++;
+      else skippedCount++;
+      report(`Project brief: ${result}`);
+    }
+
+    // Ensure project/ subdir exists if we have epics
+    if (hierarchy.length > 0) {
+      fs.mkdirSync(this.projectDocsDir, { recursive: true });
+    }
+
+    for (const epic of hierarchy) {
+      epicCount++;
+      const epicDestDir = path.join(this.projectDocsDir, epic.id);
+      fs.mkdirSync(epicDestDir, { recursive: true });
+
+      const epicDestPath = path.join(epicDestDir, 'index.md');
+      if (fs.existsSync(epic.docPath)) {
+        const result = this.syncFile(epic.docPath, epicDestPath);
+        if (result === 'copied') copiedCount++;
+        else skippedCount++;
+        report(`Epic ${epic.id}: ${result}`);
+      } else {
+        this._writeStub(epicDestPath, epic.name);
+        copiedCount++;
+        report(`Epic ${epic.id}: stub written`);
+      }
+
+      for (const story of epic.stories) {
+        storyCount++;
+        const storyDestDir = path.join(epicDestDir, story.id);
+        fs.mkdirSync(storyDestDir, { recursive: true });
+
+        const storyDestPath = path.join(storyDestDir, 'index.md');
+        if (fs.existsSync(story.docPath)) {
+          const result = this.syncFile(story.docPath, storyDestPath);
+          if (result === 'copied') copiedCount++;
+          else skippedCount++;
+          report(`Story ${story.id}: ${result}`);
+        } else {
+          this._writeStub(storyDestPath, story.name);
+          copiedCount++;
+          report(`Story ${story.id}: stub written`);
+        }
+      }
+    }
+
+    // Regenerate VitePress sidebar config
+    this.generateVitePressConfig(hierarchy);
+
+    return { epics: epicCount, stories: storyCount, copied: copiedCount, skipped: skippedCount };
+  }
+
+  /**
+   * Regenerate the @@AVC-WORK-ITEMS-START@@ … @@AVC-WORK-ITEMS-END@@ block in config.mts.
+   * If markers are absent (existing project), appends as second sidebar array element and inserts markers.
+   */
+  generateVitePressConfig(hierarchy) {
+    if (!fs.existsSync(this.configPath)) return;
+
+    const content = fs.readFileSync(this.configPath, 'utf8');
+    const workItemsBlock = this._buildWorkItemsBlock(hierarchy);
+
+    if (content.includes(WORK_ITEMS_START)) {
+      // Replace content between markers (inclusive)
+      const startIdx = content.indexOf(WORK_ITEMS_START);
+      const endIdx = content.indexOf(WORK_ITEMS_END);
+      if (endIdx === -1) return; // malformed markers, skip
+
+      const before = content.slice(0, startIdx);
+      const after = content.slice(endIdx + WORK_ITEMS_END.length);
+      const updated = before + workItemsBlock + after;
+      fs.writeFileSync(this.configPath, updated, 'utf8');
+    } else {
+      // Backwards compat: insert markers + work items block before the closing of the sidebar array
+      // Find the closing `]` of the sidebar array
+      const sidebarMatch = content.match(/sidebar:\s*\[/);
+      if (!sidebarMatch) return;
+
+      // Find the end of the first sidebar item block to insert after it
+      const insertionPattern = /sidebar:\s*\[\s*\{[\s\S]*?\}\s*(?=\])/;
+      const match = insertionPattern.exec(content);
+      if (!match) return;
+
+      const insertAt = match.index + match[0].length;
+      const updated = content.slice(0, insertAt) + '\n      ' + workItemsBlock + '\n    ' + content.slice(insertAt);
+      fs.writeFileSync(this.configPath, updated, 'utf8');
+    }
+  }
+
+  /**
+   * Build the sidebar work-items block string (with markers).
+   */
+  _buildWorkItemsBlock(hierarchy) {
+    if (hierarchy.length === 0) {
+      return `${WORK_ITEMS_START}\n      ${WORK_ITEMS_END}`;
+    }
+
+    const epicItems = hierarchy.map(epic => {
+      const storyItems = epic.stories.map(story => {
+        const link = path.posix.join('/project', epic.id, story.id) + '/';
+        return `          { text: ${JSON.stringify(story.name)}, link: ${JSON.stringify(link)} }`;
+      });
+
+      const epicLink = path.posix.join('/project', epic.id) + '/';
+      if (storyItems.length > 0) {
+        return `        { text: ${JSON.stringify(epic.name)}, link: ${JSON.stringify(epicLink)}, collapsed: false, items: [\n${storyItems.join(',\n')}\n        ] }`;
+      } else {
+        return `        { text: ${JSON.stringify(epic.name)}, link: ${JSON.stringify(epicLink)} }`;
+      }
+    });
+
+    const block = `,{
+        text: 'Work Items',
+        items: [
+${epicItems.join(',\n')}
+        ]
+      }`;
+
+    return `${WORK_ITEMS_START}\n      ${block}\n      ${WORK_ITEMS_END}`;
+  }
+
+  /**
+   * Watch .avc/project/ for md changes and trigger sync with debounce.
+   * Returns a chokidar watcher instance.
+   */
+  watch(onChange = null) {
+    let debounceTimer = null;
+
+    const watcher = chokidar.watch(path.join(this.projectPath, '**', '*.md'), {
+      ignoreInitial: true,
+      awaitWriteFinish: { stabilityThreshold: 500, pollInterval: 100 },
+    });
+
+    const trigger = () => {
+      if (debounceTimer) clearTimeout(debounceTimer);
+      debounceTimer = setTimeout(async () => {
+        try {
+          const stats = await this.sync();
+          if (onChange) onChange(stats);
+        } catch {
+          // Ignore errors in watch mode
+        }
+      }, 500);
+    };
+
+    watcher.on('add', trigger);
+    watcher.on('change', trigger);
+    watcher.on('unlink', trigger);
+
+    return watcher;
+  }
+}