@andares/pi-toolkits 0.8.0 → 0.9.0

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

@@ -0,0 +1,66 @@
+/**
+ * Mode defaults, argument parsing, and formatting.
+ */
+import { describe, expect, it } from "vitest";
+import { DEFAULT_MODES, IN_VALUES, OUT_VALUES } from "./constants.js";
+import { formatModes, parsePermissionArgs, shortMode } from "./modes.js";
+
+describe("modes", () => {
+	it("ships the documented defaults", () => {
+		expect(DEFAULT_MODES).toEqual({
+			inRead: "allow",
+			inWrite: "allow",
+			outRead: "allow",
+			outWrite: "ask",
+		});
+		expect(IN_VALUES).toEqual(["allow", "ask"]);
+		expect(OUT_VALUES).toEqual(["allow", "ask", "deny"]);
+	});
+
+	it("merges missing arguments from the defaults", () => {
+		expect(parsePermissionArgs("ask")).toEqual({
+			modes: { inRead: "ask", inWrite: "allow", outRead: "allow", outWrite: "ask" },
+		});
+		expect(parsePermissionArgs("ask ask")).toEqual({
+			modes: { inRead: "ask", inWrite: "ask", outRead: "allow", outWrite: "ask" },
+		});
+		expect(parsePermissionArgs("ask allow deny deny")).toEqual({
+			modes: { inRead: "ask", inWrite: "allow", outRead: "deny", outWrite: "deny" },
+		});
+	});
+
+	it("uses the current defaults, not the previous mode, for omitted arguments", () => {
+		const parsed = parsePermissionArgs("allow");
+		expect("modes" in parsed ? parsed.modes : undefined).toEqual(DEFAULT_MODES);
+	});
+
+	it("rejects deny for in-project modes", () => {
+		expect(parsePermissionArgs("deny")).toEqual({
+			error: expect.stringContaining("in-read"),
+		});
+	});
+
+	it("rejects unknown values and too many arguments", () => {
+		expect(parsePermissionArgs("maybe")).toEqual({
+			error: expect.stringContaining("in-read"),
+		});
+		expect(parsePermissionArgs("allow allow allow nope")).toEqual({
+			error: expect.stringContaining("out-write"),
+		});
+		expect(parsePermissionArgs("allow allow allow ask extra")).toEqual({
+			error: expect.stringContaining("at most 4"),
+		});
+		expect(parsePermissionArgs("")).toEqual({
+			error: expect.stringContaining("at least one"),
+		});
+	});
+
+	it("formats the four modes and their short letters", () => {
+		expect(formatModes(DEFAULT_MODES)).toBe("in allow/allow, out allow/ask");
+		expect([shortMode("allow"), shortMode("ask"), shortMode("deny")]).toEqual([
+			"A",
+			"a",
+			"D",
+		]);
+	});
+});

package/src/features/permission/modes.ts

@@ -0,0 +1,82 @@
+/**
+ * permission feature — argument parsing and display formatting.
+ *
+ * `/ask-perm` with no argument toggles: on → off, off → panel. With arguments
+ * it configures and enables in one step (this is the autostart path, and it
+ * never opens a dialog):
+ *
+ *   /ask-perm [in-read] [in-write] [out-read] [out-write]
+ *
+ * Missing arguments take their default value — not the current one — so
+ * `/ask-perm allow` always means "defaults, which also happens to be all
+ * allow on the inside".
+ */
+import {
+	DEFAULT_MODES,
+	IN_VALUES,
+	OUT_VALUES,
+	type PermissionModes,
+	type TriMode,
+} from "./constants.js";
+
+export type ParsedArgs =
+	| { readonly modes: PermissionModes }
+	| { readonly error: string };
+
+function isPair(value: string): boolean {
+	return (IN_VALUES as readonly string[]).includes(value);
+}
+
+function isTri(value: string): boolean {
+	return (OUT_VALUES as readonly string[]).includes(value);
+}
+
+/**
+ * Parse the command arguments. An empty string yields an error — callers must
+ * check for "no arguments" before calling this.
+ */
+export function parsePermissionArgs(raw: string): ParsedArgs {
+	const words = raw.trim().split(/\s+/).filter(Boolean);
+	if (words.length === 0) return { error: "expected at least one mode" };
+	if (words.length > 4) {
+		return { error: "expected at most 4 modes (in-read in-write out-read out-write)" };
+	}
+	const [inRead, inWrite, outRead, outWrite] = words;
+	if (inRead !== undefined && !isPair(inRead)) {
+		return { error: `in-read must be one of ${IN_VALUES.join("|")} (got "${inRead}")` };
+	}
+	if (inWrite !== undefined && !isPair(inWrite)) {
+		return { error: `in-write must be one of ${IN_VALUES.join("|")} (got "${inWrite}")` };
+	}
+	if (outRead !== undefined && !isTri(outRead)) {
+		return { error: `out-read must be one of ${OUT_VALUES.join("|")} (got "${outRead}")` };
+	}
+	if (outWrite !== undefined && !isTri(outWrite)) {
+		return { error: `out-write must be one of ${OUT_VALUES.join("|")} (got "${outWrite}")` };
+	}
+	return {
+		modes: {
+			inRead: (inRead ?? DEFAULT_MODES.inRead) as PermissionModes["inRead"],
+			inWrite: (inWrite ?? DEFAULT_MODES.inWrite) as PermissionModes["inWrite"],
+			outRead: (outRead ?? DEFAULT_MODES.outRead) as TriMode,
+			outWrite: (outWrite ?? DEFAULT_MODES.outWrite) as TriMode,
+		},
+	};
+}
+
+/** `allow/allow · allow/ask`, the human-readable summary used in notices. */
+export function formatModes(modes: PermissionModes): string {
+	return `in ${modes.inRead}/${modes.inWrite}, out ${modes.outRead}/${modes.outWrite}`;
+}
+
+/** Single-letter form for the footer status (`A` allow, `a` ask, `D` deny). */
+export function shortMode(mode: TriMode | "allow"): string {
+	switch (mode) {
+		case "allow":
+			return "A";
+		case "ask":
+			return "a";
+		case "deny":
+			return "D";
+	}
+}

