@longph2102/v-flow 1.5.0

package/cli/lib/sync-core.js

@@ -0,0 +1,232 @@
+/**
+ * Sync Core — Shared sync logic for CLI
+ *
+ * Used by both `v-flow sync` and `v-flow init` commands.
+ * Single source of truth for file synchronization.
+ */
+
+const path = require('path');
+const fs = require('fs-extra');
+const crypto = require('crypto');
+const { TARGETS, convertToMdc, convertAgentToMdc } = require('./sync-targets');
+
+/**
+ * Compute SHA256 hash of content (first 12 chars)
+ */
+function hashContent(content) {
+  return crypto.createHash('sha256').update(content).digest('hex').slice(0, 12);
+}
+
+/**
+ * Sync a single file from source to destination
+ *
+ * @param {string} srcPath - Source file path
+ * @param {string} destPath - Destination file path
+ * @param {object} options - { dryRun, verbose, transform, stats }
+ * @returns {'added'|'updated'|'unchanged'}
+ */
+async function syncFile(srcPath, destPath, options = {}) {
+  const { dryRun = false, verbose = false, transform = null, stats = null } = options;
+
+  const srcContent = await fs.readFile(srcPath, 'utf8');
+  const destContent = transform ? transform(srcContent, path.basename(srcPath)) : srcContent;
+
+  if (fs.existsSync(destPath)) {
+    const existingContent = await fs.readFile(destPath, 'utf8');
+    const srcHash = hashContent(destContent);
+    const destHash = hashContent(existingContent);
+
+    if (srcHash === destHash) {
+      if (stats) stats.skipped++;
+      return 'unchanged';
+    }
+
+    if (stats) stats.synced++;
+    if (!dryRun) {
+      await fs.writeFile(destPath, destContent, 'utf8');
+    }
+    return 'updated';
+  } 
+    if (stats) stats.added++;
+    if (!dryRun) {
+      await fs.ensureDir(path.dirname(destPath));
+      await fs.writeFile(destPath, destContent, 'utf8');
+    }
+    return 'added';
+  
+}
+
+/**
+ * Sync all .md files from a source directory to a destination directory
+ *
+ * @param {string} srcDir - Source directory
+ * @param {string} destDir - Destination directory
+ * @param {object} options - { dryRun, verbose, transform, ext, stats }
+ * @returns {{ added: number, updated: number, unchanged: number }}
+ */
+async function syncDir(srcDir, destDir, options = {}) {
+  const { dryRun = false, verbose = false, transform = null, ext = '.md', stats = null } = options;
+
+  if (!fs.existsSync(srcDir)) return { added: 0, updated: 0, unchanged: 0 };
+
+  if (!dryRun) await fs.ensureDir(destDir);
+
+  const files = await fs.readdir(srcDir);
+  const targetFiles = files.filter(f => f.endsWith('.md'));
+
+  const result = { added: 0, updated: 0, unchanged: 0 };
+
+  for (const file of targetFiles) {
+    const srcPath = path.join(srcDir, file);
+    const destFileName = ext === '.mdc' ? file.replace(/\.md$/, '.mdc') : file;
+    const destPath = path.join(destDir, destFileName);
+
+    // Explicit transform wins; else `.mdc` implies the Cursor command transform.
+    const fileTransform = transform || (ext === '.mdc' ? convertToMdc : null);
+
+    try {
+      const status = await syncFile(srcPath, destPath, { dryRun, verbose, transform: fileTransform, stats });
+      result[status]++;
+    } catch (err) {
+      if (stats) stats.errors = (stats.errors || 0) + 1;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Copy framework RUNTIME ASSETS (templates + skills) into .v-flow/.
+ * Canonical locations agents reference: `.v-flow/templates/X` and
+ * `.v-flow/skills/.../scripts/*.sh`. Populated in EVERY project — INCLUDING the framework
+ * repo itself — so those paths resolve everywhere. Independent of AI-tool file sync, so it
+ * runs even with `init --skip-ai` (these are framework runtime, not AI integration files).
+ *
+ * @returns {{ templates: number, skills: number }} source-side file counts
+ */
+async function syncVFlowAssets({ projectRoot, sourceRoot, dryRun = false }) {
+  const vFlowDir = path.join(projectRoot, '.v-flow');
+  const out = { templates: 0, skills: 0 };
+
+  const countFiles = async (dir) => {
+    if (!fs.existsSync(dir)) return 0;
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    let n = 0;
+    for (const e of entries) {
+      if (e.isFile()) n++;
+      else if (e.isDirectory()) n += await countFiles(path.join(dir, e.name));
+    }
+    return n;
+  };
+
+  for (const name of ['templates', 'skills']) {
+    const src = path.join(sourceRoot, name);
+    if (!fs.existsSync(src)) continue;
+    out[name] = await countFiles(src);
+    if (!dryRun) {
+      const dest = path.join(vFlowDir, name);
+      await fs.ensureDir(dest);
+      await fs.copy(src, dest, { overwrite: true });
+    }
+  }
+  return out;
+}
+
+/**
+ * Select target descriptors from the registry for a given selector.
+ *
+ * @param {string} target - 'all' (or falsy) → every target; else match by key
+ * @returns {Array<object>} matching entries from TARGETS
+ */
+function selectTargets(target) {
+  return TARGETS.filter((t) => !target || target === 'all' || t.key === target);
+}
+
+/**
+ * Run full sync operation — sync commands, agents, skills, and global files
+ * for every selected target. Target specifics live in the config-driven
+ * registry (`sync-targets.js`); this function only walks it.
+ *
+ * @param {object} config
+ * @param {string} config.projectRoot - Target project root
+ * @param {string} config.sourceRoot - ADLC source root
+ * @param {boolean} [config.dryRun=false] - Dry run mode
+ * @param {boolean} [config.verbose=false] - Verbose output
+ * @param {string} [config.target='all'] - 'all' or a target key (antigravity, copilot, cursor, claude)
+ * @returns {{ added: number, synced: number, skipped: number, errors: number }}
+ */
+async function runSync(config) {
+  const {
+    projectRoot,
+    sourceRoot,
+    dryRun = false,
+    verbose = false,
+    target = 'all',
+  } = config;
+
+  const stats = { synced: 0, skipped: 0, added: 0, errors: 0 };
+  const syncOpts = { dryRun, verbose, stats };
+
+  // Source directories — vendor-neutral single source of truth.
+  const COMMANDS_DIR = path.join(sourceRoot, 'commands');
+  const AGENTS_DIR = path.join(sourceRoot, 'agents');
+  const SKILLS_DIR = path.join(sourceRoot, 'skills');
+
+  for (const t of selectTargets(target)) {
+    const dest = (segs) => path.join(projectRoot, ...segs);
+
+    // ── Commands ──
+    await syncDir(COMMANDS_DIR, dest(t.commands.dir), {
+      ...syncOpts,
+      ext: t.commands.ext || '.md',
+      transform: t.commands.transform || null,
+    });
+
+    // ── Agents ──
+    await syncDir(AGENTS_DIR, dest(t.agents.dir), {
+      ...syncOpts,
+      ext: t.agents.ext || '.md',
+      transform: t.agents.transform || null,
+    });
+
+    // ── Skills (bulk copy — preserves nested SKILL.md structure) ──
+    if (fs.existsSync(SKILLS_DIR) && !dryRun) {
+      await fs.copy(SKILLS_DIR, dest(t.skills.dir), { overwrite: true });
+    }
+
+    // ── Global instruction file(s) ──
+    for (const g of t.globals || []) {
+      const srcPath = path.join(sourceRoot, ...g.src);
+      if (!fs.existsSync(srcPath)) continue;
+      const destPath = dest(g.dest);
+      // noClobber: never overwrite a hand-authored file (e.g. CLAUDE.md).
+      if (g.noClobber && fs.existsSync(destPath)) {
+        stats.skipped++;
+        continue;
+      }
+      try {
+        await syncFile(srcPath, destPath, syncOpts);
+      } catch (err) {
+        stats.errors++;
+      }
+    }
+  }
+
+  // ── SYNC RUNTIME ASSETS (templates + skills) → .v-flow/ ──
+  // Extracted to syncVFlowAssets so `init --skip-ai` and `v-flow sync` install them too.
+  await syncVFlowAssets({ projectRoot, sourceRoot, dryRun });
+
+  return stats;
+}
+
+module.exports = {
+  hashContent,
+  convertToMdc,
+  convertAgentToMdc,
+  syncFile,
+  syncDir,
+  runSync,
+  syncVFlowAssets,
+  selectTargets,
+  TARGETS,
+};

package/cli/lib/sync-targets.js

@@ -0,0 +1,84 @@
+/**
+ * Sync Targets — Config-driven registry of supported AI tools.
+ *
+ * V Flow's single source of truth is vendor-neutral markdown (`commands/`,
+ * `agents/`, `skills/`, `AGENTS.md`). Each entry below declares HOW that
+ * canonical form maps into one AI tool's conventional folders.
+ *
+ * ➕ Adding a new vendor = add ONE entry here. No changes to sync-core.js.
+ *
+ * Target shape:
+ *   {
+ *     key:      string                      // CLI selector (`--target <key>`)
+ *     label:    string                      // human-readable name for output
+ *     commands: { dir: string[], ext?, transform? }   // slash commands
+ *     agents:   { dir: string[], ext?, transform? }   // agent personas
+ *     skills:   { dir: string[] }                      // bulk-copied
+ *     globals:  [{ src: string[], dest: string[], noClobber? }]  // instruction file(s)
+ *   }
+ *
+ * `dir`/`src`/`dest` are path segments joined under projectRoot (or sourceRoot
+ * for `src`). `ext: '.mdc'` renames `.md` → `.mdc` on write. `transform` is a
+ * (content, fileName) => string applied per file. `noClobber: true` means
+ * never overwrite an existing destination (for hand-authored files).
+ */
+
+/**
+ * Convert .md content to .mdc format for Cursor (inject `globs: *`).
+ */
+function convertToMdc(content, fileName) {
+  if (content.startsWith('---')) {
+    return content.replace(/^---\r?\n/, '---\nglobs: *\n');
+  }
+  const cmdName = fileName.replace(/\.md$/, '');
+  return `---\ndescription: Execute /${cmdName}\nglobs: *\n---\n${content}`;
+}
+
+/**
+ * Convert agent .md to .mdc for Cursor with persona frontmatter.
+ */
+function convertAgentToMdc(content, fileName) {
+  const agentName = fileName.replace(/\.md$/, '');
+  return `---\ndescription: Agent persona - ${agentName}\nglobs: *\nalwaysApply: false\n---\n${content}`;
+}
+
+const TARGETS = [
+  {
+    key: 'antigravity',
+    label: 'Antigravity',
+    commands: { dir: ['.agents', 'workflows'] },
+    agents: { dir: ['.agents', 'agents'] },
+    skills: { dir: ['.agents', 'skills'] },
+    globals: [{ src: ['AGENTS.md'], dest: ['AGENTS.md'] }],
+  },
+  {
+    key: 'copilot',
+    label: 'GitHub Copilot',
+    commands: { dir: ['.github', 'prompts'] },
+    agents: { dir: ['.github', 'agents'] },
+    skills: { dir: ['.github', 'skills'] },
+    globals: [
+      { src: ['.github', 'copilot-instructions.md'], dest: ['.github', 'copilot-instructions.md'] },
+    ],
+  },
+  {
+    key: 'cursor',
+    label: 'Cursor',
+    commands: { dir: ['.cursor', 'rules'], ext: '.mdc', transform: convertToMdc },
+    agents: { dir: ['.cursor', 'agents'], ext: '.mdc', transform: convertAgentToMdc },
+    skills: { dir: ['.cursor', 'skills'] },
+    globals: [{ src: ['AGENTS.md'], dest: ['.cursorrules'] }],
+  },
+  {
+    key: 'claude',
+    label: 'Claude Code',
+    commands: { dir: ['.claude', 'commands'] },
+    agents: { dir: ['.claude', 'agents'] },
+    skills: { dir: ['.claude', 'skills'] },
+    // CLAUDE.md is Claude Code's primary memory file and is very often
+    // hand-authored — so never clobber it. Created only when absent.
+    globals: [{ src: ['AGENTS.md'], dest: ['CLAUDE.md'], noClobber: true }],
+  },
+];
+
+module.exports = { TARGETS, convertToMdc, convertAgentToMdc };

package/cli/lib/templates.js

@@ -0,0 +1,268 @@
+const path = require('path');
+const fs = require('fs-extra');
+
+const MASTER_FLOW_DIR = '.v-flow';
+
+// ============================================================
+// CODEBASE SCANNER — Delegated to scanner.js (Phase 3 refactor)
+// ============================================================
+const { scanCodebase, generateContextMd } = require('./scanner');
+
+
+const COMMANDS_SOURCE = path.resolve(__dirname, '../../commands');
+const TEMPLATES_SOURCE = path.resolve(__dirname, '../../templates');
+
+/**
+ * Get the .v-flow directory path for a given project root
+ */
+function getVFlowDir(projectRoot) {
+  return path.join(projectRoot, MASTER_FLOW_DIR);
+}
+
+/**
+ * Check if v-flow is initialized in the given directory
+ */
+function isInitialized(projectRoot) {
+  return fs.existsSync(getVFlowDir(projectRoot));
+}
+
+/**
+ * Create the .v-flow directory structure
+ */
+async function scaffoldDirectories(projectRoot) {
+  const mfDir = getVFlowDir(projectRoot);
+  const dirs = [
+    mfDir,
+    path.join(mfDir, 'features'),
+    path.join(mfDir, 'modules'),
+    path.join(mfDir, 'knowledge'),
+    path.join(mfDir, 'knowledge', 'architecture-decisions'),
+    path.join(mfDir, 'knowledge', 'patterns'),
+    path.join(mfDir, 'knowledge', 'lessons-learned'),
+    path.join(mfDir, 'knowledge', 'golden-tests'),
+    path.join(mfDir, 'incidents'),
+  ];
+
+  for (const dir of dirs) {
+    await fs.ensureDir(dir);
+  }
+}
+
+/**
+ * Copy a template file to destination, replacing placeholders
+ */
+async function copyTemplate(templateName, destPath, replacements = {}) {
+  const srcPath = path.join(TEMPLATES_SOURCE, templateName);
+  if (!fs.existsSync(srcPath)) {
+    throw new Error(`Template not found: ${templateName}`);
+  }
+
+  let content = await fs.readFile(srcPath, 'utf8');
+
+  for (const [key, value] of Object.entries(replacements)) {
+    content = content.replace(new RegExp(`\\[${key}\\]`, 'g'), value);
+  }
+
+  await fs.writeFile(destPath, content, 'utf8');
+}
+
+const AGENTS_SOURCE = path.resolve(__dirname, '../../agents');
+const SKILLS_SOURCE = path.resolve(__dirname, '../../skills');
+const MODULE_CARD_TEMPLATES_SOURCE = path.resolve(__dirname, '../../templates/module-card');
+const PTYC_SCRIPTS_SOURCE = path.resolve(__dirname, '../../scripts/ptyc');
+const PTYC_TEMPLATES_SOURCE = path.resolve(__dirname, '../../templates/ptyc');
+
+/**
+ * Setup AI agent integration files (workflows, skills, agents)
+ */
+async function setupAgentFiles(projectRoot) {
+  // ==============================
+  // Antigravity: .agents/
+  // ==============================
+
+  // 1. Workflows (slash commands)
+  const agentsWorkflowDir = path.join(projectRoot, '.agents', 'workflows');
+  await fs.ensureDir(agentsWorkflowDir);
+
+  // 2. Skills (agent definitions as skills with SKILL.md)
+  const agentsSkillsDir = path.join(projectRoot, '.agents', 'skills');
+  await fs.ensureDir(agentsSkillsDir);
+
+  // ==============================
+  // GitHub Copilot: .github/
+  // ==============================
+
+  // 1. Prompts (slash commands)
+  const githubPromptsDir = path.join(projectRoot, '.github', 'prompts');
+  await fs.ensureDir(githubPromptsDir);
+
+  // 2. Agents (custom agent definitions)
+  const githubAgentsDir = path.join(projectRoot, '.github', 'agents');
+  await fs.ensureDir(githubAgentsDir);
+
+  // ==============================
+  // Cursor: .cursor/
+  // ==============================
+
+  // 1. Rules (slash commands)
+  const cursorRulesDir = path.join(projectRoot, '.cursor', 'rules');
+  await fs.ensureDir(cursorRulesDir);
+
+  // --- Copy command files to workflows & prompts ---
+  if (fs.existsSync(COMMANDS_SOURCE)) {
+    const commandFiles = await fs.readdir(COMMANDS_SOURCE);
+    for (const file of commandFiles) {
+      if (file.endsWith('.md')) {
+        const srcPath = path.join(COMMANDS_SOURCE, file);
+        await fs.copy(srcPath, path.join(agentsWorkflowDir, file));
+        await fs.copy(srcPath, path.join(githubPromptsDir, file));
+
+        // Cursor expects .mdc extension for rules
+        const mdcName = file.replace(/\.md$/, '.mdc');
+        let content = await fs.readFile(srcPath, 'utf8');
+
+        // If it already has YAML frontmatter, inject globs: *
+        if (content.startsWith('---')) {
+          content = content.replace(/^---\r?\n/, '---\nglobs: *\n');
+        } else {
+          // Otherwise prepend a basic frontmatter
+          const cmdName = file.replace(/\.md$/, '');
+          content = `---
+description: Execute /${cmdName}
+globs: *
+---
+${content}`;
+        }
+        await fs.writeFile(path.join(cursorRulesDir, mdcName), content, 'utf8');
+      }
+    }
+  }
+
+  // --- Copy skills to .agents/skills/ ---
+  if (fs.existsSync(SKILLS_SOURCE)) {
+    await fs.copy(SKILLS_SOURCE, agentsSkillsDir);
+  }
+
+  // --- Copy module-card templates to .v-flow/templates/module-card/ ---
+  // These templates are used by understand-agent to generate module cards
+  // with the correct structure (headings, tables, mermaid diagrams)
+  const moduleCardTemplatesDir = path.join(getVFlowDir(projectRoot), 'templates', 'module-card');
+  if (fs.existsSync(MODULE_CARD_TEMPLATES_SOURCE)) {
+    await fs.ensureDir(moduleCardTemplatesDir);
+    await fs.copy(MODULE_CARD_TEMPLATES_SOURCE, moduleCardTemplatesDir);
+  }
+
+  // --- Copy PTYC doc-export tooling INTO .v-flow/ (scripts + template) ---
+  // Used by /v.ba-to-ptyc (ba-to-ptyc-agent). Paths MUST live under .v-flow so they
+  // resolve in the target project — not the framework repo. render_ptyc.py finds its
+  // template via ../../templates/ptyc, which holds inside .v-flow too. Skips sample/ fixture.
+  const vflowRoot = getVFlowDir(projectRoot);
+  if (fs.existsSync(PTYC_SCRIPTS_SOURCE)) {
+    await fs.copy(PTYC_SCRIPTS_SOURCE, path.join(vflowRoot, 'scripts', 'ptyc'), {
+      filter: (src) => path.basename(src) !== 'sample' && !src.includes('__pycache__'),
+    });
+  }
+  if (fs.existsSync(PTYC_TEMPLATES_SOURCE)) {
+    await fs.copy(PTYC_TEMPLATES_SOURCE, path.join(vflowRoot, 'templates', 'ptyc'));
+  }
+
+  // --- Copy agent definitions to .agents/agents/ & .github/agents/ & .cursor/agents/ ---
+  if (fs.existsSync(AGENTS_SOURCE)) {
+    // Antigravity: .agents/agents/ (flat .md files — personas)
+    const antigravityAgentsDir = path.join(projectRoot, '.agents', 'agents');
+    await fs.ensureDir(antigravityAgentsDir);
+
+    // Cursor: .cursor/agents/ (.mdc files & agent personas)
+    const cursorAgentsDir = path.join(projectRoot, '.cursor', 'agents');
+    await fs.ensureDir(cursorAgentsDir);
+
+    const agentFiles = await fs.readdir(AGENTS_SOURCE);
+    for (const file of agentFiles) {
+      if (file.endsWith('.md')) {
+        const srcPath = path.join(AGENTS_SOURCE, file);
+
+        // Antigravity: flat .md file in .agents/agents/
+        await fs.copy(srcPath, path.join(antigravityAgentsDir, file));
+
+        // Copilot: flat .md file in .github/agents/
+        await fs.copy(srcPath, path.join(githubAgentsDir, file));
+
+        // Cursor: .mdc file with frontmatter in .cursor/agents/
+        const mdcName = file.replace(/\.md$/, '.mdc');
+        let content = await fs.readFile(srcPath, 'utf8');
+        const agentName = file.replace(/\.md$/, '');
+        content = `---\ndescription: Agent persona - ${agentName}\nglobs: *\nalwaysApply: false\n---\n${content}`;
+        await fs.writeFile(path.join(cursorAgentsDir, mdcName), content, 'utf8');
+      }
+    }
+  }
+}
+
+/**
+ * Copy AGENTS.md and copilot-instructions.md to project root
+ */
+async function setupAgentInstructionFiles(projectRoot, sourceRoot) {
+  const agentsFile = path.join(sourceRoot, 'AGENTS.md');
+  const copilotFile = path.join(sourceRoot, '.github', 'copilot-instructions.md');
+
+  if (fs.existsSync(agentsFile)) {
+    await fs.copy(agentsFile, path.join(projectRoot, 'AGENTS.md'));
+    // For Cursor, we use AGENTS.md as the global .cursorrules
+    await fs.copy(agentsFile, path.join(projectRoot, '.cursorrules'));
+  }
+
+  if (fs.existsSync(copilotFile)) {
+    const destDir = path.join(projectRoot, '.github');
+    await fs.ensureDir(destDir);
+    await fs.copy(copilotFile, path.join(destDir, 'copilot-instructions.md'));
+  }
+}
+
+/**
+ * List all features in .v-flow/features/
+ */
+async function listFeatures(projectRoot) {
+  const featuresDir = path.join(getVFlowDir(projectRoot), 'features');
+  if (!fs.existsSync(featuresDir)) return [];
+
+  const entries = await fs.readdir(featuresDir, { withFileTypes: true });
+  return entries.filter(e => e.isDirectory()).map(e => e.name);
+}
+
+/**
+ * Check which artifacts exist for a feature
+ */
+async function checkFeatureArtifacts(projectRoot, featureName) {
+  const featureDir = path.join(getVFlowDir(projectRoot), 'features', featureName);
+  const artifacts = [
+    { name: 'spec.md', phase: '[S.1] Specification' },
+    { name: '.flow-state.yaml', phase: '[S.1] Pipeline State' },
+    { name: 'plan.md', phase: '[B.0a] Planning' },
+    { name: 'tasks.md', phase: '[B.0a] Task Breakdown' },
+    { name: 'test-cases.md', phase: '[B.0b] Test Cases' },
+    { name: 'validation-report.md', phase: '[R.0] Master Check' },
+    { name: 'metrics-report.md', phase: '[M.0] Metrics' },
+    { name: 'operations-report.md', phase: '[O.0] Operations' },
+  ];
+
+  return artifacts.map(a => ({
+    ...a,
+    exists: fs.existsSync(path.join(featureDir, a.name)),
+  }));
+}
+
+module.exports = {
+  MASTER_FLOW_DIR,
+  getVFlowDir,
+  isInitialized,
+  scaffoldDirectories,
+  copyTemplate,
+  setupAgentFiles,
+  setupAgentInstructionFiles,
+  listFeatures,
+  checkFeatureArtifacts,
+  scanCodebase,
+  generateContextMd,
+};
+
+