@itc-steve/pi-ask-complete 0.1.0

package/src/permission.ts

@@ -0,0 +1,364 @@
+// ask_permission + automatic gate for bash / write / edit / sudo_run / sensitive reads.
+// Path wildcards: most-specific wins; equal score → deny.
+// Prompt: Allow this | Allow for this session | Allow permanently | Deny with reason
+// Bash: every unit is checked; one prompt per tool call (not per unit).
+// Session remembers all ask-bases; permanent writes the primary base only.
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+  baseCommand,
+  isPersistableBashKey,
+  isSudoPrefixed,
+  stripSudoPrefix,
+} from "./base-command.ts";
+import { splitUnits } from "./bash-scan.ts";
+import { describeToolCall } from "./describe-tool.ts";
+import {
+  type PermissionDecision,
+  type PermissionPrompt,
+  runPermissionPanel,
+} from "./permission-panel.ts";
+import { PermissionStore } from "./permission-store.ts";
+
+export type { PermissionDecision };
+export { describeToolCall };
+
+/** Tools that prompt unless allow/deny rule hits. */
+const ASK_TOOLS = new Set(["bash", "write", "edit"]);
+/** Only auto-block on path deny — never prompt on normal reads. */
+const PATH_DENY_TOOLS = new Set(["read", "write", "edit"]);
+
+let queue: Promise<unknown> = Promise.resolve();
+function enqueue<T>(fn: () => Promise<T>): Promise<T> {
+  const run = queue.then(fn, fn);
+  queue = run.then(
+    () => undefined,
+    () => undefined,
+  );
+  return run;
+}
+
+function blockReason(
+  kind: "path" | "bash" | "tool" | "sudo_redirect",
+  label: string,
+  extra?: string,
+): string {
+  if (kind === "sudo_redirect") {
+    return (
+      `Privileged commands must use the sudo_run tool, not bash. ` +
+      `Call sudo_run with command: ${label}` +
+      (extra ? ` (${extra})` : "")
+    );
+  }
+  if (kind === "path") {
+    return (
+      `Blocked by path rule for \`${label}\`. ` +
+      `Add a paths allow entry in permission.json to override.`
+    );
+  }
+  return (
+    `Blocked by permission rule for \`${label}\`. ` +
+    `Add an allow entry in permission.json to override.` +
+    (extra ? ` ${extra}` : "")
+  );
+}
+
+export async function promptPermission(
+  ctx: Pick<ExtensionContext, "ui" | "hasUI">,
+  store: PermissionStore,
+  toolName: string,
+  subject: string,
+  prompt: PermissionPrompt,
+  filePath?: string,
+): Promise<PermissionDecision> {
+  if (!ctx.hasUI) {
+    return {
+      action: "deny",
+      reason: "Action requires approval, but no interactive UI is available.",
+    };
+  }
+
+  return enqueue(async () => {
+    if (store.isAllowed(toolName, subject, filePath)) return { action: "allow_once" };
+    if (store.isDenied(toolName, subject, filePath)) {
+      return {
+        action: "deny",
+        reason: blockReason(filePath ? "path" : "bash", prompt.base),
+      };
+    }
+
+    const decision = await runPermissionPanel(ctx, prompt);
+
+    if (decision.action === "allow_always") {
+      const entry = store.allowPermanently(toolName, subject, filePath);
+      return { action: "allow_always", entry };
+    }
+    if (decision.action === "allow_session") {
+      store.allowSession(toolName, subject, filePath);
+      return { action: "allow_session" };
+    }
+
+    return decision;
+  });
+}
+
+export type BashGateResult =
+  | { ok: true; decision: "already_allowed" | "approved"; entries: string[] }
+  | { ok: false; reason: string; decision: "deny" | "cancelled" };
+
+/**
+ * Gate a bash line: every unit + path arg is checked, but the user is prompted
+ * at most once for the whole tool call. Session allow covers every ask-base;
+ * permanent allow writes only the primary base.
+ */
+export async function gateBashCommand(
+  ctx: Pick<ExtensionContext, "ui" | "hasUI">,
+  store: PermissionStore,
+  command: string,
+  opts?: { cwd?: string; detail?: string },
+): Promise<BashGateResult> {
+  const plan = store.planBash(command, { cwd: opts?.cwd });
+  if (plan.action === "deny") {
+    return {
+      ok: false,
+      decision: "deny",
+      reason: blockReason(plan.kind, plan.label),
+    };
+  }
+  if (plan.action === "allow") {
+    return { ok: true, decision: "already_allowed", entries: [] };
+  }
+
+  // Session remembers every real base in the chain; permanent only the primary.
+  const bases = store.askBases(plan.units);
+  const cmdBase = baseCommand(command);
+  const primary =
+    bases[0] || (isPersistableBashKey(cmdBase) ? cmdBase : "") || "bash";
+
+  const prompt: PermissionPrompt = {
+    base: primary,
+    display: command,
+    detail: opts?.detail?.trim() || undefined,
+    // Fixed short labels (A/B/C) — bases stay out of the option text.
+    session: "Allow for this session",
+    permanent: "Allow permanently",
+  };
+
+  if (!ctx.hasUI) {
+    return {
+      ok: false,
+      decision: "deny",
+      reason: "Action requires approval, but no interactive UI is available.",
+    };
+  }
+
+  const result = await enqueue(async () => {
+    // Re-check after queue wait — a prior session allow may already cover us.
+    const again = store.planBash(command, { cwd: opts?.cwd });
+    if (again.action === "allow") return { action: "allow_once" as const };
+    if (again.action === "deny") {
+      return {
+        action: "deny" as const,
+        reason: blockReason(again.kind, again.label),
+      };
+    }
+    return runPermissionPanel(ctx, prompt);
+  });
+
+  switch (result.action) {
+    case "allow_once":
+      return { ok: true, decision: "approved", entries: [] };
+    case "allow_session": {
+      // Whole chain: every base that still needed approval this call.
+      const entries = store.allowSessionBases(bases.length ? bases : [primary]);
+      return { ok: true, decision: "approved", entries };
+    }
+    case "allow_always": {
+      // C: permanent = primary base only (not every unit in the pipeline).
+      const entries = store.allowPermanentlyBases([primary]);
+      return { ok: true, decision: "approved", entries };
+    }
+    case "deny":
+      return { ok: false, decision: "deny", reason: result.reason };
+    case "cancelled":
+      return {
+        ok: false,
+        decision: "cancelled",
+        reason: "Permission prompt cancelled by user.",
+      };
+  }
+}
+
+const AskPermissionParams = Type.Object({
+  command: Type.String({
+    description: "The system command (or action description) that needs approval",
+  }),
+  detail: Type.Optional(
+    Type.String({
+      description: "Optional extra context shown under the command (why it's needed)",
+    }),
+  ),
+});
+
+export function registerPermission(pi: ExtensionAPI, store: PermissionStore): void {
+  store.ensureUserFile();
+
+  pi.registerTool({
+    name: "ask_permission",
+    label: "Ask Permission",
+    description:
+      "Request user approval before a sensitive system action. Prefer letting the automatic gate handle bash/write/edit/sudo_run — call this only for other sensitive actions. One prompt per call (chains checked as units, prompted once).",
+    parameters: AskPermissionParams,
+    executionMode: "sequential",
+
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const command = params.command;
+      const units = splitUnits(command);
+      const bases = units.map((u) => baseCommand(u) || u);
+
+      const result = await gateBashCommand(ctx, store, command, {
+        cwd: ctx.cwd,
+        detail: params.detail,
+      });
+
+      const payload = result.ok
+        ? {
+            approved: true as const,
+            decision: result.decision,
+            command,
+            bases,
+            entries: result.entries.length ? result.entries : undefined,
+          }
+        : {
+            approved: false as const,
+            decision: result.decision,
+            command,
+            bases,
+            reason: result.reason,
+          };
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+        details: payload,
+      };
+    },
+  });
+
+  pi.on("tool_call", async (event, ctx) => {
+    const toolName = event.toolName;
+    const input = (event.input ?? {}) as Record<string, unknown>;
+
+    // ── bash: one prompt per call; sudo/doas (any unit) → sudo_run redirect ──
+    if (toolName === "bash") {
+      const command = String(input.command ?? "");
+      if (!command.trim()) return undefined;
+
+      // Leading sudo still short-circuits here; mid-chain is caught in planBash.
+      if (isSudoPrefixed(command)) {
+        const inner = stripSudoPrefix(command) || command;
+        return {
+          block: true,
+          reason: blockReason("sudo_redirect", JSON.stringify(inner)),
+        };
+      }
+
+      const result = await gateBashCommand(ctx, store, command, { cwd: ctx.cwd });
+      if (result.ok) return undefined;
+      return { block: true, reason: result.reason };
+    }
+
+    // ── sudo_run: not gated here. pix-sudo's PAM password prompt IS the gate
+    // (no password entered = denied). JSON gating would be redundant. ──
+
+    const isAskTool = ASK_TOOLS.has(toolName);
+    const isPathDenyTool = PATH_DENY_TOOLS.has(toolName);
+    if (!isAskTool && !isPathDenyTool) return undefined;
+
+    const desc = describeToolCall(toolName, input, ctx.cwd);
+    const decision = store.decide(toolName, desc.subject, desc.filePath);
+
+    if (decision.state === "allow") return undefined;
+
+    if (decision.state === "deny") {
+      return {
+        block: true,
+        reason: blockReason(
+          desc.filePath ? "path" : "tool",
+          desc.filePath ?? desc.prompt.base,
+        ),
+      };
+    }
+
+    // state === "ask" — read only auto-denies; never prompt for normal reads
+    if (!isAskTool) return undefined;
+
+    const result = await promptPermission(
+      ctx,
+      store,
+      toolName,
+      desc.subject,
+      desc.prompt,
+      desc.filePath,
+    );
+
+    switch (result.action) {
+      case "allow_once":
+      case "allow_session":
+      case "allow_always":
+        return undefined;
+      case "deny":
+        return { block: true, reason: result.reason };
+      case "cancelled":
+        return { block: true, reason: "Permission prompt cancelled by user." };
+    }
+  });
+
+  pi.on("session_start", () => {
+    store.clearSession();
+    store.reload();
+  });
+
+  pi.registerCommand("permissions", {
+    description: "Show permission allows/denies (bash, tools, path wildcards)",
+    handler: async (_args, ctx) => {
+      store.reload();
+      const { bash, tools, paths, sessionBash, sessionTools, sessionPaths } = store.listAllowed();
+      const denied = store.listDeniedPaths();
+      const lines = [
+        ...(store.yolo
+          ? ["YOLO: on (auto-approving asks; denies + sudo_run redirect still enforced)"]
+          : []),
+        bash.length ? `bash allow: ${bash.join(", ")}` : "bash allow: (none extra)",
+        tools.length ? `tools allow: ${tools.join(", ")}` : "tools allow: (none)",
+        paths.length ? `paths allow:\n  ${paths.join("\n  ")}` : "paths allow: (none extra)",
+        denied.length ? `paths deny: ${denied.length} patterns` : "paths deny: (none)",
+        sessionBash.length || sessionTools.length || sessionPaths.length
+          ? `session: bash[${sessionBash.join(", ") || "—"}] tools[${sessionTools.join(", ") || "—"}] paths[${sessionPaths.length}]`
+          : "session: (none)",
+        "",
+        "bash+sudo → redirected to sudo_run. sudo_run → gated by pix-sudo password prompt.",
+        `File: ${store.filePath}`,
+      ];
+      ctx.ui.notify(lines.join("\n"), "info");
+    },
+  });
+
+  pi.registerCommand("yolo", {
+    description:
+      "Toggle session YOLO (auto-approve asks; deny rules + sudo_run redirect still enforced)",
+    handler: async (args, ctx) => {
+      const a = (args ?? "").trim().toLowerCase();
+      if (a === "on") store.setYolo(true);
+      else if (a === "off") store.setYolo(false);
+      else store.setYolo(!store.yolo);
+
+      ctx.ui.notify(
+        store.yolo
+          ? "YOLO on — auto-approving asks this session. Deny rules and sudo_run redirect are still enforced."
+          : "YOLO off — prompts restored.",
+        "info",
+      );
+    },
+  });
+}

