@illuminis/comprism 0.1.4 → 0.1.6

package/out/machine/executor/toolservers.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolServers = void 0;
+/**
+ * Tool servers on this machine (manual 9.10): started when a job needs one,
+ * spoken to over standard input and output, stopped when the job ends.
+ *
+ * A local helper and nothing more. Which servers exist, whether one may run
+ * in this project, whether a call is allowed and what a result means are all
+ * the service's. This starts the command the person approved, asks for the
+ * tool list, carries one call, and reports what came back or why nothing did.
+ *
+ * Only the two methods an agent needs: list the tools, call a tool.
+ */
+const child_process_1 = require("child_process");
+/** How long one request may take before it is reported as not answered. */
+const timeoutMs = () => Number(process.env.COMPRISM_TOOL_SERVER_TIMEOUT_MS || 30_000);
+/** What one result may carry back. The service cuts it again. */
+const MAX_RESULT_CHARS = 20_000;
+class Server {
+    name;
+    command;
+    proc;
+    buffer = "";
+    nextId = 1;
+    pending = new Map();
+    gone = null;
+    ready;
+    constructor(name, command, cwd) {
+        this.name = name;
+        this.command = command;
+        // The command exactly as the person approved it, through their shell, the
+        // way they would type it themselves.
+        // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- the tool server command exactly as the person approved it
+        this.proc = (0, child_process_1.spawn)(this.command, { cwd, shell: true, stdio: ["pipe", "pipe", "pipe"],
+            windowsHide: true });
+        this.proc.stdout.setEncoding("utf8");
+        this.proc.stdout.on("data", (chunk) => this.read(chunk));
+        this.proc.stderr.on("data", () => { });
+        this.proc.stdin.on("error", () => { });
+        this.proc.on("error", (e) => this.fail(`could not be started: ${e.message}`));
+        this.proc.on("exit", (code) => this.fail(`stopped${code === null ? "" : ` (exit ${code})`}`));
+        this.ready = this.request("initialize", {
+            protocolVersion: "2025-06-18", capabilities: {},
+            clientInfo: { name: "comprism", version: "1" },
+        }).then(() => { this.notify("notifications/initialized"); });
+        this.ready.catch(() => { });
+    }
+    fail(why) {
+        if (this.gone)
+            return;
+        this.gone = `The tool server ${this.name} ${why}.`;
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(new Error(this.gone));
+        }
+        this.pending.clear();
+    }
+    read(chunk) {
+        this.buffer += chunk;
+        let at;
+        while ((at = this.buffer.indexOf("\n")) >= 0) {
+            const line = this.buffer.slice(0, at).trim();
+            this.buffer = this.buffer.slice(at + 1);
+            if (!line)
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                // A reply that is not a reply: every waiting request is told so.
+                for (const [id, p] of this.pending) {
+                    clearTimeout(p.timer);
+                    p.reject(new Error(`The tool server ${this.name} sent something that is not a reply.`));
+                    this.pending.delete(id);
+                }
+                continue;
+            }
+            const id = typeof msg.id === "number" ? msg.id : Number(msg.id);
+            const waiting = this.pending.get(id);
+            if (!waiting)
+                continue;
+            clearTimeout(waiting.timer);
+            this.pending.delete(id);
+            if (msg.error) {
+                const e = msg.error;
+                waiting.reject(new Error(`The tool server ${this.name} refused: ${e.message ?? "an error"}.`));
+            }
+            else {
+                waiting.resolve((msg.result ?? {}));
+            }
+        }
+    }
+    notify(method) {
+        if (this.gone)
+            return;
+        this.proc.stdin.write(JSON.stringify({ jsonrpc: "2.0", method }) + "\n");
+    }
+    request(method, params) {
+        if (this.gone)
+            return Promise.reject(new Error(this.gone));
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`The tool server ${this.name} did not answer within ${Math.max(1, Math.round(timeoutMs() / 1000))} seconds.`));
+            }, timeoutMs());
+            this.pending.set(id, { resolve, reject, timer });
+            this.proc.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
+        });
+    }
+    stop() {
+        this.fail("was stopped");
+        try {
+            this.proc.stdin.end();
+        }
+        catch { /* already closed */ }
+        // On Windows the command runs under cmd.exe, and ending cmd.exe leaves
+        // the server itself running. The whole tree is ended instead, so nothing
+        // outlives the job (manual 9.10).
+        if (process.platform === "win32" && this.proc.pid && this.proc.exitCode === null) {
+            try {
+                (0, child_process_1.spawnSync)("taskkill", ["/pid", String(this.proc.pid), "/T", "/F"], { windowsHide: true, stdio: "ignore" });
+                return;
+            }
+            catch { /* fall through to the ordinary stop */ }
+        }
+        try {
+            this.proc.kill();
+        }
+        catch { /* already gone */ }
+    }
+}
+/** The tool servers one job started, by name. */
+class ToolServers {
+    cwd;
+    running = new Map();
+    constructor(cwd) {
+        this.cwd = cwd;
+    }
+    async server(name, command) {
+        let s = this.running.get(name);
+        if (!s || s.command !== command) {
+            s?.stop();
+            s = new Server(name, command, this.cwd);
+            this.running.set(name, s);
+        }
+        await s.ready;
+        return s;
+    }
+    /** The server's tools, as it described them, as JSON text. */
+    async list(name, command) {
+        try {
+            const s = await this.server(name, command);
+            const r = await s.request("tools/list", {});
+            if (!Array.isArray(r.tools)) {
+                return { isError: true, content: `The tool server ${name} sent something that is not a tool list.` };
+            }
+            return { isError: false, content: JSON.stringify(r.tools) };
+        }
+        catch (e) {
+            this.running.get(name)?.stop();
+            this.running.delete(name);
+            return { isError: true, content: e.message };
+        }
+    }
+    /** One call, and the text the server returned. */
+    async call(name, command, tool, args) {
+        try {
+            const s = await this.server(name, command);
+            const r = await s.request("tools/call", { name: tool, arguments: args ?? {} });
+            const blocks = Array.isArray(r.content) ? r.content : [];
+            const text = blocks.filter((b) => b.type === "text").map((b) => String(b.text ?? "")).join("\n").trim();
+            return { isError: r.isError === true, content: (text || "(the tool returned nothing)").slice(0, MAX_RESULT_CHARS) };
+        }
+        catch (e) {
+            return { isError: true, content: e.message };
+        }
+    }
+    /** Every server this job started, stopped. Called when the job ends. */
+    stopAll() {
+        for (const [, s] of this.running)
+            s.stop();
+        this.running.clear();
+    }
+    get count() { return this.running.size; }
+}
+exports.ToolServers = ToolServers;

