prae-cli 0.1.0

package/lib/playground.js

@@ -0,0 +1,685 @@
+(function() {
+
+
+//#region ../kernel/src/path.ts
+/**
+	* Path normalization and glob containment, with no filesystem access.
+	*
+	* The contract, stated here because getting it wrong is how path policies
+	* become theatre: **this module compares strings.** It resolves `.` and `..`
+	* lexically so that `./src/../../etc/passwd` cannot pose as a workspace path,
+	* but it cannot see a symlink. A link inside an allowed directory pointing out
+	* of it will pass every check here.
+	*
+	* That is not a gap to paper over in the matcher — it is a gap the caller
+	* closes by resolving before it asks. `dsh-overlay-check` learned this the
+	* hard way during the plugin-store gate review: lexical containment accepted a
+	* symlink escape cleanly, and the fix was to resolve both the path and its
+	* nearest existing ancestor before deciding. Adapters that can touch the
+	* filesystem must resolve first and pass the resolved path in.
+	*/
+	/** Split a path into segments, resolving `.` and `..` lexically. */
+	function normalize(path) {
+		const absolute = path.startsWith("/");
+		const out = [];
+		let escaped = false;
+		for (const raw of path.split(/[/\\]+/)) {
+			if (raw === "" || raw === ".") continue;
+			if (raw === "..") {
+				if (out.length > 0) out.pop();
+				else escaped = true;
+				continue;
+			}
+			out.push(raw);
+		}
+		return {
+			segments: out,
+			absolute,
+			escaped
+		};
+	}
+	/** Turn one glob segment into an anchored regular expression. */
+	function segmentPattern(segment) {
+		const body = segment.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*");
+		return /* @__PURE__ */ new RegExp(`^${body}$`);
+	}
+	/**
+	* Wildcard segment matching, where `**` spans zero or more segments.
+	*
+	* Two-pointer with backtracking rather than a recursive walk: the pattern
+	* comes from a policy pack and the path from a tool call, and a catastrophic
+	* backtrack in the hot path of every call would be a denial of service handed
+	* to whoever writes the pack.
+	*/
+	function matchSegments(path, pattern) {
+		let i = 0;
+		let j = 0;
+		let starPattern = -1;
+		let starPath = 0;
+		while (i < path.length) {
+			const segment = j < pattern.length ? pattern[j] : void 0;
+			const here = path[i];
+			if (segment === "**") {
+				starPattern = j;
+				starPath = i;
+				j += 1;
+				continue;
+			}
+			if (segment !== void 0 && here !== void 0 && segmentPattern(segment).test(here)) {
+				i += 1;
+				j += 1;
+				continue;
+			}
+			if (starPattern >= 0) {
+				starPath += 1;
+				i = starPath;
+				j = starPattern + 1;
+				continue;
+			}
+			return false;
+		}
+		while (j < pattern.length && pattern[j] === "**") j += 1;
+		return j === pattern.length;
+	}
+	/**
+	* Is `path` contained by `glob`?
+	*
+	* A glob naming a directory contains everything under it: `./src` and
+	* `./src/**` both match `src/app/main.ts`. Writing the shorter form is the
+	* common intent, and treating it as "this exact directory entry only" is a
+	* trap that silently grants the whole subtree past the rule.
+	*/
+	function within(path, glob) {
+		const target = normalize(path);
+		if (target.escaped) return false;
+		const pattern = normalize(glob);
+		if (matchSegments(target.segments, pattern.segments)) return true;
+		return matchSegments(target.segments, [...pattern.segments, "**"]);
+	}
+	/** Is `path` inside any of these globs? */
+	function withinAny(path, globs) {
+		return globs.some((glob) => within(path, glob));
+	}
+	/**
+	* The host of a URL, or undefined when it is not a URL we can read.
+	*
+	* Unparseable input returns undefined, and callers treat that as "no host" —
+	* which for a `notIn` rule means the rule matches. Failing toward the rule is
+	* the only safe direction: a string we cannot parse is exactly the shape an
+	* evasion attempt takes.
+	*/
+	function hostOf(url) {
+		try {
+			return new URL(url).hostname.toLowerCase();
+		} catch {
+			return;
+		}
+	}
+	/**
+	* Host list membership, where a leading dot means "this domain or below".
+	*
+	* `example.com` matches only that host. `.example.com` also matches
+	* `api.example.com`, and deliberately still matches `example.com` itself —
+	* an operator writing the suffix form means the organisation, not a rule that
+	* covers every subdomain except the one they first thought of.
+	*/
+	function hostIn(host, list) {
+		return list.some((entry) => {
+			const want = entry.toLowerCase();
+			if (want.startsWith(".")) return host === want.slice(1) || host.endsWith(want);
+			return host === want;
+		});
+	}
+
+//#endregion
+//#region ../kernel/src/rule.ts
+/**
+	* Strength ordering, used when several rules match one call.
+	*
+	* Higher wins. This is the property that makes a pack safe to extend: adding a
+	* rule can raise the strength of a decision and never lower it, so an operator
+	* appending to a pack can never accidentally widen what an agent may do.
+	*/
+	const STRENGTH = {
+		warn: 1,
+		correct: 2,
+		ask: 3,
+		deny: 4
+	};
+
+//#endregion
+//#region ../kernel/src/evaluate.ts
+	function listed(value, want) {
+		if (want === void 0) return true;
+		if (value === void 0) return false;
+		return typeof want === "string" ? value === want : want.includes(value);
+	}
+	function argMatches(match, args) {
+		const has = Object.hasOwn(args, match.name);
+		if (match.present !== void 0 && match.present !== has) return false;
+		if (!has) return match.above === void 0 && match.below === void 0 && match.equals === void 0 && match.oneOf === void 0;
+		const value = args[match.name];
+		if (match.above !== void 0) {
+			if (typeof value !== "number" || !(value > match.above)) return false;
+		}
+		if (match.below !== void 0) {
+			if (typeof value !== "number" || !(value < match.below)) return false;
+		}
+		if (match.equals !== void 0 && value !== match.equals) return false;
+		if (match.oneOf !== void 0) {
+			if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") return false;
+			if (!match.oneOf.includes(value)) return false;
+		}
+		return true;
+	}
+	function matches(when, facts) {
+		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.path !== void 0) {
+			const raw = facts.args[when.path.arg ?? "path"];
+			if (typeof raw !== "string") return false;
+			if (when.path.inside !== void 0 && !withinAny(raw, when.path.inside)) return false;
+			if (when.path.outside !== void 0 && withinAny(raw, when.path.outside)) return false;
+		}
+		if (when.host !== void 0) {
+			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 (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;
+		}
+		if (when.arg !== void 0) {
+			for (const one of when.arg) if (!argMatches(one, facts.args)) return false;
+		}
+		if (when.count !== void 0) {
+			const key = facts.capability;
+			if (key === void 0) return false;
+			if (!((facts.counts?.[key] ?? 0) > when.count.above)) return false;
+		}
+		return true;
+	}
+	function step(rule, effect) {
+		return {
+			rule: rule.id,
+			...rule.title === void 0 ? {} : { title: rule.title },
+			effect: effect.kind,
+			because: effect.because
+		};
+	}
+	/**
+	* Decide one call against one pack.
+	*
+	* Every matching rule lands in the trace; the strongest effect decides. Ties
+	* go to the first rule in pack order, so a pack reads top-down the way its
+	* author wrote it.
+	*
+	* `correct` is the effect the rest of this ecosystem does not have. A rival
+	* guardrail can allow a call or refuse it; a rule here can also rewrite an
+	* argument and let it through, recording what it changed. Refusing is not
+	* always the safe option — an agent denied mid-task retries, and the retry is
+	* rarely safer than the clamp would have been.
+	*/
+	function evaluate(pack, facts) {
+		const hits = [];
+		for (const rule of pack.rules) if (matches(rule.when, facts)) hits.push({
+			rule,
+			effect: rule.effect
+		});
+		if (hits.length === 0) return {
+			kind: "allow",
+			trace: [],
+			evaluated: pack.rules.length
+		};
+		hits.sort((a, b) => STRENGTH[b.effect.kind] - STRENGTH[a.effect.kind]);
+		const trace = hits.map((hit) => step(hit.rule, hit.effect));
+		const evaluated = pack.rules.length;
+		const strongest = hits[0];
+		if (strongest === void 0) return {
+			kind: "allow",
+			trace: [],
+			evaluated
+		};
+		const winner = strongest.effect.kind;
+		if (winner === "deny" || winner === "ask") return {
+			kind: winner,
+			rule: strongest.rule.id,
+			reason: strongest.effect.because,
+			trace,
+			evaluated
+		};
+		if (winner === "correct") {
+			const args = { ...facts.args };
+			for (const hit of hits) if (hit.effect.kind === "correct") Object.assign(args, hit.effect.set);
+			return {
+				kind: "correct",
+				rule: strongest.rule.id,
+				reason: strongest.effect.because,
+				args,
+				trace,
+				evaluated
+			};
+		}
+		return {
+			kind: "allow",
+			trace,
+			evaluated
+		};
+	}
+
+//#endregion
+//#region ../kernel/src/pack.ts
+	function isObject(value) {
+		return typeof value === "object" && value !== null && !Array.isArray(value);
+	}
+	var Check = class {
+		errors = [];
+		fail(path, message) {
+			this.errors.push({
+				path,
+				message
+			});
+		}
+		/** Reject any key the shape does not define. */
+		keys(path, value, allowed) {
+			for (const key of Object.keys(value)) if (!allowed.includes(key)) this.fail(`${path}.${key}`, `unknown field \`${key}\`; expected one of ${allowed.map((k) => `\`${k}\``).join(", ")}`);
+		}
+		text(path, value) {
+			if (typeof value !== "string" || value.trim() === "") {
+				this.fail(path, "expected a non-empty string");
+				return;
+			}
+			return value;
+		}
+		/** A field that accepts one name or a list of them. */
+		names(path, value) {
+			if (typeof value === "string") return value;
+			if (Array.isArray(value)) {
+				const out = [];
+				value.forEach((entry, index) => {
+					const one = this.text(`${path}[${index}]`, entry);
+					if (one !== void 0) out.push(one);
+				});
+				return out;
+			}
+			this.fail(path, "expected a string or an array of strings");
+		}
+		globs(path, value) {
+			if (!Array.isArray(value)) {
+				this.fail(path, "expected an array of path globs");
+				return;
+			}
+			const out = [];
+			value.forEach((entry, index) => {
+				const one = this.text(`${path}[${index}]`, entry);
+				if (one !== void 0) out.push(one);
+			});
+			return out;
+		}
+		number(path, value) {
+			if (typeof value !== "number" || !Number.isFinite(value)) {
+				this.fail(path, "expected a finite number");
+				return;
+			}
+			return value;
+		}
+	};
+	function readPathMatch(check, path, value) {
+		if (!isObject(value)) {
+			check.fail(path, "expected an object");
+			return;
+		}
+		check.keys(path, value, [
+			"arg",
+			"outside",
+			"inside"
+		]);
+		if (value.outside === void 0 && value.inside === void 0) check.fail(path, "expected `inside` or `outside`; a path matcher with neither matches nothing");
+		const out = {};
+		if (value.arg !== void 0) {
+			const arg = check.text(`${path}.arg`, value.arg);
+			if (arg !== void 0) out.arg = arg;
+		}
+		if (value.outside !== void 0) {
+			const globs = check.globs(`${path}.outside`, value.outside);
+			if (globs !== void 0) out.outside = globs;
+		}
+		if (value.inside !== void 0) {
+			const globs = check.globs(`${path}.inside`, value.inside);
+			if (globs !== void 0) out.inside = globs;
+		}
+		return out;
+	}
+	function readHostMatch(check, path, value) {
+		if (!isObject(value)) {
+			check.fail(path, "expected an object");
+			return;
+		}
+		check.keys(path, value, [
+			"arg",
+			"in",
+			"notIn"
+		]);
+		if (value.in === void 0 && value.notIn === void 0) check.fail(path, "expected `in` or `notIn`; a host matcher with neither matches nothing");
+		const out = {};
+		if (value.arg !== void 0) {
+			const arg = check.text(`${path}.arg`, value.arg);
+			if (arg !== void 0) out.arg = arg;
+		}
+		if (value.in !== void 0) {
+			const list = check.globs(`${path}.in`, value.in);
+			if (list !== void 0) out.in = list;
+		}
+		if (value.notIn !== void 0) {
+			const list = check.globs(`${path}.notIn`, value.notIn);
+			if (list !== void 0) out.notIn = list;
+		}
+		return out;
+	}
+	function readArgMatch(check, path, value) {
+		if (!isObject(value)) {
+			check.fail(path, "expected an object");
+			return;
+		}
+		check.keys(path, value, [
+			"name",
+			"above",
+			"below",
+			"equals",
+			"oneOf",
+			"present"
+		]);
+		const name = check.text(`${path}.name`, value.name);
+		if (name === void 0) return void 0;
+		const out = { name };
+		if (value.above !== void 0) {
+			const n = check.number(`${path}.above`, value.above);
+			if (n !== void 0) out.above = n;
+		}
+		if (value.below !== void 0) {
+			const n = check.number(`${path}.below`, value.below);
+			if (n !== void 0) out.below = n;
+		}
+		if (value.equals !== void 0) out.equals = value.equals;
+		if (value.oneOf !== void 0) if (!Array.isArray(value.oneOf)) check.fail(`${path}.oneOf`, "expected an array");
+		else out.oneOf = value.oneOf;
+		if (value.present !== void 0) if (typeof value.present !== "boolean") check.fail(`${path}.present`, "expected a boolean");
+		else out.present = value.present;
+		return out;
+	}
+	function readMatch(check, path, value) {
+		if (!isObject(value)) {
+			check.fail(path, "expected an object");
+			return {};
+		}
+		check.keys(path, value, [
+			"tool",
+			"capability",
+			"plugin",
+			"agent",
+			"path",
+			"host",
+			"arg",
+			"count"
+		]);
+		const out = {};
+		for (const key of [
+			"tool",
+			"capability",
+			"plugin",
+			"agent"
+		]) if (value[key] !== void 0) {
+			const names = check.names(`${path}.${key}`, value[key]);
+			if (names !== void 0) out[key] = names;
+		}
+		if (value.path !== void 0) {
+			const match = readPathMatch(check, `${path}.path`, value.path);
+			if (match !== void 0) out.path = match;
+		}
+		if (value.host !== void 0) {
+			const match = readHostMatch(check, `${path}.host`, value.host);
+			if (match !== void 0) out.host = match;
+		}
+		if (value.arg !== void 0) if (!Array.isArray(value.arg)) check.fail(`${path}.arg`, "expected an array of argument matchers");
+		else {
+			const list = [];
+			value.arg.forEach((entry, index) => {
+				const one = readArgMatch(check, `${path}.arg[${index}]`, entry);
+				if (one !== void 0) list.push(one);
+			});
+			out.arg = list;
+		}
+		if (value.count !== void 0) if (!isObject(value.count)) check.fail(`${path}.count`, "expected an object");
+		else {
+			check.keys(`${path}.count`, value.count, ["above"]);
+			const above = check.number(`${path}.count.above`, value.count.above);
+			if (above !== void 0) out.count = { above };
+		}
+		return out;
+	}
+	function readEffect(check, path, value) {
+		if (!isObject(value)) {
+			check.fail(path, "expected an object");
+			return;
+		}
+		const kind = value.kind;
+		if (kind !== "deny" && kind !== "ask" && kind !== "correct" && kind !== "warn") {
+			check.fail(`${path}.kind`, "expected `deny`, `ask`, `correct`, or `warn`");
+			return;
+		}
+		check.keys(path, value, kind === "correct" ? [
+			"kind",
+			"set",
+			"because"
+		] : ["kind", "because"]);
+		const because = check.text(`${path}.because`, value.because);
+		if (because === void 0) return void 0;
+		if (kind === "correct") {
+			if (!isObject(value.set) || Object.keys(value.set).length === 0) {
+				check.fail(`${path}.set`, "expected a non-empty object of arguments to set");
+				return;
+			}
+			return {
+				kind,
+				set: value.set,
+				because
+			};
+		}
+		return {
+			kind,
+			because
+		};
+	}
+	function readRule(check, path, value) {
+		if (!isObject(value)) {
+			check.fail(path, "expected an object");
+			return;
+		}
+		check.keys(path, value, [
+			"id",
+			"title",
+			"when",
+			"effect"
+		]);
+		const id = check.text(`${path}.id`, value.id);
+		const effect = readEffect(check, `${path}.effect`, value.effect);
+		if (value.when === void 0) check.fail(`${path}.when`, "expected an object");
+		const when = readMatch(check, `${path}.when`, value.when ?? {});
+		if (id === void 0 || effect === void 0) return void 0;
+		const rule = {
+			id,
+			when,
+			effect
+		};
+		if (value.title !== void 0) {
+			const title = check.text(`${path}.title`, value.title);
+			if (title !== void 0) rule.title = title;
+		}
+		return rule;
+	}
+	/** Parse and validate a pack. Never throws; every problem lands in `errors`. */
+	function parsePack(source) {
+		let raw;
+		try {
+			raw = JSON.parse(source);
+		} catch (error) {
+			return {
+				ok: false,
+				errors: [{
+					path: "",
+					message: `invalid JSON: ${error instanceof Error ? error.message : String(error)}`
+				}]
+			};
+		}
+		const check = new Check();
+		if (!isObject(raw)) return {
+			ok: false,
+			errors: [{
+				path: "",
+				message: "expected an object"
+			}]
+		};
+		check.keys("", raw, [
+			"prae",
+			"pack",
+			"version",
+			"baseline",
+			"rules"
+		]);
+		if (raw.prae !== "0.1") check.fail(".prae", "expected `\"0.1\"`; this is the only pack version this build reads");
+		const name = check.text(".pack", raw.pack);
+		const version = check.text(".version", raw.version);
+		let baseline;
+		if (raw.baseline !== void 0) if (!isObject(raw.baseline)) check.fail(".baseline", "expected an object");
+		else {
+			check.keys(".baseline", raw.baseline, ["capabilities"]);
+			const caps = check.globs(".baseline.capabilities", raw.baseline.capabilities);
+			if (caps !== void 0) baseline = { capabilities: caps };
+		}
+		const rules = [];
+		if (!Array.isArray(raw.rules)) check.fail(".rules", "expected an array");
+		else {
+			const seen = /* @__PURE__ */ new Set();
+			raw.rules.forEach((entry, index) => {
+				const rule = readRule(check, `rules[${index}]`, entry);
+				if (rule === void 0) return;
+				if (seen.has(rule.id)) {
+					check.fail(`rules[${index}].id`, `duplicate rule id \`${rule.id}\``);
+					return;
+				}
+				seen.add(rule.id);
+				rules.push(rule);
+			});
+		}
+		if (check.errors.length > 0) return {
+			ok: false,
+			errors: check.errors
+		};
+		if (name === void 0 || version === void 0) return {
+			ok: false,
+			errors: check.errors
+		};
+		return {
+			ok: true,
+			pack: {
+				prae: "0.1",
+				pack: name,
+				version,
+				...baseline === void 0 ? {} : { baseline },
+				rules
+			}
+		};
+	}
+
+//#endregion
+//#region src/playground/app.ts
+	const VERDICT_LABEL = {
+		allow: "ALLOWED",
+		ask: "HELD",
+		deny: "DENIED",
+		correct: "CORRECTED"
+	};
+	function esc(value) {
+		return String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+	}
+	/** `key=value` pairs, with numbers and booleans read as themselves. */
+	function parseArgs(text) {
+		const args = {};
+		for (const line of text.split("\n")) {
+			const trimmed = line.trim();
+			if (trimmed === "") continue;
+			const at = trimmed.indexOf("=");
+			if (at === -1) continue;
+			const key = trimmed.slice(0, at).trim();
+			const raw = trimmed.slice(at + 1).trim();
+			if (raw === "true") args[key] = true;
+			else if (raw === "false") args[key] = false;
+			else if (raw !== "" && !Number.isNaN(Number(raw))) args[key] = Number(raw);
+			else args[key] = raw;
+		}
+		return args;
+	}
+	function render(els) {
+		const parsed = parsePack(els.pack.value);
+		if (!parsed.ok) {
+			els.errors.innerHTML = `<div class="k" style="color:var(--veto-text)">PACK DID NOT PARSE</div><ul>${parsed.errors.map((e) => `<li><code>${esc(e.path || "<root>")}</code> — ${esc(e.message)}</li>`).join("")}</ul>`;
+			els.errors.hidden = false;
+			els.verdict.innerHTML = "<span class=\"big\" style=\"color:var(--muted)\">—</span>";
+			els.trace.innerHTML = "";
+			return;
+		}
+		els.errors.hidden = true;
+		const capability = els.capability.value.trim();
+		const countValue = Number(els.counts.value);
+		const counts = capability !== "" && Number.isFinite(countValue) && countValue > 0 ? { [capability]: countValue } : void 0;
+		const decision = evaluate(parsed.pack, {
+			tool: els.tool.value.trim(),
+			...capability === "" ? {} : { capability },
+			args: parseArgs(els.args.value),
+			...counts === void 0 ? {} : { counts }
+		});
+		const label = VERDICT_LABEL[decision.kind] ?? decision.kind.toUpperCase();
+		els.verdict.innerHTML = `<span class="big v-${esc(decision.kind)}">${esc(label)}</span>${decision.rule === void 0 ? "" : `<span class="clause">${esc(decision.rule)} · ${esc(decision.reason ?? "")}</span>`}`;
+		els.trace.innerHTML = decision.trace.length === 0 ? `<div class="none">No rule matched. ${decision.evaluated} considered.</div>` : decision.trace.map((step$1) => `<div class="step">
+  <span class="effect e-${esc(step$1.effect)}">${esc(step$1.effect.toUpperCase())}</span>
+  <span class="id">${esc(step$1.rule)}</span>
+  <span class="why">${esc(step$1.because)}</span>
+</div>`).join("") + `<div class="none">${decision.trace.length} matched of ${decision.evaluated} considered · strongest wins</div>`;
+	}
+	function start() {
+		const get = (id) => document.getElementById(id);
+		const els = {
+			pack: get("pack"),
+			tool: get("tool"),
+			args: get("args"),
+			capability: get("capability"),
+			counts: get("counts"),
+			verdict: get("verdict"),
+			trace: get("trace"),
+			errors: get("errors")
+		};
+		const update = () => render(els);
+		for (const el of [
+			els.pack,
+			els.tool,
+			els.args,
+			els.capability,
+			els.counts
+		]) el.addEventListener("input", update);
+		for (const button of document.querySelectorAll("[data-try]")) button.addEventListener("click", () => {
+			const spec = JSON.parse(button.dataset.try ?? "{}");
+			els.tool.value = spec.tool ?? "";
+			els.args.value = spec.args ?? "";
+			els.capability.value = spec.capability ?? "";
+			els.counts.value = spec.counts ?? "";
+			update();
+		});
+		update();
+	}
+	if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", start);
+	else start();
+
+//#endregion
+})();