package/src/schema.ts

@@ -0,0 +1,56 @@
+/**
+ * TypeBox schema for the ask_user tool parameters.
+ */
+
+import { Type } from "typebox";
+
+const QuestionOptionSchema = Type.Object({
+  label: Type.String({
+    description: "Short display label for the option (shown on the selection row)",
+  }),
+  description: Type.Optional(
+    Type.String({
+      description:
+        "Short explanation shown under the label (wraps). Add one when the label alone isn't self-explanatory.",
+    }),
+  ),
+  preview: Type.Optional(
+    Type.String({
+      description:
+        "Use this when `description` (a short one-liner) is not enough and the user genuinely benefits from seeing more detail in a side column — e.g. an ASCII layout demo, a code skeleton, a Pro/Cons breakdown, or the reasoning behind why this option is offered and what choosing it entails. Rendered verbatim in a side column (spaces/newlines preserved). Do NOT treat preview as extra text capacity. Every line competes for the user's attention against the option list; only add a preview when the content is worth reading, not just because there's room for more words. If a short `description` already conveys the option, leave preview empty. Most options need only `description`.",
+    }),
+  ),
+});
+
+const QuestionSchema = Type.Object({
+  header: Type.String({
+    description: "Short question title shown in the panel header, e.g. 'Which layout?'",
+  }),
+  tab: Type.String({
+    description:
+      'Short keyword that identifies this question. Shown on the tab bar when there are multiple questions, and returned in the result as the answer\'s prefix. Write it in the user\'s language (e.g. "数据库" or "布局" in a Chinese conversation, "Database" or "Layout" in English), not as a programmatic identifier like "db_choice". Must be unique across questions in one call.',
+  }),
+  prompt: Type.Optional(
+    Type.String({ description: "Optional longer body text shown under the header" }),
+  ),
+  options: Type.Array(QuestionOptionSchema, {
+    description:
+      "Available options. Pass 2-4; each needs a short `label` + a `description`, and a `preview` only when a description can't fully convey the option.",
+  }),
+  multiSelect: Type.Optional(
+    Type.Boolean({
+      description:
+        "If true, the user may check multiple options (space toggles, enter commits). Default false.",
+    }),
+  ),
+  allowSkip: Type.Optional(
+    Type.Boolean({
+      description:
+        "If false, the user MUST answer before proceeding (Tab/Enter with no selection is blocked). Default true. Use false for required questions.",
+    }),
+  ),
+});
+
+export const AskUserParams = Type.Object({
+  questions: Type.Array(QuestionSchema, { description: "One or more questions to ask" }),
+});

