@agenttrail/guardrails 0.1.0 → 0.2.0

package/dist/guardrails.d.cts

@@ -6,7 +6,7 @@ import 'zod';
  * The eleven packs, and the order they are presented in.
  *
  * These ids are authoritative and shared with the rules authored against them,
- * and with the guard's `config.json` `enabledPacks`. Renaming one of these is a
+ * and with the guard's `config.json` `disabledPacks`. Renaming one of these is a
  * breaking change to a user's config file.
  *
  * Working-tree destruction leads: destructive git commands are the most frequently
@@ -98,11 +98,18 @@ declare function isPack(value: string): value is Pack;
  *
  * ── Honest coverage limits ──────────────────────────────────────────────────
  *
- * - The carrier must be the first word, apart from a single leading `sudo`, which
- *   is tolerated because it changes privilege rather than semantics — `sudo grep`
- *   still searches, and no rule triggers on it (`ps.sudo-write` fires on
- *   `sudo tee|dd|cp|mv|rm|ln|install|chown|chmod|sh`, none of them a carrier).
- *   A RUNNER prefix is not tolerated: `pnpm exec rg …`, `npx …` and
+ * - The carrier need not be the first word: it may follow, and be followed by, up
+ *   to two QUIET segments — read-only inspection commands (`wc`, `cat`, `head`,
+ *   `tail`, `ls`, `grep`/family, `rg`) separated by `;`, `&&`, `||` or a pipe — so
+ *   `wc -l < log; echo "…rm -rf /…"; grep -c x log` is exempt. That is sound
+ *   because a quiet segment provably neither writes nor executes: `sort` (`-o`,
+ *   `--compress-program`), `find` (`-exec`), `awk`/`sed`, `tee`/`dd` and `git`
+ *   (`push`/`reset`) are NOT quiet, so `git commit -m "x" && rm -rf /`,
+ *   `echo "…" | bash` and `sort … ; echo …` all still deny. A quiet segment carries
+ *   no quote, so it cannot hide a mention; the mention is in the CARRIER. A single
+ *   leading `sudo` before the CARRIER is still tolerated (it changes privilege, not
+ *   meaning; `ps.sudo-write` fires on `sudo tee|dd|cp|mv|rm|ln|install|chown|chmod|sh`,
+ *   none a carrier). A RUNNER prefix is not tolerated: `pnpm exec rg …`, `npx …` and
  *   `xargs -0 grep …` are not exempt, because "some program eventually execs a
  *   search" is a much weaker claim than "this command is a search".
  * - At most four quoted arguments are recognised. A fifth is not exempt.
@@ -130,6 +137,27 @@ declare function isPack(value: string): value is Pack;
  * its own trigger verb.
  */
 
+/**
+ * The `label` glob for a rule that reads a COMMAND: the two shells plus any MCP tool.
+ *
+ * A command-channel rule describes a shape — `git push --force`, `rm -rf /` — and
+ * that shape reaches the guard on more than one tool. Claude Code's own hooks route
+ * `Bash`, `PowerShell` AND `mcp__*` to the guard, and the MCP channel carries the
+ * serialized tool input as the same `detail` text every command matcher reads. A
+ * rule pinned to `{Bash,PowerShell}` alone silently ignores the MCP channel, so an
+ * MCP server that runs shell commands is unguarded. This glob widens the label to
+ * the MCP tools as well, and is referenced rather than copied so the set cannot
+ * drift rule to rule.
+ *
+ * `mcp__*` matches the WHOLE label (picomatch matches the entire tool name), so it
+ * catches any `mcp__<server>__<tool>` — including Cursor's `mcp__cursor__*` — and
+ * nothing else. It does NOT widen the `none_of` exemptions, which stay anchored to
+ * the shell: a quoted MENTION is a shell shape, and an MCP tool's serialized JSON
+ * does not start with a carrier verb, so a command shape inside an MCP payload is
+ * matched, not exempted. Whether that shape is an execution or only a field named
+ * like one is a limit the README states, not one this glob can tell apart.
+ */
+declare const SHELL_AND_MCP = "{Bash,PowerShell,mcp__*}";
 /**
  * A read-only search: `grep`, `rg`, `ag`, `ack`, PowerShell's `Select-String`.
  *
@@ -175,6 +203,50 @@ declare const HTTP_BODY_MENTION: MatchCondition;
  * the subset out longhand so the omission is visible at the call site.
  */
 declare const QUOTED_MENTION: readonly MatchCondition[];
