@longph2102/v-flow 1.5.0

package/cli/commands/watch.js

@@ -0,0 +1,151 @@
+/**
+ * v-flow watch — tool-agnostic activity safety net.
+ *
+ * Watches `.v-flow/**` and logs every file create/modify/delete to
+ * `.v-flow/logs/`. Because it observes the real artifacts agents produce, it
+ * captures activity from ANY AI tool (even ones without hooks) and from manual
+ * edits — a deterministic fallback complementing per-tool hooks.
+ *
+ * Portable recursive watch: watches each directory individually (and adds
+ * watchers for new ones) instead of relying on fs.watch({recursive:true}),
+ * which is unavailable on Linux before Node 20.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const chalk = require('chalk');
+const { withErrorHandler, requireInit } = require('../lib/cli-error');
+const { isInitialized, getVFlowDir } = require('../lib/templates');
+const activityLog = require('../lib/activity-log');
+
+// First path segment under .v-flow/ to never watch. `logs` is mandatory (we
+// write there — watching it would loop). The others are gitignored runtime
+// copies that would only add noise.
+const EXCLUDE_TOP = new Set(['logs', 'templates', 'skills']);
+const IGNORE_BASENAMES = new Set(['.DS_Store']);
+const DEBOUNCE_MS = 200;
+
+module.exports = function (program) {
+  program
+    .command('watch')
+    .description('Watch .v-flow/ and log every file change (tool-agnostic safety net)')
+    .option('--timeout <seconds>', 'Stop automatically after N seconds (0 = run until Ctrl-C)', '0')
+    .action(
+      withErrorHandler((options) => {
+        const projectRoot = process.cwd();
+        requireInit(projectRoot, isInitialized);
+        const vflowDir = getVFlowDir(projectRoot);
+
+        const watchers = [];
+        const known = new Set(); // paths seen → distinguish created vs modified
+        const timers = new Map(); // debounce per path
+        let stopped = false;
+
+        const relTop = (full) => path.relative(vflowDir, full).split(path.sep)[0];
+        const isExcluded = (full) => EXCLUDE_TOP.has(relTop(full));
+
+        function watchDir(dir) {
+          let watcher;
+          try {
+            watcher = fs.watch(dir, (eventType, filename) => {
+              if (!filename) return;
+              const full = path.join(dir, filename);
+              if (isExcluded(full) || IGNORE_BASENAMES.has(path.basename(full))) return;
+              schedule(full);
+            });
+          } catch (_) {
+            return; // dir vanished before we could watch it
+          }
+          watcher.on('error', () => {});
+          watchers.push(watcher);
+        }
+
+        // emit(full) is called for each newly-discovered path so a directory
+        // created together with its files in one tick still logs those files.
+        function addTree(dir, emit) {
+          watchDir(dir);
+          let entries = [];
+          try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+          } catch (_) {
+            return;
+          }
+          for (const ent of entries) {
+            const full = path.join(dir, ent.name);
+            if (isExcluded(full) || IGNORE_BASENAMES.has(ent.name)) continue;
+            const isNew = !known.has(full);
+            known.add(full);
+            if (isNew && emit) emit(full);
+            if (ent.isDirectory()) addTree(full, emit);
+          }
+        }
+
+        function schedule(full) {
+          if (timers.has(full)) clearTimeout(timers.get(full));
+          timers.set(
+            full,
+            setTimeout(() => {
+              timers.delete(full);
+              handleChange(full);
+            }, DEBOUNCE_MS)
+          );
+        }
+
+        function logFs(full, action) {
+          const rel = path.relative(vflowDir, full);
+          activityLog.event({ type: 'fs', action, path: rel }, `[fs] ${action} ${rel}`);
+          const colors = { created: chalk.green, modified: chalk.yellow, deleted: chalk.red };
+          const color = colors[action] || chalk.white;
+          console.log(`${chalk.dim(new Date().toISOString())}  ${color(action.padEnd(8))} ${rel}`);
+        }
+
+        function handleChange(full) {
+          const exists = fs.existsSync(full);
+          if (exists && !known.has(full)) {
+            known.add(full);
+            logFs(full, 'created');
+            try {
+              if (fs.statSync(full).isDirectory()) addTree(full, (child) => logFs(child, 'created'));
+            } catch (_) {
+              /* ignore */
+            }
+          } else if (exists) {
+            logFs(full, 'modified');
+          } else if (known.has(full)) {
+            known.delete(full);
+            logFs(full, 'deleted');
+          }
+          // else: spurious event for an unknown, non-existent path — ignore
+        }
+
+        function stop(reason) {
+          if (stopped) return;
+          stopped = true;
+          for (const t of timers.values()) clearTimeout(t);
+          for (const w of watchers) {
+            try {
+              w.close();
+            } catch (_) {
+              /* ignore */
+            }
+          }
+          activityLog.event({ type: 'watch', event: 'stop', reason }, `[watch] stop (${reason})`);
+          console.log(chalk.dim(`\n🛑 watch stopped (${reason})`));
+          process.exit(0);
+        }
+
+        addTree(vflowDir);
+        activityLog.event({ type: 'watch', event: 'start' }, '[watch] start');
+        console.log(chalk.cyan.bold(`\n👀 Watching ${path.relative(projectRoot, vflowDir) || '.v-flow'}/ — logging changes to .v-flow/logs/`));
+        console.log(chalk.dim(`   (excluding: ${[...EXCLUDE_TOP].join(', ')}) — Ctrl-C to stop\n`));
+
+        process.on('SIGINT', () => stop('SIGINT'));
+        process.on('SIGTERM', () => stop('SIGTERM'));
+
+        const timeout = parseInt(options.timeout, 10) || 0;
+        if (timeout > 0) {
+          setTimeout(() => stop(`timeout ${timeout}s`), timeout * 1000);
+        }
+      })
+    );
+};

