@illuminis/comprism 0.1.0

package/out/commands/settings.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The folder a command should act on.
+ *
+ * The folder you are standing in, unless you named one. That is what every
+ * other tool in a terminal does, and a saved folder that silently overrode the
+ * current one would be a trap.
+ */
+export declare function currentWorkspace(): {
+    path: string;
+    source: 'saved' | 'cwd';
+};
+export declare function cmdProviders(): Promise<void>;
+/**
+ * Set the model you are compared against.
+ *
+ * This is NOT the model that runs your work: the product picks that, and the
+ * whole point is that it often picks a cheaper one. This is the model you WOULD
+ * have used, which is the only thing a saving can honestly be measured against.
+ */
+export declare function cmdModel(args: string[]): Promise<void>;
+export declare function cmdWorkspace(args: string[]): Promise<void>;

package/out/commands/settings.js

@@ -0,0 +1,244 @@
+"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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.currentWorkspace = currentWorkspace;
+exports.cmdProviders = cmdProviders;
+exports.cmdModel = cmdModel;
+exports.cmdWorkspace = cmdWorkspace;
+/**
+ * The three things a person sets once and then forgets: which model they are
+ * compared against, which vendors they can reach, and which folder they work in.
+ *
+ * ── What is stored here, and what is not ──────────────────────────────────
+ *
+ * A PREFERENCE lives on this machine: the model you would otherwise have used,
+ * and the folder you work in. Neither is a secret and neither is model logic;
+ * they are two facts about you, and a round trip to ask us for them would be
+ * slower and no safer.
+ *
+ * THE MODEL LIST does not live here. It comes from our server on every call,
+ * because the models and their prices are ours, and because a copy on a
+ * customer's laptop goes stale the day a vendor changes a price. A stale price
+ * silently corrupts every figure downstream of it, which is the exact failure
+ * this product exists to replace.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const prompt_1 = require("../lib/prompt");
+const gateway_1 = require("../lib/gateway");
+const config_1 = require("../lib/config");
+const ui = __importStar(require("../lib/ui"));
+const out = (s = '') => process.stdout.write(s + '\n');
+/** Where the chosen folder is remembered. Beside the rest of the settings. */
+function workspaceFile() {
+    return node_path_1.default.join((0, config_1.homeDir)(), 'workspace.json');
+}
+/**
+ * The folder a command should act on.
+ *
+ * The folder you are standing in, unless you named one. That is what every
+ * other tool in a terminal does, and a saved folder that silently overrode the
+ * current one would be a trap.
+ */
+function currentWorkspace() {
+    try {
+        const saved = JSON.parse(node_fs_1.default.readFileSync(workspaceFile(), 'utf8'));
+        if (saved.path && node_fs_1.default.existsSync(saved.path))
+            return { path: saved.path, source: 'saved' };
+    }
+    catch { /* nothing saved, which is the normal case */ }
+    return { path: process.cwd(), source: 'cwd' };
+}
+/**
+ * How a vendor writes its own name.
+ *
+ * The workspace returns a machine name and title-cases it, which turns `openai`
+ * into "Openai" and `xai` into "Xai". Neither company spells itself that way,
+ * and two screens in the same product showing the same vendors must spell them
+ * identically. Kept in step with the same list in `keys.ts`.
+ */
+const VENDOR_LABEL = {
+    anthropic: 'Anthropic', openai: 'OpenAI', google: 'Google', xai: 'xAI',
+};
+const vendorLabel = (key, fallback) => VENDOR_LABEL[key.toLowerCase()] || fallback;
+async function cmdProviders() {
+    out(ui.banner('AI providers'));
+    out();
+    const reply = await (0, gateway_1.ask)({ intent: 'catalog', prompt: '' });
+    // Four ways this can fail to be an answer, and none of them is "your account
+    // has no vendors". Saying otherwise sends somebody to add a key they already
+    // have, which is the fault reported on 17 September 2026.
+    if (!reply.ok || reply.served === false || reply.complete === false
+        || !reply.providers || reply.providers.length === 0) {
+        out(ui.fail('Your workspace could not tell us which vendors it can reach.'));
+        out(`      ${ui.c.dim(reply.message || reply.decision.rationale || 'no answer from the workspace')}`);
+        out(`      ${ui.c.dim('check the address with')} ${ui.c.bold('comprism status')}`);
+        out();
+        process.exitCode = 1;
+        return;
+    }
+    for (const p of reply.providers) {
+        const state = p.has_key ? ui.c.green('ready') : ui.c.amber('no key stored');
+        out(`  ${ui.c.bold(vendorLabel(p.provider, p.label))}  ${state}`);
+        for (const m of p.models) {
+            const mark = m.reachable ? ui.c.green(' ok ') : ui.c.dim(' -- ');
+            out(`   ${mark} ${m.label.padEnd(24)} ${ui.c.dim(m.tier)}`);
+        }
+        out();
+    }
+    const total = reply.providers.reduce((n, p) => n + p.models.length, 0);
+    out(ui.c.dim(`  ${total} models across ${reply.providers.length} vendors, every one priced from our own study.`));
+    out(ui.c.dim('  A vendor with no key stored can still be called by sending your key with the request.'));
+    out();
+}
+/**
+ * Set the model you are compared against.
+ *
+ * This is NOT the model that runs your work: the product picks that, and the
+ * whole point is that it often picks a cheaper one. This is the model you WOULD
+ * have used, which is the only thing a saving can honestly be measured against.
+ */
+async function cmdModel(args) {
+    const cfg = (0, config_1.loadConfig)();
+    const named = args.find((a) => !a.startsWith('--'));
+    out(ui.banner('Your comparison model'));
+    out();
+    out(ui.c.dim('  The model you would have used anyway. Savings are measured against it.'));
+    out(`  ${ui.c.dim('Now:')} ${ui.c.bold(cfg.defaultModel || 'not set')}`);
+    out();
+    const reply = await (0, gateway_1.ask)({ intent: 'catalog', prompt: '' });
+    const models = (reply.providers || []).flatMap((p) => p.models);
+    // Same rule as every other reader: an answer we did not get is not an answer
+    // of none.
+    if (!reply.ok || reply.served === false || reply.complete === false
+        || models.length === 0) {
+        out(ui.fail('Your workspace could not tell us which models it can reach.'));
+        out(`      ${ui.c.dim(reply.message || reply.decision.rationale || 'no answer from the workspace')}`);
+        out();
+        process.exitCode = 1;
+        return;
+    }
+    const match = (value) => models.find((m) => m.id === value || m.key === value
+        || m.label.toLowerCase() === value.toLowerCase());
+    let chosen = named ? match(named) : undefined;
+    if (named && !chosen) {
+        out(ui.fail(`No model called "${named}".`));
+        out(`      ${ui.c.dim('see the list with')} ${ui.c.bold('comprism providers')}`);
+        out();
+        process.exitCode = 1;
+        return;
+    }
+    if (!chosen) {
+        models.forEach((m, i) => {
+            const n = String(i + 1).padStart(2);
+            out(`  ${n}. ${m.label.padEnd(24)} ${ui.c.dim(`${m.provider}  ${m.tier}`)}`);
+        });
+        out();
+        const answer = await (0, prompt_1.ask)('  number, or a model name: ');
+        (0, prompt_1.closePrompt)();
+        if (!answer) {
+            out(ui.info('Left as it was.'));
+            out();
+            return;
+        }
+        const asNumber = Number(answer);
+        chosen = Number.isInteger(asNumber) && asNumber >= 1 && asNumber <= models.length
+            ? models[asNumber - 1]
+            : match(answer);
+        if (!chosen) {
+            out(ui.fail(`"${answer}" is not on the list.`));
+            out();
+            process.exitCode = 1;
+            return;
+        }
+    }
+    (0, config_1.saveConfig)({ ...cfg, defaultModel: chosen.id });
+    out();
+    out(ui.ok(`Comparing against ${ui.c.bold(chosen.label)}.`));
+    out(`      ${ui.c.dim('every receipt from now on prices your work against this model')}`);
+    out();
+}
+async function cmdWorkspace(args) {
+    const named = args.find((a) => !a.startsWith('--'));
+    const current = currentWorkspace();
+    out(ui.banner('Working folder'));
+    out();
+    out(`  ${ui.c.bold(current.path)}`);
+    out(`      ${ui.c.dim(current.source === 'cwd'
+        ? 'the folder you are standing in'
+        : 'saved, so it is used wherever you run the command from')}`);
+    out();
+    if (args.includes('--clear')) {
+        try {
+            node_fs_1.default.unlinkSync(workspaceFile());
+        }
+        catch { /* nothing was saved */ }
+        out(ui.ok('Cleared. The folder you are standing in is used again.'));
+        out();
+        return;
+    }
+    let target = named;
+    if (!target) {
+        const answer = await (0, prompt_1.ask)('  new folder, or enter to keep it: ');
+        (0, prompt_1.closePrompt)();
+        if (!answer) {
+            out(ui.info('Left as it was.'));
+            out();
+            return;
+        }
+        target = answer;
+    }
+    const resolved = node_path_1.default.resolve(target.replace(/^~/, process.env.HOME || '~'));
+    if (!node_fs_1.default.existsSync(resolved)) {
+        out(ui.fail(`There is no folder at ${resolved}.`));
+        out();
+        process.exitCode = 1;
+        return;
+    }
+    if (!node_fs_1.default.statSync(resolved).isDirectory()) {
+        out(ui.fail(`${resolved} is a file, not a folder.`));
+        out();
+        process.exitCode = 1;
+        return;
+    }
+    node_fs_1.default.mkdirSync((0, config_1.homeDir)(), { recursive: true });
+    node_fs_1.default.writeFileSync(workspaceFile(), JSON.stringify({ path: resolved }, null, 2), { mode: 0o600 });
+    out(ui.ok(`Working folder set to ${ui.c.bold(resolved)}.`));
+    out(`      ${ui.c.dim('clear it with')} ${ui.c.bold('comprism workspace --clear')}`);
+    out();
+}

