promigence 0.1.0-beta.12

package/dist/io.js

@@ -0,0 +1,318 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { ERRORS_DOCS_URL, PromigenceError, configDir, } from "./sdk/index.js";
+import { DOCS_URL, EXIT_PRECEDENCE, GUIDE_POINTER, SCHEMA, VERSION, } from "./surface.js";
+import { usd } from "./money.js";
+import { fieldForTerminal, jsonLine } from "./term.js";
+const seenGuidePath = () => `${configDir()}/seen-guide`;
+export const seenGuide = () => existsSync(seenGuidePath());
+export function markGuideSeen() {
+    try {
+        mkdirSync(configDir(), { recursive: true });
+        writeFileSync(seenGuidePath(), `${new Date().toISOString()} promigence@${VERSION}\n`);
+    }
+    catch { }
+}
+let pipeGuardInstalled = false;
+export function isGoneReader(code) {
+    return code === "EPIPE" || code === "ENOTCONN" || code === "ECONNRESET";
+}
+function guardPipe() {
+    if (pipeGuardInstalled)
+        return;
+    pipeGuardInstalled = true;
+    const handle = (exitOnEpipe) => (err) => {
+        if (isGoneReader(err.code)) {
+            if (exitOnEpipe)
+                process.exit(0);
+            return;
+        }
+        throw err;
+    };
+    process.stdout.on("error", handle(true));
+    process.stderr.on("error", handle(false));
+}
+export function writeBytes(stream, data) {
+    if (!data.length)
+        return Promise.resolve();
+    guardPipe();
+    return new Promise((resolve) => {
+        stream.write(data, () => resolve());
+    });
+}
+export function write(stream, text) {
+    if (!text)
+        return Promise.resolve();
+    guardPipe();
+    return new Promise((resolve) => {
+        stream.write(text, () => resolve());
+    });
+}
+function flush(stream) {
+    guardPipe();
+    return new Promise((resolve) => {
+        stream.write("", () => resolve());
+    });
+}
+let beforeExit;
+export function setBeforeExit(fn) {
+    beforeExit = fn;
+}
+export async function exitWith(code) {
+    const hook = beforeExit;
+    beforeExit = undefined;
+    if (hook)
+        await hook().catch(() => undefined);
+    await flush(process.stdout);
+    await flush(process.stderr);
+    process.exit(code);
+    throw new Error("unreachable");
+}
+let accountNotice;
+export function recordNotice(n) {
+    accountNotice ??= n;
+}
+export function noticeLine(n) {
+    return `promigence: notice (${n.code}): ${n.message ?? ""}${n.fix ? ` — ${n.fix}` : ""}`;
+}
+export const PLACEHOLDER = /<[a-z][a-z_ -]*>/i;
+export async function emit(mode, env, textLines, exit, pointer, textTo = "payload") {
+    const showPointer = pointer && !seenGuide();
+    env.next = (env.next ?? []).filter((n) => !PLACEHOLDER.test(n.cmd));
+    if (!env.ok && env.error && env.error.exit === undefined) {
+        env.error.exit = typeof env.promigence_exit === "number" ? env.promigence_exit : exit;
+    }
+    if (mode === "json") {
+        if (showPointer)
+            env.hint = GUIDE_POINTER;
+        if (accountNotice)
+            env.notice = accountNotice;
+        await write(process.stdout, jsonLine(process.stdout, env));
+    }
+    else {
+        if (showPointer && !process.stdout.isTTY)
+            await write(process.stderr, GUIDE_POINTER + "\n");
+        if (accountNotice)
+            await write(process.stderr, fieldForTerminal(process.stderr, noticeLine(accountNotice)) + "\n");
+        const out = env.ok && textTo === "payload" ? process.stdout : process.stderr;
+        if (textLines.length)
+            await write(out, textLines.map((l) => fieldForTerminal(out, l)).join("\n") + "\n");
+    }
+    return exitWith(exit);
+}
+export function okEnvelope(command, fields, next) {
+    return { schema: SCHEMA, command, ok: true, ...fields, next };
+}
+export function noCommandFix(example, platform = process.platform) {
+    return platform === "win32"
+        ? `${example} PowerShell removes a bare --: write '--' in quotes, or run promigence.cmd.`
+        : example;
+}
+export function usageError(message, fix) {
+    return new PromigenceError({ code: "usage", message, fix, exitCode: 2, docs: USAGE_DOCS });
+}
+export const USAGE_DOCS = `${ERRORS_DOCS_URL}#usage`;
+export function overMost(flag, given, most, mostText, page = false) {
+    process.stderr.write(page
+        ? `promigence: ${flag} ${given} is over the most one page holds (${mostText}); asking for ${mostText} (pass the answer's next_cursor with --cursor for the rest)\n`
+        : `promigence: ${flag} ${given} is over the most (${mostText}); asking for ${mostText}\n`);
+    return most;
+}
+const LOCAL_PATH_ERRORS = {
+    ENOENT: "it does not exist",
+    ENOTDIR: "a part of the path is not a directory",
+    EISDIR: "it is a directory",
+    EACCES: "permission denied",
+    EPERM: "operation not permitted",
+    EEXIST: "it already exists",
+    EROFS: "the file system is read-only",
+    ENOSPC: "the disk is full",
+    EDQUOT: "the disk quota is used up",
+    ENAMETOOLONG: "the name is too long",
+    ELOOP: "it is a symbolic link loop, or a link where a file was expected",
+};
+export function toPromigenceError(err) {
+    if (err instanceof PromigenceError)
+        return err;
+    const e = err;
+    if (typeof e?.code === "string" && typeof e.path === "string" && LOCAL_PATH_ERRORS[e.code] !== undefined) {
+        return new PromigenceError({
+            code: "usage",
+            message: `${e.path}: ${LOCAL_PATH_ERRORS[e.code]} (${e.code}${e.syscall ? ` on ${e.syscall}` : ""})`,
+            fix: "Check the local path: that its directory exists, that you can write there, and that it names a file where a file is expected.",
+            exitCode: 2,
+        });
+    }
+    return new PromigenceError({
+        code: "internal",
+        message: `internal error: ${e?.message ?? String(err)}`,
+        fix: "Not your fault. Re-run; if it repeats, report it with the command line and promigence --version.",
+        exitCode: 1,
+    });
+}
+export function errorEnvelope(command, err, next) {
+    return {
+        schema: SCHEMA,
+        command,
+        ok: false,
+        error: {
+            code: err.code, message: err.message, fix: err.fix, docs: err.docs || DOCS_URL, guide: err.guide,
+            ...(err.requestId === undefined ? {} : { request_id: err.requestId }),
+            ...(err.category === undefined ? {} : { category: err.category }),
+            ...(err.retryable === undefined ? {} : { retryable: err.retryable }),
+        },
+        next,
+    };
+}
+export function errorTextLines(command, err, exit, next) {
+    const lines = [
+        exit === 125 && err.cliExit !== 125
+            ? `promigence ${command}: ${err.message} (error ${err.code}, exit 125: Promigence's own failure, not the command's; without passthrough it is exit ${err.cliExit})`
+            : `promigence ${command}: ${err.message} (error ${err.code}, exit ${exit})`,
+        `  fix: ${err.fix}`,
+    ];
+    if (next.length)
+        lines.push(`  next: ${next.map((n) => n.cmd).join("  ·  ")}`);
+    if (err.requestId !== undefined)
+        lines.push(`  request: ${err.requestId}`);
+    return lines;
+}
+export function pickExit(codes) {
+    let best = 0;
+    let bestRank = EXIT_PRECEDENCE.indexOf(0);
+    for (const c of codes) {
+        const rank = EXIT_PRECEDENCE.indexOf(c);
+        if (rank === -1)
+            return c;
+        if (rank < bestRank) {
+            best = c;
+            bestRank = rank;
+        }
+    }
+    return best;
+}
+const BARE_SECONDS = /^\d+(?:\.\d+)?$/;
+const DURATION = /^(?:\d+(?:\.\d+)?(?:ms|s|m|h))+$/;
+const DURATION_PART = /(\d+(?:\.\d+)?)(ms|s|m|h)/g;
+export function parseDuration(value, flag) {
+    const v = value.trim();
+    if (BARE_SECONDS.test(v))
+        return Math.round(Number(v) * 1000);
+    if (!DURATION.test(v)) {
+        throw usageError(`${flag}: '${value}' is not a duration`, `Use a number with a unit: ${flag} 15m (also ms, s, h, or parts like 2m10s; a bare number is seconds).`);
+    }
+    let total = 0;
+    for (const [, n, unit] of v.matchAll(DURATION_PART)) {
+        total += Number(n) * (unit === "ms" ? 1 : unit === "s" ? 1000 : unit === "m" ? 60_000 : 3_600_000);
+    }
+    return Math.round(total);
+}
+export function parseCommandTimeout(value, flag) {
+    const ms = parseDuration(value, flag);
+    if (ms <= 0) {
+        throw usageError(`${flag}: a command timeout must be more than 0`, `Omit ${flag} for the default, or pass a bound: ${flag} 30m.`);
+    }
+    return ms;
+}
+export function parseCount(value, flag) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1) {
+        throw usageError(`${flag}: '${value}' is not a positive integer`, `Pass ${flag} N with N >= 1.`);
+    }
+    return n;
+}
+export function parseUsd(value, flag) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n < 0) {
+        throw usageError(`${flag}: '${value}' is not a dollar amount`, `Pass ${flag} USD, e.g. ${flag} 1 (dollars, not cents).`);
+    }
+    return n;
+}
+export const MAX_OUTPUT_CEILING = 32 * 1024 * 1024;
+export function parseMaxOutput(value, flag = "--max-output") {
+    const n = parseBytes(value, flag);
+    return n > MAX_OUTPUT_CEILING ? overMost(flag, value, MAX_OUTPUT_CEILING, "32m") : n;
+}
+export function parseBytes(value, flag) {
+    const m = /^(\d+)([km])?$/i.exec(value.trim());
+    if (!m)
+        throw usageError(`${flag}: '${value}' is not a byte count`, `Pass ${flag} 64k (k = KiB, m = MiB, or plain bytes).`);
+    const n = Number(m[1]);
+    const unit = (m[2] ?? "").toLowerCase();
+    return unit === "k" ? n * 1024 : unit === "m" ? n * 1024 * 1024 : n;
+}
+export const ms = (n) => (n === undefined ? "—" : `${Math.round(n)}ms`);
+export function forkLine(fork) {
+    if (!fork)
+        return "fork: (no timings yet)";
+    const p = (name, v) => v === undefined ? `${name} —` : `${name} p50 ${ms(v.p50)} p95 ${ms(v.p95)}${v.p99 === undefined ? "" : ` p99 ${ms(v.p99)}`}`;
+    return [
+        `fork n=${fork.n} (on our side)`,
+        p("queued", fork.queued_ms),
+        p("ready", fork.ready_ms),
+        p("e2e", fork.e2e_ms),
+    ].join(" · ");
+}
+export function totalsLine(t) {
+    if (!t)
+        return "totals: (none)";
+    const parts = Object.entries(t).filter(([, v]) => typeof v === "number" && v > 0).map(([k, v]) => `${k} ${v}`);
+    return `totals: ${parts.length ? parts.join(" · ") : "none"}`;
+}
+export function forkSummary(fork) {
+    if (!fork)
+        return {};
+    const out = {
+        n: fork.n,
+        warm_retries: fork.warm_retries,
+        first_attempt_success_pct: fork.first_attempt_success_pct,
+        final_success_pct: fork.final_success_pct,
+    };
+    for (const k of ["queued_ms", "ready_ms", "e2e_ms", "verify_each_ms"]) {
+        const v = fork[k];
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+export function reportSummaryLines(report) {
+    const lines = [
+        `run ${report.run_id}: ${report.state}` + (report.snapshot_id ? ` · snapshot ${report.snapshot_id}` : ""),
+        `  ${forkLine(report.fork)}`,
+        `  ${totalsLine(report.totals)}`,
+    ];
+    const g = gradeLine(report.grade);
+    if (g)
+        lines.push(`  ${g}`);
+    if (report.cost) {
+        const secs = report.cost.billable_seconds !== undefined ? ` · ${report.cost.billable_seconds} billable s` : "";
+        lines.push(`  cost: quoted ${usd(report.cost.quoted)} · charged ${usd(report.cost.charged)} · unbilled ${usd(report.cost.unbilled)}${secs}`);
+    }
+    for (const s of report.sandboxes ?? []) {
+        const graded = s.graded === true && (s.passed !== undefined || s.holdout_passed !== undefined);
+        if (s.outcome === "completed" && !s.failure && !graded)
+            continue;
+        const f = s.failure ? ` (${s.failure.category}/${s.failure.code})` : "";
+        const billed = s.billable_seconds !== undefined ? ` · ${s.billable_seconds}s ${usd(s.cost ?? 0)}` : "";
+        lines.push(`  ${s.sandbox_id}: ${s.outcome}${f}${graded ? ` · ${sandboxGrade(s)}` : ""}${billed}`);
+    }
+    return lines;
+}
+export function sandboxGrade(s) {
+    const verdict = (p, sc) => p === undefined ? "-" : `${p ? "pass" : "fail"}${sc === undefined ? "" : ` ${Number(sc.toFixed(4))}`}`;
+    const held = s.holdout_passed !== undefined || s.holdout_score !== undefined
+        ? ` · held-out ${verdict(s.holdout_passed, s.holdout_score)}`
+        : "";
+    return `tests ${verdict(s.passed, s.score)}${held}`;
+}
+export function gradeLine(g) {
+    if (!g)
+        return undefined;
+    const parts = [`graded ${g.graded}`, `tests ${g.pass_pct.toFixed(1)}%`];
+    if (g.holdout_pass_pct !== undefined)
+        parts.push(`held-out ${g.holdout_pass_pct.toFixed(1)}%`);
+    if (g.gap_pct !== undefined)
+        parts.push(`gap ${g.gap_pct.toFixed(1)} points`);
+    if (g.grader_failed)
+        parts.push(`grader_failed ${g.grader_failed}`);
+    return `grade: ${parts.join(" · ")}`;
+}