package/cli/index.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const pkg = require('../package.json');
+const activityLog = require('./lib/activity-log');
+
+// Capture all CLI output + persist a per-command record to .v-flow/logs/.
+activityLog.install();
+
+program
+  .name('v-flow')
+  .description('🚀 V Flow CLI — Agentic AI Software Development Process')
+  .version(pkg.version)
+  // ── Global Options ──
+  .option('--verbose', 'Show detailed output')
+  .option('--lang <language>', 'Set language (vi, en)', process.env.VFLOW_LANG || 'vi');
+
+// Make global options accessible to all commands via environment
+program.hook('preAction', (thisCommand, actionCommand) => {
+  const opts = program.opts();
+  if (opts.verbose) {
+    process.env.VFLOW_VERBOSE = '1';
+  }
+  if (opts.lang) {
+    process.env.VFLOW_LANG = opts.lang;
+  }
+  activityLog.setCommand(actionCommand.name(), process.argv.slice(2));
+});
+
+// Register commands
+require('./commands/init')(program);
+require('./commands/check')(program);
+require('./commands/status')(program);
+require('./commands/feature')(program);
+require('./commands/sync')(program);
+require('./commands/doctor')(program);
+require('./commands/upgrade')(program);
+require('./commands/validate')(program);
+require('./commands/score-card')(program);
+require('./commands/dev-quiz')(program);
+require('./commands/plugin')(program);
+require('./commands/log')(program);
+require('./commands/hooks')(program);
+require('./commands/watch')(program);
+
+program.parse();

package/cli/lib/ac-test-gate.js

