npm - @nebutra/execution-policy - Versions diffs - 0.1.0 - Mend

@nebutra/execution-policy 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/.turbo/turbo-build.log +17 -0
package/.turbo/turbo-test.log +14 -0
package/.turbo/turbo-typecheck.log +4 -0
package/LICENSE +676 -0
package/dist/index.d.ts +92 -0
package/dist/index.js +131 -0
package/dist/index.js.map +1 -0
package/package.json +54 -0
package/src/index.test.ts +68 -0
package/src/index.ts +245 -0
package/tsconfig.json +12 -0
package/tsup.config.ts +10 -0

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,92 @@
+/**
+ * Permission ruleset evaluator.
+ *
+ * A small, pure, stateless re-expression of a two-dimensional wildcard
+ * permission model plus a bash-command-prefix extractor. No global state,
+ * no I/O, no mutation of inputs — every function is referentially transparent.
+ *
+ * The model has two independent dimensions per rule:
+ *   - `permission` — the capability namespace (e.g. "bash", "edit", "net")
+ *   - `pattern`    — the concrete subject within that namespace
+ * A rule applies only when BOTH dimensions match the query via {@link wildcardMatch}.
+ */
+/** The decision a rule yields. Unknown queries fail safe to "ask". */
+type Action = "allow" | "deny" | "ask";
+/** A single permission rule. Both dimensions are matched as wildcard globs. */
+interface Rule {
+    permission: string;
+    pattern: string;
+    action: Action;
+}
+/** An ordered list of rules. Earlier rules take precedence. */
+type Ruleset = Rule[];
+/**
+ * Anchored full-string glob matcher.
+ *
+ * Semantics:
+ *   - `*` matches any run of characters, including the empty run.
+ *   - `?` matches exactly one character.
+ *   - Every other character is matched literally (regex metacharacters in
+ *     `pattern` carry no special meaning).
+ *   - The match is anchored: the entire `str` must be consumed.
+ *
+ * Special rule (ported faithfully): if `pattern` ends with `" *"` (a single
+ * space immediately followed by `*`), that trailing ` *` is OPTIONAL. The
+ * pattern then matches both `"<head> <rest>"` and exactly `"<head>"` with
+ * nothing after it. For example `"git *"` matches `"git"` and `"git status"`.
+ *
+ * Implemented with a backtracking two-pointer scan whose `*` handling uses a
+ * single saved restart position, giving O(|str| * |pattern|) worst case with
+ * no catastrophic blow-up.
+ */
+declare function wildcardMatch(str: string, pattern: string): boolean;
+/**
+ * Resolve a permission query against one or more rulesets.
+ *
+ * Rulesets are concatenated in argument order (no mutation) and scanned
+ * front-to-back. The FIRST rule whose `permission` and `pattern` both match
+ * the query (via {@link wildcardMatch}) is returned. If no rule matches, a
+ * fail-safe default is returned: the queried permission/pattern with action
+ * `"ask"` (unknown → ask, never silently allow).
+ */
+declare function evaluate(permission: string, pattern: string, ...rulesets: Ruleset[]): Rule;
+/**
+ * Built-in command arity table. Maps a (possibly multi-word) command prefix
+ * to the number of leading tokens that constitute its "human-understandable
+ * command" for permission matching. Longest matching prefix wins.
+ *
+ * Frozen so the shared default cannot be mutated by callers.
+ */
+declare const BUILTIN_ARITY: Readonly<Record<string, number>>;
+/**
+ * Extract the human-understandable command from already-split, flag-free
+ * shell tokens.
+ *
+ * Strategy: try the longest prefix first. For `len` from `tokens.length` down
+ * to 1, if `tokens.slice(0, len).join(" ")` is a key in the (merged) arity
+ * table, return `tokens.slice(0, arity[thatPrefix])`. If the tokens are empty,
+ * return `[]`. Otherwise default to the first token only.
+ *
+ * `arity` is shallow-merged OVER the built-in table; neither the caller's
+ * object nor the built-in table is mutated.
+ */
+declare function commandPrefix(tokens: string[], arity?: Record<string, number> | undefined): string[];
+/**
+ * Derive the `pattern` to feed {@link evaluate} for a bash permission.
+ *
+ * Splits `command` on arbitrary whitespace, drops tokens that begin with `-`
+ * (flags are not conceptually part of the command identity), applies
+ * {@link commandPrefix}, and joins the result with single spaces.
+ */
+declare function commandPermissionKey(command: string): string;
+type ShellApprovalMode = "always" | "once_per_session" | "never";
+interface ShellApprovalRule {
+    readonly match: string | RegExp;
+    readonly requireApproval: ShellApprovalMode;
+    readonly reason: string;
+}
+declare const DEFAULT_SHELL_APPROVAL_RULES: readonly ShellApprovalRule[];
+declare function matchesShellApprovalRule(command: string, rule: ShellApprovalRule): boolean;
+declare function shellApprovalRequired(command: string, rules?: readonly ShellApprovalRule[]): ShellApprovalRule | null;
+export { type Action, BUILTIN_ARITY, DEFAULT_SHELL_APPROVAL_RULES, type Rule, type Ruleset, type ShellApprovalMode, type ShellApprovalRule, commandPermissionKey, commandPrefix, evaluate, matchesShellApprovalRule, shellApprovalRequired, wildcardMatch };

