vigiles 12.4.0 → 12.6.0

package/dist/core/bash-effects.d.ts

@@ -50,4 +50,48 @@ export declare function isReadOnlyBash(command: string): boolean;
  * native `Bash(git:*)` glob (issue #30519) and a hand-written `grep` both miss.
  */
 export declare function leafCommands(command: string): string[][];
+/** A single simple command, normalized to its operation form. */
+export interface NormalizedLeaf {
+    /** Head normalized to its basename, backslash-stripped: `/bin/rm`→`rm`, `\rm`→`rm`. */
+    readonly head: string;
+    /** `[head, ...args]` — every word quote-unwrapped and $HOME/~-canonicalized. */
+    readonly argv: readonly string[];
+    /** The normalized args (argv without the head). */
+    readonly args: readonly string[];
+    /**
+     * Canonical flag tokens present on this leaf. Short clusters are split
+     * (`-rf`→`r`,`f`) and each flag is recorded in BOTH short and long form via the
+     * alias table, so a caller can test `--force`/`-f` or `--no-verify`/`-n`
+     * uniformly. Long values are split on `=` (`--index-url=x`→`index-url`).
+     */
+    readonly flags: ReadonlySet<string>;
+    /** True iff ANY of `names` is present in {@link flags} (short or long). */
+    hasFlag(...names: readonly string[]): boolean;
+    /**
+     * Command-level env-assignments that apply to THIS leaf, keyed by variable
+     * name → static value (empty string for a naked `NAME=`). Populated from both
+     * the mvdan leading `CallExpr.Assigns` (`PIP_INDEX_URL=… pip install …`) AND
+     * the `NAME=value` words consumed by an `env` wrapper (`env NPM_CONFIG_REGISTRY=… npm i`).
+     *
+     * These carry supply-chain / behavior-altering configuration (`PIP_INDEX_URL`,
+     * `NPM_CONFIG_REGISTRY`, …) that an argv-only extractor never sees because the
+     * assignment is not an argv word. A dynamic RHS (command substitution, non-HOME
+     * parameter) is recorded with value `null` — present but unresolved. */
+    readonly assigns: ReadonlyMap<string, string | null>;
+    /** True iff a command-level assignment for ANY of `names` is present (resolved or not). */
+    hasAssign(...names: readonly string[]): boolean;
+}
+/**
+ * Extract every simple command as a {@link NormalizedLeaf} — the operation-level
+ * twin of {@link leafCommands}. Same AST-backed structural coverage (a leaf nested
+ * in a pipeline / `&&` / subshell is still found), but each word is quote-unwrapped
+ * and $HOME-canonicalized, the head is reduced to its backslash-stripped basename,
+ * and flags are expanded to short+long canonical forms. A matcher built on this
+ * compares against the OPERATION rather than the surface tokens, so it is robust
+ * to quoting, interpreter path, backslash escaping, flag aliasing, and $HOME/~.
+ *
+ * Purely additive: reuses the same mvdan-sh parse, changes nothing above. Parse
+ * failure → []. A leaf with a dynamic head is skipped (can't be normalized).
+ */
+export declare function leafCommandsNormalized(command: string): NormalizedLeaf[];
 //# sourceMappingURL=bash-effects.d.ts.map

package/dist/core/bash-effects.js

@@ -27,6 +27,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.classifyBashCommand = classifyBashCommand;
 exports.isReadOnlyBash = isReadOnlyBash;
 exports.leafCommands = leafCommands;
+exports.leafCommandsNormalized = leafCommandsNormalized;
 // mvdan-sh is a CJS package (GopherJS build) with no bundled TypeScript types.
 // The project compiles to CommonJS (Node16, no "type":"module"), so plain
 // require() works and is the idiomatic pattern here (see linters.ts).
@@ -433,4 +434,306 @@ function leafCommands(command) {
     });
     return out;
 }
