pi-roundtable 0.22.4 → 0.23.0

package/src/core/modules/host-shell/shell-programs.ts

@@ -0,0 +1,298 @@
+import { assistantName } from "../../i18n/index.ts";
+import { ownPush, type PushPolicy } from "./git-push.ts";
+import { deviceTarget, type LineState, writable } from "./shell-paths.ts";
+
+/**
+ * The hold classes of the shell rule, as `shell.<class>` ids that `HoldRule.holdClasses` lists for
+ * every command a call holds. Yolo mode approves `shell.write` (a write outside the scratch roots)
+ * and `shell.push` (a plain `git push` the push policy holds), and cards the rest unless
+ * `autonomy.yolo.allow` lists them. `shell.unreadable` is a line the rule could not read to the
+ * end, so it holds what it cannot tell apart from a destructive command.
+ */
+export const SHELL_CLASSES = Object.freeze([
+	"shell.privilege",
+	"shell.disk",
+	"shell.power",
+	"shell.kill",
+	"shell.rm",
+	"shell.write",
+	"shell.service",
+	"shell.docker",
+	"shell.firewall",
+	"shell.packages",
+	"shell.push",
+	"shell.force-push",
+	"shell.reset-hard",
+	"shell.gh",
+	"shell.crontab",
+	"shell.unreadable",
+] as const);
+
+export type ShellClass = (typeof SHELL_CLASSES)[number];
+
+/**
+ * The shell classes yolo mode never approves unless `autonomy.yolo.allow` lists them: all of them
+ * but `shell.write` and `shell.push`, the non-destructive ones. A plain push to `main` deploys, so
+ * list `shell.push` in `autonomy.yolo.card` to keep it behind a card.
+ */
+export const YOLO_CARDED_SHELL_CLASSES: readonly string[] = Object.freeze(
+	SHELL_CLASSES.filter((id) => id !== "shell.write" && id !== "shell.push"),
+);
+
+/** Why a command is held, and the class of that reason. */
+export interface Held {
+	reason: string;
+	class: ShellClass;
+}
+
+const SYSTEMD_VERBS = new Set([
+	"start",
+	"stop",
+	"restart",
+	"reload",
+	"try-restart",
+	"reload-or-restart",
+	"enable",
+	"disable",
+	"mask",
+	"unmask",
+	"kill",
+	"isolate",
+]);
+const DOCKER_VERBS = new Set(["stop", "kill", "restart", "rm", "rmi", "prune"]);
+const DOCKER_OBJECTS = new Set([
+	"container",
+	"image",
+	"volume",
+	"network",
+	"system",
+	"builder",
+]);
+const COMPOSE_VERBS = new Set(["down", "stop", "kill", "restart", "rm"]);
+const PACKAGE_VERBS = new Set([
+	"install",
+	"reinstall",
+	"remove",
+	"purge",
+	"autoremove",
+	"upgrade",
+	"full-upgrade",
+	"dist-upgrade",
+]);
+
+/** Whether a push argument forces, deletes or mirrors refs rather than adding commits to them. */
+function rewritesRemote(arg: string): boolean {
+	return (
+		arg === "--mirror" ||
+		arg === "--prune" ||
+		arg === "--delete" ||
+		arg === "-d" ||
+		arg.startsWith("+") ||
+		arg.startsWith(":")
+	);
+}
+
+/** Why a program that is held only with some arguments is, when it is; each has a single reason. */
+export function verbHeld(
+	name: string,
+	args: string[],
+	prefix: string[],
+	state: LineState,
+	policy: PushPolicy,
+): Held | undefined {
+	const verbs = args.filter((a) => !a.startsWith("-"));
+	const because = (
+		held: boolean,
+		reason: string,
+		heldClass: ShellClass,
+	): Held | undefined => (held ? { reason, class: heldClass } : undefined);
+	switch (name) {
+		case "systemctl":
+			return because(
+				verbs.some((v) => SYSTEMD_VERBS.has(v)),
+				"changes a systemd unit",
+				"shell.service",
+			);
+		case "service":
+			return because(
+				verbs.some((v) => ["start", "stop", "restart", "reload"].includes(v)),
+				"changes a service",
+				"shell.service",
+			);
+		case "docker": {
+			const [first, second] = verbs;
+			if (first === "compose")
+				return because(
+					second !== undefined && COMPOSE_VERBS.has(second),
+					`docker compose ${second}`,
+					"shell.docker",
+				);
+			if (first && DOCKER_VERBS.has(first))
+				return { reason: `docker ${first}`, class: "shell.docker" };
+			return because(
+				first !== undefined &&
+					DOCKER_OBJECTS.has(first) &&
+					second !== undefined &&
+					(DOCKER_VERBS.has(second) || second === "remove"),
+				`docker ${first} ${second}`,
+				"shell.docker",
+			);
+		}
+		case "docker-compose":
+			return because(
+				verbs[0] !== undefined && COMPOSE_VERBS.has(verbs[0]),
+				`docker-compose ${verbs[0]}`,
+				"shell.docker",
+			);
+		case "ufw":
+			return because(
+				!(verbs[0] === "status" || verbs.length === 0),
+				"changes the firewall",
+				"shell.firewall",
+			);
+		case "iptables":
+		case "ip6tables":
+		case "nft":
+			return because(
+				!args.some((a) => ["-L", "--list", "-S", "list"].includes(a)),
+				"changes the firewall",
+				"shell.firewall",
+			);
+		case "apt":
+		case "apt-get":
+		case "snap":
+			return because(
+				verbs.some((v) => PACKAGE_VERBS.has(v)),
+				"installs or removes packages",
+				"shell.packages",
+			);
+		case "dpkg":
+			return because(
+				args.some((a) =>
+					["-i", "-r", "-P", "--install", "--remove", "--purge"].includes(a),
+				),
+				"installs or removes packages",
+				"shell.packages",
+			);
+		case "git":
+			return gitHeld(args, prefix, state, policy);
+		case "gh": {
+			const reason = ghHeld(args);
+			return reason ? { reason, class: "shell.gh" } : undefined;
+		}
+		case "crontab":
+			return because(args.includes("-r"), "removes a crontab", "shell.crontab");
+		case "tee": {
+			const target = args.find(
+				(a) => !a.startsWith("-") && !writable(a, state),
+			);
+			return target
+				? {
+						reason: `writes to ${target}`,
+						class: deviceTarget(target, state) ? "shell.disk" : "shell.write",
+					}
+				: undefined;
+		}
+		default:
+			return undefined;
+	}
+}
+
+/** Why a `git` command is held: a push the policy does not let run, or a hard reset. */
+function gitHeld(
+	args: string[],
+	prefix: string[],
+	state: LineState,
+	policy: PushPolicy,
+): Held | undefined {
+	const [globals, [verb, ...rest]] = gitCommand(args);
+	if (verb === "push") {
+		const plain = !prefix.some((w) => w.startsWith("GIT_"));
+		if (plain && ownPush(globals, rest, state, policy)) return undefined;
+		if (
+			rest.some(
+				(a) => /^-[A-Za-z]*f[A-Za-z]*$/.test(a) || a.startsWith("--force"),
+			)
+		)
+			return { reason: "force-pushes", class: "shell.force-push" };
+		if (rest.some(rewritesRemote))
+			return {
+				reason: "rewrites or deletes remote refs",
+				class: "shell.force-push",
+			};
+		return {
+			reason: `pushes to GitHub, which deploys ${assistantName()} when the branch is main`,
+			class: "shell.push",
+		};
+	}
+	if (verb === "reset" && rest.includes("--hard"))
+		return { reason: "git reset --hard", class: "shell.reset-hard" };
+	return undefined;
+}
+
+/** Git's global options that take a value, as separate words. */
+const GIT_VALUE_OPTIONS = new Set([
+	"-C",
+	"-c",
+	"--git-dir",
+	"--work-tree",
+	"--namespace",
+]);
+
+/** Git's global options, such as `-C <dir>`, and the subcommand with its arguments. */
+function gitCommand(args: string[]): [string[], string[]] {
+	let i = 0;
+	while (i < args.length && (args[i] as string).startsWith("-"))
+		i += GIT_VALUE_OPTIONS.has(args[i] as string) ? 2 : 1;
+	return [args.slice(0, i), args.slice(i)];
+}
+
+const GH_BODY_FLAGS = ["-f", "-F", "--field", "--raw-field", "--input"];
+const GH_READ_VERBS = new Set(["list", "view", "download"]);
+const GH_REPO_CHANGES = new Set([
+	"create",
+	"delete",
+	"edit",
+	"rename",
+	"archive",
+	"unarchive",
+]);
+
+/** Why a `gh` command writes to GitHub in a way the owner approves, or undefined. */
+function ghHeld(args: string[]): string | undefined {
+	const [group, verb] = args.filter((a) => !a.startsWith("-"));
+	switch (group) {
+		case "pr":
+			return verb === "merge" ? "merges a pull request" : undefined;
+		case "api": {
+			const body = args.some((a) =>
+				GH_BODY_FLAGS.some((f) => a === f || a.startsWith(`${f}=`)),
+			);
+			if (verb === "graphql")
+				return args.some((a) => /\bmutation\b/.test(a))
+					? "changes GitHub through the API"
+					: undefined;
+			const index = args.findIndex((a) => a === "-X" || a === "--method");
+			const method = (
+				index === -1
+					? args.find((a) => a.startsWith("--method="))?.slice(9)
+					: args[index + 1]
+			)?.toUpperCase();
+			return body || (method !== undefined && method !== "GET")
+				? "changes GitHub through the API"
+				: undefined;
+		}
+		case "release":
+		case "secret":
+		case "variable":
+			return verb && !GH_READ_VERBS.has(verb)
+				? `changes GitHub ${group}s`
+				: undefined;
+		case "repo":
+			return verb && GH_REPO_CHANGES.has(verb)
+				? `changes a GitHub repository (${verb})`
+				: undefined;
+		default:
+			return undefined;
+	}
+}

