@andares/pi-toolkits 0.8.0 → 0.9.0

package/src/features/permission/prompt.ts

@@ -0,0 +1,146 @@
+/**
+ * permission feature — the confirmation dialog.
+ *
+ * Four answers, hotkey-first because this dialog appears mid-run and should be
+ * answerable with one keystroke:
+ *
+ *   a — allow once
+ *   s — allow this directory for the session
+ *   d — deny once
+ *   f — deny this directory for the session
+ *
+ * `SelectList` provides rendering, ↑↓ and Enter; the wrapper maps the four
+ * letters. Non-TUI dialog modes get the host's plain selector; with no UI at
+ * all the caller's `present` resolves `undefined` (fail closed).
+ */
+import { getSelectListTheme } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	type Component,
+	type KeyId,
+	matchesKey,
+	SelectList,
+	Text,
+} from "@earendil-works/pi-tui";
+import type { AskDecision } from "../../lib/gates.js";
+
+export interface PermissionPromptInput {
+	readonly title: string;
+	readonly details: readonly string[];
+}
+
+interface Option {
+	readonly value: AskDecision;
+	readonly key: KeyId;
+	readonly label: string;
+	readonly description: string;
+}
+
+function optionsFor(): Option[] {
+	return [
+		{
+			value: "allow",
+			key: "a",
+			label: "Allow once (a)",
+			description: "Run this call only",
+		},
+		{
+			value: "allow-session",
+			key: "s",
+			label: "Allow for this session (s)",
+			description: "Stop asking for this operation until the session ends",
+		},
+		{
+			value: "deny",
+			key: "d",
+			label: "Deny (d)",
+			description: "Block this call",
+		},
+		{
+			value: "deny-session",
+			key: "f",
+			label: "Deny for this session (f)",
+			description: "Block this operation until the session ends",
+		},
+	];
+}
+
+/** Header plus a hotkey-aware `SelectList`. */
+class PromptComponent implements Component {
+	constructor(
+		private readonly header: Text,
+		private readonly list: SelectList,
+		private readonly options: readonly Option[],
+		private readonly choose: (value: AskDecision) => void,
+	) {}
+
+	handleInput(data: string): void {
+		const hit = this.options.find((option) => matchesKey(data, option.key));
+		if (hit) {
+			this.choose(hit.value);
+			return;
+		}
+		this.list.handleInput(data);
+	}
+
+	render(width: number): string[] {
+		return [...this.header.render(width), ...this.list.render(width)];
+	}
+
+	invalidate(): void {
+		this.header.invalidate();
+		this.list.invalidate();
+	}
+}
+
+/**
+ * Ask the operator. Resolves `undefined` when there is no way to ask or the
+ * dialog was cancelled.
+ */
+export async function askPermission(
+	ctx: ExtensionContext,
+	input: PermissionPromptInput,
+): Promise<AskDecision | undefined> {
+	if (!ctx.hasUI) return undefined;
+	const options = optionsFor();
+
+	if (ctx.mode !== "tui") {
+		const labels = options.map((option) => option.label);
+		const choice = await ctx.ui.select(input.title, labels);
+		if (choice === undefined) return undefined;
+		return options[labels.indexOf(choice)]?.value;
+	}
+
+	return ctx.ui.custom<AskDecision | undefined>(
+		(_tui, theme, _keybindings, done) => {
+			let settled = false;
+			const finish = (value: AskDecision | undefined): void => {
+				if (settled) return;
+				settled = true;
+				done(value);
+			};
+			const header = new Text(
+				[
+					theme.fg("accent", input.title),
+					...input.details.map((line) => theme.fg("muted", line)),
+					theme.fg(
+						"dim",
+						"a allow · s allow session · d deny · f deny session · esc cancel",
+					),
+				].join("\n"),
+			);
+			const list = new SelectList(
+				options.map((option) => ({
+					value: option.value,
+					label: option.label,
+					description: option.description,
+				})),
+				6,
+				getSelectListTheme(),
+			);
+			list.onSelect = (item) => finish(item.value as AskDecision);
+			list.onCancel = () => finish(undefined);
+			return new PromptComponent(header, list, options, finish);
+		},
+	);
+}