package/dist/index.js ADDED Viewed

@@ -0,0 +1,131 @@
+// src/index.ts
+function wildcardMatch(str, pattern) {
+  if (isOptionalTrailingStar(pattern)) {
+    const head = pattern.slice(0, -2);
+    if (globMatch(str, head)) {
+      return true;
+    }
+    return globMatch(str, pattern);
+  }
+  return globMatch(str, pattern);
+}
+function isOptionalTrailingStar(pattern) {
+  return pattern.length >= 2 && pattern.endsWith(" *");
+}
+function globMatch(str, pattern) {
+  let s = 0;
+  let p = 0;
+  let starP = -1;
+  let starS = 0;
+  while (s < str.length) {
+    const pc = p < pattern.length ? pattern[p] : void 0;
+    if (pc === "*") {
+      starP = p;
+      starS = s;
+      p += 1;
+    } else if (pc === "?" || pc === str[s]) {
+      p += 1;
+      s += 1;
+    } else if (starP !== -1) {
+      p = starP + 1;
+      starS += 1;
+      s = starS;
+    } else {
+      return false;
+    }
+  }
+  while (p < pattern.length && pattern[p] === "*") {
+    p += 1;
+  }
+  return p === pattern.length;
+}
+function evaluate(permission, pattern, ...rulesets) {
+  for (const ruleset of rulesets) {
+    for (const rule of ruleset) {
+      if (wildcardMatch(permission, rule.permission) && wildcardMatch(pattern, rule.pattern)) {
+        return rule;
+      }
+    }
+  }
+  return { permission, pattern: "*", action: "ask" };
+}
+var BUILTIN_ARITY = Object.freeze({
+  git: 2,
+  npm: 2,
+  "npm run": 3,
+  docker: 2,
+  kubectl: 2,
+  cargo: 2,
+  pnpm: 2,
+  "pnpm run": 3,
+  yarn: 2,
+  "yarn run": 3,
+  go: 2,
+  ls: 1,
+  cat: 1,
+  cd: 1,
+  rm: 1,
+  cp: 1,
+  mv: 1,
+  mkdir: 1,
+  echo: 1,
+  grep: 1,
+  python: 1,
+  node: 1
+});
+function commandPrefix(tokens, arity) {
+  if (tokens.length === 0) {
+    return [];
+  }
+  const table = { ...BUILTIN_ARITY, ...arity ?? {} };
+  for (let len = tokens.length; len >= 1; len -= 1) {
+    const prefixKey = tokens.slice(0, len).join(" ");
+    const take = table[prefixKey];
+    if (take !== void 0) {
+      return tokens.slice(0, Math.min(take, tokens.length));
+    }
+  }
+  return tokens.slice(0, 1);
+}
+function commandPermissionKey(command) {
+  const tokens = command.split(/\s+/).filter((token) => token.length > 0 && !token.startsWith("-"));
+  return commandPrefix(tokens).join(" ");
+}
+var DEFAULT_SHELL_APPROVAL_RULES = Object.freeze([
+  { match: /^rm\s+-rf\b/, requireApproval: "always", reason: "destructive recursive removal" },
+  {
+    match: /\b(format|mkfs)\b/,
+    requireApproval: "always",
+    reason: "destructive filesystem operation"
+  },
+  {
+    match: /\bDROP\s+(DATABASE|SCHEMA|TABLE)\b/i,
+    requireApproval: "always",
+    reason: "destructive database operation"
+  },
+  {
+    match: /\b(npm|pnpm|yarn)\s+publish\b/,
+    requireApproval: "always",
+    reason: "package publishing"
+  },
+  { match: /^git\s+push\b/, requireApproval: "once_per_session", reason: "remote git mutation" }
+]);
+function matchesShellApprovalRule(command, rule) {
+  return typeof rule.match === "string" ? command.startsWith(rule.match) : rule.match.test(command);
+}
+function shellApprovalRequired(command, rules = DEFAULT_SHELL_APPROVAL_RULES) {
+  return rules.find(
+    (rule) => rule.requireApproval !== "never" && matchesShellApprovalRule(command, rule)
+  ) ?? null;
+}
+export {
+  BUILTIN_ARITY,
+  DEFAULT_SHELL_APPROVAL_RULES,
+  commandPermissionKey,
+  commandPrefix,
+  evaluate,
+  matchesShellApprovalRule,
+  shellApprovalRequired,
+  wildcardMatch
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Permission ruleset evaluator.\n *\n * A small, pure, stateless re-expression of a two-dimensional wildcard\n * permission model plus a bash-command-prefix extractor. No global state,\n * no I/O, no mutation of inputs — every function is referentially transparent.\n *\n * The model has two independent dimensions per rule:\n * - `permission` — the capability namespace (e.g. \"bash\", \"edit\", \"net\")\n * - `pattern` — the concrete subject within that namespace\n * A rule applies only when BOTH dimensions match the query via {@link wildcardMatch}.\n */\n\n/** The decision a rule yields. Unknown queries fail safe to \"ask\". */\nexport type Action = \"allow\" | \"deny\" | \"ask\";\n\n/** A single permission rule. Both dimensions are matched as wildcard globs. */\nexport interface Rule {\n permission: string;\n pattern: string;\n action: Action;\n}\n\n/** An ordered list of rules. Earlier rules take precedence. */\nexport type Ruleset = Rule[];\n\n/**\n * Anchored full-string glob matcher.\n *\n * Semantics:\n * - `*` matches any run of characters, including the empty run.\n * - `?` matches exactly one character.\n * - Every other character is matched literally (regex metacharacters in\n * `pattern` carry no special meaning).\n * - The match is anchored: the entire `str` must be consumed.\n *\n * Special rule (ported faithfully): if `pattern` ends with `\" *\"` (a single\n * space immediately followed by `*`), that trailing ` *` is OPTIONAL. The\n * pattern then matches both `\"<head> <rest>\"` and exactly `\"<head>\"` with\n * nothing after it. For example `\"git *\"` matches `\"git\"` and `\"git status\"`.\n *\n * Implemented with a backtracking two-pointer scan whose `*` handling uses a\n * single saved restart position, giving O(|str| * |pattern|) worst case with\n * no catastrophic blow-up.\n */\nexport function wildcardMatch(str: string, pattern: string): boolean {\n if (isOptionalTrailingStar(pattern)) {\n const head = pattern.slice(0, -2); // drop the trailing \" *\"\n // Head-only branch: the whole string equals the head, matched as a glob.\n if (globMatch(str, head)) {\n return true;\n }\n // Otherwise the full \"<head> *\" pattern must match (space is consumed).\n return globMatch(str, pattern);\n }\n return globMatch(str, pattern);\n}\n\n/**\n * True when `pattern` ends in a literal space followed by `*`, and that `*`\n * is the final character. A bare `\"*\"` (no preceding space) is NOT treated\n * as the optional-suffix form.\n */\nfunction isOptionalTrailingStar(pattern: string): boolean {\n return pattern.length >= 2 && pattern.endsWith(\" *\");\n}\n\n/**\n * Core anchored glob match using linear-time backtracking. Only `*` can\n * backtrack, and it uses a single restart marker (the classic two-pointer\n * algorithm), so there is no exponential backtracking.\n */\nfunction globMatch(str: string, pattern: string): boolean {\n let s = 0;\n let p = 0;\n let starP = -1;\n let starS = 0;\n\n while (s < str.length) {\n const pc = p < pattern.length ? pattern[p] : undefined;\n if (pc === \"*\") {\n // Record the restart point and tentatively consume zero chars.\n starP = p;\n starS = s;\n p += 1;\n } else if (pc === \"?\" || pc === str[s]) {\n p += 1;\n s += 1;\n } else if (starP !== -1) {\n // Backtrack: let the last `*` swallow one more character.\n p = starP + 1;\n starS += 1;\n s = starS;\n } else {\n return false;\n }\n }\n\n // Consume any trailing `*` segments in the pattern.\n while (p < pattern.length && pattern[p] === \"*\") {\n p += 1;\n }\n\n return p === pattern.length;\n}\n\n/**\n * Resolve a permission query against one or more rulesets.\n *\n * Rulesets are concatenated in argument order (no mutation) and scanned\n * front-to-back. The FIRST rule whose `permission` and `pattern` both match\n * the query (via {@link wildcardMatch}) is returned. If no rule matches, a\n * fail-safe default is returned: the queried permission/pattern with action\n * `\"ask\"` (unknown → ask, never silently allow).\n */\nexport function evaluate(permission: string, pattern: string, ...rulesets: Ruleset[]): Rule {\n for (const ruleset of rulesets) {\n for (const rule of ruleset) {\n if (wildcardMatch(permission, rule.permission) && wildcardMatch(pattern, rule.pattern)) {\n return rule;\n }\n }\n }\n return { permission, pattern: \"*\", action: \"ask\" };\n}\n\n/**\n * Built-in command arity table. Maps a (possibly multi-word) command prefix\n * to the number of leading tokens that constitute its \"human-understandable\n * command\" for permission matching. Longest matching prefix wins.\n *\n * Frozen so the shared default cannot be mutated by callers.\n */\nexport const BUILTIN_ARITY: Readonly<Record<string, number>> = Object.freeze({\n git: 2,\n npm: 2,\n \"npm run\": 3,\n docker: 2,\n kubectl: 2,\n cargo: 2,\n pnpm: 2,\n \"pnpm run\": 3,\n yarn: 2,\n \"yarn run\": 3,\n go: 2,\n ls: 1,\n cat: 1,\n cd: 1,\n rm: 1,\n cp: 1,\n mv: 1,\n mkdir: 1,\n echo: 1,\n grep: 1,\n python: 1,\n node: 1,\n});\n\n/**\n * Extract the human-understandable command from already-split, flag-free\n * shell tokens.\n *\n * Strategy: try the longest prefix first. For `len` from `tokens.length` down\n * to 1, if `tokens.slice(0, len).join(\" \")` is a key in the (merged) arity\n * table, return `tokens.slice(0, arity[thatPrefix])`. If the tokens are empty,\n * return `[]`. Otherwise default to the first token only.\n *\n * `arity` is shallow-merged OVER the built-in table; neither the caller's\n * object nor the built-in table is mutated.\n */\nexport function commandPrefix(\n tokens: string[],\n arity?: Record<string, number> | undefined,\n): string[] {\n if (tokens.length === 0) {\n return [];\n }\n const table: Record<string, number> = { ...BUILTIN_ARITY, ...(arity ?? {}) };\n\n for (let len = tokens.length; len >= 1; len -= 1) {\n const prefixKey = tokens.slice(0, len).join(\" \");\n const take = table[prefixKey];\n if (take !== undefined) {\n // Clamp to the available token count; never expand beyond the input.\n return tokens.slice(0, Math.min(take, tokens.length));\n }\n }\n\n return tokens.slice(0, 1);\n}\n\n/**\n * Derive the `pattern` to feed {@link evaluate} for a bash permission.\n *\n * Splits `command` on arbitrary whitespace, drops tokens that begin with `-`\n * (flags are not conceptually part of the command identity), applies\n * {@link commandPrefix}, and joins the result with single spaces.\n */\nexport function commandPermissionKey(command: string): string {\n const tokens = command.split(/\\s+/).filter((token) => token.length > 0 && !token.startsWith(\"-\"));\n return commandPrefix(tokens).join(\" \");\n}\n\nexport type ShellApprovalMode = \"always\" | \"once_per_session\" | \"never\";\n\nexport interface ShellApprovalRule {\n readonly match: string | RegExp;\n readonly requireApproval: ShellApprovalMode;\n readonly reason: string;\n}\n\nexport const DEFAULT_SHELL_APPROVAL_RULES: readonly ShellApprovalRule[] = Object.freeze([\n { match: /^rm\\s+-rf\\b/, requireApproval: \"always\", reason: \"destructive recursive removal\" },\n {\n match: /\\b(format|mkfs)\\b/,\n requireApproval: \"always\",\n reason: \"destructive filesystem operation\",\n },\n {\n match: /\\bDROP\\s+(DATABASE|SCHEMA|TABLE)\\b/i,\n requireApproval: \"always\",\n reason: \"destructive database operation\",\n },\n {\n match: /\\b(npm|pnpm|yarn)\\s+publish\\b/,\n requireApproval: \"always\",\n reason: \"package publishing\",\n },\n { match: /^git\\s+push\\b/, requireApproval: \"once_per_session\", reason: \"remote git mutation\" },\n]);\n\nexport function matchesShellApprovalRule(command: string, rule: ShellApprovalRule): boolean {\n return typeof rule.match === \"string\" ? command.startsWith(rule.match) : rule.match.test(command);\n}\n\nexport function shellApprovalRequired(\n command: string,\n rules: readonly ShellApprovalRule[] = DEFAULT_SHELL_APPROVAL_RULES,\n): ShellApprovalRule | null {\n return (\n rules.find(\n (rule) => rule.requireApproval !== \"never\" && matchesShellApprovalRule(command, rule),\n ) ?? null\n );\n}\n"],"mappings":"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","names":[]}

