@komarspn/pi-permission-system 16.0.2

package/src/bash-arity.ts

@@ -0,0 +1,210 @@
+/**
+ * Curated arity dictionary for common CLI commands.
+ *
+ * Keys are lowercase, space-joined command prefixes.
+ * Values are the total token count that defines the "human-understandable
+ * subcommand" — i.e. how many tokens to include in a session-approval pattern.
+ *
+ * Multi-level entries (e.g. "npm run": 3) take precedence over shorter entries
+ * ("npm": 2) because `prefix()` uses longest-match-wins.
+ *
+ * Exported for testability.
+ */
+export const ARITY: Record<string, number> = {
+  // Version control
+  git: 2,
+  hg: 2,
+  svn: 2,
+
+  // Node.js package managers
+  npm: 2,
+  "npm run": 3,
+  "npm exec": 3,
+  npx: 2,
+  pnpm: 2,
+  "pnpm run": 3,
+  "pnpm exec": 3,
+  "pnpm dlx": 3,
+  yarn: 2,
+  "yarn run": 3,
+  bun: 2,
+  "bun run": 3,
+  "bun add": 2,
+  "bun x": 3,
+
+  // Runtimes
+  deno: 2,
+  "deno run": 3,
+  "deno task": 3,
+  "deno compile": 3,
+
+  // Python
+  pip: 2,
+  pip3: 2,
+  uv: 2,
+  "uv run": 3,
+  "uv pip": 3,
+
+  // Rust
+  cargo: 2,
+
+  // Go
+  go: 2,
+  "go run": 3,
+
+  // Ruby
+  bundle: 2,
+  "bundle exec": 3,
+
+  // Docker / container
+  docker: 2,
+  "docker compose": 3,
+  "docker container": 3,
+  "docker image": 3,
+  "docker network": 3,
+  "docker volume": 3,
+  podman: 2,
+  "podman compose": 3,
+
+  // Kubernetes
+  kubectl: 2,
+  helm: 2,
+
+  // Cloud CLIs
+  aws: 3,
+  az: 3,
+  gcloud: 3,
+  gh: 2,
+  "gh pr": 3,
+  "gh issue": 3,
+  "gh repo": 3,
+  fly: 2,
+  vercel: 2,
+  wrangler: 2,
+
+  // Build tools
+  make: 1,
+  bazel: 2,
+
+  // Infrastructure
+  terraform: 2,
+  tofu: 2,
+  pulumi: 2,
+
+  // System service management
+  systemctl: 2,
+  service: 2,
+
+  // Shell file-ops — args are paths/targets, not subcommands
+  ls: 1,
+  ll: 1,
+  la: 1,
+  cat: 1,
+  less: 1,
+  more: 1,
+  head: 1,
+  tail: 1,
+  grep: 1,
+  rg: 1,
+  ag: 1,
+  find: 1,
+  touch: 1,
+  mkdir: 1,
+  rm: 1,
+  cp: 1,
+  mv: 1,
+  ln: 1,
+  chmod: 1,
+  chown: 1,
+  du: 1,
+  df: 1,
+  echo: 1,
+  printf: 1,
+  diff: 1,
+  patch: 1,
+  wc: 1,
+  sort: 1,
+  uniq: 1,
+  awk: 1,
+  sed: 1,
+  tar: 1,
+  zip: 1,
+  unzip: 1,
+
+  // Network
+  curl: 1,
+  wget: 1,
+  ssh: 1,
+  scp: 1,
+  rsync: 1,
+  ping: 1,
+
+  // Process management
+  kill: 1,
+  killall: 1,
+  pkill: 1,
+
+  // Package managers (system)
+  brew: 2,
+  apt: 2,
+  "apt-get": 2,
+  yum: 2,
+  dnf: 2,
+};
+
+/**
+ * Return the semantically meaningful prefix tokens for a tokenized command.
+ *
+ * Performs a longest-match-wins lookup against the `ARITY` dictionary:
+ * iterates from the longest possible prefix down to a single token, returning
+ * the first (longest) match. Lookup is case-insensitive; the returned tokens
+ * preserve their original casing.
+ *
+ * When no entry matches, defaults to arity 1 (first token only).
+ * When the resolved arity exceeds the available tokens, it is clamped.
+ *
+ * @param tokens - The command split by whitespace (e.g. `["git", "checkout", "main"]`).
+ * @returns The prefix tokens defining the meaningful subcommand.
+ */
+export function prefix(tokens: string[]): string[] {
+  if (tokens.length === 0) return [];
+
+  for (let n = tokens.length; n >= 1; n--) {
+    const key = tokens
+      .slice(0, n)
+      .map((t) => t.toLowerCase())
+      .join(" ");
+    const arity = ARITY[key];
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- ARITY record type hides that a key may be absent at runtime
+    if (arity !== undefined) {
+      return tokens.slice(0, Math.min(arity, tokens.length));
+    }
+  }
+
+  // Unknown command — default arity 1.
+  return [tokens[0]];
+}
+
+/**
+ * Remove shell comment lines from a bash command string.
+ *
+ * A comment line is one whose first non-whitespace character is `#`. Agents
+ * frequently prepend descriptive comments before the real command
+ * (e.g. `"# Check debug logs\nfind ..."`); such prefixes defeat wildcard
+ * pattern matching and session-approval suggestions, which tokenize the
+ * leading text. Stripping comment lines lets matching operate on the actual
+ * command.
+ *
+ * The original command is never returned: when every line is a comment (or
+ * the input is blank) an empty string is returned, and each caller applies
+ * its own fallback.
+ *
+ * @param command - Raw bash command, possibly multi-line.
+ * @returns The command with comment lines removed and surrounding whitespace
+ *   trimmed, or an empty string when nothing meaningful remains.
+ */
+export function stripBashCommentLines(command: string): string {
+  const lines = command.split("\n");
+  const meaningful = lines.filter((line) => !/^\s*#/.test(line));
+  return meaningful.join("\n").trim();
+}

package/src/builtin-tool-input-formatters.ts

@@ -0,0 +1,82 @@
+/**
+ * Built-in tool input formatters registered through the public seam at startup.
+ *
+ * Each formatter here dogfoods `ToolInputFormatterRegistry.register` — it goes
+ * through exactly the same path a third-party extension would use.
+ */
+
+import { toRecord } from "./common";
+import type {
+  ToolInputFormatter,
+  ToolInputFormatterRegistry,
+} from "./tool-input-formatter-registry";
+import { truncateInlineText } from "./tool-input-preview";
+
+/** Maximum total length of the generated argument summary (before "with " prefix). */
+const MCP_ARGS_SUMMARY_MAX_LENGTH = 160;
+
+/** Maximum length of a single string argument value (before quoting). */
+const MCP_ARG_VALUE_MAX_LENGTH = 60;
+
+/**
+ * Render a single MCP argument value as a compact, readable fragment.
+ *
+ * - Strings: quoted and truncated.
+ * - Numbers / booleans: plain string conversion.
+ * - Arrays: `[N items]`.
+ * - Objects: `{…}`.
+ * - Everything else: plain string conversion.
+ */
+function renderArgValue(value: unknown): string {
+  if (typeof value === "string") {
+    return `"${truncateInlineText(value, MCP_ARG_VALUE_MAX_LENGTH)}"`;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.length} items]`;
+  }
+  if (typeof value === "object" && value !== null) {
+    return "{…}";
+  }
+  return String(value);
+}
+
+/**
+ * Format an MCP tool call's `arguments` payload as a human-readable summary.
+ *
+ * Returns `undefined` when `arguments` is absent or empty — the MCP ask-prompt
+ * is then left unchanged (no suffix appended).
+ *
+ * Intended to be registered as the `"mcp"` formatter via
+ * `registerBuiltinToolInputFormatters`.
+ */
+export const formatMcpInputForPrompt: ToolInputFormatter = (
+  input: Record<string, unknown>,
+): string | undefined => {
+  const args = toRecord(input.arguments);
+  const entries = Object.entries(args);
+  if (entries.length === 0) return undefined;
+
+  const parts = entries.map(
+    ([key, value]) => `${key}: ${renderArgValue(value)}`,
+  );
+  const summary = truncateInlineText(
+    parts.join(", "),
+    MCP_ARGS_SUMMARY_MAX_LENGTH,
+  );
+  return `with ${summary}`;
+};
+
+/**
+ * Register all built-in tool input formatters into `registry`.
+ *
+ * Called once from the extension factory (`index.ts`) immediately after the
+ * registry is constructed, before any third-party registration can occur.
+ */
+export function registerBuiltinToolInputFormatters(
+  registry: ToolInputFormatterRegistry,
+): void {
+  registry.register("mcp", formatMcpInputForPrompt);
+}

package/src/canonicalize-path.ts

@@ -0,0 +1,30 @@
+import { realpathSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Resolve symlinks in an absolute path, best-effort.
+ *
+ * Splits the path into components and tries `realpathSync` from the full path
+ * down to `/`, re-appending the non-existent tail to the first ancestor that
+ * resolves. Returns the input unchanged when no ancestor resolves (unreachable
+ * in practice since `/` always exists) or when a non-ENOENT/ENOTDIR error is
+ * encountered (e.g. `EACCES`, `ELOOP`), so callers fall back to lexical
+ * containment for paths that cannot be resolved.
+ */
+export function canonicalizePath(absolutePath: string): string {
+  if (!absolutePath) return absolutePath;
+
+  const parts = absolutePath.split("/").filter(Boolean);
+  for (let i = parts.length; i >= 0; i--) {
+    const candidate = "/" + parts.slice(0, i).join("/");
+    try {
+      const real = realpathSync(candidate);
+      const tail = parts.slice(i);
+      return tail.length === 0 ? real : join(real, ...tail);
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== "ENOENT" && code !== "ENOTDIR") return absolutePath;
+    }
+  }
+  return absolutePath;
+}

package/src/common.ts

@@ -0,0 +1,121 @@
+import type { DenyWithReason, PermissionState } from "./types";
+
+export function toRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+
+  return value as Record<string, unknown>;
+}
+
+export function getNonEmptyString(value: unknown): string | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+/** Returns `raw` if it is an array of strings; otherwise `undefined`. */
+export function normalizeOptionalStringArray(
+  raw: unknown,
+): string[] | undefined {
+  return Array.isArray(raw) &&
+    raw.every((p): p is string => typeof p === "string")
+    ? raw
+    : undefined;
+}
+
+/** Returns `raw` if it is a positive integer; otherwise `undefined`. */
+export function normalizeOptionalPositiveInt(raw: unknown): number | undefined {
+  return typeof raw === "number" && Number.isInteger(raw) && raw > 0
+    ? raw
+    : undefined;
+}
+
+export function isPermissionState(value: unknown): value is PermissionState {
+  return value === "allow" || value === "deny" || value === "ask";
+}
+
+/**
+ * Narrow type guard: a raw value representing a DenyWithReason object.
+ * Accepts `{ action: "deny" }` and `{ action: "deny", reason: "…" }`.
+ * Rejects a non-string `reason` to keep malformed config out of the rule set.
+ */
+export function isDenyWithReason(value: unknown): value is DenyWithReason {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  return (
+    record.action === "deny" &&
+    (record.reason === undefined || typeof record.reason === "string")
+  );
+}
+
+type StackNode = { indent: number; target: Record<string, unknown> };
+
+export function parseSimpleYamlMap(input: string): Record<string, unknown> {
+  const root: Record<string, unknown> = {};
+  const stack: StackNode[] = [{ indent: -1, target: root }];
+
+  const lines = input.split(/\r?\n/);
+  for (const rawLine of lines) {
+    if (!rawLine.trim() || rawLine.trimStart().startsWith("#")) {
+      continue;
+    }
+
+    const indent = rawLine.length - rawLine.trimStart().length;
+    const line = rawLine.trim();
+    const separatorIndex = line.indexOf(":");
+    if (separatorIndex <= 0) {
+      continue;
+    }
+
+    const key = line
+      .slice(0, separatorIndex)
+      .trim()
+      .replace(/^['"]|['"]$/g, "");
+    const rawValue = line.slice(separatorIndex + 1).trim();
+
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+      stack.pop();
+    }
+
+    const current = stack[stack.length - 1].target;
+
+    if (!rawValue) {
+      const child: Record<string, unknown> = {};
+      current[key] = child;
+      stack.push({ indent, target: child });
+      continue;
+    }
+
+    let scalar = rawValue;
+    if (
+      (scalar.startsWith('"') && scalar.endsWith('"')) ||
+      (scalar.startsWith("'") && scalar.endsWith("'"))
+    ) {
+      scalar = scalar.slice(1, -1);
+    }
+
+    current[key] = scalar;
+  }
+
+  return root;
+}
+
+export function extractFrontmatter(markdown: string): string {
+  const normalized = markdown.replace(/\r\n/g, "\n");
+  if (!normalized.startsWith("---\n")) {
+    return "";
+  }
+
+  const end = normalized.indexOf("\n---", 4);
+  if (end === -1) {
+    return "";
+  }
+
+  return normalized.slice(4, end);
+}