prae-cli 0.9.2 → 0.10.1

package/lib/playground.js

@@ -2,124 +2,676 @@
 
 
 //#region ../kernel/src/command.ts
-/** Wrappers whose first operand is the program actually being run. */
-	const WRAPPERS = new Set([
-		"sudo",
-		"command",
-		"env",
-		"nohup",
-		"time",
-		"xargs"
+/** Wrappers whose first operand is the program, and their options that take a value. */
+	const WRAPPERS = new Map(Object.entries({
+		sudo: [
+			"-u",
+			"-g",
+			"-p",
+			"-h",
+			"-C",
+			"-r",
+			"-t",
+			"-U",
+			"-D",
+			"-T",
+			"-R"
+		],
+		doas: ["-u", "-C"],
+		env: [
+			"-u",
+			"-C",
+			"-P",
+			"--unset",
+			"--chdir"
+		],
+		command: [],
+		builtin: [],
+		exec: ["-a"],
+		nohup: [],
+		time: ["-f", "-o"],
+		nice: ["-n"],
+		timeout: [
+			"-s",
+			"-k",
+			"--signal",
+			"--kill-after"
+		],
+		setsid: [],
+		stdbuf: [
+			"-i",
+			"-o",
+			"-e"
+		],
+		xargs: [
+			"-I",
+			"-n",
+			"-P",
+			"-L",
+			"-s",
+			"-d",
+			"-E",
+			"-a",
+			"--arg-file"
+		]
+	}).map(([name, options]) => [name, new Set(options)]));
+	const SHELLS = new Set([
+		"sh",
+		"bash",
+		"zsh",
+		"dash",
+		"ksh",
+		"mksh",
+		"ash"
 	]);
-	/** Wrapper options that consume the next token, so it is not the program. */
-	const OPTION_WITH_VALUE = new Set([
-		"-u",
-		"-g",
-		"-p",
-		"-h",
-		"-C",
-		"-r",
-		"-t",
-		"-U",
-		"-I",
-		"-n",
-		"-P",
-		"-L",
-		"-s"
+	/** Words that open or continue a compound command, not a program. */
+	const RESERVED = new Set([
+		"!",
+		"if",
+		"then",
+		"elif",
+		"else",
+		"fi",
+		"while",
+		"until",
+		"do",
+		"done"
 	]);
-	const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+	const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*\+?=/;
+	/** Scripts inside scripts (`bash -c`, `eval`, backticks, here-documents). */
+	const MAX_DEPTH = 8;
+	/** Brackets inside one script. */
+	const MAX_NESTING = 64;
+	/** A part of the line that cannot be read with confidence. */
+	var Undecomposable = class extends Error {};
+	const basename = (word) => (word.split("/").pop() ?? word).toLowerCase();
+	const isBlank = (c) => c === " " || c === "	" || c === "\r";
+	const isSpecial = (c) => /^[0-9@*#?$!-]$/.test(c);
+	const expands = (w) => /[*?]|\[.*\]|\{.*(,|\.\.).*\}/.test(w.bare);
 	/**
-	* Split a line into pipeline segments of words, one scan, quote-aware.
-	*
-	* Splitting on `|` before parsing quotes is the classic mistake — it turns
-	* `echo "a | b"` into two segments — so quoting and separators are read
-	* together.
+	* Read one script into `out`. `expansionsOnly` reads it as the body of an
+	* unquoted here-document: text, in which only substitutions run.
 	*/
-	function scan(command) {
-		const parts = [];
-		let tokens = [];
-		let current = "";
-		let quote;
-		const endToken = () => {
-			if (current !== "") tokens.push(current);
-			current = "";
+	function read(src, out, depth, expansionsOnly = false) {
+		if (depth > MAX_DEPTH) throw new Undecomposable(`scripts nested more than ${MAX_DEPTH} deep`);
+		let at = 0;
+		let nesting = 0;
+		/** Commands here read their standard input from a pipe. */
+		let piped = false;
+		const pending = [];
+		const ch = (k = 0) => src[at + k] ?? "";
+		const ahead = (s) => src.startsWith(s, at);
+		const ends = (k) => {
+			const c = ch(k);
+			return c === "" || isBlank(c) || c === "\n" || ";&|()<>".includes(c);
 		};
-		const endSegment = () => {
-			endToken();
-			if (tokens.length > 0) parts.push(tokens);
-			tokens = [];
+		const deeper = () => {
+			nesting += 1;
+			if (nesting > MAX_NESTING) throw new Undecomposable(`brackets nested more than ${MAX_NESTING} deep`);
 		};
-		for (let at = 0; at < command.length; at += 1) {
-			const ch = command[at];
-			if (quote !== void 0) {
-				if (ch === quote) quote = void 0;
-				else current += ch;
-				continue;
+		const fresh = () => ({
+			text: "",
+			literal: true,
+			quoted: false,
+			bare: ""
+		});
+		/** A script inside this one: its unreadable parts are recorded, not fatal. */
+		const nested = (text, onlyExpansions = false) => {
+			try {
+				read(text, out, depth + 1, onlyExpansions);
+			} catch (error) {
+				if (!(error instanceof Undecomposable)) throw error;
+				out.undecomposable.push(error.message);
 			}
-			if (ch === "'" || ch === "\"") {
-				quote = ch;
-				continue;
+		};
+		function blanks() {
+			for (;;) {
+				const c = ch();
+				if (isBlank(c)) at += 1;
+				else if (c === "\\" && ch(1) === "\n") at += 2;
+				else if (c === "#") while (at < src.length && ch() !== "\n") at += 1;
+				else return;
 			}
-			if (ch === ";") {
-				endSegment();
-				continue;
+		}
+		/** One unquoted newline, then the here-document bodies it starts. */
+		function newline() {
+			at += 1;
+			for (let doc = pending.shift(); doc; doc = pending.shift()) body(doc);
+		}
+		function body(doc) {
+			let text = "";
+			while (at < src.length) {
+				const stop = src.indexOf("\n", at);
+				const end = stop === -1 ? src.length : stop;
+				const line = src.slice(at, end);
+				at = Math.min(end + 1, src.length);
+				if ((doc.strip ? line.replace(/^\t+/, "") : line) === doc.delim) break;
+				text += `${line}\n`;
 			}
-			if (ch === "|" || ch === "&") {
-				endSegment();
-				if (command[at + 1] === ch) at += 1;
-				continue;
+			if (doc.feed.shell !== void 0) if (!doc.quoted && /[$`\\]/.test(text)) out.undecomposable.push(`a here-document with expansions is run by ${doc.feed.shell}`);
+			else nested(text);
+			else if (!doc.quoted) nested(text, true);
+		}
+		function list$1(end) {
+			for (;;) {
+				blanks();
+				const c = ch();
+				if (c === "") {
+					if (end === void 0) return;
+					throw new Undecomposable(end === ")" ? "an unclosed `(`" : "an unclosed `{`");
+				}
+				if (c === "\n") newline();
+				else if (c === ";") {
+					if (ch(1) === ";") throw new Undecomposable("`;;` outside a case statement");
+					at += 1;
+				} else if (c === "&" && ch(1) !== ">") at += ch(1) === "&" ? 2 : 1;
+				else if (c === "|" && ch(1) === "|") at += 2;
+				else if (c === "|") throw new Undecomposable("a pipe with nothing before it");
+				else if (c === ")") {
+					if (end !== ")") throw new Undecomposable("an unbalanced `)`");
+					at += 1;
+					return;
+				} else if (end === "}" && c === "}" && ends(1)) {
+					at += 1;
+					return;
+				} else pipeline();
 			}
-			if (/\s/.test(ch)) {
-				endToken();
-				continue;
+		}
+		function pipeline() {
+			const names = [];
+			for (let position = 0;; position += 1) {
+				names.push(...command(position > 0 || piped));
+				blanks();
+				if (ch() !== "|" || ch(1) === "|") break;
+				at += ch(1) === "&" ? 2 : 1;
+				for (blanks(); ch() === "\n"; blanks()) newline();
 			}
-			current += ch;
+			if (names.length > 0) out.pipelines.push(names.join("|"));
 		}
-		endSegment();
-		return parts;
-	}
-	/** Decompose a command line into pipeline segments. */
-	function segments(command) {
-		const found = [];
-		for (const tokens of scan(command)) {
-			let at = 0;
-			const wrappers = [];
-			while (at < tokens.length) {
-				const token = tokens[at];
-				if (ASSIGNMENT.test(token)) {
-					at += 1;
+		function command(fromPipe) {
+			blanks();
+			if (ahead("((") && arithmetic()) {
+				trailing();
+				return [];
+			}
+			if (ch() === "(") {
+				at += 1;
+				return compound(")", fromPipe);
+			}
+			if (ch() === "{" && (isBlank(ch(1)) || ch(1) === "\n")) {
+				at += 1;
+				return compound("}", fromPipe);
+			}
+			return simple(fromPipe);
+		}
+		function compound(end, fromPipe) {
+			deeper();
+			const before = out.segments.length;
+			const outer = piped;
+			piped = fromPipe;
+			list$1(end);
+			piped = outer;
+			nesting -= 1;
+			trailing();
+			return out.segments.slice(before).map((s) => s.name);
+		}
+		/** Redirections after a compound command; anything else is not shell. */
+		function trailing() {
+			blanks();
+			while (redirection() !== void 0) blanks();
+			if (!ends(0) && ch() !== "}") throw new Undecomposable("a word after a compound command");
+		}
+		function simple(fromPipe) {
+			const mark = out.segments.length;
+			const words = [];
+			const redirects = [];
+			const feed = {};
+			let runsNothing = false;
+			let conditional = false;
+			for (;;) {
+				blanks();
+				const c = ch();
+				if (conditional) {
+					if (c === "") throw new Undecomposable("an unclosed `[[`");
+					if (c === "\n") {
+						newline();
+						continue;
+					}
+					if (ahead("]]") && ends(2)) {
+						at += 2;
+						conditional = false;
+						continue;
+					}
+					const op = /^(&&|\|\||[()<>!])/.exec(src.slice(at, at + 2));
+					if (op !== null) {
+						at += op[0].length;
+						continue;
+					}
+				}
+				if (c === "" || c === "\n" || c === ";" || c === ")" || c === "|") break;
+				if (c === "&" && ch(1) !== ">") break;
+				if (c === "(") {
+					if (ahead("((")) {
+						if (arithmetic()) continue;
+						throw new Undecomposable("an unexpected `(`");
+					}
+					if (words.length === 1) {
+						at += 1;
+						blanks();
+						if (ch() === ")") {
+							at += 1;
+							for (blanks(); ch() === "\n"; blanks()) newline();
+							return command(fromPipe);
+						}
+					}
+					throw new Undecomposable("an unexpected `(`");
+				}
+				const redirected = redirection(feed);
+				if (redirected !== void 0) {
+					redirects.push(...redirected);
 					continue;
 				}
-				const word = (token.split("/").pop() ?? token).toLowerCase();
-				if (WRAPPERS.has(word)) {
-					wrappers.push(word);
+				const w = word();
+				if (w === void 0) throw new Undecomposable("an unexpected character");
+				if (words.length === 0 && w.literal && !w.quoted) {
+					if (RESERVED.has(w.text)) return command(fromPipe);
+					if (w.text === "case" || w.text === "coproc") throw new Undecomposable(`a \`${w.text}\` statement`);
+					if (w.text === "function") {
+						blanks();
+						word();
+						blanks();
+						if (ahead("()")) at += 2;
+						for (blanks(); ch() === "\n"; blanks()) newline();
+						return command(fromPipe);
+					}
+					if (w.text === "for" || w.text === "select") runsNothing = true;
+					if (w.text === "[[") {
+						runsNothing = true;
+						conditional = true;
+					}
+				}
+				words.push(w);
+			}
+			if (runsNothing || words.length === 0) return [];
+			const name = resolve(words, redirects, [], false, mark, feed, fromPipe);
+			return name === void 0 ? [] : [name];
+		}
+		/** A redirection at `at`: the operator and its target, as tokens. */
+		function redirection(feed) {
+			if ((ch() === "<" || ch() === ">") && ch(1) === "(") return void 0;
+			const m = /^(\d*)(<<<|<<-|<<|<>|<&|>>|>\||>&|&>>|&>|<|>)/.exec(src.slice(at, at + 12));
+			if (m === null) return void 0;
+			at += m[0].length;
+			blanks();
+			const target = word();
+			if (target === void 0) throw new Undecomposable("a redirection with no target");
+			const op = m[2];
+			if (op === "<<" || op === "<<-") pending.push({
+				delim: target.text,
+				strip: op === "<<-",
+				quoted: target.quoted,
+				feed: feed ?? {}
+			});
+			else if (op === "<<<" && feed !== void 0) feed.herestring = target;
+			if (op === ">&" || op === "<&") return [`${m[0]}${target.text}`];
+			return [m[0], target.text];
+		}
+		/** One word at `at`, quotes and expansions read; undefined at an operator. */
+		function word() {
+			const w = fresh();
+			const start$1 = at;
+			for (;;) {
+				const c = ch();
+				if (c === "" || isBlank(c) || c === "\n" || ";&|()".includes(c)) break;
+				if (c === "<" || c === ">") {
+					if (ch(1) !== "(") break;
+					const from = at;
+					at += 2;
+					substitution();
+					w.text += src.slice(from, at);
+					w.literal = false;
+				} else if (c === "\\") {
+					if (ch(1) !== "\n") {
+						w.text += ch(1);
+						w.quoted = true;
+					}
+					at += 2;
+				} else if (c === "'") {
+					const end = src.indexOf("'", at + 1);
+					if (end === -1) throw new Undecomposable("an unbalanced single quote");
+					w.text += src.slice(at + 1, end);
+					w.quoted = true;
+					at = end + 1;
+				} else if (c === "$" && ch(1) === "'") ansi(w);
+				else if (c === "$" && ch(1) === "\"") {
+					at += 1;
+					double(w, true);
+				} else if (c === "\"") double(w, true);
+				else if (c === "`") backtick(w, false);
+				else if (c === "$") dollar(w);
+				else {
+					w.text += c;
+					w.bare += c;
+					at += 1;
+				}
+			}
+			return at === start$1 ? void 0 : w;
+		}
+		/** `"…"` (or, unclosed, a here-document body): only `$` and backticks are live. */
+		function double(w, closed) {
+			w.quoted = true;
+			if (closed) at += 1;
+			for (;;) {
+				const c = ch();
+				if (c === "") {
+					if (closed) throw new Undecomposable("an unbalanced double quote");
+					return;
+				}
+				if (c === "\"" && closed) {
+					at += 1;
+					return;
+				}
+				const n = ch(1);
+				if (c === "\\" && n !== "" && (n === "\n" || "$`\"\\".includes(n))) {
+					if (n !== "\n") w.text += n;
+					at += 2;
+				} else if (c === "`") backtick(w, closed);
+				else if (c === "$") dollar(w);
+				else {
+					w.text += c;
 					at += 1;
-					while (at < tokens.length) {
-						const option = tokens[at];
-						if (!option.startsWith("-")) break;
-						at += OPTION_WITH_VALUE.has(option) ? 2 : 1;
+				}
+			}
+		}
+		/** `$'…'`: escapes can spell anything, so one with escapes is not a literal. */
+		function ansi(w) {
+			let k = at + 2;
+			for (;;) {
+				const c = src[k];
+				if (c === void 0) throw new Undecomposable("an unbalanced `$'` quote");
+				if (c === "'") break;
+				if (c === "\\") {
+					w.literal = false;
+					w.text += c + (src[k + 1] ?? "");
+					k += 2;
+				} else {
+					w.text += c;
+					k += 1;
+				}
+			}
+			w.quoted = true;
+			at = k + 1;
+		}
+		/** `$(…)`, `$((…))`, `${…}`, `$NAME`; a lone `$` is a dollar sign. */
+		function dollar(w) {
+			const from = at;
+			if (ahead("$(")) {
+				if (!(ahead("$((") && arithmetic())) {
+					at += 2;
+					substitution();
+				}
+			} else if (ahead("${")) {
+				at += 2;
+				parameter();
+			} else if (/[A-Za-z_]/.test(ch(1))) {
+				at += 1;
+				while (/[A-Za-z0-9_]/.test(ch())) at += 1;
+			} else if (isSpecial(ch(1))) at += 2;
+			else {
+				w.text += "$";
+				w.bare += "$";
+				at += 1;
+				return;
+			}
+			w.text += src.slice(from, at);
+			w.literal = false;
+		}
+		/** After `$(`, `<(` or `>(`: a list up to its `)`, with its own stdin. */
+		function substitution() {
+			deeper();
+			const outer = piped;
+			piped = false;
+			list$1(")");
+			piped = outer;
+			nesting -= 1;
+		}
+		/** After `${`: up to the matching `}`; a default value can run a command. */
+		function parameter() {
+			deeper();
+			const sink = fresh();
+			for (;;) {
+				const c = ch();
+				if (c === "") throw new Undecomposable("an unclosed `${`");
+				if (c === "}") break;
+				if (c === "\\") at += 2;
+				else if (c === "'") {
+					const end = src.indexOf("'", at + 1);
+					if (end === -1) throw new Undecomposable("an unbalanced single quote");
+					at = end + 1;
+				} else if (c === "\"") double(sink, true);
+				else if (c === "`") backtick(sink, false);
+				else if (c === "$") dollar(sink);
+				else at += 1;
+			}
+			at += 1;
+			nesting -= 1;
+		}
+		/**
+		* Where `((…))` / `$((…))` at `at` ends, if bash reads it as arithmetic:
+		* only when the `)` matching the second `(` is followed at once by `)`.
+		* Otherwise bash reads `(` `(` — nested subshells, or `$(` and a subshell —
+		* and `((rm -rf /) )` runs rm. Quotes and backticks are skipped whole;
+		* anything unclosed is not arithmetic, so it is read the stricter way.
+		*/
+		function arithmeticEnd() {
+			let depth$1 = 1;
+			for (let k = at + (ch() === "$" ? 3 : 2); k < src.length; k += 1) {
+				const c = src[k];
+				if (c === "\\") k += 1;
+				else if (c === "'" || c === "\"" || c === "`") {
+					let end = k + 1;
+					while (end < src.length && src[end] !== c) {
+						if (src[end] === "\\" && c !== "'") end += 1;
+						end += 1;
 					}
+					if (end >= src.length) return void 0;
+					k = end;
+				} else if (c === "(") depth$1 += 1;
+				else if (c === ")") {
+					depth$1 -= 1;
+					if (depth$1 === 0) return src[k + 1] === ")" ? k + 2 : void 0;
+				}
+			}
+		}
+		/**
+		* `((…))` or `$((…))` read as arithmetic, in which a substitution still
+		* runs; false, and nothing read, when bash would not read it so.
+		*/
+		function arithmetic() {
+			const end = arithmeticEnd();
+			if (end === void 0) return false;
+			deeper();
+			at += ch() === "$" ? 3 : 2;
+			const sink = fresh();
+			while (at < end) {
+				const c = ch();
+				if (c === "$") dollar(sink);
+				else if (c === "`") backtick(sink, false);
+				else at += 1;
+			}
+			if (at !== end) throw new Undecomposable("an ambiguous `((`");
+			nesting -= 1;
+			return true;
+		}
+		/** `` `…` ``: its text, unescaped, is a script of its own. */
+		function backtick(w, inDouble) {
+			let inner = "";
+			let k = at + 1;
+			for (;;) {
+				const c = src[k];
+				if (c === void 0) throw new Undecomposable("an unbalanced backtick");
+				if (c === "`") break;
+				const n = src[k + 1] ?? "";
+				const escaped = "`$\\".includes(n) || inDouble && n === "\"";
+				if (c === "\\" && n !== "" && escaped) {
+					inner += n;
+					k += 2;
+				} else {
+					inner += c;
+					k += 1;
+				}
+			}
+			w.text += src.slice(at, k + 1);
+			w.literal = false;
+			at = k + 1;
+			nested(inner);
+		}
+		/**
+		* Words to the program they run, inserted at `insertAt` so a command comes
+		* before the substitutions in its words; then whatever that program runs in
+		* turn (`bash -c`, `eval`, `find -exec`).
+		*/
+		function resolve(words, redirects, seen, open, insertAt, feed, fromPipe = false) {
+			const wrappers = [...seen];
+			let openEnded = open;
+			let replace;
+			let k = 0;
+			while (k < words.length) {
+				const w = words[k];
+				if (ASSIGNMENT.test(w.text)) {
+					k += 1;
 					continue;
 				}
-				break;
+				if (!w.literal || expands(w)) break;
+				const base = basename(w.text);
+				const options = WRAPPERS.get(base);
+				if (options === void 0) break;
+				wrappers.push(base);
+				if (base === "xargs") openEnded = true;
+				k += 1;
+				while (k < words.length) {
+					const option = words[k].text;
+					if (option === "--") {
+						k += 1;
+						break;
+					}
+					if (!option.startsWith("-")) break;
+					if (base === "env" && /^(-S|--split-string)/.test(option)) {
+						out.undecomposable.push("`env -S` splits a string into a command");
+						return insert(insertAt, {
+							name: base,
+							tokens: [],
+							wrappers
+						});
+					}
+					if (base === "xargs" && option.startsWith("-I")) replace = option.length > 2 ? option.slice(2) : words[k + 1]?.text;
+					k += options.has(option) ? 2 : 1;
+				}
+				if (base === "timeout") k += 1;
 			}
-			const name = tokens[at];
-			if (name === void 0) {
-				const last = wrappers.at(-1);
-				if (last !== void 0) found.push({
+			const program = words[k];
+			const rest = words.slice(k + 1);
+			const tokens = [...rest.map((w) => w.text), ...redirects];
+			const last = wrappers.at(-1);
+			if (program === void 0) return last === void 0 || wrappers.length === seen.length ? void 0 : insert(insertAt, {
+				name: last,
+				tokens: [...redirects],
+				wrappers
+			});
+			if (!program.literal || expands(program) || openEnded && (program.text.includes("{}") || replace !== void 0 && replace !== "" && program.text.includes(replace))) {
+				out.undecomposable.push("the program word is only known at run time");
+				if (last !== void 0) insert(insertAt, {
 					name: last,
-					tokens: [],
+					tokens: [program.text, ...tokens],
 					wrappers
 				});
-				continue;
+				return;
 			}
-			found.push({
-				name: (name.split("/").pop() ?? name).toLowerCase(),
-				tokens: tokens.slice(at + 1),
-				wrappers
+			const name = basename(program.text);
+			insert(insertAt, {
+				name,
+				tokens,
+				wrappers,
+				...openEnded ? { openEnded: true } : {}
 			});
+			if (SHELLS.has(name)) shell(name, rest, feed, fromPipe);
+			else if (name === "eval") if (rest.every((w) => w.literal)) nested(rest.map((w) => w.text).join(" "));
+			else out.undecomposable.push("`eval` of a string that is not a literal");
+			else if (name === "source" || name === ".") {
+				if (rest[0] !== void 0 && !rest[0].literal) out.undecomposable.push(`\`${name}\` of a file only known at run time`);
+			} else if (name === "find") for (let i = 0; i < rest.length; i += 1) {
+				const flag = rest[i].text;
+				if (![
+					"-exec",
+					"-execdir",
+					"-ok",
+					"-okdir"
+				].includes(flag)) continue;
+				let end = i + 1;
+				while (end < rest.length && !/^[;+]$/.test(rest[end].text)) end += 1;
+				resolve(rest.slice(i + 1, end), [], [...wrappers, "find"], true, out.segments.length);
+				i = end;
+			}
+			return name;
+		}
+		function insert(where, segment) {
+			out.segments.splice(where, 0, segment);
+			return segment.name;
+		}
+		/** What a shell program runs: a `-c` string, a script file, or its stdin. */
+		function shell(name, args, feed, fromPipe) {
+			let inline = false;
+			let stdin = false;
+			let k = 0;
+			while (k < args.length) {
+				const option = args[k].text;
+				if (option === "--" || option === "-") {
+					k += 1;
+					break;
+				}
+				if (option === "--rcfile" || option === "--init-file") k += 2;
+				else if (option.startsWith("--")) k += 1;
+				else if (/^[-+][A-Za-z]+$/.test(option)) {
+					if (option.startsWith("-") && option.includes("c")) inline = true;
+					if (option.includes("s")) stdin = true;
+					k += option.includes("o") ? 2 : 1;
+				} else break;
+			}
+			const operand = args[k];
+			if (inline) {
+				if (operand === void 0) return;
+				if (operand.literal) nested(operand.text);
+				else out.undecomposable.push(`\`${name} -c\` runs a string that is not a literal`);
+				return;
+			}
+			if (operand !== void 0 && !stdin) {
+				if (!operand.literal) out.undecomposable.push(`\`${name}\` runs a script only known at run time`);
+				return;
+			}
+			if (fromPipe) out.undecomposable.push(`\`${name}\` runs commands read from a pipe`);
+			if (feed === void 0) return;
+			feed.shell = `\`${name}\``;
+			const string = feed.herestring;
+			if (string === void 0) return;
+			if (string.literal) nested(string.text);
+			else out.undecomposable.push(`a here-string with expansions is run by \`${name}\``);
+		}
+		if (expansionsOnly) double(fresh(), false);
+		else list$1(void 0);
+	}
+	/** Read a command line into every command it would run, and what could not be read. */
+	function decompose(command) {
+		const out = {
+			segments: [],
+			pipelines: [],
+			undecomposable: []
+		};
+		try {
+			read(command, out, 0);
+		} catch (error) {
+			out.undecomposable.push(error instanceof Undecomposable ? error.message : "the line could not be read");
 		}
-		return found;
+		return out;
 	}
 	/** `git*` matches `git`, `github`; bare strings match exactly. */
 	function matches$1(pattern, value) {
@@ -144,17 +696,19 @@
 	}
 	const list = (v) => v === void 0 ? [] : typeof v === "string" ? [v] : v;
 	/**
-	* Judge one command line against one matcher. Every present field must hold.
+	* Every present field holds on what was read. With `open`, a segment whose
+	* arguments arrive at run time (`xargs`, `find -exec`) satisfies any token
+	* condition, because those arguments could.
 	*/
-	function commandMatches(match, command) {
-		const parts = segments(command);
+	function holds(match, read$1, open) {
+		const parts = read$1.segments;
 		if (parts.length === 0) return false;
 		const names = list(match.name);
 		const args = list(match.token);
 		const anyArgs = list(match.anyToken);
 		const pipes = list(match.pipedTo);
 		const shapes = list(match.pipeline);
-		const argsHold = (segment) => tokensHold(args, segment.tokens) && (anyArgs.length === 0 || anyArgs.some((wanted) => segment.tokens.some((token) => matches$1(wanted, token))));
+		const argsHold = (segment) => open && segment.openEnded === true || tokensHold(args, segment.tokens) && (anyArgs.length === 0 || anyArgs.some((wanted) => segment.tokens.some((token) => matches$1(wanted, token))));
 		if (names.length > 0) {
 			const hit = parts.filter((segment) => names.some((pattern) => matches$1(pattern, segment.name) || segment.wrappers.some((wrapper) => matches$1(pattern, wrapper))));
 			if (hit.length === 0) return false;
@@ -166,11 +720,32 @@
 			if (!parts.slice(1).some((segment) => pipes.some((pattern) => matches$1(pattern, segment.name)))) return false;
 		}
 		if (shapes.length > 0) {
-			const signature = parts.map((segment) => segment.name).join("|");
-			if (!shapes.some((pattern) => globMatches(pattern, signature))) return false;
+			const signatures = [parts.map((segment) => segment.name).join("|"), ...read$1.pipelines];
+			if (!shapes.some((pattern) => signatures.some((signature) => globMatches(pattern, signature)))) return false;
 		}
 		return true;
 	}
+	/**
+	* Judge one command line against one matcher, on what could be read. Every
+	* present field must hold.
+	*/
+	function commandMatches(match, command) {
+		return holds(match, typeof command === "string" ? decompose(command) : command, false);
+	}
+	/**
+	* Why a matcher that did not hold on what was read might still hold on what
+	* runs: part of the line could not be read, or a matched program takes
+	* arguments only known at run time. Undefined when there is no such reason.
+	* A `deny` or `ask` rule matches on it, conservatively (`evaluate.ts`).
+	*/
+	function commandUnread(match, command) {
+		const read$1 = typeof command === "string" ? decompose(command) : command;
+		if (read$1.undecomposable.length > 0) return [...new Set(read$1.undecomposable)].join("; ");
+		if (!holds(match, read$1, true)) return void 0;
+		const open = read$1.segments.find((s) => s.openEnded === true);
+		const from = open?.wrappers.includes("xargs") ? "xargs" : "find -exec";
+		return `the arguments \`${open?.name ?? "?"}\` gets from ${from} are only known at run time`;
+	}
 
 //#endregion
 //#region ../kernel/src/path.ts
@@ -383,15 +958,25 @@
 		}
 		return true;
 	}
-	function matches(when, facts) {
+	/**
+	* Whether a rule's matcher holds on a call: `false`, or a hit — carrying a
+	* note when the hit is conservative. `strict` rules (deny, ask) match a shell
+	* line they cannot fully read, because what was not read could be what they
+	* refuse; the note says what that was. Weaker rules never match on a guess.
+	*/
+	function matches(when, facts, strict, shell) {
+		let note;
 		if (!listed(facts.tool, when.tool)) return false;
 		if (!listed(facts.capability, when.capability)) return false;
 		if (!listed(facts.plugin, when.plugin)) return false;
 		if (!listed(facts.agent, when.agent)) return false;
 		if (when.command !== void 0) {
-			const raw = facts.args.command ?? facts.args.cmd ?? facts.args.script;
-			if (typeof raw !== "string") return false;
-			if (!commandMatches(when.command, raw)) return false;
+			const line = shell();
+			if (line === void 0) return false;
+			if (!commandMatches(when.command, line)) {
+				note = strict ? commandUnread(when.command, line) : void 0;
+				if (note === void 0) return false;
+			}
 		}
 		if (when.path !== void 0) {
 			const raw = pathArgOf(facts.args, when.path.arg);
@@ -403,7 +988,10 @@
 			const raw = facts.args[when.host.arg ?? "url"];
 			if (typeof raw !== "string") return false;
 			const host = hostOf(raw);
-			if (host === void 0) return when.host.notIn !== void 0;
+			if (host === void 0) {
+				if (when.host.notIn === void 0) return false;
+				return note === void 0 ? {} : { note };
+			}
 			if (when.host.in !== void 0 && !hostIn(host, when.host.in)) return false;
 			if (when.host.notIn !== void 0 && hostIn(host, when.host.notIn)) return false;
 		}
@@ -420,7 +1008,7 @@
 			const wanted = when.secrets.types;
 			if ((facts.secrets ?? []).filter((finding) => finding.confidence >= floor && (wanted === void 0 || wanted.includes(finding.type))).length < (when.secrets.atLeast ?? 1)) return false;
 		}
-		return true;
+		return note === void 0 ? {} : { note };
 	}
 	function step(rule, effect) {
 		return {
@@ -445,10 +1033,26 @@
 	*/
 	function evaluate(pack, facts) {
 		const hits = [];
-		for (const rule of pack.rules) if (matches(rule.when, facts)) hits.push({
-			rule,
-			effect: rule.effect
-		});
+		let line = null;
+		const shell = () => {
+			if (line === null) {
+				const raw = facts.args.command ?? facts.args.cmd ?? facts.args.script;
+				line = typeof raw === "string" ? decompose(raw) : void 0;
+			}
+			return line;
+		};
+		for (const rule of pack.rules) {
+			const strict = rule.effect.kind === "deny" || rule.effect.kind === "ask";
+			const hit = matches(rule.when, facts, strict, shell);
+			if (hit === false) continue;
+			hits.push({
+				rule,
+				effect: hit.note === void 0 ? rule.effect : {
+					...rule.effect,
+					because: `${rule.effect.because} (could not decompose: ${hit.note})`
+				}
+			});
+		}
 		if (hits.length === 0) return {
 			kind: "allow",
 			trace: [],
@@ -984,6 +1588,7 @@
 			"version",
 			"description",
 			"owner",
+			"expires_at",
 			"baseline",
 			"rules"
 		]);
@@ -992,6 +1597,8 @@
 		const version = check.text(".version", raw.version);
 		const description = raw.description === void 0 ? void 0 : check.text(".description", raw.description);
 		const owner = raw.owner === void 0 ? void 0 : check.text(".owner", raw.owner);
+		const expires = raw.expires_at === void 0 ? void 0 : check.text(".expires_at", raw.expires_at);
+		if (expires !== void 0 && (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/.test(expires) || !Number.isFinite(Date.parse(expires)))) check.fail(".expires_at", "expected an ISO 8601 time with a zone, e.g. 2026-10-05T12:00:00Z");
 		let baseline;
 		if (raw.baseline !== void 0) if (!isObject(raw.baseline)) check.fail(".baseline", "expected an object");
 		else {
@@ -1030,6 +1637,7 @@
 				version,
 				...description === void 0 ? {} : { description },
 				...owner === void 0 ? {} : { owner },
+				...expires === void 0 ? {} : { expires_at: expires },
 				...baseline === void 0 ? {} : { baseline },
 				rules
 			}