@@ -0,0 +1,89 @@
+/**
+ * AC-PASS Gate — verify every spec Acceptance Criterion (AC-NN) is satisfied by
+ * a PASSING automated test, by reading a JUnit XML test report.
+ *
+ * This is the "living-spec" leg of validation: existing checks confirm each AC
+ * is *referenced* by a task/test-case on paper; this one reaches into the real
+ * test runner and fails when an AC has no PASSING test behind it.
+ *
+ * Convention: a testcase "covers" AC-NN when the AC id token appears in its
+ * `name`/`classname` (e.g. `it('AC-03: rejects expired token', ...)`), reusing
+ * the same AC-NN ids V Flow already threads through spec → task → test-case.
+ *
+ * JUnit XML is the universal interchange format — Jest (jest-junit), Vitest,
+ * pytest, go-junit-report, Maven Surefire, etc. all emit it.
+ */
+
+/**
+ * Parse JUnit XML into a flat list of testcases.
+ * A case counts as failed if it contains a <failure>/<error> child, skipped if
+ * it contains <skipped>. Anything else is a pass.
+ *
+ * @param {string} xml
+ * @returns {Array<{name,classname,label,passed,failed,skipped}>}
+ */
+function parseJUnitResults(xml) {
+  const cases = [];
+  if (!xml || typeof xml !== 'string') return cases;
+
+  // Match <testcase .../> (self-closing) or <testcase ...>...</testcase>.
+  const reCase = /<testcase\b([^>]*?)(?:\/>|>([\s\S]*?)<\/testcase>)/g;
+  let m;
+  while ((m = reCase.exec(xml)) !== null) {
+    const attrs = m[1] || '';
+    const inner = m[2] || '';
+    const name = (attrs.match(/\bname\s*=\s*"([^"]*)"/) || [])[1] || '';
+    const classname = (attrs.match(/\bclassname\s*=\s*"([^"]*)"/) || [])[1] || '';
+    const failed = /<(?:failure|error)\b/.test(inner);
+    const skipped = /<skipped\b/.test(inner);
+    cases.push({
+      name,
+      classname,
+      label: `${classname} ${name}`.trim(),
+      passed: !failed && !skipped,
+      failed,
+      skipped,
+    });
+  }
+  return cases;
+}
+
+/**
+ * Extract unique AC-NN ids from arbitrary text.
+ * @param {string} text
+ * @returns {string[]}
+ */
+function extractAcIds(text) {
+  return [...new Set((text || '').match(/\bAC-\d+\b/g) || [])];
+}
+
+/**
+ * Classify each spec AC against parsed test cases.
+ *
+ * @param {string[]} specAcs - AC ids declared in the spec (e.g. ['AC-01','AC-02'])
+ * @param {Array} cases - output of parseJUnitResults
+ * @returns {{ total:number, passed:string[], failing:string[], missing:string[] }}
+ *   passed  = AC referenced by ≥1 PASSING test
+ *   failing = AC referenced only by failing/skipped tests (no passing one)
+ *   missing = AC referenced by no test at all
+ */
+function checkAcTestPass(specAcs, cases) {
+  const acs = [...new Set(specAcs || [])];
+  const list = cases || [];
+  const passed = [];
+  const failing = [];
+  const missing = [];
+
+  for (const ac of acs) {
+    // Word-boundary match so AC-1 does not match AC-12.
+    const re = new RegExp(`\\b${ac}\\b`);
+    const refs = list.filter((c) => re.test(c.label));
+    if (refs.length === 0) missing.push(ac);
+    else if (refs.some((c) => c.passed)) passed.push(ac);
+    else failing.push(ac);
+  }
+
+  return { total: acs.length, passed, failing, missing };
+}
+
+module.exports = { parseJUnitResults, extractAcIds, checkAcTestPass };

package/cli/lib/activity-log.js