package/src/core/modules/host-shell/shell-quoting.ts

@@ -0,0 +1,237 @@
+/** Reading the quoted and delimited pieces of a command line that do not nest: `$'…'` and here-documents. */
+
+/** Whether a line continuation follows a character that starts a longer token (`$\⏎(`, `<<\⏎EOF`). */
+export function continuedToken(src: string): boolean {
+	return /[$<>{,(]\\\n/.test(src);
+}
+
+/**
+ * Whether the `}` at `pos` closes a group: a word of its own after a separator. Any other `{` or
+ * `}` is part of a word, which may be a brace expansion such as `{sudo,ls}`.
+ */
+export function closesGroup(src: string, pos: number): boolean {
+	const before = src[pos - 1];
+	const after = src[pos + 1];
+	const space = (ch: string) => /\s/.test(ch);
+	return (
+		(before === undefined || space(before) || ";&|()".includes(before)) &&
+		(after === undefined || space(after) || ";&|()<>".includes(after))
+	);
+}
+
+/** A line the lexer cannot place; the rule holds it whole. */
+export class Unreadable extends Error {}
+
+/** The escapes of `$'…'` that stand for one fixed character. */
+const ANSI_ESCAPES: Readonly<Record<string, string>> = {
+	a: "\x07",
+	b: "\b",
+	e: "\x1b",
+	E: "\x1b",
+	f: "\f",
+	n: "\n",
+	r: "\r",
+	t: "\t",
+	v: "\v",
+};
+
+/** The text of the `$'…'` string at `pos`, with the escapes bash decodes (`$'\x73udo'` is `sudo`), and where it ends. */
+export function ansiQuoted(
+	src: string,
+	pos: number,
+): { text: string; end: number } {
+	let text = "";
+	let i = pos + 2;
+	while (i < src.length && src[i] !== "'") {
+		if (src[i] !== "\\" || i + 1 >= src.length) {
+			text += src[i];
+			i++;
+			continue;
+		}
+		const c = src[i + 1] as string;
+		i += 2;
+		const simple = ANSI_ESCAPES[c];
+		if (simple !== undefined) text += simple;
+		else if (/[0-7]/.test(c)) {
+			const digits = /^[0-7]{0,2}/.exec(src.slice(i, i + 2))?.[0] ?? "";
+			text += String.fromCharCode(Number.parseInt(c + digits, 8) & 0xff);
+			i += digits.length;
+		} else if (c === "x" || c === "u" || c === "U") {
+			const max = c === "x" ? 2 : c === "u" ? 4 : 8;
+			const hex = /^[0-9a-fA-F]*/.exec(src.slice(i, i + max))?.[0] ?? "";
+			if (hex === "") text += `\\${c}`;
+			else {
+				const code = Number.parseInt(hex, 16);
+				text += code <= 0x10ffff ? String.fromCodePoint(code) : "";
+				i += hex.length;
+			}
+		} else if (c === "c" && i < src.length)
+			text += String.fromCharCode((src.charCodeAt(i++) as number) & 0x1f);
+		else if ("\\'\"?".includes(c)) text += c;
+		// Any other escape stays as it is, backslash and all: `$'s\⏎udo'` is `s\⏎udo`, which `eval` joins.
+		else text += `\\${c}`;
+	}
+	// A NUL ends the string: `$'sudo\0x'` is `sudo`.
+	const nul = text.indexOf("\0");
+	return {
+		text: nul === -1 ? text : text.slice(0, nul),
+		end: Math.min(i + 1, src.length),
+	};
+}
+
+/** The here-document delimiter at `pos`, with its quotes removed, and where its word ends. */
+export function readDelimiter(
+	src: string,
+	pos: number,
+): { text: string; quoted: boolean; end: number } {
+	let text = "";
+	let quoted = false;
+	let i = pos;
+	while (i < src.length) {
+		const c = src[i] as string;
+		// Bash ends the word at a blank or newline only: `EOF\r` is a delimiter of its own.
+		if (" \t\n;&|()<>".includes(c)) break;
+		if (c === "'") {
+			const close = src.indexOf("'", i + 1);
+			const stop = close === -1 ? src.length : close;
+			text += src.slice(i + 1, stop);
+			i = stop + 1;
+			quoted = true;
+		} else if (c === '"') {
+			for (i++; i < src.length && src[i] !== '"'; i++) {
+				if (src[i] === "\\" && src[i + 1] === "\n") throw new Unreadable();
+				if (
+					src[i] === "\\" &&
+					i + 1 < src.length &&
+					'"\\$`'.includes(src[i + 1] as string)
+				)
+					i++;
+				text += src[i];
+			}
+			i++;
+			quoted = true;
+		} else if (c === "\\") {
+			// Bash joins a backslash and a newline out of the word; no one writes one in a delimiter.
+			if (src[i + 1] === "\n") throw new Unreadable();
+			if (i + 1 < src.length) text += src[i + 1];
+			i += 2;
+			quoted = true;
+		} else if (c === "$" && src[i + 1] === "'") {
+			const found = ansiQuoted(src, i);
+			text += found.text;
+			i = found.end;
+			quoted = true;
+		} else {
+			text += c;
+			i++;
+		}
+	}
+	// `<<` followed by nothing, by an operator, or by `""` names no delimiter: bash versions end
+	// such a body, and the substitution around it, in different places.
+	if (text === "") throw new Unreadable();
+	return { text, quoted, end: Math.min(i, src.length) };
+}
+
+/**
+ * Where the body of the here-document that starts at `start` ends (`bodyEnd`) and where the text
+ * after its delimiter line begins (`next`). Without a delimiter line the body runs to the end.
+ */
+export function heredocBody(
+	src: string,
+	start: number,
+	here: { delimiter: string; quoted: boolean; stripTabs: boolean },
+): { bodyEnd: number; next: number; terminated: boolean } {
+	let at = start;
+	// Joining continuation lines is bounded by the delimiter length per start and by a total step
+	// budget; a body that exhausts it is unreadable (held) instead of quadratic.
+	let budget = 4 * src.length + 1000;
+	const limit = here.delimiter.length;
+	while (at < src.length) {
+		const nl = src.indexOf("\n", at);
+		const lineEnd = nl === -1 ? src.length : nl;
+		const line = src.slice(at, lineEnd);
+		if ((here.stripTabs ? line.replace(/^\t+/, "") : line) === here.delimiter)
+			return {
+				bodyEnd: at,
+				next: nl === -1 ? src.length : nl + 1,
+				terminated: true,
+			};
+		// A continued line may join the delimiter line; bash and this lexer might disagree.
+		if (!here.quoted) {
+			// `kept` is the joined text as the delimiter compares it (leading tabs dropped for `<<-`),
+			// grown by appending, so each join costs only the new piece.
+			const strip = (t: string) => (here.stripTabs ? t.replace(/^\t+/, "") : t);
+			let kept = strip(line);
+			let end = lineEnd;
+			while (/(?:^|[^\\])(?:\\\\)*\\$/.test(kept) && end < src.length) {
+				if (--budget < 0) throw new Unreadable();
+				const stop = src.indexOf("\n", end + 1);
+				const nextEnd = stop === -1 ? src.length : stop;
+				const piece = src.slice(end + 1, nextEnd);
+				kept = kept.slice(0, -1) + (kept.length === 1 ? strip(piece) : piece);
+				end = nextEnd;
+				// Past the delimiter length, or once the text before a continuing backslash is no
+				// longer a prefix of the delimiter, no join can match.
+				const base = kept.endsWith("\\") ? kept.slice(0, -1) : kept;
+				if (base.length > limit || !here.delimiter.startsWith(base)) break;
+				if (kept === here.delimiter) throw new Unreadable();
+			}
+		}
+		if (nl === -1) break;
+		at = nl + 1;
+	}
+	return { bodyEnd: src.length, next: src.length, terminated: false };
+}
+
+/**
+ * The text of the backtick substitution at `start`, with the escapes bash takes out of it: a
+ * backslash before a backtick, a backslash or `$`, and, inside double quotes, before `"`.
+ */
+export function backtickBody(
+	src: string,
+	start: number,
+	inDouble: boolean,
+): { inner: string; end: number } {
+	const escapable = inDouble ? '`\\$"' : "`\\$";
+	let inner = "";
+	let i = start + 1;
+	for (; i < src.length && src[i] !== "`"; i++) {
+		const next = src[i + 1];
+		// Bash joins a backslash and a newline in a backtick body before it reads the body.
+		if (src[i] === "\\" && next === "\n") throw new Unreadable();
+		if (src[i] === "\\" && next && escapable.includes(next)) i++;
+		inner += src[i];
+	}
+	return { inner, end: Math.min(i + 1, src.length) };
+}
+
+/** The redirection operator at `pos` (`>`, `>>`, `<`, `<>`, `>|`, `>&2`, `<&0`) as the word the lexer gives it, where it ends, and whether it closes a descriptor (`>&-`). */
+export function redirectOperator(
+	src: string,
+	pos: number,
+): { op: string; end: number; closes: boolean } {
+	let op = src[pos] as string;
+	let closes = false;
+	let end = pos + 1;
+	if (src[end] === ">") {
+		op += ">";
+		end++;
+	}
+	if (op === "<>") op = ">"; // opens the file for writing too
+	if (op === ">" && src[end] === "|") end++; // `>|` forces the overwrite
+	if (src[end] === "&") {
+		const digit = /\s*[0-9-]/y.test(src.slice(end + 1, end + 65));
+		const blank = " \t\n".includes(src[end + 1] ?? "\n");
+		// `<& file` names no descriptor; `<& 0` and `<& -` do, as `<&0` does.
+		if (op === "<" && blank && !digit) return { op, end, closes };
+		end++;
+		// `>&2`, `>&-` and `<&0` duplicate or close a descriptor; `>& file` names a file.
+		if (op === "<" || digit) op = "dup";
+		// `>&-` closes the descriptor: the `-` is its whole operand, and what follows it directly is the next word.
+		if (op === "dup" && src[end] === "-") {
+			end++;
+			closes = true;
+		}
+	}
+	return { op, end, closes };
+}

package/src/core/modules/host-shell/shell-scripts.ts

@@ -0,0 +1,114 @@
+import { basename } from "node:path";
+import type { LineState } from "./shell-paths.ts";
+
+/** Shells that run the command given with `-c`, or a script from a file or standard input. */
+export const SHELLS: ReadonlySet<string> = new Set([
+	"bash",
+	"sh",
+	"zsh",
+	"dash",
+	"ksh",
+	"ash",
+]);
+
+/** Shell options that take the next word as their argument. */
+const SHELL_OPTIONS_WITH_ARGUMENT = new Set([
+	"-o",
+	"+o",
+	"-O",
+	"+O",
+	"--rcfile",
+	"--init-file",
+]);
+
+/** The command a shell runs from its arguments (`-c`, also in a cluster such as `-ec`), if it is given one. */
+export function shellScript(args: readonly string[]): string | undefined {
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i] as string;
+		if (SHELL_OPTIONS_WITH_ARGUMENT.has(arg)) i++;
+		else if (/^-[A-Za-z]*c[A-Za-z]*$/.test(arg)) return args[i + 1];
+		else if (!/^[-+]/.test(arg) || arg === "--") return undefined;
+	}
+	return undefined;
+}
+
+/** Files that stand for the script text another command or a here-document gives on standard input, and a process substitution. */
+const STDIN_FILE = /^(?:\/(?:dev\/(?:stdin|fd\/|tty)|proc\/)|[<>]\()/;
+
+/** A written path as the line names it, without a leading `./`. */
+const normal = (path: string): string => path.replace(/^(?:\.\/)+/, "");
+
+/**
+ * How a shell gets its script when it has no `-c`: from standard input (`-s`, `-`, or no operand at
+ * all), or from the file it is given, which is its first word that is not an option.
+ */
+function scriptSource(args: readonly string[]): {
+	stdin: boolean;
+	file?: string;
+} {
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i] as string;
+		if (SHELL_OPTIONS_WITH_ARGUMENT.has(arg)) i++;
+		else if (arg === "--")
+			return args[i + 1] === undefined
+				? { stdin: true }
+				: { stdin: false, file: args[i + 1] };
+		else if (arg === "-") return { stdin: true };
+		else if (/^-[A-Za-z]*s[A-Za-z]*$/.test(arg)) return { stdin: true };
+		else if (!/^[-+]/.test(arg)) return { stdin: false, file: arg };
+	}
+	return { stdin: true };
+}
+
+/**
+ * Whether a command runs a script that the line does not show in a word of its own: a shell with
+ * no `-c` script reads its commands from standard input (a pipe, a here-document, a here-string,
+ * a process substitution) or from a file the line wrote; `source` and `.` do the same; a program
+ * the line wrote runs. A shell that `xargs` starts takes its script or file from the input.
+ * Running a script file that the line did not write is no different from running any program.
+ */
+export function readsUnseenScript(
+	word: string,
+	name: string,
+	args: readonly string[],
+	prefix: readonly string[],
+	state: LineState,
+): boolean {
+	const fromInput = prefix.includes("xargs");
+	const written = (path: string | undefined): boolean =>
+		path !== undefined && state.written.has(normal(path));
+	if (SHELLS.has(name)) {
+		if (shellScript(args) !== undefined) return false;
+		const { stdin, file } = scriptSource(args);
+		return (
+			fromInput ||
+			stdin ||
+			(file !== undefined && (STDIN_FILE.test(file) || written(file)))
+		);
+	}
+	if (name === "source" || name === ".") {
+		const [file] = args;
+		return (
+			fromInput || file === undefined || STDIN_FILE.test(file) || written(file)
+		);
+	}
+	return /^\.{0,2}\//.test(word) && written(word);
+}
+
+/** Notes the files a command writes: the targets of `>` and `>>`, and the operands of `tee`. */
+export function recordWrites(
+	words: readonly string[],
+	teeOperands: readonly string[],
+	state: LineState,
+): void {
+	for (let i = 0; i < words.length - 1; i++)
+		if (words[i] === ">" || words[i] === ">>")
+			state.written.add(normal(words[i + 1] as string));
+	for (const operand of teeOperands)
+		if (!operand.startsWith("-")) state.written.add(normal(operand));
+}
+
+/** The operands of `tee` in a command, or none when it is another program. */
+export function teeOperands(name: string, args: readonly string[]): string[] {
+	return basename(name) === "tee" ? [...args] : [];
+}