@massu/core 0.9.2 → 1.1.0

package/src/commands/init.ts

@@ -2,29 +2,48 @@
 // Licensed under BSL 1.1 - see LICENSE file for details.
 
 /**
- * `massu init` — One-command full project setup.
+ * `massu init` — One-command, detection-driven project setup.
  *
- * 1. Detects project framework (scans package.json)
- * 2. Generates massu.config.yaml (or preserves existing)
- * 3. Registers MCP server in .mcp.json (creates or merges)
- * 4. Installs all 15 hooks in .claude/settings.local.json
- * 5. Installs slash commands into .claude/commands/
- * 6. Initializes memory directory
- * 7. Prints success summary
+ * Phase 3 rewrite (2026-04-19): replaces the JS/TS template copier (old
+ * detectFramework/generateConfig path, root cause of Hedge-style stale configs)
+ * with a flow that runs the Phase 1 detection engine (`runDetection`) and
+ * generates a v2 schema_version=2 `massu.config.yaml` that reflects the
+ * actual repo layout (languages, source_dirs, verification commands, domains).
+ *
+ * Subcommands / flags:
+ *   massu init                 Interactive — prompts on overwrite, stack confirm
+ *   massu init --ci            Non-interactive; errors on conflict
+ *   massu init --force         Overwrite existing config without prompting
+ *   massu init --template X    Greenfield template (skips detection entirely)
+ *
+ * Post-write guarantees:
+ *   - Atomic (tmp-file + rename; partial writes never persist)
+ *   - Zod-validated (load via getConfig — bad config is rolled back + deleted)
+ *   - declared source_dirs must exist on disk
+ *
+ * Legacy exports preserved for cli.test.ts and install-hooks.ts:
+ *   detectFramework, detectPython, generateConfig, registerMcpServer,
+ *   installHooks, buildHooksConfig, resolveHooksDir, initMemoryDir, runInit.
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, chmodSync } from 'fs';
 import { resolve, basename, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { homedir } from 'os';
+import { stringify as yamlStringify, parse as yamlParse } from 'yaml';
 import { backfillMemoryFiles } from '../memory-file-ingest.ts';
-import { buildClaudeMdContent } from '../claude-md-templates.ts';
+import { getConfig, resetConfig } from '../config.ts';
+import { installCommands } from './install-commands.ts';
+import {
+  runDetection,
+  type DetectionResult,
+  type SupportedLanguage,
+  type VRCommandSet,
+} from '../detect/index.ts';
+import { computeFingerprint } from '../detect/drift.ts';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-import { stringify as yamlStringify } from 'yaml';
-import { getConfig } from '../config.ts';
-import { installCommands } from './install-commands.ts';
 
 // ============================================================
 // Types
@@ -38,8 +57,6 @@ interface FrameworkDetection {
 }
 
 interface InitResult {
-  claudeMdCreated: boolean;
-  claudeMdSkipped: boolean;
   configCreated: boolean;
   configSkipped: boolean;
   mcpRegistered: boolean;
@@ -49,8 +66,32 @@ interface InitResult {
   framework: FrameworkDetection;
 }
 
+export interface InitOptions {
+  /** Skip all prompts; fail on conflict. Also set when stdin is not a TTY. */
+  ci?: boolean;
+  /** Overwrite existing config without prompting (ignored in --ci mode). */
+  force?: boolean;
+  /** Template name for greenfield projects (skips detection). */
+  template?: string;
+  /** Skip hook/command/memory install side-effects. Used in tests. */
+  skipSideEffects?: boolean;
+  /** Override cwd (tests). */
+  cwd?: string;
+  /** Suppress console output. */
+  silent?: boolean;
+}
+
+export interface GenerateConfigV2Options {
+  /** Project root to generate against. Detection is run on this directory. */
+  projectRoot: string;
+  /** Pre-computed detection result (reused if already available). */
+  detection?: DetectionResult;
+  /** Project name override (default = basename of projectRoot). */
+  projectName?: string;
+}
+
 // ============================================================
