@vaultcompass/vault-guard-core 1.4.3 → 1.4.5

package/dist/scan-output.d.ts

@@ -62,9 +62,24 @@ export interface FormatOptions {
     /**
      * Base directory to render `file` paths relative to.
      * Defaults to `process.cwd()`. Files outside this root are kept absolute.
-     * Pass `null` to skip relativization entirely.
+     * Pass `null` to skip relativization for `formatJson`'s `file` paths and
+     * for SARIF when no {@link scanRoot} is given either. A `scanRoot` still
+     * relativizes SARIF `artifactLocation.uri` (and diagnostic ctx) against
+     * itself in that case, so `cwd: null` does not skip SARIF relativization
+     * on its own.
      */
     cwd?: string | null;
+    /**
+     * Directory actually being scanned (the scan target), when it differs from
+     * {@link cwd}. SARIF only: `artifactLocation.uri` is relativized against
+     * this instead of `cwd`, so a finding outside the process cwd but inside the
+     * scan target still gets a relative uri. Defaults to `cwd`.
+     *
+     * `formatJson` ignores this field. Its `file` paths stay cwd-relative,
+     * because they are what the terminal output and the baseline fingerprints
+     * are keyed on.
+     */
+    scanRoot?: string;
     /** Non-fatal diagnostics to include in structured output. */
     diagnostics?: Diagnostic[];
     /** Scan timing / coverage stats for JSON and SARIF `runs[].properties`. */

package/dist/scan-output.js

@@ -37,24 +37,103 @@ function isWindowsStylePath(p) {
  * SARIF spec requires this even when the scanner itself runs on Windows,
  * where `path.relative` returns backslash-separated paths).
  *
+ * The base is the scan root (the directory actually being scanned), not the
+ * process cwd. Scanning an out-of-tree target from somewhere else used to
+ * leave every uri absolute, which published the developer's home directory
+ * and OS username to whoever reads the Code Scanning upload.
+ *
+ * A file genuinely outside the scan root still stays absolute rather than
+ * becoming a `../..` traversal: SARIF relative references are resolved
+ * against `%SRCROOT%`, so a traversal out of it is not a legal uri, and there
+ * is no other root to express such a path against. In practice this only
+ * happens for a path a caller injected from outside the scan, since every
+ * file the scanner itself walks is under the target it was given -- and a
+ * non-absolute `file` is resolved against cwd below before that check runs,
+ * so a literal `..` traversal segment never reaches the returned uri either.
+ *
  * Picks `path.win32` when either side of the comparison looks like a
  * Windows-style path, so this is correct both when the process itself runs
  * on Windows (native `path` is already `path.win32`) and when a
  * Windows-style path is normalized on a POSIX host (tests, or a SARIF file
  * produced elsewhere and re-normalized).
  */
-function toSarifArtifactUri(file, cwd) {
-    if (cwd === null)
+function toSarifArtifactUri(file, cwd, scanRoot) {
+    if (cwd === null && scanRoot === undefined)
         return file.split('\\').join('/');
-    const base = cwd ?? process.cwd();
-    const impl = isWindowsStylePath(file) || isWindowsStylePath(base) ? path_1.default.win32 : path_1.default;
-    if (!impl.isAbsolute(file))
-        return file.split('\\').join('/');
-    const rel = impl.relative(base, file);
+    const anchor = cwd ?? process.cwd();
+    const impl = isWindowsStylePath(file) || isWindowsStylePath(anchor) ? path_1.default.win32 : path_1.default;
+    const abs = impl.isAbsolute(file) ? file : impl.resolve(anchor, file);
+    const base = resolveSarifBase(anchor, scanRoot, impl);
+    const rel = impl.relative(base, abs);
     if (rel.startsWith('..') || impl.isAbsolute(rel))
-        return file.split('\\').join('/');
+        return abs.split('\\').join('/');
     return (rel || '.').split('\\').join('/');
 }
+/**
+ * The effective SARIF `%SRCROOT%` base. `scanRoot` is honored only when it
+ * is genuinely outside `cwd`: a scan root nested inside cwd (or equal to
+ * it) must not narrow `%SRCROOT%` to a subdirectory, because GitHub Code
+ * Scanning (and any other SARIF consumer) resolves `%SRCROOT%` from its own
+ * knowledge of the checkout, not from this uri -- a uri relative to a
+ * subdirectory would then name a different file entirely. Mirrors
+ * `resolveScanRoot` in `packages/cli/src/utils/scan-utils.ts`, which applies
+ * the same rule when it derives `scanRoot` from the CLI's scan target in the
+ * first place.
+ */
+function resolveSarifBase(cwd, scanRoot, impl) {
+    if (scanRoot === undefined)
+        return cwd;
+    const rel = impl.relative(cwd, scanRoot);
+    if (rel === '' || (!rel.startsWith('..') && !impl.isAbsolute(rel)))
+        return cwd;
+    return scanRoot;
+}
+/**
+ * Diagnostic `ctx` reaches SARIF notifications as `JSON.stringify(d.ctx)`
+ * (see `formatSarif` above), and some diagnostic sources (`fs.permission_denied`,
+ * `file.read_error`) carry the scanned directory or file as an absolute path,
+ * plus a `detail` field that is `String(error)` -- Node's own fs error text
+ * often bakes that same absolute path in (e.g. "EACCES: permission denied,
+ * scandir '/abs/dir'"). Both leak exactly what `artifactLocation.uri`
+ * exists to avoid leaking, so ctx gets the same relativize-or-keep-absolute
+ * treatment before it is stringified into a notification: any absolute-path
+ * ctx value (`dir`, `path`, `file`, or any other field shaped that way) is
+ * run through {@link toSarifArtifactUri}, and any other string value has
+ * literal occurrences of the base directory stripped out.
+ */
+function sanitizeDiagnosticCtxForSarif(ctx, cwd, scanRoot) {
+    if (cwd === null && scanRoot === undefined)
+        return ctx;
+    const anchor = cwd ?? process.cwd();
+    const base = resolveSarifBase(anchor, scanRoot, path_1.default);
+    const out = {};
+    for (const [key, value] of Object.entries(ctx)) {
+        if (typeof value !== 'string') {
+            out[key] = value;
+        }
+        else if (path_1.default.isAbsolute(value)) {
+            out[key] = toSarifArtifactUri(value, cwd, scanRoot);
+        }
+        else {
+            out[key] = stripSarifBasePath(value, base);
+        }
+    }
+    return out;
+}
+/**
+ * Removes literal occurrences of the SARIF base directory from a free-form
+ * string (diagnostic `detail`, which is `String(error)` and can embed the
+ * scanned path inside Node's own message text). This is not a full
+ * relative-path rewrite of the string, just enough to keep the base
+ * directory out of the document, matching what `artifactLocation.uri` does
+ * for the path fields themselves.
+ */
+function stripSarifBasePath(text, base) {
+    if (!text.includes(base))
+        return text;
+    const withTrailingSep = base.endsWith(path_1.default.sep) ? base : base + path_1.default.sep;
+    return text.split(withTrailingSep).join('').split(base).join('.');
+}
 function formatJson(results, opts = {}) {
     const fpCwd = opts.cwd === undefined ? process.cwd() : opts.cwd;
     const output = {
@@ -112,7 +191,10 @@ function formatSarif(results, opts = {}) {
         locations: [
             {
                 physicalLocation: {
-                    artifactLocation: { uri: toSarifArtifactUri(file, opts.cwd), uriBaseId: '%SRCROOT%' },
+                    artifactLocation: {
+                        uri: toSarifArtifactUri(file, opts.cwd, opts.scanRoot),
+                        uriBaseId: '%SRCROOT%',
+                    },
                     region: {
                         startLine: m.line,
                         startColumn: m.column + 1,
@@ -133,7 +215,9 @@ function formatSarif(results, opts = {}) {
         ? opts.diagnostics.map(d => ({
             id: d.code,
             level: d.severity === 'error' ? 'error' : 'warning',
-            message: { text: `${d.code}: ${JSON.stringify(d.ctx)}` },
+            message: {
+                text: `${d.code}: ${JSON.stringify(sanitizeDiagnosticCtxForSarif(d.ctx, opts.cwd, opts.scanRoot))}`,
+            },
         }))
         : undefined;
     const runProps = opts.run !== undefined

package/dist/scanners/pre-commit-hook.d.ts

@@ -1,7 +1,16 @@
 export type HookManager = 'native' | 'husky' | 'lefthook' | 'precommit';
 export interface InstallHookOptions {
     manager?: HookManager;
-    /** Working directory (git repo root). Defaults to `process.cwd()`. */
+    /**
+     * Working directory. MUST be the git repository root -- the directory
+     * containing `.git` -- not a package subdirectory in a monorepo, even
+     * one that owns its own `.husky`. `install()`/`uninstall()` refuse
+     * outright when `.git` is not directly present (see the check at the
+     * top of each), and core.hooksPath is resolved relative to the
+     * worktree root regardless of where a nested `.husky` lives, so running
+     * from anywhere else either fails fast or resolves the wrong hooks
+     * directory entirely. Defaults to `process.cwd()`.
+     */
     cwd?: string;
 }
 export declare class PreCommitHook {
@@ -31,14 +40,71 @@ export declare class PreCommitHook {
         hooksDir: string;
         viaHooksPath: boolean;
     };
+    /**
+     * Whether the resolved hooks directory is husky 9's GENERATED,
+     * gitignored directory (\`.husky/_\` by default) rather than a real
+     * hooks directory. Husky's own prepare script rewrites this directory on
+     * every \`pnpm install\`, so nothing vault-guard writes there survives;
+     * the durable, tracked hook lives one directory up at
+     * \`.husky/<hookname>\`.
+     *
+     * This is deliberately narrow: the ONLY signal that may trigger the
+     * redirect is the directory SHAPE -- a resolved basename of \`_\` under a
+     * directory literally named \`.husky\`. Two false-positive shapes were
+     * caught by review before shipping and must never redirect:
+     *  - core.hooksPath pointing at an unrelated directory (e.g. .githooks)
+     *    that happens to contain a file literally named \`h\` -- an \`h\` file
+     *    is not evidence of husky on its own, only the directory shape is;
+     *  - a dispatcher-shaped pre-commit file (the same two-line shebang
+     *    body husky 9 writes) sitting somewhere that is NOT \`.husky/_\`
+     *    (e.g. plain \`.git/hooks/pre-commit\`) -- content shape alone is not
+     *    evidence either, since a foreign hook can coincidentally look like
+     *    this.
+     * Neither the \`h\` shim nor dispatcher-shaped content is checked at all
+     * here; they would only ever have been used to confirm a shape match,
+     * never to trigger one on their own, and the shape check alone is both
+     * necessary and sufficient for every case this fix needs to handle.
+     */
+    isHuskyGeneratedHooksDir(hooksDir: string): boolean;
+    /**
+     * Where husky's own \`h\` shim actually resolves and executes the tracked
+     * hook, given a husky-generated hooksDir (isHuskyGeneratedHooksDir(hooksDir)
+     * must already be true). Husky computes this as the PARENT of the
+     * generated \`_\` directory -- fixed relative to hooksDir, never a fixed
+     * \`<cwd>/.husky\`, because core.hooksPath can point at a NESTED
+     * \`.husky/_\` (e.g. \`packages/app/.husky/_\`, the ordinary shape for a
+     * monorepo package that owns husky's "prepare" script but is not itself
+     * the git root). In that case husky's shim genuinely runs
+     * \`packages/app/.husky/<hookname>\`, not \`<cwd>/.husky/<hookname>\` --
+     * proven wrong by independent review with a functional shim and a real
+     * commit before this was fixed. getPreCommitHookPath, installNative,
+     * uninstallNative, and getPreCommitCmdPath all resolve through this one
+     * place so the redirect target can never drift between them.
+     */
+    private resolveHuskyDir;
+    /** \`absPath\`, relative to \`cwd\`, with forward slashes on every platform. */
+    private relFromCwd;
     /**
      * Absolute path to the \`pre-commit\` hook file for the given manager.
+     *
+     * For the \`native\` manager, when the resolved hooks directory is
+     * husky 9's generated directory (see isHuskyGeneratedHooksDir), this
+     * resolves to the TRACKED hook file husky's own \`h\` shim actually runs
+     * -- see resolveHuskyDir -- because nothing written under the generated
+     * directory survives husky's prepare script. See install()'s
+     * husky-delegation in installNative for the write side of this.
      */
     getPreCommitHookPath(cwd: string, manager?: HookManager): string;
     /**
-     * Absolute path to the Windows \`pre-commit.cmd\` companion (native manager only).
+     * Absolute path to the Windows \`pre-commit.cmd\` companion (native manager
+     * only). \`undefined\` under a husky-generated hooks directory: the .cmd
+     * companion is native-only and installNative's husky-redirect never
+     * writes one there (see installNative), so there is no meaningful path
+     * to report. Callers that used to guard this getter with their own
+     * isHuskyGeneratedHooksDir check (the CLI's foreignHookConflict did)
+     * can drop that guard now that it lives here instead.
      */
-    getPreCommitCmdPath(cwd: string): string;
+    getPreCommitCmdPath(cwd: string): string | undefined;
     install(options?: InstallHookOptions): {
         success: boolean;
         message: string;
@@ -57,7 +123,34 @@ export declare class PreCommitHook {
     private removeNativeCmdCompanion;
     private installNative;
     private uninstallNative;
+    /**
+     * @param huskyDir Directory holding the tracked hook. Defaults to
+     *   \`<cwd>/.husky\`, correct for the explicit \`husky\` manager (it never
+     *   consults core.hooksPath). installNative's redirect passes the
+     *   ACTUAL directory resolveHuskyDir computed instead, which can be
+     *   nested (e.g. \`packages/app/.husky\`) -- see resolveHuskyDir.
+     */
     private installHusky;
+    /**
+     * @param huskyDir See installHusky.
+     *
+     * Fix for a defect the reviewer found while checking uninstall after
+     * the redirect started routing every husky 9 repo through this
+     * function (previously only reachable via the explicit `husky`
+     * manager): when installHusky wrote the WHOLE file from
+     * HUSKY_HOOK_SCRIPT (the fresh-install path -- what both the redirect
+     * and a from-scratch \`--manager husky\` install take), there is no
+     * "# --- vault-guard ---" appended-block marker to strip, so the old
+     * logic here matched nothing, rewrote the file byte-identical, and
+     * reported success:true with isInstalled still true. Distinguishing
+     * the two shapes vault-guard itself ever produces -- the whole-file
+     * header vs. the appended-stanza marker -- fixes this: a whole-file
+     * hook is removed entirely; an appended stanza is stripped, keeping
+     * the pre-existing foreign content; anything else that merely mentions
+     * "vault-guard" in neither recognized shape is left untouched, with an
+     * honest message and success only if it happens not to still read as
+     * installed.
+     */
     private uninstallHusky;
     private installLefthook;
     private uninstallLefthook;

package/dist/scanners/pre-commit-hook.js

@@ -8,12 +8,23 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const errors_1 = require("../errors");
+/**
+ * Marks a hook file vault-guard wrote WHOLE, from a template -- as
+ * opposed to a stanza vault-guard appended to a pre-existing (foreign)
+ * hook it does not own. uninstallHusky uses this to decide whether it is
+ * safe to delete the file outright: present means the whole file is
+ * vault-guard's, so removing it entirely is correct; absent (even when
+ * the file mentions "vault-guard" some other way) means the file
+ * predates vault-guard or was never fully vault-guard's, so it must not
+ * be deleted wholesale.
+ */
+const VAULT_GUARD_HOOK_HEADER = '# vault-guard pre-commit (installed by @vaultcompass/vault-guard)';
 /**
  * Shell hook body for **native** Git hooks (`core.hooksPath` or `.git/hooks`).
  * Scans **staged files only** — fast and matches what will actually be committed.
  */
 const NATIVE_HOOK_SCRIPT = `#!/bin/sh
-# vault-guard pre-commit (installed by @vaultcompass/vault-guard)
+${VAULT_GUARD_HOOK_HEADER}
 set -e
 
 # Re-attach stdin for GUI git clients when possible.
@@ -69,6 +80,7 @@ exit /b 0
 `;
 /** Husky-friendly hook (sources \`_/husky.sh\` when present). */
 const HUSKY_HOOK_SCRIPT = `#!/usr/bin/env sh
+${VAULT_GUARD_HOOK_HEADER}
 if [ -f "$(dirname "$0")/_/husky.sh" ]; then
   . "$(dirname "$0")/_/husky.sh"
 fi
@@ -151,20 +163,93 @@ class PreCommitHook {
         const worktreeRoot = this.resolveWorktreeRoot(cwd) ?? cwd;
         return { hooksDir: path_1.default.join(worktreeRoot, hooksPath), viaHooksPath: true };
     }
+    /**
+     * Whether the resolved hooks directory is husky 9's GENERATED,
+     * gitignored directory (\`.husky/_\` by default) rather than a real
+     * hooks directory. Husky's own prepare script rewrites this directory on
+     * every \`pnpm install\`, so nothing vault-guard writes there survives;
+     * the durable, tracked hook lives one directory up at
+     * \`.husky/<hookname>\`.
+     *
+     * This is deliberately narrow: the ONLY signal that may trigger the
+     * redirect is the directory SHAPE -- a resolved basename of \`_\` under a
+     * directory literally named \`.husky\`. Two false-positive shapes were
+     * caught by review before shipping and must never redirect:
+     *  - core.hooksPath pointing at an unrelated directory (e.g. .githooks)
+     *    that happens to contain a file literally named \`h\` -- an \`h\` file
+     *    is not evidence of husky on its own, only the directory shape is;
+     *  - a dispatcher-shaped pre-commit file (the same two-line shebang
+     *    body husky 9 writes) sitting somewhere that is NOT \`.husky/_\`
+     *    (e.g. plain \`.git/hooks/pre-commit\`) -- content shape alone is not
+     *    evidence either, since a foreign hook can coincidentally look like
+     *    this.
+     * Neither the \`h\` shim nor dispatcher-shaped content is checked at all
+     * here; they would only ever have been used to confirm a shape match,
+     * never to trigger one on their own, and the shape check alone is both
+     * necessary and sufficient for every case this fix needs to handle.
+     */
+    isHuskyGeneratedHooksDir(hooksDir) {
+        const base = path_1.default.basename(hooksDir);
+        const parentBase = path_1.default.basename(path_1.default.dirname(hooksDir));
+        return base === '_' && parentBase === '.husky';
+    }
+    /**
+     * Where husky's own \`h\` shim actually resolves and executes the tracked
+     * hook, given a husky-generated hooksDir (isHuskyGeneratedHooksDir(hooksDir)
+     * must already be true). Husky computes this as the PARENT of the
+     * generated \`_\` directory -- fixed relative to hooksDir, never a fixed
+     * \`<cwd>/.husky\`, because core.hooksPath can point at a NESTED
+     * \`.husky/_\` (e.g. \`packages/app/.husky/_\`, the ordinary shape for a
+     * monorepo package that owns husky's "prepare" script but is not itself
+     * the git root). In that case husky's shim genuinely runs
+     * \`packages/app/.husky/<hookname>\`, not \`<cwd>/.husky/<hookname>\` --
+     * proven wrong by independent review with a functional shim and a real
+     * commit before this was fixed. getPreCommitHookPath, installNative,
+     * uninstallNative, and getPreCommitCmdPath all resolve through this one
+     * place so the redirect target can never drift between them.
+     */
+    resolveHuskyDir(hooksDir) {
+        return path_1.default.dirname(hooksDir);
+    }
+    /** \`absPath\`, relative to \`cwd\`, with forward slashes on every platform. */
+    relFromCwd(cwd, absPath) {
+        return path_1.default.relative(cwd, absPath).split(path_1.default.sep).join('/');
+    }
     /**
      * Absolute path to the \`pre-commit\` hook file for the given manager.
+     *
+     * For the \`native\` manager, when the resolved hooks directory is
+     * husky 9's generated directory (see isHuskyGeneratedHooksDir), this
+     * resolves to the TRACKED hook file husky's own \`h\` shim actually runs
+     * -- see resolveHuskyDir -- because nothing written under the generated
+     * directory survives husky's prepare script. See install()'s
+     * husky-delegation in installNative for the write side of this.
      */
     getPreCommitHookPath(cwd, manager = 'native') {
         if (manager === 'husky') {
             return path_1.default.join(cwd, '.husky', 'pre-commit');
         }
-        return path_1.default.join(this.getEffectiveHooksDir(cwd).hooksDir, 'pre-commit');
+        const { hooksDir } = this.getEffectiveHooksDir(cwd);
+        if (this.isHuskyGeneratedHooksDir(hooksDir)) {
+            return path_1.default.join(this.resolveHuskyDir(hooksDir), 'pre-commit');
+        }
+        return path_1.default.join(hooksDir, 'pre-commit');
     }
     /**
-     * Absolute path to the Windows \`pre-commit.cmd\` companion (native manager only).
+     * Absolute path to the Windows \`pre-commit.cmd\` companion (native manager
+     * only). \`undefined\` under a husky-generated hooks directory: the .cmd
+     * companion is native-only and installNative's husky-redirect never
+     * writes one there (see installNative), so there is no meaningful path
+     * to report. Callers that used to guard this getter with their own
+     * isHuskyGeneratedHooksDir check (the CLI's foreignHookConflict did)
+     * can drop that guard now that it lives here instead.
      */
     getPreCommitCmdPath(cwd) {
-        return path_1.default.join(this.getEffectiveHooksDir(cwd).hooksDir, 'pre-commit.cmd');
+        const { hooksDir } = this.getEffectiveHooksDir(cwd);
+        if (this.isHuskyGeneratedHooksDir(hooksDir)) {
+            return undefined;
+        }
+        return path_1.default.join(hooksDir, 'pre-commit.cmd');
     }
     install(options = {}) {
         const cwd = options.cwd ?? process.cwd();
@@ -245,6 +330,25 @@ class PreCommitHook {
     }
     installNative(cwd) {
         const { hooksDir, viaHooksPath } = this.getEffectiveHooksDir(cwd);
+        // core.hooksPath points at husky 9's generated, gitignored directory
+        // (typically .husky/_, but see resolveHuskyDir for the nested case).
+        // Writing there is pointless -- husky's prepare script rewrites it on
+        // every `pnpm install` -- so install into the same tracked hook file
+        // the husky manager uses, and say so. Never write under the generated
+        // directory in this branch.
+        if (this.isHuskyGeneratedHooksDir(hooksDir)) {
+            const huskyDir = this.resolveHuskyDir(hooksDir);
+            const result = this.installHusky(cwd, huskyDir);
+            if (!result.success) {
+                return result;
+            }
+            const relHookPath = this.relFromCwd(cwd, result.hookPath ?? path_1.default.join(huskyDir, 'pre-commit'));
+            return {
+                success: true,
+                message: `Hooks are managed by husky; installing into ${relHookPath}. ${result.message}`,
+                hookPath: result.hookPath,
+            };
+        }
         const hookPath = path_1.default.join(hooksDir, 'pre-commit');
         const cmdPath = path_1.default.join(hooksDir, 'pre-commit.cmd');
         try {
@@ -287,6 +391,14 @@ class PreCommitHook {
     }
     uninstallNative(cwd) {
         const { hooksDir } = this.getEffectiveHooksDir(cwd);
+        if (this.isHuskyGeneratedHooksDir(hooksDir)) {
+            const huskyDir = this.resolveHuskyDir(hooksDir);
+            const result = this.uninstallHusky(cwd, huskyDir);
+            return {
+                success: result.success,
+                message: `Hooks are managed by husky; ${result.message}`,
+            };
+        }
         const hookPath = path_1.default.join(hooksDir, 'pre-commit');
         const cmdRemoved = this.removeNativeCmdCompanion(hooksDir);
         if (!fs_1.default.existsSync(hookPath)) {
@@ -323,9 +435,16 @@ class PreCommitHook {
     // -------------------------------------------------------------------------
     // Husky — .husky/pre-commit
     // -------------------------------------------------------------------------
-    installHusky(cwd) {
-        const huskyDir = path_1.default.join(cwd, '.husky');
+    /**
+     * @param huskyDir Directory holding the tracked hook. Defaults to
+     *   \`<cwd>/.husky\`, correct for the explicit \`husky\` manager (it never
+     *   consults core.hooksPath). installNative's redirect passes the
+     *   ACTUAL directory resolveHuskyDir computed instead, which can be
+     *   nested (e.g. \`packages/app/.husky\`) -- see resolveHuskyDir.
+     */
+    installHusky(cwd, huskyDir = path_1.default.join(cwd, '.husky')) {
         const hookPath = path_1.default.join(huskyDir, 'pre-commit');
+        const relHookPath = this.relFromCwd(cwd, hookPath);
         try {
             if (!fs_1.default.existsSync(huskyDir)) {
                 fs_1.default.mkdirSync(huskyDir, { recursive: true });
@@ -339,12 +458,12 @@ class PreCommitHook {
                     return { success: true, message: 'Husky hook already contains vault-guard block', hookPath };
                 }
                 fs_1.default.appendFileSync(hookPath, `\n# --- vault-guard ---\nvault-guard scan --staged || {\n  echo "❌ vault-guard blocked commit"\n  exit 1\n}\n`, { encoding: 'utf-8' });
-                return { success: true, message: 'Appended vault-guard to existing .husky/pre-commit', hookPath };
+                return { success: true, message: `Appended vault-guard to existing ${relHookPath}`, hookPath };
             }
             fs_1.default.writeFileSync(hookPath, HUSKY_HOOK_SCRIPT, { mode: 0o755 });
             return {
                 success: true,
-                message: 'Created .husky/pre-commit (run `npx husky init` first if _/husky.sh is missing)',
+                message: `Created ${relHookPath} (run \`npx husky init\` first if _/husky.sh is missing)`,
                 hookPath,
             };
         }
@@ -353,28 +472,72 @@ class PreCommitHook {
             return { success: false, message: hookError.message };
         }
     }
-    uninstallHusky(cwd) {
-        const hookPath = path_1.default.join(cwd, '.husky', 'pre-commit');
+    /**
+     * @param huskyDir See installHusky.
+     *
+     * Fix for a defect the reviewer found while checking uninstall after
+     * the redirect started routing every husky 9 repo through this
+     * function (previously only reachable via the explicit `husky`
+     * manager): when installHusky wrote the WHOLE file from
+     * HUSKY_HOOK_SCRIPT (the fresh-install path -- what both the redirect
+     * and a from-scratch \`--manager husky\` install take), there is no
+     * "# --- vault-guard ---" appended-block marker to strip, so the old
+     * logic here matched nothing, rewrote the file byte-identical, and
+     * reported success:true with isInstalled still true. Distinguishing
+     * the two shapes vault-guard itself ever produces -- the whole-file
+     * header vs. the appended-stanza marker -- fixes this: a whole-file
+     * hook is removed entirely; an appended stanza is stripped, keeping
+     * the pre-existing foreign content; anything else that merely mentions
+     * "vault-guard" in neither recognized shape is left untouched, with an
+     * honest message and success only if it happens not to still read as
+     * installed.
+     */
+    uninstallHusky(cwd, huskyDir = path_1.default.join(cwd, '.husky')) {
+        const hookPath = path_1.default.join(huskyDir, 'pre-commit');
+        const relHookPath = this.relFromCwd(cwd, hookPath);
         if (!fs_1.default.existsSync(hookPath)) {
-            return { success: true, message: 'No .husky/pre-commit to remove' };
+            return { success: true, message: `No ${relHookPath} to remove` };
         }
-        let content = fs_1.default.readFileSync(hookPath, 'utf-8');
+        const content = fs_1.default.readFileSync(hookPath, 'utf-8');
         if (!content.includes('vault-guard')) {
-            return { success: true, message: 'No vault-guard stanza in .husky/pre-commit' };
+            return { success: true, message: `No vault-guard stanza in ${relHookPath}` };
         }
-        // Remove appended block if present.
-        content = content.replace(/\n# --- vault-guard ---[\s\S]*$/m, '');
-        // If entire file is only our husky template, delete file.
-        if (!content.includes('vault-guard')) {
-            if (content.trim().length === 0) {
+        // vault-guard wrote the ENTIRE file from HUSKY_HOOK_SCRIPT (whether
+        // via a fresh --manager husky install or the native husky-redirect):
+        // it is safe, and correct, to remove the file outright rather than
+        // try to strip individual lines from a template vault-guard owns.
+        if (content.includes(VAULT_GUARD_HOOK_HEADER)) {
+            fs_1.default.unlinkSync(hookPath);
+            return { success: true, message: `Removed ${relHookPath}` };
+        }
+        // vault-guard appended a stanza to a pre-existing (foreign) hook: strip
+        // just that stanza, preserving whatever the file had before.
+        if (content.includes('# --- vault-guard ---')) {
+            const stripped = content.replace(/\n# --- vault-guard ---[\s\S]*$/m, '');
+            if (stripped.trim().length === 0) {
                 fs_1.default.unlinkSync(hookPath);
-                return { success: true, message: 'Removed .husky/pre-commit' };
+                return { success: true, message: `Removed ${relHookPath}` };
             }
-            fs_1.default.writeFileSync(hookPath, content, { mode: 0o755 });
-            return { success: true, message: 'Removed vault-guard stanza from .husky/pre-commit' };
+            fs_1.default.writeFileSync(hookPath, stripped, { mode: 0o755 });
+            const stillInstalled = stripped.includes('vault-guard') && stripped.includes('scan --staged');
+            return {
+                success: !stillInstalled,
+                message: stillInstalled
+                    ? `Removed the appended stanza from ${relHookPath}, but it still references vault-guard -- review manually`
+                    : `Removed vault-guard stanza from ${relHookPath}`,
+            };
         }
-        fs_1.default.writeFileSync(hookPath, content, { mode: 0o755 });
-        return { success: true, message: 'Updated .husky/pre-commit (review manually if needed)' };
+        // Mentions "vault-guard" somewhere, but in NEITHER shape vault-guard
+        // itself ever writes (no whole-file header, no appended-stanza
+        // marker) -- do not guess at what to remove from a file this code did
+        // not write; leave it untouched and say so honestly. Report success
+        // only if it does not still read as installed (isInstalled uses the
+        // same two-substring check).
+        const stillInstalled = content.includes('vault-guard') && content.includes('scan --staged');
+        return {
+            success: !stillInstalled,
+            message: `${relHookPath} mentions vault-guard but does not match the shape this version writes; it may have been written by an older vault-guard, or by hand. Leaving it unchanged. Review and remove the vault-guard reference manually if needed.`,
+        };
     }
     // -------------------------------------------------------------------------
     // Lefthook — lefthook-local.yml (merged with lefthook.yml)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaultcompass/vault-guard-core",
-  "version": "1.4.3",
+  "version": "1.4.5",
   "description": "Secret-scanning engine: vendor-anchored patterns, entropy gating, baselines, SARIF/JSON, hook helpers.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",