@gotgenes/pi-permission-system 16.0.1 → 16.1.0

package/src/access-intent/bash/program.ts

@@ -0,0 +1,102 @@
+import type { AccessPath } from "#src/access-intent/access-path";
+import {
+  type BashCommand,
+  collectCommands,
+} from "#src/access-intent/bash/command-enumeration";
+import {
+  type BashPathRuleCandidate,
+  collectPathCandidates,
+  projectExternalPaths,
+  projectRuleCandidates,
+} from "#src/access-intent/bash/cwd-projection";
+import { getParser } from "#src/access-intent/bash/parser";
+
+export type { BashCommand, BashPathRuleCandidate };
+
+/**
+ * A bash command parsed once into a born-ready representation.
+ *
+ * Parsing is the expensive step (tree-sitter WASM); `BashProgram` performs it
+ * a single time and eagerly resolves all three typed slices so the bash
+ * permission gates do not each re-parse or re-walk the command, and so the
+ * slices are guaranteed to agree.
+ *
+ * Construct via the async `parse()` factory; the constructor is private.
+ */
+export class BashProgram {
+  private constructor(
+    private readonly commandUnits: readonly BashCommand[],
+    private readonly resolvedExternalPaths: readonly AccessPath[],
+    private readonly resolvedRuleCandidates: readonly BashPathRuleCandidate[],
+  ) {}
+
+  /**
+   * Parse a bash command into a born-ready `BashProgram`.
+   *
+   * Uses tree-sitter-bash to build the full AST, enumerates command units and
+   * walks path-candidate tokens once, then eagerly resolves all three slices
+   * against `cwd`. Heredoc bodies, comments, and other non-argument content are
+   * skipped. An unparseable command yields an empty program.
+   */
+  static async parse(command: string, cwd: string): Promise<BashProgram> {
+    const parser = await getParser();
+    const tree = parser.parse(command);
+    if (!tree) return new BashProgram([], [], []);
+
+    try {
+      const candidates = collectPathCandidates(tree.rootNode);
+      return new BashProgram(
+        collectCommands(tree.rootNode),
+        projectExternalPaths(candidates, cwd),
+        projectRuleCandidates(candidates, cwd),
+      );
+    } finally {
+      tree.delete();
+    }
+  }
+
+  /**
+   * The top-level command-pattern units of the chain, in source order.
+   *
+   * Splits on the shell chain operators (`&&`, `||`, `;`, `|`, `&`, newlines);
+   * quotes, command substitution, and subshells are respected by the parser and
+   * are NOT split — a subshell or other compound statement is emitted whole.
+   * May be empty (e.g. an empty command or a comment-only line); callers fall
+   * back to the whole command so the surface is never evaluated weaker than
+   * before.
+   */
+  // Used by resolveBashCommandCheck (bash-command.ts) and tests. Fallow's
+  // syntactic analysis cannot resolve the static-factory return type (private
+  // ctor), so it reports a false positive here.
+  // fallow-ignore-next-line unused-class-member
+  commands(): BashCommand[] {
+    return [...this.commandUnits];
+  }
+
+  /**
+   * Deduplicated paths that resolve outside `cwd`, as {@link AccessPath} value
+   * objects holding both the lexical (as-typed) and canonical (symlink-resolved)
+   * forms behind distinct accessors.
+   *
+   * Resolved eagerly at parse time against the `cwd` supplied to `parse()`.
+   * Use `.matchValues()` for `external_directory` pattern matching and
+   * `.boundaryValue()` for containment checks; `.value()` for display and logs.
+   */
+  externalPaths(): AccessPath[] {
+    return [...this.resolvedExternalPaths];
+  }
+
+  /**
+   * Path-rule candidates paired with their policy lookup values.
+   *
+   * Resolved eagerly at parse time against the `cwd` supplied to `parse()`.
+   * Each token is resolved against the effective working directory in force at
+   * the token's position (folding literal current-shell `cd` commands), while
+   * raw and project-relative aliases are retained for backward-compatible
+   * relative rules. A token after a non-literal `cd` keeps only its literal
+   * value so no spurious absolute rule can match (#393).
+   */
+  pathRuleCandidates(): BashPathRuleCandidate[] {
+    return [...this.resolvedRuleCandidates];
+  }
+}