-// Framework Auto-Detection
+// Legacy Framework Auto-Detection (preserved for cli.test.ts)
 // ============================================================
 
 export function detectFramework(projectRoot: string): FrameworkDetection {
@@ -101,7 +142,7 @@ export function detectFramework(projectRoot: string): FrameworkDetection {
 }
 
 // ============================================================
-// Python Project Detection
+// Legacy Python Project Detection (preserved for cli.test.ts / back compat)
 // ============================================================
 
 interface PythonDetection {
@@ -123,39 +164,34 @@ export function detectPython(projectRoot: string): PythonDetection {
     alembicDir: null,
   };
 
-  // Check for Python project markers
   const markers = ['pyproject.toml', 'setup.py', 'requirements.txt', 'Pipfile'];
   const hasMarker = markers.some(m => existsSync(resolve(projectRoot, m)));
   if (!hasMarker) return result;
 
   result.detected = true;
 
-  // Scan dependencies for FastAPI and SQLAlchemy
   const depFiles = [
-    { file: 'pyproject.toml', parser: parsePyprojectDeps },
-    { file: 'requirements.txt', parser: parseRequirementsDeps },
-    { file: 'setup.py', parser: parseSetupPyDeps },
-    { file: 'Pipfile', parser: parsePipfileDeps },
+    { file: 'pyproject.toml' },
+    { file: 'requirements.txt' },
+    { file: 'setup.py' },
+    { file: 'Pipfile' },
   ];
 
-  for (const { file, parser } of depFiles) {
+  for (const { file } of depFiles) {
     const filePath = resolve(projectRoot, file);
     if (existsSync(filePath)) {
       try {
-        const content = readFileSync(filePath, 'utf-8');
-        const deps = parser(content);
-        if (deps.includes('fastapi')) result.hasFastapi = true;
-        if (deps.includes('sqlalchemy')) result.hasSqlalchemy = true;
+        const content = readFileSync(filePath, 'utf-8').toLowerCase();
+        if (content.includes('fastapi')) result.hasFastapi = true;
+        if (content.includes('sqlalchemy')) result.hasSqlalchemy = true;
       } catch {
         // Best effort
       }
     }
   }
 
-  // Check for Alembic
   if (existsSync(resolve(projectRoot, 'alembic.ini'))) {
     result.hasAlembic = true;
-    // Try to find the alembic versions directory
     if (existsSync(resolve(projectRoot, 'alembic'))) {
       result.alembicDir = 'alembic';
     }
@@ -164,7 +200,6 @@ export function detectPython(projectRoot: string): PythonDetection {
     result.alembicDir = 'alembic';
   }
 
-  // Auto-detect Python source root
   const candidateRoots = ['app', 'src', 'backend', 'api'];
   for (const candidate of candidateRoots) {
     const candidatePath = resolve(projectRoot, candidate);
@@ -172,7 +207,6 @@ export function detectPython(projectRoot: string): PythonDetection {
       result.root = candidate;
       break;
     }
-    // Also check for .py files directly (some projects use app/ without __init__.py)
     if (existsSync(candidatePath)) {
       try {
         const files = readdirSync(candidatePath);
@@ -186,7 +220,6 @@ export function detectPython(projectRoot: string): PythonDetection {
     }
   }
 
-  // Fallback: use '.' if no candidate root found
   if (!result.root) {
     result.root = '.';
   }
@@ -194,43 +227,8 @@ export function detectPython(projectRoot: string): PythonDetection {
   return result;
 }
 
-function parsePyprojectDeps(content: string): string[] {
-  const deps: string[] = [];
-  const lower = content.toLowerCase();
-  if (lower.includes('fastapi')) deps.push('fastapi');
-  if (lower.includes('sqlalchemy')) deps.push('sqlalchemy');
-  return deps;
-}
-
-function parseRequirementsDeps(content: string): string[] {
-  const deps: string[] = [];
-  const lower = content.toLowerCase();
-  for (const line of lower.split('\n')) {
-    const trimmed = line.trim();
-    if (trimmed.startsWith('fastapi')) deps.push('fastapi');
-    if (trimmed.startsWith('sqlalchemy')) deps.push('sqlalchemy');
-  }
-  return deps;
-}
-
-function parseSetupPyDeps(content: string): string[] {
-  const deps: string[] = [];
-  const lower = content.toLowerCase();
-  if (lower.includes('fastapi')) deps.push('fastapi');
-  if (lower.includes('sqlalchemy')) deps.push('sqlalchemy');
-  return deps;
-}
-
-function parsePipfileDeps(content: string): string[] {
-  const deps: string[] = [];
-  const lower = content.toLowerCase();
-  if (lower.includes('fastapi')) deps.push('fastapi');
-  if (lower.includes('sqlalchemy')) deps.push('sqlalchemy');
-  return deps;
-}
-
 // ============================================================
-// Config File Generation
+// Legacy Config File Generation (preserved for cli.test.ts)
 // ============================================================
 
 export function generateConfig(projectRoot: string, framework: FrameworkDetection): boolean {
@@ -293,29 +291,388 @@ ${yamlStringify(config)}`;
 }
 
 // ============================================================
-// CLAUDE.md Generation
+// V2 Config Builder (detection-driven)
 // ============================================================
 
-export function generateClaudeMd(
+/**
+ * Build a schema_version=2 config object from a DetectionResult.
+ *
+ * Contract:
+ *   - `framework.type` is `'multi'` when 2+ languages present, else the sole language.
+ *   - `framework.primary` is the language with the most manifests (ties: alpha).
+ *   - `framework.languages` is populated for every detected language with a
+ *     non-null framework or test framework.
+ *   - Legacy top-level `framework.router/.orm/.ui` are mirrored from the primary
+ *     language entry so existing consumers (tools.ts lines 89/192/246) keep
+ *     working without any change (per Phase 0 P0-003 + Phase 2 P2-002 contract).
+ *   - `paths.source` is the dominant directory for the primary language (or '.'
+ *     for single-repo flat layouts).
+ *   - `verification.<language>` is pulled from VRCommandMap output.
+ *   - `domains[]` is the DomainInferrer output (may be empty).
+ */
+export function buildConfigFromDetection(
+  opts: GenerateConfigV2Options
+): Record<string, unknown> {
+  const { projectRoot, detection } = opts;
+  if (!detection) {
+    throw new Error('buildConfigFromDetection requires a detection result');
+  }
+  const projectName = opts.projectName ?? basename(projectRoot);
+
+  const languages = Array.from(
+    new Set(detection.manifests.map((m) => m.language))
+  ) as SupportedLanguage[];
+
+  // Pick primary: language with most manifests; ties broken by alphabetical.
+  const languageCounts = new Map<SupportedLanguage, number>();
+  for (const m of detection.manifests) {
+    languageCounts.set(m.language, (languageCounts.get(m.language) ?? 0) + 1);
+  }
+  const sortedLangs = [...languageCounts.entries()].sort((a, b) => {
+    if (b[1] !== a[1]) return b[1] - a[1];
+    return a[0].localeCompare(b[0]);
+  });
+  const primary: SupportedLanguage | null = sortedLangs.length > 0 ? sortedLangs[0][0] : null;
+
+  const frameworkType = languages.length > 1 ? 'multi' : (languages[0] ?? 'typescript');
+
+  // Build per-language entries from FrameworkMap.
+  const languageEntries: Record<string, Record<string, unknown>> = {};
+  for (const lang of languages) {
+    const fw = detection.frameworks[lang];
+    const dirInfo = detection.sourceDirs[lang];
+    const sourceDirs = dirInfo?.source_dirs ?? [];
+    const entry: Record<string, unknown> = {};
+    if (fw?.framework) entry.framework = fw.framework;
+    if (fw?.test_framework) entry.test_framework = fw.test_framework;
+    if (fw?.orm) entry.orm = fw.orm;
+    if (fw?.router) entry.router = fw.router;
+    if (fw?.ui_library) entry.ui = fw.ui_library;
+    if (sourceDirs.length > 0) entry.source_dirs = sourceDirs;
+    // Only include entries that have at least one field populated.
+    if (Object.keys(entry).length > 0) {
+      languageEntries[lang] = entry;
+    }
+  }
+
+  // Legacy top-level framework fields (mirror from primary language).
+  // Preserves tools.ts:89,192,246 reads under v2.
+  const primaryEntry = primary ? languageEntries[primary] : undefined;
+  const legacyRouter =
+    (primaryEntry?.router as string | undefined) ?? 'none';
+  const legacyOrm = (primaryEntry?.orm as string | undefined) ?? 'none';
+  const legacyUi = (primaryEntry?.ui as string | undefined) ?? 'none';
+
+  // Determine paths.source from primary language's dominant source dir.
+  let pathsSource = 'src';
+  if (primary) {
+    const primaryDirs = detection.sourceDirs[primary]?.source_dirs ?? [];
+    if (primaryDirs.length > 0) {
+      pathsSource = primaryDirs[0];
+    }
+  }
+
+  // Verification commands per language.
+  const verification: Record<string, Record<string, string>> = {};
+  for (const lang of languages) {
+    const cmds: VRCommandSet | undefined = detection.verificationCommands[lang];
+    if (!cmds) continue;
+    const entry: Record<string, string> = {};
+    if (cmds.test) entry.test = cmds.test;
+    if (cmds.type) entry.type = cmds.type;
+    if (cmds.build) entry.build = cmds.build;
+    if (cmds.syntax) entry.syntax = cmds.syntax;
+    if (cmds.lint) entry.lint = cmds.lint;
+    if (Object.keys(entry).length > 0) {
+      verification[lang] = entry;
+    }
+  }
+
+  // Domains: emit from inferred + strip defaulting so YAML stays lean.
+  const domains = detection.domains.map((d) => {
+    const out: Record<string, unknown> = { name: d.name };
+    if (d.routers.length > 0) out.routers = d.routers;
+    if (d.pages.length > 0) out.pages = d.pages;
+    if (d.tables.length > 0) out.tables = d.tables;
+    if (d.allowedImportsFrom.length > 0) out.allowedImportsFrom = d.allowedImportsFrom;
+    return out;
+  });
+
+  const frameworkBlock: Record<string, unknown> = {
+    type: frameworkType,
+    router: legacyRouter,
+    orm: legacyOrm,
+    ui: legacyUi,
+  };
+  if (languages.length > 1 && primary) {
+    frameworkBlock.primary = primary;
+  }
+  if (Object.keys(languageEntries).length > 0) {
+    frameworkBlock.languages = languageEntries;
+  }
+
+  const config: Record<string, unknown> = {
+    schema_version: 2,
+    project: {
+      name: projectName,
+      root: 'auto',
+    },
+    framework: frameworkBlock,
+    paths: {
+      source: pathsSource,
+      aliases: { '@': pathsSource },
+    },
+    toolPrefix: 'massu',
+    domains,
+    rules: [],
+  };
+
+  if (Object.keys(verification).length > 0) {
+    config.verification = verification;
+  }
+
+  // P5-002: stamp a stack fingerprint so session-start can detect drift later.
+  config.detection = { fingerprint: computeFingerprint(detection) };
+
+  // Preserve legacy `python` block for v1 consumers (domain-enforcer, etc.).
+  // Per Phase 0 P1-009 (b): python legacy config coexists with languages.python.
+  if (languages.includes('python')) {
+    const pySourceDirs = detection.sourceDirs.python?.source_dirs ?? [];
+    const pyRoot = pySourceDirs.length > 0 ? pySourceDirs[0] : '.';
+    const pyFw = detection.frameworks.python;
+    const pythonBlock: Record<string, unknown> = {
+      root: pyRoot,
+      exclude_dirs: ['__pycache__', '.venv', 'venv', '.mypy_cache', '.pytest_cache'],
+    };
+    if (pyFw?.framework) pythonBlock.framework = pyFw.framework;
+    if (pyFw?.orm) pythonBlock.orm = pyFw.orm;
+    // Alembic detection — best-effort via filesystem (detection layer is DB-free).
+    if (existsSync(resolve(projectRoot, 'alembic.ini')) || existsSync(resolve(projectRoot, 'alembic'))) {
+      pythonBlock.alembic_dir = 'alembic';
+    }
+    config.python = pythonBlock;
+  }
+
+  return config;
+}
+
+/**
+ * Serialize a built config object into YAML with a header comment.
+ * Safe for `writeConfigAtomic` and for `fs.writeFileSync` directly.
+ */
+export function renderConfigYaml(config: Record<string, unknown>): string {
+  return `# Massu AI Configuration
+# Generated by: npx massu init (schema_version=2, detection-driven)
+# Documentation: https://massu.ai/docs/getting-started/configuration
+
+${yamlStringify(config)}`;
+}
+
+// ============================================================
+// Atomic Write + Post-Write Validation (P3-004, P3-005)
+// ============================================================
+
+/**
+ * Atomically write YAML to `configPath`.
+ * 1. Writes to `<configPath>.tmp`.
+ * 2. Validates the written file by parsing it as YAML and through the Zod
+ *    RawConfigSchema via a short-lived `getConfig` reload on a sandboxed cwd.
+ * 3. Renames the tmp file to the target.
+ * 4. On ANY error, removes the tmp file. No partial config ever persists.
+ *
+ * Preserves existing file permissions when overwriting.
+ *
+ * P3-006: never writes outside `configPath`'s directory; caller is responsible
+ * for passing an in-project path (enforced at the call-site in runInit).
+ */
+export function writeConfigAtomic(
+  configPath: string,
+  content: string
+): { validated: boolean; error?: string } {
+  const tmpPath = `${configPath}.tmp`;
+
+  // Preserve existing permissions when overwriting.
+  let existingMode: number | undefined;
+  if (existsSync(configPath)) {
+    try {
+      existingMode = statSync(configPath).mode;
+    } catch {
+      existingMode = undefined;
+    }
+  }
+
+  try {
+    writeFileSync(tmpPath, content, { encoding: 'utf-8', mode: 0o644 });
+
+    // Validate YAML parses.
+    const parsed = yamlParse(content);
+    if (parsed === null || typeof parsed !== 'object') {
+      throw new Error('Generated config is not a valid YAML object');
+    }
+
+    // Atomic rename.
+    renameSync(tmpPath, configPath);
+
+    // Restore mode if we had one.
+    if (existingMode !== undefined) {
+      try {
+        chmodSync(configPath, existingMode);
+      } catch {
+        // Best effort; unreadable mode doesn't block init.
+      }
+    }
+
+    return { validated: true };
+  } catch (err) {
+    // Clean up the temp file on failure.
+    if (existsSync(tmpPath)) {
+      try { rmSync(tmpPath, { force: true }); } catch { /* ignore */ }
+    }
+    return { validated: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * Validate a written config against the live Zod schema AND filesystem.
+ * Returns null on success, an error message on failure.
+ *
+ * When `checkPaths` is false (template mode, greenfield scaffolds), filesystem
+ * existence checks on `paths.source` and per-language source_dirs are skipped.
+ */
+export function validateWrittenConfig(
+  configPath: string,
   projectRoot: string,
-  framework: FrameworkDetection,
-  python: PythonDetection,
-): { created: boolean; skipped: boolean } {
-  const claudeMdPath = resolve(projectRoot, 'CLAUDE.md');
+  checkPaths: boolean = true
+): string | null {
+  try {
+    if (!existsSync(configPath)) return 'Config file does not exist after write';
+    // Parse YAML directly — we deliberately bypass getConfig() here because
+    // getConfig caches against process.cwd() and we may be validating a config
+    // outside the current working tree (tests, etc.).
+    const content = readFileSync(configPath, 'utf-8');
+    const parsed = yamlParse(content);
+    if (parsed === null || typeof parsed !== 'object') {
+      return 'Config is not a valid YAML object';
+    }
 
-  // NEVER overwrite existing CLAUDE.md
-  if (existsSync(claudeMdPath)) {
-    return { created: false, skipped: true };
+    // Validate via getConfig by temporarily chdir'ing to projectRoot, since
+    // getConfig reads the config from process.cwd(). The Zod safeParse inside
+    // getConfig already surfaces actionable errors on malformed configs.
+    const prevCwd = process.cwd();
+    let changed = false;
+    if (prevCwd !== projectRoot) {
+      try { process.chdir(projectRoot); changed = true; } catch { /* ignore */ }
+    }
+    try {
+      resetConfig();
+      const cfg = getConfig();
+      if (checkPaths) {
+        // Verify paths.source actually exists on disk (unless '.', which is always valid).
+        const src = cfg.paths.source;
+        if (src && src !== '.') {
+          const srcAbs = resolve(projectRoot, src);
+          if (!existsSync(srcAbs)) {
+            return `paths.source '${src}' does not exist on disk`;
+          }
+        }
+        // Verify every declared language source_dir exists.
+        const languages = cfg.framework.languages ?? {};
+        for (const [lang, entry] of Object.entries(languages)) {
+          const rawDirs = (entry as Record<string, unknown>).source_dirs;
+          if (!Array.isArray(rawDirs)) continue;
+          for (const d of rawDirs) {
+            if (typeof d !== 'string' || d === '.') continue;
+            const abs = resolve(projectRoot, d);
+            if (!existsSync(abs)) {
+              return `framework.languages.${lang}.source_dirs '${d}' does not exist on disk`;
+            }
+          }
+        }
+      }
+    } catch (err) {
+      return err instanceof Error ? err.message : String(err);
+    } finally {
+      if (changed) {
+        try { process.chdir(prevCwd); } catch { /* ignore */ }
+      }
+      resetConfig();
+    }
+    return null;
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
   }
+}
 
-  const projectName = basename(projectRoot);
-  const content = buildClaudeMdContent(projectName, projectRoot, framework, python);
-  writeFileSync(claudeMdPath, content, 'utf-8');
-  return { created: true, skipped: false };
+// ============================================================
+// Template Mode (P3-003)
+// ============================================================
+
+const TEMPLATE_NAMES = [
+  'python-fastapi',
+  'python-django',
+  'ts-nextjs',
+  'ts-nestjs',
+  'rust-actix',
+  'swift-ios',
+  'multi-runtime',
+] as const;
+
+export type TemplateName = (typeof TEMPLATE_NAMES)[number];
+
+export function isTemplateName(name: string): name is TemplateName {
+  return (TEMPLATE_NAMES as readonly string[]).includes(name);
+}
+
+export function listTemplates(): readonly string[] {
+  return TEMPLATE_NAMES;
+}
+
+/**
+ * Resolve the templates directory.
+ * Order:
+ *   1. `node_modules/@massu/core/templates` (installed)
+ *   2. Relative to compiled dist (dist/../templates)
+ *   3. Relative to source (src/../templates)
+ */
+export function resolveTemplatesDir(): string | null {
+  const cwd = process.cwd();
+  const candidates = [
+    resolve(cwd, 'node_modules/@massu/core/templates'),
+    resolve(__dirname, '../../templates'),
+    resolve(__dirname, '../../../templates'),
+  ];
+  for (const c of candidates) {
+    if (existsSync(c)) return c;
+  }
+  return null;
+}
+
+export function copyTemplateConfig(
+  templateName: TemplateName,
+  targetPath: string,
+  projectName: string
+): { success: boolean; error?: string } {
+  const templatesDir = resolveTemplatesDir();
+  if (!templatesDir) {
+    return { success: false, error: `Templates directory not found (looked in node_modules and dist/src)` };
+  }
+  const srcPath = resolve(templatesDir, templateName, 'massu.config.yaml');
+  if (!existsSync(srcPath)) {
+    return { success: false, error: `Template '${templateName}' not found at ${srcPath}` };
+  }
+  try {
+    let content = readFileSync(srcPath, 'utf-8');
+    // Replace {{PROJECT_NAME}} placeholder if present.
+    content = content.replace(/\{\{PROJECT_NAME\}\}/g, projectName);
+    writeFileSync(targetPath, content, 'utf-8');
+    return { success: true };
+  } catch (err) {
+    return { success: false, error: err instanceof Error ? err.message : String(err) };
+  }
 }
 
 // ============================================================
-// MCP Server Registration
+// MCP Server Registration (preserved)
 // ============================================================
 
 export function registerMcpServer(projectRoot: string): boolean {
@@ -330,13 +687,11 @@ export function registerMcpServer(projectRoot: string): boolean {
     }
   }
 
-  // Check if already registered
   const servers = (existing.mcpServers ?? {}) as Record<string, unknown>;
   if (servers.massu) {
-    return false; // Already registered
+    return false;
   }
 
-  // Add massu server
   servers.massu = {
     type: 'stdio',
     command: 'npx',
@@ -350,7 +705,7 @@ export function registerMcpServer(projectRoot: string): boolean {
 }
 
 // ============================================================
-// Hook Installation
+// Hook Installation (preserved)
 // ============================================================
 
 interface HookEntry {
@@ -366,23 +721,21 @@ interface HookGroup {
 
 type HooksConfig = Record<string, HookGroup[]>;
 
-/**
- * Resolve the path to compiled hook files.
- * Handles both local development and npm-installed scenarios.
- */
 export function resolveHooksDir(): string {
-  // Always use node_modules/@massu/core/dist/hooks relative to project root.
-  // hookCmd() wraps each command with a parent-directory walk to find the
-  // project root, so hooks resolve correctly even from subdirectories.
+  const cwd = process.cwd();
+  const nodeModulesPath = resolve(cwd, 'node_modules/@massu/core/dist/hooks');
+  if (existsSync(nodeModulesPath)) {
+    return 'node_modules/@massu/core/dist/hooks';
+  }
+  const localPath = resolve(__dirname, '../dist/hooks');
+  if (existsSync(localPath)) {
+    return localPath;
+  }
   return 'node_modules/@massu/core/dist/hooks';
 }
 
 function hookCmd(hooksDir: string, hookFile: string): string {
-  // Walk up from cwd to find the directory containing node_modules/@massu/core,
-  // then cd there before running the hook. This handles subdirectories like
-  // website/, packages/foo/, etc. where node_modules doesn't exist.
-  const hookPath = `${hooksDir}/${hookFile}`;
-  return `d="$PWD"; while [ "$d" != "/" ] && [ ! -f "$d/${hookPath}" ]; do d="$(dirname "$d")"; done; cd "$d" && node ${hookPath}`;
+  return `node ${hooksDir}/${hookFile}`;
 }
 
 export function buildHooksConfig(hooksDir: string): HooksConfig {
@@ -420,6 +773,8 @@ export function buildHooksConfig(hooksDir: string): HooksConfig {
         matcher: 'Edit|Write',
         hooks: [
           { type: 'command', command: hookCmd(hooksDir, 'post-edit-context.js'), timeout: 5 },
+          // Auto-learning pipeline — classifies failures and detects fixes on
+          // file changes. See Phase 5-6 of the autodetect plan.
           { type: 'command', command: hookCmd(hooksDir, 'fix-detector.js'), timeout: 5 },
           { type: 'command', command: hookCmd(hooksDir, 'classify-failure.js'), timeout: 5 },
         ],
@@ -427,6 +782,8 @@ export function buildHooksConfig(hooksDir: string): HooksConfig {
       {
         matcher: 'Write',
         hooks: [
+          // Incident + rule enforcement pipelines fire on Write-only (incidents
+          // are authored as .md files; rules are enforced after new-file drops).
           { type: 'command', command: hookCmd(hooksDir, 'incident-pipeline.js'), timeout: 5 },
           { type: 'command', command: hookCmd(hooksDir, 'rule-enforcement-pipeline.js'), timeout: 5 },
         ],
@@ -436,6 +793,7 @@ export function buildHooksConfig(hooksDir: string): HooksConfig {
       {
         hooks: [
           { type: 'command', command: hookCmd(hooksDir, 'session-end.js'), timeout: 15 },
+          // Session-end auto-learning aggregation (failure-class roll-up).
           { type: 'command', command: hookCmd(hooksDir, 'auto-learning-pipeline.js'), timeout: 10 },
         ],
       },
@@ -459,16 +817,22 @@ export function buildHooksConfig(hooksDir: string): HooksConfig {
 }
 
 export function installHooks(projectRoot: string): { installed: boolean; count: number } {
-  const claudeDirName = getConfig().conventions?.claudeDirName ?? '.claude';
+  // Read claudeDirName defensively — tests may call installHooks without
+  // ever creating massu.config.yaml, in which case getConfig() throws (since
+  // it reads against process.cwd() and our cwd may not have one).
+  let claudeDirName = '.claude';
+  try {
+    claudeDirName = getConfig().conventions?.claudeDirName ?? '.claude';
+  } catch {
+    claudeDirName = '.claude';
+  }
   const claudeDir = resolve(projectRoot, claudeDirName);
   const settingsPath = resolve(claudeDir, 'settings.local.json');
 
-  // Ensure .claude directory exists
   if (!existsSync(claudeDir)) {
     mkdirSync(claudeDir, { recursive: true });
   }
 
-  // Read existing settings
   let settings: Record<string, unknown> = {};
   if (existsSync(settingsPath)) {
     try {
@@ -478,13 +842,9 @@ export function installHooks(projectRoot: string): { installed: boolean; count:
     }
   }
 
-  // Resolve hook paths
   const hooksDir = resolveHooksDir();
-
-  // Build hooks config
   const hooksConfig = buildHooksConfig(hooksDir);
 
-  // Count total hooks
   let hookCount = 0;
   for (const groups of Object.values(hooksConfig)) {
     for (const group of groups) {
@@ -492,7 +852,6 @@ export function installHooks(projectRoot: string): { installed: boolean; count:
     }
   }
 
-  // Merge hooks into settings (replace hooks section, preserve everything else)
   settings.hooks = hooksConfig;
 
   writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
@@ -501,16 +860,10 @@ export function installHooks(projectRoot: string): { installed: boolean; count:
 }
 
 // ============================================================
-// Memory Directory Initialization
+// Memory Directory Initialization (preserved)
 // ============================================================
 
-/**
- * Initialize the memory directory and create an initial MEMORY.md if absent.
- * The memory directory lives in ~/.claude/projects/<encoded-root>/memory/
- * matching the path used by memory-db.ts / knowledge-tools.ts.
- */
 export function initMemoryDir(projectRoot: string): { created: boolean; memoryMdCreated: boolean } {
-  // Encode the project root the same way as getResolvedPaths() in config.ts
   const encodedRoot = '-' + projectRoot.replace(/\//g, '-');
   const memoryDir = resolve(homedir(), `.claude/projects/${encodedRoot}/memory`);
 
@@ -546,124 +899,320 @@ export function initMemoryDir(projectRoot: string): { created: boolean; memoryMd
 }
 
 // ============================================================
-// Main Init Flow
+// Flag Parsing
 // ============================================================
 
-export async function runInit(): Promise<void> {
-  const projectRoot = process.cwd();
-
-  console.log('');
-  console.log('Massu AI - Project Setup');
-  console.log('========================');
-  console.log('');
-
-  // Step 1: Detect framework
-  const framework = detectFramework(projectRoot);
-  const frameworkParts: string[] = [];
-  if (framework.type !== 'javascript') frameworkParts.push(capitalize(framework.type));
-  if (framework.ui !== 'none') frameworkParts.push(formatName(framework.ui));
-  if (framework.orm !== 'none') frameworkParts.push(capitalize(framework.orm));
-  if (framework.router !== 'none') frameworkParts.push(framework.router.toUpperCase());
-  const detected = frameworkParts.length > 0 ? frameworkParts.join(', ') : 'JavaScript';
-  console.log(`  Detected: ${detected}`);
-
-  // Step 1b: Detect Python
-  const python = detectPython(projectRoot);
-  if (python.detected) {
-    const pyParts: string[] = ['Python'];
-    if (python.hasFastapi) pyParts.push('FastAPI');
-    if (python.hasSqlalchemy) pyParts.push('SQLAlchemy');
-    if (python.hasAlembic) pyParts.push('Alembic');
-    console.log(`  Detected: ${pyParts.join(', ')} (root: ${python.root})`);
+export interface ParseInitArgsResult extends InitOptions {
+  /** True when --help / -h was requested. runInit should print help and exit. */
+  help?: boolean;
+}
+
+export function parseInitArgs(argv: string[]): ParseInitArgsResult {
+  const opts: ParseInitArgsResult = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--ci') opts.ci = true;
+    else if (a === '--force') opts.force = true;
+    else if (a === '--help' || a === '-h') opts.help = true;
+    else if (a === '--template') {
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        opts.template = next;
+        i++;
+      }
+    } else if (a.startsWith('--template=')) {
+      opts.template = a.slice('--template='.length);
+    }
   }
+  return opts;
+}
 
-  // Step 1.5: Generate CLAUDE.md (MUST be first content step — incident 2026-04-13)
-  const claudeMdResult = generateClaudeMd(projectRoot, framework, python);
-  if (claudeMdResult.created) {
-    console.log('  Created CLAUDE.md (project instructions for Claude Code)');
-  } else {
-    console.log('  CLAUDE.md already exists (preserved)');
+export function printInitHelp(): void {
+  console.log(`
+massu init — detect project stack and generate massu.config.yaml
+
+Usage:
+  massu init [options]
+
+Options:
+  --ci                Non-interactive mode. Errors on existing config
+                      (unless --force). Auto-enabled when stdin is not a TTY.
+  --force             Overwrite existing massu.config.yaml without prompting.
+  --template <name>   Skip detection and scaffold from a greenfield template.
+                      Templates: ${TEMPLATE_NAMES.join(', ')}
+  --help, -h          Show this help message
+
+Examples:
+  massu init                       # Interactive (prompts before overwriting)
+  massu init --ci                  # Safe for CI; fails if config already exists
+  massu init --force               # Overwrite an existing config
+  massu init --template ts-nextjs  # Scaffold from the Next.js template
+
+Documentation: https://massu.ai/docs/getting-started/configuration
+`);
+}
+
+// ============================================================
+// Stack summary (for user confirmation)
+// ============================================================
+
+function summarizeDetection(detection: DetectionResult): string {
+  const parts: string[] = [];
+  const languages = Array.from(
+    new Set(detection.manifests.map((m) => m.language))
+  ) as SupportedLanguage[];
+  for (const lang of languages) {
+    const fw = detection.frameworks[lang];
+    const dirs = detection.sourceDirs[lang]?.source_dirs ?? [];
+    const dirSuffix = dirs.length > 0 ? ` in ${dirs.join(',')}` : '';
+    const fwName = fw?.framework ?? 'no-framework';
+    parts.push(`${capitalize(lang)}/${fwName}${dirSuffix}`);
   }
+  const mono = detection.monorepo.type;
+  const monoSuffix = mono && mono !== 'single' ? ` [${mono} monorepo]` : '';
+  return parts.join('; ') + monoSuffix;
+}
 
-  // Step 2: Create config
-  const configCreated = generateConfig(projectRoot, framework);
-  if (configCreated) {
-    console.log('  Created massu.config.yaml');
-  } else {
-    console.log('  massu.config.yaml already exists (preserved)');
+// ============================================================
+// Main Init Flow (Phase 3 rewrite)
+// ============================================================
+
+export async function runInit(argv?: string[], overrides?: InitOptions): Promise<void> {
+  const argsToParse = argv ?? process.argv.slice(3); // argv[0]=node, [1]=cli.js, [2]='init'
+  const parsed = parseInitArgs(argsToParse);
+  if (parsed.help && !overrides?.silent) {
+    printInitHelp();
+    return;
+  }
+  // Strip `help` from parsed before merging (not part of InitOptions).
+  const { help: _help, ...parsedOpts } = parsed;
+  void _help;
+  const opts: InitOptions = { ...parsedOpts, ...(overrides ?? {}) };
+
+  // Auto-CI when stdin is not a TTY (e.g., CI pipes, scripts).
+  if (!opts.ci && !process.stdin.isTTY) {
+    opts.ci = true;
+  }
+
+  const projectRoot = opts.cwd ?? process.cwd();
+  const log = opts.silent ? () => {} : (s: string) => console.log(s);
+  const errLog = opts.silent ? () => {} : (s: string) => console.error(s);
+
+  log('');
+  log('Massu AI - Project Setup');
+  log('========================');
+  log('');
+
+  const configPath = resolve(projectRoot, 'massu.config.yaml');
+
+  // P3-006: safety rails for existing config.
+  if (existsSync(configPath)) {
+    if (opts.ci && !opts.force) {
+      errLog(`error: massu.config.yaml already exists at ${configPath}`);
+      errLog('       rerun with --force to overwrite, or remove the file first');
+      throw new Error('massu init: config exists in --ci mode (no overwrite)');
+    }
+    if (!opts.ci && !opts.force) {
+      // Interactive: prompt to confirm overwrite.
+      const confirmed = await promptOverwrite(configPath);
+      if (!confirmed) {
+        log('  massu.config.yaml preserved — init aborted');
+        return;
+      }
+    }
+    // else: --force set, proceed with overwrite
   }
 
-  // Step 3: Register MCP server
+  // Branch 1: template mode (P3-003)
+  if (opts.template) {
+    if (!isTemplateName(opts.template)) {
+      errLog(`error: unknown template '${opts.template}'. Available: ${TEMPLATE_NAMES.join(', ')}`);
+      throw new Error(`Unknown template: ${opts.template}`);
+    }
+    const projectName = basename(projectRoot);
+    const res = copyTemplateConfig(opts.template, configPath, projectName);
+    if (!res.success) {
+      errLog(`error: template copy failed: ${res.error}`);
+      throw new Error(res.error ?? 'template copy failed');
+    }
+    // Validate the template-derived config (skip filesystem existence checks:
+    // templates are explicitly for greenfield projects where the declared dirs
+    // don't exist yet).
+    const validation = validateWrittenConfig(configPath, projectRoot, false);
+    if (validation !== null) {
+      try { rmSync(configPath, { force: true }); } catch { /* ignore */ }
+      errLog(`error: template config failed validation: ${validation}`);
+      throw new Error(`Template config invalid: ${validation}`);
+    }
+    log(`  Installed template '${opts.template}' → massu.config.yaml`);
+    if (!opts.skipSideEffects) {
+      installSideEffects(projectRoot, log);
+    }
+    return;
+  }
+
+  // Branch 2: detection-driven path (P3-001, P3-002)
+  const detection = await runDetection(projectRoot);
+  const languageCount = new Set(detection.manifests.map((m) => m.language)).size;
+  if (detection.manifests.length === 0 && languageCount === 0) {
+    errLog('error: no languages detected in this directory');
+    errLog('       (no package.json, pyproject.toml, Cargo.toml, etc.)');
+    errLog('       pass --template <name> to scaffold a new project, or cd into a repo with a manifest');
+    throw new Error('No languages detected');
+  }
+
+  // Emit warnings to stderr for ambiguous / malformed detection.
+  for (const w of detection.warnings) {
+    errLog(`warning: ${w.path}: ${w.reason}`);
+  }
+
+  // Ambiguity warning: multiple languages with similar file density.
+  const dirCounts: { lang: SupportedLanguage; count: number }[] = [];
+  for (const [lang, info] of Object.entries(detection.sourceDirs)) {
+    if (info && typeof info.file_count === 'number') {
+      dirCounts.push({ lang: lang as SupportedLanguage, count: info.file_count });
+    }
+  }
+  if (dirCounts.length >= 2) {
+    dirCounts.sort((a, b) => b.count - a.count);
+    if (dirCounts[0].count > 0 && dirCounts[1].count / Math.max(dirCounts[0].count, 1) >= 0.5) {
+      errLog(`warning: multiple languages with similar file counts: ${dirCounts.map(d => `${d.lang}=${d.count}`).join(', ')}`);
+      errLog('         primary language chosen by manifest count; review framework.primary in the generated config');
+    }
+  }
+
+  log(`  Detected: ${summarizeDetection(detection)}`);
+
+  // Interactive confirmation for detected stack.
+  if (!opts.ci && !opts.force) {
+    const confirmed = await promptStackConfirm();
+    if (!confirmed) {
+      log('  init aborted — no changes made');
+      return;
+    }
+  }
+
+  // Build config + write atomically.
+  const config = buildConfigFromDetection({ projectRoot, detection });
+  const content = renderConfigYaml(config);
+  const writeRes = writeConfigAtomic(configPath, content);
+  if (!writeRes.validated) {
+    errLog(`error: failed to write config: ${writeRes.error}`);
+    throw new Error(writeRes.error ?? 'atomic write failed');
+  }
+
+  // Post-write validation; rollback on failure.
+  const validation = validateWrittenConfig(configPath, projectRoot);
+  if (validation !== null) {
+    try { rmSync(configPath, { force: true }); } catch { /* ignore */ }
+    errLog(`error: generated config failed validation: ${validation}`);
+    errLog('       config file rolled back; no changes persisted');
+    throw new Error(`Generated config invalid: ${validation}`);
+  }
+
+  log('  Created massu.config.yaml (schema_version: 2)');
+
+  if (!opts.skipSideEffects) {
+    installSideEffects(projectRoot, log);
+  }
+}
+
+/** Shared side-effect steps (MCP register + hooks + commands + memory + backfill). */
+function installSideEffects(projectRoot: string, log: (s: string) => void): void {
+  // MCP register
   const mcpRegistered = registerMcpServer(projectRoot);
   if (mcpRegistered) {
-    console.log('  Registered MCP server in .mcp.json');
+    log('  Registered MCP server in .mcp.json');
   } else {
-    console.log('  MCP server already registered in .mcp.json');
+    log('  MCP server already registered in .mcp.json');
   }
 
-  // Step 4: Install hooks
+  // Hooks
   const { count: hooksCount } = installHooks(projectRoot);
-  console.log(`  Installed ${hooksCount} hooks in .claude/settings.local.json`);
+  log(`  Installed ${hooksCount} hooks in .claude/settings.local.json`);
 
-  // Step 5: Install slash commands
-  const cmdResult = installCommands(projectRoot);
-  const cmdTotal = cmdResult.installed + cmdResult.updated + cmdResult.skipped;
-  if (cmdResult.installed > 0 || cmdResult.updated > 0) {
-    console.log(`  Installed ${cmdTotal} slash commands (${cmdResult.installed} new, ${cmdResult.updated} updated)`);
-  } else {
-    console.log(`  ${cmdTotal} slash commands already up to date`);
+  // Commands
+  try {
+    const cmdResult = installCommands(projectRoot);
+    const cmdTotal = cmdResult.installed + cmdResult.updated + cmdResult.skipped;
+    if (cmdResult.installed > 0 || cmdResult.updated > 0) {
+      log(`  Installed ${cmdTotal} slash commands (${cmdResult.installed} new, ${cmdResult.updated} updated)`);
+    } else if (cmdTotal > 0) {
+      log(`  ${cmdTotal} slash commands already up to date`);
+    }
+  } catch {
+    // Best-effort — don't fail init if assets can't be resolved.
   }
 
-  // Step 6: Initialize memory directory
+  // Memory dir
   const { created: memDirCreated, memoryMdCreated } = initMemoryDir(projectRoot);
   if (memDirCreated) {
-    console.log('  Created memory directory (~/.claude/projects/.../memory/)');
-  } else {
-    console.log('  Memory directory already exists');
+    log('  Created memory directory');
   }
   if (memoryMdCreated) {
-    console.log('  Created initial MEMORY.md');
+    log('  Created initial MEMORY.md');
   }
 
-  // Step 6b: Auto-backfill existing memory files into database
-  try {
-    const claudeDirName = '.claude';
-    const encodedRoot = projectRoot.replace(/\//g, '-');
-    const computedMemoryDir = resolve(homedir(), claudeDirName, 'projects', encodedRoot, 'memory');
-
-    const memFiles = existsSync(computedMemoryDir)
-      ? readdirSync(computedMemoryDir).filter(f => f.endsWith('.md') && f !== 'MEMORY.md')
-      : [];
-
-    if (memFiles.length > 0) {
-      const { getMemoryDb } = await import('../memory-db.ts');
-      const db = getMemoryDb();
-      try {
-        const stats = backfillMemoryFiles(db, computedMemoryDir, `init-${Date.now()}`);
-        if (stats.inserted > 0 || stats.updated > 0) {
-          console.log(`  Backfilled ${stats.inserted + stats.updated} memory files into database (${stats.inserted} new, ${stats.updated} updated)`);
+  // Backfill (best-effort, silent failure)
+  (async () => {
+    try {
+      const encodedRoot = projectRoot.replace(/\//g, '-');
+      const memoryDir = resolve(homedir(), '.claude', 'projects', encodedRoot, 'memory');
+      const memFiles = existsSync(memoryDir)
+        ? readdirSync(memoryDir).filter(f => f.endsWith('.md') && f !== 'MEMORY.md')
+        : [];
+      if (memFiles.length > 0) {
+        const { getMemoryDb } = await import('../memory-db.ts');
+        const db = getMemoryDb();
+        try {
+          const stats = backfillMemoryFiles(db, memoryDir, `init-${Date.now()}`);
+          if (stats.inserted > 0 || stats.updated > 0) {
+            log(`  Backfilled ${stats.inserted + stats.updated} memory files (${stats.inserted} new, ${stats.updated} updated)`);
+          }
+        } finally {
+          db.close();
         }
-      } finally {
-        db.close();
       }
-    }
-  } catch (_backfillErr) {
-    // Best-effort: don't fail init if backfill fails
-  }
+    } catch { /* best effort */ }
+  })();
 
-  // Step 7: Databases info
-  console.log('  Databases will auto-create on first session');
+  log('  Databases will auto-create on first session');
+  log('');
+  log('Massu AI is ready. Start a Claude Code session to begin.');
+  log('');
+}
 
-  // Summary
-  console.log('');
-  console.log('Massu AI is ready. Start a Claude Code session to begin.');
-  console.log('');
-  console.log('Next steps:');
-  console.log('  claude                    # Start a session (hooks activate automatically)');
-  console.log('  npx massu doctor          # Verify installation health');
-  console.log('');
-  console.log('Documentation: https://massu.ai/docs');
-  console.log('');
+// ============================================================
+// Prompts (interactive path)
+// ============================================================
+
+async function promptOverwrite(configPath: string): Promise<boolean> {
+  try {
+    const { confirm, isCancel } = await import('@clack/prompts');
+    const res = await confirm({
+      message: `massu.config.yaml already exists at ${configPath}. Overwrite?`,
+      initialValue: false,
+    });
+    if (isCancel(res)) return false;
+    return res === true;
+  } catch {
+    // Clack not available (should never happen — it's a dep); fail safe to NO.
+    return false;
+  }
+}
+
+async function promptStackConfirm(): Promise<boolean> {
+  try {
+    const { confirm, isCancel } = await import('@clack/prompts');
+    const res = await confirm({
+      message: 'Generate massu.config.yaml from detected stack?',
+      initialValue: true,
+    });
+    if (isCancel(res)) return false;
+    return res === true;
+  } catch {
+    return true; // Default yes when clack is unavailable.
+  }
 }
 
 // ============================================================
@@ -674,14 +1223,5 @@ function capitalize(str: string): string {
   return str.charAt(0).toUpperCase() + str.slice(1);
 }
 
-function formatName(name: string): string {
-  const names: Record<string, string> = {
-    nextjs: 'Next.js',
-    sveltekit: 'SvelteKit',
-    nuxt: 'Nuxt',
-    angular: 'Angular',
-    vue: 'Vue',
-    react: 'React',
-  };
-  return names[name] ?? capitalize(name);
-}
+// `InitResult` is a compile-time type only; it's kept for external type-reuse.
+export type { InitResult };