package/out/commands/welcome.d.ts

@@ -0,0 +1 @@
+export declare function showWelcome(): Promise<void>;

package/out/commands/welcome.js

@@ -0,0 +1,196 @@
+"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.showWelcome = showWelcome;
+/**
+ * The first thing anybody sees.
+ *
+ * ── Why a banner is not decoration ────────────────────────────────────────
+ *
+ * Typing the bare command used to print a list of other commands. That tells a
+ * person what they COULD do and nothing about where they are. In a product
+ * whose whole claim is a number, four facts make the number mean anything: who
+ * you are signed in as, whose workspace you are in, which model your savings
+ * are measured against, and which folder you are working in.
+ *
+ * A person who does not know the comparison model cannot read a saving, and a
+ * person who has to run three commands to find it will not.
+ *
+ * The prism spectrum is the brand: white light in, a spectrum out. It is drawn
+ * from the same eight colors as every other illuminis screen, through the same
+ * helper, so a terminal and the portal read as one product.
+ *
+ * Everything here is either already on this machine or comes back in ONE call.
+ * A welcome screen costing three round trips is one people learn to skip.
+ */
+const connection_1 = require("../lib/connection");
+const gateway_1 = require("../lib/gateway");
+const config_1 = require("../lib/config");
+const settings_1 = require("./settings");
+const version_1 = require("../lib/version");
+const ui = __importStar(require("../lib/ui"));
+const out = (s = '') => process.stdout.write(s + '\n');
+/**
+ * Who this machine is signed in as, and everything else the header prints.
+ *
+ * ── One call, to the one service ──────────────────────────────────────────
+ *
+ * This used to call the platform's own `whoami` for the identity, and the
+ * header then had no way at all to say how many vendor keys the account held.
+ * Two questions, two addresses, and the header could show a person facts that
+ * disagreed with each other. On 17 September 2026 it did exactly that: "User
+ * unknown" beside a company name, and a session that then announced no provider
+ * key was stored while four were stored and active.
+ *
+ * Every line below now comes from one request to the single service, so the
+ * header either shows a consistent picture or says plainly that it could not
+ * reach the workspace. There is no third state in which half of it is true.
+ *
+ * Null rather than an error when it cannot be reached. A header is the wrong
+ * place to fail: somebody on a plane still gets the local facts, and the lines
+ * needing the server say so.
+ */
+async function session() {
+    const conn = (0, connection_1.readConnection)();
+    if (!conn?.url || !conn.workspaceKey)
+        return null;
+    const reply = await (0, gateway_1.ask)({ intent: 'session', prompt: '' });
+    // `ok` false means nobody answered. `served` false means the workspace is
+    // running a build without this question. Neither is an answer about the
+    // account, and neither may be drawn as one.
+    if (!reply.ok || reply.served === false || !reply.session)
+        return null;
+    return reply.session;
+}
+/**
+ * The mark: a prism splitting light.
+ *
+ * A four row pyramid, drawn only in the full block glyph. The first attempt
+ * used quarter blocks and came out looking like a rendering fault, because
+ * those glyphs sit differently in every terminal font and a mark cannot depend
+ * on a font. A full block renders identically everywhere, so the only thing
+ * carrying the design is the color, which is the point of a prism.
+ *
+ * Color is taken by COLUMN, not by row. The apex sits on the middle of the
+ * spectrum and each row down widens to one more color on either side, so the
+ * base carries all eight. That is a prism doing its job: one input at the top,
+ * the whole spectrum at the bottom. Banding it by row would have shown four of
+ * the eight and read as a striped triangle instead.
+ *
+ * The eight values come from the same helper as the rule beneath it, so the
+ * mark and the rule can never drift apart.
+ */
+const MARK_BASE = 8;
+function mark() {
+    const rows = [];
+    for (let r = 1; r <= 4; r++) {
+        const blocks = r * 2;
+        const left = (MARK_BASE - blocks) / 2;
+        let line = ' '.repeat(left);
+        for (let i = 0; i < blocks; i++)
+            line += ui.spectrumAt(left + i, '\u2588');
+        rows.push(line + ' '.repeat(left));
+    }
+    return rows;
+}
+/** A label and its value, aligned so the values form one column. */
+function row(label, value) {
+    return `  ${ui.c.dim(label.padEnd(11))}${value}`;
+}
+/** "base-tenant" is a machine name. A person reads "Base Tenant". */
+function readable(name) {
+    return name.replace(/[-_]/g, ' ').replace(/\b\w/g, (m) => m.toUpperCase());
+}
+async function showWelcome() {
+    const conn = (0, connection_1.readConnection)();
+    const cfg = (0, config_1.loadConfig)();
+    const folder = (0, settings_1.currentWorkspace)();
+    const me = await session();
+    const [m1, m2, m3, m4] = mark();
+    out();
+    out(`  ${m1}   ${ui.c.bold('CompletionPrism')} ${ui.c.dim(`v${version_1.COMPRISM_VERSION}`)}`);
+    out(`  ${m2}   ${ui.c.muted('Optimize AI completion economics by optimizing work.')}`);
+    out(`  ${m3}`);
+    out(`  ${m4}`);
+    out(ui.prismRule());
+    out();
+    if (!conn?.url) {
+        // Nothing else here is knowable yet, and the one useful thing to say is the
+        // single command that changes that.
+        out(row('Signed in', ui.c.amber('not yet')));
+        out(row('Comparing', cfg.defaultModel || 'not set'));
+        out(row('Workspace', `${folder.path}  ${ui.c.dim('(where you are)')}`));
+        out();
+        out(`  ${ui.c.dim('start with')}  ${ui.c.bold('comprism login')}`);
+        out();
+        return;
+    }
+    const company = me?.company || readable(conn.tenant || 'unknown');
+    const who = me?.user_email || ui.c.dim('unknown');
+    const plan = me?.plan || '';
+    const allowance = me?.requests_per_month || 0;
+    // The address the SERVER says it answers on, in preference to the one this
+    // machine happens to hold. A client that can only echo its own stored address
+    // can never tell a person that the address is the thing that is wrong, which
+    // is exactly what happened when a machine sat pointed at a dead laptop port.
+    const address = (me?.workspace_url || conn.url).replace(/^https?:\/\//, '');
+    out(row('User', who));
+    out(row('Company', company));
+    out(row('Server', ui.c.dim(address)));
+    out(row('Comparing', `${cfg.defaultModel || ui.c.amber('not set')}  ${ui.c.dim('change with `comprism model`')}`));
+    out(row('Workspace', `${folder.path}  ${ui.c.dim(folder.source === 'cwd' ? '(where you are)' : '(saved)')}`));
+    if (plan) {
+        out(row('Plan', allowance
+            ? `${plan}  ${ui.c.dim(`${allowance.toLocaleString()} requests a month`)}`
+            : plan));
+    }
+    if (!me) {
+        out();
+        out(`  ${ui.c.amber('your workspace could not be reached, so only local settings are shown')}`);
+        out(`  ${ui.c.dim('nothing here is known about your account, including your provider keys')}`);
+    }
+    else if (me.vendors_known === false) {
+        // It answered, but could not establish this one line. Said plainly, because
+        // an unchecked vendor list shown as a number is the fault this whole change
+        // exists to end.
+        out();
+        out(`  ${ui.c.amber('your vendor keys could not be checked, so that is unknown rather than none')}`);
+    }
+    out();
+    out(`  ${ui.c.dim('ask a question')}    ${ui.c.bold('comprism ask')}`);
+    out(`  ${ui.c.dim('have work done')}    ${ui.c.bold('comprism work')}`);
+    out(`  ${ui.c.dim('every command')}     ${ui.c.bold('comprism help')}`);
+    out();
+}

package/out/executor/documents.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Applying a patch, and reading a PDF.
+ *
+ * Specification: docs/modules/CODING_AGENT_BUILD_SPECIFICATION.md, register
+ * items D15 (apply a patch) and D3 (read a PDF).
+ *
+ * Both exist for the same reason: the thing the agent needs is already in a
+ * format somebody else chose. A patch arrives from a review or a bug report, and
+ * a specification arrives as a PDF because that is how standards bodies publish.
+ * Neither is worth re-typing into a form we prefer.
+ */
+import { RunResult, ShellOptions } from "./shell";
+/**
+ * Apply a unified diff.
+ *
+ * Through `git apply` rather than a parser of our own. Patch formats have
+ * decades of edge cases in them - renames, mode changes, binary hunks, fuzzy
+ * context - and a hand-rolled applier gets the common case right and the
+ * interesting ones wrong, silently, in somebody's repository.
+ *
+ * **Checked before it is applied.** `--check` runs the whole thing and changes
+ * nothing, so a patch that does not fit is refused whole rather than leaving
+ * half of itself behind. That is the same property `edit_file` has and for the
+ * same reason: a file left half changed is worse than one not changed, because
+ * the model believes the whole change landed.
+ */
+export declare function applyPatch(patch: string, opts: ShellOptions): Promise<RunResult>;
+/**
+ * Read a PDF as text.
+ *
+ * Through whichever extractor the machine has, in order of how good the output
+ * is: `pdftotext` keeps the layout, `mutool` is close, and Python's pypdf is
+ * usually present on a machine that has Python at all. If none of them is
+ * there, it says so and names one to install rather than returning nothing.
+ *
+ * A PDF full of scanned images produces no text, and that is reported as what it
+ * is. Silently returning an empty document would have the model conclude the
+ * specification is blank.
+ */
+export declare function readPdf(root: string, rel: string, pages: string | undefined, opts: ShellOptions): Promise<RunResult>;

package/out/executor/documents.js

@@ -0,0 +1,170 @@
+"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.applyPatch = applyPatch;
+exports.readPdf = readPdf;
+/**
+ * Applying a patch, and reading a PDF.
+ *
+ * Specification: docs/modules/CODING_AGENT_BUILD_SPECIFICATION.md, register
+ * items D15 (apply a patch) and D3 (read a PDF).
+ *
+ * Both exist for the same reason: the thing the agent needs is already in a
+ * format somebody else chose. A patch arrives from a review or a bug report, and
+ * a specification arrives as a PDF because that is how standards bodies publish.
+ * Neither is worth re-typing into a form we prefer.
+ */
+const shell_1 = require("./shell");
+const paths_1 = require("./paths");
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+/**
+ * Apply a unified diff.
+ *
+ * Through `git apply` rather than a parser of our own. Patch formats have
+ * decades of edge cases in them - renames, mode changes, binary hunks, fuzzy
+ * context - and a hand-rolled applier gets the common case right and the
+ * interesting ones wrong, silently, in somebody's repository.
+ *
+ * **Checked before it is applied.** `--check` runs the whole thing and changes
+ * nothing, so a patch that does not fit is refused whole rather than leaving
+ * half of itself behind. That is the same property `edit_file` has and for the
+ * same reason: a file left half changed is worse than one not changed, because
+ * the model believes the whole change landed.
+ */
+async function applyPatch(patch, opts) {
+    if (!String(patch || "").trim()) {
+        return { isError: true, content: "Refused: there is no patch here." };
+    }
+    // Written to a temporary file rather than piped, so the patch cannot be
+    // mangled by shell quoting. A diff is full of characters a shell cares about.
+    const file = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "patch-")), "change.patch");
+    fs.writeFileSync(file, patch.endsWith("\n") ? patch : `${patch}\n`, "utf8");
+    try {
+        const check = await (0, shell_1.runCommand)(`git apply --check --verbose ${file}`, opts);
+        if (!/^exit 0/.test(check.content)) {
+            return {
+                isError: true,
+                content: "Refused, and nothing was changed: this patch does not apply to the "
+                    + `project as it stands.\n\n${check.content}\n\n`
+                    + "Read the files it touches and make the change with edit_file "
+                    + "instead, or ask for a patch against the current state.",
+            };
+        }
+        const applied = await (0, shell_1.runCommand)(`git apply --stat --apply ${file}`, opts);
+        if (!/^exit 0/.test(applied.content)) {
+            return { ...applied, isError: true };
+        }
+        return { content: `Applied the patch.\n\n${applied.content}`, summary: "patch applied" };
+    }
+    finally {
+        try {
+            fs.rmSync(path.dirname(file), { recursive: true, force: true });
+        }
+        catch { /* nothing to do */ }
+    }
+}
+/**
+ * Read a PDF as text.
+ *
+ * Through whichever extractor the machine has, in order of how good the output
+ * is: `pdftotext` keeps the layout, `mutool` is close, and Python's pypdf is
+ * usually present on a machine that has Python at all. If none of them is
+ * there, it says so and names one to install rather than returning nothing.
+ *
+ * A PDF full of scanned images produces no text, and that is reported as what it
+ * is. Silently returning an empty document would have the model conclude the
+ * specification is blank.
+ */
+async function readPdf(root, rel, pages, opts) {
+    let file;
+    try {
+        file = (0, paths_1.resolveInside)(root, rel, true);
+    }
+    catch (err) {
+        return { isError: true, content: err.message };
+    }
+    const range = pages ? pageRange(pages) : null;
+    const attempts = [
+        `pdftotext -layout ${range ? `-f ${range.from} -l ${range.to} ` : ""}${quote(file)} -`,
+        `mutool draw -F txt ${quote(file)} ${range ? `${range.from}-${range.to}` : ""}`,
+        `python3 -c ${quote(pythonExtractor(file, range))}`,
+    ];
+    for (const command of attempts) {
+        const result = await (0, shell_1.runCommand)(command, { ...opts, timeoutMs: 120_000 });
+        if (!/^exit 0/.test(result.content))
+            continue;
+        const body = result.content.replace(/^exit 0\n\n?/, "").trim();
+        if (!body) {
+            return {
+                isError: true,
+                content: `${rel} produced no text. It is probably scanned images rather than `
+                    + "text, so there is nothing to read without character recognition.",
+            };
+        }
+        const cut = body.length > 60_000
+            ? `${body.slice(0, 60_000)}\n\n[... the rest was not read. Ask for a page range.]`
+            : body;
+        return { content: cut, summary: `read ${rel}` };
+    }
+    return {
+        isError: true,
+        content: `Nothing on this machine can read a PDF. Install one of them and try `
+            + "again: `brew install poppler` on a Mac, `apt install poppler-utils` on "
+            + "Linux, or `pip install pypdf`.",
+    };
+}
+function pageRange(pages) {
+    const match = /^(\d+)\s*(?:-\s*(\d+))?$/.exec(pages.trim());
+    if (!match)
+        return null;
+    const from = Number(match[1]);
+    return { from, to: match[2] ? Number(match[2]) : from };
+}
+function quote(value) {
+    return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+function pythonExtractor(file, range) {
+    const slice = range ? `[${range.from - 1}:${range.to}]` : "";
+    return ("import sys\n"
+        + "try:\n"
+        + "    from pypdf import PdfReader\n"
+        + "except ImportError:\n"
+        + "    sys.exit(1)\n"
+        + `r = PdfReader(${JSON.stringify(file)})\n`
+        + `for page in r.pages${slice}:\n`
+        + "    print(page.extract_text() or '')\n");
+}

package/out/executor/files.d.ts

@@ -0,0 +1,2 @@
+import { RunResult } from "./shell";
+export declare function performFileAction(root: string, name: string, a: Record<string, unknown>): RunResult;