package/src/{handlers/gates/bash-token-classification.ts → access-intent/bash/token-classification.ts}

@@ -1,7 +1,7 @@
 /**
  * Pure, synchronous token-classification helpers for bash path extraction.
  *
- * Exports two classifiers consumed by `bash-program.ts`:
+ * Exports two classifiers consumed by `cwd-projection.ts`:
  *   - `classifyTokenAsPathCandidate` — strict gate for the external-directory guard.
  *   - `classifyTokenAsRuleCandidate` — broader gate for cross-cutting `path` rules.
  *

package/src/access-intent/bash/token-collection.ts

@@ -0,0 +1,351 @@
+import { basename } from "node:path";
+import {
+  ARG_NODE_TYPES,
+  resolveNodeText,
+  SKIP_SUBTREE_TYPES,
+} from "#src/access-intent/bash/node-text";
+import type { TSNode } from "#src/access-intent/bash/parser";
+
+// ── Public surface ─────────────────────────────────────────────────────────
+
+/**
+ * Recursively visit the AST and collect resolved text of nodes that
+ * represent command arguments or redirect destinations.
+ *
+ * Skips `heredoc_body`, `heredoc_end`, and `comment` subtrees entirely.
+ *
+ * For commands in `PATTERN_FIRST_COMMANDS`, uses position-based
+ * argument skipping to avoid collecting inline patterns/scripts
+ * as path candidates. For all other commands, collects all
+ * arguments generically.
+ */
+export function collectPathCandidateTokens(node: TSNode): string[] {
+  if (SKIP_SUBTREE_TYPES.has(node.type)) return [];
+  if (node.type === "command") return collectCommandTokens(node);
+  if (node.type === "file_redirect") return collectRedirectTokens(node);
+
+  const tokens: string[] = [];
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child) tokens.push(...collectPathCandidateTokens(child));
+  }
+  return tokens;
+}
+
+/**
+ * Select the collection strategy for a `command` node: pattern-first
+ * commands use `collectPatternCommandTokens`; all others use
+ * `collectGenericCommandTokens`.
+ */
+export function collectCommandTokens(node: TSNode): string[] {
+  const commandName = extractCommandName(node);
+  const config = commandName
+    ? PATTERN_FIRST_COMMANDS.get(commandName)
+    : undefined;
+  return config
+    ? collectPatternCommandTokens(node, config)
+    : collectGenericCommandTokens(node);
+}
+
+/**
+ * Collect redirect-destination tokens from a `file_redirect` node.
+ */
+export function collectRedirectTokens(node: TSNode): string[] {
+  const tokens: string[] = [];
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    if (ARG_NODE_TYPES.has(child.type)) {
+      tokens.push(resolveNodeText(child));
+    }
+  }
+  return tokens;
+}
+
+/**
+ * Extract the command name from a `command` node.
+ * Returns the basename (e.g. `/usr/bin/sed` → `sed`), or undefined
+ * if the command name cannot be determined (e.g. variable expansion).
+ */
+export function extractCommandName(node: TSNode): string | undefined {
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    if (child.type === "command_name") {
+      const text = resolveNodeText(child);
+      return text ? basename(text) : undefined;
+    }
+  }
+  return undefined;
+}
+
+// ── Private helpers and config ─────────────────────────────────────────────
+
+interface PatternCommandConfig {
+  /** Flags that consume the next argument as a non-path value (pattern, separator, etc.) */
+  readonly argConsumingFlags: ReadonlySet<string>;
+  /** Flags that consume the next argument as a file path */
+  readonly fileConsumingFlags: ReadonlySet<string>;
+  /**
+   * Number of leading positional arguments that are patterns/scripts, not paths.
+   * Default: 1 (covers sed, awk, grep, rg).
+   * sd uses 2 (FIND and REPLACE_WITH are both non-path positionals).
+   */
+  readonly patternPositionals?: number;
+}
+
+/**
+ * Commands whose first N positional arguments are inline patterns/scripts,
+ * not filesystem paths. The map stores per-command flag configuration so
+ * the walker can correctly identify which arguments are consumed by flags
+ * vs. which are positional.
+ */
+const PATTERN_FIRST_COMMANDS: ReadonlyMap<string, PatternCommandConfig> =
+  new Map([
+    [
+      "sed",
+      {
+        argConsumingFlags: new Set(["-e", "-i"]),
+        fileConsumingFlags: new Set(["-f"]),
+      },
+    ],
+    [
+      "awk",
+      {
+        argConsumingFlags: new Set(["-e", "-F", "-v"]),
+        fileConsumingFlags: new Set(["-f"]),
+      },
+    ],
+    [
+      "gawk",
+      {
+        argConsumingFlags: new Set(["-e", "-F", "-v"]),
+        fileConsumingFlags: new Set(["-f"]),
+      },
+    ],
+    [
+      "nawk",
+      {
+        argConsumingFlags: new Set(["-e", "-F", "-v"]),
+        fileConsumingFlags: new Set(["-f"]),
+      },
+    ],
+    [
+      "grep",
+      {
+        argConsumingFlags: new Set(["-e", "-A", "-B", "-C", "-m"]),
+        fileConsumingFlags: new Set(["-f"]),
+      },
+    ],
+    [
+      "egrep",
+      {
+        argConsumingFlags: new Set(["-e", "-A", "-B", "-C", "-m"]),
+        fileConsumingFlags: new Set(["-f"]),
+      },
+    ],
+    [
+      "fgrep",
+      {
+        argConsumingFlags: new Set(["-e", "-A", "-B", "-C", "-m"]),
+        fileConsumingFlags: new Set(["-f"]),
+      },
+    ],
+    [
+      "rg",
+      {
+        argConsumingFlags: new Set([
+          "-e",
+          "-A",
+          "-B",
+          "-C",
+          "-m",
+          "-g",
+          "-t",
+          "-T",
+          "-j",
+          "-M",
+          "-r",
+          "-E",
+        ]),
+        fileConsumingFlags: new Set(["-f"]),
+      },
+    ],
+    [
+      "sd",
+      {
+        argConsumingFlags: new Set(["-n", "-f"]),
+        fileConsumingFlags: new Set([]),
+        patternPositionals: 2,
+      },
+    ],
+  ]);
+
+/**
+ * Describes what the walker should do when it encounters a flag word inside
+ * a pattern-first command.  Using a discriminated union lets the `switch` in
+ * `collectPatternCommandTokens` narrow `nextArgAction` without a non-null
+ * assertion (which would trigger the Biome/ESLint assertion conflict).
+ */
+type PatternCommandFlagDirective =
+  | { kind: "end-of-flags" }
+  | { kind: "regular-flag" }
+  | {
+      kind: "consume-arg";
+      nextArgAction: "skip" | "extract";
+      setsExplicitScript: boolean;
+    };
+
+/**
+ * Classify a flag word from a pattern-first command into a directive that
+ * tells the walker how to handle the flag and its following argument.
+ */
+function classifyPatternCommandFlag(
+  text: string,
+  config: PatternCommandConfig,
+): PatternCommandFlagDirective {
+  if (text === "--") return { kind: "end-of-flags" };
+  if (config.argConsumingFlags.has(text)) {
+    return {
+      kind: "consume-arg",
+      nextArgAction: "skip",
+      setsExplicitScript: text === "-e" || text === "-f",
+    };
+  }
+  if (config.fileConsumingFlags.has(text)) {
+    return {
+      kind: "consume-arg",
+      nextArgAction: "extract",
+      setsExplicitScript: true,
+    };
+  }
+  return { kind: "regular-flag" };
+}
+
+/**
+ * Collect path-candidate tokens from a command known to have
+ * pattern/script arguments in leading positional slots.
+ *
+ * Uses position-based skipping: the first N positional arguments
+ * (where N = patternPositionals, default 1) are assumed to be
+ * inline patterns/scripts and are skipped. Remaining positional
+ * arguments are collected as path candidates.
+ *
+ * Flags listed in `argConsumingFlags` consume the next argument
+ * (skipped). Flags in `fileConsumingFlags` consume the next
+ * argument as a file path (collected). The flags `-e` and `-f`
+ * additionally signal that an explicit script was provided via
+ * flag, so no inline positional script is expected.
+ */
+function collectPatternCommandTokens(
+  node: TSNode,
+  config: PatternCommandConfig,
+): string[] {
+  const patternPositionals = config.patternPositionals ?? 1;
+  let hasExplicitScript = false;
+  let positionalsSeen = 0;
+  let nextArgAction: "skip" | "extract" | null = null;
+  let pastEndOfFlags = false;
+  const tokens: string[] = [];
+
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+
+    // Skip command_name and variable_assignment nodes.
+    if (child.type === "command_name" || child.type === "variable_assignment")
+      continue;
+
+    // Only process argument-like nodes; recurse into others
+    // (e.g. command_substitution) for nested commands.
+    if (!ARG_NODE_TYPES.has(child.type)) {
+      tokens.push(...collectPathCandidateTokens(child));
+      continue;
+    }
+
+    const text = resolveNodeText(child);
+
+    // Handle consumed argument from previous flag.
+    if (nextArgAction === "skip") {
+      nextArgAction = null;
+      continue;
+    }
+    if (nextArgAction === "extract") {
+      tokens.push(text);
+      nextArgAction = null;
+      continue;
+    }
+
+    // Flag detection (only before "--" end-of-flags marker).
+    if (
+      !pastEndOfFlags &&
+      child.type === "word" &&
+      text.startsWith("-") &&
+      text.length > 1
+    ) {
+      const directive = classifyPatternCommandFlag(text, config);
+      switch (directive.kind) {
+        case "end-of-flags":
+          pastEndOfFlags = true;
+          break;
+        case "consume-arg":
+          nextArgAction = directive.nextArgAction;
+          if (directive.setsExplicitScript) hasExplicitScript = true;
+          break;
+        case "regular-flag":
+          break;
+      }
+      continue;
+    }
+
+    // Positional argument.
+    if (!hasExplicitScript && positionalsSeen < patternPositionals) {
+      positionalsSeen++;
+      continue; // Skip: this is an inline pattern/script.
+    }
+
+    // File argument — collect as path candidate.
+    tokens.push(text);
+  }
+
+  return tokens;
+}
+
+/**
+ * Collect all argument tokens from a generic (non-pattern-first) command node,
+ * skipping the command name and variable assignments.
+ */
+function collectGenericCommandTokens(node: TSNode): string[] {
+  const tokens: string[] = [];
+  let seenCommandName = false;
+
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+
+    if (child.type === "command_name") {
+      seenCommandName = true;
+      continue;
+    }
+    // Skip variable_assignment nodes (FOO=/bar)
+    if (child.type === "variable_assignment") continue;
+
+    // If there was no explicit command_name node, the first word-like
+    // child is the command name itself — skip it.
+    if (!seenCommandName && ARG_NODE_TYPES.has(child.type)) {
+      seenCommandName = true;
+      continue;
+    }
+
+    // Argument nodes: resolve their text and collect.
+    if (ARG_NODE_TYPES.has(child.type)) {
+      tokens.push(resolveNodeText(child));
+      continue;
+    }
+
+    // Recurse into other children (e.g. command_substitution nested in args)
+    tokens.push(...collectPathCandidateTokens(child));
+  }
+
+  return tokens;
+}

