@smithers-orchestrator/cli 0.16.0

package/src/tui/components/RunsList.jsx

@@ -0,0 +1,184 @@
+// @ts-nocheck
+import React, { useEffect, useState } from "react";
+import { useKeyboard } from "@opentui/react";
+import { formatAge } from "../../format.js";
+import { basename } from "node:path";
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+
+/**
+ * @param {{ adapter: SmithersDb; focused: boolean; onChange: (runId: string) => void; onSubmit: (runId: string) => void; }} value
+ */
+export function RunsList({ adapter, focused, onChange, onSubmit, }) {
+    const [runs, setRuns] = useState([]);
+    const [selectedIndex, setSelectedIndex] = useState(0);
+    const [filterMode, setFilterMode] = useState("all");
+    const [selectedRunStats, setSelectedRunStats] = useState(null);
+    useEffect(() => {
+        let mounted = true;
+        async function pollRuns() {
+            if (!mounted)
+                return;
+            try {
+                const fetchedRuns = await adapter.listRuns(20, filterMode === "pending" ? "waiting-approval" : undefined);
+                if (mounted) {
+                    setRuns(fetchedRuns);
+                    if (fetchedRuns.length > 0 && selectedIndex === 0) {
+                        // Auto select the first run initially if nothing was selected
+                        // But we don't want to call onSelect constantly, so we'll just let the list render.
+                    }
+                }
+            }
+            catch (err) { }
+            if (mounted)
+                setTimeout(pollRuns, 1000);
+        }
+        pollRuns();
+        return () => {
+            mounted = false;
+        };
+    }, [adapter, selectedIndex, filterMode]);
+    useEffect(() => {
+        if (runs.length > 0) {
+            onChange(runs[selectedIndex]?.runId ?? runs[0].runId);
+        }
+    }, [runs, selectedIndex, onChange]);
+    const selectedRun = runs[selectedIndex];
+    useEffect(() => {
+        let mounted = true;
+        if (!selectedRun) {
+            setSelectedRunStats(null);
+            return;
+        }
+        async function fetchStats() {
+            try {
+                const events = await adapter.listEvents(selectedRun.runId, -1, 10000);
+                const nodes = await adapter.listNodes(selectedRun.runId);
+                let tIn = 0, tOut = 0, tCache = 0;
+                for (const e of events) {
+                    if (e.type === "TokenUsageReported") {
+                        try {
+                            const p = JSON.parse(e.payloadJson);
+                            tIn += (p.inputTokens ?? 0);
+                            tOut += (p.outputTokens ?? 0);
+                            tCache += (p.cacheReadTokens ?? 0);
+                        }
+                        catch { }
+                    }
+                }
+                const sMs = selectedRun.startedAtMs || selectedRun.createdAtMs;
+                const durationMs = selectedRun.finishedAtMs && sMs
+                    ? selectedRun.finishedAtMs - sMs
+                    : sMs ? Date.now() - sMs : 0;
+                if (mounted) {
+                    setSelectedRunStats({
+                        tokensIn: tIn,
+                        tokensOut: tOut,
+                        tokensCache: tCache,
+                        durationMs,
+                        nodeCount: nodes.length,
+                    });
+                }
+            }
+            catch { }
+        }
+        fetchStats();
+        return () => { mounted = false; };
+    }, [adapter, selectedRun?.runId]);
+    useKeyboard((key) => {
+        if (!focused)
+            return;
+        if (key.name === "p" || key.name === "P") {
+            setFilterMode((m) => m === "all" ? "pending" : "all");
+            setSelectedIndex(0);
+            return;
+        }
+        if (runs[selectedIndex]) {
+            const runId = runs[selectedIndex].runId;
+            const status = runs[selectedIndex].status;
+            if (key.name === "enter" || key.name === "return") {
+                onSubmit(runId);
+                return;
+            }
+            if (key.name === "y" && status === "waiting-approval") {
+                Bun.spawn(["bun", "run", "src/index.js", "approve", runId], { stdout: "ignore", stderr: "ignore" }).unref();
+                return;
+            }
+            if (key.name === "d" && status === "waiting-approval") {
+                Bun.spawn(["bun", "run", "src/index.js", "deny", runId], { stdout: "ignore", stderr: "ignore" }).unref();
+                return;
+            }
+            if (key.name === "c" && (status === "running" || status === "waiting-timer")) {
+                Bun.spawn(["bun", "run", "src/index.js", "cancel", runId], { stdout: "ignore", stderr: "ignore" }).unref();
+                return;
+            }
+            if (key.name === "r" && (status === "failed" || status === "cancelled")) {
+                const path = runs[selectedIndex].workflowPath;
+                if (path) {
+                    Bun.spawn(["bun", "run", "src/index.js", "up", path, "--resume", "--runId", runId, "-d"], { stdout: "ignore", stderr: "ignore" }).unref();
+                }
+                return;
+            }
+        }
+        if (key.name === "k") {
+            Bun.spawn(["bun", "run", "src/index.js", "down"], { stdout: "ignore", stderr: "ignore" }).unref();
+            return;
+        }
+    });
+    const options = runs.map((run) => {
+        const workflowName = run.workflowName ?? (run.workflowPath ? basename(run.workflowPath) : "—");
+        const started = run.startedAtMs ? formatAge(run.startedAtMs) : run.createdAtMs ? formatAge(run.createdAtMs) : "—";
+        return {
+            name: `${workflowName} (${run.status})`,
+            description: `${run.runId.slice(-6)} - ${started}`,
+            value: run.runId,
+        };
+    });
+    if (runs.length === 0) {
+        return <text style={{ margin: 1 }}>No runs found.</text>;
+    }
+    let truncatedOutput = selectedRun?.errorJson;
+    if (!truncatedOutput) {
+        if (selectedRun?.status === "finished") {
+            truncatedOutput = "Run completed successfully without generic failure traces.\nPress [Enter] to inspect individual task payloads.";
+        }
+        else if (selectedRun?.status === "failed") {
+            truncatedOutput = "Workflow failed, but no global error stack trace was captured. Press [Enter] to inspect which individual node crashed.";
+        }
+        else {
+            truncatedOutput = "Workflow is still active or pending execution...";
+        }
+    }
+    if (truncatedOutput.length > 500) {
+        const head = truncatedOutput.substring(0, 200);
+        const tail = truncatedOutput.substring(truncatedOutput.length - 200);
+        truncatedOutput = `${head}\n\n... [ TRUNCATED ${truncatedOutput.length - 400} CHARACTERS ] ...\n\n${tail}`;
+    }
+    return (<box style={{ flexGrow: 1, width: "100%", height: "100%", flexDirection: "row" }}>
+      {/* Left List */}
+      <box style={{ width: 40, height: "100%", borderRight: true, borderColor: "#34d399", flexDirection: "column" }}>
+        <select style={{ width: "100%", height: "100%" }} options={options} focused={focused} onChange={(index) => {
+            setSelectedIndex(index);
+        }} textColor="#E2E8F0" selectedTextColor="#34d399" selectedBackgroundColor="#1f2937" descriptionColor="#9ca3af" selectedDescriptionColor="#a7f3d0" showScrollIndicator wrapSelection/>
+      </box>
+      
+      {/* Right Preview */}
+      <box style={{ flexGrow: 1, height: "100%", flexDirection: "column", paddingLeft: 1 }}>
+        <text style={{ color: "yellow" }}>State: {selectedRun?.status}</text>
+        {selectedRunStats && (<text style={{ color: "#a855f7", marginTop: 1 }}>
+              ⏱️ {(selectedRunStats.durationMs / 1000).toFixed(1)}s  |  🧩 {selectedRunStats.nodeCount} Tasks  |  🪙 {selectedRunStats.tokensIn} IN, {selectedRunStats.tokensOut} OUT, {selectedRunStats.tokensCache} CACHE
+            </text>)}
+        <text style={{ color: "gray", marginTop: 1 }}>--- Run Status / Error Summary ---</text>
+        <scrollbox style={{ flexGrow: 1, width: "100%", marginTop: 1 }}>
+          <text>{truncatedOutput}</text>
+        </scrollbox>
+
+        {/* Action Footer */}
+        <box style={{ width: "100%", height: 3, borderTop: true, borderColor: "gray", flexDirection: "column" }}>
+            <text style={{ color: "#93c5fd" }}>{filterMode === "all" ? "[P] Filter: Show Pending Approvals Only" : "[P] Filter: Show All Workflows"}</text>
+            {selectedRun?.status === "waiting-approval" && <text style={{ color: "green" }}>[Y] Approve  |  [D] Deny Human Task</text>}
+            {(selectedRun?.status === "running" || selectedRun?.status === "waiting-timer") && <text style={{ color: "red" }}>[C] Safely Cancel/Halt Workflow  |  [K] Kill All Active Workflows</text>}
+            {(selectedRun?.status === "failed" || selectedRun?.status === "cancelled") && <text style={{ color: "yellow" }}>[R] Resume from latest checkpoint</text>}
+        </box>
+      </box>
+    </box>);
+}

