@edupia-tutor/spec-driven-docs 0.14.0

package/bin/index.js

@@ -0,0 +1,598 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const ROOT = path.join(__dirname, '..');
+
+const pkg      = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+const VERSION  = pkg.version;
+
+const args = process.argv.slice(2);
+const isMigrateSpecs = args.includes('--migrate-specs');
+const isInit     = args.includes('--init');
+const isProject  = args.includes('--project');
+const installHooks = args.includes('--hooks');
+const showHelp   = args.includes('--help') || args.includes('-h');
+
+// --module <name> flag
+const moduleIdx  = args.indexOf('--module');
+const moduleName = moduleIdx !== -1 ? args[moduleIdx + 1] : null;
+
+// --services backend:java-spring,web-admin:react,app-mobile:flutter
+const servicesIdx = args.indexOf('--services');
+const servicesRaw = servicesIdx !== -1 ? args[servicesIdx + 1] : null;
+const serviceList = servicesRaw
+  ? servicesRaw.split(',').map(s => {
+      const [name, mod] = s.trim().split(':');
+      return { name: name.trim(), module: (mod || '').trim() };
+    }).filter(s => s.name)
+  : [];
+
+const isUmbrella    = args.includes('--umbrella');
+const specSourceIdx = args.indexOf('--spec-source');
+const specSource    = specSourceIdx !== -1 ? args[specSourceIdx + 1] : null;
+
+const AVAILABLE_MODULES = [
+  'java-spring', 'angular', 'react', 'nextjs',
+  'dotnet', 'golang', 'php-laravel', 'context-engineering',
+  'flutter', 'react-native', 'ios-swiftui', 'android-compose',
+];
+
+// Language/framework labels per module (for generated project-context.yaml)
+const MODULE_STACK = {
+  'java-spring':      { language: 'Java 17',      framework: 'Spring Boot 3.x' },
+  'golang':           { language: 'Go',            framework: 'Gin / Echo' },
+  'dotnet':           { language: 'C#',            framework: '.NET / ASP.NET Core' },
+  'php-laravel':      { language: 'PHP',           framework: 'Laravel' },
+  'context-engineering': { language: 'TypeScript', framework: 'Node.js' },
+  'react':            { language: 'TypeScript',    framework: 'React' },
+  'nextjs':           { language: 'TypeScript',    framework: 'Next.js' },
+  'vue':              { language: 'TypeScript',    framework: 'Vue 3' },
+  'nuxt':             { language: 'TypeScript',    framework: 'Nuxt 3' },
+  'angular':          { language: 'TypeScript',    framework: 'Angular' },
+  'flutter':          { language: 'Dart',          framework: 'Flutter' },
+  'react-native':     { language: 'TypeScript',    framework: 'React Native / Expo' },
+  'ios-swiftui':      { language: 'Swift',         framework: 'SwiftUI' },
+  'android-compose':  { language: 'Kotlin',        framework: 'Jetpack Compose' },
+};
+
+if (showHelp) {
+  console.log('Usage: npx @edupia-tutor/spec-driven-docs [options]');
+  console.log('');
+  console.log('Install modes:');
+  console.log('  --init                    Install framework to .agent/ + create shortcuts in .claude/commands/');
+  console.log('                            Recommended for new projects. Run upgrade.sh to upgrade later.');
+  console.log('  --init --umbrella         Umbrella repo setup: installs framework at umbrella level only.');
+  console.log('                            Generates project-context.yaml with services routing.');
+  console.log('                            Does NOT install into service submodule directories.');
+  console.log('  --project                 Install full commands to ./.claude/commands/ (project-scoped, legacy)');
+  console.log('  (no flag)                 Install full commands to ~/.claude/commands/ (global, legacy)');
+  console.log('');
+  console.log('Maintenance:');
+  console.log('  --migrate-specs           Migrate an existing project from the legacy artifact-type-first');
+  console.log('                            spec layout (specs/prd, specs/bdd, ...) to the feature-package');
+  console.log('                            layout (specs/{domain}/{prd-slug}/{prd.md,bdd/,tech-docs/,...}).');
+  console.log('                            DRY-RUN by default; add --apply to execute. Uses git mv when possible.');
+  console.log('');
+  console.log('Options:');
+  console.log('  --module <name>           Copy stack module to .agent/modules/<name>/');
+  console.log('  --services <list>         Monorepo setup: install into each service subfolder in one command.');
+  console.log('                            Format: name:module,name:module,...');
+  console.log('                            Example: backend:java-spring,web-admin:react,app-mobile:flutter');
+  console.log('  --umbrella                Umbrella mode (use with --init). See above.');
+  console.log('  --spec-source <path>      Path to PO spec submodule (e.g. free-trial-specs).');
+  console.log('                            Auto-configures prd_dir, design_spec_dir, domain_knowledge_dir.');
+  console.log('  --hooks                   Install data-guard hook to .claude/hooks/ + update .claude/settings.json');
+  console.log('');
+  console.log('Available modules:');
+  AVAILABLE_MODULES.forEach(m => console.log(`  ${m}`));
+  console.log('');
+  console.log('Examples:');
+  console.log('  npx @edupia-tutor/spec-driven-docs --init                         # single-service project');
+  console.log('  npx @edupia-tutor/spec-driven-docs --init --module java-spring    # with stack module');
+  console.log('  npx @edupia-tutor/spec-driven-docs --init \\');
+  console.log('    --services backend:java-spring,web-admin:react,app-mobile:flutter  # monorepo setup');
+  console.log('  npx @edupia-tutor/spec-driven-docs --init --umbrella \\');
+  console.log('    --spec-source free-trial-specs \\');
+  console.log('    --services mass-product-web:nextjs   # umbrella with one FE service');
+  console.log('  npx @edupia-tutor/spec-driven-docs --project --hooks              # legacy project install');
+  process.exit(0);
+}
+
+// ── --migrate-specs: migrate a consumer repo to the feature-package layout ──
+// Runs BEFORE the build step — this operates on the user's specs, not the package.
+if (isMigrateSpecs) {
+  require(path.join(__dirname, '..', 'scripts', 'migrate-specs.js'));
+  return; // migrate-specs.js calls process.exit itself
+}
+
+// ── Step 1: Build .tmpl → .md ─────────────────────────────────────────────
+const buildScript = path.join(__dirname, 'build.js');
+if (fs.existsSync(buildScript)) {
+  try {
+    require(buildScript);
+  } catch (err) {
+    console.error('Build step failed:', err.message);
+    process.exit(1);
+  }
+}
+
+// ── --init mode: install to .agent/ + create .claude/commands/ shortcuts ─────
+if (isInit) {
+  const coreDir = path.join(ROOT, 'core');
+
+  if (!fs.existsSync(coreDir)) {
+    console.error('');
+    console.error('❌ core/ directory not found.');
+    console.error('   The package may not have been built correctly.');
+    process.exit(1);
+  }
+
+  const projectRoot      = process.cwd();
+  const agentDir         = path.join(projectRoot, '.agent');
+  const claudeCommandsDir = path.join(projectRoot, '.claude', 'commands');
+  const frameworkVersion = fs.readFileSync(path.join(coreDir, 'FRAMEWORK_VERSION'), 'utf8').trim();
+
+  console.log('');
+  console.log('╔══════════════════════════════════════════╗');
+  console.log('║     Spec-Driven Docs — Project Init       ║');
+  console.log(`║     v${frameworkVersion}  (Edupia Team)                ║`);
+  console.log('╚══════════════════════════════════════════╝');
+  console.log('');
+  console.log(`Target : ${agentDir}`);
+  if (moduleName) console.log(`Module : ${moduleName}`);
+  console.log('');
+
+  // 1. Copy core/** → .agent/**
+  console.log('Installing framework files to .agent/ ...');
+  console.log('');
+  copyDirRecursive(coreDir, agentDir);
+
+  const agentSubdirs = fs.readdirSync(agentDir, { withFileTypes: true })
+    .filter(e => e.isDirectory())
+    .map(e => e.name);
+  for (const sub of agentSubdirs) {
+    console.log(`  ✅ .agent/${sub}/`);
+  }
+  console.log(`  ✅ .agent/FRAMEWORK_VERSION  (v${frameworkVersion})`);
+
+  // 2. Create .claude/commands/ shortcuts that delegate to .agent/commands/
+  console.log('');
+  console.log('Creating .claude/commands/ shortcuts ...');
+  console.log('');
+  fs.mkdirSync(claudeCommandsDir, { recursive: true });
+
+  const agentCommandsDir = path.join(agentDir, 'commands');
+  const commandFiles = fs.readdirSync(agentCommandsDir).filter(f => f.endsWith('.md'));
+  const failedShortcuts = [];
+
+  for (const cmdFile of commandFiles) {
+    const cmdName = cmdFile.replace('.md', '');
+    const shortcut =
+      `# /${cmdName}\n` +
+      `\n` +
+      `Read the full command definition from \`.agent/commands/${cmdFile}\`` +
+      ` and execute it with arguments: $ARGUMENTS\n`;
+    try {
+      fs.writeFileSync(path.join(claudeCommandsDir, cmdFile), shortcut, 'utf8');
+      console.log(`  ✅ /${cmdName}`);
+    } catch {
+      console.log(`  ❌ /${cmdName}  (failed to write shortcut)`);
+      failedShortcuts.push(cmdName);
+    }
+  }
+
+  // 3. Install module (optional --module flag)
+  if (moduleName) {
+    console.log('');
+    if (!AVAILABLE_MODULES.includes(moduleName)) {
+      console.log(`⚠️  Unknown module: "${moduleName}"`);
+      console.log(`   Available: ${AVAILABLE_MODULES.join(', ')}`);
+    } else {
+      const srcModuleDir  = path.join(ROOT, 'modules', moduleName);
+      const destModuleDir = path.join(agentDir, 'modules', moduleName);
+      fs.mkdirSync(destModuleDir, { recursive: true });
+      copyDirRecursive(srcModuleDir, destModuleDir);
+      console.log(`✅ Module "${moduleName}" installed to: .agent/modules/${moduleName}`);
+    }
+  }
+
+  // 4. Install data-guard hook (optional --hooks flag)
+  if (installHooks) {
+    console.log('');
+    installDataGuardHook();
+  }
+
+  // 5-alt. Umbrella mode: generate umbrella project-context.yaml (do NOT install into submodules)
+  if (isUmbrella) {
+    const rootCtxPath = path.join(agentDir, 'project-context.yaml');
+    if (!fs.existsSync(rootCtxPath)) {
+      const specSrc = specSource || 'TODO-spec-submodule';
+
+      let servicesBlock = '';
+      if (serviceList.length > 0) {
+        servicesBlock = serviceList.map(s => [
+          `  ${s.name}:`,
+          `    path: "${s.name}"`,
+          `    module: "${s.module || 'TODO'}"`,
+          `    specs_dir: "${s.name}/specs/bdd"`,
+        ].join('\n')).join('\n');
+      } else {
+        servicesBlock = [
+          `  # {domain}:`,
+          `  #   path: "{service-submodule-dir}"`,
+          `  #   module: "{stack-module}"`,
+          `  #   specs_dir: "{service-dir}/specs/bdd"`,
+        ].join('\n');
+      }
+
+      const domainsBlock = serviceList.length > 0
+        ? serviceList.map(s => `  - "${s.name}"`).join('\n')
+        : `  - "TODO"`;
+
+      const umbrellaYaml = [
+        `project:`,
+        `  name: "${path.basename(projectRoot)}"`,
+        `  description: ""`,
+        ``,
+        `setup:`,
+        `  mode: umbrella`,
+        `  spec_source: "${specSrc}"`,
+        ``,
+        `# Paths auto-derived from spec_source by context-loader.`,
+        `# Override here only if your structure differs.`,
+        `paths:`,
+        `  prd_dir:              "${specSrc}/specs/prd"`,
+        `  design_spec_dir:      "${specSrc}/specs/design-spec"`,
+        `  tech_docs_dir:        "${specSrc}/specs/tech-docs"   # API contract — shared (BE pushes here, FE/App read via /sync)`,
+        `  domain_knowledge_dir: "${specSrc}/specs/domain-knowledge"`,
+        `  business_dictionary:  "${specSrc}/specs/domain-knowledge/business-dictionary.md"`,
+        `  core_entities:        "${specSrc}/specs/domain-knowledge/core-entities.md"`,
+        `  product_definitions_dir: "${specSrc}/specs/product-definition"`,
+        `  refinement_dir:       ".agent/review"`,
+        `  trace_dir:            ".trace"`,
+        ``,
+        `# Domain → service submodule routing.`,
+        `# Each key must match @trace.domain in your PRD files.`,
+        `services:`,
+        servicesBlock,
+        ``,
+        `tech_stack:`,
+        `  language: multi-service`,
+        `  module: ""`,
+        ``,
+        `conventions:`,
+        `  ticket_prefix: FEAT`,
+        ``,
+        `domains:`,
+        domainsBlock,
+        ``,
+      ].join('\n');
+
+      fs.writeFileSync(rootCtxPath, umbrellaYaml, 'utf8');
+      console.log('');
+      console.log('  ✅ .agent/project-context.yaml (umbrella mode, generated)');
+      if (specSource) console.log(`     spec_source : ${specSrc}`);
+      if (serviceList.length > 0) console.log(`     services    : ${serviceList.map(s => s.name).join(', ')}`);
+    } else {
+      console.log('  ℹ️  .agent/project-context.yaml (already exists — skipped)');
+    }
+  }
+
+  // 5. Monorepo: install into each service subfolder
+  if (serviceList.length > 0) {
+    console.log('');
+    console.log(`Setting up ${serviceList.length} service workspace(s)...`);
+
+    for (const svc of serviceList) {
+      const svcDir         = path.join(projectRoot, svc.name);
+      const svcAgentDir    = path.join(svcDir, '.agent');
+      const svcClaudeCmds  = path.join(svcDir, '.claude', 'commands');
+
+      console.log('');
+      console.log(`  ── ${svc.name} (${svc.module || 'no module'}) ──`);
+
+      // Create service dir if needed
+      fs.mkdirSync(svcDir, { recursive: true });
+
+      // Copy core → service/.agent/
+      copyDirRecursive(coreDir, svcAgentDir);
+      console.log(`  ✅ ${svc.name}/.agent/`);
+
+      // Install module
+      if (svc.module) {
+        if (!AVAILABLE_MODULES.includes(svc.module)) {
+          console.log(`  ⚠️  Unknown module "${svc.module}" — skipped`);
+        } else {
+          const srcMod  = path.join(ROOT, 'modules', svc.module);
+          const destMod = path.join(svcAgentDir, 'modules', svc.module);
+          if (fs.existsSync(srcMod)) {
+            fs.mkdirSync(destMod, { recursive: true });
+            copyDirRecursive(srcMod, destMod);
+            console.log(`  ✅ ${svc.name}/.agent/modules/${svc.module}/`);
+          }
+        }
+      }
+
+      // Create .claude/commands/ shortcuts
+      fs.mkdirSync(svcClaudeCmds, { recursive: true });
+      const svcCmdFiles = fs.readdirSync(path.join(svcAgentDir, 'commands')).filter(f => f.endsWith('.md'));
+      for (const cmdFile of svcCmdFiles) {
+        const cmdName = cmdFile.replace('.md', '');
+        const shortcut =
+          `# /${cmdName}\n\nRead the full command definition from \`.agent/commands/${cmdFile}\`` +
+          ` and execute it with arguments: $ARGUMENTS\n`;
+        fs.writeFileSync(path.join(svcClaudeCmds, cmdFile), shortcut, 'utf8');
+      }
+      console.log(`  ✅ ${svc.name}/.claude/commands/ (${svcCmdFiles.length} shortcuts)`);
+
+      // Generate project-context.yaml (only if not already present)
+      const ctxPath = path.join(svcAgentDir, 'project-context.yaml');
+      if (!fs.existsSync(ctxPath)) {
+        const stack = MODULE_STACK[svc.module] || { language: 'TODO', framework: 'TODO' };
+        const yaml = [
+          `project:`,
+          `  name: ${path.basename(projectRoot)} — ${svc.name}`,
+          ``,
+          `tech_stack:`,
+          `  language: ${stack.language}`,
+          `  framework: ${stack.framework}`,
+          `  module: ${svc.module || 'TODO'}`,
+          ``,
+          `conventions:`,
+          `  ticket_prefix: FEAT`,
+          ``,
+          `paths:`,
+          `  specs_dir: ../specs/bdd`,
+          `  prd_dir: ../specs/prd`,
+          `  tech_docs_dir: ../specs/tech-docs`,
+          `  domain_knowledge_dir: ../specs/domain-knowledge`,
+          `  business_dictionary: ../specs/domain-knowledge/business-dictionary.md`,
+          `  core_entities: ../specs/domain-knowledge/core-entities.md`,
+          `  refinement_dir: ../specs/.review`,
+          `  product_definitions_dir: ../specs/product-definition`,
+          `  trace_dir: ../.trace`,
+          ``,
+        ].join('\n');
+        fs.writeFileSync(ctxPath, yaml, 'utf8');
+        console.log(`  ✅ ${svc.name}/.agent/project-context.yaml (generated)`);
+      } else {
+        console.log(`  ℹ️  ${svc.name}/.agent/project-context.yaml (already exists — skipped)`);
+      }
+    }
+
+    // Generate root project-context.yaml for PO/BA (only if not present)
+    const rootCtxPath = path.join(agentDir, 'project-context.yaml');
+    if (!fs.existsSync(rootCtxPath)) {
+      const svcYaml = serviceList.map(s => [
+        `  - name: ${s.name}`,
+        `    module: ${s.module || 'TODO'}`,
+        `    description: ""`,
+      ].join('\n')).join('\n');
+      const rootYaml = [
+        `project:`,
+        `  name: ${path.basename(projectRoot)}`,
+        ``,
+        `tech_stack:`,
+        `  language: multi-service`,
+        ``,
+        `services:`,
+        svcYaml,
+        ``,
+        `conventions:`,
+        `  ticket_prefix: FEAT`,
+        ``,
+        `paths:`,
+        `  specs_dir: specs/bdd`,
+        `  prd_dir: specs/prd`,
+        `  tech_docs_dir: specs/tech-docs`,
+        `  domain_knowledge_dir: specs/domain-knowledge`,
+        `  business_dictionary: specs/domain-knowledge/business-dictionary.md`,
+        `  core_entities: specs/domain-knowledge/core-entities.md`,
+        `  refinement_dir: specs/.review`,
+        `  product_definitions_dir: specs/product-definition`,
+        `  trace_dir: .trace`,
+        ``,
+      ].join('\n');
+      fs.writeFileSync(rootCtxPath, rootYaml, 'utf8');
+      console.log('');
+      console.log('  ✅ .agent/project-context.yaml (root — PO/BA workspace, generated)');
+    }
+  }
+
+  // 6. Summary
+  console.log('');
+  if (failedShortcuts.length > 0) {
+    console.log(`⚠️  ${commandFiles.length - failedShortcuts.length}/${commandFiles.length} shortcuts created.`);
+    process.exit(1);
+  }
+  console.log(`✅ Framework v${frameworkVersion} installed!`);
+  console.log('');
+  if (isUmbrella) {
+    console.log('Umbrella workspace ready:');
+    console.log('  Open Claude Code at project root (umbrella)');
+    console.log('  Agent reads specs from: ' + (specSource || 'spec_source in project-context.yaml'));
+    if (serviceList.length > 0) {
+      console.log('  Service submodules configured:');
+      serviceList.forEach(s => console.log(`    ${s.name} (${s.module || 'no module'})`));
+    }
+    console.log('');
+    console.log('Next steps:');
+    console.log('  1. Review .agent/project-context.yaml — update service paths + domain names');
+    console.log('  2. Run /setup-ai-first in Claude Code');
+    console.log('  3. Commit .agent/ to git');
+    console.log('');
+  } else
+  if (serviceList.length > 0) {
+    console.log('Monorepo workspaces ready:');
+    console.log('  PO/BA    → open Claude Code at project root');
+    serviceList.forEach(s => {
+      console.log(`  ${s.name.padEnd(10)} → open Claude Code at ./${s.name}/`);
+    });
+    console.log('');
+    console.log('Next steps:');
+    console.log('  1. Fill in CLAUDE.md in each service subfolder (architecture + coding standards)');
+    console.log('  2. Fill in .agent/project-context.yaml in each subfolder (review generated values)');
+    console.log('  3. PO/BA: open root in Claude Code and run /setup-ai-first');
+    console.log('  4. Commit everything to git so the whole team has the framework');
+  } else {
+    console.log('Next steps:');
+    console.log('  1. Open Claude Code and run /setup-ai-first');
+    console.log('  2. Commit .agent/ to git so your whole team has the framework');
+  }
+  console.log('');
+  console.log('To upgrade later:  bash scripts/upgrade.sh');
+  console.log('                   (or: npx @edupia-tutor/spec-driven-docs@latest --init)');
+  console.log('');
+  process.exit(0);
+}
+
+// ── Banner (legacy --project / global modes) ──────────────────────────────
+const targetDir = isProject
+  ? path.join(process.cwd(), '.claude', 'commands')
+  : path.join(os.homedir(), '.claude', 'commands');
+
+const scope = isProject ? 'project' : 'global';
+
+console.log('');
+console.log('╔══════════════════════════════════════════╗');
+console.log('║     Spec-Driven Docs — CLI Installer      ║');
+console.log(`║     v${VERSION}  (Edupia Team)                ║`);
+console.log('╚══════════════════════════════════════════╝');
+console.log('');
+console.log(`Scope  : ${scope}`);
+console.log(`Target : ${targetDir}`);
+if (moduleName)    console.log(`Module : ${moduleName}`);
+if (installHooks)  console.log('Hooks  : enabled');
+console.log('');
+
+// ── Step 2: Install commands ──────────────────────────────────────────────
+fs.mkdirSync(targetDir, { recursive: true });
+
+const commandsDir = path.join(ROOT, 'commands');
+const commands    = fs.readdirSync(commandsDir).filter(f => f.endsWith('.md'));
+const failed      = [];
+
+for (const cmd of commands) {
+  try {
+    fs.copyFileSync(path.join(commandsDir, cmd), path.join(targetDir, cmd));
+    console.log(`  ✅ ${cmd.replace('.md', '')}`);
+  } catch {
+    console.log(`  ❌ ${cmd.replace('.md', '')} (failed)`);
+    failed.push(cmd);
+  }
+}
+
+console.log('');
+
+if (failed.length > 0) {
+  console.log(`⚠️  Installed ${commands.length - failed.length}/${commands.length} commands. Failed: ${failed.join(', ')}`);
+  process.exit(1);
+}
+
+console.log(`✅ Installed ${commands.length}/${commands.length} commands to:`);
+console.log(`   ${targetDir}`);
+
+// ── Step 3: Install module (optional) ─────────────────────────────────────
+if (moduleName) {
+  console.log('');
+  if (!AVAILABLE_MODULES.includes(moduleName)) {
+    console.log(`⚠️  Unknown module: "${moduleName}"`);
+    console.log(`   Available: ${AVAILABLE_MODULES.join(', ')}`);
+    process.exit(1);
+  }
+
+  const srcModuleDir  = path.join(ROOT, 'modules', moduleName);
+  const destModuleDir = path.join(process.cwd(), '.agent', 'modules', moduleName);
+
+  fs.mkdirSync(destModuleDir, { recursive: true });
+  copyDirRecursive(srcModuleDir, destModuleDir);
+
+  console.log(`✅ Module "${moduleName}" installed to:`);
+  console.log(`   ${destModuleDir}`);
+}
+
+// ── Step 4: Install data-guard hook (optional, --hooks flag) ──────────────
+if (installHooks) {
+  console.log('');
+  installDataGuardHook();
+}
+
+// ── Summary ───────────────────────────────────────────────────────────────
+console.log('');
+console.log('Next steps:');
+console.log('  1. Open your project in Claude Code');
+console.log('  2. Type /setup-ai-first to initialize the workflow');
+console.log('  3. Type / to browse all available commands');
+if (!moduleName) {
+  console.log('');
+  console.log(`Tip: re-run with --module <name> to install a stack profile.`);
+  console.log(`     Available: ${AVAILABLE_MODULES.join(', ')}`);
+}
+if (!installHooks) {
+  console.log('');
+  console.log('Tip: re-run with --hooks to install data-guard hook (sensitive file protection).');
+}
+console.log('');
+
+// ── Helpers ───────────────────────────────────────────────────────────────
+
+function copyDirRecursive(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src)) {
+    const srcPath  = path.join(src, entry);
+    const destPath = path.join(dest, entry);
+    if (fs.statSync(srcPath).isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function installDataGuardHook() {
+  const projectRoot = process.cwd();
+  const hooksDir    = path.join(projectRoot, '.claude', 'hooks');
+  const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+
+  // 1. Copy hook script
+  fs.mkdirSync(hooksDir, { recursive: true });
+  const srcHook  = path.join(ROOT, 'hooks', 'data-guard.js');
+  const destHook = path.join(hooksDir, 'data-guard.js');
+  fs.copyFileSync(srcHook, destHook);
+  console.log(`  ✅ Hook copied to: .claude/hooks/data-guard.js`);
+
+  // 2. Update .claude/settings.json
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch {}
+  }
+
+  // Merge: add PreToolUse hook if not already present
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
+
+  const hookEntry = {
+    matcher: 'Read|Write|Edit|Bash',
+    hooks: [{ type: 'command', command: 'node .claude/hooks/data-guard.js' }],
+  };
+
+  const alreadyRegistered = settings.hooks.PreToolUse.some(
+    h => h.hooks && h.hooks.some(hh => hh.command && hh.command.includes('data-guard.js'))
+  );
+
+  if (!alreadyRegistered) {
+    settings.hooks.PreToolUse.push(hookEntry);
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+    console.log(`  ✅ Hook registered in: .claude/settings.json`);
+  } else {
+    console.log(`  ℹ️  Hook already registered in .claude/settings.json`);
+  }
+
+  console.log('');
+  console.log('  🔒 Data guard active — AI will be blocked from reading:');
+  console.log('     .env*, *.key, *.pem, *secret*, *password*, *credential*');
+  console.log('     application-prod.*, appsettings.Production.json, ...');
+}