package/src/features/permission/panel.ts

@@ -0,0 +1,118 @@
+/**
+ * permission feature — the mode panel.
+ *
+ * A `SettingsList` (the same component the built-in settings dialogs use)
+ * supplies rendering, ↑↓ navigation, space-cycle and Esc-cancel. A thin
+ * wrapper adds the one behaviour this dialog needs on top: **Enter anywhere
+ * applies the current values**, so typing `/ask-perm` then Enter enables the
+ * defaults without navigating.
+ *
+ * TUI only: `SettingsList` is a custom component, and rpc/print modes cannot
+ * host one. Callers fall back to the argument form there.
+ */
+import { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	type Component,
+	matchesKey,
+	type SettingItem,
+	SettingsList,
+} from "@earendil-works/pi-tui";
+import {
+	IN_VALUES,
+	OUT_VALUES,
+	type PermissionModes,
+} from "./constants.js";
+
+/** Intercepts Enter globally; everything else belongs to the list. */
+class ApplyOnEnter implements Component {
+	constructor(
+		private readonly list: SettingsList,
+		private readonly snapshot: () => PermissionModes,
+		private readonly done: (value: PermissionModes | undefined) => void,
+	) {}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "enter")) {
+			this.done(this.snapshot());
+			return;
+		}
+		this.list.handleInput(data);
+	}
+
+	render(width: number): string[] {
+		return this.list.render(width);
+	}
+
+	invalidate(): void {
+		this.list.invalidate();
+	}
+}
+
+/** Build the settings rows for one mode set. */
+function buildItems(modes: PermissionModes): SettingItem[] {
+	return [
+		{
+			id: "apply",
+			label: "Enable with these modes",
+			description: "Press Enter to enable permission checks",
+			currentValue: "enter",
+		},
+		{
+			id: "inRead",
+			label: "In-project read",
+			description: "Reads inside the working directory and added directories",
+			currentValue: modes.inRead,
+			values: [...IN_VALUES],
+		},
+		{
+			id: "inWrite",
+			label: "In-project write / exec",
+			description: "Writes and command execution inside the project",
+			currentValue: modes.inWrite,
+			values: [...IN_VALUES],
+		},
+		{
+			id: "outRead",
+			label: "Outside read",
+			description: "Reads outside the project boundary",
+			currentValue: modes.outRead,
+			values: [...OUT_VALUES],
+		},
+		{
+			id: "outWrite",
+			label: "Outside write / exec",
+			description: "Writes and execution outside the project boundary",
+			currentValue: modes.outWrite,
+			values: [...OUT_VALUES],
+		},
+	];
+}
+
+/**
+ * Open the mode panel. Resolves with the chosen modes, or `undefined` when the
+ * operator cancels (Esc) or the host cannot render a custom component.
+ */
+export function openPermissionPanel(
+	ctx: ExtensionContext,
+	modes: PermissionModes,
+): Promise<PermissionModes | undefined> {
+	if (!ctx.hasUI || ctx.mode !== "tui") return Promise.resolve(undefined);
+
+	return ctx.ui.custom<PermissionModes | undefined>(
+		(_tui, _theme, _keybindings, done) => {
+			let current: PermissionModes = { ...modes };
+			const items = buildItems(current);
+			const list = new SettingsList(
+				items,
+				8,
+				getSettingsListTheme(),
+				(id, value) => {
+					current = { ...current, [id]: value } as PermissionModes;
+				},
+				() => done(undefined),
+			);
+			return new ApplyOnEnter(list, () => current, done);
+		},
+	);
+}

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