+/**
+ * Zero or more global flags sitting between a command and its subcommand.
+ *
+ * A command-channel rule that pins a tool to its subcommand CONTIGUOUSLY —
+ * `git\s+reset`, `aws\s+s3`, `kubectl\s+delete`, `docker\s+volume` — is defeated
+ * by a global flag slipped in between them. The subcommand no longer follows the
+ * tool, so the rule stops matching and the action runs unguarded:
+ *
+ *     git -C /repo reset --hard        git --no-pager …   git -c core.x=y …
+ *     git --work-tree=/x …             aws --profile p …  aws --region r …
+ *     kubectl -n prod delete …         docker --context c …   docker -H … …
+ *     terraform -chdir=/x apply …      helm -n ns …       npm --silent …
+ *
+ * This constant is the ONE shared fix for that whole class, referenced rather
+ * than copied so a rule cannot drift to a weaker spelling. It is spliced in RIGHT
+ * AFTER the tool name and BEFORE the `\s+` that precedes the subcommand:
+ * `\\bgit${LEADING_FLAGS}\\s+reset\\s+--hard\\b`. Empty (zero flags) it collapses
+ * back to the original `tool\s+subcommand`, so the plain form still matches.
+ *
+ * The forms it tolerates, each as one unit that may repeat:
+ *   `--no-pager` / `--silent`         a bare long flag
+ *   `-C /repo` / `-n prod`            a short flag with a separate value
+ *   `-c core.pager=cat`               a short flag whose value carries `=`
+ *   `--work-tree=/x` / `-chdir=/x`    a flag with an attached `=value`
+ *   `--profile prod` / `--context c`  a long flag with a separate value
+ *
+ * ── Bounded on purpose ───────────────────────────────────────────────────────
+ *
+ * Every quantifier is bounded — the run repeats at most a handful of times and
+ * each token has a capped length — so the fragment is linear and cannot backtrack
+ * catastrophically. A regex whose repetition nests an unbounded quantifier is
+ * rejected at parse time; this stays well inside that limit and the length cap.
+ *
+ * ── What it does NOT cover ───────────────────────────────────────────────────
+ *
+ * It reads flag SHAPE, not meaning: it cannot tell a flag that consumes the next
+ * word as its value from the subcommand itself, so a value token is required not
+ * to begin with `-`, which lets a bare flag followed by the subcommand still
+ * resolve to the subcommand. It does not cross a shell metacharacter, and it does
+ * not read a flag that itself runs another program. An absolute tool path
+ * (`/usr/bin/git`) already matches through the `\b` anchor every tool carries;
+ * this fragment only closes the gap between the tool and its subcommand.
+ */
+declare const LEADING_FLAGS = "(?:\\s+-{1,2}[A-Za-z][\\w-]{0,24}(?:=\\S{1,40})?(?:\\s+[^-\\s]\\S{0,40})?){0,6}";
 
 /**
  * Fixture constructors — three one-line functions, and no zod.
@@ -213,6 +285,20 @@ declare function pwsh(command: string): Fixture;
  * it only documents the case being proven.
  */
 declare function file(filePath: string, tool?: string): Fixture;
+/**
+ * A fixture on the command channel, from an MCP tool.
+ *
+ * The guard hands the engine an MCP call's serialized `tool_input` as the `detail`
+ * text (`JSON.stringify(input)`), so a fixture mirrors that: the `input` object is
+ * serialized and its JSON becomes the command. `tool` defaults to a generic MCP
+ * name; the widened `{Bash,PowerShell,mcp__*}` label matches any `mcp__*`.
+ *
+ * The point is to prove a command SHAPE carried by an MCP server still fires the
+ * rule (`{ command: "rm -rf /" }`), and that a serialized MENTION is NOT exempted:
+ * the `none_of` carriers are anchored to the shell, and JSON does not start with a
+ * carrier verb.
+ */
+declare function mcp(input: Record<string, unknown>, tool?: string): Fixture;
 /** `git commit -m "…"` — the carrier behind the three hard denies. */
 declare function mentionInCommit(text: string): Fixture;
 /** `grep -rn "…" docs/` — searching for the words is not executing them. */
@@ -276,7 +362,7 @@ declare function mentions(text: string): Fixture[];
  * Pinned to `package.json`'s `version` by `__tests__/stamp.test.ts` — this is a copy
  * of that value, not an independent one, and the test is what makes the copy safe.
  */
-declare const CATALOG_VERSION = "0.1.0";
+declare const CATALOG_VERSION = "0.2.0";
 /**
  * When the rules in this catalog reached their current state, as an ISO-8601
  * instant. The question it answers is not "when did this reach a registry" but "how
@@ -286,7 +372,7 @@ declare const CATALOG_VERSION = "0.1.0";
  * the guard handles a missing date, and a wrong date that looks right is worse than
  * a missing one.
  */
