vigiles 12.4.0 → 12.5.0

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

@@ -50,4 +50,35 @@ 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;
+}
+/**
+ * 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,136 @@ 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;
+}
+/**
+ * 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;
+}
+/** 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 head = normalizeHead(headRaw);
+    const args = node.Args.slice(1)
+        .map((w) => normalizeParts(w.Parts))
+        .filter((w) => w !== null);
+    const flags = buildFlags(args);
+    return {
+        head,
+        argv: [head, ...args],
+        args,
+        flags,
+        hasFlag: (...names) => names.some((n) => flags.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.5.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",