@@ -0,0 +1,209 @@
+/**
+ * Activity Log — Persistent, file-based audit of V-Flow usage.
+ *
+ * Records two surfaces into <projectRoot>/.v-flow/logs/:
+ *   • CLI runs    — every `v-flow <cmd>` invocation (args, exit code, duration,
+ *                   full console transcript). Captured automatically from
+ *                   cli/index.js via install().
+ *   • Agent steps — structured events appended by the `v-flow log` command,
+ *                   which the agentic workflow (AGENTS.md) calls at phase
+ *                   boundaries.
+ *
+ * Output files:
+ *   activity.jsonl  — one JSON object per line (machine-readable / grep / jq).
+ *   activity.log    — human-readable mirror.
+ *
+ * Design notes:
+ *   • Best-effort — every failure is swallowed; logging must NEVER break the CLI.
+ *   • Synchronous appends — survive process.exit()/crashes without an async flush.
+ *   • Disabled via VFLOW_NO_LOG=1. Custom path via VFLOW_LOG_DIR / VFLOW_LOG_FILE.
+ *   • Never auto-creates .v-flow/ (that would corrupt isInitialized()); only logs
+ *     into the project when .v-flow/ already exists (or an explicit override set).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const util = require('util');
+
+// eslint-disable-next-line no-control-regex
+const ANSI = /\x1b\[[0-9;]*m/g;
+const stripAnsi = (s) => String(s).replace(ANSI, '');
+
+let _installed = false;
+let _finalized = false;
+const _disabled = process.env.VFLOW_NO_LOG === '1';
+let _startTime = null;
+let _command = null; // { name, invocation }
+const _transcript = []; // buffered console output lines
+
+// Commands that write their own log entries — skip the auto CLI command record
+// (avoids double-logging and, for `watch`, a huge buffered transcript).
+const SELF_LOGGING = new Set(['log', 'watch']);
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function safeVersion() {
+  try {
+    return require('../../package.json').version;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Resolve the log directory.
+ * Priority: VFLOW_LOG_DIR > dir(VFLOW_LOG_FILE) > <cwd>/.v-flow/logs (only if
+ * .v-flow already exists). Returns null when logging should be skipped.
+ */
+function resolveLogDir() {
+  if (process.env.VFLOW_LOG_DIR) return process.env.VFLOW_LOG_DIR;
+  if (process.env.VFLOW_LOG_FILE) return path.dirname(process.env.VFLOW_LOG_FILE);
+  const vflow = path.join(process.cwd(), '.v-flow');
+  if (fs.existsSync(vflow)) return path.join(vflow, 'logs');
+  return null;
+}
+
+function jsonlPath(dir) {
+  if (process.env.VFLOW_LOG_FILE) return process.env.VFLOW_LOG_FILE;
+  return path.join(dir, 'activity.jsonl');
+}
+
+function logPath(dir) {
+  if (process.env.VFLOW_LOG_FILE) {
+    return `${process.env.VFLOW_LOG_FILE.replace(/\.jsonl?$/i, '')  }.log`;
+  }
+  return path.join(dir, 'activity.log');
+}
+
+/**
+ * Append one structured entry to activity.jsonl, plus an optional human-readable
+ * line to activity.log. Safe to call anytime — no-op if disabled or no dir.
+ * `ts` is added automatically.
+ *
+ * @param {object} entry        Fields to record (without ts).
+ * @param {string} [humanLine]  Suffix for the .log mirror (ts is prepended).
+ */
+function event(entry, humanLine) {
+  if (_disabled) return;
+  try {
+    const dir = resolveLogDir();
+    if (!dir) return;
+    fs.mkdirSync(dir, { recursive: true });
+    const record = { ts: nowIso(), ...entry };
+    fs.appendFileSync(jsonlPath(dir), `${JSON.stringify(record)}\n`);
+    if (humanLine) {
+      fs.appendFileSync(logPath(dir), `${record.ts}  ${humanLine}\n`);
+    }
+  } catch (_) {
+    /* logging must never break the CLI */
+  }
+}
+
+/**
+ * Install console capture + the exit hook that persists the CLI command record.
+ * Call once from cli/index.js. No-op if disabled.
+ */
+function install() {
+  if (_installed || _disabled) return;
+  _installed = true;
+  _startTime = Date.now();
+
+  const orig = {
+    log: console.log.bind(console),
+    info: console.info.bind(console),
+    warn: console.warn.bind(console),
+    error: console.error.bind(console),
+    debug: console.debug.bind(console),
+  };
+  const tee = (fn) => (...args) => {
+    try {
+      _transcript.push(stripAnsi(util.format(...args)));
+    } catch (_) {
+      /* ignore formatting errors */
+    }
+    fn(...args);
+  };
+  console.log = tee(orig.log);
+  console.info = tee(orig.info);
+  console.warn = tee(orig.warn);
+  console.error = tee(orig.error);
+  console.debug = tee(orig.debug);
+
+  process.on('exit', (code) => finalize(code));
+}
+
+/**
+ * Record which command is running. Called from index.js preAction hook.
+ */
+function setCommand(name, invocation) {
+  _command = { name, invocation: invocation || [] };
+}
+
+/**
+ * Persist the CLI command record (jsonl + transcript). Idempotent; runs on exit.
+ */
+function finalize(exitCode) {
+  if (_finalized || _disabled) return;
+  _finalized = true;
+  // Only persist when a real subcommand ran. Skip help/version/no-op and any
+  // self-logging command (avoids double/circular logging).
+  if (!_command || SELF_LOGGING.has(_command.name)) return;
+  try {
+    const dir = resolveLogDir();
+    if (!dir) return;
+    fs.mkdirSync(dir, { recursive: true });
+    const durationMs = _startTime ? Date.now() - _startTime : null;
+    const code = typeof exitCode === 'number' ? exitCode : process.exitCode || 0;
+    const record = {
+      ts: nowIso(),
+      type: 'cli',
+      cmd: _command.name,
+      invocation: _command.invocation,
+      exitCode: code,
+      durationMs,
+      cwd: process.cwd(),
+      version: safeVersion(),
+    };
+    fs.appendFileSync(jsonlPath(dir), `${JSON.stringify(record)}\n`);
+    const label = `v-flow ${record.invocation.join(' ')}`.trim();
+    const header = `\n── ${record.ts}  ${label}  (exit ${code}, ${durationMs}ms) ──\n`;
+    const body = _transcript.length ? `${_transcript.join('\n')}\n` : '';
+    fs.appendFileSync(logPath(dir), `${header}${body}`);
+  } catch (_) {
+    /* never break the CLI */
+  }
+}
+
+/**
+ * Read the last N entries from activity.jsonl (best-effort). Used by `v-flow log --tail`.
+ * @returns {object[]} parsed records (oldest → newest)
+ */
+function tail(n = 20) {
+  try {
+    const dir = resolveLogDir();
+    if (!dir) return [];
+    const file = jsonlPath(dir);
+    if (!fs.existsSync(file)) return [];
+    const lines = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean);
+    return lines.slice(-n).map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch (_) {
+        return { raw: line };
+      }
+    });
+  } catch (_) {
+    return [];
+  }
+}
+
+module.exports = {
+  install,
+  setCommand,
+  finalize,
+  event,
+  tail,
+  resolveLogDir,
+};

