promigence 0.1.0-beta.12

package/dist/bin.js

@@ -0,0 +1,332 @@
+#!/usr/bin/env node
+import { GLOBAL_FLAGS, LISTED_COMMANDS, REQUEST_TIMEOUT_DEFAULT, SCHEMA, VERSION, findCommand, nearestFlag, notReleasedEnvelope, notReleasedLines, renderCommandHelp, renderHelp, unknownFlags, } from "./surface.js";
+import { HANDLERS, client, serverLocation } from "./commands.js";
+import { maybeFarNotice } from "./timing.js";
+import { refineError } from "./errfix.js";
+import { EXTRA_HANDLERS } from "./handlers.js";
+import { BUNDLE_HANDLERS } from "./bundle.js";
+import { LIVE_HANDLERS } from "./live.js";
+import { SSH_HANDLERS } from "./ssh.js";
+import { LOGIN_HANDLERS } from "./login.js";
+import { ORG_HANDLERS } from "./orgs.js";
+import { TEMPLATES_HANDLERS } from "./templates.js";
+import { ACCOUNT_HANDLERS } from "./account.js";
+import { MCP_HANDLERS } from "./mcp.js";
+import { AGENT_HANDLERS } from "./agent.js";
+import { CREDITS_HANDLERS, canAsk, claimOnRefusal } from "./credits.js";
+import { RUNNERS_HANDLERS } from "./runners.js";
+import { PRICING_HANDLERS } from "./pricing.js";
+import { GITHUB_HANDLERS } from "./github.js";
+import { GITLAB_HANDLERS } from "./gitlab.js";
+import { emit, errorEnvelope, errorTextLines, parseDuration, setBeforeExit, toPromigenceError, usageError as usageFailure, USAGE_DOCS, write, } from "./io.js";
+import { setCaller } from "./sdk/caller.js";
+import { sh } from "./term.js";
+import { parse, positionalsBeforeTail, takesTail } from "./argv.js";
+setCaller("cli", VERSION, { default: true });
+const flagValue = (p, name) => {
+    const v = p.flags.get(name);
+    const last = v?.[v.length - 1];
+    return typeof last === "string" ? last : undefined;
+};
+function editDistance(a, b) {
+    const d = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let prev = d[0];
+        d[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cur = d[j];
+            d[j] = Math.min(d[j] + 1, d[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+            prev = cur;
+        }
+    }
+    return d[b.length];
+}
+function outputMode(p) {
+    if (p.modeFlag)
+        return p.modeFlag;
+    const env = process.env["PROMIGENCE_OUTPUT"];
+    if (env === "json" || env === "text")
+        return env;
+    return process.stdout.isTTY ? "text" : "json";
+}
+function envProblem() {
+    const out = process.env["PROMIGENCE_OUTPUT"];
+    if (out !== undefined && out !== "" && out !== "json" && out !== "text") {
+        return { message: `PROMIGENCE_OUTPUT='${out}' is not an output mode`, fix: "Set PROMIGENCE_OUTPUT=json or text, or unset it." };
+    }
+    const url = process.env["PROMIGENCE_API_URL"];
+    if (url !== undefined && url !== "") {
+        let ok = false;
+        try {
+            ok = /^https?:$/.test(new URL(url).protocol);
+        }
+        catch {
+            ok = false;
+        }
+        if (!ok)
+            return { message: `PROMIGENCE_API_URL='${url}' is not an http(s) URL`, fix: "Set it to the API's URL, e.g. https://api.promigence.ai/v1, or unset it." };
+    }
+    return undefined;
+}
+function commandMode(cmd, p, inferred) {
+    if (cmd.name === "sandbox ssh" && p.flags.has("--proxy"))
+        return "text";
+    const env = process.env["PROMIGENCE_OUTPUT"];
+    if (p.modeFlag || env === "json" || env === "text")
+        return inferred;
+    if (cmd.name === "exec" && p.flags.has("--sandbox") && !p.flags.has("--background"))
+        return "text";
+    return inferred;
+}
+function useColor(mode) {
+    return mode === "text" && !!process.stdout.isTTY && !("NO_COLOR" in process.env) && process.env["TERM"] !== "dumb";
+}
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+function notReleased(mode, c) {
+    const env = notReleasedEnvelope(c);
+    return emit(mode, env, notReleasedLines(c, env), 1, !c.noGuidePointer);
+}
+function usageError(mode, raw, message) {
+    const env = {
+        schema: SCHEMA,
+        command: raw,
+        ok: false,
+        error: {
+            code: "usage",
+            message,
+            fix: "Run 'promigence --help' for the command list or 'promigence <command> --help' for one command.",
+            docs: USAGE_DOCS,
+            guide: "promigence agent-guide --section errors --code usage",
+        },
+        next: [{ cmd: "promigence --help", why: "command list" }],
+    };
+    return emit(mode, env, [`promigence: ${message} (exit 2)`, `  fix: ${env.error.fix}`], 2, true);
+}
+function checkFlags(cmd, p, argv = []) {
+    const unknown = unknownFlags(cmd, p.flags.keys());
+    if (unknown.length === 0) {
+        checkValueCounts(cmd, p);
+        return checkStrayWords(cmd, p, argv);
+    }
+    const first = unknown[0];
+    if (first === "--fresh") {
+        throw usageFailure(`--fresh does nothing for 'promigence ${cmd.name}': it sends no automatic idempotency key to skip`, `Drop --fresh: every \`promigence ${cmd.name}\` starts a new ${cmd.name === "run" ? "run" : "request"}. It is for the auto-keyed commands (${LISTED_COMMANDS.filter((c) => c.autoIdempotencyKey).map((c) => c.name).join(", ")}).`);
+    }
+    const near = nearestFlag(first, cmd);
+    const also = unknown.length > 1 ? ` (also ${unknown.slice(1).join(" ")})` : "";
+    throw usageFailure(`unknown flag ${first} for 'promigence ${cmd.name}'${also}`, `${near ? `Did you mean ${near}? ` : ""}Run 'promigence ${cmd.name} --help' for the flags this command takes.`);
+}
+function checkValueCounts(cmd, p) {
+    const spec = new Map([...GLOBAL_FLAGS, ...cmd.flags].map((f) => [f.name, f]));
+    for (const [name, values] of p.flags) {
+        const f = spec.get(name);
+        if (!f?.arg)
+            continue;
+        if (values.length > 1 && values.some((v) => v === true)) {
+            throw usageFailure(`${name} needs a value each time it is given`, `Pass ${name} <value> — or ${name}=<value> if the value starts with '-'.`);
+        }
+        if (values.length === 1 && values[0] === true && name !== "--devcontainer") {
+            throw usageFailure(`${name} needs a value`, `Pass ${name} ${f.arg} — or ${name}=<value> if the value starts with '-'.`);
+        }
+        const distinct = new Set(values.filter((v) => typeof v === "string"));
+        if (!f.repeatable && distinct.size > 1) {
+            throw usageFailure(`${name} was given ${values.length} times with different values; it takes one`, `Keep one ${name}. Run 'promigence ${cmd.name} --help' for what it takes.`);
+        }
+    }
+}
+function checkStrayWords(cmd, p, argv) {
+    if (cmd.ownExtraWords)
+        return;
+    const room = cmd.name.split(" ").length + positionalsBeforeTail(cmd);
+    const extra = p.words.slice(room);
+    if (extra.length === 0)
+        return;
+    const at = argv.indexOf(extra[0]);
+    const flag = at >= 2 && argv[at - 2].startsWith("--") && !argv[at - 2].includes("=") ? argv[at - 2] : undefined;
+    const fixes = [
+        ...(flag ? [`${flag} takes one value: to pass several, repeat it (${flag} A ${flag} B).`] : []),
+        ...(takesTail(cmd) ? ["The command to run goes after `--`."] : []),
+        `Run 'promigence ${cmd.name} --help' for what it takes.`,
+    ];
+    const near = !flag && at === cmd.name.split(" ").length ? nearestCommand([...cmd.name.split(" "), extra[0]]) : undefined;
+    throw usageFailure(`'promigence ${cmd.name}' has no place for ${extra.length === 1 ? "an argument" : `${extra.length} arguments`} here${flag ? ` (after ${flag} and its value)` : ""}; nothing was run`, [...(near && near !== cmd.name ? [`Did you mean 'promigence ${near}'?`] : []), ...fixes].join(" "));
+}
+function nearestCommand(words) {
+    const typed = words.join(" ");
+    let best;
+    let bestD = Number.POSITIVE_INFINITY;
+    for (const c of LISTED_COMMANDS) {
+        const d = editDistance(typed, c.name);
+        if (d < bestD) {
+            bestD = d;
+            best = c.name;
+        }
+    }
+    return best !== undefined && bestD > 0 && bestD <= Math.max(2, Math.floor(typed.length / 5)) ? best : undefined;
+}
+function requestTimeoutMs(p) {
+    if (p.flags.has("--request-timeout")) {
+        const flag = flagValue(p, "--request-timeout");
+        if (flag === undefined) {
+            throw usageFailure("--request-timeout needs a value", `Pass --request-timeout ${REQUEST_TIMEOUT_DEFAULT} (also ms, s, m, h; a bare number is seconds).`);
+        }
+        const ms = parseDuration(flag, "--request-timeout");
+        if (ms <= 0)
+            throw usageFailure("--request-timeout must be more than 0", `Pass --request-timeout ${REQUEST_TIMEOUT_DEFAULT}.`);
+        return ms;
+    }
+    const env = process.env["PROMIGENCE_REQUEST_TIMEOUT"];
+    if (env !== undefined && env !== "")
+        return parseDuration(env, "PROMIGENCE_REQUEST_TIMEOUT");
+    return undefined;
+}
+function errorNext(cmd, code, p) {
+    switch (code) {
+        case "auth":
+            return [
+                { cmd: "promigence auth login --from-env PROMIGENCE_API_KEY", why: "store a key (the OS keychain, else ~/.config/promigence/credentials, 0600)" },
+                { cmd: "promigence me", why: "confirm the key once you have one" },
+                { cmd: "promigence login", why: "sign up or sign in; it mints a key and stores it" },
+            ];
+        case "usage":
+        case "invalid_argument":
+            return [{ cmd: `promigence ${cmd.name} --help`, why: "flags, arguments and exit codes for this command" }];
+        case "not_found":
+            return [{ cmd: "promigence examples", why: "what you can fork with no build (the built-in base)" }];
+        case "rate_limited":
+            return [{ cmd: "promigence me", why: "your concurrency and rate limits" }];
+        case "cap_exceeded": {
+            const count = p ? flagValue(p, "--count") : undefined;
+            if (count === undefined)
+                return [{ cmd: "promigence agent-guide --section cost", why: "what a run costs, and how --cap bounds it" }];
+            const snap = (p ? flagValue(p, "--snapshot") : undefined) ?? "promigence/base";
+            const timeout = p ? flagValue(p, "--timeout") : undefined;
+            return [{
+                    cmd: `${sh `promigence run quote --snapshot ${snap} --count ${count}`}${timeout ? sh ` --timeout ${timeout}` : ""}`,
+                    why: "price the run before launching it",
+                }];
+        }
+        case "unreachable":
+            return [{ cmd: "promigence doctor", why: "check client, auth and API reachability" }];
+        default:
+            return [{ cmd: sh `promigence agent-guide --section errors --code ${code}`, why: "what this error means and how to fix it" }];
+    }
+}
+async function main(argv) {
+    const p = parse(argv);
+    let mode = outputMode(p);
+    if (p.version) {
+        if (p.modeFlag === "json")
+            await write(process.stdout, JSON.stringify({ schema: SCHEMA, command: "version", ok: true, version: VERSION, next: [] }) + "\n");
+        else
+            await write(process.stdout, `${VERSION}\n`);
+        return;
+    }
+    if (p.words[0] === "help" && !findCommand(p.words)) {
+        const target = p.words.length > 1 ? findCommand(p.words.slice(1)) : undefined;
+        if (p.words.length > 1 && !target)
+            return void (await usageError(mode, p.words.slice(1).join(" "), `unknown command '${p.words.slice(1).join(" ")}'`));
+        await write(process.stdout, target ? renderCommandHelp(target) : renderHelp());
+        return;
+    }
+    const cmd = findCommand(p.words);
+    if (p.words.length === 0) {
+        const stray = [...p.flags.keys()].filter((f) => !GLOBAL_FLAGS.some((g) => g.name === f));
+        if (stray.length) {
+            const known = ["--version", "--help", "--json", "--text", ...GLOBAL_FLAGS.map((g) => g.name)];
+            const short = { "-v": "--version", "-V": "--version", "-h": "--help" };
+            const near = short[stray[0]] ?? known.find((k) => editDistance(k, stray[0]) <= 2);
+            return void (await usageError(mode, stray[0], `unknown flag ${stray[0]}${near ? `; did you mean ${near}?` : ""}`));
+        }
+        if (p.modeFlag === "json") {
+            await write(process.stdout, JSON.stringify({ schema: SCHEMA, command: "help", ok: true, version: VERSION, commands: LISTED_COMMANDS.map((c) => c.name), next: [{ cmd: "promigence agent-guide", why: "the guide for agents" }] }) + "\n");
+            return;
+        }
+        const text = renderHelp();
+        await write(process.stdout, useColor(mode) ? text.replace(/^(Setup|Snapshots|Runs|Sandboxes|Ops)$/gm, bold) : text);
+        return;
+    }
+    if (!cmd) {
+        const prefix = p.words.join(" ") + " ";
+        const group = LISTED_COMMANDS.filter((c) => c.name.startsWith(prefix));
+        if (group.length) {
+            if (mode === "json") {
+                await write(process.stdout, JSON.stringify({ schema: SCHEMA, command: p.words.join(" "), ok: true, commands: group.map((c) => c.name), next: group.slice(0, 3).map((c) => ({ cmd: `promigence ${c.name} --help`, why: c.summary })) }) + "\n");
+            }
+            else {
+                await write(process.stdout, [`promigence ${p.words.join(" ")} — one of:`, ...group.map((c) => `  ${c.name.padEnd(22)} ${c.summary}`), `Run 'promigence ${group[0].name} --help' for one of them.`, ""].join("\n"));
+            }
+            return;
+        }
+        const SHORT = { "version": "--version", "-v": "--version", "-V": "--version", "-h": "--help" };
+        const near = (p.words.length === 1 ? SHORT[p.words[0]] : undefined) ?? nearestCommand(p.words);
+        return void (await usageError(mode, p.words.join(" "), `unknown command '${p.words.join(" ")}'${near ? `; did you mean '${near}'?` : ""}`));
+    }
+    mode = commandMode(cmd, p, mode);
+    const badEnv = envProblem();
+    if (badEnv)
+        return void (await usageError(mode, cmd.name, badEnv.message));
+    if (p.help) {
+        await write(process.stdout, renderCommandHelp(cmd));
+        return;
+    }
+    const handler = HANDLERS[cmd.name] ?? EXTRA_HANDLERS[cmd.name] ?? BUNDLE_HANDLERS[cmd.name] ?? LOGIN_HANDLERS[cmd.name] ?? ORG_HANDLERS[cmd.name] ?? LIVE_HANDLERS[cmd.name] ?? SSH_HANDLERS[cmd.name] ?? ACCOUNT_HANDLERS[cmd.name] ?? MCP_HANDLERS[cmd.name] ?? AGENT_HANDLERS[cmd.name] ?? CREDITS_HANDLERS[cmd.name] ?? RUNNERS_HANDLERS[cmd.name] ?? PRICING_HANDLERS[cmd.name] ?? GITHUB_HANDLERS[cmd.name] ?? GITLAB_HANDLERS[cmd.name] ?? TEMPLATES_HANDLERS[cmd.name];
+    if (!handler)
+        return void (await notReleased(mode, cmd));
+    const ctx = {
+        cmd,
+        args: p.words.slice(cmd.name.split(" ").length),
+        flags: p.flags,
+        cmdTail: p.cmdTail,
+        mode,
+        requestTimeoutMs: undefined,
+        explicitMode: p.modeFlag,
+        pointer: !cmd.noGuidePointer,
+        apiKey: flagValue(p, "--api-key"),
+    };
+    if (ctx.apiKey !== undefined && cmd.name !== "auth login" && cmd.name !== "doctor") {
+        process.stderr.write("promigence: warning: --api-key puts the key on the command line, where `ps` and shell history can read it; prefer PROMIGENCE_API_KEY or `promigence auth login --from-env VAR`.\n");
+    }
+    setBeforeExit(() => maybeFarNotice({ json: ctx.mode === "json", location: () => serverLocation(ctx) }));
+    try {
+        checkFlags(cmd, p, argv);
+        ctx.requestTimeoutMs = requestTimeoutMs(p);
+        await handler(ctx);
+    }
+    catch (err) {
+        let billingOff;
+        const refined = await refineError(toPromigenceError(err), {
+            command: cmd.name,
+            args: ctx.args,
+            ...(flagValue(p, "--sandbox") === undefined ? {} : { sandbox: flagValue(p, "--sandbox") }),
+            billingOff: () => (billingOff ??= client(ctx).billing.usage()
+                .then((b) => b.billing_enabled === false)
+                .catch(() => false)),
+        }).catch(() => ({ err: toPromigenceError(err), next: undefined }));
+        const e = refined.err;
+        let next = refined.next ?? errorNext(cmd, e.code, p);
+        const runId = ctx.startedRunId;
+        if (runId !== undefined && !next.some((n) => n.cmd.includes(runId))) {
+            next = [
+                { cmd: sh `promigence run report ${runId}`, why: "the run started and goes on: what it did" },
+                { cmd: sh `promigence run kill ${runId}`, why: "end it, if you no longer want it" },
+                ...next,
+            ];
+        }
+        const env = errorEnvelope(cmd.name, e, next);
+        if (runId !== undefined)
+            env["run_id"] = runId;
+        let exit = e.cliExit;
+        if (cmd.passthroughExit && !p.flags.has("--no-passthrough")) {
+            env.promigence_exit = exit;
+            exit = e.code === "enoent" ? 127 : cmd.passthroughExit;
+        }
+        if (e.code === "credit_unclaimed" && mode === "text" && canAsk()) {
+            const lines = await claimOnRefusal(ctx).catch(() => undefined);
+            if (lines)
+                return void (await emit(mode, env, lines, exit, false));
+        }
+        await emit(mode, env, errorTextLines(cmd.name, e, exit, next), exit, !cmd.noGuidePointer);
+    }
+}
+await main(process.argv.slice(2));

package/dist/bundle.js

@@ -0,0 +1,133 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { BUNDLE_EXT, BundleVerifyError, NotFoundError, NotVerifiedError, parseBundle, platformOf, renderBundle, verifyBundle, } from "./sdk/index.js";
+import { bool, client, nexts, positional, snapshotSource, str, } from "./commands.js";
+import { emit, okEnvelope, usageError, write } from "./io.js";
+import { sh } from "./term.js";
+function asPromigenceError(e, path) {
+    if (!(e instanceof BundleVerifyError))
+        return e;
+    if (e.kind === "canonical" || e.kind === "schema") {
+        return usageError(`${path}: ${e.message}`, `A bundle is written by 'promigence snapshot export'. Check you passed the right file.`);
+    }
+    return new NotVerifiedError(`${path}: ${e.message}`, "This file is not the environment it names. Ask whoever sent it for a fresh " +
+        "'promigence snapshot export', or export it yourself from the snapshot id it claims.");
+}
+export function loadBundle(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        throw new NotFoundError(`no such bundle: ${path}`, `Pass the path to a .promigence file, or export one with \`${sh `promigence snapshot export <hash> --out ${basename(path)}`}\`.`);
+    }
+    try {
+        const bundle = parseBundle(text);
+        const form = verifyBundle(bundle);
+        return { bundle, path, text, form };
+    }
+    catch (e) {
+        throw asPromigenceError(e, path);
+    }
+}
+export const looksLikeBundle = (v) => v.endsWith(BUNDLE_EXT) || ((v.startsWith("./") || v.startsWith("../") || v.startsWith("/")) && fileExists(v));
+function fileExists(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export async function snapshotArg(ctx, c) {
+    const v = str(ctx, "--snapshot");
+    if (v === undefined) {
+        throw usageError("--snapshot is required", "Pass --snapshot snap_<id> | <alias> | <alias>@<commit7> | ./env.promigence, or promigence/base (the built-in base).");
+    }
+    if (!looksLikeBundle(v))
+        return v;
+    const loaded = loadBundle(v);
+    await write(process.stderr, `${v}: ${loaded.form} bundle, verified — ${loaded.bundle.snap_id} (${loaded.bundle.manifest_hash})\n`);
+    await registerBundle(c, loaded);
+    return loaded.bundle.snap_id;
+}
+export async function registerBundle(c, loaded) {
+    const id = loaded.bundle.snap_id;
+    const known = await c.snapshots.get(id).then(() => true).catch(() => false);
+    if (known)
+        return { known: true, registered: true, how: "already in your org" };
+    const origin = bundleOrigin(loaded.bundle);
+    throw new NotFoundError(`${id} is not in your org, and a bundle from another account cannot be brought in yet`, `The bundle verified: it names ${id}${origin.length ? ` (${origin.join(" · ")})` : ""}. To run it here, build ` +
+        "the same snapshot in your org ('promigence snapshot create' with the same inputs), or run it with the " +
+        "account that holds it.");
+}
+export function bundleOrigin(b, liveOf) {
+    const verification = { ...(b.verification ?? {}) };
+    if (liveOf)
+        verification["from_live_sandbox"] = liveOf;
+    const text = (v) => (typeof v === "string" ? v : "");
+    const source = snapshotSource({ repo: text(b.provenance["repo"]), commit: text(b.provenance["commit"]), verification });
+    const verify = text(b.provenance["verify"]?.cmd);
+    return [...(source === "-" ? [] : [source]), ...(verify ? [`verify ${JSON.stringify(verify)}`] : [])];
+}
+function outPath(ctx, b) {
+    const out = str(ctx, "--out");
+    if (out === "-")
+        return undefined;
+    if (out !== undefined)
+        return out;
+    if (!process.stdout.isTTY && ctx.explicitMode !== "json")
+        return undefined;
+    return `${b.alias ?? b.snap_id}${BUNDLE_EXT}`;
+}
+const snapshotExport = async (ctx) => {
+    const id = positional(ctx, "a snapshot id or alias", "promigence snapshot export snap_01");
+    const full = bool(ctx, "--full") || bool(ctx, "--layers");
+    const citation = bool(ctx, "--citation") || bool(ctx, "--no-layers");
+    if (full && citation) {
+        throw usageError("--full and --citation contradict each other", "Pass one: --full writes the full form however large, --citation writes identity, provenance and verification only.");
+    }
+    const c = client(ctx);
+    const { bundle, served_by } = await c.snapshots.bundle(id);
+    const form = verifyBundle(bundle);
+    const text = renderBundle(bundle);
+    const file = outPath(ctx, bundle);
+    if (file === undefined) {
+        await write(process.stdout, text);
+        return ctxExit(0);
+    }
+    const path = resolve(file);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text);
+    const next = nexts([sh `promigence run --snapshot ${file} --count 2 --cap 1 -- CMD`, "run it from the file, here or anywhere"], [sh `promigence snapshot inspect ${bundle.snap_id}`, "the manifest behind it"]);
+    let origin = bundleOrigin(bundle);
+    if (origin.length === 0) {
+        const rec = await c.snapshots.get(bundle.snap_id).catch(() => undefined);
+        const live = rec?.verification?.["from_live_sandbox"];
+        if (typeof live === "string" && live !== "")
+            origin = bundleOrigin(bundle, live);
+    }
+    const platform = platformOf(bundle);
+    const lines = [
+        `wrote ${file} — ${text.length.toLocaleString("en-US")} B, ${form} form (${served_by}-composed)`,
+        `  ${bundle.snap_id}${bundle.alias ? ` (alias ${bundle.alias})` : ""} · ${bundle.manifest_hash}`,
+        ...(origin.length ? [`  ${origin.join(" · ")}`] : []),
+        ...(platform ? [`  platform ${platform.slice(0, 19)}…`] : []),
+        "  it runs where its snapshot already is",
+    ];
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, {
+        path, bytes: text.length, form, served_by,
+        snapshot_id: bundle.snap_id, manifest_hash: bundle.manifest_hash,
+        platform: platform ?? null,
+        bundle,
+    }, next), lines, 0, ctx.pointer);
+};
+async function ctxExit(code) {
+    await write(process.stdout, "");
+    process.exit(code);
+    throw new Error("unreachable");
+}
+export const BUNDLE_HANDLERS = {
+    "snapshot export": snapshotExport,
+};
+export { existsSync };