-declare const CATALOG_PUBLISHED_AT = "2026-09-15T07:13:18Z";
+declare const CATALOG_PUBLISHED_AT = "2026-09-18T13:00:33Z";
 
 /**
  * The corpus itself — rules only, and **deliberately free of zod**.
@@ -337,4 +423,4 @@ declare function getRule(id: string): Rule | undefined;
 /** Every rule in one pack, in authored order. */
 declare function rulesForPack(pack: Pack): readonly Rule[];
 
-export { CATALOG_PUBLISHED_AT, CATALOG_VERSION, Fixture, GIT_TEXT_MENTION, HTTP_BODY_MENTION, MatchCondition, PACKS, PRINT_MENTION, type Pack, QUOTED_MENTION, RULES, RULES_BY_PACK, Rule, SEARCH_MENTION, bash, file, getRule, isPack, mentionInCommit, mentionInEcho, mentionInPost, mentionInSearch, mentions, pwsh, rulesForPack };
+export { CATALOG_PUBLISHED_AT, CATALOG_VERSION, Fixture, GIT_TEXT_MENTION, HTTP_BODY_MENTION, LEADING_FLAGS, MatchCondition, PACKS, PRINT_MENTION, type Pack, QUOTED_MENTION, RULES, RULES_BY_PACK, Rule, SEARCH_MENTION, SHELL_AND_MCP, bash, file, getRule, isPack, mcp, mentionInCommit, mentionInEcho, mentionInPost, mentionInSearch, mentions, pwsh, rulesForPack };

package/dist/guardrails.d.ts

@@ -6,7 +6,7 @@ import 'zod';
  * The eleven packs, and the order they are presented in.
  *
  * These ids are authoritative and shared with the rules authored against them,
- * and with the guard's `config.json` `enabledPacks`. Renaming one of these is a
+ * and with the guard's `config.json` `disabledPacks`. Renaming one of these is a
  * breaking change to a user's config file.
  *
  * Working-tree destruction leads: destructive git commands are the most frequently
@@ -98,11 +98,18 @@ declare function isPack(value: string): value is Pack;
  *
  * ── Honest coverage limits ──────────────────────────────────────────────────
  *
- * - The carrier must be the first word, apart from a single leading `sudo`, which
- *   is tolerated because it changes privilege rather than semantics — `sudo grep`
- *   still searches, and no rule triggers on it (`ps.sudo-write` fires on
- *   `sudo tee|dd|cp|mv|rm|ln|install|chown|chmod|sh`, none of them a carrier).
- *   A RUNNER prefix is not tolerated: `pnpm exec rg …`, `npx …` and
+ * - The carrier need not be the first word: it may follow, and be followed by, up
+ *   to two QUIET segments — read-only inspection commands (`wc`, `cat`, `head`,
+ *   `tail`, `ls`, `grep`/family, `rg`) separated by `;`, `&&`, `||` or a pipe — so
+ *   `wc -l < log; echo "…rm -rf /…"; grep -c x log` is exempt. That is sound
+ *   because a quiet segment provably neither writes nor executes: `sort` (`-o`,
+ *   `--compress-program`), `find` (`-exec`), `awk`/`sed`, `tee`/`dd` and `git`
+ *   (`push`/`reset`) are NOT quiet, so `git commit -m "x" && rm -rf /`,
+ *   `echo "…" | bash` and `sort … ; echo …` all still deny. A quiet segment carries
+ *   no quote, so it cannot hide a mention; the mention is in the CARRIER. A single
+ *   leading `sudo` before the CARRIER is still tolerated (it changes privilege, not
+ *   meaning; `ps.sudo-write` fires on `sudo tee|dd|cp|mv|rm|ln|install|chown|chmod|sh`,
+ *   none a carrier). A RUNNER prefix is not tolerated: `pnpm exec rg …`, `npx …` and
  *   `xargs -0 grep …` are not exempt, because "some program eventually execs a
  *   search" is a much weaker claim than "this command is a search".
  * - At most four quoted arguments are recognised. A fifth is not exempt.
@@ -130,6 +137,27 @@ declare function isPack(value: string): value is Pack;
  * its own trigger verb.
  */
 