package/src/handlers/gates/bash-command.ts

@@ -1,4 +1,4 @@
-import type { BashCommand } from "#src/handlers/gates/bash-program";
+import type { BashCommand } from "#src/access-intent/bash/command-enumeration";
 import { pickMostRestrictive } from "#src/handlers/gates/candidate-check";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import type { PermissionCheckResult } from "#src/types";

package/src/handlers/gates/bash-external-directory.ts

@@ -1,13 +1,11 @@
+import type { BashProgram } from "#src/access-intent/bash/program";
 import { getNonEmptyString, toRecord } from "#src/common";
-import { getExternalDirectoryPolicyValues } from "#src/path-utils";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
-import type { PermissionCheckResult } from "#src/types";
-import type { BashProgram } from "./bash-program";
-import { pickMostRestrictive } from "./candidate-check";
 import type { GateResult } from "./descriptor";
 import { formatBashExternalDirectoryAskPrompt } from "./external-directory-messages";
+import { selectUncoveredExternalPaths } from "./external-directory-policy";
 import type { ToolCallContext } from "./types";
 
 /**
@@ -24,37 +22,27 @@ export function describeBashExternalDirectoryGate(
   bashProgram: BashProgram | null,
   resolver: ScopedPermissionResolver,
 ): GateResult {
-  if (tcc.toolName !== "bash" || !tcc.cwd) return null;
+  if (tcc.toolName !== "bash") return null;
 
   const command = getNonEmptyString(toRecord(tcc.input).command);
   if (!command) return null;
 
   if (!bashProgram) return null;
 
-  const externalPaths = bashProgram.externalPaths(tcc.cwd);
+  const externalPaths = bashProgram.externalPaths();
   if (externalPaths.length === 0) return null;
 
-  // Collect paths whose resolved state is not already "allow".
-  // Checking state (not source) ensures config-level allow rules (source: "special")
-  // suppress the prompt just as session-level allow rules (source: "session") do.
-  const uncoveredEntries: Array<{
-    path: string;
-    check: PermissionCheckResult;
-  }> = [];
-  for (const p of externalPaths) {
-    // Match each path against both its typed and symlink-resolved aliases on
-    // the external_directory surface, so a config pattern on either form
-    // applies (#418).
-    const check = resolver.resolvePathPolicy(
-      getExternalDirectoryPolicyValues(p, tcc.cwd),
+  // Resolve every external path on the external_directory surface and keep the
+  // ones not already allowed (config-level allows suppress the prompt just as
+  // session-level allows do); the shared helper single-sources the #418 alias
+  // matching and the worst-uncovered selection.
+  const { uncovered: uncoveredEntries, worstCheck } =
+    selectUncoveredExternalPaths(
+      externalPaths,
+      resolver,
       tcc.agentName ?? undefined,
-      "external_directory",
     );
-    if (check.state !== "allow") {
-      uncoveredEntries.push({ path: p, check });
-    }
-  }
-  const uncoveredPaths = uncoveredEntries.map(({ path }) => path);
+  const uncoveredPaths = uncoveredEntries.map(({ path }) => path.value());
 
   if (uncoveredPaths.length === 0) {
     return {
@@ -67,19 +55,17 @@ export function describeBashExternalDirectoryGate(
           toolName: tcc.toolName,
           agentName: tcc.agentName,
           command,
-          externalPaths,
+          externalPaths: externalPaths.map((p) => p.value()),
           resolution: "session_approved",
         },
       },
     };
   }
 
-  // Use the most restrictive check among uncovered paths as the pre-check result.
-  // This ensures a config-level "deny" rule is not downgraded to "ask" by the
-  // generic "*" catch-all that the old path-less checkPermission call returned.
-  const worstCheck =
-    pickMostRestrictive(uncoveredEntries.map(({ check }) => check)) ??
-    uncoveredEntries[0].check;
+  // After the early bypass, at least one path is uncovered, so worstCheck is
+  // defined; the fallback keeps TypeScript happy across the early return. A
+  // config-level "deny" is preserved (not downgraded to the catch-all "ask").
+  const preCheck = worstCheck ?? uncoveredEntries[0].check;
 
   const bashExtMessage = formatBashExternalDirectoryAskPrompt(
     command,
@@ -122,6 +108,6 @@ export function describeBashExternalDirectoryGate(
       surface: "external_directory",
       value: command,
     },
-    preCheck: worstCheck,
+    preCheck,
   };
 }

package/src/handlers/gates/bash-path-extractor.ts

@@ -1,15 +1,21 @@
-import { BashProgram } from "./bash-program";
+import { BashProgram } from "#src/access-intent/bash/program";
 
 /**
  * Extract paths from a bash command string that resolve outside CWD.
  *
  * Thin facade over {@link BashProgram.externalPaths}; parses the command and
- * returns the cd-aware external paths. See `BashProgram` for the parsing and
- * resolution semantics.
+ * returns the cd-aware external paths in their lexical (as-typed) string form.
+ * See `BashProgram` for the parsing and resolution semantics.
+ *
+ * Returns `string[]` (not `AccessPath[]`) so the large projection-correctness
+ * test suite in `bash-external-directory.test.ts` can assert path values
+ * without migrating every call site.
  */
 export async function extractExternalPathsFromBashCommand(
   command: string,
   cwd: string,
 ): Promise<string[]> {
-  return (await BashProgram.parse(command)).externalPaths(cwd);
+  return (await BashProgram.parse(command, cwd))
+    .externalPaths()
+    .map((p) => p.value());
 }

