promigence 0.1.0-beta.12

package/dist/handlers.js

@@ -0,0 +1,511 @@
+import { existsSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { BUNDLE_EXT, DEFAULT_SNAPSHOT, PromigenceError, VERSION as SDK_VERSION, configDir, credentialsPath, platformOf, readCredentialsWithStore, renderBundle, verifyBundle, } from "./sdk/index.js";
+import { storeLabel } from "./sdk/credstore.js";
+import { bool, client, list, nexts, positional, required, str, } from "./commands.js";
+import { emit, exitWith, forkSummary, markGuideSeen, ms, okEnvelope, parseCount, parseDuration, parseUsd, pickExit, usageError, write, } from "./io.js";
+import { ALL_ERROR_CODES, BUDGETS, estimateTokens, guideJson, humanHeader, lookupError, renderGuide } from "./guide.js";
+import { livePricing, quickClient } from "./pricing.js";
+import { install, installLines } from "./install.js";
+import { backgroundOutput } from "./live.js";
+import { detect, gitFacts, imageCreateCommand, renderConfig, stripRemoteCredentials } from "./init.js";
+import { TIERS } from "./generated.js";
+import { GOLDEN_PATH, SCHEMA, VERSION } from "./surface.js";
+import { jsonLine, sh } from "./term.js";
+import { fmtMs, median, where } from "./timing.js";
+const SECTION_NAMES = new Set(["core", "commands", "errors", "cost"]);
+const agentGuide = async (ctx) => {
+    const format = str(ctx, "--format") ?? (ctx.explicitMode === "json" ? "json" : "md");
+    if (format !== "md" && format !== "json") {
+        throw usageError(`--format: '${format}' is not a format`, "Pass --format md (default) or --format json.");
+    }
+    const json = format === "json";
+    if (bool(ctx, "--create") && !bool(ctx, "--install") && !bool(ctx, "--check")) {
+        throw usageError("--create needs --install", "Pass --install --create to write AGENTS.md (and the skill and rule files) here.");
+    }
+    if (bool(ctx, "--install") || bool(ctx, "--check")) {
+        const checking = bool(ctx, "--check");
+        const res = install(process.cwd(), { write: !checking, create: bool(ctx, "--create") });
+        markGuideSeen();
+        const skipped = res.artifacts.find((a) => a.action === "skipped");
+        const next = nexts(...(skipped
+            ? [["promigence agent-guide --install --create", "create AGENTS.md and write the fence into it"]]
+            : []), ["promigence agent-guide", "the guide itself (~1.4k tokens)"], ["promigence examples", "what you can fork with no build (the built-in base)"]);
+        const env = okEnvelope(ctx.cmd.name, {
+            mode: checking ? "check" : "install",
+            dir: res.dir,
+            changed: res.changed,
+            ...(res.memoryFile ? { memory_file: res.memoryFile } : {}),
+            artifacts: res.artifacts,
+        }, next);
+        return emit(ctx.mode, env, installLines(res, checking), checking && res.changed ? 13 : 0, false);
+    }
+    const code = str(ctx, "--code");
+    const sectionFlag = str(ctx, "--section");
+    if (sectionFlag !== undefined && !SECTION_NAMES.has(sectionFlag)) {
+        throw usageError(`--section: '${sectionFlag}' is not a section`, "Pass --section commands | errors | cost (omit it for the core guide).");
+    }
+    const section = (sectionFlag ?? "core");
+    if (code !== undefined && lookupError(code) === undefined) {
+        const near = ALL_ERROR_CODES.filter((k) => k.includes(code) || code.includes(k)).slice(0, 3);
+        throw usageError(`--code: '${code}' is not an error code`, `${near.length ? `Did you mean ${near.join(", ")}? ` : ""}List them: promigence agent-guide --section errors.`);
+    }
+    const prices = section === "cost" && code === undefined ? await livePricing(quickClient(ctx)) : undefined;
+    const opts = { section, ...(code === undefined ? {} : { code }), ...(prices === undefined ? {} : { prices }) };
+    const guide = renderGuide(opts);
+    markGuideSeen();
+    if (json) {
+        const body = guideJson(opts);
+        const env = {
+            schema: SCHEMA, command: ctx.cmd.name, ok: true, ...body,
+            next: [
+                { cmd: "promigence examples", why: "what you can fork with no build (the built-in base)" },
+                { cmd: GOLDEN_PATH, why: "the golden path, end to end" },
+            ],
+        };
+        await write(process.stdout, jsonLine(process.stdout, env));
+        return exitWith(0);
+    }
+    if (section === "core" && code === undefined && process.stdout.isTTY)
+        await write(process.stdout, humanHeader());
+    await write(process.stdout, guide);
+    const budget = BUDGETS[section] ?? BUDGETS.core;
+    const used = estimateTokens(guide);
+    if (used > budget)
+        await write(process.stderr, `warning: ${section} guide is ~${used} tokens, over its ${budget} budget\n`);
+    return exitWith(0);
+};
+const TIERS_SELLABLE = TIERS.filter((t) => t.sellable)
+    .sort((a, b) => a.vcpus - b.vcpus || a.mem_gib - b.mem_gib)
+    .map((t) => t.name);
+const init = async (ctx) => {
+    const dir = process.cwd();
+    const path = join(dir, "promigence.toml");
+    const printOnly = bool(ctx, "--print");
+    if (existsSync(path) && !bool(ctx, "--force") && !printOnly) {
+        throw usageError(`promigence.toml already exists in ${dir}`, "Pass --force to overwrite it, or --print to see what init would write without touching it.");
+    }
+    const found = detect(dir);
+    const git = gitFacts(dir);
+    const notes = [];
+    const repoGiven = str(ctx, "--repo");
+    const repo = repoGiven === undefined ? git.repo : stripRemoteCredentials(repoGiven);
+    const credsRemoved = repoGiven === undefined ? Boolean(git.credentialsRemoved) : repo !== repoGiven;
+    if (credsRemoved) {
+        notes.push("WARNING: credentials removed from the git remote URL: promigence.toml is committed with your code, and " +
+            "credentials in repository URLs are not accepted. For private code, see the line on code the builder cannot clone.");
+    }
+    if (!repo) {
+        throw usageError("no git remote `origin` in this directory, and no --repo", "Pass --repo https://github.com/org/app — the builder clones it, so it must be a public repository it can reach.");
+    }
+    const commit = str(ctx, "--commit") ?? git.commit;
+    if (!commit) {
+        throw usageError("cannot read HEAD in this directory, and no --commit", "Run this inside a git checkout, or pass --commit <40-char sha> (a branch is not a pin).");
+    }
+    if (!/^[0-9a-f]{40}$/i.test(commit)) {
+        throw usageError(`--commit ${commit} is not a 40-character sha`, "A branch or short sha is not a pin: pass the full sha (git rev-parse HEAD).");
+    }
+    const setupFlags = list(ctx, "--setup");
+    const setup = setupFlags.length ? setupFlags : found.setup;
+    const verify = str(ctx, "--verify") ?? found.verify;
+    const tier = str(ctx, "--tier") ?? "medium";
+    if (!TIERS_SELLABLE.includes(tier)) {
+        throw usageError(`--tier: '${tier}' is not a tier`, `Pass --tier ${TIERS_SELLABLE.join(" | ")} (see 'promigence agent-guide --section cost').`);
+    }
+    if (!verify) {
+        throw usageError(`no verify command could be inferred (${found.why})`, "Pass --verify 'the command that must exit 0' — a snapshot with nothing to verify is not verified.");
+    }
+    notes.push(`ecosystem: ${found.ecosystem}${found.lockfile ? ` (${found.lockfile})` : ""}`);
+    notes.push(`verify: ${setupFlags.length || str(ctx, "--verify") ? "given on the command line" : found.why}`);
+    if (git.dirty)
+        notes.push("WARNING: the working tree is dirty — the snapshot is built from the commit, not your edits.");
+    if (str(ctx, "--commit") === undefined && git.onRemote === false) {
+        notes.push(git.noRemoteRefs
+            ? `WARNING: HEAD ${commit.slice(0, 7)} has not been pushed (this checkout has no remote branches), so the builder ` +
+                "cannot fetch it: push it first (git push), or pass --commit with a sha that is on the remote."
+            : `WARNING: HEAD ${commit.slice(0, 7)} is on no remote branch, so the builder cannot fetch it: push it first (git push), ` +
+                "or pass --commit with a sha that is on the remote.");
+    }
+    if (git.branch && git.branch !== "HEAD")
+        notes.push(`pinned from branch ${git.branch}; re-run promigence init after every commit you want to fork`);
+    const uncloneable = credsRemoved || (str(ctx, "--commit") === undefined && git.onRemote === false);
+    const otherWays = "Code the builder cannot clone (private, or not pushed): `promigence snapshot create --dir . --alias NAME " +
+        "--setup … --verify … --wait` uploads this checkout instead (built on promigence/base), or `promigence github connect` " +
+        "and then `promigence snapshot create --repo owner/name`.";
+    if (uncloneable)
+        notes.push(otherWays);
+    const cfg = {
+        repo, commit: commit.toLowerCase(), setup, verify, tier,
+        toolchain: found.toolchain,
+        ...(found.lockfile ? { lockfile: found.lockfile } : {}),
+    };
+    const createCmd = imageCreateCommand(cfg, found.ecosystem);
+    const toml = renderConfig(cfg, notes, createCmd);
+    if (!printOnly)
+        writeFileSync(path, toml);
+    const next = nexts([createCmd, "build and verify the snapshot this file describes"], ["promigence examples", "or fork the built-in base first, with no build at all"]);
+    const env = okEnvelope(ctx.cmd.name, {
+        path: printOnly ? null : path,
+        written: !printOnly,
+        ecosystem: found.ecosystem,
+        ...(found.lockfile ? { lockfile: found.lockfile } : {}),
+        repo, commit: cfg.commit, setup, verify, tier,
+        toolchain: found.toolchain,
+        ...(git.branch ? { branch: git.branch } : {}),
+        ...(git.dirty === undefined ? {} : { dirty: git.dirty }),
+        inference: found.why,
+        ...(credsRemoved ? { credentials_removed: true } : {}),
+        config: toml,
+    }, next);
+    const lines = [
+        `promigence init: ${printOnly ? "(--print, nothing written)" : path}`,
+        `  ecosystem ${found.ecosystem}${found.lockfile ? ` from ${found.lockfile}` : ""} — ${found.why}`,
+        `  repo   ${repo}`,
+        ...(credsRemoved ? ["  WARNING: credentials removed from the git remote URL (promigence.toml is committed with your code)"] : []),
+        `  commit ${cfg.commit}${git.dirty ? "  (working tree is dirty; the build uses the commit)" : ""}`,
+        ...setup.map((s, i) => `  setup[${i}] ${s}`),
+        `  verify ${verify}`,
+        `  tier   ${tier}${str(ctx, "--tier") === undefined ? "  (init's default; every fork of this snapshot runs at this size: --tier small is the smaller one)" : ""}`,
+        ...(printOnly ? ["", ...toml.split("\n")] : []),
+        `  next: ${createCmd}`,
+        ...(uncloneable ? [`  or:   ${otherWays}`] : []),
+    ];
+    return emit(ctx.mode, env, lines, 0, ctx.pointer);
+};
+const FALLBACK_EXAMPLES = [
+    {
+        snapshot_id: DEFAULT_SNAPSHOT,
+        visibility: "public",
+        tier: "small",
+        verify: { cmd: "python3 -c 'print(6*7)'" },
+    },
+];
+const examples = async (ctx) => {
+    const limit = parseCount(str(ctx, "--limit") ?? "20", "--limit");
+    const c = client(ctx);
+    let snapshots;
+    let fallback = false;
+    let failed = false;
+    let reason;
+    try {
+        snapshots = await c.snapshots.public(limit);
+        if (snapshots.length === 0) {
+            snapshots = [...FALLBACK_EXAMPLES];
+            fallback = true;
+            reason = "the API lists no public snapshots yet; promigence/base is built in and not listed by the API";
+        }
+    }
+    catch (err) {
+        snapshots = [...FALLBACK_EXAMPLES];
+        fallback = true;
+        failed = true;
+        reason = err instanceof PromigenceError ? `${err.code}: ${err.message}` : String(err);
+    }
+    const bundles = [];
+    if (bool(ctx, "--bundle")) {
+        if (fallback) {
+            throw usageError(`--bundle writes one file per public snapshot, and there are none to write (${reason}); the built-in promigence/base has no bundle`, "Bundle an environment of your own instead: `promigence snapshot export <id> --out env.promigence`.");
+        }
+        for (const s of snapshots) {
+            const id = s.snapshot_id;
+            const { bundle, served_by } = await c.snapshots.bundle(id);
+            const form = verifyBundle(bundle);
+            const text = renderBundle(bundle);
+            const file = `${bundle.alias ?? bundle.snap_id}${BUNDLE_EXT}`;
+            writeFileSync(resolve(file), text);
+            bundles.push({
+                path: resolve(file), bytes: text.length, form, served_by,
+                snapshot_id: bundle.snap_id, manifest_hash: bundle.manifest_hash,
+                platform: platformOf(bundle) ?? null,
+            });
+        }
+    }
+    const first = fallback ? undefined : snapshots[0];
+    const golden = first
+        ? sh `promigence run --snapshot ${first.alias ? (first.commit ? `${first.alias}@${first.commit.slice(0, 7)}` : first.alias) : first.snapshot_id} --count 2 --cap 1 --json -- sh -c ${first.verify?.cmd ?? "true"}`
+        : GOLDEN_PATH;
+    const next = nexts([golden, "fork it twice, run its verify command in each, print the validity report"], ["promigence agent-guide", "the model, the output contract and the exit codes"]);
+    const env = {
+        ...okEnvelope(ctx.cmd.name, {
+            snapshots,
+            count: snapshots.length,
+            source: fallback ? "fallback" : "api",
+            default_snapshot: DEFAULT_SNAPSHOT,
+            ...(reason ? { fallback_reason: reason } : {}),
+            ...(bundles.length ? { bundles } : {}),
+            authenticated: false,
+        }, next),
+    };
+    const lines = [
+        fallback ? "public snapshots: the built-in base" : `public snapshots: ${snapshots.length}`,
+        ...(failed ? [`  the API did not serve the list: ${reason}`] : []),
+        ...(fallback && !failed ? ["  promigence/base is built in and not listed by the API; it has no manifest or bundle"] : []),
+        ...(fallback ? [] : [`  ${DEFAULT_SNAPSHOT}  built in: the default when no --snapshot is given (not in the list below)`]),
+        ...snapshots.map((s) => `  ${s.alias ?? s.snapshot_id}${s.commit ? `@${s.commit.slice(0, 7)}` : ""}  tier ${s.tier ?? "?"}  verify ${JSON.stringify(s.verify?.cmd ?? "?")}  ${s.repo ?? ""}`),
+        ...bundles.map((b) => `  wrote ${b["path"]} — ${b["bytes"].toLocaleString("en-US")} B, ${b["form"]} form (${b["served_by"]}-composed)`),
+        `  next: ${golden}`,
+    ];
+    return emit(ctx.mode, env, lines, 0, ctx.pointer);
+};
+const ok = (name, measured) => ({ name, measured, result: "ok" });
+const warn = (name, measured, fix) => ({ name, measured, result: "warn", fix });
+const fail = (name, measured, fix, exit) => ({ name, measured, result: "fail", fix, exit });
+function keySource(ctx) {
+    if (ctx.apiKey)
+        return { source: "--api-key (visible in `ps`; prefer PROMIGENCE_API_KEY)", present: true };
+    if (process.env["PROMIGENCE_API_KEY"])
+        return { source: "PROMIGENCE_API_KEY", present: true };
+    const { creds, store } = readCredentialsWithStore();
+    if (creds.api_key) {
+        return { source: store === "file" || store === undefined ? credentialsPath() : `${storeLabel(store)} (item ${credentialsPath()})`, present: true };
+    }
+    return { source: "none", present: false };
+}
+async function clientChecks(ctx) {
+    const checks = [];
+    const major = Number(process.versions.node.split(".")[0]);
+    checks.push(major >= 20
+        ? ok("node", `v${process.versions.node} (>= 20)`)
+        : fail("node", `v${process.versions.node}`, "promigence needs Node >= 20 (package.json engines). Upgrade Node, then rerun.", 1));
+    checks.push(ok("promigence", `${VERSION} (sdk ${SDK_VERSION})`));
+    const cfg = configDir();
+    checks.push(ok("config_dir", `${cfg}${existsSync(cfg) ? "" : " (not created yet)"}`));
+    const key = keySource(ctx);
+    if (!key.present) {
+        checks.push(fail("auth_key", "no key in --api-key, PROMIGENCE_API_KEY, the OS keychain or the credentials file", "No key yet: `promigence login` signs you up or in and stores one. A key you already have: `promigence auth login --from-env VAR`.", 7));
+    }
+    else {
+        checks.push(ok("auth_key", `from ${key.source}`));
+        const path = credentialsPath();
+        if (existsSync(path)) {
+            const mode = statSync(path).mode & 0o777;
+            checks.push(mode === 0o600
+                ? ok("credentials_mode", `0${mode.toString(8)} on ${path}`)
+                : warn("credentials_mode", `0${mode.toString(8)} on ${path}`, `Tighten it: chmod 600 ${path} (it holds your API key).`));
+        }
+    }
+    return checks;
+}
+async function apiChecks(ctx, checks) {
+    const c = client(ctx);
+    checks.push(ok("api_url", c.apiUrl));
+    let health;
+    const t0 = Date.now();
+    try {
+        health = await c.health({ timeoutMs: 10_000 });
+    }
+    catch (err) {
+        const e = err;
+        checks.push(fail("api_reachable", `${e.code ?? "error"}: ${e.message ?? String(err)}`, e.fix ?? "Check PROMIGENCE_API_URL and connectivity; the API is at https://api.promigence.ai/v1.", e.cliExit ?? 9));
+        return;
+    }
+    const ms = Date.now() - t0;
+    checks.push(ok("api_reachable", `GET /health in ${ms} ms`));
+    if (health.serving === false) {
+        checks.push(warn("capacity_ready", "the service cannot start new sandboxes right now", "New sandboxes queue until capacity is ready; nothing is billed while they wait. `promigence status` shows each service."));
+    }
+    else {
+        checks.push(ok("capacity_ready", health.serving === true ? "new sandboxes can start now" : "the API did not say; `promigence status` shows each service"));
+    }
+    const server = health.version;
+    checks.push(ok("version_skew", server
+        ? `client ${VERSION} · api ${server} (numbered separately)`
+        : `client ${VERSION} · the API did not report a version`));
+    if (!keySource(ctx).present)
+        return;
+    try {
+        const me = await c.me();
+        const cap = typeof me.default_spend_cap === "number" && me.default_spend_cap > 0 ? ` · default spend cap $${me.default_spend_cap}` : "";
+        checks.push(ok("auth_accepted", `org ${me.org_id ?? "?"}${me.key?.key_id ? ` key ${me.key.key_id}` : ""}${cap}`));
+    }
+    catch (err) {
+        const e = err;
+        checks.push(fail("auth_accepted", `${e.code}: ${e.message}`, e.fix, e.cliExit ?? 7));
+    }
+}
+const ping = async (ctx) => {
+    const n = Number(process.env["PROMIGENCE_PING_COUNT"] ?? "5");
+    if (!Number.isInteger(n) || n < 1 || n > 50)
+        throw usageError("PROMIGENCE_PING_COUNT takes 1 to 50", "Unset it for the default of five.");
+    const c = client(ctx);
+    const rounds = [];
+    let location;
+    for (let i = 0; i < n; i++) {
+        const h = await c.health({ timeoutMs: 10_000 });
+        if (typeof h.location === "string" && h.location)
+            location = h.location;
+        const tm = c.lastTiming;
+        if (tm)
+            rounds.push({ totalMs: tm.totalMs, ourMs: tm.ourMs });
+    }
+    const totals = rounds.map((r) => r.totalMs);
+    const ours = rounds.map((r) => r.ourMs).filter((x) => x !== null);
+    const nets = rounds.filter((r) => r.ourMs !== null).map((r) => Math.max(0, r.totalMs - r.ourMs));
+    const rt = median(totals);
+    const our = median(ours);
+    const net = median(nets);
+    const r1 = (x) => (x === undefined ? null : Math.round(x * 10) / 10);
+    const fields = {
+        location: location ?? null,
+        round_trips: n,
+        round_trip_ms: { median: r1(rt), min: r1(Math.min(...totals)), max: r1(Math.max(...totals)) },
+        our_side_ms: r1(our),
+        network_ms: r1(net),
+    };
+    const lines = [
+        `promigence ping: ${where(location)}`,
+        `  round trip   ${rt === undefined ? "—" : fmtMs(rt)} (median of ${n}; ${fmtMs(Math.min(...totals))} to ${fmtMs(Math.max(...totals))})`,
+        `  our side     ${our === undefined ? "— (not said by this service)" : fmtMs(our)}`,
+        `  your network ${net === undefined ? "—" : fmtMs(net)}`,
+        ...(net !== undefined && net >= 150
+            ? ["  Times marked 'on our side' are the platform's own; the rest is the distance to our servers."]
+            : []),
+    ];
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, fields, nexts(["promigence doctor", "check the client, your key and the API"])), lines, 0, ctx.pointer);
+};
+const doctor = async (ctx) => {
+    const checks = await clientChecks(ctx);
+    await apiChecks(ctx, checks);
+    const failed = checks.filter((c) => c.result === "fail");
+    const warned = checks.filter((c) => c.result === "warn");
+    const exit = pickExit(failed.map((c) => c.exit ?? 1));
+    const next = failed.length
+        ? nexts([failed[0].fix?.match(/`([^`]+)`/)?.[1] ?? "promigence agent-guide --section errors", `fix the first failure: ${failed[0].name}`])
+        : nexts(["promigence examples", "what you can fork with no build (the built-in base)"]);
+    const env = {
+        ...okEnvelope(ctx.cmd.name, {
+            checks,
+            ok: failed.length === 0,
+            failures: failed.length,
+            warnings: warned.length,
+            exit,
+        }, next),
+        ok: failed.length === 0,
+    };
+    const lines = [
+        `promigence doctor: ${checks.length} checks · ${failed.length} failed · ${warned.length} warned`,
+        ...checks.map((c) => `  ${(c.result === "ok" ? "ok  " : c.result === "warn" ? "warn" : "FAIL")}  ${c.name.padEnd(18)} ${c.measured}`),
+        ...failed.flatMap((c) => [`  fix (${c.name}): ${c.fix}`]),
+        ...warned.flatMap((c) => [`  note (${c.name}): ${c.fix}`]),
+    ];
+    return emit(ctx.mode, env, lines, exit, ctx.pointer);
+};
+export function parseRange(value) {
+    const v = value.trim();
+    const m = /^(\d+)-(\d*)$/.exec(v);
+    if (!m) {
+        throw usageError(`--range: '${value}' is not a byte range`, v.startsWith("-")
+            ? "There is no suffix form: pass --range A-B or A- (0-based, B inclusive). For the tail, read `total_bytes` from the envelope and ask for `<total_bytes-N>-`."
+            : "Pass --range A-B or A- (0-based, B inclusive), e.g. --range 0-65535.");
+    }
+    const out = { from: Number(m[1]) };
+    if (m[2] !== "")
+        out.to = Number(m[2]);
+    if (out.to !== undefined && out.to < out.from) {
+        throw usageError(`--range: '${value}' ends before it starts`, "Pass --range A-B with B >= A.");
+    }
+    return out;
+}
+const execOutput = async (ctx) => {
+    const execId = positional(ctx, "an exec id", "promigence exec output exec_ab12 --sandbox sbx_cd34");
+    if (execId.startsWith("x_"))
+        return backgroundOutput(ctx, execId);
+    if (bool(ctx, "--follow")) {
+        throw usageError("--follow is for a background exec (x_…)", "A foreground exec has already finished; drop --follow.");
+    }
+    const range = str(ctx, "--range");
+    const res = await client(ctx).sandboxes.output(execId, {
+        ...(str(ctx, "--sandbox") === undefined ? {} : { sandboxId: str(ctx, "--sandbox") }),
+        ...(str(ctx, "--run") === undefined ? {} : { runId: str(ctx, "--run") }),
+        ...(range === undefined ? {} : { range: parseRange(range) }),
+    });
+    if (ctx.mode === "text") {
+        await write(process.stdout, bool(ctx, "--stderr") ? res.stderr : res.stdout);
+        return exitWith(0);
+    }
+    const next = nexts(...(res.run_id ? [[sh `promigence run report ${res.run_id} --json`, "the validity report this exec belongs to"]] : []), ...(res.sandbox_id && res.terminal !== true ? [[sh `promigence sandbox kill ${res.sandbox_id}`, "end the sandbox when you are done"]] : []));
+    const env = okEnvelope(ctx.cmd.name, {
+        exec_id: res.exec_id,
+        ...(res.sandbox_id ? { sandbox_id: res.sandbox_id } : {}),
+        ...(res.run_id ? { run_id: res.run_id } : {}),
+        ...(res.argv ? { argv: res.argv } : {}),
+        exit_code: res.exit_code,
+        stdout: res.stdout,
+        stderr: res.stderr,
+        truncated: res.truncated ?? false,
+        bytes: res.bytes,
+        total_bytes: res.total_bytes,
+        ...(res.range ? { range: res.range } : {}),
+    }, next);
+    return emit(ctx.mode, env, [], 0, false);
+};
+const benchBurst = async (ctx) => {
+    const snapshot = required(ctx, "--snapshot", "Pass --snapshot snap_<id> | <alias>[@commit7], or promigence/base (the built-in base).");
+    const count = parseCount(required(ctx, "--count", "Pass --count N — how many sandboxes to start at once. The published burst table uses 100."), "--count");
+    const timeoutMs = parseDuration(str(ctx, "--timeout") ?? "120s", "--timeout");
+    const capStr = str(ctx, "--cap") ?? process.env["PROMIGENCE_SPEND_CAP"];
+    if (capStr === undefined) {
+        throw usageError("bench burst needs a spend cap", `Pass --cap USD (or set PROMIGENCE_SPEND_CAP). Price it first: \`${sh `promigence run quote --snapshot ${snapshot} --count ${count}`}\`.`);
+    }
+    const spendCap = parseUsd(capStr, "--cap");
+    const keep = bool(ctx, "--keep");
+    const c = client(ctx);
+    const t0 = Date.now();
+    const started = await c.runs.start({ snapshot, count, spendCap, timeoutMs });
+    const runId = started.run_id;
+    ctx.startedRunId = runId;
+    let waited;
+    let wallMs;
+    let report;
+    let killed = false;
+    try {
+        waited = await c.runs.waitReady(runId, { waitTimeoutMs: timeoutMs + 10_000 });
+        wallMs = Date.now() - t0;
+        report = await c.runs.report(runId).catch(() => undefined);
+    }
+    finally {
+        if (!keep)
+            killed = await c.runs.kill(runId).then(() => true, () => false);
+    }
+    const up = waited.sandboxes.filter((s) => s.state === "ready" || s.state === "running").length;
+    const successPct = Math.round((up / count) * 1000) / 10;
+    const fork = report ? forkSummary(report.fork) : {};
+    const next = nexts([sh `promigence run report ${runId} --json`, "the validity report behind these numbers"], ...(killed ? [] : [[sh `promigence run kill ${runId}`, keep ? "end the burst (--keep left it running and billing)" : "the kill did not complete: end the burst"]]));
+    const env = {
+        ...okEnvelope(ctx.cmd.name, {
+            run_id: runId,
+            requested: { snapshot, count, timeout_ms: timeoutMs, spend_cap: spendCap },
+            up,
+            success_pct: successPct,
+            wall_ms: wallMs,
+            waited_ms: waited.waitedMs,
+            timed_out: waited.timedOut,
+            fork,
+            ...(report?.totals ? { totals: report.totals } : {}),
+            sandboxes: waited.sandboxes,
+            killed,
+        }, next),
+        ok: up === count,
+    };
+    const pct = (k) => {
+        const v = fork[k];
+        return v ? `${k} p50 ${ms(v.p50 ?? 0)} · p95 ${ms(v.p95 ?? 0)}${v.p99 === undefined ? "" : ` · p99 ${ms(v.p99)}`}` : "";
+    };
+    const lines = [
+        `burst ${runId}: ${up}/${count} up (${successPct}%) in ${ms(wallMs)}`,
+        ...["e2e_ms", "fork_ms", "ready_ms", "queued_ms"].map(pct).filter(Boolean).map((l) => `  ${l}`),
+        ...(waited.timedOut ? [`  timed out after ${ms(timeoutMs + 10_000)}: ${count - up} never came up`] : []),
+        killed ? "  sandboxes killed" : keep ? "  --keep: sandboxes left running, billed until killed or --timeout" : "  the kill did not complete: run the kill below",
+        `  next: ${next.map((n) => n.cmd).join("  ·  ")}`,
+    ];
+    return emit(ctx.mode, env, lines, up === count ? 0 : 3, ctx.pointer);
+};
+export const EXTRA_HANDLERS = {
+    "bench burst": benchBurst,
+    "agent-guide": agentGuide,
+    init,
+    examples,
+    doctor,
+    ping,
+    "exec output": execOutput,
+};

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./sdk/index.js";
+export { SCHEMA, GUIDE_POINTER, GOLDEN_PATH, COMMANDS, LISTED_COMMANDS, GROUPS, GLOBAL_FLAGS, EXIT_CODES, LIVE_COMMANDS, LIVE_SUMMARY, NOT_LIVE_SUMMARY, STATUS_LINE, DESCRIPTION, compactNames, EXIT_PRECEDENCE, EXIT_PRECEDENCE_TEXT, OUTPUT_MODE_PRECEDENCE, WAIT_TIMEOUT_DEFAULT, REQUEST_TIMEOUT_DEFAULT, GUIDE_COMMON_ERRORS, findCommand, knownFlags, nearestFlag, unknownFlags, renderHelp, renderCommandHelp, signInLine, notReleasedEnvelope, notReleasedLines, } from "./surface.js";
+export { ALL_ERROR_CODES, BILLED_TEXT, BUDGETS, SECTIONS, estimateTokens, guideJson, lookupError, renderGuide, renderLlmsTxt, 
+renderGuide as renderAgentGuide, } from "./guide.js";
+export type { Section } from "./guide.js";
+export { CLIENT_ERRORS, CLIENT_ERROR_BY_CODE, ERRORS, ERROR_BY_CODE, TIERS, BUILD_MAX_S, PRICING } from "./generated.js";
+export type { ErrorEntry, TierEntry } from "./generated.js";
+export { FENCE_BEGIN, FENCE_END, FENCE_MAX_LINES, fenceBody, install, spliceFence } from "./install.js";
+export type { Artifact, InstallResult } from "./install.js";
+export { detect, gitFacts, normalizeRemote, readConfig, renderConfig, stripRemoteCredentials } from "./init.js";
+export type { Config, Detection, Ecosystem, GitFacts, ReadConfig } from "./init.js";
+export { DEVCONTAINER_NAMES, DEVCONTAINER_SPEC, DevcontainerError, detectOne, discover, load, parseJsonc, planJson, planLines, planSetup, resolveGiven, shellQuote, snapshotEnv, snapshotUsers, substituteString, translate, workspaceRootFor, wrapCommand, } from "./devcontainer.js";
+export type { LoadedDevcontainer, Plan, PlanSource, LifecycleStep, IgnoredProperty } from "./devcontainer.js";
+export type { Command, Flag, Group, CommandStatus, ExitCode, Envelope, EnvelopeError, NextHint } from "./surface.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from "./sdk/index.js";
+export { SCHEMA, GUIDE_POINTER, GOLDEN_PATH, COMMANDS, LISTED_COMMANDS, GROUPS, GLOBAL_FLAGS, EXIT_CODES, LIVE_COMMANDS, LIVE_SUMMARY, NOT_LIVE_SUMMARY, STATUS_LINE, DESCRIPTION, compactNames, EXIT_PRECEDENCE, EXIT_PRECEDENCE_TEXT, OUTPUT_MODE_PRECEDENCE, WAIT_TIMEOUT_DEFAULT, REQUEST_TIMEOUT_DEFAULT, GUIDE_COMMON_ERRORS, findCommand, knownFlags, nearestFlag, unknownFlags, renderHelp, renderCommandHelp, signInLine, notReleasedEnvelope, notReleasedLines, } from "./surface.js";
+export { ALL_ERROR_CODES, BILLED_TEXT, BUDGETS, SECTIONS, estimateTokens, guideJson, lookupError, renderGuide, renderLlmsTxt, renderGuide as renderAgentGuide, } from "./guide.js";
+export { CLIENT_ERRORS, CLIENT_ERROR_BY_CODE, ERRORS, ERROR_BY_CODE, TIERS, BUILD_MAX_S, PRICING } from "./generated.js";
+export { FENCE_BEGIN, FENCE_END, FENCE_MAX_LINES, fenceBody, install, spliceFence } from "./install.js";
+export { detect, gitFacts, normalizeRemote, readConfig, renderConfig, stripRemoteCredentials } from "./init.js";
+export { DEVCONTAINER_NAMES, DEVCONTAINER_SPEC, DevcontainerError, detectOne, discover, load, parseJsonc, planJson, planLines, planSetup, resolveGiven, shellQuote, snapshotEnv, snapshotUsers, substituteString, translate, workspaceRootFor, wrapCommand, } from "./devcontainer.js";

