@vaultcompass/vault-guard 1.2.2 → 1.3.0

package/dist/commands/init.d.ts

@@ -14,6 +14,12 @@ export interface InitConflict {
     path: string;
     reason: 'exists' | 'foreign_manifest' | 'manifest_mismatch' | 'not_a_git_repository' | 'foreign_hook';
 }
+export interface InitAdvisory {
+    /** Detected manager that may already own pre-commit. */
+    manager: 'husky' | 'lefthook' | 'precommit';
+    path: string;
+    guidance: string;
+}
 export interface InitPlannedAction {
     kind: 'create' | 'hook-install' | 'skip';
     path: string;
@@ -26,6 +32,8 @@ export interface InitResult {
     alreadyInitialized: boolean;
     actions: InitPlannedAction[];
     conflicts: InitConflict[];
+    /** Non-blocking tips when other hook managers are present. */
+    advisories: InitAdvisory[];
     hook?: {
         manager: string;
         path?: string;

package/dist/commands/init.js

@@ -86,18 +86,8 @@ function hookRelativePath(cwd, hookPath) {
 }
 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' };
-    }
+    // Manager-specific paths first — lefthook/precommit do not use getPreCommitHookPath
+    // (that helper still resolves the native hooks dir for non-husky managers).
     if (manager === 'lefthook') {
         const localPath = path.join(cwd, 'lefthook-local.yml');
         if (!fs.existsSync(localPath))
@@ -116,10 +106,88 @@ function foreignHookConflict(cwd, manager) {
             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' };
+    if (manager === 'husky') {
+        const hookPath = hook.getPreCommitHookPath(cwd, 'husky');
+        if (!fs.existsSync(hookPath))
+            return undefined;
+        if (hook.isInstalled({ cwd, manager: 'husky' }))
+            return undefined;
+        const content = readFileIfExists(hookPath) ?? '';
+        if (content.includes('vault-guard'))
+            return undefined;
+        return { path: hookRelativePath(cwd, hookPath), reason: 'foreign_hook' };
+    }
+    // native: POSIX hook and optional Windows companion
+    const hookPath = hook.getPreCommitHookPath(cwd, 'native');
+    if (fs.existsSync(hookPath) && !hook.isInstalled({ cwd, manager: 'native' })) {
+        const content = readFileIfExists(hookPath) ?? '';
+        if (content.trim().length > 0) {
+            return { path: hookRelativePath(cwd, hookPath), reason: 'foreign_hook' };
+        }
+    }
+    const cmdPath = hook.getPreCommitCmdPath(cwd);
+    if (fs.existsSync(cmdPath)) {
+        const content = readFileIfExists(cmdPath) ?? '';
+        const isOurs = content.includes('vault-guard') && content.includes('scan --staged');
+        if (content.trim().length > 0 && !isOurs) {
+            return { path: hookRelativePath(cwd, cmdPath), reason: 'foreign_hook' };
+        }
+    }
+    return undefined;
+}
+function detectOtherHookManagers(cwd, selected) {
+    const advisories = [];
+    const huskyDir = path.join(cwd, '.husky');
+    if (fs.existsSync(huskyDir) && selected !== 'husky') {
+        advisories.push({
+            manager: 'husky',
+            path: '.husky/',
+            guidance: 'Husky detected. Prefer `vault-guard init --manager husky` or `vault-guard install-hook --manager husky` so the scan runs from .husky/pre-commit. Native hooks may not run when husky owns core.hooksPath.',
+        });
+    }
+    const lefthookYml = path.join(cwd, 'lefthook.yml');
+    const lefthookLocal = path.join(cwd, 'lefthook-local.yml');
+    if ((fs.existsSync(lefthookYml) || fs.existsSync(lefthookLocal)) && selected !== 'lefthook') {
+        advisories.push({
+            manager: 'lefthook',
+            path: fs.existsSync(lefthookLocal) ? 'lefthook-local.yml' : 'lefthook.yml',
+            guidance: 'Lefthook detected. Prefer `vault-guard init --manager lefthook` (writes lefthook-local.yml) or merge `vault-guard scan --staged` under pre-commit.commands manually. Init never overwrites existing lefthook files.',
+        });
+    }
+    const precommitCfg = path.join(cwd, '.pre-commit-config.yaml');
+    if (fs.existsSync(precommitCfg) && selected !== 'precommit') {
+        advisories.push({
+            manager: 'precommit',
+            path: '.pre-commit-config.yaml',
+            guidance: 'pre-commit framework config detected. Prefer `vault-guard init --manager precommit` only if the file is absent, or merge the local vault-guard hook into repos: yourself. Init never overwrites an existing .pre-commit-config.yaml.',
+        });
+    }
+    return advisories;
+}
+function conflictGuidance(c) {
+    switch (c.reason) {
+        case 'exists':
+            return 'File already exists with different content — edit manually or move it aside, then re-run init.';
+        case 'foreign_manifest':
+            return 'Existing .vault-guard/init-manifest.json is invalid or foreign — fix or remove it, then re-run.';
+        case 'manifest_mismatch':
+            return 'Init manifest does not match current templates/options — run `vault-guard init --revert` then init again, or update files by hand.';
+        case 'not_a_git_repository':
+            return 'Run `git init` first, or pass `--skip-hook` to scaffold config/workflow without a hook.';
+        case 'foreign_hook':
+            if (c.path.includes('husky') || c.path.startsWith('.husky')) {
+                return 'Existing Husky pre-commit has no vault-guard stanza. Append `vault-guard scan --staged` yourself, or use `install-hook --manager husky` after reviewing the file.';
+            }
+            if (c.path.includes('lefthook')) {
+                return 'Add under pre-commit.commands:\n  vault-guard:\n    run: vault-guard scan --staged';
+            }
+            if (c.path.includes('pre-commit-config')) {
+                return 'Merge a local vault-guard hook into repos: (see `vault-guard install-hook --manager precommit` error output for a snippet).';
+            }
+            return 'An existing pre-commit hook is present without vault-guard. Merge `vault-guard scan --staged` manually, or remove the foreign hook if unused.';
+        default:
+            return 'Resolve manually, then re-run vault-guard init.';
+    }
 }
 function ensureParentDir(filePath) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
@@ -130,6 +198,7 @@ function planInit(options = {}) {
     const manager = options.manager ?? 'native';
     const actions = [];
     const conflicts = [];
+    const advisories = detectOtherHookManagers(cwd, manager);
     const trackedFiles = [];
     const manifestAbs = path.join(cwd, templates_1.MANIFEST_RELATIVE_PATH);
     const manifestRaw = readFileIfExists(manifestAbs);
@@ -219,17 +288,30 @@ function planInit(options = {}) {
         alreadyInitialized,
         actions,
         conflicts,
+        advisories,
         hook: hookState,
         manifestPath: templates_1.MANIFEST_RELATIVE_PATH,
         mcpMergeHint: MCP_MERGE_HINT,
     };
 }
 function applyInit(plan, options = {}) {
-    if (!plan.ok || plan.dryRun || plan.alreadyInitialized) {
+    if (!plan.ok || plan.dryRun) {
         return plan;
     }
     const cwd = options.cwd ?? process.cwd();
     const manager = options.manager ?? 'native';
+    // Idempotent native refresh: backfill/update optional pre-commit.cmd even when
+    // the repo is already fully initialized.
+    if (plan.alreadyInitialized &&
+        plan.hook &&
+        !options.skipHook &&
+        manager === 'native') {
+        new vault_guard_core_1.PreCommitHook().install({ cwd, manager: 'native' });
+        return plan;
+    }
+    if (plan.alreadyInitialized) {
+        return plan;
+    }
     const trackedFiles = [];
     const createdPaths = [];
     const rollbackCreatedFiles = () => {
@@ -244,28 +326,34 @@ function applyInit(plan, options = {}) {
             }
         }
     };
-    if (plan.hook && !plan.hook.installed && !options.skipHook) {
+    if (plan.hook && !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}`,
-                    },
-                ],
-            };
+        // Always call install for native when planning a hook: first-time write, or
+        // idempotent refresh of the optional pre-commit.cmd companion.
+        if (!plan.hook.installed || manager === 'native') {
+            const result = hook.install({ cwd, manager });
+            if (!result.success && !plan.hook.installed) {
+                return {
+                    ...plan,
+                    ok: false,
+                    actions: [
+                        ...plan.actions,
+                        {
+                            kind: 'skip',
+                            path: plan.hook.path ?? 'pre-commit',
+                            detail: `hook install failed: ${result.message}`,
+                        },
+                    ],
+                };
+            }
+            if (result.success) {
+                plan.hook = {
+                    manager,
+                    path: result.hookPath ?? plan.hook.path,
+                    installed: true,
+                };
+            }
         }
-        plan.hook = {
-            manager,
-            path: result.hookPath ?? plan.hook.path,
-            installed: true,
-        };
     }
     try {
         for (const action of plan.actions) {
@@ -345,6 +433,7 @@ function revertInit(options = {}) {
             reverted: false,
             alreadyInitialized: false,
             actions: [],
+            advisories: [],
             conflicts: [{ path: templates_1.MANIFEST_RELATIVE_PATH, reason: 'foreign_manifest' }],
             manifestPath: templates_1.MANIFEST_RELATIVE_PATH,
             mcpMergeHint: MCP_MERGE_HINT,
@@ -358,6 +447,7 @@ function revertInit(options = {}) {
             reverted: false,
             alreadyInitialized: false,
             actions: [],
+            advisories: [],
             conflicts: [{ path: templates_1.MANIFEST_RELATIVE_PATH, reason: 'foreign_manifest' }],
             manifestPath: templates_1.MANIFEST_RELATIVE_PATH,
             mcpMergeHint: MCP_MERGE_HINT,
@@ -413,6 +503,7 @@ function revertInit(options = {}) {
         reverted: !dryRun,
         alreadyInitialized: false,
         actions,
+        advisories: [],
         conflicts: [],
         manifestPath: templates_1.MANIFEST_RELATIVE_PATH,
         mcpMergeHint: MCP_MERGE_HINT,
@@ -436,6 +527,14 @@ function printHuman(result, options) {
         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(`      → ${conflictGuidance(c)}`));
+        }
+        if (result.advisories.length > 0) {
+            console.error(chalk_1.default.yellow('\nAlso noted:'));
+            for (const a of result.advisories) {
+                console.error(chalk_1.default.yellow(`   [${a.manager}] ${a.path}`));
+                console.error(chalk_1.default.gray(`      ${a.guidance}`));
+            }
         }
         console.error(chalk_1.default.gray('\nResolve manually, then re-run vault-guard init.'));
         return;
@@ -458,6 +557,13 @@ function printHuman(result, options) {
             console.log(chalk_1.default.white(`   ${result.dryRun ? 'install' : 'installed'} hook (${a.detail})`));
         }
     }
+    if (result.advisories.length > 0) {
+        console.log(chalk_1.default.yellow('\nHook manager notes:'));
+        for (const a of result.advisories) {
+            console.log(chalk_1.default.yellow(`   [${a.manager}] ${a.path}`));
+            console.log(chalk_1.default.gray(`      ${a.guidance}`));
+        }
+    }
     console.log(chalk_1.default.gray(`\n${result.mcpMergeHint}`));
     console.log(chalk_1.default.gray(`Manifest: ${result.manifestPath}`));
 }
@@ -473,7 +579,7 @@ async function initCommand(options = {}) {
         return result.ok ? 0 : 1;
     }
     const plan = planInit(options);
-    const result = plan.dryRun || plan.alreadyInitialized ? plan : applyInit(plan, options);
+    const result = plan.dryRun ? plan : applyInit(plan, options);
     if (options.json) {
         process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
     }

package/dist/commands/install-hook.js

@@ -16,7 +16,10 @@ async function installHookCommand(manager = 'native') {
         if (result.hookPath) {
             console.log(chalk_1.default.gray(`   Path: ${result.hookPath}`));
         }
-        console.log(chalk_1.default.gray('\nThe hook runs `vault-guard scan --staged` before each commit (staged files only).\n'));
+        console.log(chalk_1.default.gray('\nThe hook runs `vault-guard scan --staged` before each commit (staged files only).\n' +
+            (manager === 'native'
+                ? 'Also writes optional pre-commit.cmd (Git for Windows still runs the POSIX pre-commit via sh).\n'
+                : '')));
     }
     else {
         console.error(chalk_1.default.red('❌ Error:'), chalk_1.default.white(result.message));

package/dist/commands/scan.js

@@ -95,6 +95,8 @@ async function scanCommand(targetPath, format = 'text', staged = false) {
                 bus,
                 stats,
                 configIgnorePatterns,
+                fromGitIndex: true,
+                cwd,
             });
         }
         else {

package/dist/utils/scan-utils.d.ts

@@ -27,10 +27,19 @@ export interface ScanOptions {
      * directory scans and staged-file scans.
      */
     configIgnorePatterns?: string[];
+    /**
+     * When true, read each path from the git index (`git show :path`) so
+     * `--staged` matches what will actually be committed — including `AD`
+     * (added in index, deleted in worktree) and partially staged files.
+     */
+    fromGitIndex?: boolean;
+    /** Repo root for `fromGitIndex` (defaults to `process.cwd()`). */
+    cwd?: string;
 }
 /**
  * Scan an explicit list of files (e.g. paths from \`git diff --cached\`).
- * Skips missing paths and non-files silently.
+ * Without `fromGitIndex`, skips missing worktree paths. With `fromGitIndex`,
+ * reads staged blobs so deleted worktree files are still scanned.
  */
 export declare function scanFileListAsync(files: string[], scanner: SecretScanner, options?: ScanOptions): Promise<ScanResult[]>;
 /**

package/dist/utils/scan-utils.js

@@ -35,15 +35,16 @@ const BINARY_EXTENSIONS = [
 ];
 /**
  * Scan an explicit list of files (e.g. paths from \`git diff --cached\`).
- * Skips missing paths and non-files silently.
+ * Without `fromGitIndex`, skips missing worktree paths. With `fromGitIndex`,
+ * reads staged blobs so deleted worktree files are still scanned.
  */
 async function scanFileListAsync(files, scanner, options = {}) {
-    const { verbose = false, maxSize = MAX_FILE_SIZE, skipBinary = true, progress = false, concurrency = 10, configIgnorePatterns = [], } = options;
+    const { verbose = false, maxSize = MAX_FILE_SIZE, skipBinary = true, progress = false, concurrency = 10, configIgnorePatterns = [], fromGitIndex = false, cwd = process.cwd(), } = options;
     // Apply config ignore patterns to the explicit file list (e.g. staged files).
     // buildConfigIgnoreFilter matches relative to cwd so patterns like
     // `packages/**/__tests__/**` work identically for staged and directory scans.
     const configIgnoreTester = configIgnorePatterns.length > 0
-        ? (0, vault_guard_core_1.buildConfigIgnoreFilter)(configIgnorePatterns, process.cwd())
+        ? (0, vault_guard_core_1.buildConfigIgnoreFilter)(configIgnorePatterns, cwd)
         : null;
     const filteredFiles = configIgnoreTester
         ? files.filter(f => !configIgnoreTester(f))
@@ -51,6 +52,27 @@ async function scanFileListAsync(files, scanner, options = {}) {
     const results = [];
     const scanFile = async (file) => {
         try {
+            if (fromGitIndex) {
+                const rel = path_1.default.relative(cwd, file).split(path_1.default.sep).join('/');
+                if (skipBinary && isBinaryFile(file))
+                    return;
+                const content = (0, vault_guard_core_1.readGitIndexFile)(cwd, rel);
+                if (skipBinary && content.includes('\0'))
+                    return;
+                const byteLen = Buffer.byteLength(content, 'utf-8');
+                if (byteLen > maxSize && verbose) {
+                    console.warn(chalk_1.default.yellow(`⚠️  Large staged blob (scanning in memory):`), chalk_1.default.white(rel), chalk_1.default.gray(`(${(byteLen / 1024 / 1024).toFixed(2)}MB)`));
+                }
+                if (options.stats) {
+                    options.stats.filesScanned += 1;
+                    options.stats.bytesScanned += byteLen;
+                }
+                const matches = (0, vault_guard_core_1.applyPathAwareSeverity)(scanner.scanContent(content, { filePath: file }), file);
+                if (matches.length > 0) {
+                    results.push({ file, matches });
+                }
+                return;
+            }
             if (!fs_1.default.existsSync(file))
                 return;
             const st = await fs_1.default.promises.stat(file);
@@ -59,7 +81,7 @@ async function scanFileListAsync(files, scanner, options = {}) {
             if (skipBinary && isBinaryFile(file))
                 return;
             if (st.size > maxSize && verbose) {
-                console.warn(chalk_1.default.yellow(`⚠️  Large file (streaming line-by-line):`), chalk_1.default.white(path_1.default.relative(process.cwd(), file)), chalk_1.default.gray(`(${(st.size / 1024 / 1024).toFixed(2)}MB)`));
+                console.warn(chalk_1.default.yellow(`⚠️  Large file (streaming line-by-line):`), chalk_1.default.white(path_1.default.relative(cwd, file)), chalk_1.default.gray(`(${(st.size / 1024 / 1024).toFixed(2)}MB)`));
             }
             if (options.stats) {
                 options.stats.filesScanned += 1;
@@ -77,11 +99,11 @@ async function scanFileListAsync(files, scanner, options = {}) {
                 options.bus.add({
                     code: 'file.read_error',
                     severity: 'error',
-                    ctx: { file: path_1.default.relative(process.cwd(), file), detail: String(error) },
+                    ctx: { file: path_1.default.relative(cwd, file), detail: String(error) },
                 });
             }
             if (verbose) {
-                console.error(chalk_1.default.red('❌ Error scanning file:'), chalk_1.default.white(path_1.default.relative(process.cwd(), file)));
+                console.error(chalk_1.default.red('❌ Error scanning file:'), chalk_1.default.white(path_1.default.relative(cwd, file)));
                 console.error(chalk_1.default.gray(String(error)));
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaultcompass/vault-guard",
-  "version": "1.2.2",
+  "version": "1.3.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.2.2",
-    "@vaultcompass/vault-guard-telemetry": "1.2.2"
+    "@vaultcompass/vault-guard-core": "1.3.0",
+    "@vaultcompass/vault-guard-telemetry": "1.3.0"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",