+/**
+ * Known short↔long flag aliases. Deliberately small and operation-relevant:
+ * a caller always gates on the head (e.g. only treats `index-url` as supply-chain
+ * when the head is `pip`), so recording both forms unconditionally is safe.
+ */
+const SHORT_TO_LONG = {
+    f: "force",
+    n: "no-verify",
+    r: "recursive",
+    i: "index-url",
+};
+const LONG_TO_SHORT = {
+    force: "f",
+    "no-verify": "n",
+    recursive: "r",
+    "index-url": "i",
+};
+/**
+ * Reconstruct a Word's static text, unwrapping single/double quotes and
+ * canonicalizing `$HOME`/`${HOME}` to `~`. Returns null if the word contains a
+ * truly dynamic segment (command substitution, arithmetic, a non-HOME parameter)
+ * — such a word can't be soundly reduced to a literal operation token.
+ */
+function normalizeParts(parts) {
+    if (!parts)
+        return null;
+    let out = "";
+    for (const p of parts) {
+        const t = sh.syntax.NodeType(p);
+        if (t === "Lit" || t === "SglQuoted") {
+            out += p.Value ?? "";
+        }
+        else if (t === "DblQuoted") {
+            const inner = normalizeParts(p.Parts);
+            if (inner === null)
+                return null;
+            out += inner;
+        }
+        else if (t === "ParamExp") {
+            // Canonicalize the home directory; any other parameter is dynamic.
+            if (p.Param?.Value === "HOME")
+                out += "~";
+            else
+                return null;
+        }
+        else {
+            return null; // CmdSubst / ArithmExp / ProcSubst / … → dynamic
+        }
+    }
+    return out;
+}
+/** Normalize a command head to its basename, stripping one leading backslash. */
+function normalizeHead(raw) {
+    const unescaped = raw.startsWith("\\") ? raw.slice(1) : raw;
+    const slash = unescaped.lastIndexOf("/");
+    return slash >= 0 ? unescaped.slice(slash + 1) : unescaped;
+}
+/** Build the canonical flag set for a leaf's args (short-cluster + alias expansion). */
+function buildFlags(args) {
+    const flags = new Set();
+    const add = (name) => {
+        if (!name)
+            return;
+        flags.add(name);
+        if (name.length === 1 && SHORT_TO_LONG[name])
+            flags.add(SHORT_TO_LONG[name]);
+        const short = LONG_TO_SHORT[name];
+        if (short)
+            flags.add(short);
+    };
+    for (const a of args) {
+        if (a.startsWith("--")) {
+            add(a.slice(2).split("=")[0] ?? "");
+        }
+        else if (a.length > 1 && a[0] === "-") {
+            for (const ch of a.slice(1)) {
+                if (/[a-zA-Z]/.test(ch))
+                    add(ch);
+            }
+        }
+    }
+    return flags;
+}
+// ---------------------------------------------------------------------------
+// Command-wrapper stripping.
+//
+// A wrapper is a command whose JOB is to run ANOTHER command: `env FOO=bar CMD`,
+// `command CMD`, `sudo CMD`, `nice -n5 CMD`, `timeout 5 CMD`, `xargs CMD`,
+// `nohup CMD`. Because the normalized leaf keys on the leaf HEAD, a wrapper head
+// hides the real operation — `env GIT_SSH= git push --force` and `command rm -rf /`
+// look like `env`/`command` leaves, so a head-keyed matcher never sees the
+// `git push --force` / `rm -rf /` it must block. We resolve THROUGH the wrapper:
+// skip the wrapper's own options (and their values) and any `NAME=value` words it
+// consumes, then treat the next word as the real command head (recursing so
+// `sudo timeout 5 rm -rf /` unwraps fully). A wrapper with no following command
+// (bare `env`, `env -i`) is preserved as-is, so the env-dump predicate still fires.
+// ---------------------------------------------------------------------------
+const WRAPPER_HEADS = new Set([
+    "env",
+    "command",
+    "nice",
+    "timeout",
+    "sudo",
+    "xargs",
+    "nohup",
+]);
+/**
+ * Per-wrapper short/long options that consume a SEPARATE following token as their
+ * value (so the value is not mistaken for the wrapped command). Attached forms
+ * (`-n5`, `--kill-after=5`) are single tokens and need no entry.
+ */
+const WRAPPER_VALUE_OPTS = {
+    env: new Set(["-u", "--unset", "-C", "--chdir", "-S", "--split-string"]),
+    command: new Set(),
+    nice: new Set(["-n", "--adjustment"]),
+    timeout: new Set(["-s", "--signal", "-k", "--kill-after"]),
+    sudo: new Set([
+        "-u",
+        "--user",
+        "-g",
+        "--group",
+        "-p",
+        "--prompt",
+        "-C",
+        "--close-from",
+        "-h",
+        "--host",
+        "-r",
+        "--role",
+        "-t",
+        "--type",
+        "-U",
+        "--other-user",
+        "-R",
+        "--chroot",
+        "-D",
+        "--chdir",
+    ]),
+    xargs: new Set([
+        "-I",
+        "-i",
+        "--replace",
+        "-n",
+        "--max-args",
+        "-P",
+        "--max-procs",
+        "-d",
+        "--delimiter",
+        "-E",
+        "-e",
+        "--eof",
+        "-s",
+        "--max-chars",
+        "-L",
+        "-l",
+        "--max-lines",
+        "-a",
+        "--arg-file",
+    ]),
+    nohup: new Set(),
+};
+/** Count of leading NON-option positionals a wrapper consumes before the command (timeout DURATION). */
+const WRAPPER_SKIP_POSITIONALS = {
+    timeout: 1,
+};
+/** True iff a normalized word is a `NAME=value` env-assignment (used by `env`). */
+function isAssignmentWord(word) {
+    return /^[A-Za-z_][A-Za-z0-9_]*=/.test(word);
+}
+/** Split a `NAME=value` word into its name and value. */
+function splitAssignmentWord(word) {
+    const eq = word.indexOf("=");
+    return [word.slice(0, eq), word.slice(eq + 1)];
+}
+/**
+ * Resolve a wrapped command through one or more wrapper layers. Given a leaf's
+ * full normalized argv (`[head, ...args]`), returns the effective argv of the
+ * REAL command plus any `NAME=value` words an `env` wrapper consumed (so the
+ * caller can fold them into the leaf's assignment map). If the head is not a
+ * wrapper, or the wrapper has no following command, the argv is returned
+ * unchanged with an empty assignment set.
+ */
+function stripWrappers(argv) {
+    const envAssigns = new Map();
+    let cur = argv;
+    for (let guard = 0; guard < 8; guard++) {
+        const head = cur[0];
+        if (head === undefined || !WRAPPER_HEADS.has(head))
+            break;
+        const valueOpts = WRAPPER_VALUE_OPTS[head] ?? new Set();
+        let positionalsToSkip = WRAPPER_SKIP_POSITIONALS[head] ?? 0;
+        let i = 1; // start after the wrapper head
+        let ended = false;
+        for (; i < cur.length; i++) {
+            const a = cur[i];
+            if (a === undefined)
+                break;
+            if (a === "--") {
+                i++;
+                ended = true;
+                break;
+            }
+            if (a.length > 1 && a.startsWith("-")) {
+                if (valueOpts.has(a))
+                    i++; // skip this option's separate value too
+                continue;
+            }
+            if (head === "env" && isAssignmentWord(a)) {
+                const [name, value] = splitAssignmentWord(a);
+                envAssigns.set(name, value);
+                continue;
+            }
+            if (positionalsToSkip > 0) {
+                positionalsToSkip--;
+                continue;
+            }
+            break; // cur[i] is the real command head
+        }
+        void ended;
+        if (i >= cur.length)
+            break; // wrapper with no following command → keep as-is
+        const next = cur.slice(i);
+        if (next.length === cur.length)
+            break; // no progress → stop
+        cur = next;
+    }
+    return { argv: cur, envAssigns };
+}
+/**
+ * Extract every simple command as a {@link NormalizedLeaf} — the operation-level
+ * twin of {@link leafCommands}. Same AST-backed structural coverage (a leaf nested
+ * in a pipeline / `&&` / subshell is still found), but each word is quote-unwrapped
+ * and $HOME-canonicalized, the head is reduced to its backslash-stripped basename,
+ * and flags are expanded to short+long canonical forms. A matcher built on this
+ * compares against the OPERATION rather than the surface tokens, so it is robust
+ * to quoting, interpreter path, backslash escaping, flag aliasing, and $HOME/~.
+ *
+ * Purely additive: reuses the same mvdan-sh parse, changes nothing above. Parse
+ * failure → []. A leaf with a dynamic head is skipped (can't be normalized).
+ */
+function leafCommandsNormalized(command) {
+    let file;
+    try {
+        file = sh.syntax.NewParser().Parse(command, "cmd.sh");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    sh.syntax.Walk(file, (node) => {
+        const leaf = normalizeCallExpr(node);
+        if (leaf)
+            out.push(leaf);
+        return true;
+    });
+    return out;
+}
+/** Collect a CallExpr's leading `NAME=value` env-assignments into a name→value map. */
+function collectAssigns(node) {
+    const assigns = new Map();
+    for (const a of node.Assigns ?? []) {
+        const name = a.Name?.Value;
+        if (!name)
+            continue;
+        // A naked `NAME=` has no Value word → empty string; a dynamic RHS → null.
+        const value = a.Value ? normalizeParts(a.Value.Parts) : "";
+        assigns.set(name, value);
+    }
+    return assigns;
+}
+/** Normalize a single CallExpr node to a {@link NormalizedLeaf}, or null if it isn't one / has a dynamic head. */
+function normalizeCallExpr(node) {
+    if (sh.syntax.NodeType(node) !== "CallExpr" || !node.Args?.length)
+        return null;
+    const headRaw = normalizeParts(node.Args[0]?.Parts);
+    if (headRaw === null)
+        return null; // dynamic head → not normalizable
+    const rawHead = normalizeHead(headRaw);
+    const rawArgs = node.Args.slice(1)
+        .map((w) => normalizeParts(w.Parts))
+        .filter((w) => w !== null);
+    // Resolve through any command-wrapper (`env`/`command`/`sudo`/`timeout`/…) so
+    // the leaf reflects the REAL operation, not the wrapper head.
+    const stripped = stripWrappers([rawHead, ...rawArgs]);
+    const head = normalizeHead(stripped.argv[0] ?? rawHead);
+    const args = stripped.argv.slice(1);
+    // Command-level assignments: mvdan leading `CallExpr.Assigns` plus any
+    // `NAME=value` words an `env` wrapper consumed on the way to the real command.
+    const assigns = collectAssigns(node);
+    for (const [k, v] of stripped.envAssigns)
+        assigns.set(k, v);
+    const flags = buildFlags(args);
+    return {
+        head,
+        argv: [head, ...args],
+        args,
+        flags,
+        hasFlag: (...names) => names.some((n) => flags.has(n)),
+        assigns,
+        hasAssign: (...names) => names.some((n) => assigns.has(n)),
+    };
+}
 //# sourceMappingURL=bash-effects.js.map

package/dist/hook.d.ts

@@ -49,4 +49,6 @@ export { defineHook, defineFileGate, definePromptGate, defineStopGate, tool, too
 export type { Decision, HookMode, GateAction, CommandView, PathView, ResponseView, BashToolEvent, FileToolEvent, PromptEvent, StopEvent, ReactEvent, SessionEvent, HookProgram, FileGateHook, PromptGateHook, StopGateHook, InjectHook, ReactHook, AnyHook, DispatchKind, Injection, Reaction, RunReaction, CompiledHookProgram, CompileHookOptions, RawHookEvent, HookProgramOutcome, } from "./core/hook-program.js";
 export { provide, dangerously, defineProvider, provider, } from "./core/hook-providers.js";
 export type { ProviderName, ProviderResults, HookCtx, NeedSpec, InlineProvider, RegisteredProvider, RegisteredRef, ProviderRegistry, } from "./core/hook-providers.js";
+export { leafCommandsNormalized } from "./core/bash-effects.js";
+export type { NormalizedLeaf } from "./core/bash-effects.js";
 //# sourceMappingURL=hook.d.ts.map

package/dist/hook.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.provider = exports.defineProvider = exports.dangerously = exports.provide = exports.HookCompileError = exports.verifyHookStamp = exports.stampHook = exports.checkHookImports = exports.compileHookProgram = exports.hookNeeds = exports.hookRouting = exports.dispatchKind = exports.decisionExitCode = exports.runHookProgram = exports.runReact = exports.runInject = exports.decideStopGate = exports.decidePromptGate = exports.decideFileGate = exports.decideProgram = exports.responseView = exports.nothing = exports.notice = exports.run = exports.defineReact = exports.inject = exports.defineInject = exports.hookMode = exports.gateAction = exports.pathView = exports.commandView = exports.ask = exports.deny = exports.allow = exports.tools = exports.tool = exports.defineStopGate = exports.definePromptGate = exports.defineFileGate = exports.defineHook = void 0;
+exports.leafCommandsNormalized = exports.provider = exports.defineProvider = exports.dangerously = exports.provide = exports.HookCompileError = exports.verifyHookStamp = exports.stampHook = exports.checkHookImports = exports.compileHookProgram = exports.hookNeeds = exports.hookRouting = exports.dispatchKind = exports.decisionExitCode = exports.runHookProgram = exports.runReact = exports.runInject = exports.decideStopGate = exports.decidePromptGate = exports.decideFileGate = exports.decideProgram = exports.responseView = exports.nothing = exports.notice = exports.run = exports.defineReact = exports.inject = exports.defineInject = exports.hookMode = exports.gateAction = exports.pathView = exports.commandView = exports.ask = exports.deny = exports.allow = exports.tools = exports.tool = exports.defineStopGate = exports.definePromptGate = exports.defineFileGate = exports.defineHook = void 0;
 /**
  * `vigiles/hook` — the **closed vocabulary** for authoring a compiled hook.
  *
@@ -95,4 +95,8 @@ Object.defineProperty(exports, "provide", { enumerable: true, get: function () {
 Object.defineProperty(exports, "dangerously", { enumerable: true, get: function () { return hook_providers_js_1.dangerously; } });
 Object.defineProperty(exports, "defineProvider", { enumerable: true, get: function () { return hook_providers_js_1.defineProvider; } });
 Object.defineProperty(exports, "provider", { enumerable: true, get: function () { return hook_providers_js_1.provider; } });
+// Operation-normalized leaf extraction — the robust matching primitive a
+// hardened guard is built on (see examples/harness/safe-bash-guard-v2.mjs).
+var bash_effects_js_1 = require("./core/bash-effects.js");
+Object.defineProperty(exports, "leafCommandsNormalized", { enumerable: true, get: function () { return bash_effects_js_1.leafCommandsNormalized; } });
 //# sourceMappingURL=hook.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "12.4.0",
+  "version": "12.6.0",
   "description": "Lint & test the harness your AI agent runs on — verify the references in your CLAUDE.md / AGENTS.md and test that your hooks and skills actually work.",
   "keywords": [
     "claude-code",