@@ -0,0 +1,111 @@
+/**
+ * Path canonicalization, containment, grant scoping, and add-dir state.
+ */
+import { mkdirSync, mkdtempSync, realpathSync, symlinkSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+	canonicalize,
+	expandHome,
+	grantRoot,
+	insideAnyRoot,
+	isWithin,
+	readAddedDirectories,
+	sessionRoots,
+} from "./paths.js";
+
+function tempProject(): string {
+	return realpathSync(mkdtempSync(join(tmpdir(), "pi-perm-paths-")));
+}
+
+describe("expandHome", () => {
+	it("expands only a leading ~", () => {
+		expect(expandHome("~")).toBe(homedir());
+		expect(expandHome("~/x")).toBe(join(homedir(), "x"));
+		expect(expandHome("~user/x")).toBe("~user/x");
+		expect(expandHome("/abs/~/x")).toBe("/abs/~/x");
+	});
+});
+
+describe("containment", () => {
+	it("matches the root and its contents but not a sibling prefix", () => {
+		expect(isWithin("/a/b", "/a/b")).toBe(true);
+		expect(isWithin("/a/b", "/a/b/c")).toBe(true);
+		expect(isWithin("/a/b", "/a/bc")).toBe(false);
+		expect(isWithin("/a/b", "/a")).toBe(false);
+	});
+
+	it("resolves missing suffixes through the nearest existing ancestor", () => {
+		const root = tempProject();
+		expect(canonicalize(join(root, "missing", "deep", "file"))).toBe(
+			join(realpathSync(root), "missing", "deep", "file"),
+		);
+	});
+
+	it("resolves symlinks, so a link cannot walk out of the root", () => {
+		const root = tempProject();
+		const outside = tempProject();
+		writeFileSync(join(outside, "secret"), "x");
+		symlinkSync(outside, join(root, "link"));
+		const resolved = canonicalize(join(root, "link", "secret"));
+		expect(isWithin(root, resolved)).toBe(false);
+	});
+
+	it("deduplicates and canonicalizes the session roots", () => {
+		const root = tempProject();
+		const outside = tempProject();
+		const roots = sessionRoots(root, [root, outside, outside]);
+		expect(roots).toHaveLength(2);
+		expect(insideAnyRoot(roots, join(outside, "x"))).toBe(true);
+		expect(insideAnyRoot(roots, "/definitely/not/here")).toBe(false);
+	});
+});
+
+describe("grantRoot", () => {
+	it("uses the directory itself for a directory", () => {
+		const root = tempProject();
+		const dir = join(root, "build");
+		mkdirSync(dir);
+		expect(grantRoot(dir)).toBe(dir);
+	});
+
+	it("uses the parent for an existing file", () => {
+		const root = tempProject();
+		const file = join(root, "notes.txt");
+		writeFileSync(file, "x");
+		expect(grantRoot(file)).toBe(root);
+	});
+
+	it("uses the parent for a path that does not exist yet", () => {
+		const root = tempProject();
+		expect(grantRoot(join(root, "build"))).toBe(root);
+	});
+});
+
+describe("readAddedDirectories", () => {
+	it("takes the last add-dir:state entry and ignores other entries", () => {
+		const entries = [
+			{ type: "message" },
+			{ type: "custom", customType: "other", data: { dirs: [{ absolutePath: "/no" }] } },
+			{
+				type: "custom",
+				customType: "add-dir:state",
+				data: { dirs: [{ absolutePath: "/a" }, { absolutePath: "/b" }] },
+			},
+			{
+				type: "custom",
+				customType: "add-dir:state",
+				data: { dirs: [{ absolutePath: "/c" }] },
+			},
+		];
+		expect(readAddedDirectories(entries)).toEqual(["/c"]);
+	});
+
+	it("returns nothing without pi-add-dir state or with a malformed payload", () => {
+		expect(readAddedDirectories([{ type: "message" }])).toEqual([]);
+		expect(
+			readAddedDirectories([{ type: "custom", customType: "add-dir:state", data: {} }]),
+		).toEqual([]);
+	});
+});

