@agile-vibe-coding/avc 0.1.1 → 0.2.3

package/kanban/server/services/FileSystemScanner.js

@@ -0,0 +1,95 @@
+import fs from 'fs/promises';
+import path from 'path';
+
+/**
+ * FileSystemScanner
+ * Recursively scans .avc/project/ directory to find all work.json files
+ */
+export class FileSystemScanner {
+  /**
+   * @param {string} projectRoot - Absolute path to project root directory
+   */
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    this.avcProjectPath = path.join(projectRoot, '.avc', 'project');
+  }
+
+  /**
+   * Scan the .avc/project/ directory and return all work.json file paths
+   * @returns {Promise<Array<string>>} Array of absolute paths to work.json files
+   */
+  async scan() {
+    try {
+      // Check if .avc/project exists
+      await fs.access(this.avcProjectPath);
+
+      const workFiles = [];
+      await this._scanDirectory(this.avcProjectPath, workFiles);
+
+      return workFiles;
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        // .avc/project doesn't exist yet
+        return [];
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Recursively scan a directory for work.json files
+   * @private
+   * @param {string} dirPath - Directory to scan
+   * @param {Array<string>} results - Accumulator for results
+   */
+  async _scanDirectory(dirPath, results) {
+    try {
+      const entries = await fs.readdir(dirPath, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = path.join(dirPath, entry.name);
+
+        if (entry.isDirectory()) {
+          // Recursively scan subdirectories
+          await this._scanDirectory(fullPath, results);
+        } else if (entry.isFile() && entry.name === 'work.json') {
+          // Found a work.json file
+          results.push(fullPath);
+        }
+      }
+    } catch (error) {
+      // Log error but continue scanning
+      console.error(`Error scanning directory ${dirPath}:`, error.message);
+    }
+  }
+
+  /**
+   * Get the relative path from .avc/project/ to a work.json file
+   * Useful for extracting the work item ID from the path
+   * @param {string} fullPath - Absolute path to work.json
+   * @returns {string} Relative path from .avc/project/
+   */
+  getRelativePath(fullPath) {
+    return path.relative(this.avcProjectPath, fullPath);
+  }
+
+  /**
+   * Extract work item ID from file path
+   * Example: .avc/project/context-0001/context-0001-0001/work.json → context-0001-0001
+   * @param {string} fullPath - Absolute path to work.json
+   * @returns {string|null} Work item ID or null if invalid path
+   */
+  extractIdFromPath(fullPath) {
+    const relativePath = this.getRelativePath(fullPath);
+    const dir = path.dirname(relativePath);
+
+    // Handle root-level work.json (shouldn't exist in normal hierarchy)
+    if (dir === '.') {
+      return null;
+    }
+
+    // Extract the deepest folder name (the work item ID)
+    // Example: context-0001/context-0001-0001 → context-0001-0001
+    return path.basename(dir);
+  }
+}

package/kanban/server/services/FileWatcher.js

@@ -0,0 +1,144 @@
+import chokidar from 'chokidar';
+import { EventEmitter } from 'events';
+import path from 'path';
+
+/**
+ * FileWatcher
+ * Watches .avc/project/ for changes to work.json files
+ * Emits events when files are added, changed, or deleted
+ */
+export class FileWatcher extends EventEmitter {
+  /**
+   * @param {string} projectRoot - Absolute path to project root directory
+   */
+  constructor(projectRoot) {
+    super();
+    this.projectRoot = projectRoot;
+    this.avcPath = path.join(projectRoot, '.avc');
+    this.avcProjectPath = path.join(projectRoot, '.avc', 'project');
+    this.watcher = null;
+    this.dirWatcher = null;
+    this.avcDirWatcher = null;
+  }
+
+  /**
+   * Start watching for file changes
+   */
+  start() {
+    if (this.watcher) {
+      console.warn('FileWatcher already started');
+      return;
+    }
+
+    // Watch all work.json files in .avc/project/
+    const watchPattern = path.join(this.avcProjectPath, '**/work.json');
+
+    this.watcher = chokidar.watch(watchPattern, {
+      persistent: true,
+      ignoreInitial: true, // Don't emit events for initial scan
+      usePolling: true,    // Required for WSL2 /mnt/ paths (no inotify on Windows mounts)
+      interval: 2000,      // Poll every 2 seconds
+      awaitWriteFinish: {
+        // Wait for file writes to complete before emitting event
+        stabilityThreshold: 500,
+        pollInterval: 100,
+      },
+    });
+
+    // File added
+    this.watcher.on('add', (filePath) => {
+      this.emit('added', filePath);
+    });
+
+    // File changed
+    this.watcher.on('change', (filePath) => {
+      this.emit('changed', filePath);
+    });
+
+    // File deleted
+    this.watcher.on('unlink', (filePath) => {
+      this.emit('deleted', filePath);
+    });
+
+    // Directory deleted inside .avc/project/
+    this.watcher.on('unlinkDir', (dirPath) => {
+      this.emit('deleted', dirPath);
+    });
+
+    // Error
+    this.watcher.on('error', (error) => {
+      this.emit('error', error);
+    });
+
+    // Ready (initial scan complete)
+    this.watcher.on('ready', () => {
+      this.emit('ready');
+    });
+
+    // Secondary watcher: explicitly watch the .avc/project directory itself.
+    // On WSL2, polling a file-glob may not reliably emit unlinkDir when the
+    // entire .avc/ tree is deleted (e.g. by /remove). Watching the directory
+    // path directly guarantees detection on the next 2-second poll cycle.
+    this.dirWatcher = chokidar.watch(this.avcProjectPath, {
+      persistent: true,
+      ignoreInitial: true,
+      usePolling: true,
+      interval: 2000,
+      depth: 0, // Only care about the directory itself, not its contents
+    });
+
+    this.dirWatcher.on('unlinkDir', () => {
+      this.emit('deleted', this.avcProjectPath);
+    });
+
+    this.dirWatcher.on('error', (error) => {
+      this.emit('error', error);
+    });
+
+    // Tertiary watcher: watch .avc/ itself so that when /remove deletes the
+    // entire .avc/ tree, we reliably detect it on the next poll cycle.
+    // On WSL2, chokidar polling may not fire unlinkDir for .avc/project/ when
+    // its parent is deleted — watching the parent directly fixes this.
+    this.avcDirWatcher = chokidar.watch(this.avcPath, {
+      persistent: true,
+      ignoreInitial: true,
+      usePolling: true,
+      interval: 2000,
+      depth: 0,
+    });
+
+    this.avcDirWatcher.on('unlinkDir', () => {
+      this.emit('deleted', this.avcProjectPath);
+    });
+
+    this.avcDirWatcher.on('error', (error) => {
+      this.emit('error', error);
+    });
+  }
+
+  /**
+   * Stop watching for file changes
+   */
+  async stop() {
+    if (this.watcher) {
+      await this.watcher.close();
+      this.watcher = null;
+    }
+    if (this.dirWatcher) {
+      await this.dirWatcher.close();
+      this.dirWatcher = null;
+    }
+    if (this.avcDirWatcher) {
+      await this.avcDirWatcher.close();
+      this.avcDirWatcher = null;
+    }
+  }
+
+  /**
+   * Check if watcher is active
+   * @returns {boolean}
+   */
+  isWatching() {
+    return this.watcher !== null;
+  }
+}

package/kanban/server/services/HierarchyBuilder.js

@@ -0,0 +1,196 @@
+/**
+ * HierarchyBuilder
+ * Builds parent-child relationships for work items
+ */
+export class HierarchyBuilder {
+  /**
+   * Build hierarchical relationships for work items
+   * Adds _parent, _children, _type fields to each work item
+   * @param {Array<object>} workItems - Array of work items
+   * @returns {object} Object with { items: Map, roots: Array }
+   */
+  buildHierarchy(workItems) {
+    // Create a map of id → work item for fast lookup
+    const itemsMap = new Map();
+
+    // First pass: Create map and initialize fields
+    workItems.forEach((item) => {
+      // Determine type from ID structure
+      item._type = this.getWorkItemType(item.id);
+
+      // Determine parent ID
+      item._parentId = this.getParentId(item.id);
+
+      // Initialize children array
+      item._children = [];
+
+      // Add to map
+      itemsMap.set(item.id, item);
+    });
+
+    // Second pass: Build parent-child relationships
+    const roots = [];
+
+    workItems.forEach((item) => {
+      if (item._parentId) {
+        // Has a parent - add to parent's children array
+        const parent = itemsMap.get(item._parentId);
+        if (parent) {
+          parent._children.push(item);
+          item._parent = parent;
+        } else {
+          // Parent not found (orphaned item)
+          console.warn(`Orphaned work item: ${item.id} (parent ${item._parentId} not found)`);
+          roots.push(item);
+        }
+      } else {
+        // No parent - this is a root (epic)
+        roots.push(item);
+      }
+    });
+
+    // Sort children by ID for consistent ordering
+    itemsMap.forEach((item) => {
+      if (item._children.length > 0) {
+        item._children.sort((a, b) => a.id.localeCompare(b.id));
+      }
+    });
+
+    // Sort roots by ID
+    roots.sort((a, b) => a.id.localeCompare(b.id));
+
+    return {
+      items: itemsMap,
+      roots,
+    };
+  }
+
+  /**
+   * Determine work item type based on ID depth
+   * @param {string} id - Work item ID
+   * @returns {string} Type: 'epic' | 'story' | 'task' | 'subtask'
+   */
+  getWorkItemType(id) {
+    const parts = id.split('-');
+    const depth = parts.length - 1; // Subtract 1 for 'context' prefix
+
+    switch (depth) {
+      case 1:
+        return 'epic';
+      case 2:
+        return 'story';
+      case 3:
+        return 'task';
+      case 4:
+        return 'subtask';
+      default:
+        return 'unknown';
+    }
+  }
+
+  /**
+   * Get parent ID from a work item ID
+   * @param {string} id - Work item ID
+   * @returns {string|null} Parent ID or null if root level
+   */
+  getParentId(id) {
+    const parts = id.split('-');
+
+    if (parts.length <= 2) {
+      // Root level (epic), no parent
+      return null;
+    }
+
+    // Remove the last segment
+    return parts.slice(0, -1).join('-');
+  }
+
+  /**
+   * Get all ancestors for a work item (path to root)
+   * @param {object} item - Work item
+   * @returns {Array<object>} Array of ancestors from immediate parent to root
+   */
+  getAncestors(item) {
+    const ancestors = [];
+    let current = item._parent;
+
+    while (current) {
+      ancestors.push(current);
+      current = current._parent;
+    }
+
+    return ancestors;
+  }
+
+  /**
+   * Get all descendants for a work item (recursive children)
+   * @param {object} item - Work item
+   * @returns {Array<object>} Array of all descendants
+   */
+  getDescendants(item) {
+    const descendants = [];
+
+    const traverse = (node) => {
+      if (node._children && node._children.length > 0) {
+        node._children.forEach((child) => {
+          descendants.push(child);
+          traverse(child);
+        });
+      }
+    };
+
+    traverse(item);
+    return descendants;
+  }
+
+  /**
+   * Get the root epic for a work item
+   * @param {object} item - Work item
+   * @returns {object|null} Root epic or null if already a root
+   */
+  getRootEpic(item) {
+    if (!item._parent) {
+      // Already a root
+      return item._type === 'epic' ? item : null;
+    }
+
+    let current = item._parent;
+    while (current._parent) {
+      current = current._parent;
+    }
+
+    return current._type === 'epic' ? current : null;
+  }
+
+  /**
+   * Calculate progress statistics for a work item based on children
+   * @param {object} item - Work item
+   * @returns {object} Progress statistics
+   */
+  calculateProgress(item) {
+    if (!item._children || item._children.length === 0) {
+      // Leaf node - progress based on own status
+      return {
+        total: 1,
+        completed: item.status === 'completed' ? 1 : 0,
+        percentage: item.status === 'completed' ? 100 : 0,
+      };
+    }
+
+    // Aggregate children's progress
+    let total = 0;
+    let completed = 0;
+
+    item._children.forEach((child) => {
+      const childProgress = this.calculateProgress(child);
+      total += childProgress.total;
+      completed += childProgress.completed;
+    });
+
+    return {
+      total,
+      completed,
+      percentage: total > 0 ? Math.round((completed / total) * 100) : 0,
+    };
+  }
+}

package/kanban/server/services/ProcessRegistry.js

@@ -0,0 +1,122 @@
+import { EventEmitter } from 'events';
+import { randomBytes } from 'crypto';
+
+/**
+ * ProcessRegistry
+ * Tracks forked ceremony/CLI processes: status, lightweight log ring-buffer, IPC control.
+ */
+export class ProcessRegistry extends EventEmitter {
+  constructor() {
+    super();
+    this._processes = new Map(); // processId → ProcessRecord
+    this.LOG_CAP = 500;
+  }
+
+  /**
+   * Allocate a new ProcessRecord (before the child is forked).
+   * @returns {object} The new record
+   */
+  create(type, label) {
+    const id = `${type}-${Date.now()}-${randomBytes(3).toString('hex')}`;
+    const record = {
+      id,
+      type,
+      label,
+      status: 'running',
+      startedAt: Date.now(),
+      endedAt: null,
+      childProcess: null,
+      logs: [],
+      result: null,
+      error: null,
+    };
+    this._processes.set(id, record);
+    this.emit('created', record);
+    return record;
+  }
+
+  /** Attach the ChildProcess handle after fork(). */
+  attach(processId, child) {
+    const r = this._processes.get(processId);
+    if (r) r.childProcess = child;
+  }
+
+  /** Append a log entry (capped at LOG_CAP). */
+  appendLog(processId, entry) {
+    const r = this._processes.get(processId);
+    if (!r) return;
+    r.logs.push(entry);
+    if (r.logs.length > this.LOG_CAP) r.logs = r.logs.slice(-this.LOG_CAP);
+    this.emit('log', processId, entry);
+  }
+
+  /** Update status and optional extra fields (result/error). */
+  setStatus(processId, status, extra = {}) {
+    const r = this._processes.get(processId);
+    if (!r) return;
+    r.status = status;
+    if (['complete', 'error', 'cancelled'].includes(status)) {
+      r.endedAt = Date.now();
+      r.childProcess = null;
+    }
+    Object.assign(r, extra);
+    this.emit('status', processId, status, r);
+  }
+
+  get(id) { return this._processes.get(id) ?? null; }
+
+  /** Alias for get() — processId is used as the map key. */
+  getByProcessId(processId) { return this.get(processId); }
+
+  /** All records as plain DTOs (no ChildProcess reference). */
+  list() { return [...this._processes.values()].map(r => this._dto(r)); }
+
+  getDTO(id) {
+    const r = this._processes.get(id);
+    return r ? this._dto(r) : null;
+  }
+
+  /** Send cancel IPC; force-kill after 5 s if still alive. */
+  kill(id) {
+    const r = this._processes.get(id);
+    if (!r?.childProcess) return false;
+    try { r.childProcess.send({ type: 'cancel' }); } catch (_) {}
+    setTimeout(() => { try { r.childProcess?.kill('SIGTERM'); } catch (_) {} }, 5000);
+    return true;
+  }
+
+  pause(id) {
+    const r = this._processes.get(id);
+    if (r?.childProcess) { try { r.childProcess.send({ type: 'pause' }); } catch (_) {} return true; }
+    return false;
+  }
+
+  resume(id) {
+    const r = this._processes.get(id);
+    if (r?.childProcess) { try { r.childProcess.send({ type: 'resume' }); } catch (_) {} return true; }
+    return false;
+  }
+
+  /** Remove all finished records (complete/error/cancelled). */
+  clearCompleted() {
+    for (const [id, r] of this._processes) {
+      if (['complete', 'error', 'cancelled'].includes(r.status)) {
+        this._processes.delete(id);
+      }
+    }
+  }
+
+  _dto(r) {
+    return {
+      id: r.id,
+      type: r.type,
+      label: r.label,
+      status: r.status,
+      startedAt: r.startedAt,
+      endedAt: r.endedAt,
+      result: r.result,
+      error: r.error,
+      // logs are NOT included — ceremony stores accumulate via WS events
+    };
+  }
+}

package/kanban/server/services/WorkItemReader.js

@@ -0,0 +1,123 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { extractDescriptionFromDoc } from '../utils/markdown.js';
+
+/**
+ * WorkItemReader
+ * Parses work.json files and builds hierarchical work item structure
+ */
+export class WorkItemReader {
+  /**
+   * @param {string} projectRoot - Absolute path to project root directory
+   */
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    this.avcProjectPath = path.join(projectRoot, '.avc', 'project');
+  }
+
+  /**
+   * Read and parse a single work.json file
+   * @param {string} filePath - Absolute path to work.json
+   * @returns {Promise<object|null>} Parsed work item or null if invalid
+   */
+  async readWorkItem(filePath) {
+    try {
+      const content = await fs.readFile(filePath, 'utf8');
+      const workItem = JSON.parse(content);
+
+      // Enhance with computed fields
+      workItem._filePath = filePath;
+      workItem._dirPath = path.dirname(filePath);
+
+      return workItem;
+    } catch (error) {
+      console.error(`Error reading work item from ${filePath}:`, error.message);
+      return null;
+    }
+  }
+
+  /**
+   * Read all work items from an array of file paths
+   * @param {Array<string>} filePaths - Array of absolute paths to work.json files
+   * @returns {Promise<Array<object>>} Array of parsed work items
+   */
+  async readAllWorkItems(filePaths) {
+    const promises = filePaths.map((filePath) => this.readWorkItem(filePath));
+    const results = await Promise.all(promises);
+
+    // Filter out null results (failed reads)
+    return results.filter((item) => item !== null);
+  }
+
+  /**
+   * Determine work item type based on ID depth
+   * Example: context-0001 → epic, context-0001-0001 → story, etc.
+   * @param {string} id - Work item ID
+   * @returns {string} Type: 'epic' | 'story' | 'task' | 'subtask'
+   */
+  getWorkItemType(id) {
+    const parts = id.split('-');
+    const depth = parts.length - 1; // Subtract 1 for 'context' prefix
+
+    switch (depth) {
+      case 1:
+        return 'epic';
+      case 2:
+        return 'story';
+      case 3:
+        return 'task';
+      case 4:
+        return 'subtask';
+      default:
+        return 'unknown';
+    }
+  }
+
+  /**
+   * Get parent ID from a work item ID
+   * Example: context-0001-0001-0001 → context-0001-0001
+   * @param {string} id - Work item ID
+   * @returns {string|null} Parent ID or null if root level
+   */
+  getParentId(id) {
+    const parts = id.split('-');
+
+    if (parts.length <= 2) {
+      // Root level (epic), no parent
+      return null;
+    }
+
+    // Remove the last segment
+    return parts.slice(0, -1).join('-');
+  }
+
+  /**
+   * Read doc.md file for a work item
+   * @param {string} workItemPath - Directory path of work item
+   * @returns {Promise<string|null>} Markdown content or null if not found
+   */
+  async readDocumentation(workItemPath) {
+    try {
+      const docPath = path.join(workItemPath, 'doc.md');
+      return await fs.readFile(docPath, 'utf8');
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Get full details for a work item (including doc.md)
+   * @param {object} workItem - Base work item object
+   * @returns {Promise<object>} Enhanced work item with documentation
+   */
+  async getFullDetails(workItem) {
+    const dirPath = workItem._dirPath;
+    const doc = await this.readDocumentation(dirPath);
+    return {
+      ...workItem,
+      // doc.md opening paragraph is canonical; fall back to work.json value if no doc.md
+      description: doc ? extractDescriptionFromDoc(doc) || workItem.description : workItem.description,
+      documentation: doc,
+    };
+  }
+}