package/src/types.ts

@@ -0,0 +1,114 @@
+/**
+ * Shared types and icon constants for pi-ask-user.
+ */
+
+import { Key } from "@earendil-works/pi-tui";
+import type { Editor } from "@earendil-works/pi-tui";
+
+// ────────────────────────────────────────────────────────────────────────────
+// Icon constants — all in U+25A0–25FF Geometric Shapes for font consistency
+// ────────────────────────────────────────────────────────────────────────────
+
+export const ICON_RADIO_EMPTY = "○"; // U+25CB white circle
+export const ICON_RADIO_FILLED = "◉"; // U+25C9 fisheye
+export const ICON_CHECK_EMPTY = "□"; // U+25A1
+export const ICON_CHECK_FILLED = "▣"; // U+25A3
+export const ICON_OTHER = "✎"; // pencil for "Type something."
+export const ICON_CURSOR = "▸"; // current cursor position, independent of selection
+export const ICON_NOTE = ICON_OTHER; // same ✎ pencil as custom answers — the note is also free-form user input
+export const ICON_ANSWER = "›"; // lead glyph on option-pick answers in the result card
+
+// ────────────────────────────────────────────────────────────────────────────
+// Toggle key
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Collapse/expand toggle. Ctrl+\ (0x1c) is free in pi's built-in keybindings
+ * (unlike Ctrl+] which collides with tui.editor.jumpForward) and is not used
+ * as a prefix by tmux/zellij/screen/ssh.
+ */
+export const TOGGLE_KEY = Key.ctrl("\\");
+export const TOGGLE_HINT = "Ctrl+\\";
+
+// ────────────────────────────────────────────────────────────────────────────
+// Types
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface QuestionOption {
+  label: string;
+  description?: string;
+  /** Rich preview shown in the right column when this option is focused. */
+  preview?: string;
+}
+
+export interface RenderOption extends QuestionOption {
+  isOther?: boolean;
+}
+
+export interface Question {
+  /** Internal per-call identity. Never exposed in the tool's JSON result. */
+  id: string;
+  /** Original caller-provided key. Kept byte-for-byte for JSON results. */
+  tab: string;
+  /** Sanitized, non-empty label used exclusively by the TUI. */
+  displayTab: string;
+  header: string;
+  prompt?: string;
+  options: QuestionOption[];
+  multiSelect?: boolean;
+  allowSkip?: boolean;
+}
+
+/** A committed answer. Discriminated by `kind` so every state carries exactly
+ *  the fields it needs — the compiler guarantees completeness, and the three
+ *  display/serialization consumers all derive from `describeAnswer()` (single
+ *  source of truth) so they can never drift apart.
+ *
+ *  - `single`: the user picked one of the offered options.
+ *  - `custom`: single-select, the user typed a custom answer ("Type something.").
+ *  - `multi`:  multi-select — `options` are the picked option labels; an
+ *    optional `custom` carries any typed text alongside them. Pure-custom
+ *    (no options checked) is `options: []` + `custom`; an empty commit
+ *    (skippable, submitted with nothing) is `options: []` with no `custom`.
+ *  - `skipped`: the user navigated past without answering (Tab/arrows).
+ */
+export type Answer =
+  | { id: string; tab: string; kind: "single"; option: string }
+  | { id: string; tab: string; kind: "custom"; text: string }
+  | { id: string; tab: string; kind: "multi"; options: string[]; custom?: string }
+  | { id: string; tab: string; kind: "skipped" };
+
+export interface AskUserResult {
+  questions: Question[];
+  answers: Answer[];
+  cancelled: boolean;
+  /** Free-form note the user can attach on the review screen. Absent when empty. */
+  message?: string;
+}
+
+export interface PanelCallbacks {
+  onResult: (result: AskUserResult) => void;
+}
+
+/** Per-tab ephemeral UI state. Preserved across tab switches. */
+export interface TabState {
+  /** Cursor position (where ▸ is). */
+  cursor: number;
+  /** Vertical scroll offset for the options viewport. */
+  scrollOffset: number;
+  /** Whether "Type something." input mode is active for this tab. */
+  inputMode: boolean;
+  /** This tab's own editor instance (its draft lives inside; no cross-tab sync needed). */
+  editor: Editor;
+  /** Indices of committed options (multi-select). */
+  multiChecked: Set<number>;
+  /** Committed custom text for multi-select mode (kept alongside multiChecked, never overwriting it). Null if none. */
+  customText: string | null;
+  /** Committed single-select index, or -1 if none yet. */
+  selectedSingle: number;
+}
+
+/** Minimal TUI surface the panel/editors depend on. */
+export interface TuiLike {
+  requestRender(): void;
+}