package/src/features/permission/paths.ts

@@ -0,0 +1,126 @@
+/**
+ * permission feature — path resolution and containment.
+ *
+ * "Inside the project" means inside the session working directory or inside a
+ * directory added to the session (pi-add-dir stores those in a session entry).
+ * Containment is decided on canonical paths, so `../` and symlinks cannot walk
+ * the check out of a root; a path that does not exist yet is resolved through
+ * its nearest existing ancestor.
+ */
+import { realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve, sep } from "node:path";
+
+/** Expand a leading `~` (and only a leading `~/` or bare `~`). */
+export function expandHome(pathValue: string): string {
+	if (pathValue === "~") return homedir();
+	if (pathValue.startsWith(`~${sep}`) || pathValue.startsWith("~/")) {
+		return join(homedir(), pathValue.slice(2));
+	}
+	return pathValue;
+}
+
+/**
+ * Absolute, symlink-resolved form of `pathValue`.
+ *
+ * The path itself may not exist (a write target, `mkdir` argument, …), so the
+ * nearest existing ancestor is resolved and the missing suffix re-appended.
+ */
+export function canonicalize(pathValue: string): string {
+	const absolute = resolve(pathValue);
+	const suffix: string[] = [];
+	let current = absolute;
+	for (;;) {
+		try {
+			const real = realpathSync.native(current);
+			return suffix.length === 0
+				? real
+				: join(real, ...suffix.reverse());
+		} catch {
+			const parent = dirname(current);
+			if (parent === current) return absolute;
+			suffix.push(basename(current));
+			current = parent;
+		}
+	}
+}
+
+function fold(value: string): string {
+	return process.platform === "win32" ? value.toLowerCase() : value;
+}
+
+/** Whether `pathValue` is `root` or under it. Both must be canonical. */
+export function isWithin(root: string, pathValue: string): boolean {
+	const a = fold(root);
+	const b = fold(pathValue);
+	return b === a || b.startsWith(a.endsWith(sep) ? a : `${a}${sep}`);
+}
+
+/** The directory a session grant on `pathValue` should cover. */
+export function grantRoot(pathValue: string): string {
+	try {
+		return statSync(pathValue).isDirectory() ? pathValue : dirname(pathValue);
+	} catch {
+		// A path that does not exist (a write target, a `mkdir` argument) is
+		// granted at its enclosing directory: the operator is approving an area,
+		// and a per-file grant would ask again for the next sibling.
+		return dirname(pathValue);
+	}
+}
+
+/** Structural shape of a session entry, so no host type is imported here. */
+interface SessionEntryLike {
+	readonly type: string;
+	readonly customType?: string;
+	readonly data?: unknown;
+}
+
+interface AddDirState {
+	readonly dirs?: ReadonlyArray<{ readonly absolutePath?: unknown }>;
+}
+
+/**
+ * Directories added to the session by pi-add-dir.
+ *
+ * pi exposes no directory-list API; pi-add-dir records its state as a session
+ * custom entry (`add-dir:state`, appended on every change). The last such
+ * entry on the branch wins. Absence of pi-add-dir is a normal, silent miss —
+ * only the working directory is then in scope.
+ */
+export function readAddedDirectories(
+	entries: readonly SessionEntryLike[],
+): string[] {
+	let dirs: string[] = [];
+	for (const entry of entries) {
+		if (entry.type !== "custom" || entry.customType !== "add-dir:state") {
+			continue;
+		}
+		const state = entry.data as AddDirState | undefined;
+		if (!Array.isArray(state?.dirs)) continue;
+		dirs = state.dirs
+			.map((dir) =>
+				typeof dir?.absolutePath === "string" ? dir.absolutePath : "",
+			)
+			.filter((dir) => dir !== "");
+	}
+	return dirs;
+}
+
+/** Canonical root list for one session: working directory plus added dirs. */
+export function sessionRoots(cwd: string, added: readonly string[]): string[] {
+	const roots = new Set<string>();
+	for (const value of [cwd, ...added]) {
+		if (!value) continue;
+		roots.add(canonicalize(expandHome(value)));
+	}
+	return [...roots];
+}
+
+/** `true` when `pathValue` is inside at least one root. */
+export function insideAnyRoot(
+	roots: readonly string[],
+	pathValue: string,
+): boolean {
+	return roots.some((root) => isWithin(root, pathValue));
+}
+