vigiles 2.0.0

package/dist/cli.js

@@ -0,0 +1,1267 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * vigiles CLI — compile typed specs to instruction files.
+ *
+ * Commands:
+ *   vigiles init            — scaffold a spec from scratch
+ *   vigiles compile         — compile .spec.ts → .md with linter verification
+ *   vigiles audit           — verify hashes, report coverage, detect duplicates
+ *   vigiles generate-types  — emit .d.ts with types from project state
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const glob_1 = require("glob");
+const generate_types_js_1 = require("./generate-types.js");
+const validate_js_1 = require("./validate.js");
+const compile_js_1 = require("./compile.js");
+const proofs_js_1 = require("./proofs.js");
+const inline_js_1 = require("./inline.js");
+const linters_js_1 = require("./linters.js");
+const freshness_js_1 = require("./freshness.js");
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const IGNORE_NODE_MODULES = ["node_modules/**"];
+// Config is loaded from .vigilesrc.json via validate.ts::loadConfig().
+// All settings (validation, compilation, freshness) are in one place.
+// ---------------------------------------------------------------------------
+// Spec loading
+// ---------------------------------------------------------------------------
+function findSpecs(pattern) {
+    const glob = pattern ?? "**/*.md.spec.ts";
+    return (0, glob_1.globSync)(glob, {
+        ignore: [...IGNORE_NODE_MODULES, "dist/**"],
+        cwd: process.cwd(),
+    });
+}
+async function loadSpec(specPath) {
+    const fullPath = (0, node_path_1.resolve)(process.cwd(), specPath);
+    // Try multiple dist/ path strategies
+    const candidates = [];
+    // src/ → dist/ mapping (e.g., src/CLAUDE.md.spec.ts → dist/CLAUDE.md.spec.js)
+    if (fullPath.includes("/src/")) {
+        candidates.push(fullPath.replace(/\/src\//, "/dist/").replace(/\.ts$/, ".js"));
+    }
+    // Root-level spec → dist/ (e.g., CLAUDE.md.spec.ts → dist/CLAUDE.md.spec.js)
+    const dir = fullPath.substring(0, fullPath.lastIndexOf("/"));
+    const base = fullPath.substring(fullPath.lastIndexOf("/") + 1);
+    candidates.push((0, node_path_1.resolve)(dir, "dist", base.replace(/\.ts$/, ".js")));
+    // examples/ → dist/examples/ mapping
+    candidates.push(fullPath
+        .replace(/\.ts$/, ".js")
+        .replace(process.cwd(), (0, node_path_1.resolve)(process.cwd(), "dist")));
+    for (const distPath of candidates) {
+        if ((0, node_fs_1.existsSync)(distPath)) {
+            try {
+                const mod = (await import(distPath));
+                // CJS double-default: `{ default: { default: spec } }`.
+                const raw = mod.default;
+                if (raw && typeof raw === "object" && "default" in raw) {
+                    return raw.default;
+                }
+                return raw;
+            }
+            catch {
+                // Try next candidate
+            }
+        }
+    }
+    // Try loading .ts directly via tsx
+    try {
+        const { execSync } = require("node:child_process");
+        // Handle ESM/CJS double-default: m.default may itself have a .default
+        const script = `import(${JSON.stringify(fullPath)}).then(m => { const d = m.default?.default ?? m.default; console.log(JSON.stringify(d)); })`;
+        const output = execSync(`npx tsx -e '${script.replace(/'/g, "'\\''")}'`, {
+            encoding: "utf-8",
+            cwd: process.cwd(),
+            stdio: ["pipe", "pipe", "pipe"],
+            timeout: 15000,
+        });
+        return JSON.parse(output.trim());
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Output helpers
+// ---------------------------------------------------------------------------
+function printErrors(specFile, errors) {
+    for (const err of errors) {
+        const pathInfo = err.path ? ` (${err.path})` : "";
+        console.log(`  [${err.type}] ${err.message}${pathInfo}`);
+        console.log(`::error file=${specFile}::${err.message}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+async function compile(specPaths, config) {
+    let allValid = true;
+    for (const specPath of specPaths) {
+        const spec = await loadSpec(specPath);
+        if (!spec) {
+            console.log(`\n✗ ${specPath} — failed to load`);
+            console.log(`  Ensure the spec is compiled: run \`npm run build\` first.`);
+            allValid = false;
+            continue;
+        }
+        const basePath = process.cwd();
+        if (spec._specType === "claude") {
+            const { markdown: rawMarkdown, errors, linterResults, targets, } = (0, compile_js_1.compileClaude)(spec, {
+                basePath,
+                specFile: specPath,
+                maxRules: config.maxRules,
+                maxTokens: config.maxTokens,
+                maxSectionLines: config.maxSectionLines,
+                catalogOnly: config.catalogOnly,
+                linters: config.linters,
+            });
+            // Embed input hash for freshness tracking
+            let markdown = rawMarkdown;
+            if (config.freshnessMode === "input-hash") {
+                const inputs = (0, freshness_js_1.discoverInputs)(specPath, spec, basePath, config.freshnessInputs);
+                const inputHash = (0, freshness_js_1.computeInputHash)(inputs.files, basePath);
+                markdown = (0, freshness_js_1.addInputHash)(rawMarkdown, inputHash);
+            }
+            const linterCount = linterResults.filter((r) => r.exists).length;
+            const primaryOutput = specPath.replace(/\.spec\.ts$/, "");
+            if (errors.length === 0) {
+                // Write primary target
+                (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, primaryOutput), markdown);
+                const outputNames = [primaryOutput];
+                // Write additional targets with swapped heading + recomputed hash
+                for (const t of targets.slice(1)) {
+                    // Strip hash, replace heading, recompute hash
+                    const body = markdown
+                        .replace(/^<!-- vigiles:[^\n]+\n\n?/, "")
+                        .replace(/^# [^\n]+/, `# ${t}`);
+                    const additional = (0, compile_js_1.addHash)(body, specPath);
+                    const dir = primaryOutput.substring(0, primaryOutput.lastIndexOf("/") + 1);
+                    const targetPath = dir + t;
+                    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, targetPath), additional);
+                    outputNames.push(targetPath);
+                }
+                console.log(`\n✓ ${specPath} → ${outputNames.join(", ")}`);
+                console.log(`  ${String(Object.keys(spec.rules).length)} rules (${String(linterCount)} linter-verified)`);
+            }
+            else {
+                console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
+                printErrors(specPath, errors);
+                allValid = false;
+                // Still write the file so the user can see partial output
+                (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, primaryOutput), markdown);
+            }
+        }
+        else if (spec._specType === "skill") {
+            const outputPath = specPath.replace(/\.spec\.ts$/, "");
+            const { markdown, errors } = (0, compile_js_1.compileSkill)(spec, {
+                basePath,
+                specFile: specPath,
+            });
+            if (errors.length === 0) {
+                (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, outputPath), markdown);
+                console.log(`\n✓ ${specPath} → ${outputPath}`);
+            }
+            else {
+                console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
+                printErrors(specPath, errors);
+                allValid = false;
+                (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, outputPath), markdown);
+            }
+        }
+    }
+    return allValid;
+}
+/** True when running inside a GitHub Actions workflow. */
+function isGitHubActions() {
+    return process.env.GITHUB_ACTIONS === "true";
+}
+/**
+ * Emit a GitHub Actions annotation for the inline PR experience.
+ * No-op outside GitHub Actions.
+ */
+function ghAnnotate(level, message, file, line) {
+    if (!isGitHubActions())
+        return;
+    const locParts = [];
+    if (file)
+        locParts.push(`file=${file}`);
+    if (line !== undefined)
+        locParts.push(`line=${String(line)}`);
+    const loc = locParts.length > 0 ? " " + locParts.join(",") : "";
+    console.log(`::${level}${loc}::${message}`);
+}
+function verifyHashes(filePaths, silent = false) {
+    let errorCount = 0;
+    const log = (msg) => {
+        if (!silent)
+            console.log(msg);
+    };
+    for (const filePath of filePaths) {
+        const fullPath = (0, node_path_1.resolve)(process.cwd(), filePath);
+        // If the file doesn't exist at all (typo, deleted), that's an error —
+        // not a "no hash" informational message. Without this check, a scoped
+        // audit like `vigiles audit typo.md` would silently exit clean.
+        if (!(0, node_fs_1.existsSync)(fullPath)) {
+            log(`\n✗ ${filePath} — file not found`);
+            if (!silent) {
+                ghAnnotate("error", `File not found: ${filePath}`, filePath);
+            }
+            errorCount++;
+            continue;
+        }
+        const result = (0, compile_js_1.checkFileHash)(fullPath);
+        if (!result.hasHash) {
+            log(`\n- ${filePath} — no vigiles hash (hand-written or pre-v2)`);
+            continue;
+        }
+        if (result.valid) {
+            log(`\n✓ ${filePath} — hash valid (from ${result.specFile})`);
+            continue;
+        }
+        log(`\n✗ ${filePath} — hash mismatch (manually edited after compilation)`);
+        log(`  Re-run \`vigiles compile\` to regenerate from ${result.specFile ?? "spec"}.`);
+        if (!silent) {
+            ghAnnotate("error", "Hash mismatch — file was manually edited after compilation", filePath);
+        }
+        errorCount++;
+    }
+    return { valid: errorCount === 0, errorCount };
+}
+function validateSpecs(filePaths, rulesConfig, silent = false) {
+    let allValid = true;
+    const log = (msg) => {
+        if (!silent)
+            console.log(msg);
+    };
+    for (const filePath of filePaths) {
+        const fullPath = (0, node_path_1.resolve)(process.cwd(), filePath);
+        let content;
+        try {
+            content = (0, node_fs_1.readFileSync)(fullPath, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        // Multi-target: if file has a "compiled from" hash, it has a spec
+        // even if it's not named <file>.spec.ts (e.g., AGENTS.md from CLAUDE.md.spec.ts)
+        const hashMatch = content.match(/<!-- vigiles:sha256:[a-f0-9]+ compiled from (.+) -->/);
+        if (hashMatch) {
+            // Verify the referenced spec still exists
+            const specRef = (0, node_path_1.resolve)(process.cwd(), hashMatch[1]);
+            if (!(0, node_fs_1.existsSync)(specRef)) {
+                log(`  ✗ [require-spec] ${filePath} references "${hashMatch[1]}" but that spec no longer exists.`);
+                allValid = false;
+            }
+            continue;
+        }
+        const result = (0, validate_js_1.validate)(content, {
+            filePath: fullPath,
+            rules: rulesConfig,
+        });
+        for (const err of result.errors) {
+            log(`  ✗ [${err.rule}] ${err.message}`);
+            allValid = false;
+        }
+        for (const warn of result.warnings) {
+            log(`  ⚠ [${warn.rule}] ${warn.message}`);
+        }
+    }
+    return allValid;
+}
+function check(filePaths, silent = false) {
+    const hashes = verifyHashes(filePaths, silent);
+    const vConfig = (0, validate_js_1.loadConfig)();
+    const specsValid = validateSpecs(filePaths, vConfig.rules, silent);
+    return {
+        valid: hashes.valid && specsValid,
+        hashErrors: hashes.errorCount,
+        // `validateSpecs` only returns a boolean today, so we collapse
+        // failures to 1 until it starts reporting counts. Kept in its own
+        // counter so audit's "stale hash — run vigiles compile" remediation
+        // doesn't misreport a require-spec / other validation failure.
+        validationErrors: specsValid ? 0 : 1,
+    };
+}
+/**
+ * Find near-duplicate rules within each spec using NCD similarity.
+ * Catches spec bloat — rules that likely say the same thing in different words.
+ * Uses information-theoretic distance (gzip-based) — no LLM, fully deterministic.
+ */
+async function findDuplicateRules(threshold = 0.3, silent = false, scopeFiles) {
+    const log = (msg) => {
+        if (!silent)
+            console.log(msg);
+    };
+    const allSpecs = findSpecs();
+    // If audit was invoked with explicit file arguments, only scan the specs
+    // for those files — otherwise an unrelated duplicate elsewhere in the
+    // repo would fail a targeted CI check (e.g. `vigiles audit path/foo.md`).
+    //
+    // Resolve each requested file to its real source spec by reading the
+    // compiled-from header. Multi-target projects compile one spec to
+    // several targets (e.g. CLAUDE.md.spec.ts → CLAUDE.md + AGENTS.md), so
+    // naive `${file}.spec.ts` concatenation would miss the real source for
+    // the secondary targets. Fall back to the concatenation rule if the
+    // file has no hash header (e.g. freshly hand-written).
+    const specs = scopeFiles && scopeFiles.length > 0
+        ? (() => {
+            const wanted = new Set();
+            const compiledFromRe = /<!--\s*vigiles:sha256:[a-f0-9]+\s+compiled from (.+?)\s*-->/;
+            for (const f of scopeFiles) {
+                let resolved;
+                try {
+                    const content = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), f), "utf-8");
+                    const m = compiledFromRe.exec(content);
+                    if (m) {
+                        resolved = (0, node_path_1.resolve)(process.cwd(), m[1].trim());
+                    }
+                }
+                catch {
+                    // File unreadable — fall through to the naming convention
+                }
+                if (!resolved) {
+                    resolved = (0, node_path_1.resolve)(process.cwd(), `${f}.spec.ts`);
+                }
+                wanted.add(resolved);
+            }
+            return allSpecs.filter((specPath) => wanted.has((0, node_path_1.resolve)(process.cwd(), specPath)));
+        })()
+        : allSpecs;
+    if (specs.length === 0)
+        return { valid: true, pairCount: 0 };
+    let totalPairs = 0;
+    let specsWithDuplicates = 0;
+    for (const specPath of specs) {
+        const spec = await loadSpec(specPath);
+        if (!spec || spec._specType !== "claude")
+            continue;
+        const rules = spec.rules;
+        const ruleCount = Object.keys(rules).length;
+        if (ruleCount < 2)
+            continue;
+        // Guard against unknown rule kinds (legacy "check" artifacts, JS
+        // callers) that would crash ruleToText inside findSimilarRules.
+        // Same pattern as the try/catch in runProofSuite.
+        let pairs;
+        try {
+            pairs = (0, proofs_js_1.findSimilarRules)(rules, threshold);
+        }
+        catch (e) {
+            log(`  ⚠ ${specPath}: similarity check failed (${e instanceof Error ? e.message : String(e)})`);
+            continue;
+        }
+        if (pairs.length === 0)
+            continue;
+        if (specsWithDuplicates === 0) {
+            log(`Found near-duplicate rules (NCD < ${String(threshold)}):\n`);
+        }
+        specsWithDuplicates++;
+        totalPairs += pairs.length;
+        log(`  ${specPath}`);
+        for (const pair of pairs.slice(0, 5)) {
+            log(`    ${pair.idA}  ↔  ${pair.idB}  (distance: ${pair.distance.toFixed(3)})`);
+        }
+        if (pairs.length > 5) {
+            log(`    ... and ${String(pairs.length - 5)} more`);
+        }
+    }
+    if (totalPairs === 0) {
+        log("No near-duplicate rules detected.");
+        return { valid: true, pairCount: 0 };
+    }
+    log(`\n  ${String(totalPairs)} duplicate pair(s) in ${String(specsWithDuplicates)} spec(s). Consider merging or rewording.`);
+    return { valid: false, pairCount: totalPairs };
+}
+/** Exit codes: 0 clean, 1 warnings only, 2 hard errors. */
+function auditExitCode(report) {
+    if (report.hashErrors > 0 ||
+        report.validationErrors > 0 ||
+        report.inlineErrors > 0 ||
+        report.freshnessErrors > 0)
+        return 2;
+    if (report.duplicatePairs > 0)
+        return 1;
+    // Coverage gaps and guidance counts are informational, not failures
+    return 0;
+}
+/**
+ * Verify inline `<!-- vigiles:enforce ... -->` comments in an instruction
+ * file. Each comment's linter rule goes through the same verification as
+ * spec-declared enforce rules (existence, enabled status, closest-match
+ * suggestions on typo).
+ */
+function verifyInlineRules(filePath, silent, linterOptions) {
+    const log = (msg) => {
+        if (!silent)
+            console.log(msg);
+    };
+    let content;
+    try {
+        content = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), filePath), "utf-8");
+    }
+    catch {
+        return { ok: true, errorCount: 0, ruleCount: 0 };
+    }
+    const { rules, errors: parseErrors } = (0, inline_js_1.parseInlineRules)(content);
+    if (rules.length === 0 && parseErrors.length === 0) {
+        return { ok: true, errorCount: 0, ruleCount: 0 };
+    }
+    let errorCount = 0;
+    log(`\n${filePath} (inline mode):`);
+    for (const err of parseErrors) {
+        log(`  ✗ line ${String(err.line)}: ${err.message}`);
+        errorCount++;
+        if (!silent) {
+            ghAnnotate("error", err.message, filePath, err.line);
+        }
+    }
+    for (const rule of rules) {
+        const result = (0, linters_js_1.checkLinterRule)(rule.linterRule, process.cwd(), linterOptions);
+        if (!result.exists) {
+            const message = result.error ?? `Rule "${rule.linterRule}" not found`;
+            log(`  ✗ line ${String(rule.line)}: ${message}`);
+            errorCount++;
+            if (!silent) {
+                ghAnnotate("error", message, filePath, rule.line);
+            }
+        }
+        else if (result.enabled === "disabled") {
+            const message = `Rule "${rule.linterRule}" exists but is disabled in ${result.linter} config`;
+            log(`  ✗ line ${String(rule.line)}: ${message}`);
+            errorCount++;
+            if (!silent) {
+                ghAnnotate("error", message, filePath, rule.line);
+            }
+        }
+        else {
+            log(`  ✓ line ${String(rule.line)}: ${rule.linterRule}`);
+        }
+    }
+    return { ok: errorCount === 0, errorCount, ruleCount: rules.length };
+}
+/**
+ * Unified audit command: verify hashes, report coverage gaps, detect duplicates,
+ * suggest improvements.
+ *
+ * Flags:
+ *   --summary   Print a single-line summary (for SessionStart hooks)
+ *   --json      Print structured JSON report (for CI integration)
+ */
+async function audit(restArgs, flags, config) {
+    const summary = flags.includes("--summary");
+    const json = flags.includes("--json");
+    const silent = summary || json;
+    const files = findInstructionFiles(restArgs);
+    // 1. Verify hashes and structure
+    if (!silent) {
+        if (files.length > 0) {
+            console.log("Verifying compiled files...\n");
+        }
+        else {
+            console.log("No compiled instruction files found.\n");
+        }
+    }
+    const hashResult = files.length > 0
+        ? check(files, silent)
+        : { valid: true, hashErrors: 0, validationErrors: 0 };
+    // 1b. Verify inline vigiles:enforce comments in any instruction file
+    // that isn't already managed by a .spec.ts. Spec mode is the source of
+    // truth when it exists, so a literal `<!-- vigiles:enforce ... -->`
+    // snippet that survived into the compiled markdown (or an
+    // explanatory example in a spec-managed file) must not trip audit.
+    // A file is spec-managed iff it has a sibling `<file>.spec.ts` OR its
+    // own `<!-- vigiles:sha256:... compiled from <spec> -->` header.
+    // See docs/inline-mode.md.
+    let inlineErrors = 0;
+    let inlineRules = 0;
+    if (!silent && files.length > 0) {
+        console.log("\nInline rule verification:");
+    }
+    const compiledFromRe = /<!--\s*vigiles:sha256:[a-f0-9]+\s+compiled from .+?\s*-->/;
+    for (const filePath of files) {
+        const abs = (0, node_path_1.resolve)(process.cwd(), filePath);
+        if ((0, node_fs_1.existsSync)(`${abs}.spec.ts`)) {
+            continue; // managed by sibling spec
+        }
+        let content;
+        try {
+            content = (0, node_fs_1.readFileSync)(abs, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        if (compiledFromRe.test(content)) {
+            continue; // managed by the spec referenced in the hash header
+        }
+        const result = verifyInlineRules(filePath, silent, {
+            catalogOnly: config?.catalogOnly,
+            linters: config?.linters,
+        });
+        inlineErrors += result.errorCount;
+        inlineRules += result.ruleCount;
+    }
+    if (!silent && files.length > 0 && inlineRules === 0) {
+        console.log("  (no inline vigiles:enforce comments found)");
+    }
+    // 2. Coverage gaps (discover)
+    if (!silent)
+        console.log("\nLinter rule coverage:\n");
+    const coverage = discover(silent);
+    // 3. Duplicate rule detection (NCD). Scope to the requested files when
+    // audit was invoked with explicit paths, so targeted CI checks don't
+    // fail on unrelated duplicates elsewhere in the repo.
+    if (!silent)
+        console.log("\nDuplicate rule detection:\n");
+    const dups = await findDuplicateRules(0.3, silent, restArgs.length > 0 ? files : undefined);
+    // 4. Guidance rule count (strengthen suggestions moved to /strengthen skill)
+    const guidanceCount = await countGuidanceRules(silent);
+    // 5. Freshness check
+    const freshnessSeverity = config?.rules.freshness;
+    let freshnessErrors = 0;
+    if (freshnessSeverity) {
+        if (!silent)
+            console.log("\nFreshness check:\n");
+        const mode = config?.freshnessMode ?? "strict";
+        freshnessErrors = await checkFreshness(files, mode, config, freshnessSeverity, silent);
+    }
+    const report = {
+        hashErrors: hashResult.hashErrors,
+        validationErrors: hashResult.validationErrors,
+        inlineErrors,
+        inlineRules,
+        duplicatePairs: dups.pairCount,
+        coverageEnabled: coverage.enabled,
+        coverageDocumented: coverage.documented,
+        strengthenSuggestions: guidanceCount,
+        freshnessErrors,
+        files,
+    };
+    if (summary) {
+        printAuditSummary(report);
+    }
+    else if (json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    return report;
+}
+/** Single-line audit summary for SessionStart hooks — minimal token cost. */
+function printAuditSummary(report) {
+    const parts = [];
+    if (report.hashErrors > 0)
+        parts.push(`${String(report.hashErrors)} stale`);
+    if (report.validationErrors > 0)
+        parts.push(`${String(report.validationErrors)} validation errors`);
+    if (report.inlineErrors > 0)
+        parts.push(`${String(report.inlineErrors)} inline errors`);
+    if (report.duplicatePairs > 0)
+        parts.push(`${String(report.duplicatePairs)} duplicates`);
+    const undocumented = report.coverageEnabled - report.coverageDocumented;
+    if (undocumented > 0)
+        parts.push(`${String(undocumented)} undocumented rules`);
+    if (report.strengthenSuggestions > 0)
+        parts.push(`${String(report.strengthenSuggestions)} guidance (run /strengthen to upgrade)`);
+    if (report.freshnessErrors > 0)
+        parts.push(`${String(report.freshnessErrors)} stale (run vigiles compile)`);
+    if (parts.length === 0) {
+        console.log("vigiles: clean");
+    }
+    else {
+        console.log(`vigiles: ${parts.join(" / ")}`);
+    }
+}
+function collectDocumentedRules() {
+    const documented = new Set();
+    const mdFiles = (0, glob_1.globSync)("**/CLAUDE.md", {
+        ignore: IGNORE_NODE_MODULES,
+        cwd: process.cwd(),
+    });
+    for (const mdFile of mdFiles) {
+        const content = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), mdFile), "utf-8");
+        const enforcedRe = /\*\*Enforced by:\*\*\s*`([^`]+)`/g;
+        let m;
+        while ((m = enforcedRe.exec(content)) !== null) {
+            documented.add(m[1]);
+        }
+    }
+    return documented;
+}
+function printLinterCoverage(linter, documentedRules, silent = false) {
+    const log = (msg) => {
+        if (!silent)
+            console.log(msg);
+    };
+    const documented = linter.rules.filter((r) => documentedRules.has(`${linter.linter}/${r}`));
+    const undocumented = linter.rules.filter((r) => !documentedRules.has(`${linter.linter}/${r}`));
+    const pct = linter.rules.length > 0
+        ? Math.round((documented.length / linter.rules.length) * 100)
+        : 0;
+    log(`  ${linter.linter}: ${String(documented.length)}/${String(linter.rules.length)} rules documented (${String(pct)}%)`);
+    if (documented.length > 0 && documented.length <= 10) {
+        for (const r of documented) {
+            log(`    ✓ ${linter.linter}/${r}`);
+        }
+    }
+    if (undocumented.length > 0) {
+        const show = undocumented.slice(0, 5);
+        log(`    Top undocumented:`);
+        for (const r of show) {
+            log(`    ✗ ${linter.linter}/${r}`);
+        }
+        if (undocumented.length > 5) {
+            log(`    ... and ${String(undocumented.length - 5)} more`);
+        }
+    }
+    log("");
+    return { enabled: linter.rules.length, documented: documented.length };
+}
+function discover(silent = false) {
+    const log = (msg) => {
+        if (!silent)
+            console.log(msg);
+    };
+    log("Scanning project for linter rules...\n");
+    const result = (0, generate_types_js_1.generateTypes)({ basePath: process.cwd() });
+    const documentedRules = collectDocumentedRules();
+    log("Detected linters:\n");
+    let totalEnabled = 0;
+    let totalDocumented = 0;
+    for (const linter of result.linters) {
+        const totals = printLinterCoverage(linter, documentedRules, silent);
+        totalEnabled += totals.enabled;
+        totalDocumented += totals.documented;
+    }
+    if (result.linters.length === 0) {
+        log("  No linters detected.\n");
+    }
+    const totalPct = totalEnabled > 0 ? Math.round((totalDocumented / totalEnabled) * 100) : 0;
+    log(`Coverage: ${String(totalDocumented)}/${String(totalEnabled)} rules documented (${String(totalPct)}%)`);
+    if (totalDocumented < totalEnabled) {
+        log(`\nConsider adding enforce() rules for frequently-triggered undocumented rules.`);
+        log(`The agent encounters these rules but has no context about WHY.`);
+    }
+    return { enabled: totalEnabled, documented: totalDocumented };
+}
+function init(args) {
+    const targetFlag = args.find((a) => a.startsWith("--target="));
+    const target = targetFlag ? targetFlag.split("=")[1] : "CLAUDE.md";
+    const specPath = `${target}.spec.ts`;
+    if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(process.cwd(), specPath))) {
+        console.log(`${specPath} already exists.`);
+        return;
+    }
+    const targetLine = target !== "CLAUDE.md" ? `\n  target: "${target}",` : "";
+    const template = `import { claude, enforce, guidance } from "vigiles/spec";
+
+export default claude({${targetLine}
+  sections: {
+    // Prose sections become ## headings in the compiled output.
+    // Do not add # or ## headers inside sections.
+    // positioning: "What this project does and why.",
+
+    // This section is included in the compiled output to help agents
+    // understand how to work with specs. Remove it once your team is familiar.
+    "how-to-edit": "This file is compiled from a .spec.ts file. Do not edit it directly — edit the spec and run 'npx vigiles compile'. To add a rule: add to the rules object in the spec.",
+  },
+
+  commands: {
+    // Commands are verified against package.json at compile time.
+    // "npm run build": "Compile the project",
+    // "npm test": "Run all tests",
+  },
+
+  keyFiles: {
+    // File paths are verified to exist at compile time.
+    // "src/index.ts": "Main entry point",
+  },
+
+  rules: {
+    // enforce() — backed by a linter rule, verified to exist AND be enabled:
+    // "no-console": enforce("eslint/no-console", "Use structured logger."),
+    //
+    // guidance() — prose only, no enforcement:
+    // "research-first": guidance("Google unfamiliar APIs before implementing."),
+  },
+});
+`;
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), specPath), template);
+    console.log(`Created ${specPath} — edit it and run \`vigiles compile\`.`);
+}
+// ---------------------------------------------------------------------------
+// Setup wizard
+// ---------------------------------------------------------------------------
+const VIGILES_CI_STEP = `      - name: Verify specs
+        run: npx vigiles audit && npx vigiles generate-types --check`;
+function addGhaStep() {
+    // Find existing GHA workflow
+    const ciPaths = [
+        ".github/workflows/ci.yml",
+        ".github/workflows/ci.yaml",
+        ".github/workflows/main.yml",
+        ".github/workflows/main.yaml",
+        ".github/workflows/test.yml",
+        ".github/workflows/test.yaml",
+    ];
+    for (const ciPath of ciPaths) {
+        const fullPath = (0, node_path_1.resolve)(process.cwd(), ciPath);
+        if ((0, node_fs_1.existsSync)(fullPath)) {
+            const content = (0, node_fs_1.readFileSync)(fullPath, "utf-8");
+            if (content.includes("vigiles")) {
+                console.log(`✓ ${ciPath} already has vigiles steps`);
+                return true;
+            }
+            // Append step at end of file (safe for all YAML formats)
+            const trimmed = content.trimEnd();
+            (0, node_fs_1.writeFileSync)(fullPath, trimmed + "\n\n" + VIGILES_CI_STEP + "\n");
+            console.log(`✓ Added vigiles check step to ${ciPath}`);
+            return true;
+        }
+    }
+    return false;
+}
+const KNOWN_INSTRUCTION_FILES = ["CLAUDE.md", "AGENTS.md"];
+const KNOWN_OTHER_CONFIGS = {
+    ".cursorrules": "Cursor",
+    ".github/copilot-instructions.md": "GitHub Copilot",
+    ".windsurfrules": "Windsurf",
+};
+const KNOWN_SYNC_TOOLS = [
+    "rule-porter",
+    "rulesync",
+    "vibe-cli",
+    "@nichochar/rule-porter",
+];
+function detectProject() {
+    const cwd = process.cwd();
+    const instructionFiles = [];
+    const agents = [];
+    const otherConfigs = [];
+    // Check known instruction files
+    for (const f of KNOWN_INSTRUCTION_FILES) {
+        const full = (0, node_path_1.resolve)(cwd, f);
+        if ((0, node_fs_1.existsSync)(full)) {
+            let isSymlink = false;
+            try {
+                isSymlink = (0, node_fs_1.lstatSync)(full).isSymbolicLink();
+            }
+            catch {
+                // ignore
+            }
+            const hasSpec = (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, `${f}.spec.ts`));
+            instructionFiles.push({ path: f, hasSpec, isSymlink });
+        }
+    }
+    // Detect agents from files
+    if (instructionFiles.some((f) => f.path === "CLAUDE.md") ||
+        (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, ".claude"))) {
+        agents.push("Claude Code");
+    }
+    if (instructionFiles.some((f) => f.path === "AGENTS.md")) {
+        agents.push("Codex / GitHub Copilot");
+    }
+    // Check non-markdown configs
+    for (const [path, agent] of Object.entries(KNOWN_OTHER_CONFIGS)) {
+        if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, path))) {
+            otherConfigs.push(`${path} (${agent})`);
+            if (!agents.includes(agent))
+                agents.push(agent);
+        }
+    }
+    // Check for sync tools in package.json
+    const syncTools = [];
+    const pkgPath = (0, node_path_1.resolve)(cwd, "package.json");
+    if ((0, node_fs_1.existsSync)(pkgPath)) {
+        try {
+            const pkg = JSON.parse((0, node_fs_1.readFileSync)(pkgPath, "utf-8"));
+            const allDeps = {
+                ...pkg.dependencies,
+                ...pkg.devDependencies,
+            };
+            for (const tool of KNOWN_SYNC_TOOLS) {
+                if (tool in allDeps)
+                    syncTools.push(tool);
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return {
+        instructionFiles,
+        agents,
+        syncTools,
+        otherConfigs,
+        hasClaude: (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, ".claude")),
+    };
+}
+async function setup(args) {
+    const targetFlag = args.find((a) => a.startsWith("--target="));
+    const strict = args.includes("--strict");
+    const noGha = args.includes("--no-gha");
+    console.log(`vigiles setup${strict ? " (strict mode)" : ""}\n`);
+    // Step 1: Detect project
+    const detected = detectProject();
+    if (detected.agents.length > 0) {
+        console.log(`Detected: ${detected.agents.join(", ")}`);
+    }
+    if (detected.otherConfigs.length > 0) {
+        console.log(`Other agent configs: ${detected.otherConfigs.join(", ")}`);
+    }
+    if (detected.syncTools.length > 0) {
+        console.log(`Sync tools: ${detected.syncTools.join(", ")}`);
+    }
+    for (const f of detected.instructionFiles) {
+        if (f.isSymlink) {
+            console.log(`Note: ${f.path} is a symlink`);
+        }
+    }
+    if (detected.agents.length > 0 ||
+        detected.otherConfigs.length > 0 ||
+        detected.syncTools.length > 0) {
+        console.log("");
+    }
+    // Step 2: Determine targets
+    let targets;
+    if (targetFlag) {
+        targets = [targetFlag.split("=")[1]];
+    }
+    else {
+        // Auto-detect: create specs for instruction files that need them
+        const needsSpec = detected.instructionFiles.filter((f) => !f.hasSpec);
+        if (needsSpec.length > 0) {
+            // Existing files without specs — suggest migration
+            for (const f of needsSpec) {
+                console.log(`Found ${f.path} without a spec. Migrate with the migrate-to-spec skill`);
+                console.log(`  or create a blank spec: npx vigiles init --target=${f.path}\n`);
+            }
+            const hasAnySpec = detected.instructionFiles.some((f) => f.hasSpec);
+            if (!hasAnySpec &&
+                needsSpec.length === detected.instructionFiles.length) {
+                // ALL existing files need migration — don't create new ones
+                console.log("Install the plugin to use the migration skill:");
+                console.log("  npx skills add zernie/vigiles");
+                return;
+            }
+        }
+        // Default: CLAUDE.md, plus AGENTS.md if Codex detected
+        targets = ["CLAUDE.md"];
+        const hasAgentsMd = detected.instructionFiles.some((f) => f.path === "AGENTS.md");
+        const hasCodex = detected.agents.includes("Codex / GitHub Copilot") || hasAgentsMd;
+        if (hasCodex && !hasAgentsMd) {
+            targets.push("AGENTS.md");
+        }
+    }
+    // Step 3: Create specs
+    for (const target of targets) {
+        const specPath = `${target}.spec.ts`;
+        if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(process.cwd(), specPath))) {
+            console.log(`✓ ${specPath} already exists`);
+        }
+        else if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(process.cwd(), target))) {
+            console.log(`⚠ ${target} exists without spec — migrate with migrate-to-spec skill`);
+        }
+        else {
+            init(["--target=" + target]);
+        }
+    }
+    // Step 4: Generate types
+    console.log("\nScanning linters and project files...");
+    const typesResult = (0, generate_types_js_1.generateTypes)({ basePath: process.cwd() });
+    const outPath = ".vigiles/generated.d.ts";
+    const outDir = (0, node_path_1.resolve)(process.cwd(), ".vigiles");
+    if (!(0, node_fs_1.existsSync)(outDir)) {
+        (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
+    }
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outPath), typesResult.dts);
+    for (const l of typesResult.linters) {
+        console.log(`  ${l.linter}: ${String(l.rules.length)} rules`);
+    }
+    if (typesResult.scripts.length > 0) {
+        console.log(`  npm scripts: ${String(typesResult.scripts.length)}`);
+    }
+    console.log(`✓ Generated ${outPath}`);
+    // Step 5: Compile specs
+    console.log("\nCompiling specs...");
+    const specs = findSpecs();
+    if (specs.length > 0) {
+        await compile(specs, (0, validate_js_1.loadConfig)());
+    }
+    // Step 6: Add CI step
+    console.log("");
+    const addedGha = noGha ? false : addGhaStep();
+    if (!addedGha) {
+        console.log("  No CI workflow found. Add this step to your CI:\n");
+        console.log("    npx vigiles audit && npx vigiles generate-types --check");
+    }
+    // Step 7: Install Claude Code plugin (hooks + skills)
+    const shouldInstallPlugin = detected.hasClaude || targets.includes("CLAUDE.md");
+    if (shouldInstallPlugin) {
+        let pluginInstalled = false;
+        // Try installing the full plugin via skills CLI (gives hooks + skills)
+        try {
+            const { execSync: exec } = require("node:child_process");
+            exec("npx skills add zernie/vigiles", {
+                cwd: process.cwd(),
+                stdio: ["pipe", "pipe", "pipe"],
+                timeout: 30000,
+            });
+            pluginInstalled = true;
+            console.log("✓ Installed vigiles plugin (hooks + skills) via skills CLI");
+        }
+        catch {
+            // skills CLI not available — fall back to direct hook installation
+        }
+        if (!pluginInstalled) {
+            // Fall back: write hooks directly to .claude/settings.json
+            // (gives auto-compile + block edits, but no skills)
+            const settingsDir = (0, node_path_1.resolve)(process.cwd(), ".claude");
+            const settingsPath = (0, node_path_1.resolve)(settingsDir, "settings.json");
+            if (!(0, node_fs_1.existsSync)(settingsDir)) {
+                (0, node_fs_1.mkdirSync)(settingsDir, { recursive: true });
+            }
+            let settings = {};
+            if ((0, node_fs_1.existsSync)(settingsPath)) {
+                try {
+                    settings = JSON.parse((0, node_fs_1.readFileSync)(settingsPath, "utf-8"));
+                }
+                catch {
+                    // Ignore malformed settings
+                }
+            }
+            if (!settings["hooks"]) {
+                settings["hooks"] = {};
+            }
+            const hooks = settings["hooks"];
+            const preCmd = `FILE=$(cat | jq -r '.tool_input.file_path // empty') && case "$FILE" in *.md) [ -f "$FILE" ] && head -1 "$FILE" | grep -q 'vigiles:sha256:' && { SPEC=$(head -1 "$FILE" | sed -n 's/.*compiled from \\(.*\\) -->/\\1/p'); echo "BLOCKED: Edit $SPEC instead." >&2; exit 2; } ;; esac; exit 0`;
+            const postCmd = `FILE=$(cat | jq -r '.tool_input.file_path // empty') && case "$(basename "$FILE")" in eslint.config.*|.eslintrc*|package.json|pyproject.toml|Cargo.toml) npx vigiles generate-types 2>&1 || true ;; esac && case "$FILE" in *.spec.ts) npx vigiles compile 2>&1 || true ;; esac`;
+            // Append to existing arrays (don't duplicate if already present)
+            const existingStr = JSON.stringify(settings);
+            if (!existingStr.includes("vigiles:sha256")) {
+                const pre = (hooks["PreToolUse"] ?? []);
+                pre.push({ matcher: "Edit|Write", command: preCmd });
+                hooks["PreToolUse"] = pre;
+            }
+            if (!existingStr.includes("vigiles compile")) {
+                const post = (hooks["PostToolUse"] ?? []);
+                post.push({ matcher: "Edit|Write", command: postCmd });
+                hooks["PostToolUse"] = post;
+            }
+            (0, node_fs_1.writeFileSync)(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+            console.log("✓ Installed hooks in .claude/settings.json");
+            console.log("  (For skills like edit-spec and migrate-to-spec, also run: npx skills add zernie/vigiles)");
+        }
+    }
+    // Step 8: Agent-specific guidance
+    const specPathsList = targets.map((t) => `${t}.spec.ts`);
+    const specPaths = specPathsList.join(", ");
+    if (targets.includes("AGENTS.md")) {
+        console.log("\n  Codex / Copilot reads AGENTS.md directly — no hooks needed.");
+        console.log("  Run `npx vigiles compile` after spec edits. CI enforces freshness.");
+    }
+    if (detected.otherConfigs.length > 0 && detected.syncTools.length === 0) {
+        console.log("\n  Non-markdown agent configs detected. Use a sync tool to convert:");
+        console.log("    npm install -D rule-porter");
+    }
+    // Step 8b: Write config if strict mode
+    if (strict) {
+        const configPath = (0, node_path_1.resolve)(process.cwd(), ".vigilesrc.json");
+        if (!(0, node_fs_1.existsSync)(configPath)) {
+            (0, node_fs_1.writeFileSync)(configPath, JSON.stringify({
+                rules: {
+                    "require-spec": "error",
+                    "require-skill-spec": "error",
+                },
+            }, null, 2) + "\n");
+            console.log("✓ Created .vigilesrc.json with strict rules");
+        }
+    }
+    // Step 9: Summary
+    console.log("\n---");
+    console.log("Setup complete.\n");
+    console.log(`  1. Edit ${specPaths} — add your project's conventions`);
+    console.log("  2. Run `/strengthen` in Claude Code to upgrade guidance → enforce");
+    if (!strict) {
+        console.log("  3. When ready, enforce specs in CI: npx vigiles setup --strict");
+    }
+    console.log("\n  Commit:");
+    const files = [
+        ...targets,
+        ...specPathsList,
+        ".vigiles/generated.d.ts",
+        ...(shouldInstallPlugin ? [".claude/settings.json"] : []),
+        ...(strict ? [".vigilesrc.json"] : []),
+    ];
+    console.log(`    git add ${files.join(" ")} && git commit -m "Add vigiles spec"`);
+}
+// ---------------------------------------------------------------------------
+// Strengthen: guidance() → enforce() suggestions
+// ---------------------------------------------------------------------------
+async function checkFreshness(files, mode, config, severity, silent) {
+    const log = (msg) => {
+        if (!silent)
+            console.log(msg);
+    };
+    let errorCount = 0;
+    const basePath = process.cwd();
+    for (const filePath of files) {
+        const abs = (0, node_path_1.resolve)(basePath, filePath);
+        if (!(0, node_fs_1.existsSync)(abs))
+            continue;
+        const content = (0, node_fs_1.readFileSync)(abs, "utf-8");
+        // Find the spec that compiled this file
+        const hashMatch = content.match(/<!--\s*vigiles:sha256:[a-f0-9]+\s+compiled from (.+?)\s*-->/);
+        if (!hashMatch) {
+            // No hash = hand-written file, skip freshness check
+            continue;
+        }
+        let result;
+        const specFile = hashMatch[1];
+        if (mode === "strict") {
+            // Recompile in memory and diff
+            const spec = await loadSpec(specFile);
+            if (!spec || spec._specType !== "claude") {
+                log(`  ? ${filePath} — can't load spec "${specFile}", skipping`);
+                continue;
+            }
+            const compiled = (0, compile_js_1.compileClaude)(spec, {
+                basePath,
+                specFile,
+                maxRules: config?.maxRules,
+                maxTokens: config?.maxTokens,
+                maxSectionLines: config?.maxSectionLines,
+                catalogOnly: config?.catalogOnly,
+                linters: config?.linters,
+            });
+            // Compare markdown body (strip hash/input lines)
+            const metaRe = /^<!-- vigiles:(sha256|inputs):[^\n]+ -->\r?\n?/gm;
+            const existingBody = content.replace(metaRe, "").trim();
+            const compiledBody = compiled.markdown.replace(metaRe, "").trim();
+            if (existingBody === compiledBody) {
+                result = { fresh: true, mode: "strict" };
+            }
+            else {
+                result = {
+                    fresh: false,
+                    mode: "strict",
+                    reason: "Output would differ if recompiled — run `vigiles compile`",
+                };
+            }
+        }
+        else if (mode === "input-hash") {
+            const specFile = hashMatch[1];
+            const spec = await loadSpec(specFile);
+            if (!spec || spec._specType !== "claude") {
+                log(`  ? ${filePath} — can't load spec "${specFile}", skipping`);
+                continue;
+            }
+            const inputs = (0, freshness_js_1.discoverInputs)(specFile, spec, basePath, config?.freshnessInputs);
+            result = (0, freshness_js_1.checkInputHashFreshness)(content, inputs.files, basePath);
+        }
+        else {
+            // output-hash mode
+            result = (0, freshness_js_1.checkOutputHashFreshness)(content);
+        }
+        if (!result.fresh) {
+            errorCount++;
+            const marker = severity === "error" ? "✗" : "⚠";
+            log(`  ${marker} ${filePath} — ${result.reason ?? "stale"}`);
+            if (result.changedFiles && result.changedFiles.length > 0) {
+                for (const f of result.changedFiles) {
+                    log(`    changed: ${f}`);
+                }
+            }
+        }
+        else if (!silent) {
+            log(`  ✓ ${filePath} — fresh (${mode})`);
+        }
+    }
+    if (errorCount === 0) {
+        log("  All files fresh.");
+    }
+    return severity === "error" ? errorCount : 0;
+}
+async function countGuidanceRules(silent = false) {
+    const specs = findSpecs();
+    if (specs.length === 0)
+        return 0;
+    let count = 0;
+    for (const specPath of specs) {
+        const spec = await loadSpec(specPath);
+        if (!spec || spec._specType !== "claude")
+            continue;
+        for (const rule of Object.values(spec.rules)) {
+            if (rule._kind === "guidance")
+                count++;
+        }
+    }
+    if (!silent && count > 0) {
+        console.log(`${String(count)} guidance rule(s) — run /strengthen to find enforce() upgrades\n`);
+    }
+    return count;
+}
+// ---------------------------------------------------------------------------
+// Command handlers for main()
+// ---------------------------------------------------------------------------
+function findInstructionFiles(restArgs) {
+    if (restArgs.length > 0)
+        return restArgs;
+    const patterns = ["**/CLAUDE.md", "**/AGENTS.md", "**/SKILL.md"];
+    const files = [];
+    for (const pattern of patterns) {
+        files.push(...(0, glob_1.globSync)(pattern, { ignore: IGNORE_NODE_MODULES, cwd: process.cwd() }));
+    }
+    return files;
+}
+function handleGenerateTypes(args, restArgs) {
+    const checkOnly = args.includes("--check");
+    const outPath = restArgs[0] ?? ".vigiles/generated.d.ts";
+    const fileGlobs = args
+        .filter((a) => a.startsWith("--files="))
+        .map((a) => a.split("=")[1])
+        .filter(Boolean);
+    console.log("Scanning project...\n");
+    const result = (0, generate_types_js_1.generateTypes)({
+        basePath: process.cwd(),
+        fileGlobs: fileGlobs.length > 0 ? fileGlobs : undefined,
+    });
+    for (const l of result.linters) {
+        console.log(`  ${l.linter}: ${String(l.rules.length)} enabled rules (via ${l.via})`);
+    }
+    if (result.scripts.length > 0) {
+        console.log(`  npm scripts: ${String(result.scripts.length)}`);
+    }
+    console.log(`  project files: ${String(result.files.length)}`);
+    const fullOut = (0, node_path_1.resolve)(process.cwd(), outPath);
+    if (checkOnly) {
+        // --check: compare against existing file, exit 1 if stale
+        if (!(0, node_fs_1.existsSync)(fullOut)) {
+            console.log(`\n✗ ${outPath} does not exist. Run \`vigiles generate-types\` to create it.`);
+            process.exit(1);
+        }
+        const existing = (0, node_fs_1.readFileSync)(fullOut, "utf-8");
+        // Normalize for formatter differences (trailing whitespace, blank lines)
+        const normalize = (s) => s
+            .split("\n")
+            .map((l) => l.trimEnd())
+            .join("\n")
+            .replace(/\n{3,}/g, "\n\n")
+            .trim();
+        if (normalize(existing) === normalize(result.dts)) {
+            console.log(`\n✓ ${outPath} is up to date`);
+        }
+        else {
+            console.log(`\n✗ ${outPath} is stale. Run \`vigiles generate-types\` to update.`);
+            process.exit(1);
+        }
+        return;
+    }
+    const outDir = fullOut.substring(0, fullOut.lastIndexOf("/"));
+    if (!(0, node_fs_1.existsSync)(outDir)) {
+        (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
+    }
+    (0, node_fs_1.writeFileSync)(fullOut, result.dts);
+    console.log(`\n✓ Generated ${outPath}`);
+}
+function printUsage(command) {
+    console.log("vigiles — compile typed specs to instruction files");
+    console.log("");
+    console.log("Commands:");
+    console.log("  vigiles init [flags]           Setup project (--target=X.md, --strict, --no-gha)");
+    console.log("  vigiles compile [files...]     Compile .spec.ts → .md");
+    console.log("  vigiles audit [files...]       Verify, find gaps, suggest improvements");
+    console.log("");
+    console.log("Examples:");
+    console.log("  vigiles init                 Auto-detect project, create specs, wire CI");
+    console.log("  vigiles compile              Compile all .spec.ts files");
+    console.log("  vigiles audit                Verify hashes + coverage + suggestions");
+    console.log("");
+    console.log("Plumbing:");
+    console.log("  vigiles generate-types [out]  Emit .d.ts from project state");
+    console.log("  vigiles generate-types --check  Verify .d.ts is up to date");
+    if (command && command !== "--help") {
+        console.log(`\nUnknown command: "${command}"`);
+        process.exit(1);
+    }
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    const restArgs = args.slice(1).filter((a) => !a.startsWith("--"));
+    const config = (0, validate_js_1.loadConfig)();
+    switch (command) {
+        // --- Primary commands ---
+        case "init": {
+            // Explicit --target bypasses the setup wizard and always creates a
+            // bare spec, so `npx vigiles init --target=<file>` is a reliable
+            // remediation for the require-spec validator. Bare `vigiles init`
+            // still runs the full wizard (project detection + auto-targets).
+            const hasTarget = args.some((a) => a.startsWith("--target="));
+            if (hasTarget) {
+                init(args.slice(1));
+            }
+            else {
+                await setup(args);
+            }
+            break;
+        }
+        case "compile": {
+            const specs = restArgs.length > 0 ? restArgs : findSpecs();
+            if (specs.length === 0) {
+                console.log("No .spec.ts files found.");
+                console.log("Run `vigiles init` to create one.");
+                process.exit(0);
+            }
+            const valid = await compile(specs, config);
+            console.log("");
+            if (valid) {
+                console.log("Compilation complete.");
+            }
+            else {
+                console.log("Compilation complete with errors.");
+                process.exit(1);
+            }
+            break;
+        }
+        case "audit": {
+            // audit = verify + discover + guidance count
+            const flags = args.slice(1).filter((a) => a.startsWith("--"));
+            const report = await audit(restArgs, flags, config);
+            const exitCode = auditExitCode(report);
+            // Skip GH annotations when --json or --summary is active —
+            // those modes promise clean machine-readable stdout, and
+            // ::error/::warning lines would contaminate the output for
+            // callers parsing it as JSON.
+            const structuredOutput = flags.includes("--json") || flags.includes("--summary");
+            if (isGitHubActions() && !structuredOutput) {
+                if (report.hashErrors > 0) {
+                    ghAnnotate("error", `${String(report.hashErrors)} compiled file(s) with stale hash — run vigiles compile`);
+                }
+                if (report.validationErrors > 0) {
+                    ghAnnotate("error", `${String(report.validationErrors)} spec validation failure(s) — see audit output`);
+                }
+                if (report.duplicatePairs > 0) {
+                    ghAnnotate("warning", `${String(report.duplicatePairs)} near-duplicate rule pair(s) detected — consider merging`);
+                }
+            }
+            if (exitCode !== 0) {
+                process.exit(exitCode);
+            }
+            break;
+        }
+        // --- Plumbing ---
+        case "generate-types":
+            handleGenerateTypes(args, restArgs);
+            break;
+        default:
+            printUsage(command);
+            break;
+    }
+}
+void main();
+//# sourceMappingURL=cli.js.map