@gotgenes/pi-permission-system 16.0.1 → 16.1.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [16.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v16.0.2...pi-permission-system-v16.1.0) (2026-06-26)
+
+
+### Features
+
+* **pi-permission-system:** introduce AccessPath value object ([c00d5c5](https://github.com/gotgenes/pi-packages/commit/c00d5c580a828234fafd7946be4e81313665d25d)), closes [#476](https://github.com/gotgenes/pi-packages/issues/476)
+
+## [16.0.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v16.0.1...pi-permission-system-v16.0.2) (2026-06-25)
+
+
+### Documentation
+
+* **pi-permission-system:** record parser/node-text extraction in architecture and skill ([#473](https://github.com/gotgenes/pi-packages/issues/473)) ([7626425](https://github.com/gotgenes/pi-packages/commit/7626425f587dd62ab54f39390841a6ca152b32e1))
+
 ## [16.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v16.0.0...pi-permission-system-v16.0.1) (2026-06-21)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "16.0.1",
+  "version": "16.1.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

package/src/access-intent/access-path.ts

@@ -0,0 +1,88 @@
+import {
+  canonicalNormalizePathForComparison,
+  getPathPolicyValues,
+  normalizePathForComparison,
+} from "#src/path-utils";
+
+/**
+ * A path's two representations held behind type-distinct accessors.
+ *
+ * A single `string` carrying both meanings was the root cause of [#418]:
+ * both external-directory gates matched config patterns against the
+ * symlink-resolved (canonical) path instead of the typed (lexical) path,
+ * defeating a configured `/tmp/*` allow.
+ *
+ * `AccessPath` makes the misuse a compile error:
+ * - {@link matchValues} returns `string[]` — the lexical alias union ∪ canonical,
+ *   for `external_directory` pattern matching.
+ * - {@link boundaryValue} returns `string` — the canonical form, for
+ *   outside-CWD containment and infra-read checks.
+ * - {@link value} returns `string` — the lexical absolute form, for display,
+ *   approval patterns, decision values, and logs.
+ *
+ * Construct via {@link forExternalDirectory}; the constructor is private.
+ */
+export class AccessPath {
+  private constructor(
+    private readonly lexical: string,
+    private readonly matchAliases: readonly string[],
+    private readonly canonical: string,
+  ) {}
+
+  /**
+   * Pattern-match values for the `external_directory` surface: the lexical
+   * alias union plus the canonical alias, so a config pattern on either the
+   * typed form (`/tmp/*`) or the symlink-resolved form (`/private/tmp/*`)
+   * matches (#418).
+   *
+   * Collapses to the lexical aliases when the canonical equals one of them
+   * (e.g. when the path is not a symlink).
+   */
+  matchValues(): string[] {
+    return this.canonical
+      ? [...new Set([...this.matchAliases, this.canonical])]
+      : [...this.matchAliases];
+  }
+
+  /**
+   * Canonical (symlink-resolved, win32-lowercased) form, for the outside-CWD
+   * boundary decision and Pi infrastructure-read containment checks.
+   *
+   * Returns `""` when the path could not be resolved (empty input).
+   */
+  boundaryValue(): string {
+    return this.canonical;
+  }
+
+  /**
+   * Lexical (as-typed, normalized but not symlink-resolved) form, for display,
+   * approval patterns, decision values, and log messages.
+   *
+   * Returns `""` for empty input.
+   */
+  value(): string {
+    return this.lexical;
+  }
+
+  /**
+   * Build an `AccessPath` for a tool-input or bash-token path resolved against
+   * `cwd`.
+   *
+   * - `matchValues()` returns the same set as the former
+   *   `getExternalDirectoryPolicyValues(pathValue, cwd)` — the lexical alias
+   *   union from `getPathPolicyValues` plus the canonical alias from
+   *   `canonicalNormalizePathForComparison` (#418).
+   * - `boundaryValue()` returns `canonicalNormalizePathForComparison(pathValue, cwd)`,
+   *   which is win32-lowercased (#382) — do not substitute a raw
+   *   `canonicalizePath` output here.
+   * - `value()` returns `normalizePathForComparison(pathValue, cwd)`, the
+   *   absolute lexical form.
+   */
+  static forExternalDirectory(pathValue: string, cwd: string): AccessPath {
+    return new AccessPath(
+      normalizePathForComparison(pathValue, cwd),
+      getPathPolicyValues(pathValue, { cwd }),
+      canonicalNormalizePathForComparison(pathValue, cwd),
+    );
+  }
+}

package/src/access-intent/bash/command-enumeration.ts

@@ -0,0 +1,154 @@
+import type { TSNode } from "#src/access-intent/bash/parser";
+import type { BashCommandContext } from "#src/types";
+
+// ── Command type ─────────────────────────────────────────────────────────────
+
+/**
+ * One command-pattern unit of a parsed bash program.
+ *
+ * Minimal by design — `text` is the simple-command (or whole compound
+ * statement) string matched against the bash rules.
+ * The type is the stable extension point: #306 adds an execution `context`,
+ * #307 adds per-command path candidates and an effective working directory.
+ */
+export interface BashCommand {
+  readonly text: string;
+  /**
+   * Execution context for a nested command (substitution or subshell); absent
+   * for a current-shell (top-level) command.
+   */
+  readonly context?: BashCommandContext;
+}
+
+// ── Command enumeration ──────────────────────────────────────────────────────
+
+/**
+ * Container node types descended into when enumerating command units.
+ */
+const COMMAND_ENUM_DESCEND = new Set([
+  "program",
+  "list",
+  "pipeline",
+  "redirected_statement",
+]);
+
+/**
+ * Named node types skipped during command enumeration: redirect targets,
+ * comments, and heredoc bodies — none is a command to evaluate.
+ * Anonymous tokens (chain operators `&&`/`;`/`|`, substitution and subshell
+ * delimiters `$(`/`)`/`` ` ``/`(`) are filtered by the `isNamed` guard, not
+ * listed here.
+ */
+const COMMAND_ENUM_SKIP = new Set([
+  "file_redirect",
+  "heredoc_redirect",
+  "herestring_redirect",
+  "comment",
+  "heredoc_body",
+  "heredoc_end",
+]);
+
+/**
+ * Nested execution contexts whose interior commands really execute and must be
+ * evaluated too: command substitution (`$(…)`, backticks) and process
+ * substitution (`<(…)`/`>(…)`).
+ * Subshells (`( … )`) are handled separately because they are also emitted
+ * whole.
+ */
+const NESTED_EXECUTION_CONTEXTS = new Map<string, BashCommandContext>([
+  ["command_substitution", "command_substitution"],
+  ["process_substitution", "process_substitution"],
+]);
+
+/**
+ * Enumerate the command units of a bash program, in source order.
+ *
+ * Descends container nodes (`program`, `list`, `pipeline`,
+ * `redirected_statement`) and emits each `command` node whole.
+ * Additionally descends into the three nested execution contexts — command
+ * substitution (`$(…)`, backticks), process substitution (`<(…)`/`>(…)`), and
+ * subshells (`( … )`) — emitting each inner command as its own unit *in
+ * addition to* the enclosing command, since those inner commands really execute
+ * (#306).
+ * Control-flow bodies and `{ … }` brace groups are emitted whole without
+ * descending (deferred).
+ *
+ * The enclosing command/subshell is always still emitted whole, so adding the
+ * nested units can only ever produce a more-restrictive decision, never weaker.
+ */
+export function collectCommands(node: TSNode): BashCommand[] {
+  const out: BashCommand[] = [];
+  collectCommandsInto(node, undefined, out);
+  return out;
+}
+
+function collectCommandsInto(
+  node: TSNode,
+  context: BashCommandContext | undefined,
+  out: BashCommand[],
+): void {
+  // Anonymous tokens (operators `&&`/`;`/`|`, delimiters `$(`/`)`/`` ` ``/`(`)
+  // carry no command.
+  if (!node.isNamed) return;
+  if (COMMAND_ENUM_SKIP.has(node.type)) return;
+
+  if (node.type === "command") {
+    out.push(makeUnit(node.text, context));
+    // A command's text already contains any substitution; descend its subtree
+    // to ALSO emit the inner commands of command/process substitutions.
+    collectSubstitutionCommands(node, out);
+    return;
+  }
+
+  if (node.type === "subshell") {
+    out.push(makeUnit(node.text, context)); // never-weaker whole emit
+    descendCommandChildren(node, "subshell", out);
+    return;
+  }
+
+  if (COMMAND_ENUM_DESCEND.has(node.type)) {
+    descendCommandChildren(node, context, out);
+    return;
+  }
+
+  // Any other named statement (compound_statement `{ … }`, if/while/for/case,
+  // function_definition): emit whole, do not descend — deferred (#306).
+  out.push(makeUnit(node.text, context));
+}
+
+function makeUnit(
+  text: string,
+  context: BashCommandContext | undefined,
+): BashCommand {
+  return context ? { text, context } : { text };
+}
+
+function descendCommandChildren(
+  node: TSNode,
+  context: BashCommandContext | undefined,
+  out: BashCommand[],
+): void {
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child) collectCommandsInto(child, context, out);
+  }
+}
+
+/**
+ * Search a command's subtree for command/process substitutions and enumerate
+ * the commands inside them, tagged with the substitution's execution context.
+ * A substitution can nest under `command_name` (when the whole command is
+ * `$(…)`) or under an argument, so the entire subtree is searched.
+ */
+function collectSubstitutionCommands(node: TSNode, out: BashCommand[]): void {
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    const nestedContext = NESTED_EXECUTION_CONTEXTS.get(child.type);
+    if (nestedContext) {
+      descendCommandChildren(child, nestedContext, out);
+    } else {
+      collectSubstitutionCommands(child, out);
+    }
+  }
+}