package/package.json ADDED Viewed

@@ -0,0 +1,54 @@
+{
+  "name": "@nebutra/execution-policy",
+  "version": "0.1.0",
+  "description": "Shared command permission and approval policy primitives for runtime and execution packages",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "nebutra": {
+    "status": "wip",
+    "productionReady": false,
+    "surface": "support-contract",
+    "requires": [
+      "@nebutra/agent-runtime consumes this contract for runtime approval grammar",
+      "@nebutra/code-execution consumes this contract for executor policy checks"
+    ],
+    "gaps": [
+      "Session-scoped approval persistence still lives in agent-runtime",
+      "Shell parsing remains prefix-based until a shell AST parser is introduced",
+      "Network and file-write policies are not unified here yet"
+    ],
+    "featureId": "execution-policy",
+    "category": "ai",
+    "summary": "Single shared owner for command permission matching and shell approval defaults"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.4"
+  },
+  "homepage": "https://github.com/Nebutra/Nebutra-Sailor/tree/main/packages/ai/execution-policy#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nebutra/Nebutra-Sailor.git",
+    "directory": "packages/ai/execution-policy"
+  },
+  "bugs": {
+    "url": "https://github.com/Nebutra/Nebutra-Sailor/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.test.ts ADDED Viewed

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import {
+  type Action,
+  BUILTIN_ARITY,
+  commandPermissionKey,
+  commandPrefix,
+  DEFAULT_SHELL_APPROVAL_RULES,
+  evaluate,
+  type Rule,
+  type Ruleset,
+  shellApprovalRequired,
+  wildcardMatch,
+} from "./index";
+describe("wildcardMatch", () => {
+  it("matches anchored globs with optional trailing space-star", () => {
+    expect(wildcardMatch("git", "git")).toBe(true);
+    expect(wildcardMatch("git status", "git")).toBe(false);
+    expect(wildcardMatch("git", "git *")).toBe(true);
+    expect(wildcardMatch("git status", "git *")).toBe(true);
+    expect(wildcardMatch("npm", "git *")).toBe(false);
+  });
+});
+describe("evaluate", () => {
+  it("resolves first matching permission and pattern pair", () => {
+    const allowGitRead: Rule = { permission: "bash", pattern: "git status", action: "allow" };
+    const askGit: Rule = { permission: "bash", pattern: "git *", action: "ask" };
+    const denyRm: Rule = { permission: "bash", pattern: "rm *", action: "deny" };
+    const ruleset: Ruleset = [allowGitRead, askGit, denyRm];
+    expect(evaluate("bash", "git status", ruleset)).toEqual(allowGitRead);
+    expect(evaluate("bash", "git push", ruleset)).toEqual(askGit);
+    expect(evaluate("edit", "git status", ruleset)).toEqual({
+      permission: "edit",
+      pattern: "*",
+      action: "ask",
+    });
+  });
+  it("keeps the documented action vocabulary", () => {
+    const actions: Action[] = ["allow", "deny", "ask"];
+    expect(actions).toHaveLength(3);
+  });
+});
+describe("commandPermissionKey", () => {
+  it("uses the shared command arity table", () => {
+    expect(BUILTIN_ARITY.git).toBe(2);
+    expect(commandPrefix(["git", "checkout", "main"])).toEqual(["git", "checkout"]);
+    expect(commandPermissionKey("pnpm run test -- --watch")).toBe("pnpm run test");
+    expect(commandPermissionKey("rm -rf build")).toBe("rm");
+  });
+});
+describe("shellApprovalRequired", () => {
+  it("keeps destructive defaults in the shared execution policy contract", () => {
+    expect(DEFAULT_SHELL_APPROVAL_RULES.length).toBeGreaterThanOrEqual(5);
+    expect(shellApprovalRequired("rm -rf build")).toMatchObject({
+      requireApproval: "always",
+      reason: "destructive recursive removal",
+    });
+    expect(shellApprovalRequired("git push origin main")).toMatchObject({
+      requireApproval: "once_per_session",
+    });
+    expect(shellApprovalRequired("pnpm test")).toBeNull();
+  });
+});

package/src/index.ts ADDED Viewed

@@ -0,0 +1,245 @@
+/**
+ * Permission ruleset evaluator.
+ *
+ * A small, pure, stateless re-expression of a two-dimensional wildcard
+ * permission model plus a bash-command-prefix extractor. No global state,
+ * no I/O, no mutation of inputs — every function is referentially transparent.
+ *
+ * The model has two independent dimensions per rule:
+ *   - `permission` — the capability namespace (e.g. "bash", "edit", "net")
+ *   - `pattern`    — the concrete subject within that namespace
+ * A rule applies only when BOTH dimensions match the query via {@link wildcardMatch}.
+ */
+/** The decision a rule yields. Unknown queries fail safe to "ask". */
+export type Action = "allow" | "deny" | "ask";
+/** A single permission rule. Both dimensions are matched as wildcard globs. */
+export interface Rule {
+  permission: string;
+  pattern: string;
+  action: Action;
+}
+/** An ordered list of rules. Earlier rules take precedence. */
+export type Ruleset = Rule[];
+/**
+ * Anchored full-string glob matcher.
+ *
+ * Semantics:
+ *   - `*` matches any run of characters, including the empty run.
+ *   - `?` matches exactly one character.
+ *   - Every other character is matched literally (regex metacharacters in
+ *     `pattern` carry no special meaning).
+ *   - The match is anchored: the entire `str` must be consumed.
+ *
+ * Special rule (ported faithfully): if `pattern` ends with `" *"` (a single
+ * space immediately followed by `*`), that trailing ` *` is OPTIONAL. The
+ * pattern then matches both `"<head> <rest>"` and exactly `"<head>"` with
+ * nothing after it. For example `"git *"` matches `"git"` and `"git status"`.
+ *
+ * Implemented with a backtracking two-pointer scan whose `*` handling uses a
+ * single saved restart position, giving O(|str| * |pattern|) worst case with
+ * no catastrophic blow-up.
+ */
+export function wildcardMatch(str: string, pattern: string): boolean {
+  if (isOptionalTrailingStar(pattern)) {
+    const head = pattern.slice(0, -2); // drop the trailing " *"
+    // Head-only branch: the whole string equals the head, matched as a glob.
+    if (globMatch(str, head)) {
+      return true;
+    }
+    // Otherwise the full "<head> *" pattern must match (space is consumed).
+    return globMatch(str, pattern);
+  }
+  return globMatch(str, pattern);
+}
+/**
+ * True when `pattern` ends in a literal space followed by `*`, and that `*`
+ * is the final character. A bare `"*"` (no preceding space) is NOT treated
+ * as the optional-suffix form.
+ */
+function isOptionalTrailingStar(pattern: string): boolean {
+  return pattern.length >= 2 && pattern.endsWith(" *");
+}
+/**
+ * Core anchored glob match using linear-time backtracking. Only `*` can
+ * backtrack, and it uses a single restart marker (the classic two-pointer
+ * algorithm), so there is no exponential backtracking.
+ */
+function globMatch(str: string, pattern: string): boolean {
+  let s = 0;
+  let p = 0;
+  let starP = -1;
+  let starS = 0;
+  while (s < str.length) {
+    const pc = p < pattern.length ? pattern[p] : undefined;
+    if (pc === "*") {
+      // Record the restart point and tentatively consume zero chars.
+      starP = p;
+      starS = s;
+      p += 1;
+    } else if (pc === "?" || pc === str[s]) {
+      p += 1;
+      s += 1;
+    } else if (starP !== -1) {
+      // Backtrack: let the last `*` swallow one more character.
+      p = starP + 1;
+      starS += 1;
+      s = starS;
+    } else {
+      return false;
+    }
+  }
+  // Consume any trailing `*` segments in the pattern.
+  while (p < pattern.length && pattern[p] === "*") {
+    p += 1;
+  }
+  return p === pattern.length;
+}
+/**
+ * Resolve a permission query against one or more rulesets.
+ *
+ * Rulesets are concatenated in argument order (no mutation) and scanned
+ * front-to-back. The FIRST rule whose `permission` and `pattern` both match
+ * the query (via {@link wildcardMatch}) is returned. If no rule matches, a
+ * fail-safe default is returned: the queried permission/pattern with action
+ * `"ask"` (unknown → ask, never silently allow).
+ */
+export function evaluate(permission: string, pattern: string, ...rulesets: Ruleset[]): Rule {
+  for (const ruleset of rulesets) {
+    for (const rule of ruleset) {
+      if (wildcardMatch(permission, rule.permission) && wildcardMatch(pattern, rule.pattern)) {
+        return rule;
+      }
+    }
+  }
+  return { permission, pattern: "*", action: "ask" };
+}
+/**
+ * Built-in command arity table. Maps a (possibly multi-word) command prefix
+ * to the number of leading tokens that constitute its "human-understandable
+ * command" for permission matching. Longest matching prefix wins.
+ *
+ * Frozen so the shared default cannot be mutated by callers.
+ */
+export const BUILTIN_ARITY: Readonly<Record<string, number>> = Object.freeze({
+  git: 2,
+  npm: 2,
+  "npm run": 3,
+  docker: 2,
+  kubectl: 2,
+  cargo: 2,
+  pnpm: 2,
+  "pnpm run": 3,
+  yarn: 2,
+  "yarn run": 3,
+  go: 2,
+  ls: 1,
+  cat: 1,
+  cd: 1,
+  rm: 1,
+  cp: 1,
+  mv: 1,
+  mkdir: 1,
+  echo: 1,
+  grep: 1,
+  python: 1,
+  node: 1,
+});
+/**
+ * Extract the human-understandable command from already-split, flag-free
+ * shell tokens.
+ *
+ * Strategy: try the longest prefix first. For `len` from `tokens.length` down
+ * to 1, if `tokens.slice(0, len).join(" ")` is a key in the (merged) arity
+ * table, return `tokens.slice(0, arity[thatPrefix])`. If the tokens are empty,
+ * return `[]`. Otherwise default to the first token only.
+ *
+ * `arity` is shallow-merged OVER the built-in table; neither the caller's
+ * object nor the built-in table is mutated.
+ */
+export function commandPrefix(
+  tokens: string[],
+  arity?: Record<string, number> | undefined,
+): string[] {
+  if (tokens.length === 0) {
+    return [];
+  }
+  const table: Record<string, number> = { ...BUILTIN_ARITY, ...(arity ?? {}) };
+  for (let len = tokens.length; len >= 1; len -= 1) {
+    const prefixKey = tokens.slice(0, len).join(" ");
+    const take = table[prefixKey];
+    if (take !== undefined) {
+      // Clamp to the available token count; never expand beyond the input.
+      return tokens.slice(0, Math.min(take, tokens.length));
+    }
+  }
+  return tokens.slice(0, 1);
+}
+/**
+ * Derive the `pattern` to feed {@link evaluate} for a bash permission.
+ *
+ * Splits `command` on arbitrary whitespace, drops tokens that begin with `-`
+ * (flags are not conceptually part of the command identity), applies
+ * {@link commandPrefix}, and joins the result with single spaces.
+ */
+export function commandPermissionKey(command: string): string {
+  const tokens = command.split(/\s+/).filter((token) => token.length > 0 && !token.startsWith("-"));
+  return commandPrefix(tokens).join(" ");
+}
+export type ShellApprovalMode = "always" | "once_per_session" | "never";
+export interface ShellApprovalRule {
+  readonly match: string | RegExp;
+  readonly requireApproval: ShellApprovalMode;
+  readonly reason: string;
+}
+export const DEFAULT_SHELL_APPROVAL_RULES: readonly ShellApprovalRule[] = Object.freeze([
+  { match: /^rm\s+-rf\b/, requireApproval: "always", reason: "destructive recursive removal" },
+  {
+    match: /\b(format|mkfs)\b/,
+    requireApproval: "always",
+    reason: "destructive filesystem operation",
+  },
+  {
+    match: /\bDROP\s+(DATABASE|SCHEMA|TABLE)\b/i,
+    requireApproval: "always",
+    reason: "destructive database operation",
+  },
+  {
+    match: /\b(npm|pnpm|yarn)\s+publish\b/,
+    requireApproval: "always",
+    reason: "package publishing",
+  },
+  { match: /^git\s+push\b/, requireApproval: "once_per_session", reason: "remote git mutation" },
+]);
+export function matchesShellApprovalRule(command: string, rule: ShellApprovalRule): boolean {
+  return typeof rule.match === "string" ? command.startsWith(rule.match) : rule.match.test(command);
+}
+export function shellApprovalRequired(
+  command: string,
+  rules: readonly ShellApprovalRule[] = DEFAULT_SHELL_APPROVAL_RULES,
+): ShellApprovalRule | null {
+  return (
+    rules.find(
+      (rule) => rule.requireApproval !== "never" && matchesShellApprovalRule(command, rule),
+    ) ?? null
+  );
+}

package/tsconfig.json ADDED Viewed

@@ -0,0 +1,12 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "target": "esnext",
+    "types": ["node"],
+    "incremental": false
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts ADDED Viewed

@@ -0,0 +1,10 @@
+import { defineConfig } from "tsup";
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["esm"],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  target: "es2022",
+});