package/src/tui/components/RunsList.tsx

@@ -0,0 +1,7 @@
+import type { SmithersDb } from "@smithers-orchestrator/db/adapter";
+export declare function RunsList({ adapter, focused, onChange, onSubmit, }: {
+    adapter: SmithersDb;
+    focused: boolean;
+    onChange: (runId: string) => void;
+    onSubmit: (runId: string) => void;
+}): import("react/jsx-runtime").JSX.Element;

package/src/tui/components/SqliteBrowser.jsx

@@ -0,0 +1,131 @@
+// @ts-nocheck
+import React, { useEffect, useState } from "react";
+import { useKeyboard } from "@opentui/react";
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+
+/**
+ * @param {{ adapter: SmithersDb; onBack: () => void; }} value
+ */
+export function SqliteBrowser({ adapter, onBack, }) {
+    const [tables, setTables] = useState([]);
+    const [selectedTableIdx, setSelectedTableIdx] = useState(0);
+    const [query, setQuery] = useState("");
+    const [results, setResults] = useState([]);
+    const [error, setError] = useState(null);
+    const [focusedPane, setFocusedPane] = useState("tables");
+    // Fetch tables on mount
+    useEffect(() => {
+        let mounted = true;
+        adapter.rawQuery("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'")
+            .then((res) => {
+            if (mounted) {
+                const names = res.map((r) => r.name).sort();
+                setTables(names);
+                if (names.length > 0) {
+                    setQuery(`SELECT * FROM ${names[0]} LIMIT 50;`);
+                }
+            }
+        })
+            .catch((err) => {
+            if (mounted)
+                setError(err.message);
+        });
+        return () => { mounted = false; };
+    }, [adapter]);
+    // Execute query whenever it changes
+    useEffect(() => {
+        let mounted = true;
+        if (!query.trim()) {
+            setResults([]);
+            return;
+        }
+        adapter.rawQuery(query)
+            .then((res) => {
+            if (mounted) {
+                setResults(res);
+                setError(null);
+            }
+        })
+            .catch((err) => {
+            if (mounted) {
+                setError(err.message);
+                setResults([]);
+            }
+        });
+        return () => { mounted = false; };
+    }, [adapter, query]);
+    useKeyboard((key) => {
+        if (key.name === "escape") {
+            if (focusedPane === "query") {
+                setFocusedPane("tables");
+            }
+            else {
+                onBack();
+            }
+            return;
+        }
+        if (key.name === "tab") {
+            setFocusedPane((p) => p === "tables" ? "query" : p === "query" ? "results" : "tables");
+            return;
+        }
+        if (focusedPane === "tables" && tables.length > 0) {
+            if (key.name === "down" || key.name === "j") {
+                const next = Math.min(tables.length - 1, selectedTableIdx + 1);
+                setSelectedTableIdx(next);
+                setQuery(`SELECT * FROM ${tables[next]} LIMIT 50;`);
+            }
+            if (key.name === "up" || key.name === "k") {
+                const prev = Math.max(0, selectedTableIdx - 1);
+                setSelectedTableIdx(prev);
+                setQuery(`SELECT * FROM ${tables[prev]} LIMIT 50;`);
+            }
+        }
+        if (focusedPane === "query") {
+            if (key.name === "backspace") {
+                setQuery((q) => q.slice(0, -1));
+                return;
+            }
+            if (key.name === "enter" || key.name === "return") {
+                setFocusedPane("results");
+                return;
+            }
+            if (!key.ctrl && !key.meta && key.sequence && key.sequence.length === 1 && key.name !== "up" && key.name !== "down" && key.name !== "left" && key.name !== "right") {
+                setQuery((q) => q + key.sequence);
+            }
+        }
+    });
+    const tableOptions = tables.map((t) => ({
+        name: t,
+        value: t,
+    }));
+    const resultText = error
+        ? `[!] Query Error:\n${error}`
+        : results.length === 0
+            ? "No results."
+            : JSON.stringify(results, null, 2);
+    return (<box style={{ flexGrow: 1, width: "100%", height: "100%", flexDirection: "row" }}>
+      {/* Left Pane: Tables List */}
+      <box style={{ width: 30, height: "100%", borderRight: true, borderColor: focusedPane === "tables" ? "#34d399" : "gray", flexDirection: "column" }}>
+        <text style={{ color: focusedPane === "tables" ? "white" : "gray", marginBottom: 1 }}> Tables </text>
+        <select style={{ width: "100%", flexGrow: 1 }} options={tableOptions} focused={focusedPane === "tables"} onChange={(idx) => {
+            setSelectedTableIdx(idx);
+            setQuery(`SELECT * FROM ${tables[idx]} LIMIT 50;`);
+        }} textColor="#E2E8F0" selectedTextColor="#34d399" selectedBackgroundColor="#1f2937"/>
+      </box>
+      
+      {/* Right Pane: Query & Results */}
+      <box style={{ flexGrow: 1, height: "100%", flexDirection: "column", paddingLeft: 1 }}>
+        <box style={{ width: "100%", height: 3, borderBottom: true, borderColor: focusedPane === "query" ? "#34d399" : "gray", flexDirection: "column" }}>
+          <text style={{ color: "yellow" }}> SQL Query: {focusedPane === "query" ? "(Press Enter to run)" : ""} </text>
+          {focusedPane === "query" ? (<text style={{ color: "white", marginTop: 1 }}>{"> "}{query}█</text>) : (<text style={{ color: "white", marginTop: 1 }}>{query}</text>)}
+        </box>
+        
+        <box style={{ flexGrow: 1, width: "100%", flexDirection: "column", marginTop: 1 }}>
+          <text style={{ color: "gray", marginBottom: 1 }}> Results ({results.length} rows) </text>
+          <scrollbox style={{ flexGrow: 1, width: "100%" }}>
+            <text style={{ color: error ? "red" : "#a7f3d0" }}>{resultText}</text>
+          </scrollbox>
+        </box>
+      </box>
+    </box>);
+}

