@andares/pi-toolkits 0.8.0 → 0.9.0

package/src/features/autostart/index.ts

@@ -1,81 +1,120 @@
 /**
- * autostart feature — run project-declared slash commands at session start.
+ * autostart feature — run declared slash commands at session start.
  *
- * Config lives at `<project root>/.pi/autostart.toml` (see autostart.ts for
- * the schema). Execution gates, in order:
+ * Two sources, executed in order, never merged:
  *
- *  1. reason filter — only startup/new/fork replay (see RUNNABLE_REASONS)
- *  2. config file exists — a missing file is a silent opt-in skip
- *  3. `ctx.isProjectTrusted()` — an untrusted project never auto-executes
- *  4. per-command pre-validation against `pi.getCommands()`: only commands
- *     registered by an *extension* are dispatched. This is mandatory:
- *     sendUserMessage with an unhandled "/x" falls through prompt() to the
- *     model as a plain user message (pi agent-session.js), so an unknown
- *     command must be skipped here, never sent.
+ *  1. `<agentDir>/autostart.toml` — the operator's own defaults. Runs in every
+ *     project; no trust gate, because the file lives in pi's config directory
+ *     and is not controlled by the project.
+ *  2. `<project root>/.pi/autostart.toml` — project-declared commands. Gated on
+ *     `ctx.isProjectTrusted()`: an untrusted repository must not execute
+ *     anything.
+ *
+ * Execution gates, in order:
+ *
+ *  - reason filter — only startup/new/fork replay (see RUNNABLE_REASONS)
+ *  - config file exists — a missing file is a silent opt-in skip
+ *  - project trust (project source only)
+ *  - per-command pre-validation against `pi.getCommands()`: only commands
+ *    registered by an *extension* are dispatched. This is mandatory:
+ *    sendUserMessage with an unhandled "/x" falls through prompt() to the
+ *    model as a plain user message (pi agent-session.js), so an unknown
+ *    command must be skipped here, never sent.
  *
  * Dispatch uses `sendUserMessage(cmd, { expandPromptTemplates: true })` —
  * that flag is what routes "/cmd args" through _tryExecuteExtensionCommand
- * instead of the model prompt path. The wrapper defaults it to false
- * (each byte-identical across every published version of the supported
- * window, 1.0.0 → 1.3.0; see AGENTS.md host-compat
- * discipline for the version matrix).
+ * instead of the model prompt path. The wrapper defaults it to false in this
+ * package (each byte-identical across every published version of the supported
+ * window, 1.0.0 → 1.3.0; see AGENTS.md host-compat discipline for the version
+ * matrix).
  *
  * Only extension commands can run this way. Built-in commands (/compact,
  * /reload, /resume, …) are dispatched at the TUI layer and cannot be
  * triggered from the extension layer; skill commands (/skill:name) expand
- * into prompts rather than execute. First-party use case: `/add-dir`
- * (pi-add-dir), which is idempotent ("Already added" check).
+ * into prompts rather than execute. First-party use cases: `/add-dir`
+ * (pi-add-dir, idempotent) and `/ask-perm` (session-scoped permission).
  */
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
 	AUTOSTART_CONFIG_PATH,
 	AutostartParseError,
 	commandNameOf,
+	GLOBAL_AUTOSTART_FILENAME,
 	parseAutostartConfig,
 	RUNNABLE_REASONS,
 } from "./autostart.js";
 