package/src/features/permission/session-rules.ts

@@ -0,0 +1,99 @@
+/**
+ * permission feature — session-scoped grants.
+ *
+ * Ephemeral by design: an allow/deny recorded here lives only in this process
+ * and is cleared when the mode is switched off or the session ends. Nothing is
+ * written to disk, so a forgotten toggle cannot outlive the session it was
+ * meant for.
+ *
+ * A grant is `(effect, directory root)`. Read grants do not imply write grants.
+ * Matching is containment — no globs — because the operator grants "this
+ * directory", not "this pattern".
+ */
+import type { Effect } from "./constants.js";
+import { insideAnyRoot } from "./paths.js";
+
+/** One session-scoped allow or deny. */
+export interface Grant {
+	readonly effect: Effect;
+	/** Canonical directory root; the file that triggered it was folded in. */
+	readonly root: string;
+}
+
+export class SessionRules {
+	private readonly allowList: Grant[] = [];
+	private readonly denyList: Grant[] = [];
+	/**
+	 * Grants for commands that cannot be resolved to a path (an opaque unit).
+	 * Keyed on the command text, so only the exact command is covered.
+	 */
+	private readonly allowedCommands = new Set<string>();
+	private readonly deniedCommands = new Set<string>();
+
+	/** Record an allow for `(effect, root)`; replaces an identical grant. */
+	allow(grant: Grant): void {
+		this.add(this.allowList, grant);
+	}
+
+	/** Record a deny for `(effect, root)`; replaces an identical grant. */
+	deny(grant: Grant): void {
+		this.add(this.denyList, grant);
+	}
+
+	private add(list: Grant[], grant: Grant): void {
+		const index = list.findIndex(
+			(entry) => entry.effect === grant.effect && entry.root === grant.root,
+		);
+		if (index >= 0) list[index] = grant;
+		else list.push(grant);
+	}
+
+	/** `true` when an allow covers this access. */
+	allows(effect: Effect, pathValue: string): boolean {
+		return this.allowList.some(
+			(grant) =>
+				grant.effect === effect && insideAnyRoot([grant.root], pathValue),
+		);
+	}
+
+	/** `true` when a deny covers this access. */
+	denies(effect: Effect, pathValue: string): boolean {
+		return this.denyList.some(
+			(grant) =>
+				grant.effect === effect && insideAnyRoot([grant.root], pathValue),
+		);
+	}
+
+	/** Record an allow for an opaque command's exact text. */
+	allowCommand(command: string): void {
+		this.allowedCommands.add(command);
+	}
+
+	/** Record a deny for an opaque command's exact text. */
+	denyCommand(command: string): void {
+		this.deniedCommands.add(command);
+	}
+
+	/** `true` when this exact command was allowed for the session. */
+	allowsCommand(command: string): boolean {
+		return this.allowedCommands.has(command);
+	}
+
+	/** `true` when this exact command was denied for the session. */
+	deniesCommand(command: string): boolean {
+		return this.deniedCommands.has(command);
+	}
+
+	/** Drop every grant (mode off, session boundary). */
+	clear(): void {
+		this.allowList.length = 0;
+		this.denyList.length = 0;
+		this.allowedCommands.clear();
+		this.deniedCommands.clear();
+	}
+
+	/** Counts for `/ask-perm status` and tests. */
+	counts(): { allow: number; deny: number } {
+		return { allow: this.allowList.length, deny: this.denyList.length };
+	}
+}

package/src/features/permission/units.test.ts