package/src/tui/components/SqliteBrowser.tsx

@@ -0,0 +1,5 @@
+import type { SmithersDb } from "@smithers-orchestrator/db/adapter";
+export declare function SqliteBrowser({ adapter, onBack, }: {
+    adapter: SmithersDb;
+    onBack: () => void;
+}): import("react/jsx-runtime").JSX.Element;

package/src/tui/components/WorkflowLauncher.jsx

@@ -0,0 +1,63 @@
+// @ts-nocheck
+import React, { useEffect, useState } from "react";
+import { useKeyboard } from "@opentui/react";
+import { readdirSync } from "node:fs";
+/**
+ * @param {{ onClose: () => void }} value
+ */
+export function WorkflowLauncher({ onClose }) {
+    const [examples, setExamples] = useState([]);
+    const [selectedIndex, setSelectedIndex] = useState(0);
+    useEffect(() => {
+        try {
+            const files = readdirSync("examples").filter((f) => /\.(?:jsx?|tsx?)$/.test(f)).filter(f => !f.startsWith("_"));
+            setExamples(files);
+        }
+        catch {
+            setExamples([]);
+        }
+    }, []);
+    useKeyboard((key) => {
+        if (key.name === "escape" || (key.name === "c" && key.ctrl)) {
+            onClose();
+            return;
+        }
+        if (key.name === "down" || key.name === "j") {
+            setSelectedIndex((s) => Math.min(s + 1, Math.max(0, examples.length - 1)));
+        }
+        if (key.name === "up" || key.name === "k") {
+            setSelectedIndex((s) => Math.max(s - 1, 0));
+        }
+        if (key.name === "enter" || key.name === "return") {
+            if (examples[selectedIndex]) {
+                // spawn the workflow
+                const file = examples[selectedIndex];
+                try {
+                    const proc = Bun.spawn(["bun", "run", "src/index.js", "up", `examples/${file}`, "-d"], {
+                        stdin: "ignore",
+                        stdout: "ignore",
+                        stderr: "ignore",
+                    });
+                    proc.unref(); // allow the parent process (TUI) to exit independently
+                }
+                catch { }
+                onClose();
+            }
+        }
+    });
+    return (<box style={{
+            flexGrow: 1,
+            width: "100%",
+            height: "100%",
+            border: true,
+            borderColor: "yellow",
+            flexDirection: "column",
+        }} title="Launch Workflow [Esc to Close, Enter to Run]">
+      <text style={{ margin: 1, color: "gray" }}>Select an example to run in the background:</text>
+      {examples.length === 0 ? (<text style={{ margin: 1 }}>No examples found in ./examples</text>) : (<scrollbox style={{ width: "100%", height: "100%", flexDirection: "column", paddingLeft: 2 }}>
+          {examples.map((ex, i) => (<text key={ex} style={{ color: selectedIndex === i ? "green" : "white" }}>
+              {selectedIndex === i ? "▶ " : "  "}{ex}
+            </text>))}
+        </scrollbox>)}
+    </box>);
+}