package/src/handlers/gates/bash-path.ts

@@ -1,9 +1,9 @@
+import type { BashProgram } from "#src/access-intent/bash/program";
 import { getNonEmptyString, toRecord } from "#src/common";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { PermissionCheckResult } from "#src/types";
-import type { BashProgram } from "./bash-program";
 import { pickMostRestrictive } from "./candidate-check";
 import type { GateResult } from "./descriptor";
 import { formatPathAskPrompt } from "./path";
@@ -36,7 +36,7 @@ export function describeBashPathGate(
 
   if (!bashProgram) return null;
 
-  const candidates = bashProgram.pathRuleCandidates(tcc.cwd);
+  const candidates = bashProgram.pathRuleCandidates();
   if (candidates.length === 0) return null;
   const tokens = candidates.map(({ token }) => token);
 

package/src/handlers/gates/external-directory-policy.ts

@@ -0,0 +1,65 @@
+import type { AccessPath } from "#src/access-intent/access-path";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
+import type { PermissionCheckResult } from "#src/types";
+import { pickMostRestrictive } from "./candidate-check";
+
+/** An external path whose resolved `external_directory` state is not "allow". */
+export interface UncoveredExternalPath {
+  path: AccessPath;
+  check: PermissionCheckResult;
+}
+
+/** The uncovered external paths plus the most restrictive check among them. */
+export interface UncoveredExternalPaths {
+  uncovered: UncoveredExternalPath[];
+  /** Worst check among uncovered paths; `undefined` only when none are uncovered. */
+  worstCheck: PermissionCheckResult | undefined;
+}
+
+/**
+ * Resolve one external path's policy on the `external_directory` surface.
+ *
+ * Matches against the typed and symlink-resolved aliases
+ * ({@link AccessPath.matchValues}) so a config pattern on either form applies
+ * (#418). This is the single source for the alias-derivation plus
+ * surface-tagged resolve that the two external-directory gates previously
+ * duplicated.
+ */
+export function resolveExternalDirectoryPolicy(
+  path: AccessPath,
+  resolver: ScopedPermissionResolver,
+  agentName: string | undefined,
+): PermissionCheckResult {
+  return resolver.resolvePathPolicy(
+    path.matchValues(),
+    agentName,
+    "external_directory",
+  );
+}
+
+/**
+ * Resolve a set of external paths and select those not already allowed.
+ *
+ * Each path is resolved via {@link resolveExternalDirectoryPolicy}; entries
+ * whose state is not "allow" are collected (filtering on state, not source, so
+ * config-level allow rules suppress the prompt just as session-level allow
+ * rules do), and the most restrictive uncovered check is returned so a config
+ * "deny" is not downgraded to the catch-all "ask".
+ */
+export function selectUncoveredExternalPaths(
+  paths: readonly AccessPath[],
+  resolver: ScopedPermissionResolver,
+  agentName: string | undefined,
+): UncoveredExternalPaths {
+  const uncovered: UncoveredExternalPath[] = [];
+  for (const path of paths) {
+    const check = resolveExternalDirectoryPolicy(path, resolver, agentName);
+    if (check.state !== "allow") {
+      uncovered.push({ path, check });
+    }
+  }
+  return {
+    uncovered,
+    worstCheck: pickMostRestrictive(uncovered.map(({ check }) => check)),
+  };
+}