-export function registerAutostart(pi: ExtensionAPI): void {
-	pi.on("session_start", async (event, ctx) => {
-		if (!RUNNABLE_REASONS.has(event.reason)) return;
+export interface AutostartOptions {
+	/** pi's config directory; defaults to `getAgentDir()`. */
+	readonly agentDir?: string;
+}
+
+interface Source {
+	readonly path: string;
+	readonly label: string;
+	/** Project sources require trust; the operator's global file does not. */
+	readonly requiresTrust: boolean;
+}
+
+function messageOf(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+export function registerAutostart(
+	pi: ExtensionAPI,
+	options: AutostartOptions = {},
+): void {
+	const agentDir = options.agentDir ?? getAgentDir();
 
+	async function readCommands(
+		ctx: ExtensionContext,
+		source: Source,
+	): Promise<string[] | undefined> {
 		let text: string;
 		try {
-			text = await readFile(join(ctx.cwd, AUTOSTART_CONFIG_PATH), "utf8");
+			text = await readFile(source.path, "utf8");
 		} catch (err) {
 			// Missing file = opt-in skip. Any other read failure (EACCES, EISDIR,
 			// …) is a misconfiguration the operator should hear about.
 			if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
 				ctx.ui.notify(
-					`autostart: skipped — cannot read ${AUTOSTART_CONFIG_PATH}: ${err instanceof Error ? err.message : String(err)}`,
+					`autostart: skipped ${source.label} — cannot read ${source.path}: ${messageOf(err)}`,
 					"warning",
 				);
 			}
-			return;
+			return undefined;
 		}
 
-		let commands: string[];
 		try {
-			commands = parseAutostartConfig(text);
+			return parseAutostartConfig(text);
 		} catch (err) {
 			const message = err instanceof AutostartParseError ? err.message : String(err);
 			ctx.ui.notify(
-				`autostart: skipped — ${message} (${AUTOSTART_CONFIG_PATH})`,
+				`autostart: skipped ${source.label} — ${message} (${source.path})`,
 				"error",
 			);
-			return;
+			return undefined;
 		}
-		if (commands.length === 0) return;
+	}
 
-		if (!ctx.isProjectTrusted()) {
-			ctx.ui.notify(
-				`autostart: skipped — project not trusted (${AUTOSTART_CONFIG_PATH})`,
-				"warning",
-			);
-			return;
-		}
+	pi.on("session_start", async (event, ctx) => {
+		if (!RUNNABLE_REASONS.has(event.reason)) return;
+
+		const sources: Source[] = [
+			{
+				path: join(agentDir, GLOBAL_AUTOSTART_FILENAME),
+				label: "global config",
+				requiresTrust: false,
+			},
+			{
+				path: join(ctx.cwd, AUTOSTART_CONFIG_PATH),
+				label: "project config",
+				requiresTrust: true,
+			},
+		];
 
 		// Only extension-registered commands are dispatchable; skill and
 		// prompt-template entries expand rather than execute.
@@ -87,23 +126,36 @@ export function registerAutostart(pi: ExtensionAPI): void {
 				),
 		);
 
-		for (const command of commands) {
-			const name = commandNameOf(command);
-			if (!name || !dispatchable.has(name)) {
+		for (const source of sources) {
+			const commands = await readCommands(ctx, source);
+			if (commands === undefined || commands.length === 0) continue;
+
+			if (source.requiresTrust && !ctx.isProjectTrusted()) {
 				ctx.ui.notify(
-					`autostart: skipped "${command}" — not a registered extension command`,
+					`autostart: skipped ${source.label} — project not trusted (${source.path})`,
 					"warning",
 				);
 				continue;
 			}
-			// One failing command must not cancel the rest of the list.
-			try {
-				await pi.sendUserMessage(command, { expandPromptTemplates: true });
-			} catch (err) {
-				ctx.ui.notify(
-					`autostart: "${command}" failed — ${err instanceof Error ? err.message : String(err)}`,
-					"error",
-				);
+
+			for (const command of commands) {
+				const name = commandNameOf(command);
+				if (!name || !dispatchable.has(name)) {
+					ctx.ui.notify(
+						`autostart: skipped "${command}" — not a registered extension command`,
+						"warning",
+					);
+					continue;
+				}
+				// One failing command must not cancel the rest of the list.
+				try {
+					await pi.sendUserMessage(command, { expandPromptTemplates: true });
+				} catch (err) {
+					ctx.ui.notify(
+						`autostart: "${command}" failed — ${messageOf(err)}`,
+						"error",
+					);
+				}
 			}
 		}
 	});

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

@@ -0,0 +1,60 @@
+/**
+ * Fixed safety tables: credential paths are denied in every mode, destructive
+ * commands always ask.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { dangerReason, secretReason } from "./constants.js";
+
+const HOME = homedir();
+
+describe("secrets table", () => {
+	it("covers the credential directories exactly", () => {
+		expect(secretReason(join(HOME, ".ssh", "id_rsa"))).toBe("credentials");
+		expect(secretReason(join(HOME, ".ssh"))).toBe("credentials");
+		expect(secretReason(join(HOME, ".gnupg", "private-keys-v1.d"))).toBe("credentials");
+		expect(secretReason(join(HOME, ".aws", "credentials"))).toBe("credentials");
+	});
+
+	it("does not over-match a sibling prefix", () => {
+		expect(secretReason(join(HOME, ".ssh-easy", "x"))).toBeUndefined();
+		expect(secretReason(join(HOME, ".ssh_evil", "x"))).toBeUndefined();
+		expect(secretReason(join(HOME, ".awsconfig", "x"))).toBeUndefined();
+	});
+
+	it("covers pi auth files but nothing else under the agent dir", () => {
+		expect(secretReason(join(HOME, ".pi", "agent", "auth.json"))).toBe("pi credentials");
+		expect(secretReason(join(HOME, ".pi", "agent", "auth-foo.json"))).toBe("pi credentials");
+		expect(secretReason(join(HOME, ".pi", "agent", "settings.json"))).toBeUndefined();
+		expect(secretReason(join(HOME, ".pi", "agent", "xauth", "auth.json"))).toBeUndefined();
+	});
+
+	it("covers .env files but not the templates", () => {
+		expect(secretReason("/proj/.env")).toBe("environment file");
+		expect(secretReason("/proj/.env.local")).toBe("environment file");
+		expect(secretReason("/proj/.env.example")).toBeUndefined();
+	});
+});
+
+describe("danger table", () => {
+	it("catches the destructive core", () => {
+		expect(dangerReason("rm", ["-rf", "/"], ["/"], "/proj")).toContain("recursive delete");
+		expect(dangerReason("rm", ["-rf", HOME], [HOME], "/proj")).toContain("recursive delete");
+		expect(dangerReason("rm", ["-rf", "/proj"], ["/proj"], "/proj")).toContain("recursive delete");
+		expect(dangerReason("git", ["push", "--force"], [], "/proj")).toBe("forced git push");
+		expect(dangerReason("git", ["push", "-f"], [], "/proj")).toBe("forced git push");
+		expect(dangerReason("git", ["reset", "--hard"], [], "/proj")).toBe("git reset --hard");
+		expect(dangerReason("git", ["clean", "-fd"], [], "/proj")).toBe("git clean -f");
+		expect(dangerReason("npm", ["publish"], [], "/proj")).toBe("package publish");
+		expect(dangerReason("dd", ["of=/dev/sda"], ["/dev/sda"], "/proj")).toBe("raw device write");
+		expect(dangerReason("sudo", ["rm", "x"], ["/proj/x"], "/proj")).toBe("privileged command");
+	});
+
+	it("does not flag ordinary commands", () => {
+		expect(dangerReason("rm", ["-rf", "/proj/build"], ["/proj/build"], "/proj")).toBeUndefined();
+		expect(dangerReason("git", ["push"], [], "/proj")).toBeUndefined();
+		expect(dangerReason("git", ["log"], [], "/proj")).toBeUndefined();
+		expect(dangerReason("npm", ["view", "react"], [], "/proj")).toBeUndefined();
+	});
+});

package/src/features/permission/constants.ts

@@ -0,0 +1,158 @@
+/**
+ * permission feature — modes, labels, and the fixed safety tables.
+ *
+ * The four modes are deliberately small: project boundary (in/out) crossed
+ * with operation kind (read/write, exec folded into write). There is no rule
+ * matrix — session grants cover the exceptions.
+ *
+ * Two tables sit outside the four modes on purpose:
+ *  - {@link SECRET_ROOTS} / {@link isSecretFile}: reads and writes of
+ *    credential material are denied in every mode. Without this, the default
+ *    `outside read = allow` would hand the agent `~/.ssh/id_rsa`.
+ *  - {@link DANGER_REASON}: destructive commands are always asked about, even
+ *    when their scope says allow (`rm -rf .` inside the project is still a
+ *    guarded operation). Scope alone cannot express "destructive".
+ */
+import { homedir } from "node:os";
+import { basename, join, sep } from "node:path";
+
+/** Three-way mode, used for outside-project operations. */
+export type TriMode = "ask" | "allow" | "deny";
+
+/** Two-way mode, used for inside-project operations. */
+export type PairMode = "ask" | "allow";
+
+/** What one tool call does to the filesystem. */
+export type Effect = "read" | "write";
+
+/** The four permission modes, all at once. */
+export interface PermissionModes {
+	inRead: PairMode;
+	inWrite: PairMode;
+	outRead: TriMode;
+	outWrite: TriMode;
+}
+
+/**
+ * Defaults: project-internal work is uninterrupted; outside reads are allowed
+ * (the secrets table is what protects credentials); outside writes ask.
+ */
+export const DEFAULT_MODES: PermissionModes = {
+	inRead: "allow",
+	inWrite: "allow",
+	outRead: "allow",
+	outWrite: "ask",
+};
+
+/** Footer status key (extension-scoped; `/ask` uses its own). */
+export const PERMISSION_STATUS_KEY = "perm-mode";
+
+/** Values offered by the mode panel, in cycle order. */
+export const IN_VALUES: readonly PairMode[] = ["allow", "ask"];
+export const OUT_VALUES: readonly TriMode[] = ["allow", "ask", "deny"];
+
+/**
+ * Credential locations denied in every mode. `~` is expanded at match time so
+ * the table survives a moved home directory.
+ */
+export const SECRET_ROOTS: readonly string[] = [
+	"~/.ssh",
+	"~/.gnupg",
+	"~/.aws",
+	"~/.pi/agent/auth.json",
+];
+
+/** `.env` family: secrets by convention, except the sample templates. */
+const ENV_TEMPLATES = new Set([".env.example", ".env.sample", ".env.template"]);
+
+/** pi's own credential files other than the exact `auth.json` entry. */
+function isPiAuthFile(pathValue: string): boolean {
+	const authPrefix = join(homedir(), ".pi", "agent", "auth");
+	return pathValue.startsWith(authPrefix) && basename(pathValue).endsWith(".json");
+}
+
+/** Containment: `pathValue` is `root` itself or under it (with sep boundaries). */
+function pathWithin(root: string, pathValue: string): boolean {
+	const a = process.platform === "win32" ? root.toLowerCase() : root;
+	const b = process.platform === "win32" ? pathValue.toLowerCase() : pathValue;
+	return b === a || b.startsWith(a.endsWith(sep) ? a : `${a}${sep}`);
+}
+
+/** `true` when `pathValue` is `.env`-shaped and not a template. */
+function isSecretEnvFile(pathValue: string): boolean {
+	const name = basename(pathValue);
+	if (ENV_TEMPLATES.has(name)) return false;
+	return name === ".env" || name.startsWith(".env.");
+}
+
+/** Absolute secret prefixes, `~` expanded. */
+export function secretRoots(): string[] {
+	return SECRET_ROOTS.map((root) =>
+		root.startsWith("~") ? join(homedir(), root.slice(1)) : root,
+	);
+}
+
+/** Why `pathValue` is secret, or `undefined` when it is not. */
+export function secretReason(pathValue: string): string | undefined {
+	if (isPiAuthFile(pathValue)) return "pi credentials";
+	if (isSecretEnvFile(pathValue)) return "environment file";
+	for (const root of secretRoots()) {
+		if (pathWithin(root, pathValue)) return "credentials";
+	}
+	return undefined;
+}
+
+/**
+ * Commands always confirmed regardless of mode. Returns the human-facing
+ * reason, or `undefined` for an ordinary command.
+ *
+ * `targets` are the unit's already-resolved absolute paths.
+ */
+export function dangerReason(
+	command: string,
+	args: readonly string[],
+	targets: readonly string[],
+	base: string | null,
+): string | undefined {
+	const home = homedir();
+	const inDangerousRoot = (pathValue: string): boolean =>
+		pathValue === "/" ||
+		pathValue === home ||
+		(base !== null && pathValue === base);
+
+	if (command === "sudo" || command === "doas") return "privileged command";
+	if (command === "rm" && targets.some(inDangerousRoot)) {
+		return "recursive delete of /, the home directory, or the working directory";
+	}
+	if (command === "git") {
+		const [verb, ...rest] = args;
+		if (verb === "reset" && rest.includes("--hard")) return "git reset --hard";
+		if (verb === "clean" && rest.some((a) => /^-[a-zA-Z]*f/.test(a))) {
+			return "git clean -f";
+		}
+		if (verb === "push" && rest.some((a) => a === "-f" || a === "--force")) {
+			return "forced git push";
+		}
+	}
+	if (
+		["npm", "pnpm", "yarn", "bun"].includes(command) &&
+		args[0] === "publish"
+	) {
+		return "package publish";
+	}
+	if (command === "dd" && targets.some((t) => t.startsWith("/dev/"))) {
+		return "raw device write";
+	}
+	if (command.startsWith("mkfs")) return "filesystem creation";
+	if (["shutdown", "reboot", "poweroff", "halt"].includes(command)) {
+		return "system power command";
+	}
+	if (
+		command === "chmod" &&
+		args.some((a) => /^-[a-zA-Z]*R/.test(a)) &&
+		args.includes("777")
+	) {
+		return "recursive world-writable chmod";
+	}
+	return undefined;
+}