package/dist/init.d.ts

@@ -0,0 +1,40 @@
+export type Ecosystem = "bun" | "pnpm" | "yarn" | "npm" | "uv" | "poetry" | "pipenv" | "pip" | "pyproject" | "cargo" | "go" | "bundler" | "composer" | "unknown";
+export interface Detection {
+    ecosystem: Ecosystem;
+    lockfile?: string;
+    setup: string[];
+    verify: string;
+    toolchain: string[];
+    why: string;
+}
+export declare function detect(dir: string): Detection;
+export declare function stripRemoteCredentials(url: string): string;
+export declare function normalizeRemote(url: string): string;
+export interface GitFacts {
+    repo?: string;
+    commit?: string;
+    branch?: string;
+    dirty?: boolean;
+    credentialsRemoved?: boolean;
+    onRemote?: boolean;
+    noRemoteRefs?: boolean;
+}
+export declare function gitFacts(dir: string): GitFacts;
+export declare const INIT_IMAGES: Partial<Record<string, string>>;
+export declare function ecosystemOfCommands(commands: readonly string[]): string | undefined;
+export declare function imageCreateCommand(c: Pick<Config, "repo" | "commit" | "setup" | "verify"> & {
+    tier?: string | undefined;
+}, ecosystem: string): string;
+export interface Config {
+    repo: string;
+    commit: string;
+    setup: string[];
+    verify: string;
+    tier: string;
+    toolchain: string[];
+    lockfile?: string;
+    alias?: string;
+}
+export type ReadConfig = Partial<Pick<Config, "repo" | "commit" | "tier" | "alias" | "verify" | "setup">>;
+export declare function readConfig(text: string): ReadConfig;
+export declare function renderConfig(c: Config, notes?: readonly string[], build?: string): string;