package/out/machine/executor/worktree.d.ts

@@ -0,0 +1,9 @@
+import { RunResult, ShellOptions } from "./shell";
+/** Where a copy is, by its id, or undefined. */
+export declare function worktreePath(id: string): string | undefined;
+export declare function openWorktree(id: string, opts: ShellOptions): Promise<RunResult>;
+/** What the helper changed in its copy, as one diff. */
+export declare function diffWorktree(id: string, opts: ShellOptions): Promise<RunResult>;
+export declare function closeWorktree(id: string, opts: ShellOptions): Promise<RunResult>;
+/** Every copy this process made, removed; for the end of a session. */
+export declare function closeAllWorktrees(root: string): Promise<void>;

package/out/machine/executor/worktree.js

@@ -0,0 +1,119 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.worktreePath = worktreePath;
+exports.openWorktree = openWorktree;
+exports.diffWorktree = diffWorktree;
+exports.closeWorktree = closeWorktree;
+exports.closeAllWorktrees = closeAllWorktrees;
+/**
+ * A helper's own copy of the project (manual 5.26).
+ *
+ * A git worktree in the temporary folder, started from the project as it is
+ * now: the last commit plus the person's uncommitted changes to tracked files,
+ * committed inside the copy as its starting point. The helper's edits land
+ * there and nowhere else; what comes back is a diff against that starting
+ * point, which the service applies to the real folder with the usual approval.
+ * Nothing here decides anything: it makes the copy, reads its diff, and
+ * removes it.
+ */
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const shell_1 = require("./shell");
+const copies = new Map();
+const git = (args, opts) => (0, shell_1.runProgram)("git", args, opts);
+const okExit = (r) => !r.isError && /^exit 0/.test(r.content);
+const body = (r) => r.content.replace(/^exit -?\d+\n\n/, "");
+/** Where a copy is, by its id, or undefined. */
+function worktreePath(id) {
+    return copies.get(id);
+}
+async function openWorktree(id, opts) {
+    if (!/^[\w-]{1,40}$/.test(id))
+        return { isError: true, content: "Refused: not a usable copy name." };
+    if (copies.has(id))
+        return { content: copies.get(id), summary: `copy ${id}` };
+    const where = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), `comprism-helper-${id}-`));
+    fs.rmdirSync(where);
+    const made = await git(["worktree", "add", "--detach", "-q", where, "HEAD"], opts);
+    if (!okExit(made))
+        return { isError: true, content: `A separate copy could not be made: ${body(made)}` };
+    const inCopy = { ...opts, root: where, cwd: undefined };
+    // The person's uncommitted changes, so the helper starts from what they see.
+    const pending = await git(["diff", "--binary", "HEAD"], opts);
+    const patch = body(pending);
+    if (okExit(pending) && patch.trim() && patch.trim() !== "(no output)") {
+        const file = path.join(where, ".comprism-start.patch");
+        fs.writeFileSync(file, patch.endsWith("\n") ? patch : `${patch}\n`);
+        await git(["apply", "--whitespace=nowarn", file], inCopy);
+        fs.unlinkSync(file);
+    }
+    await git(["add", "-A"], inCopy);
+    await git(["-c", "user.name=comprism", "-c", "user.email=helper@illuminis.ai",
+        "commit", "-q", "--allow-empty", "--no-verify", "-m", "start"], inCopy);
+    copies.set(id, fs.realpathSync(where));
+    return { content: copies.get(id), summary: `copy ${id}` };
+}
+/** What the helper changed in its copy, as one diff. */
+async function diffWorktree(id, opts) {
+    const where = copies.get(id);
+    if (!where)
+        return { isError: true, content: `There is no copy called ${id}.` };
+    const inCopy = { ...opts, root: where, cwd: undefined };
+    await git(["add", "-A"], inCopy);
+    const d = await git(["--no-pager", "diff", "--cached", "--binary", "--no-color", "HEAD"], inCopy);
+    if (!okExit(d))
+        return { isError: true, content: body(d) };
+    const text = body(d).trim() === "(no output)" ? "" : body(d);
+    return { content: text, summary: text ? "changes" : "no changes", facts: { changed: text ? 1 : 0 } };
+}
+async function closeWorktree(id, opts) {
+    const where = copies.get(id);
+    if (!where)
+        return { content: `${id} is already gone.` };
+    await git(["worktree", "remove", "--force", where], opts);
+    try {
+        fs.rmSync(where, { recursive: true, force: true });
+    }
+    catch { /* removed above */ }
+    copies.delete(id);
+    return { content: `Removed ${id}.` };
+}
+/** Every copy this process made, removed; for the end of a session. */
+async function closeAllWorktrees(root) {
+    for (const id of [...copies.keys()])
+        await closeWorktree(id, { root });
+}

