@turri-dev/cli 0.0.0-stage → 0.1.1

package/dist/regenerate/os-sandbox.js

@@ -0,0 +1,243 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { basename, dirname, join, resolve, sep } from "node:path";
+/** The caps set inside the sandbox before the command runs: processes, and file size in 1024-byte blocks (8 GiB). */
+export const PROCESS_CAP = 4096;
+export const FILE_SIZE_CAP_BLOCKS = 8 * 1024 * 1024;
+/** A folder as the kernel sees it - symlinks resolved as far as it exists - since that is what both sandboxes check. */
+function real(path) {
+    // Neither sandbox runs on Windows: the paths are kept as they are, so what is generated is the same everywhere.
+    if (process.platform === "win32")
+        return path;
+    let head = resolve(path);
+    const tail = [];
+    for (;;) {
+        if (existsSync(head))
+            return join(realpathSync(head), ...tail.reverse());
+        const parent = dirname(head);
+        if (parent === head)
+            return resolve(path);
+        tail.push(basename(head));
+        head = parent;
+    }
+}
+/** What of macOS a command needs to read beyond the toolchains, besides `/usr`, `/bin`, `/System`: the loader's caches, the time zone, the developer tools. */
+export const MACOS_MACHINE = [
+    "/usr",
+    "/bin",
+    "/sbin",
+    "/System",
+    "/Library/Apple",
+    "/Library/Developer",
+    "/Library/Java",
+    "/Library/Frameworks",
+    "/Library/Preferences",
+    "/private/etc",
+    "/private/var/db/timezone",
+    "/private/var/db/dyld",
+    "/private/var/select",
+    "/opt/homebrew",
+    "/opt/local",
+    "/Applications/Xcode.app",
+    "/dev",
+];
+/** What of Linux a command needs to read beyond the toolchains. */
+export const LINUX_MACHINE = ["/usr", "/bin", "/sbin", "/lib", "/lib32", "/lib64", "/libx32", "/etc", "/opt", "/nix", "/snap", "/run/systemd/resolve"];
+/**
+ * What of the machine a command reads, from the environment it runs in: the system's folders, every folder on its PATH,
+ * the folders its toolchain variables point at, and the project's `toolchains:`. Only the PATH folders themselves, not
+ * their parents - `~/.cargo/bin`, not `~/.cargo`, which holds a registry's credentials - but for a version manager's
+ * install: a `bin` whose parent is a version, `…/installs/node/24.16.0/bin`, links its tools into the install beside it
+ * (`npm` into `lib/node_modules`), and an install holds the toolchain, never a credential.
+ */
+export function machineFor(env, toolchainVariables, extra = [], platform = process.platform) {
+    const base = platform === "darwin" ? MACOS_MACHINE : platform === "linux" ? LINUX_MACHINE : [];
+    const onPath = (env.PATH ?? "").split(platform === "win32" ? ";" : ":").filter((dir) => dir.startsWith("/"));
+    const installs = onPath.flatMap((dir) => {
+        const install = /^(.*\/v?\d+\.\d+(?:\.\d+)?[^/]*)\/bin\/?$/.exec(dir)?.[1];
+        return install !== undefined ? [install] : [];
+    });
+    const located = toolchainVariables.map((name) => env[name]).filter((dir) => dir !== undefined && dir.startsWith("/"));
+    return [...new Set([...base, ...onPath, ...installs, ...located, ...extra])];
+}
+function sbplString(path) {
+    return `"${path.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+/**
+ * The Seatbelt profile for a fence. Everything is allowed but what it names - reading file contents outside the
+ * allow-list, writing outside the writable folders, the code record, Unix sockets outside the folders, signals and
+ * process information beyond the sandbox - later rules winning over earlier ones. File metadata stays readable, as
+ * resolving a path needs.
+ */
+export function seatbeltProfile(fence, userDirs = darwinUserDirs()) {
+    // The machine's folders as given - they are the system's own spelling; the fence's with their symlinks resolved.
+    const subpaths = (paths, resolveLinks = true) => paths.map((path) => `  (subpath ${sbplString(resolveLinks ? real(path) : path)})`).join("\n");
+    const readable = [...fence.read, ...fence.write, ...fence.writable];
+    const writable = [...fence.write, ...fence.writable];
+    return [
+        "(version 1)",
+        "(allow default)",
+        ";; Reading: the machine's allow-list and the fence, nothing else.",
+        "(deny file-read-data file-read-xattr)",
+        "(allow file-read-data file-read-xattr",
+        '  (literal "/")',
+        '  (literal "/etc") (literal "/var") (literal "/tmp") (literal "/private/var/run/resolv.conf")',
+        subpaths(fence.machine, false),
+        subpaths(readable),
+        ")",
+        ";; Writing: its own folders, the module's home, TMPDIR and caches, the devices.",
+        "(deny file-write*)",
+        "(allow file-write*",
+        subpaths(writable),
+        '  (literal "/dev/null") (literal "/dev/zero") (literal "/dev/tty") (literal "/dev/dtracehelper")',
+        '  (regex #"^/dev/fd/")',
+        ")",
+        ...darwinToolCaches(userDirs),
+        ";; The code record is the harness's. (A wildcard deny does not override an allow of one operation: each is named.)",
+        ...(fence.deny.length > 0 ? [`(deny file-read-data file-read-xattr file-write*${fence.deny.map((path) => ` (literal ${sbplString(real(path))})`).join("")})`] : []),
+        ";; No Unix socket outside its folders: the Docker daemon, an SSH agent, the person's services.",
+        "(deny network-outbound (remote unix-socket))",
+        `(allow network-outbound (remote unix-socket (path-literal "/private/var/run/mDNSResponder")) (remote unix-socket (subpath ${sbplString(real(fence.cwd))}))${writable.map((path) => ` (remote unix-socket (subpath ${sbplString(real(path))}))`).join("")})`,
+        ";; Signals and process information: only within this sandbox.",
+        "(deny signal)",
+        "(allow signal (target same-sandbox))",
+        "(deny process-info*)",
+        "(allow process-info* (target same-sandbox))",
+        "(allow process-info-pidinfo process-info-setcontrol (target self))",
+        "",
+    ].join("\n");
+}
+/** macOS's per-user temporary and cache folders, as `getconf` gives them - asked once. */
+let darwinDirs;
+export function darwinUserDirs() {
+    if (darwinDirs !== undefined)
+        return darwinDirs;
+    const ask = (name) => {
+        if (process.platform !== "darwin")
+            return undefined;
+        const run = spawnSync("getconf", [name], { encoding: "utf8", timeout: 5000 });
+        const dir = run.status === 0 ? run.stdout.trim().replace(/\/$/, "") : "";
+        return dir !== "" ? real(dir) : undefined;
+    };
+    darwinDirs = { temp: ask("DARWIN_USER_TEMP_DIR"), cache: ask("DARWIN_USER_CACHE_DIR") };
+    return darwinDirs;
+}
+/**
+ * The developer tools' own scratch files on macOS: `xcrun` (behind `/usr/bin/git`, `clang`, `make`) keeps a database in
+ * the per-user temporary folder, and clang its module cache in the per-user cache folder - whatever TMPDIR says.
+ */
+function darwinToolCaches({ temp, cache }) {
+    const rules = [];
+    const regex = (path) => path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (temp !== undefined)
+        rules.push(`(allow file-read-data file-write* (regex #"^${regex(temp)}/xcrun_db"))`);
+    if (cache !== undefined)
+        rules.push(`(allow file-read-data file-write* (subpath ${sbplString(join(cache, "clang"))}) (subpath ${sbplString(join(cache, "com.apple.dt.xcrun"))}))`);
+    return rules.length > 0 ? [";; The developer tools' own scratch files.", ...rules] : [];
+}
+/** The bubblewrap arguments for a fence, up to the command. `proc: "bind"` binds the host's /proc where mounting one is refused. */
+export function bubblewrapArgs(fence, options = { proc: "mount" }) {
+    const args = ["--die-with-parent", "--unshare-pid", "--unshare-ipc", "--unshare-uts", "--unshare-cgroup-try"];
+    for (const path of fence.machine)
+        args.push("--ro-bind-try", path, path);
+    args.push(...(options.proc === "mount" ? ["--proc", "/proc"] : ["--ro-bind", "/proc", "/proc"]));
+    args.push("--dev", "/dev", "--tmpfs", "/tmp");
+    for (const path of fence.read)
+        args.push("--ro-bind", real(path), real(path));
+    for (const path of [...fence.write, ...fence.writable])
+        args.push("--bind", real(path), real(path));
+    // The record: covered by an empty file, unreadable and unwritable.
+    for (const path of fence.deny)
+        if (existsSync(path))
+            args.push("--ro-bind", "/dev/null", real(path));
+    args.push("--chdir", real(fence.cwd));
+    return args;
+}
+/** The caps, set inside the sandbox, then the command itself. */
+function capped(argv) {
+    const caps = `ulimit -S -u ${PROCESS_CAP} 2>/dev/null; ulimit -S -f ${FILE_SIZE_CAP_BLOCKS} 2>/dev/null; exec "$@"`;
+    return ["/bin/bash", "-c", caps, "turri", ...argv];
+}
+/** How a command is run behind the wall that is up: for the host runner's `wrap`. Where none is, it runs as it is. */
+export function sandboxWrap(wall, fence) {
+    if (wall.kind === "seatbelt")
+        return (argv) => ["/usr/bin/sandbox-exec", "-p", seatbeltProfile(fence), ...capped(argv)];
+    if (wall.kind === "bubblewrap")
+        return (argv) => ["bwrap", ...bubblewrapArgs(fence, { proc: wall.proc }), "--", ...capped(argv)];
+    return (argv) => argv;
+}
+/** What bubblewrap's refusal to start says is missing, and how to give it - each failure has a message of its own. */
+export function whyBubblewrapFailed(output) {
+    if (/ENOENT|not found|No such file or directory: 'bwrap'|spawnSync bwrap/i.test(output) && !/Can't mount/.test(output)) {
+        return { why: "bubblewrap is not installed", fix: "install it: `apt install bubblewrap` (or your distribution's package)" };
+    }
+    if (/Creating new namespace failed: Operation not permitted|No permissions to create a new namespace/.test(output)) {
+        return {
+            why: "this machine does not let an unprivileged process create a user namespace",
+            fix: "in Docker, run the container as a user that is not root (`--user`), with `--security-opt seccomp=unconfined`; on the host, `sysctl -w kernel.unprivileged_userns_clone=1`",
+        };
+    }
+    if (/setting up uid map: Permission denied|Failed to make \/ slave: Permission denied/.test(output)) {
+        return {
+            why: "AppArmor keeps bubblewrap from setting up its namespace",
+            fix: "in Docker, add `--security-opt apparmor=unconfined`; on Ubuntu 24.04, `sysctl -w kernel.apparmor_restrict_unprivileged_userns=0` or an AppArmor profile for bwrap",
+        };
+    }
+    if (/Can't mount proc on (\/newroot)?\/proc/.test(output)) {
+        return { why: "the container masks /proc", fix: "in Docker, add `--security-opt systempaths=unconfined`" };
+    }
+    return { why: `bubblewrap did not start: ${output.trim().split("\n")[0] ?? "no reason given"}` };
+}
+let probed;
+/** For tests: forget what was found, or say what to find. */
+export function setSandboxForTests(wall) {
+    probed = wall;
+}
+/**
+ * Which wall is up on this machine - tried once, by starting a sandbox that runs `true` - and, when none starts, why
+ * and how to give it one.
+ */
+export function sandboxAvailable() {
+    if (probed !== undefined)
+        return probed;
+    probed = probe();
+    return probed;
+}
+function probe() {
+    if (process.platform === "darwin") {
+        if (!existsSync("/usr/bin/sandbox-exec"))
+            return { kind: "none", why: "this macOS has no sandbox-exec (Seatbelt)" };
+        const run = spawnSync("/usr/bin/sandbox-exec", ["-p", "(version 1)(allow default)", "/usr/bin/true"], { encoding: "utf8", timeout: 10_000 });
+        return run.status === 0 ? { kind: "seatbelt" } : { kind: "none", why: `Seatbelt did not start: ${(run.stderr || String(run.error ?? "")).trim()}` };
+    }
+    if (process.platform === "linux") {
+        const tryProc = (proc) => spawnSync("bwrap", ["--ro-bind", "/", "/", ...(proc === "mount" ? ["--proc", "/proc"] : ["--ro-bind", "/proc", "/proc"]), "--dev", "/dev", "--unshare-pid", "--", "true"], {
+            encoding: "utf8",
+            timeout: 10_000,
+        });
+        const mounted = tryProc("mount");
+        if (mounted.status === 0)
+            return { kind: "bubblewrap", proc: "mount" };
+        const output = `${mounted.stderr ?? ""}${mounted.error !== undefined ? String(mounted.error) : ""}`;
+        if (/Can't mount proc on (\/newroot)?\/proc/.test(output) && tryProc("bind").status === 0)
+            return { kind: "bubblewrap", proc: "bind" };
+        return { kind: "none", ...whyBubblewrapFailed(output) };
+    }
+    if (process.platform === "win32")
+        return { kind: "none", why: "Windows has no OS sandbox turri drives: the command check and the audit hold alone" };
+    return { kind: "none", why: `${process.platform} has no OS sandbox turri drives` };
+}
+/** Whether `path` is one of the fence's roots or under one - for the tests and the audit. */
+export function underAny(path, roots) {
+    const target = real(path);
+    return roots.some((root) => {
+        const base = real(root);
+        return target === base || target.startsWith(base + sep);
+    });
+}
+/** Where the agents' commands run, in one line for the person: which walls are up, or that only the shared ones are. */
+export function sandboxSummary(wall = sandboxAvailable()) {
+    if (wall.kind === "none")
+        return { level: "limited", text: `agents' commands run on this machine behind the command check and the audit - no OS sandbox: ${wall.why} (turri doctor)` };
+    return { level: "ok", text: `agents' commands run on this machine behind the command check, ${wall.kind === "seatbelt" ? "Seatbelt" : "bubblewrap"} and the audit` };
+}

package/dist/regenerate/paths.js

@@ -0,0 +1,165 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * The ***plain standard library: import modules for generic pieces of software that ship with turri,
+ * imported as `stdlib/backend/python-fastapi` - a reserved name (see plain/stdlib.ts).
+ */
+export const STDLIB_DIR = join(dirname(dirname(dirname(fileURLToPath(import.meta.url)))), "stdlib");
+/**
+ * Where a module's generated code and tests live.
+ *
+ * Everything a module produces sits under `plain_modules/<module>/`, next to the specs it
+ * came from and inside the project's own repository: `code/` holds the implementation and
+ * its unit tests, `tests/` the black-box conformance tests - of every functionality built so
+ * far, the required modules' included, organised however suits them.
+ * The build state is written into `code/`, so what a codebase contains travels with that
+ * codebase instead of living in a scratch directory that can be cleared without anyone
+ * noticing the specs and the code have drifted apart.
+ */
+export const MODULES_DIR = "plain_modules";
+export function moduleDir(moduleName, cwd = process.cwd()) {
+    return join(cwd, MODULES_DIR, moduleName);
+}
+/** Implementation and unit tests: `plain_modules/<module>/code`. */
+export function defaultBuildDir(moduleName, cwd = process.cwd()) {
+    return join(moduleDir(moduleName, cwd), "code");
+}
+/**
+ * The directory every module's output hangs off, `plain_modules` by default.
+ *
+ * Callers override this to build somewhere else - a sandbox, a test fixture - and the
+ * layout underneath it stays the same.
+ */
+/**
+ * The project a spec belongs to: the nearest folder, from the spec's own up, that holds a
+ * `config.turri.yaml`, a stack's `config.turri.<stack>.yaml`, the `config.yaml` turri read before it had a file of
+ * its own, or a `plain_modules` - where its code is built, its config read, its testing scripts found. Without any, the
+ * spec's own folder. So `plain/hubspot.plain`, beside `plain/config.turri.yaml` and `plain/plain_modules`, is built there,
+ * wherever turri was started;
+ * specs at the root of their project are built where they always were.
+ */
+export function projectDirOf(plainFile) {
+    const start = dirname(resolve(plainFile));
+    for (let dir = start;; dir = dirname(dir)) {
+        if (existsSync(join(dir, "config.yaml")) || existsSync(join(dir, MODULES_DIR)) || hasModuleConfig(dir))
+            return dir;
+        if (dirname(dir) === dir)
+            return start;
+    }
+}
+/** Whether a folder holds a config file - config.turri.yaml, a stack's config.turri.<stack>.yaml, or one in the old naming - which makes it a project too. */
+function hasModuleConfig(dir) {
+    try {
+        return readdirSync(dir).some((name) => /^config\..+\.yaml$/.test(name));
+    }
+    catch {
+        return false;
+    }
+}
+export function modulesRoot(cwd = process.cwd()) {
+    return join(cwd, MODULES_DIR);
+}
+export function buildDirUnder(root, moduleName) {
+    return join(root, moduleName, "code");
+}
+export function testsDirUnder(root, moduleName) {
+    return join(root, moduleName, "tests");
+}
+/**
+ * The `plain_modules` a directory sits in: what holds every module's code and tests. A
+ * directory outside one - a sandbox, an explicit `--build-dir` - is its own root, so this
+ * never silently widens to a whole disk.
+ */
+export function modulesRootOf(dir) {
+    const parts = resolve(dir).split(sep);
+    const index = parts.lastIndexOf(MODULES_DIR);
+    return index === -1 ? resolve(dir) : parts.slice(0, index + 1).join(sep);
+}
+/**
+ * `.turri` inside the modules root: what turri keeps beside the code - the package
+ * caches, the modules' homes and temporary folders, the copies test runs happen in, the
+ * outputs kept for read_output. Ignored by the project's history.
+ */
+export function modulesScratchDir(dir) {
+    return join(modulesRootOf(dir), ".turri");
+}
+/** Make `path` inside the modules' scratch, which ignores itself. Returns `path`. */
+export function ensureInModulesScratch(dir, path) {
+    return ensureInScratch(modulesScratchDir(dir), path);
+}
+/** Where the project keeps what `deploy` puts out: `dist/`, beside `plain_modules`. */
+export const DIST_DIR = "dist";
+/**
+ * Where a person tries a module: `<project>/dist/<module>`, the module's code as its last commit has
+ * it. Outside `plain_modules`, so no agent can reach it, and replaced whole by every deploy.
+ */
+export function distDirFor(projectDir, moduleName) {
+    return join(projectDir, DIST_DIR, moduleName);
+}
+/**
+ * The project a directory belongs to: the one `plain_modules` sits in, when the directory is
+ * inside it; otherwise the directory's parent for a build folder, or the directory itself.
+ */
+export function projectRootOf(dir) {
+    const parts = resolve(dir).split(sep);
+    const index = parts.lastIndexOf(MODULES_DIR);
+    return index === -1 ? resolve(dir) : parts.slice(0, index).join(sep);
+}
+/**
+ * `.turri` in the project: the harness's own scratch space - copies to try things in,
+ * saved agent sessions. Never part of the project's history, so it ignores itself - but for `skills/`, the
+ * project's own skills.
+ */
+export function scratchDir(dir) {
+    const parts = resolve(dir).split(sep);
+    const index = parts.lastIndexOf(MODULES_DIR);
+    const project = index === -1 ? dirname(resolve(dir)) : parts.slice(0, index).join(sep);
+    return join(project, ".turri");
+}
+/**
+ * Where a skill run keeps its state - the manifest an interrupted run resumes from, the evidence
+ * each phase's gate is judged on: `.turri/runs/<skill>` in the project, beside the rest of
+ * turri's scratch, ignored by the project's history like it.
+ */
+export function skillRunDir(cwd, skillName) {
+    const scratch = join(resolve(cwd), ".turri");
+    return ensureInScratch(scratch, join(scratch, "runs", skillName));
+}
+/**
+ * What the scratch dir's .gitignore says: everything in it is ignored but `skills/` - the project's own skills
+ * (skills.ts), which are written by hand and kept in its history.
+ */
+export const SCRATCH_IGNORE = "*\n!skills/\n!skills/**\n";
+/** Make `path`, inside a scratch dir, and see that the scratch dir ignores itself, its skills apart. Returns `path`. */
+export function ensureInScratch(scratch, path) {
+    mkdirSync(path, { recursive: true });
+    const ignore = join(scratch, ".gitignore");
+    // One written before skills were kept here ignored them too: it is brought up to date.
+    if (!existsSync(ignore) || readFileSync(ignore, "utf8") === "*\n")
+        writeFileSync(ignore, SCRATCH_IGNORE);
+    return path;
+}
+/** Where agent sessions are saved, so what an agent did can be read - and resumed - later. */
+export function sessionsDir(project) {
+    const scratch = scratchDir(join(project, MODULES_DIR));
+    return ensureInScratch(scratch, join(scratch, "sessions"));
+}
+/**
+ * Template search order, matching file_utils.get_template_directories: the plain file's
+ * own directory first, then a sibling `template/` directory if there is one (where a
+ * project keeps its import modules), then anything passed in, then PLAIN_TEMPLATE_DIRS.
+ * A `stdlib/...` import is not looked for in them: it is turri's (see plain/stdlib.ts).
+ */
+export function resolveTemplateDirs(plainFile, extra = []) {
+    const own = dirname(resolve(plainFile));
+    const dirs = [own];
+    const sibling = join(own, "template");
+    if (existsSync(sibling))
+        dirs.push(sibling);
+    dirs.push(...extra.map((dir) => resolve(dir)));
+    const fromEnv = process.env.PLAIN_TEMPLATE_DIRS;
+    if (fromEnv)
+        dirs.push(...fromEnv.split(":").filter(Boolean).map((dir) => resolve(dir)));
+    return [...new Set(dirs)];
+}

package/dist/regenerate/plain-palette.js

@@ -0,0 +1,83 @@
+/** On a dark surface - turri-dark's #0f0f0f, pi's dark ones. Every colour at least 7:1 on it, and 4.5:1 on the fills. */
+const DARK = {
+    roles: {
+        section: { colour: "#fcd34d", bold: true },
+        concept: { colour: "#7dd3fc" },
+        link: { colour: "#c4b5fd", underline: true },
+        literal: { colour: "#fdba74" },
+        keyword: { colour: "#f9a8d4", bold: true },
+        module: { colour: "#5eead4" },
+        comment: { colour: "#b4bfcf", italic: true },
+        bullet: { colour: "#b4bfcf" },
+    },
+    added: "#86efac",
+    removed: "#fca5a5",
+    addedFill: "#1f4d2e",
+    removedFill: "#5c2323",
+    muted: "#808080",
+};
+/** On a light surface - turri-light's white, pi's light ones. Every colour at least 7:1 on it, and 5:1 on the fills. */
+const LIGHT = {
+    roles: {
+        section: { colour: "#0a1fd4", bold: true },
+        concept: { colour: "#155e75" },
+        link: { colour: "#6d28d9", underline: true },
+        literal: { colour: "#92400e" },
+        keyword: { colour: "#9d174d", bold: true },
+        module: { colour: "#065f46" },
+        comment: { colour: "#475569", italic: true },
+        bullet: { colour: "#475569" },
+    },
+    added: "#166534",
+    removed: "#991b1b",
+    addedFill: "#d3f5dc",
+    removedFill: "#fcd9d9",
+    muted: "#6b7280",
+};
+const rgb = (hex) => {
+    const value = Number.parseInt(hex.slice(1), 16);
+    return [(value >> 16) & 255, (value >> 8) & 255, value & 255];
+};
+/** A colour's SGR parameters: 24-bit, or the nearest of the 256 where the terminal has no more. */
+function sgr(hex, background, truecolor) {
+    const [r, g, b] = rgb(hex);
+    if (truecolor)
+        return `${background ? 48 : 38};2;${r};${g};${b}`;
+    const step = (value) => (value < 48 ? 0 : value < 115 ? 1 : Math.min(5, Math.floor((value - 35) / 40)));
+    return `${background ? 48 : 38};5;${16 + 36 * step(r) + 6 * step(g) + step(b)}`;
+}
+const paintWith = (ink, text, truecolor) => {
+    const on = [sgr(ink.colour, false, truecolor), ...(ink.bold ? ["1"] : []), ...(ink.italic ? ["3"] : []), ...(ink.underline ? ["4"] : [])].join(";");
+    const off = ["39", ...(ink.bold ? ["22"] : []), ...(ink.italic ? ["23"] : []), ...(ink.underline ? ["24"] : [])].join(";");
+    return `\x1b[${on}m${text}\x1b[${off}m`;
+};
+/** A fill behind a whole row: set again after every reset inside it, so nothing in the row ends it early. */
+const fillWith = (hex, text, truecolor) => {
+    const on = `\x1b[${sgr(hex, true, truecolor)}m`;
+    return `${on}${text.replace(/\x1b\[(?:0|49)?m/g, (reset) => `${reset}${on}`)}\x1b[49m`;
+};
+/**
+ * Brand blue, for what is shown to do what its spec says - regen's ◆. Brand blue itself on a light surface, 9.72:1
+ * on white; on a dark one, where it is illegible (1.97:1 on brand black - see docs/theming.md), its tint 55% of the way
+ * to white, 7.34:1 on brand black.
+ */
+export const BRAND_BLUE = { light: "#0a1fd4", dark: "#919aec" };
+/** Text in brand blue on a theme - its tint on a dark one - in as many colours as the terminal has. */
+export function brandBlue(theme) {
+    const colour = theme.appearance === "light" ? BRAND_BLUE.light : BRAND_BLUE.dark;
+    const truecolor = (theme.getColorMode?.() ?? "truecolor") === "truecolor";
+    return (text) => paintWith({ colour, bold: true }, text, truecolor);
+}
+/** How a spec diff is painted on a theme: its palette by whether the theme is dark or light, in as many colours as the terminal has. */
+export function plainPaint(theme) {
+    const palette = theme.appearance === "light" ? LIGHT : DARK;
+    const truecolor = (theme.getColorMode?.() ?? "truecolor") === "truecolor";
+    return {
+        syntax: (role, text) => paintWith(palette.roles[role], text, truecolor),
+        added: (text) => paintWith({ colour: palette.added, bold: true }, text, truecolor),
+        removed: (text) => paintWith({ colour: palette.removed, bold: true }, text, truecolor),
+        addedBand: (text) => fillWith(palette.addedFill, text, truecolor),
+        removedBand: (text) => fillWith(palette.removedFill, text, truecolor),
+        muted: (text) => paintWith({ colour: palette.muted }, text, truecolor),
+    };
+}