package/dist/capacity.js

@@ -0,0 +1,69 @@
+const CR = "\r";
+const CLEAR_LINE = "\u001b[2K";
+export function statusLine(stream = process.stderr) {
+    const tty = stream.isTTY === true;
+    let shown = false;
+    let last = "";
+    return {
+        set(text) {
+            if (!tty || !text || text === last)
+                return;
+            stream.write(CR + CLEAR_LINE + fitLine(text, stream.columns));
+            shown = true;
+            last = text;
+        },
+        clear() {
+            if (!tty || !shown)
+                return;
+            stream.write(CR + CLEAR_LINE);
+            shown = false;
+            last = "";
+        },
+    };
+}
+export function fitLine(text, columns) {
+    if (!columns || columns < 2 || text.length < columns)
+        return text;
+    return `${text.slice(0, columns - 2)}…`;
+}
+export function queuedLines(rows, indent = "  ") {
+    const by = new Map();
+    for (const r of rows) {
+        const m = r.queued_message;
+        if (typeof m === "string" && m !== "")
+            by.set(m, (by.get(m) ?? 0) + 1);
+    }
+    return [...by].map(([m, n]) => `${indent}${rows.length === 1 ? "" : `${n} `}queued: ${m}`);
+}
+export function queuedClause(rows) {
+    let best;
+    const by = new Map();
+    for (const r of rows) {
+        const m = r.queued_message;
+        if (typeof m !== "string" || m === "")
+            continue;
+        const n = (by.get(m) ?? 0) + 1;
+        by.set(m, n);
+        if (!best || n > best[1])
+            best = [m, n];
+    }
+    return best ? `${best[1]} still queued: ${best[0]}` : undefined;
+}
+export function capacityLine(c, ready, total) {
+    if (!c)
+        return undefined;
+    if (total > 0 && ready >= total)
+        return undefined;
+    const of = `${ready} of ${total} sandbox${total === 1 ? "" : "es"} ready`;
+    if (c.queued_message)
+        return `queued: ${c.queued_message} — ${of}`;
+    if (c.state === "blocked" && c.blocked)
+        return `capacity: cannot grow — ${c.blocked.reason}`;
+    if (c.state === "arriving") {
+        const when = c.eta_s === null || c.eta_s === undefined ? "" : `, ~${c.eta_s}s`;
+        return `capacity arriving: more capacity is being added${when} — ${of}`;
+    }
+    if (c.awaiting_capacity > 0)
+        return `waiting for capacity: ${c.awaiting_capacity} queued`;
+    return ready < total ? of : undefined;
+}