package/src/wildcard.ts

@@ -0,0 +1,102 @@
+/**
+ * Path / command glob matching.
+ *
+ *   *   → any chars except /
+ *   **  → any chars including /
+ *   ?   → one char except /
+ *
+ * Patterns with no `/` also match against the basename
+ * (so `*.env` matches `/a/b/foo.env` and `.env`, but not `.env.example`).
+ */
+
+const MAX_PATTERN = 500;
+
+export function normalizePath(p: string): string {
+  return p.replaceAll("\\", "/").replace(/\/{2,}/g, "/");
+}
+
+/** Compile a glob to a RegExp. Invalid/oversized patterns never match. */
+export function compileGlob(pattern: string): RegExp {
+  if (!pattern || pattern.length > MAX_PATTERN) return /$^/;
+
+  const p = normalizePath(pattern);
+  let out = "^";
+  for (let i = 0; i < p.length; ) {
+    if (p[i] === "*" && p[i + 1] === "*") {
+      if (p[i + 2] === "/") {
+        // **/ → zero or more directories
+        out += "(?:.*/)?";
+        i += 3;
+      } else {
+        out += ".*";
+        i += 2;
+      }
+    } else if (p[i] === "*") {
+      out += "[^/]*";
+      i += 1;
+    } else if (p[i] === "?") {
+      out += "[^/]";
+      i += 1;
+    } else {
+      const c = p[i]!;
+      out += /[.+^${}()|[\]\\]/.test(c) ? `\\${c}` : c;
+      i += 1;
+    }
+  }
+  out += "$";
+  // nosemgrep: pattern is length-bounded + escaped; only * ? ** are wild
+  return new RegExp(out);
+}
+
+export function matchGlob(pattern: string, value: string): boolean {
+  const re = compileGlob(pattern);
+  const norm = normalizePath(value);
+  if (re.test(norm)) return true;
+
+  // File-name-only patterns also match basename
+  if (!pattern.includes("/")) {
+    const base = norm.split("/").pop() ?? norm;
+    if (re.test(base)) return true;
+  }
+  return false;
+}
+
+/**
+ * Specificity score for a glob: more literal (non-wildcard) chars = more
+ * specific; fewer `*` breaks ties. So a deep dotfile deny beats a broad
+ * `Projects` tree allow for the same file even though both match.
+ */
+export function globSpecificity(pattern: string): number {
+  const p = normalizePath(pattern);
+  // Literal chars AFTER the last wildcard pin the filename/tail — the strongest
+  // specificity signal. A pattern ending in `**` (broad tree) pins nothing → 0,
+  // so two trees tie and resolveRules' deny-wins tiebreak decides.
+  const lastWild = Math.max(p.lastIndexOf("*"), p.lastIndexOf("?"));
+  const suffix = lastWild < 0 ? p : p.slice(lastWild + 1);
+  return suffix.replace(/[*?]/g, "").length;
+}
+
+/**
+ * Most-specific matching rule wins, regardless of allow/deny. On an exact
+ * specificity tie, deny wins (fail closed). Returns undefined when nothing
+ * matches.
+ */
+export function resolveRules(
+  rules: ReadonlyArray<{ pattern: string; state: "allow" | "deny" }>,
+  value: string,
+): "allow" | "deny" | undefined {
+  let best: { state: "allow" | "deny"; score: number } | undefined;
+  for (const rule of rules) {
+    if (!matchGlob(rule.pattern, value)) continue;
+    const score = globSpecificity(rule.pattern);
+    if (
+      !best ||
+      score > best.score ||
+      // equal score → deny wins
+      (score === best.score && rule.state === "deny")
+    ) {
+      best = { state: rule.state, score };
+    }
+  }
+  return best?.state;
+}