package/out/machine/folder/project.d.ts

@@ -0,0 +1,28 @@
+export interface ProjectFacts {
+    /** The repository root, or the folder itself outside a repository. Real path. */
+    root: string;
+    /** Where the person was standing, relative to `root`. Empty at the root. */
+    start: string;
+    /** Null outside a repository, or when HEAD is not on a branch. */
+    branch: string | null;
+    /** Folders the person named, real paths, never the root itself. */
+    added: string[];
+    home: string;
+    /** `owner/name` of the GitHub repository `origin` points at, or null. The
+     *  service needs it for pull requests, issues and CI (manual 5.18 to 5.21). */
+    repository?: string | null;
+}
+/** `owner/name` from a GitHub remote address, in any of its spellings. */
+export declare function githubRepository(remote: string | null): string | null;
+/** A folder the person named, or the reason it cannot be used. */
+export declare function checkFolder(raw: string): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    why: string;
+};
+/** The project for a job started in `startDir`, with any added folders. */
+export declare function resolveProject(startDir: string, added?: string[]): ProjectFacts;
+/** The facts as the service reads them, on the job and on the session line. */
+export declare function asWire(p: ProjectFacts, mode?: string): Record<string, unknown>;

package/out/machine/folder/project.js

@@ -0,0 +1,114 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.githubRepository = githubRepository;
+exports.checkFolder = checkFolder;
+exports.resolveProject = resolveProject;
+exports.asWire = asWire;
+/**
+ * Where a job works, as this machine sees it (manual 2.1 to 2.3).
+ *
+ * A local helper and nothing more: it observes the folder, the Git repository
+ * around it and the branch, because only this machine can. The service decides
+ * what those facts mean, stores them on the job and writes the line a person
+ * reads. Nothing here decides whether a path may be touched; the executor's
+ * check in `executor/paths.ts` does that immediately before each action.
+ */
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+/** `owner/name` from a GitHub remote address, in any of its spellings. */
+function githubRepository(remote) {
+    // `github.com`, or an SSH alias such as `github-work` set up for a second account.
+    const m = /(?:^|[@/])github[\w.-]*[:/]([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/.exec((remote ?? "").trim());
+    return m ? `${m[1]}/${m[2]}` : null;
+}
+/** A folder the person named, or the reason it cannot be used. */
+function checkFolder(raw) {
+    const expanded = raw.replace(/^~(?=$|[\\/])/, os.homedir());
+    const resolved = path.resolve(expanded);
+    if (!fs.existsSync(resolved))
+        return { ok: false, why: `There is no folder at ${resolved}.` };
+    if (!fs.statSync(resolved).isDirectory())
+        return { ok: false, why: `${resolved} is a file, not a folder.` };
+    return { ok: true, path: fs.realpathSync(resolved) };
+}
+/** Git's output, or null when git failed or this is not a repository. */
+function git(args, cwd) {
+    try {
+        // An argument list, never a shell string, so it behaves the same on Windows.
+        return (0, node_child_process_1.execFileSync)("git", args, {
+            cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/** The project for a job started in `startDir`, with any added folders. */
+function resolveProject(startDir, added = []) {
+    const start = fs.realpathSync(startDir);
+    // The way up to the repository root and the way back down, relative, rather
+    // than the root's absolute name. Git spells an absolute path its own way (on
+    // Windows, long names where the temp folder has short ones), and comparing two
+    // spellings of one folder reads as two folders.
+    const where = git(["rev-parse", "--show-cdup", "--show-prefix"], start);
+    const [up = "", down = ""] = where === null ? [] : where.split(/\r?\n/);
+    const root = where === null ? start : fs.realpathSync(path.resolve(start, up || "."));
+    const branch = where === null
+        ? null : (git(["symbolic-ref", "--short", "-q", "HEAD"], root) ?? "").trim() || null;
+    const extra = [...new Set(added.map((a) => fs.realpathSync(a)))].filter((a) => a !== root);
+    return {
+        root,
+        start: down.replace(/\/+$/, ""),
+        branch,
+        added: extra,
+        home: os.homedir(),
+        repository: where === null ? null : githubRepository(git(["remote", "get-url", "origin"], root)),
+    };
+}
+/** The facts as the service reads them, on the job and on the session line. */
+function asWire(p, mode) {
+    return {
+        project_root: p.root,
+        start_folder: p.start,
+        branch: p.branch,
+        added_folders: p.added,
+        home: p.home,
+        ...(p.repository ? { repository: p.repository } : {}),
+        ...(mode ? { permission_mode: mode } : {}),
+    };
+}

package/out/machine/runtime/home.d.ts

@@ -0,0 +1,2 @@
+export declare const HOME_DIR_NAME = ".comprism";
+export declare function homeDir(): string;

package/out/machine/runtime/home.js

@@ -0,0 +1,48 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOME_DIR_NAME = void 0;
+exports.homeDir = homeDir;
+/**
+ * The tool's own folder on this computer, where it keeps its settings, its
+ * copies of shipped files and its programs. One answer for every client that
+ * carries the machine services.
+ */
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+exports.HOME_DIR_NAME = ".comprism";
+function homeDir() {
+    return process.env.COMPRISM_HOME || path.join(os.homedir(), exports.HOME_DIR_NAME);
+}

package/out/machine/runtime/needs.d.ts

@@ -0,0 +1,30 @@
+export interface Requirement {
+    /** What it is for, said as the work it makes possible. */
+    purpose: string;
+    /** Any one of these being present is enough. */
+    anyOf: string[];
+    /** Work that cannot be done without it, for the message. */
+    without: string;
+    /** True when the tool cannot function at all without this. */
+    essential: boolean;
+}
+export declare const REQUIREMENTS: Requirement[];
+/** Is this program on the machine, by name, without running anything of theirs. */
+export declare function present(program: string): boolean;
+/**
+ * The one command that installs what is missing, for the machine it is on.
+ *
+ * Named per platform rather than guessed: telling somebody on Ubuntu to run a
+ * Homebrew command is worse than saying nothing, because they now have to work
+ * out that the instruction was wrong before they can work out what is right.
+ */
+export declare function howToInstall(missing: string[]): string;
+export interface Readiness {
+    ready: boolean;
+    /** One line per requirement, ready to print. */
+    lines: string[];
+    /** The command to run, empty when nothing is missing. */
+    fix: string;
+}
+/** What this machine can and cannot do, and how to close the gap. */
+export declare function check(): Readiness;

package/out/machine/runtime/needs.js

@@ -0,0 +1,89 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUIREMENTS = void 0;
+exports.present = present;
+exports.howToInstall = howToInstall;
+exports.check = check;
+/**
+ * What the machine services need on a computer before they can do their work:
+ * git for the git actions, a PDF reader for PDFs (service catalog, machine
+ * services). Kept with the engine, not with one client, because the terminal,
+ * VS Code and desktop all carry the same engine. Checked on the computer itself,
+ * and at install time, before anyone has signed in.
+ */
+const node_child_process_1 = require("node:child_process");
+const node_os_1 = __importDefault(require("node:os"));
+exports.REQUIREMENTS = [
+    {
+        purpose: 'working with a repository',
+        anyOf: ['git'],
+        without: 'reading, branching and committing a project',
+        essential: false,
+    },
+    {
+        purpose: 'reading a PDF you already have',
+        // Three ways to do the same job. The first keeps the layout, the second is
+        // close, the third is usually there on any machine with Python at all.
+        anyOf: ['pdftotext', 'mutool', 'python3'],
+        without: 'reading a specification or a contract that arrived as a PDF',
+        essential: false,
+    },
+];
+/** Is this program on the machine, by name, without running anything of theirs. */
+function present(program) {
+    try {
+        // Windows has no /usr/bin/env, so every program read as missing there.
+        if (node_os_1.default.platform() === 'win32')
+            (0, node_child_process_1.execFileSync)('where', [program], { stdio: 'ignore' });
+        else
+            (0, node_child_process_1.execFileSync)('/usr/bin/env', ['which', program], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The one command that installs what is missing, for the machine it is on.
+ *
+ * Named per platform rather than guessed: telling somebody on Ubuntu to run a
+ * Homebrew command is worse than saying nothing, because they now have to work
+ * out that the instruction was wrong before they can work out what is right.
+ */
+function howToInstall(missing) {
+    if (missing.length === 0)
+        return '';
+    const platform = node_os_1.default.platform();
+    const parts = missing.map((m) => (m === 'pdftotext' ? 'poppler' : m));
+    if (platform === 'darwin')
+        return `brew install ${parts.join(' ')}`;
+    if (platform === 'linux') {
+        const apt = missing.map((m) => (m === 'pdftotext' ? 'poppler-utils' : m));
+        return `sudo apt-get install -y ${apt.join(' ')}`;
+    }
+    if (platform === 'win32')
+        return `winget install ${parts.join(' ')}`;
+    return `install: ${parts.join(', ')}`;
+}
+/** What this machine can and cannot do, and how to close the gap. */
+function check() {
+    const lines = [];
+    const missing = [];
+    for (const req of exports.REQUIREMENTS) {
+        const found = req.anyOf.find(present);
+        if (found) {
+            lines.push(`  ready    ${req.purpose}`);
+        }
+        else {
+            // The FIRST of the alternatives is the one named, because a list of three
+            // equivalent programs is a decision nobody wants to make about a thing
+            // they did not know they needed.
+            missing.push(req.anyOf[0]);
+            lines.push(`  missing  ${req.purpose}, so ${req.without} will not work`);
+        }
+    }
+    return { ready: missing.length === 0, lines, fix: howToInstall(missing) };
+}

package/out/machine/runtime/self.d.ts

@@ -0,0 +1,23 @@
+/** True when running as the ready to run program rather than under Node. */
+export declare function isStandalone(): boolean;
+/** Where the install script keeps the program: `~/.comprism/bin`. */
+export declare function standaloneBinDir(): string;
+export type InstallMethod = "script" | "npm" | "python";
+/**
+ * Which of the three install options put this copy here.
+ *
+ * The program is only ever distributed two ways, so where it sits decides it:
+ * in `~/.comprism/bin` it came from the install script, anywhere else pip put
+ * it. Under Node it came from npm.
+ */
+export declare function installMethod(): InstallMethod;
+/** The command and arguments that start another copy of this tool. */
+export declare function selfLaunch(args: string[], nodeFlags?: string[]): [string, string[]];
+/**
+ * A file shipped beside the code, as a path on disk.
+ *
+ * Under npm it sits in the package. Inside the program it is carried as an
+ * asset and written once to `~/.comprism/assets`, because the programs it is
+ * handed to (Python, for the reader script) need a real file.
+ */
+export declare function shippedFile(name: string, packagePath: string): string;