+/**
+ * The `label` glob for a rule that reads a COMMAND: the two shells plus any MCP tool.
+ *
+ * A command-channel rule describes a shape — `git push --force`, `rm -rf /` — and
+ * that shape reaches the guard on more than one tool. Claude Code's own hooks route
+ * `Bash`, `PowerShell` AND `mcp__*` to the guard, and the MCP channel carries the
+ * serialized tool input as the same `detail` text every command matcher reads. A
+ * rule pinned to `{Bash,PowerShell}` alone silently ignores the MCP channel, so an
+ * MCP server that runs shell commands is unguarded. This glob widens the label to
+ * the MCP tools as well, and is referenced rather than copied so the set cannot
+ * drift rule to rule.
+ *
+ * `mcp__*` matches the WHOLE label (picomatch matches the entire tool name), so it
+ * catches any `mcp__<server>__<tool>` — including Cursor's `mcp__cursor__*` — and
+ * nothing else. It does NOT widen the `none_of` exemptions, which stay anchored to
+ * the shell: a quoted MENTION is a shell shape, and an MCP tool's serialized JSON
+ * does not start with a carrier verb, so a command shape inside an MCP payload is
+ * matched, not exempted. Whether that shape is an execution or only a field named
+ * like one is a limit the README states, not one this glob can tell apart.
+ */
+declare const SHELL_AND_MCP = "{Bash,PowerShell,mcp__*}";
 /**
  * A read-only search: `grep`, `rg`, `ag`, `ack`, PowerShell's `Select-String`.
  *
@@ -175,6 +203,50 @@ declare const HTTP_BODY_MENTION: MatchCondition;
  * the subset out longhand so the omission is visible at the call site.
  */
 declare const QUOTED_MENTION: readonly MatchCondition[];
+/**
+ * Zero or more global flags sitting between a command and its subcommand.
+ *
+ * A command-channel rule that pins a tool to its subcommand CONTIGUOUSLY —
+ * `git\s+reset`, `aws\s+s3`, `kubectl\s+delete`, `docker\s+volume` — is defeated
+ * by a global flag slipped in between them. The subcommand no longer follows the
+ * tool, so the rule stops matching and the action runs unguarded:
+ *
+ *     git -C /repo reset --hard        git --no-pager …   git -c core.x=y …
+ *     git --work-tree=/x …             aws --profile p …  aws --region r …
+ *     kubectl -n prod delete …         docker --context c …   docker -H … …
+ *     terraform -chdir=/x apply …      helm -n ns …       npm --silent …
+ *
+ * This constant is the ONE shared fix for that whole class, referenced rather
+ * than copied so a rule cannot drift to a weaker spelling. It is spliced in RIGHT
+ * AFTER the tool name and BEFORE the `\s+` that precedes the subcommand:
+ * `\\bgit${LEADING_FLAGS}\\s+reset\\s+--hard\\b`. Empty (zero flags) it collapses
+ * back to the original `tool\s+subcommand`, so the plain form still matches.
+ *
+ * The forms it tolerates, each as one unit that may repeat:
+ *   `--no-pager` / `--silent`         a bare long flag
+ *   `-C /repo` / `-n prod`            a short flag with a separate value
+ *   `-c core.pager=cat`               a short flag whose value carries `=`
+ *   `--work-tree=/x` / `-chdir=/x`    a flag with an attached `=value`
+ *   `--profile prod` / `--context c`  a long flag with a separate value
+ *
+ * ── Bounded on purpose ───────────────────────────────────────────────────────
+ *
+ * Every quantifier is bounded — the run repeats at most a handful of times and
+ * each token has a capped length — so the fragment is linear and cannot backtrack
+ * catastrophically. A regex whose repetition nests an unbounded quantifier is
+ * rejected at parse time; this stays well inside that limit and the length cap.
+ *
+ * ── What it does NOT cover ───────────────────────────────────────────────────
+ *
+ * It reads flag SHAPE, not meaning: it cannot tell a flag that consumes the next
+ * word as its value from the subcommand itself, so a value token is required not
+ * to begin with `-`, which lets a bare flag followed by the subcommand still
+ * resolve to the subcommand. It does not cross a shell metacharacter, and it does
+ * not read a flag that itself runs another program. An absolute tool path
+ * (`/usr/bin/git`) already matches through the `\b` anchor every tool carries;
+ * this fragment only closes the gap between the tool and its subcommand.
+ */
+declare const LEADING_FLAGS = "(?:\\s+-{1,2}[A-Za-z][\\w-]{0,24}(?:=\\S{1,40})?(?:\\s+[^-\\s]\\S{0,40})?){0,6}";
 
 /**
  * Fixture constructors — three one-line functions, and no zod.
@@ -213,6 +285,20 @@ declare function pwsh(command: string): Fixture;
  * it only documents the case being proven.
  */
 declare function file(filePath: string, tool?: string): Fixture;