@@ -0,0 +1,205 @@
+/**
+ * Bash decomposition: segments, wrappers, substitution, cd folding, redirects,
+ * read/write classification, and the fail-closed cases.
+ */
+import { homedir } from "node:os";
+import { describe, expect, it } from "vitest";
+import { parseCommandUnits, stripHeredocs, type CommandUnit } from "./units.js";
+
+const CWD = "/proj";
+const HOME = homedir();
+
+function summary(command: string) {
+	return parseCommandUnits(command, CWD).map((unit) => ({
+		command: unit.command,
+		head: unit.headWord,
+		effect: unit.effect,
+		opaque: unit.opaque,
+		base: unit.base,
+		targets: unit.targets.map((target) => `${target.effect}:${target.path}`),
+	}));
+}
+
+function first(command: string): CommandUnit {
+	return parseCommandUnits(command, CWD)[0];
+}
+
+describe("segments and cd folding", () => {
+	it("splits on && and folds cd into the following command", () => {
+		const units = summary("cd /tmp && rm x");
+		expect(units).toHaveLength(2);
+		expect(units[0]).toMatchObject({ command: "cd", base: CWD, targets: ["read:/tmp"] });
+		expect(units[1]).toMatchObject({ command: "rm", base: "/tmp", targets: ["write:/tmp/x"] });
+	});
+
+	it("splits pipelines and keeps quoted operators as data", () => {
+		expect(summary("cat a | grep x")).toHaveLength(2);
+		expect(summary('echo "a && b"')).toHaveLength(1);
+	});
+
+	it("strips leading VAR=value assignments", () => {
+		expect(first("FOO=bar rm x").command).toBe("rm");
+		expect(first("FOO=bar rm x").headWord).toBe("rm");
+	});
+
+	it("returns no units for an empty command", () => {
+		expect(parseCommandUnits("   ", CWD)).toEqual([]);
+	});
+});
+
+describe("wrappers and nested execution", () => {
+	it("peels sudo and keeps the wrapper visible", () => {
+		const unit = first("sudo -u root rm -rf /");
+		expect(unit).toMatchObject({ command: "rm", headWord: "sudo" });
+		expect(unit.targets).toEqual([{ path: "/", effect: "write", source: "operand" }]);
+	});
+
+	it("peels xargs and env", () => {
+		expect(first("xargs -I{} rm {}").command).toBe("rm");
+		expect(first("env FOO=bar rm x").command).toBe("rm");
+	});
+
+	it("recurses into bash -c payloads", () => {
+		const unit = first("bash -c 'rm -rf /tmp/x'");
+		expect(unit).toMatchObject({ command: "rm", opaque: false });
+		expect(unit.targets[0]?.path).toBe("/tmp/x");
+	});
+
+	it("finds a substitution inside a quoted word", () => {
+		const units = summary('echo "x$(rm y)"');
+		expect(units[0]).toMatchObject({ command: "rm", targets: ["write:/proj/y"] });
+		expect(units[1]?.command).toBe("echo");
+	});
+
+	it("recurses into command substitution", () => {
+		const units = summary("echo $(rm -rf /tmp/x)");
+		expect(units[0]).toMatchObject({
+			command: "rm",
+			effect: "write",
+			targets: ["write:/tmp/x"],
+		});
+		expect(units[1]).toMatchObject({ command: "echo", effect: "read" });
+	});
+
+	it("recurses into find -exec", () => {
+		const units = summary("find . -name x -exec rm {} \\;");
+		expect(units.map((unit) => unit.command)).toContain("rm");
+	});
+});
+
+describe("redirects and heredocs", () => {
+	it("classifies redirect targets and ignores /dev/null", () => {
+		expect(summary("ls 2>/dev/null")[0]?.targets).toEqual([]);
+		expect(summary("echo hi > /tmp/x")[0]?.targets).toEqual(["write:/tmp/x"]);
+		expect(summary("cat < input > output")[0]?.targets).toEqual([
+			"read:/proj/input",
+			"write:/proj/output",
+		]);
+	});
+
+	it("treats a redirect to a credential path as a write to it", () => {
+		expect(summary("echo a > ~/.ssh/authorized_keys")[0]?.targets).toEqual([
+			`write:${HOME}/.ssh/authorized_keys`,
+		]);
+	});
+
+	it("keeps the redirect target as the target, not the command name", () => {
+		expect(summary("ls > out.txt")[0]?.targets).toEqual(["write:/proj/out.txt"]);
+		expect(summary("ls >> out.txt")[0]?.targets).toEqual(["write:/proj/out.txt"]);
+		expect(summary("ls 2> err.txt")[0]?.targets).toEqual(["write:/proj/err.txt"]);
+	});
+
+	it("strips heredoc bodies and keeps the redirect", () => {
+		const unit = first("cat > f <<EOF\nhello\nEOF");
+		expect(unit).toMatchObject({ command: "cat", effect: "write" });
+		expect(unit.targets).toEqual([{ path: "/proj/f", effect: "write", source: "redirect" }]);
+	});
+
+	it("marks an unterminated heredoc opaque", () => {
+		expect(stripHeredocs("cat <<EOF\nunterminated")).toBeUndefined();
+		expect(first("cat <<EOF\nunterminated").opaque).toBe(true);
+	});
+});
+
+describe("read/write classification", () => {
+	it("knows read and write commands", () => {
+		expect(first("git log").effect).toBe("read");
+		expect(first("git push").effect).toBe("write");
+		expect(first("pnpm view react").effect).toBe("read");
+		expect(first("pnpm install").effect).toBe("write");
+		expect(first("cat notes.txt").effect).toBe("read");
+	});
+
+	it("withdraws a read claim for write-capable options", () => {
+		const sed = first("sed -i s/a/b/ f.txt");
+		expect(sed.effect).toBe("write");
+		expect(sed.targets).toEqual([
+			{ path: "/proj/f.txt", effect: "write", source: "operand" },
+		]);
+		expect(first("sort -o out.txt f").targets).toEqual([
+			{ path: "/proj/out.txt", effect: "write", source: "operand" },
+		]);
+	});
+
+	it("treats unknown commands as writes", () => {
+		expect(first("frobnicate x").effect).toBe("write");
+	});
+});
+
+describe("paths", () => {
+	it("treats rm/mv/cp operands as targets even when bare", () => {
+		expect(summary("rm notes.txt")[0]?.targets).toEqual(["write:/proj/notes.txt"]);
+		expect(summary("cp a b")[0]?.targets).toEqual(["write:/proj/a", "write:/proj/b"]);
+	});
+
+	it("resolves git -C against the -C directory, not the base", () => {
+		expect(summary("git -C ../other log")[0]?.targets).toEqual([
+			"read:/other",
+		]);
+		expect(summary("git -C /tmp log")[0]?.targets).toEqual(["read:/tmp"]);
+		expect(summary("git -C \"$DIR\" log")[0]?.opaque).toBe(true);
+	});
+
+	it("collapses a glob to the directory it expands in", () => {
+		expect(summary("rm -rf *")[0]?.targets).toEqual([`write:${CWD}`]);
+	});
+
+	it("does not treat URLs as paths", () => {
+		expect(summary("curl -o /tmp/x https://example.com/a")[0]?.targets).toEqual([
+			"write:/tmp/x",
+		]);
+	});
+
+	it("expands ~ while parsing", () => {
+		expect(summary("tee ~/x")[0]?.targets).toEqual([`write:${HOME}/x`]);
+	});
+});
+
+describe("fail closed", () => {
+	it("marks an unresolved variable in a path position opaque", () => {
+		expect(summary("echo $UNKNOWN/x")).toEqual([
+			expect.objectContaining({ opaque: true, targets: [] }),
+		]);
+	});
+
+	it("marks a non-literal cd and its following relative command opaque", () => {
+		const units = summary('cd "$DIR" && rm x');
+		expect(units[0]?.opaque).toBe(true);
+		expect(units[1]?.opaque).toBe(true);
+		expect(units[1]?.base).toBeNull();
+	});
+
+	it("ignores comments, including apostrophes inside them", () => {
+		expect(first("echo hi # it's fine").opaque).toBe(false);
+		expect(first("echo hi # a 'quote").opaque).toBe(false);
+		expect(first("echo hi # x '").targets).toEqual([]);
+	});
+
+	it("marks unbalanced quoting opaque", () => {
+		expect(first('echo "unclosed').opaque).toBe(true);
+	});
+
+	it("marks a non-literal shell payload opaque", () => {
+		expect(first('bash -c "$CMD"').opaque).toBe(true);
+	});
+});