@vaultcompass/vault-guard 1.1.1 → 1.2.0

package/dist/cli-entry.js

@@ -9,11 +9,8 @@ if (nodeMajor < 22) {
 }
 const program = (0, cli_1.buildCli)();
 // Parse arguments and execute command
-program.parseAsync().then(() => {
-    // Successful completion
-    process.exit(0);
-}).catch((error) => {
+program.parseAsync().catch((error) => {
     // Handle errors
     console.error(error);
-    process.exit(1);
+    process.exitCode = 1;
 });

package/dist/cli.js

@@ -47,11 +47,17 @@ const suggest_model_1 = require("./commands/suggest-model");
 const proxy_1 = require("./commands/proxy");
 const data_1 = require("./commands/data");
 const config_1 = require("./commands/config");
+const init_1 = require("./commands/init");
 function readCliVersion() {
     const pkgPath = path.join(__dirname, '..', 'package.json');
     const raw = fs.readFileSync(pkgPath, 'utf-8');
     return JSON.parse(raw).version;
 }
+function setExitCode(exitCode) {
+    if (exitCode !== 0) {
+        process.exitCode = exitCode;
+    }
+}
 function buildCli() {
     const program = new commander_1.Command();
     program
@@ -64,8 +70,7 @@ function buildCli() {
         .description('Validate the nearest .vault-guard.json (structure + scanner load)')
         .action(async () => {
         const exitCode = await (0, config_1.configValidateCommand)(process.cwd());
-        if (exitCode !== 0)
-            process.exit(exitCode);
+        setExitCode(exitCode);
     });
     // Scan command
     program
@@ -77,9 +82,37 @@ function buildCli() {
         .action(async (path, options) => {
         const format = options.format ?? 'text';
         const exitCode = await (0, scan_1.scanCommand)(path, format, Boolean(options.staged));
-        if (exitCode !== 0) {
-            process.exit(exitCode);
+        setExitCode(exitCode);
+    });
+    program
+        .command('init')
+        .description('Initialize Vault Guard in this repository (config, CI workflow, agent rules, hook)')
+        .option('--dry-run', 'Print the file manifest and planned actions without writing', false)
+        .option('--revert', 'Remove files recorded in .vault-guard/manifest.json', false)
+        .option('--json', 'Machine-readable output', false)
+        .option('-m, --manager <manager>', 'Hook integration when installing pre-commit: native | husky | lefthook | precommit', 'native')
+        .option('--skip-hook', 'Do not install a pre-commit hook', false)
+        .option('--skip-workflow', 'Do not create .github/workflows/vault-guard.yml', false)
+        .option('--skip-config', 'Do not create .vault-guard.json', false)
+        .option('--skip-agent-rules', 'Do not create .vault-guard/mcp-snippet.json or agent-rules.md', false)
+        .action(async (options) => {
+        const m = (options.manager ?? 'native').toLowerCase();
+        if (!['native', 'husky', 'lefthook', 'precommit'].includes(m)) {
+            console.error(`Unknown manager: ${options.manager}`);
+            process.exitCode = 1;
+            return;
         }
+        const exitCode = await (0, init_1.initCommand)({
+            dryRun: Boolean(options.dryRun),
+            revert: Boolean(options.revert),
+            json: Boolean(options.json),
+            manager: m,
+            skipHook: Boolean(options.skipHook),
+            skipWorkflow: Boolean(options.skipWorkflow),
+            skipConfig: Boolean(options.skipConfig),
+            skipAgentRules: Boolean(options.skipAgentRules),
+        });
+        setExitCode(exitCode);
     });
     // Install-hook command
     program
@@ -90,7 +123,8 @@ function buildCli() {
         const m = (options.manager ?? 'native').toLowerCase();
         if (!['native', 'husky', 'lefthook', 'precommit'].includes(m)) {
             console.error(`Unknown manager: ${options.manager}`);
-            process.exit(1);
+            process.exitCode = 1;
+            return;
         }
         await (0, install_hook_1.installHookCommand)(m);
     });
@@ -108,9 +142,7 @@ function buildCli() {
         .argument('[files...]', 'Files to check')
         .action(async (files) => {
         const exitCode = await (0, fix_1.fixCommand)(files);
-        if (exitCode !== 0) {
-            process.exit(exitCode);
-        }
+        setExitCode(exitCode);
     });
     // Check command
     program
@@ -119,9 +151,7 @@ function buildCli() {
         .argument('[files...]', 'Files to check')
         .action(async (files) => {
         const exitCode = await (0, check_1.checkCommand)(files);
-        if (exitCode !== 0) {
-            process.exit(exitCode);
-        }
+        setExitCode(exitCode);
     });
     program
         .command('statusline')
@@ -162,7 +192,8 @@ function buildCli() {
                 const n = Number(options.maxRpm);
                 if (!Number.isFinite(n) || n < 1) {
                     console.error('--max-rpm must be a positive number');
-                    process.exit(1);
+                    process.exitCode = 1;
+                    return;
                 }
                 maxRpm = Math.floor(n);
             }
@@ -192,7 +223,7 @@ function buildCli() {
         }
         catch (e) {
             console.error(String(e));
-            process.exit(1);
+            process.exitCode = 1;
         }
     });
     // `data` parent command — inspects, exports, and resets the local
@@ -207,8 +238,7 @@ function buildCli() {
         .option('--json', 'Print JSON', false)
         .action(async (options) => {
         const exitCode = await (0, data_1.dataStatusCommand)({ json: Boolean(options.json) });
-        if (exitCode !== 0)
-            process.exit(exitCode);
+        setExitCode(exitCode);
     });
     dataCmd
         .command('reset')
@@ -222,8 +252,7 @@ function buildCli() {
             dryRun: Boolean(options.dryRun),
             json: Boolean(options.json),
         });
-        if (exitCode !== 0)
-            process.exit(exitCode);
+        setExitCode(exitCode);
     });
     dataCmd
         .command('export')
@@ -233,8 +262,7 @@ function buildCli() {
         .action(async (options) => {
         const fmt = options.format === 'jsonl' ? 'jsonl' : 'json';
         const exitCode = await (0, data_1.dataExportCommand)({ output: options.output, format: fmt });
-        if (exitCode !== 0)
-            process.exit(exitCode);
+        setExitCode(exitCode);
     });
     return program;
 }

package/dist/commands/index.d.ts

@@ -1,6 +1,7 @@
 export { scanCommand } from './scan';
 export { configValidateCommand } from './config';
 export { installHookCommand } from './install-hook';
+export { initCommand, type InitOptions } from './init';
 export { tokensCommand } from './tokens';
 export { fixCommand } from './fix';
 export { checkCommand } from './check';

package/dist/commands/index.js

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.dataExportCommand = exports.dataResetCommand = exports.dataStatusCommand = exports.proxyCommand = exports.suggestModelCommand = exports.statuslineCommand = exports.checkCommand = exports.fixCommand = exports.tokensCommand = exports.installHookCommand = exports.configValidateCommand = exports.scanCommand = void 0;
+exports.dataExportCommand = exports.dataResetCommand = exports.dataStatusCommand = exports.proxyCommand = exports.suggestModelCommand = exports.statuslineCommand = exports.checkCommand = exports.fixCommand = exports.tokensCommand = exports.initCommand = exports.installHookCommand = exports.configValidateCommand = exports.scanCommand = void 0;
 var scan_1 = require("./scan");
 Object.defineProperty(exports, "scanCommand", { enumerable: true, get: function () { return scan_1.scanCommand; } });
 var config_1 = require("./config");
 Object.defineProperty(exports, "configValidateCommand", { enumerable: true, get: function () { return config_1.configValidateCommand; } });
 var install_hook_1 = require("./install-hook");
 Object.defineProperty(exports, "installHookCommand", { enumerable: true, get: function () { return install_hook_1.installHookCommand; } });
+var init_1 = require("./init");
+Object.defineProperty(exports, "initCommand", { enumerable: true, get: function () { return init_1.initCommand; } });
 var tokens_1 = require("./tokens");
 Object.defineProperty(exports, "tokensCommand", { enumerable: true, get: function () { return tokens_1.tokensCommand; } });
 var fix_1 = require("./fix");

package/dist/commands/init.d.ts

@@ -0,0 +1,40 @@
+import { type HookManager } from '@vaultcompass/vault-guard-core';
+export interface InitOptions {
+    cwd?: string;
+    dryRun?: boolean;
+    revert?: boolean;
+    json?: boolean;
+    manager?: HookManager;
+    skipHook?: boolean;
+    skipWorkflow?: boolean;
+    skipConfig?: boolean;
+    skipAgentRules?: boolean;
+}
+export interface InitConflict {
+    path: string;
+    reason: 'exists' | 'foreign_manifest' | 'manifest_mismatch' | 'not_a_git_repository' | 'foreign_hook';
+}
+export interface InitPlannedAction {
+    kind: 'create' | 'hook-install' | 'skip';
+    path: string;
+    detail?: string;
+}
+export interface InitResult {
+    ok: boolean;
+    dryRun: boolean;
+    reverted: boolean;
+    alreadyInitialized: boolean;
+    actions: InitPlannedAction[];
+    conflicts: InitConflict[];
+    hook?: {
+        manager: string;
+        path?: string;
+        installed: boolean;
+    };
+    manifestPath: string;
+    mcpMergeHint: string;
+}
+export declare function planInit(options?: InitOptions): InitResult;
+export declare function applyInit(plan: InitResult, options?: InitOptions): InitResult;
+export declare function revertInit(options?: InitOptions): InitResult;
+export declare function initCommand(options?: InitOptions): Promise<number>;

package/dist/commands/init.js

@@ -0,0 +1,488 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planInit = planInit;
+exports.applyInit = applyInit;
+exports.revertInit = revertInit;
+exports.initCommand = initCommand;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const vault_guard_core_1 = require("@vaultcompass/vault-guard-core");
+const chalk_1 = __importDefault(require("chalk"));
+const templates_1 = require("../init/templates");
+const MCP_MERGE_HINT = 'Merge .vault-guard/mcp-snippet.json into your editor MCP config (~/.cursor/mcp.json or Claude Desktop).';
+function isGitRepo(cwd) {
+    return fs.existsSync(path.join(cwd, '.git'));
+}
+function readFileIfExists(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseManifest(content) {
+    try {
+        const parsed = JSON.parse(content);
+        if (parsed.initVersion !== '1' || !Array.isArray(parsed.files)) {
+            return undefined;
+        }
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function managedContentPaths(options) {
+    const skip = new Set();
+    if (options.skipConfig)
+        skip.add('.vault-guard.json');
+    if (options.skipWorkflow)
+        skip.add('.github/workflows/vault-guard.yml');
+    if (options.skipAgentRules) {
+        skip.add('.vault-guard/mcp-snippet.json');
+        skip.add('.vault-guard/agent-rules.md');
+    }
+    return templates_1.MANAGED_FILE_PATHS.filter((p) => p !== templates_1.MANIFEST_RELATIVE_PATH && !skip.has(p));
+}
+function hookRelativePath(cwd, hookPath) {
+    return path.relative(cwd, hookPath).split(path.sep).join('/');
+}
+function foreignHookConflict(cwd, manager) {
+    const hook = new vault_guard_core_1.PreCommitHook();
+    const hookPath = hook.getPreCommitHookPath(cwd, manager);
+    if (!fs.existsSync(hookPath))
+        return undefined;
+    if (hook.isInstalled({ cwd, manager }))
+        return undefined;
+    const rel = hookRelativePath(cwd, hookPath);
+    if (manager === 'husky') {
+        const content = readFileIfExists(hookPath) ?? '';
+        if (content.includes('vault-guard'))
+            return undefined;
+        return { path: rel, reason: 'foreign_hook' };
+    }
+    if (manager === 'lefthook') {
+        const localPath = path.join(cwd, 'lefthook-local.yml');
+        if (!fs.existsSync(localPath))
+            return undefined;
+        const content = readFileIfExists(localPath) ?? '';
+        if (content.includes('vault-guard scan --staged'))
+            return undefined;
+        return { path: 'lefthook-local.yml', reason: 'foreign_hook' };
+    }
+    if (manager === 'precommit') {
+        const configPath = path.join(cwd, '.pre-commit-config.yaml');
+        if (!fs.existsSync(configPath))
+            return undefined;
+        const content = readFileIfExists(configPath) ?? '';
+        if (content.includes('vault-guard scan --staged'))
+            return undefined;
+        return { path: '.pre-commit-config.yaml', reason: 'foreign_hook' };
+    }
+    const content = readFileIfExists(hookPath) ?? '';
+    if (content.trim().length === 0)
+        return undefined;
+    return { path: rel, reason: 'foreign_hook' };
+}
+function ensureParentDir(filePath) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+function planInit(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const dryRun = Boolean(options.dryRun);
+    const manager = options.manager ?? 'native';
+    const actions = [];
+    const conflicts = [];
+    const trackedFiles = [];
+    const manifestAbs = path.join(cwd, templates_1.MANIFEST_RELATIVE_PATH);
+    const manifestRaw = readFileIfExists(manifestAbs);
+    const manifestParsed = manifestRaw ? parseManifest(manifestRaw) : undefined;
+    if (manifestRaw && !manifestParsed) {
+        conflicts.push({ path: templates_1.MANIFEST_RELATIVE_PATH, reason: 'foreign_manifest' });
+    }
+    for (const rel of managedContentPaths(options)) {
+        const abs = path.join(cwd, rel);
+        const expected = (0, templates_1.templateContentForPath)(rel);
+        const current = readFileIfExists(abs);
+        if (current === undefined) {
+            actions.push({ kind: 'create', path: rel });
+            trackedFiles.push({ path: rel, action: 'created' });
+            continue;
+        }
+        if (current === expected) {
+            actions.push({ kind: 'skip', path: rel, detail: 'content matches template' });
+            trackedFiles.push({ path: rel, action: 'created' });
+            continue;
+        }
+        conflicts.push({ path: rel, reason: 'exists' });
+    }
+    let hookState;
+    if (!options.skipHook) {
+        if (!isGitRepo(cwd)) {
+            conflicts.push({ path: '.git', reason: 'not_a_git_repository' });
+        }
+        else {
+            const foreignHook = foreignHookConflict(cwd, manager);
+            if (foreignHook) {
+                conflicts.push(foreignHook);
+            }
+            else {
+                const hook = new vault_guard_core_1.PreCommitHook();
+                const hookPath = hook.getPreCommitHookPath(cwd, manager);
+                if (hook.isInstalled({ cwd, manager })) {
+                    hookState = { manager, path: hookPath, installed: true };
+                    actions.push({ kind: 'skip', path: hookPath, detail: 'hook already installed' });
+                }
+                else {
+                    hookState = { manager, path: hookPath, installed: false };
+                    actions.push({ kind: 'hook-install', path: hookPath, detail: manager });
+                }
+            }
+        }
+    }
+    const hookMeta = hookState?.path && !options.skipHook
+        ? { manager, path: hookRelativePath(cwd, hookState.path) }
+        : undefined;
+    function manifestMatchesState(manifest) {
+        if (manifest.templateVersion !== templates_1.INIT_TEMPLATE_VERSION)
+            return false;
+        const expectedPaths = trackedFiles
+            .map(f => f.path)
+            .sort()
+            .join('\0');
+        const actualPaths = manifest.files
+            .map(f => f.path)
+            .sort()
+            .join('\0');
+        if (expectedPaths !== actualPaths)
+            return false;
+        if (hookMeta) {
+            return manifest.hookManager === hookMeta.manager && manifest.hookPath === hookMeta.path;
+        }
+        return manifest.hookManager === undefined && manifest.hookPath === undefined;
+    }
+    if (manifestRaw === undefined && conflicts.length === 0) {
+        actions.push({ kind: 'create', path: templates_1.MANIFEST_RELATIVE_PATH });
+    }
+    else if (manifestParsed) {
+        if (manifestMatchesState(manifestParsed)) {
+            actions.push({ kind: 'skip', path: templates_1.MANIFEST_RELATIVE_PATH, detail: 'manifest current' });
+        }
+        else if (conflicts.length === 0) {
+            conflicts.push({ path: templates_1.MANIFEST_RELATIVE_PATH, reason: 'manifest_mismatch' });
+        }
+    }
+    const alreadyInitialized = conflicts.length === 0 &&
+        actions.length > 0 &&
+        actions.every(a => a.kind === 'skip');
+    return {
+        ok: conflicts.length === 0,
+        dryRun,
+        reverted: false,
+        alreadyInitialized,
+        actions,
+        conflicts,
+        hook: hookState,
+        manifestPath: templates_1.MANIFEST_RELATIVE_PATH,
+        mcpMergeHint: MCP_MERGE_HINT,
+    };
+}
+function applyInit(plan, options = {}) {
+    if (!plan.ok || plan.dryRun || plan.alreadyInitialized) {
+        return plan;
+    }
+    const cwd = options.cwd ?? process.cwd();
+    const manager = options.manager ?? 'native';
+    const trackedFiles = [];
+    const createdPaths = [];
+    const rollbackCreatedFiles = () => {
+        for (const rel of createdPaths.reverse()) {
+            const abs = path.join(cwd, rel);
+            try {
+                if (fs.existsSync(abs))
+                    fs.unlinkSync(abs);
+            }
+            catch {
+                /* best effort */
+            }
+        }
+    };
+    if (plan.hook && !plan.hook.installed && !options.skipHook) {
+        const hook = new vault_guard_core_1.PreCommitHook();
+        const result = hook.install({ cwd, manager });
+        if (!result.success) {
+            return {
+                ...plan,
+                ok: false,
+                actions: [
+                    ...plan.actions,
+                    {
+                        kind: 'skip',
+                        path: plan.hook.path ?? 'pre-commit',
+                        detail: `hook install failed: ${result.message}`,
+                    },
+                ],
+            };
+        }
+        plan.hook = {
+            manager,
+            path: result.hookPath ?? plan.hook.path,
+            installed: true,
+        };
+    }
+    try {
+        for (const action of plan.actions) {
+            if (action.kind !== 'create' || action.path === templates_1.MANIFEST_RELATIVE_PATH)
+                continue;
+            const abs = path.join(cwd, action.path);
+            ensureParentDir(abs);
+            fs.writeFileSync(abs, (0, templates_1.templateContentForPath)(action.path), {
+                encoding: 'utf8',
+                flag: 'wx',
+            });
+            trackedFiles.push({ path: action.path, action: 'created' });
+            createdPaths.push(action.path);
+        }
+    }
+    catch (error) {
+        rollbackCreatedFiles();
+        if (plan.hook?.installed && !options.skipHook) {
+            new vault_guard_core_1.PreCommitHook().uninstall({ cwd, manager });
+        }
+        return {
+            ...plan,
+            ok: false,
+            actions: [
+                ...plan.actions,
+                {
+                    kind: 'skip',
+                    path: 'init',
+                    detail: `file write failed: ${String(error)}`,
+                },
+            ],
+        };
+    }
+    const hookMeta = plan.hook?.path && !options.skipHook
+        ? { manager, path: hookRelativePath(cwd, plan.hook.path) }
+        : undefined;
+    const allTracked = trackedFiles.length > 0
+        ? trackedFiles
+        : managedContentPaths(options).map(p => ({ path: p, action: 'created' }));
+    const manifestContent = (0, templates_1.buildManifestContent)(allTracked, hookMeta);
+    const manifestAbs = path.join(cwd, templates_1.MANIFEST_RELATIVE_PATH);
+    try {
+        if (!fs.existsSync(manifestAbs)) {
+            ensureParentDir(manifestAbs);
+            fs.writeFileSync(manifestAbs, manifestContent, { encoding: 'utf8', flag: 'wx' });
+        }
+    }
+    catch (error) {
+        rollbackCreatedFiles();
+        if (plan.hook?.installed && !options.skipHook) {
+            new vault_guard_core_1.PreCommitHook().uninstall({ cwd, manager });
+        }
+        return {
+            ...plan,
+            ok: false,
+            actions: [
+                ...plan.actions,
+                {
+                    kind: 'skip',
+                    path: templates_1.MANIFEST_RELATIVE_PATH,
+                    detail: `manifest write failed: ${String(error)}`,
+                },
+            ],
+        };
+    }
+    return { ...plan, ok: true };
+}
+function revertInit(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const dryRun = Boolean(options.dryRun);
+    const manifestAbs = path.join(cwd, templates_1.MANIFEST_RELATIVE_PATH);
+    const raw = readFileIfExists(manifestAbs);
+    if (!raw) {
+        return {
+            ok: false,
+            dryRun,
+            reverted: false,
+            alreadyInitialized: false,
+            actions: [],
+            conflicts: [{ path: templates_1.MANIFEST_RELATIVE_PATH, reason: 'foreign_manifest' }],
+            manifestPath: templates_1.MANIFEST_RELATIVE_PATH,
+            mcpMergeHint: MCP_MERGE_HINT,
+        };
+    }
+    const manifest = parseManifest(raw);
+    if (!manifest) {
+        return {
+            ok: false,
+            dryRun,
+            reverted: false,
+            alreadyInitialized: false,
+            actions: [],
+            conflicts: [{ path: templates_1.MANIFEST_RELATIVE_PATH, reason: 'foreign_manifest' }],
+            manifestPath: templates_1.MANIFEST_RELATIVE_PATH,
+            mcpMergeHint: MCP_MERGE_HINT,
+        };
+    }
+    const actions = [];
+    const filePaths = [...manifest.files.map(f => f.path)].reverse();
+    for (const rel of filePaths) {
+        actions.push({
+            kind: 'skip',
+            path: rel,
+            detail: dryRun ? 'would remove file' : 'removed file',
+        });
+        if (!dryRun) {
+            const abs = path.join(cwd, rel);
+            if (fs.existsSync(abs))
+                fs.unlinkSync(abs);
+        }
+    }
+    if (manifest.hookManager) {
+        actions.push({
+            kind: 'hook-install',
+            path: manifest.hookPath ?? 'pre-commit',
+            detail: dryRun ? 'would uninstall hook' : 'uninstalled hook',
+        });
+        if (!dryRun) {
+            new vault_guard_core_1.PreCommitHook().uninstall({
+                cwd,
+                manager: manifest.hookManager,
+            });
+        }
+    }
+    actions.push({
+        kind: 'skip',
+        path: templates_1.MANIFEST_RELATIVE_PATH,
+        detail: dryRun ? 'would remove manifest' : 'removed manifest',
+    });
+    if (!dryRun && fs.existsSync(manifestAbs)) {
+        fs.unlinkSync(manifestAbs);
+        const vgDir = path.join(cwd, '.vault-guard');
+        try {
+            if (fs.existsSync(vgDir) && fs.readdirSync(vgDir).length === 0) {
+                fs.rmdirSync(vgDir);
+            }
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    return {
+        ok: true,
+        dryRun,
+        reverted: !dryRun,
+        alreadyInitialized: false,
+        actions,
+        conflicts: [],
+        manifestPath: templates_1.MANIFEST_RELATIVE_PATH,
+        mcpMergeHint: MCP_MERGE_HINT,
+    };
+}
+function printHuman(result, options) {
+    if (options.revert) {
+        if (!result.ok) {
+            console.error(chalk_1.default.red('❌ Revert failed:'), 'no valid init manifest found');
+            return;
+        }
+        console.log(result.dryRun
+            ? chalk_1.default.blue('🔍 Dry-run revert plan')
+            : chalk_1.default.green.bold('✅ Reverted Vault Guard init artifacts'));
+        for (const a of result.actions) {
+            console.log(chalk_1.default.gray(`   ${a.detail ?? a.path}`));
+        }
+        return;
+    }
+    if (result.conflicts.length > 0) {
+        console.error(chalk_1.default.red.bold('❌ Init blocked — conflicts (no automatic overwrites):'));
+        for (const c of result.conflicts) {
+            console.error(chalk_1.default.white(`   ${c.path}`), chalk_1.default.gray(`(${c.reason})`));
+        }
+        console.error(chalk_1.default.gray('\nResolve manually, then re-run vault-guard init.'));
+        return;
+    }
+    if (result.alreadyInitialized) {
+        console.log(chalk_1.default.green('✅ Already initialized — no changes needed'));
+        return;
+    }
+    if (result.dryRun) {
+        console.log(chalk_1.default.blue('🔍 Dry-run — would apply:'));
+    }
+    else {
+        console.log(chalk_1.default.green.bold('✅ Vault Guard initialized'));
+    }
+    for (const a of result.actions) {
+        if (a.kind === 'create') {
+            console.log(chalk_1.default.white(`   ${result.dryRun ? 'create' : 'created'} ${a.path}`));
+        }
+        else if (a.kind === 'hook-install') {
+            console.log(chalk_1.default.white(`   ${result.dryRun ? 'install' : 'installed'} hook (${a.detail})`));
+        }
+    }
+    console.log(chalk_1.default.gray(`\n${result.mcpMergeHint}`));
+    console.log(chalk_1.default.gray(`Manifest: ${result.manifestPath}`));
+}
+async function initCommand(options = {}) {
+    if (options.revert) {
+        const result = revertInit(options);
+        if (options.json) {
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        }
+        else {
+            printHuman(result, options);
+        }
+        return result.ok ? 0 : 1;
+    }
+    const plan = planInit(options);
+    const result = plan.dryRun || plan.alreadyInitialized ? plan : applyInit(plan, options);
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    }
+    else {
+        printHuman(result, options);
+    }
+    if (result.conflicts.length > 0)
+        return 2;
+    if (!result.ok)
+        return 1;
+    return 0;
+}

package/dist/init/templates.d.ts

@@ -0,0 +1,28 @@
+/** Stable init template version — bump when file contents change materially. */
+export declare const INIT_TEMPLATE_VERSION = "1";
+export declare const MANIFEST_RELATIVE_PATH = ".vault-guard/manifest.json";
+export declare const MANAGED_FILE_PATHS: readonly [".vault-guard.json", ".github/workflows/vault-guard.yml", ".vault-guard/mcp-snippet.json", ".vault-guard/agent-rules.md", ".vault-guard/manifest.json"];
+export type ManagedFilePath = (typeof MANAGED_FILE_PATHS)[number];
+export declare function defaultVaultGuardConfigJson(): string;
+export declare function githubWorkflowYaml(): string;
+export declare function mcpSnippetJson(): string;
+export declare function agentRulesMarkdown(): string;
+export declare function templateContentForPath(relativePath: ManagedFilePath): string;
+export interface InitManifest {
+    initVersion: string;
+    templateVersion: string;
+    createdAt: string;
+    hookManager?: string;
+    hookPath?: string;
+    files: Array<{
+        path: string;
+        action: 'created';
+    }>;
+}
+export declare function buildManifestContent(files: Array<{
+    path: string;
+    action: 'created';
+}>, hook?: {
+    manager: string;
+    path: string;
+}): string;

package/dist/init/templates.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MANAGED_FILE_PATHS = exports.MANIFEST_RELATIVE_PATH = exports.INIT_TEMPLATE_VERSION = void 0;
+exports.defaultVaultGuardConfigJson = defaultVaultGuardConfigJson;
+exports.githubWorkflowYaml = githubWorkflowYaml;
+exports.mcpSnippetJson = mcpSnippetJson;
+exports.agentRulesMarkdown = agentRulesMarkdown;
+exports.templateContentForPath = templateContentForPath;
+exports.buildManifestContent = buildManifestContent;
+/** Stable init template version — bump when file contents change materially. */
+exports.INIT_TEMPLATE_VERSION = '1';
+exports.MANIFEST_RELATIVE_PATH = '.vault-guard/manifest.json';
+exports.MANAGED_FILE_PATHS = [
+    '.vault-guard.json',
+    '.github/workflows/vault-guard.yml',
+    '.vault-guard/mcp-snippet.json',
+    '.vault-guard/agent-rules.md',
+    exports.MANIFEST_RELATIVE_PATH,
+];
+function defaultVaultGuardConfigJson() {
+    return `${JSON.stringify({
+        ignore: {
+            patterns: ['**/__tests__/**', 'fixtures/**', 'bench/fixtures/**'],
+        },
+    }, null, 2)}\n`;
+}
+function githubWorkflowYaml() {
+    return `name: Vault Guard
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  secrets:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: vaultcompasshq/vault-guard@v1.1.2
+        with:
+          version: latest
+          path: .
+          format: sarif
+          sarif-output: vault-guard-results.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: vault-guard-results.sarif
+`;
+}
+function mcpSnippetJson() {
+    return `${JSON.stringify({
+        mcpServers: {
+            'vault-guard': {
+                command: 'npx',
+                args: ['-y', '@vaultcompass/vault-guard-mcp'],
+            },
+        },
+    }, null, 2)}\n`;
+}
+function agentRulesMarkdown() {
+    return `# Vault Guard — agent guardrails
+
+Vault Guard is the local secret scanner for this repository. Follow these rules
+before writing, editing, or committing code.
+
+## Before applying edits
+
+1. Call the Vault Guard MCP tool \`scan_text\` on any proposed file content that
+   may contain credentials (API keys, tokens, connection strings, private keys).
+2. If findings are returned, do **not** write the secret material. Redact or
+   replace with environment variables / placeholders and scan again.
+3. For whole files on disk, use \`scan_file\`. For directories, use
+   \`scan_workspace\`.
+
+## Before committing
+
+- Ensure \`vault-guard scan --staged\` passes (pre-commit hook enforces this).
+- Never use \`git commit --no-verify\` to bypass secret checks unless the user
+  explicitly requests an emergency bypass.
+
+## Merge MCP config (manual)
+
+Copy the \`mcpServers\` block from \`.vault-guard/mcp-snippet.json\` into your
+editor MCP config (e.g. \`~/.cursor/mcp.json\` or Claude Desktop config). Vault
+Guard does not modify files outside this repository.
+
+## History scanning
+
+Vault Guard does not scan Git history. Use Gitleaks or TruffleHog for retroactive
+history mining alongside Vault Guard's working-tree protection.
+`;
+}
+function templateContentForPath(relativePath) {
+    switch (relativePath) {
+        case '.vault-guard.json':
+            return defaultVaultGuardConfigJson();
+        case '.github/workflows/vault-guard.yml':
+            return githubWorkflowYaml();
+        case '.vault-guard/mcp-snippet.json':
+            return mcpSnippetJson();
+        case '.vault-guard/agent-rules.md':
+            return agentRulesMarkdown();
+        default:
+            throw new Error(`No template for ${relativePath}`);
+    }
+}
+function buildManifestContent(files, hook) {
+    const manifest = {
+        initVersion: '1',
+        templateVersion: exports.INIT_TEMPLATE_VERSION,
+        createdAt: new Date().toISOString(),
+        files,
+        ...(hook ? { hookManager: hook.manager, hookPath: hook.path } : {}),
+    };
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaultcompass/vault-guard",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Block secrets at commit and in CI. Pre-commit hooks, SARIF output, and fast staged-file scans for AI-native workflows.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -36,8 +36,8 @@
   "dependencies": {
     "chalk": "^4.1.2",
     "commander": "^12.0.0",
-    "@vaultcompass/vault-guard-core": "1.1.1",
-    "@vaultcompass/vault-guard-telemetry": "1.1.1"
+    "@vaultcompass/vault-guard-core": "1.2.0",
+    "@vaultcompass/vault-guard-telemetry": "1.2.0"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",