+/**
+ * A fixture on the command channel, from an MCP tool.
+ *
+ * The guard hands the engine an MCP call's serialized `tool_input` as the `detail`
+ * text (`JSON.stringify(input)`), so a fixture mirrors that: the `input` object is
+ * serialized and its JSON becomes the command. `tool` defaults to a generic MCP
+ * name; the widened `{Bash,PowerShell,mcp__*}` label matches any `mcp__*`.
+ *
+ * The point is to prove a command SHAPE carried by an MCP server still fires the
+ * rule (`{ command: "rm -rf /" }`), and that a serialized MENTION is NOT exempted:
+ * the `none_of` carriers are anchored to the shell, and JSON does not start with a
+ * carrier verb.
+ */
+declare function mcp(input: Record<string, unknown>, tool?: string): Fixture;
 /** `git commit -m "…"` — the carrier behind the three hard denies. */
 declare function mentionInCommit(text: string): Fixture;
 /** `grep -rn "…" docs/` — searching for the words is not executing them. */
@@ -276,7 +362,7 @@ declare function mentions(text: string): Fixture[];
  * Pinned to `package.json`'s `version` by `__tests__/stamp.test.ts` — this is a copy
  * of that value, not an independent one, and the test is what makes the copy safe.
  */
-declare const CATALOG_VERSION = "0.1.0";
+declare const CATALOG_VERSION = "0.2.0";
 /**
  * When the rules in this catalog reached their current state, as an ISO-8601
  * instant. The question it answers is not "when did this reach a registry" but "how
@@ -286,7 +372,7 @@ declare const CATALOG_VERSION = "0.1.0";
  * the guard handles a missing date, and a wrong date that looks right is worse than
  * a missing one.
  */
-declare const CATALOG_PUBLISHED_AT = "2026-09-15T07:13:18Z";
+declare const CATALOG_PUBLISHED_AT = "2026-09-18T13:00:33Z";
 
 /**
  * The corpus itself — rules only, and **deliberately free of zod**.
@@ -337,4 +423,4 @@ declare function getRule(id: string): Rule | undefined;
 /** Every rule in one pack, in authored order. */
 declare function rulesForPack(pack: Pack): readonly Rule[];
 
-export { CATALOG_PUBLISHED_AT, CATALOG_VERSION, Fixture, GIT_TEXT_MENTION, HTTP_BODY_MENTION, MatchCondition, PACKS, PRINT_MENTION, type Pack, QUOTED_MENTION, RULES, RULES_BY_PACK, Rule, SEARCH_MENTION, bash, file, getRule, isPack, mentionInCommit, mentionInEcho, mentionInPost, mentionInSearch, mentions, pwsh, rulesForPack };
+export { CATALOG_PUBLISHED_AT, CATALOG_VERSION, Fixture, GIT_TEXT_MENTION, HTTP_BODY_MENTION, LEADING_FLAGS, MatchCondition, PACKS, PRINT_MENTION, type Pack, QUOTED_MENTION, RULES, RULES_BY_PACK, Rule, SEARCH_MENTION, SHELL_AND_MCP, bash, file, getRule, isPack, mcp, mentionInCommit, mentionInEcho, mentionInPost, mentionInSearch, mentions, pwsh, rulesForPack };

package/dist/guardrails.js

@@ -3,16 +3,19 @@ import {
   CATALOG_VERSION,
   GIT_TEXT_MENTION,
   HTTP_BODY_MENTION,
+  LEADING_FLAGS,
   PACKS,
   PRINT_MENTION,
   QUOTED_MENTION,
   RULES,
   RULES_BY_PACK,
   SEARCH_MENTION,
+  SHELL_AND_MCP,
   bash,
   file,
   getRule,
   isPack,
+  mcp,
   mentionInCommit,
   mentionInEcho,
   mentionInPost,
@@ -20,22 +23,25 @@ import {
   mentions,
   pwsh,
   rulesForPack
-} from "./chunk-DBB7HO4T.js";
+} from "./chunk-3NDBRXP3.js";
 export {
   CATALOG_PUBLISHED_AT,
   CATALOG_VERSION,
   GIT_TEXT_MENTION,
   HTTP_BODY_MENTION,
+  LEADING_FLAGS,
   PACKS,
   PRINT_MENTION,
   QUOTED_MENTION,
   RULES,
   RULES_BY_PACK,
   SEARCH_MENTION,
+  SHELL_AND_MCP,
   bash,
   file,
   getRule,
   isPack,
+  mcp,
   mentionInCommit,
   mentionInEcho,
   mentionInPost,