package/src/tui/components/WorkflowLauncher.tsx

@@ -0,0 +1,3 @@
+export declare function WorkflowLauncher({ onClose }: {
+    onClose: () => void;
+}): import("react/jsx-runtime").JSX.Element;

package/src/util/CliErrorMapping.ts

@@ -0,0 +1,7 @@
+import type { CliExitCode } from "./CliExitCode.ts";
+
+export type CliErrorMapping = {
+    message: string;
+    hint: string;
+    exitCode: CliExitCode;
+};

package/src/util/CliExitCode.ts

@@ -0,0 +1,10 @@
+/**
+ * Uniform CLI exit codes for the devtools live-run commands.
+ *
+ * - 0   ok
+ * - 1   user error (bad flags, missing id, declined confirmation)
+ * - 2   server error (transport, backend, unexpected condition)
+ * - 3   declined (user aborted at an interactive prompt)
+ * - 130 sigint (ctrl-c during a watch/stream)
+ */
+export type CliExitCode = 0 | 1 | 2 | 3 | 130;

package/src/util/errorMessage.js

@@ -0,0 +1,212 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./CliErrorMapping.ts").CliErrorMapping} CliErrorMapping */
+// @smithers-type-exports-end
+
+import {
+    EXIT_USER_ERROR,
+    EXIT_SERVER_ERROR,
+} from "./exitCodes.js";
+
+/**
+ * Exhaustive map of every typed error code the four devtools RPCs may
+ * return. Each entry yields a user-friendly message plus an actionable
+ * hint and the uniform exit code to surface.
+ *
+ * Codes come from:
+ * - getDevToolsSnapshot / streamDevTools  (ticket 0010, 0011)
+ * - getNodeDiff                           (ticket 0012)
+ * - getNodeOutput                         (ticket 0012)
+ * - jumpToFrame                           (ticket 0013)
+ *
+ * Plus two transport-level codes used by the CLI itself when it cannot
+ * reach the server or the auth token is missing.
+ *
+ * @type {Readonly<Record<string, CliErrorMapping>>}
+ */
+export const CLI_ERROR_MESSAGES = Object.freeze({
+    // ----- Input validation (every Invalid* → exit 1) -----
+    InvalidRunId: {
+        message: "The run id is not in the expected shape.",
+        hint: "Run ids must match /^[a-z0-9_-]{1,64}$/. Check for typos or pick a run from `smithers ps`.",
+        exitCode: EXIT_USER_ERROR,
+    },
+    InvalidNodeId: {
+        message: "The node id is not in the expected shape.",
+        hint: "Node ids must match /^[a-zA-Z0-9:_-]{1,128}$/. Copy the id from `smithers tree` or `smithers node`.",
+        exitCode: EXIT_USER_ERROR,
+    },
+    InvalidIteration: {
+        message: "The iteration number is invalid.",
+        hint: "Iteration must be a non-negative 32-bit integer. Omit --iteration to use the latest.",
+        exitCode: EXIT_USER_ERROR,
+    },
+    InvalidFrameNo: {
+        message: "The frame number is invalid.",
+        hint: "Frame numbers must be non-negative integers. Omit --frame to use the latest frame.",
+        exitCode: EXIT_USER_ERROR,
+    },
+    InvalidDelta: {
+        message: "The server produced a delta the client cannot apply.",
+        hint: "This usually self-corrects; retry the command. If it persists, file a bug with the run id.",
+        exitCode: EXIT_SERVER_ERROR,
+    },
+
+    // ----- Lookups -----
+    RunNotFound: {
+        message: "No run with that id exists in the local database.",
+        hint: "Use `smithers ps` to list runs.",
+        exitCode: EXIT_USER_ERROR,
+    },
+    NodeNotFound: {
+        message: "That node does not exist in this run.",
+        hint: "Use `smithers tree <runId>` to see the available nodes.",
+        exitCode: EXIT_USER_ERROR,
+    },
+    IterationNotFound: {
+        message: "That iteration of the node does not exist.",
+        hint: "Omit --iteration to use the latest iteration, or pick one from `smithers node`.",
+        exitCode: EXIT_USER_ERROR,
+    },
+    AttemptNotFound: {
+        message: "That node has no attempts yet.",
+        hint: "Wait for the task to start, or rerun the workflow.",
+        exitCode: EXIT_USER_ERROR,
+    },
+    AttemptNotFinished: {
+        message: "The latest attempt is still running.",
+        hint: "Wait for the task to finish before asking for a diff, or jump to a frame before it started.",
+        exitCode: EXIT_USER_ERROR,
+    },
+    FrameOutOfRange: {
+        message: "That frame number is outside the range recorded for this run.",
+        hint: "Use `smithers tree <runId>` (without --frame) to see the latest frameNo.",
+        exitCode: EXIT_USER_ERROR,
+    },
+    SeqOutOfRange: {
+        message: "The requested sequence number is outside the live stream window.",
+        hint: "Reconnect without --from-seq to rebase from a fresh snapshot.",
+        exitCode: EXIT_USER_ERROR,
+    },
+
+    // ----- Stream lifecycle -----
+    BackpressureDisconnect: {
+        message: "The server disconnected the stream because the client fell behind.",
+        hint: "Re-run with a slower consumer (e.g. pipe to `less -R`) or drop --watch.",
+        exitCode: EXIT_SERVER_ERROR,
+    },
+
+    // ----- Auth -----
+    Unauthorized: {
+        message: "The request was rejected because credentials are missing or expired.",
+        hint: "Run `smithers login` and try again.",
+        exitCode: EXIT_SERVER_ERROR,
+    },
+
+    // ----- Rewind -----
+    ConfirmationRequired: {
+        message: "The server requires explicit confirmation for this rewind.",
+        hint: "Rerun the command with --yes to confirm.",
+        exitCode: EXIT_USER_ERROR,
+    },
+    Busy: {
+        message: "Another rewind is already in progress for this run.",
+        hint: "Wait for the current rewind to finish, then retry.",
+        exitCode: EXIT_SERVER_ERROR,
+    },
+    UnsupportedSandbox: {
+        message: "This run uses a sandbox type that cannot be rewound.",
+        hint: "Only jj-backed runs are supported. Start the run under jj to rewind it.",
+        exitCode: EXIT_SERVER_ERROR,
+    },
+    VcsError: {
+        message: "The version control operation failed.",
+        hint: "Inspect the workspace for a dirty working copy or missing commits and retry.",
+        exitCode: EXIT_SERVER_ERROR,
+    },
+    RewindFailed: {
+        message: "The rewind did not complete successfully.",
+        hint: "Check `smithers why <runId>` for details and retry after addressing the cause.",
+        exitCode: EXIT_SERVER_ERROR,
+    },
+    RateLimited: {
+        message: "Too many rewind attempts in a short window.",
+        hint: "Wait a minute and try again, or lower the rewind frequency.",
+        exitCode: EXIT_SERVER_ERROR,
+    },
+    WorkingTreeDirty: {
+        message: "The working tree has uncommitted changes that block the diff.",
+        hint: "Commit or stash the changes (or run the command on a clean checkout) and retry.",
+        exitCode: EXIT_SERVER_ERROR,
+    },
+
+    // ----- Diff / output payload -----
+    DiffTooLarge: {
+        message: "The diff exceeds the payload budget and cannot be sent in full.",
+        hint: "Rerun with --stat for a summary only.",
+        exitCode: EXIT_SERVER_ERROR,
+    },
+    NodeHasNoOutput: {
+        message: "This node does not produce an output row.",
+        hint: "Only tasks with a registered output table expose --pretty output.",
+        exitCode: EXIT_USER_ERROR,
+    },
+    SchemaConversionError: {
+        message: "The server could not derive a schema for this output row.",
+        hint: "Use --json to print the raw row without schema ordering.",
+        exitCode: EXIT_SERVER_ERROR,
+    },
+    MalformedOutputRow: {
+        message: "The stored output row is not valid JSON.",
+        hint: "Inspect the row with `smithers node` and file a bug if it reproduces.",
+        exitCode: EXIT_SERVER_ERROR,
+    },
+    PayloadTooLarge: {
+        message: "The output row exceeds the payload budget.",
+        hint: "Use `--json | jq` to slice the row into smaller pieces, or inspect it via `smithers node`.",
+        exitCode: EXIT_SERVER_ERROR,
+    },
+
+    // ----- Transport / infra (not produced by route functions, but the
+    // boundary tests in the ticket reference them).
+    ServerUnreachable: {
+        message: "The smithers gateway is not reachable.",
+        hint: "Check SMITHERS_HOST and verify the gateway is running.",
+        exitCode: EXIT_SERVER_ERROR,
+    },
+    AuthExpired: {
+        message: "The authentication session has expired.",
+        hint: "Run `smithers login` to refresh credentials.",
+        exitCode: EXIT_SERVER_ERROR,
+    },
+});
+
+/**
+ * @param {string | undefined | null} code
+ * @param {string} [rawMessage]
+ * @returns {CliErrorMapping}
+ */
+export function getCliErrorMapping(code, rawMessage) {
+    if (code && Object.prototype.hasOwnProperty.call(CLI_ERROR_MESSAGES, code)) {
+        return CLI_ERROR_MESSAGES[code];
+    }
+    return {
+        message: rawMessage && rawMessage.length > 0
+            ? rawMessage
+            : (code ? `Unexpected error: ${code}` : "Unexpected error."),
+        hint: "If this persists, file a bug with the run id and the command that was run.",
+        exitCode: EXIT_SERVER_ERROR,
+    };
+}
+
+/**
+ * @param {string | undefined | null} code
+ * @param {string} [rawMessage]
+ * @returns {string}
+ */
+export function formatCliErrorForStderr(code, rawMessage) {
+    const mapping = getCliErrorMapping(code, rawMessage);
+    const heading = code
+        ? `error: ${code}: ${mapping.message}`
+        : `error: ${mapping.message}`;
+    return `${heading}\n  hint: ${mapping.hint}`;
+}

package/src/util/exitCodes.js

@@ -0,0 +1,18 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./CliExitCode.ts").CliExitCode} CliExitCode */
+// @smithers-type-exports-end
+
+/** Uniform CLI exit codes for the devtools live-run commands. */
+export const EXIT_OK = 0;
+export const EXIT_USER_ERROR = 1;
+export const EXIT_SERVER_ERROR = 2;
+export const EXIT_DECLINED = 3;
+export const EXIT_SIGINT = 130;
+
+export const CLI_EXIT_CODES = Object.freeze({
+    ok: EXIT_OK,
+    userError: EXIT_USER_ERROR,
+    serverError: EXIT_SERVER_ERROR,
+    declined: EXIT_DECLINED,
+    sigint: EXIT_SIGINT,
+});