package/dist/commands.d.ts

@@ -0,0 +1,110 @@
+import { PromigenceClient, type ExecResponse, type OptimizeFor, type RunReport, type SandboxRef, type ScoreMode, type SecretRecord, type SnapshotBuild } from "./sdk/index.js";
+import { type Mode } from "./io.js";
+import { type BuildPrice } from "./pricing.js";
+import { type Command, type NextHint } from "./surface.js";
+export interface Ctx {
+    cmd: Command;
+    args: string[];
+    flags: Map<string, Array<string | true>>;
+    cmdTail: string[];
+    mode: Mode;
+    explicitMode?: Mode | undefined;
+    pointer: boolean;
+    apiKey: string | undefined;
+    requestTimeoutMs?: number | undefined;
+    startedRunId?: string | undefined;
+}
+export type Handler = (ctx: Ctx) => Promise<never>;
+export declare function str(ctx: Ctx, name: string): string | undefined;
+export declare function list(ctx: Ctx, name: string): string[];
+export declare function bool(ctx: Ctx, name: string): boolean;
+export declare function required(ctx: Ctx, name: string, hint: string): string;
+export declare function clientOpts(ctx: Ctx): {
+    apiKey?: string;
+    requestTimeoutMs?: number;
+    cliErrors: true;
+};
+export declare function client(ctx: Ctx): PromigenceClient;
+export declare function serverLocation(ctx: Ctx): Promise<string | undefined>;
+export declare const nexts: (...items: Array<[string, string]>) => NextHint[];
+export declare const KEPT_BY_HOLDERS = "sandboxes that were already given its value keep it until they end; it stays masked in their output";
+export declare function waitBound(ctx: Ctx): number;
+export declare function spendCap(ctx: Ctx, c: PromigenceClient): Promise<number>;
+export declare function replayNote(started: {
+    idempotent_replay?: boolean;
+    idempotent_replay_age_s?: number;
+}, explicitKey: boolean): string | undefined;
+export declare function buildReplayNote(started: {
+    build_id?: string;
+    idempotent_replay?: boolean;
+    idempotent_replay_age_s?: number;
+}, explicitKey: boolean): string | undefined;
+export declare function optimizeForFlag(ctx: Ctx): OptimizeFor | undefined;
+export declare function gradeOpts(ctx: Ctx): {
+    cmd: string;
+    holdoutCmd?: string;
+    timeoutMs?: number;
+    score?: ScoreMode;
+} | undefined;
+export declare function secretListLines(s: SecretRecord): string[];
+export declare function buildPriceOf(b: SnapshotBuild): BuildPrice | undefined;
+export declare function verifyTiming(v: Record<string, unknown> | undefined): string | undefined;
+export declare function buildLogLines(log: string[] | undefined, state: string): string[];
+export declare function snapshotSource(s: {
+    repo?: string;
+    commit?: string;
+    verification?: Record<string, unknown>;
+}): string;
+export declare function readyLine(ourMs: number | undefined, totalMs: number): string;
+export declare function sandboxIdLines(sandboxes: ReadonlyArray<Pick<SandboxRef, "sandbox_id" | "state">>, cap?: number): string[];
+type EnvError = {
+    code: string;
+    message: string;
+    fix: string;
+    docs: string;
+    guide: string;
+};
+export declare function envError(code: string, message: string, fix: string): EnvError;
+export interface ExecOutcome {
+    exitCode: number | null;
+    fields: Record<string, unknown>;
+    error?: EnvError;
+}
+export declare function execOutcome(res: ExecResponse, sandboxId: string, timeoutMs?: number, words?: "cli" | "mcp"): ExecOutcome;
+export declare function execTimingLine(exitCode: number | null | undefined, wallMs: unknown, totalMs: number, isTTY?: boolean, env?: NodeJS.ProcessEnv): string;
+export declare function endNotice(res: ExecResponse, timeoutMs?: number): string;
+export declare const MAX_OUTPUT_BYTES_PIPED: number;
+export declare function truncationNotice(kept: "first" | "last", maxOutputBytes: number | undefined): string;
+export declare function tagLines(sandboxId: string, text: string, escape?: boolean): string[];
+export declare const GRADES_SHOWN = 10;
+export declare function gradeRowLines(report: RunReport): string[];
+export declare function commandOutputLines(report: RunReport, outputs: ReadonlyMap<string, OutputTail>): string[];
+export declare const SETTLE_WAIT_MS = 15000;
+type ReportRow = NonNullable<RunReport["sandboxes"]>[number];
+export declare const limitPauseOf: (s: ReportRow) => "spend_cap" | "credits_exhausted" | undefined;
+export declare function runError(report: RunReport, exit: number): EnvError | undefined;
+export declare function runHeadline(report: RunReport, count: number): string;
+export declare const FAILURES_SHOWN = 5;
+export declare function limitPauseLines(report: RunReport): string[];
+export declare function failureLines(report: RunReport, outputs: ReadonlyMap<string, OutputTail>, stderrTail: boolean): string[];
+export interface OutputTail {
+    stdout: string;
+    stderr: string;
+    truncated: boolean;
+}
+export declare const OUTPUT_TAIL_SANDBOXES = 20;
+export declare const OUTPUT_TAIL_CHARS = 4096;
+export declare function outputTails(c: PromigenceClient, sandboxes: ReadonlyArray<{
+    sandbox_id: string;
+    execs?: Array<{
+        exec_id: string;
+    }>;
+}>): Promise<Map<string, OutputTail>>;
+export declare function positional(ctx: Ctx, what: string, example: string): string;
+export declare function supportStoppedLines(sandboxes: ReadonlyArray<{
+    sandbox_id: string;
+    outcome?: string | null;
+}>): string[];
+export declare function filesPutTarArgs(out: string, parent: string, base: string, noMetadata?: string[]): string[];
+export declare const HANDLERS: Readonly<Record<string, Handler>>;
+export {};