package/cli/lib/cli-error.js

@@ -0,0 +1,183 @@
+/**
+ * CLI Error Utilities — Unified error handling for V-Flow CLI
+ *
+ * Provides consistent error formatting, exit codes, and error types
+ * across all CLI commands.
+ */
+
+const chalk = require('chalk');
+
+// ============================================================
+// ERROR TYPES
+// ============================================================
+
+/**
+ * Base CLI error with exit code and user-friendly message
+ */
+class CliError extends Error {
+  constructor(message, { exitCode = 1, hint = null, cause = null } = {}) {
+    super(message);
+    this.name = 'CliError';
+    this.exitCode = exitCode;
+    this.hint = hint;
+    if (cause) this.cause = cause;
+  }
+}
+
+/**
+ * Project not initialized error
+ */
+class NotInitializedError extends CliError {
+  constructor() {
+    super('V Flow is not initialized (.v-flow/ not found)', {
+      exitCode: 1,
+      hint: 'Run: v-flow init',
+    });
+    this.name = 'NotInitializedError';
+  }
+}
+
+/**
+ * Feature not found error
+ */
+class FeatureNotFoundError extends CliError {
+  constructor(featureName) {
+    super(`Feature not found: ${featureName}`, {
+      exitCode: 1,
+      hint: 'Run: v-flow feature list to see available features',
+    });
+    this.name = 'FeatureNotFoundError';
+  }
+}
+
+/**
+ * Validation error (bad input, missing argument, etc.)
+ */
+class ValidationError extends CliError {
+  constructor(message, hint = null) {
+    super(message, { exitCode: 1, hint });
+    this.name = 'ValidationError';
+  }
+}
+
+// ============================================================
+// ERROR HANDLER
+// ============================================================
+
+/**
+ * Wrap a command action with consistent error handling.
+ *
+ * Usage:
+ *   program.command('foo').action(withErrorHandler(async (options) => { ... }));
+ *
+ * @param {Function} actionFn - async function(options) to wrap
+ * @returns {Function} wrapped function
+ */
+function withErrorHandler(actionFn) {
+  return async (...args) => {
+    try {
+      await actionFn(...args);
+    } catch (err) {
+      if (err instanceof CliError) {
+        console.error(chalk.red(`\n❌ ${err.message}`));
+        if (err.hint) {
+          console.error(chalk.dim(`   → ${err.hint}`));
+        }
+        console.error('');
+        process.exit(err.exitCode);
+      } else {
+        // Unexpected error — show stack in verbose mode
+        console.error(chalk.red(`\n❌ Unexpected error: ${err.message}`));
+        if (process.env.VFLOW_DEBUG || process.argv.includes('--debug')) {
+          console.error(chalk.dim(err.stack));
+        } else {
+          console.error(chalk.dim('   → Re-run with VFLOW_DEBUG=1 for full stack trace'));
+        }
+        console.error('');
+        process.exit(1);
+      }
+    }
+  };
+}
+
+// ============================================================
+// GUARD UTILITIES
+// ============================================================
+
+/**
+ * Assert project is initialized, throw NotInitializedError if not.
+ * @param {string} projectRoot
+ * @param {Function} isInitialized - from templates.js
+ */
+function requireInit(projectRoot, isInitialized) {
+  if (!isInitialized(projectRoot)) {
+    throw new NotInitializedError();
+  }
+}
+
+// ============================================================
+// FORMATTING UTILITIES
+// ============================================================
+
+/**
+ * Format bytes to human-readable string
+ */
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+/**
+ * Print a section header
+ */
+function printHeader(title) {
+  console.log(chalk.white.bold(`\n${title}`));
+}
+
+/**
+ * Print a success line
+ */
+function printOk(message) {
+  console.log(chalk.green(`   ✅ ${message}`));
+}
+
+/**
+ * Print a warning line
+ */
+function printWarn(message) {
+  console.log(chalk.yellow(`   ⚠️  ${message}`));
+}
+
+/**
+ * Print an error line
+ */
+function printError(message) {
+  console.log(chalk.red(`   ❌ ${message}`));
+}
+
+/**
+ * Print a dimmed info line
+ */
+function printDim(message) {
+  console.log(chalk.dim(`   ${message}`));
+}
+
+module.exports = {
+  // Error classes
+  CliError,
+  NotInitializedError,
+  FeatureNotFoundError,
+  ValidationError,
+  // Handler
+  withErrorHandler,
+  // Guards
+  requireInit,
+  // Formatting
+  formatBytes,
+  printHeader,
+  printOk,
+  printWarn,
+  printError,
+  printDim,
+};