@agile-vibe-coding/avc 0.1.1 → 0.3.1

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

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/dependency-checker.js

@@ -0,0 +1,72 @@
+/**
+ * dependency-checker.js — Pure-function module for checking work item dependency readiness.
+ *
+ * No side effects, no file I/O. All data passed in as arguments.
+ */
+
+/**
+ * Extract the parent ID from a work item ID by stripping the last segment.
+ * context-0001-0001-0001 → context-0001-0001
+ * context-0001-0001 → context-0001
+ * context-0001 → null
+ * @param {string} id
+ * @returns {string|null}
+ */
+export function getParentId(id) {
+  const match = id.match(/^(context-\d{4}(?:-\d{4})*)-\d{4}$/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Check if all dependencies of a work item are completed.
+ * Walks up the parent chain: task checks parent story deps,
+ * story checks parent epic deps, etc.
+ *
+ * @param {string} itemId - The work item to check
+ * @param {Map<string,object>|object} items - Map of id → work item, or plain object
+ * @returns {{ ready: boolean, blockers: Array<{id: string, name: string, type: string, status: string}> }}
+ */
+export function checkDependenciesReady(itemId, items) {
+  const get = (id) => items instanceof Map ? items.get(id) : items[id];
+  const blockers = [];
+  const seen = new Set();
+
+  function collectBlockers(id) {
+    if (!id || seen.has(id)) return;
+    seen.add(id);
+
+    const item = get(id);
+    if (!item) return;
+
+    // Check direct dependencies
+    for (const depId of item.dependencies || []) {
+      if (seen.has(depId)) continue;
+      const dep = get(depId);
+      if (!dep) continue;
+      if (dep.status !== 'completed') {
+        blockers.push({
+          id: depId,
+          name: dep.name || depId,
+          type: dep.type || 'unknown',
+          status: dep.status || 'planned',
+        });
+      }
+    }
+
+    // Walk up to parent and check its dependencies too
+    const parentId = getParentId(id);
+    if (parentId) {
+      collectBlockers(parentId);
+    }
+  }
+
+  collectBlockers(itemId);
+
+  // Deduplicate blockers by id
+  const unique = [...new Map(blockers.map(b => [b.id, b])).values()];
+
+  return {
+    ready: unique.length === 0,
+    blockers: unique,
+  };
+}

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