@shardflux/cli 0.4.1 → 0.5.1

package/dist/credentials.d.ts

@@ -0,0 +1,77 @@
+import { UsageError } from './errors.js';
+export declare const CREDENTIALS_FILE = "credentials.json";
+export declare const FILE_FORMAT_VERSION = 1;
+export interface StoredUser {
+    id: string;
+    email: string;
+}
+/** A user session (`sfu_...`); `state` pending_mfa while `shard auth mfa` has not completed the sign-in. */
+export interface StoredSession {
+    token: string;
+    /** When the session ends at the latest (the API's absolute expiry), or null when unknown. */
+    expires_at: string | null;
+    /** Null while the sign-in waits for its second factor. */
+    user: StoredUser | null;
+    state: 'active' | 'pending_mfa';
+}
+/** A project API key (`sfk_...`) saved by `shard setup` or `shard api-keys create --save`. */
+export interface StoredApiKey {
+    token: string;
+    id: string;
+    key_id: string;
+    project_id: string;
+    name: string;
+}
+export interface Profile {
+    session?: StoredSession;
+    /** Default organization and project (`shard orgs use`, `shard projects use`, `shard setup`). */
+    organization_id?: string;
+    project_id?: string;
+    api_key?: StoredApiKey;
+}
+export interface CredentialsDoc {
+    version: 1;
+    profiles: Record<string, Profile>;
+}
+/** The credentials file is unreadable (not JSON, another format, or a newer version): exit 2, naming the file. */
+export declare class CredentialsFileError extends UsageError {
+    readonly file: string;
+    constructor(file: string, problem: string);
+}
+/**
+ * The configuration directory: $SHARDFLUX_CONFIG_DIR, else $XDG_CONFIG_HOME/shardflux, else %APPDATA%\shardflux on
+ * Windows, else ~/.config/shardflux (home: $HOME, else %USERPROFILE%, else the OS's).
+ */
+export declare function configDir(env: Record<string, string | undefined>, platform?: NodeJS.Platform): string;
+/** Creates the directory 0700 (and tightens an existing one that others can read: it holds credentials). */
+export declare function ensurePrivateDir(dir: string): void;
+/**
+ * Writes `text` to `file` atomically with mode 0600: a unique temp file in the same directory, fsync, rename over the
+ * target. The directory is created 0700 first.
+ */
+export declare function writePrivateFile(dir: string, file: string, text: string): void;
+/** Parses and checks a credentials document; returns the problem as text instead of throwing. */
+export declare function parseCredentials(text: string): {
+    doc: CredentialsDoc;
+} | {
+    problem: string;
+};
+/**
+ * The credentials file of one config directory. Reads are cached for the command; `update()` re-reads, applies the
+ * change and writes atomically. `warn` receives notes for stderr (a corrupt file moved aside, a file others can read).
+ */
+export declare class CredentialStore {
+    #private;
+    readonly dir: string;
+    readonly file: string;
+    constructor(dir: string, warn?: (message: string) => void);
+    /** The file's contents; an empty document when there is no file. Throws CredentialsFileError when it is unusable. */
+    read(): CredentialsDoc;
+    /** The profile of an API URL (a copy; empty when there is none). */
+    profile(apiUrl: string): Profile;
+    /**
+     * Changes one profile: `change` edits a copy (or returns a replacement); an empty result removes the profile. An
+     * unusable file is moved aside first (never overwritten), with a note. Returns the profile as written.
+     */
+    update(apiUrl: string, change: (p: Profile) => Profile | void): Profile;
+}

package/dist/credentials.js

@@ -0,0 +1,217 @@
+/**
+ * The credentials file (0.5.0+; README "Credentials file"). `shard auth login` saves the user session and
+ * `shard setup` (or `shard api-keys create --save`) a project API key, so an agent signs in once and every later
+ * command finds its credentials. Environment variables still win: SHARDFLUX_API_KEY over the saved key,
+ * SHARDFLUX_SESSION_TOKEN over the saved session.
+ *
+ *   <config dir>/credentials.json   {"version":1,"profiles":{"<API URL>":{"session":{...},"organization_id",
+ *                                    "project_id","api_key":{...}}}}
+ *
+ * Config dir: $SHARDFLUX_CONFIG_DIR, else $XDG_CONFIG_HOME/shardflux, else %APPDATA%\shardflux (Windows), else
+ * ~/.config/shardflux. The directory is created 0700 and files are written 0600, atomically (a temp file in the same
+ * directory, fsync, rename), so a crash never leaves half a file and other users never see a secret. One profile per
+ * API URL (the normalized `--api-url`), so staging and production credentials never mix.
+ *
+ * A file that is not valid JSON, or not this format, is never silently replaced: reading it is a usage error naming
+ * the file; a command that writes credentials moves it aside first (credentials.json.corrupt-<time>) and says so.
+ * Synchronous on purpose: a few hundred bytes, read once per command, and `ctx.cloud()` resolves synchronously.
+ */
+import { randomBytes } from 'node:crypto';
+import { chmodSync, closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, win32 } from 'node:path';
+import { UsageError } from "./errors.js";
+export const CREDENTIALS_FILE = 'credentials.json';
+export const FILE_FORMAT_VERSION = 1;
+/** The credentials file is unreadable (not JSON, another format, or a newer version): exit 2, naming the file. */
+export class CredentialsFileError extends UsageError {
+    file;
+    constructor(file, problem) {
+        super(`${file} is not a usable shard credentials file (${problem}). Fix or remove it; "shard auth login" moves it aside and starts a new one.`);
+        this.file = file;
+    }
+}
+const TRUTHY_NONEMPTY = (v) => typeof v === 'string' && v.trim().length > 0;
+/**
+ * The configuration directory: $SHARDFLUX_CONFIG_DIR, else $XDG_CONFIG_HOME/shardflux, else %APPDATA%\shardflux on
+ * Windows, else ~/.config/shardflux (home: $HOME, else %USERPROFILE%, else the OS's).
+ */
+export function configDir(env, platform = process.platform) {
+    if (TRUTHY_NONEMPTY(env.SHARDFLUX_CONFIG_DIR))
+        return env.SHARDFLUX_CONFIG_DIR.trim();
+    const join_ = (...parts) => (platform === 'win32' ? win32.join(...parts) : join(...parts));
+    if (TRUTHY_NONEMPTY(env.XDG_CONFIG_HOME))
+        return join_(env.XDG_CONFIG_HOME.trim(), 'shardflux');
+    if (platform === 'win32' && TRUTHY_NONEMPTY(env.APPDATA))
+        return win32.join(env.APPDATA.trim(), 'shardflux');
+    const home = [env.HOME, env.USERPROFILE].find(TRUTHY_NONEMPTY) ?? homedir();
+    return join_(home, '.config', 'shardflux');
+}
+/** Creates the directory 0700 (and tightens an existing one that others can read: it holds credentials). */
+export function ensurePrivateDir(dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (process.platform === 'win32')
+        return;
+    const st = statSync(dir);
+    if ((st.mode & 0o077) !== 0)
+        chmodSync(dir, 0o700);
+}
+/**
+ * Writes `text` to `file` atomically with mode 0600: a unique temp file in the same directory, fsync, rename over the
+ * target. The directory is created 0700 first.
+ */
+export function writePrivateFile(dir, file, text) {
+    ensurePrivateDir(dir);
+    const tmp = join(dir, `.${file.split(/[\\/]/).pop() ?? 'file'}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`);
+    const fd = openSync(tmp, 'wx', 0o600);
+    try {
+        writeSync(fd, text);
+        fsyncSync(fd);
+    }
+    catch (err) {
+        closeSync(fd);
+        rmSync(tmp, { force: true });
+        throw err;
+    }
+    closeSync(fd);
+    try {
+        renameSync(tmp, file);
+    }
+    catch (err) {
+        rmSync(tmp, { force: true });
+        throw err;
+    }
+    if (process.platform !== 'win32')
+        chmodSync(file, 0o600);
+}
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isStr = (v) => typeof v === 'string';
+function checkProfile(url, p) {
+    if (!isObj(p))
+        return `profile "${url}" is not an object`;
+    if (p.organization_id !== undefined && !isStr(p.organization_id))
+        return `profile "${url}": organization_id is not a string`;
+    if (p.project_id !== undefined && !isStr(p.project_id))
+        return `profile "${url}": project_id is not a string`;
+    if (p.session !== undefined) {
+        const s = p.session;
+        if (!isObj(s) || !isStr(s.token) || !(s.expires_at === null || isStr(s.expires_at)) || !(s.state === 'active' || s.state === 'pending_mfa'))
+            return `profile "${url}": session is malformed`;
+        if (!(s.user === null || (isObj(s.user) && isStr(s.user.id) && isStr(s.user.email))))
+            return `profile "${url}": session.user is malformed`;
+    }
+    if (p.api_key !== undefined) {
+        const k = p.api_key;
+        if (!isObj(k) || !isStr(k.token) || !isStr(k.id) || !isStr(k.key_id) || !isStr(k.project_id) || !isStr(k.name))
+            return `profile "${url}": api_key is malformed`;
+    }
+    return null;
+}
+/** Parses and checks a credentials document; returns the problem as text instead of throwing. */
+export function parseCredentials(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        return { problem: `not valid JSON: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    if (!isObj(raw))
+        return { problem: 'not a JSON object' };
+    if (typeof raw.version === 'number' && raw.version > FILE_FORMAT_VERSION)
+        return { problem: `format version ${raw.version} is newer than this shard understands; update shard` };
+    if (raw.version !== FILE_FORMAT_VERSION)
+        return { problem: 'no "version": 1' };
+    if (!isObj(raw.profiles))
+        return { problem: '"profiles" is not an object' };
+    for (const [url, p] of Object.entries(raw.profiles)) {
+        const problem = checkProfile(url, p);
+        if (problem)
+            return { problem };
+    }
+    return { doc: raw };
+}
+const isEmpty = (p) => p.session === undefined && p.api_key === undefined && p.organization_id === undefined && p.project_id === undefined;
+/**
+ * The credentials file of one config directory. Reads are cached for the command; `update()` re-reads, applies the
+ * change and writes atomically. `warn` receives notes for stderr (a corrupt file moved aside, a file others can read).
+ */
+export class CredentialStore {
+    dir;
+    file;
+    #warn;
+    #cache = null;
+    #warnedMode = false;
+    constructor(dir, warn = () => undefined) {
+        this.dir = dir;
+        this.file = join(dir, CREDENTIALS_FILE);
+        this.#warn = warn;
+    }
+    /** The file's contents; an empty document when there is no file. Throws CredentialsFileError when it is unusable. */
+    read() {
+        if (this.#cache)
+            return this.#cache;
+        const loaded = this.#load();
+        if ('problem' in loaded)
+            throw new CredentialsFileError(this.file, loaded.problem);
+        this.#cache = loaded.doc;
+        return loaded.doc;
+    }
+    /** The profile of an API URL (a copy; empty when there is none). */
+    profile(apiUrl) {
+        return structuredClone(this.read().profiles[apiUrl] ?? {});
+    }
+    /**
+     * Changes one profile: `change` edits a copy (or returns a replacement); an empty result removes the profile. An
+     * unusable file is moved aside first (never overwritten), with a note. Returns the profile as written.
+     */
+    update(apiUrl, change) {
+        let loaded = this.#load();
+        if ('problem' in loaded) {
+            const backup = `${this.file}.corrupt-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+            renameSync(this.file, backup);
+            this.#warn(`note: ${this.file} was not usable (${loaded.problem}); moved it to ${backup} and started a new one`);
+            loaded = { doc: { version: FILE_FORMAT_VERSION, profiles: {} } };
+        }
+        const doc = loaded.doc;
+        const current = structuredClone(doc.profiles[apiUrl] ?? {});
+        const next = change(current) ?? current;
+        for (const k of Object.keys(next))
+            if (next[k] === undefined)
+                delete next[k];
+        if (isEmpty(next))
+            delete doc.profiles[apiUrl];
+        else
+            doc.profiles[apiUrl] = next;
+        writePrivateFile(this.dir, this.file, `${JSON.stringify(doc, null, 2)}\n`);
+        this.#cache = doc;
+        return structuredClone(next);
+    }
+    #load() {
+        let text;
+        try {
+            text = readFileSync(this.file, 'utf8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return { doc: { version: FILE_FORMAT_VERSION, profiles: {} } };
+            return { problem: `cannot read it: ${err.code ?? String(err)}` };
+        }
+        this.#checkMode();
+        return parseCredentials(text);
+    }
+    #checkMode() {
+        if (this.#warnedMode || process.platform === 'win32')
+            return;
+        try {
+            const mode = statSync(this.file).mode & 0o777;
+            if ((mode & 0o077) !== 0) {
+                this.#warnedMode = true;
+                this.#warn(`warning: ${this.file} can be read by other users (mode ${mode.toString(8).padStart(4, '0')}); restrict it: chmod 600 ${this.file}`);
+            }
+        }
+        catch {
+            // Unreadable metadata: the read itself reports it.
+        }
+    }
+}

package/dist/errors.d.ts

@@ -1,3 +1,4 @@
+import type { CheckoutStatus, ExecutionResult } from '@shardflux/sdk';
 export declare const EXIT: {
     readonly ok: 0;
     /** Any other failure: API refusal (conflict, quota, ...), network, protocol. */
@@ -6,31 +7,74 @@ export declare const EXIT: {
     readonly usage: 2;
     /** The workspace, operation or route does not exist in this project. */
     readonly notFound: 3;
-    /** Missing, malformed, revoked or insufficient API key. */
+    /** Missing, malformed, revoked or insufficient API key or session (also a sign-in that waits for its second factor). */
     readonly auth: 4;
     /** Waiting ran out of time (the operation continues server side), or a request timed out. */
     readonly timeout: 5;
-    /** The awaited operation ended `failed` or `canceled` (the error's `retryable` says whether a retry may succeed). */
+    /**
+     * The awaited operation ended `failed` or `canceled`, or a file-first execution ended `failed` or `lost` (the error's
+     * `retryable` says whether a retry may succeed); also a Checkout that `billing upgrade --wait` saw expire or get
+     * canceled.
+     */
     readonly operationFailed: 6;
     /** SIGINT (Ctrl-C). */
     readonly interrupted: 130;
 };
-export declare class UsageError extends Error {
+/** A failure `shard` reports with its own next step (`hint:` line); the API's errors get theirs from the code. */
+declare class HintedError extends Error {
+    readonly hint: string | undefined;
+    constructor(message: string, hint?: string);
+}
+export declare class UsageError extends HintedError {
+    name: string;
+}
+/** No usable credential: SHARDFLUX_API_KEY / the saved key, or the session, missing or malformed (never carries it). */
+export declare class AuthConfigError extends HintedError {
+    name: string;
+}
+/** A workspace key that no workspace of this project has (or another name that resolves to nothing). */
+export declare class NotFoundError extends HintedError {
     name: string;
 }
-/** SHARDFLUX_API_KEY missing or malformed (never carries the key). */
-export declare class AuthConfigError extends Error {
+/** `auth login` of a two-factor account without a code: the pending sign-in is saved; `shard auth mfa` completes it (exit 4). */
+export declare class MfaPendingError extends HintedError {
     name: string;
 }
-/** A workspace key that no workspace of this project has. */
-export declare class NotFoundError extends Error {
+/** `billing upgrade --wait`: the Checkout expired, was canceled or failed without activating a subscription (exit 6). */
+export declare class CheckoutEndedError extends Error {
     name: string;
+    readonly checkout: CheckoutStatus;
+    constructor(checkout: CheckoutStatus);
 }
-/** The user pressed Ctrl-C; `operationId` is set when a server-side operation keeps running. */
+/**
+ * The user pressed Ctrl-C; `operationId` is set when a server-side operation keeps running, `executionId` when a
+ * file-first execution does (it cannot be canceled), with `hint` naming the command that fetches its result.
+ */
 export declare class InterruptedError extends Error {
     name: string;
     readonly operationId: string | undefined;
-    constructor(message: string, operationId?: string);
+    readonly executionId: string | undefined;
+    readonly hint: string | undefined;
+    constructor(message: string, operationId?: string, more?: {
+        executionId?: string;
+        hint?: string;
+    });
+}
+/** A file-first execution that ended `failed` or `lost` (contracts §29.8): nothing was published. */
+export declare class ExecutionFailedError extends Error {
+    name: string;
+    readonly result: ExecutionResult;
+    constructor(result: ExecutionResult);
+}
+/**
+ * A file-first execution that is still queued or running when `shard executions get` returns (no --wait, or --wait ran
+ * out). It continues server side; `hint` names the command that waits for it.
+ */
+export declare class ExecutionPendingError extends Error {
+    name: string;
+    readonly result: ExecutionResult;
+    readonly hint: string;
+    constructor(message: string, result: ExecutionResult, hint: string);
 }
 export interface ErrorInfo {
     code: string;
@@ -43,9 +87,17 @@ export interface ErrorInfo {
     source?: 'api' | 'cell';
     last_state?: string;
     operation?: unknown;
+    /** A file-first execution the error is about (failed, lost, still running, or left running by Ctrl-C). */
+    execution_id?: string;
 }
-/** Removes anything shaped like a Shardflux API key (and the configured key itself) from text. */
-export declare function redact(text: string, key?: string): string;
+/**
+ * Removes anything shaped like a Shardflux API key or user session token from text, and each of the given secrets
+ * (the configured key, the saved session, ...) wherever it appears.
+ */
+export declare function redact(text: string, ...secrets: (string | null | undefined)[]): string;
+/** The `hint:` a CLI error carries itself, if any. */
+export declare function ownHint(err: unknown): string | undefined;
 export declare function describeError(err: unknown): ErrorInfo;
 /** Maps an error to the documented exit code. */
 export declare function exitCodeFor(err: unknown, interrupted?: boolean): number;
+export {};

package/dist/errors.js

@@ -3,7 +3,7 @@
  * stderr with the API's error code, message and request id; the process exit
  * code tells scripts what kind of failure it was (README "Exit codes").
  */
-import { OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TemplateBuildTimeoutError, TemplateFileError, TemplateUploadError } from '@shardflux/sdk';
+import { CheckoutTimeoutError, ExecStartError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TemplateBuildTimeoutError, TemplateFileError, TemplateUploadError } from '@shardflux/sdk';
 export const EXIT = {
     ok: 0,
     /** Any other failure: API refusal (conflict, quota, ...), network, protocol. */
@@ -12,54 +12,125 @@ export const EXIT = {
     usage: 2,
     /** The workspace, operation or route does not exist in this project. */
     notFound: 3,
-    /** Missing, malformed, revoked or insufficient API key. */
+    /** Missing, malformed, revoked or insufficient API key or session (also a sign-in that waits for its second factor). */
     auth: 4,
     /** Waiting ran out of time (the operation continues server side), or a request timed out. */
     timeout: 5,
-    /** The awaited operation ended `failed` or `canceled` (the error's `retryable` says whether a retry may succeed). */
+    /**
+     * The awaited operation ended `failed` or `canceled`, or a file-first execution ended `failed` or `lost` (the error's
+     * `retryable` says whether a retry may succeed); also a Checkout that `billing upgrade --wait` saw expire or get
+     * canceled.
+     */
     operationFailed: 6,
     /** SIGINT (Ctrl-C). */
     interrupted: 130,
 };
-export class UsageError extends Error {
+/** A failure `shard` reports with its own next step (`hint:` line); the API's errors get theirs from the code. */
+class HintedError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.hint = hint;
+    }
+}
+export class UsageError extends HintedError {
     name = 'UsageError';
 }
-/** SHARDFLUX_API_KEY missing or malformed (never carries the key). */
-export class AuthConfigError extends Error {
+/** No usable credential: SHARDFLUX_API_KEY / the saved key, or the session, missing or malformed (never carries it). */
+export class AuthConfigError extends HintedError {
     name = 'AuthConfigError';
 }
-/** A workspace key that no workspace of this project has. */
-export class NotFoundError extends Error {
+/** A workspace key that no workspace of this project has (or another name that resolves to nothing). */
+export class NotFoundError extends HintedError {
     name = 'NotFoundError';
 }
-/** The user pressed Ctrl-C; `operationId` is set when a server-side operation keeps running. */
+/** `auth login` of a two-factor account without a code: the pending sign-in is saved; `shard auth mfa` completes it (exit 4). */
+export class MfaPendingError extends HintedError {
+    name = 'MfaPendingError';
+}
+/** `billing upgrade --wait`: the Checkout expired, was canceled or failed without activating a subscription (exit 6). */
+export class CheckoutEndedError extends Error {
+    name = 'CheckoutEndedError';
+    checkout;
+    constructor(checkout) {
+        super(`Checkout ${checkout.id}${checkout.plan_key ? ` (${checkout.plan_key})` : ''} ended ${checkout.status} without activating a subscription.`);
+        this.checkout = checkout;
+    }
+}
+/**
+ * The user pressed Ctrl-C; `operationId` is set when a server-side operation keeps running, `executionId` when a
+ * file-first execution does (it cannot be canceled), with `hint` naming the command that fetches its result.
+ */
 export class InterruptedError extends Error {
     name = 'InterruptedError';
     operationId;
-    constructor(message, operationId) {
+    executionId;
+    hint;
+    constructor(message, operationId, more = {}) {
         super(message);
         this.operationId = operationId;
+        this.executionId = more.executionId;
+        this.hint = more.hint;
+    }
+}
+/** A file-first execution that ended `failed` or `lost` (contracts §29.8): nothing was published. */
+export class ExecutionFailedError extends Error {
+    name = 'ExecutionFailedError';
+    result;
+    constructor(result) {
+        const e = result.error;
+        super(`Execution ${result.executionId} ${result.state}${e?.message ? `: ${e.message}` : ''}`);
+        this.result = result;
+    }
+}
+/**
+ * A file-first execution that is still queued or running when `shard executions get` returns (no --wait, or --wait ran
+ * out). It continues server side; `hint` names the command that waits for it.
+ */
+export class ExecutionPendingError extends Error {
+    name = 'ExecutionPendingError';
+    result;
+    hint;
+    constructor(message, result, hint) {
+        super(message);
+        this.result = result;
+        this.hint = hint;
     }
 }
 const AUTH_CODES = new Set(['unauthenticated', 'invalid_credentials', 'token_invalid', 'forbidden', 'mfa_required', 'email_unverified', 'step_up_required', 'csrf_failed']);
 const KEY_PATTERN = /sfk_[A-Za-z0-9]{8,}_[A-Za-z0-9]+/g;
-/** Removes anything shaped like a Shardflux API key (and the configured key itself) from text. */
-export function redact(text, key) {
-    let out = text.replace(KEY_PATTERN, 'sfk_[redacted]');
-    if (key && key.length >= 8)
-        out = out.split(key).join('[redacted]');
+/** User session tokens (`sfu_` + 43 base64url characters), also cut short. */
+const SESSION_PATTERN = /sfu_[A-Za-z0-9_-]{16,}/g;
+/**
+ * Removes anything shaped like a Shardflux API key or user session token from text, and each of the given secrets
+ * (the configured key, the saved session, ...) wherever it appears.
+ */
+export function redact(text, ...secrets) {
+    let out = text.replace(KEY_PATTERN, 'sfk_[redacted]').replace(SESSION_PATTERN, 'sfu_[redacted]');
+    for (const s of secrets)
+        if (s && s.length >= 8)
+            out = out.split(s).join('[redacted]');
     return out;
 }
+/** The `hint:` a CLI error carries itself, if any. */
+export function ownHint(err) {
+    return err instanceof HintedError ? err.hint : undefined;
+}
 function isNamed(err, name) {
     return typeof err === 'object' && err !== null && err.name === name;
 }
 export function describeError(err) {
+    // A processful command that could not start (0.5.1; the SDK's ExecStartError): the workspace's reason, no HTTP status
+    // (the start itself was answered 201) and details.error, details.session_id.
+    if (err instanceof ExecStartError)
+        return { code: err.code, message: err.message, retryable: false, ...(err.details ? { details: err.details } : {}), source: err.source };
     if (err instanceof ShardfluxApiError) {
         return {
             code: err.code,
             message: err.message,
             status: err.status,
-            request_id: err.requestId,
+            // A refusal the SDK made itself (NotSupportedForModeError.local) has no request id.
+            ...(err.requestId ? { request_id: err.requestId } : {}),
             retryable: err.retryable,
             ...(err.operationId ? { operation_id: err.operationId } : {}),
             ...(err.details ? { details: err.details } : {}),
@@ -76,8 +147,22 @@ export function describeError(err) {
         const details = { ...(err.errorCode ? { error_code: err.errorCode } : {}), ...(typeof reason === 'string' ? { reason } : {}) };
         return { code: 'operation_failed', message: err.message, operation_id: err.operationId, retryable: err.retryable, ...(Object.keys(details).length ? { details } : {}), operation: err.operation };
     }
+    // File-first executions (0.5.0; contracts §29.8): failed or lost like a failed operation (details.reason says why;
+    // retryable: a new execution id may succeed), still running like a wait that gave up.
+    if (err instanceof ExecutionFailedError) {
+        const e = err.result.error;
+        const details = { ...(e?.details ?? {}), ...(e?.code ? { error_code: e.code } : {}), state: err.result.state };
+        return { code: 'execution_failed', message: err.message, execution_id: err.result.executionId, retryable: e?.retryable === true, details };
+    }
+    if (err instanceof ExecutionPendingError)
+        return { code: 'timeout', message: err.message, execution_id: err.result.executionId, last_state: err.result.state };
     if (err instanceof UsageError)
         return { code: 'usage', message: err.message };
+    if (err instanceof CheckoutTimeoutError) {
+        return { code: 'timeout', message: `${err.message}; the checkout stays open (pay at its URL, then check with: shard billing status)`, last_state: err.checkout.status, details: { checkout_id: err.checkout.id, status: err.checkout.status, url: err.checkout.url } };
+    }
+    if (err instanceof CheckoutEndedError)
+        return { code: 'checkout_ended', message: err.message, details: { checkout_id: err.checkout.id, status: err.checkout.status } };
     // Template builds (0.4.0): a template file that cannot be read or packed is a usage error; a wait that ran out names the build.
     if (err instanceof TemplateFileError)
         return { code: 'usage', message: err.message };
@@ -87,10 +172,13 @@ export function describeError(err) {
         return { code: 'upload_failed', message: err.message, ...(err.status ? { status: err.status } : {}), details: { sha256: err.sha256, ...(err.code ? { storage_code: err.code } : {}) } };
     if (err instanceof AuthConfigError)
         return { code: 'unauthenticated', message: err.message };
+    if (err instanceof MfaPendingError)
+        return { code: 'mfa_required', message: err.message };
     if (err instanceof NotFoundError)
         return { code: 'not_found', message: err.message };
-    if (err instanceof InterruptedError)
-        return { code: 'interrupted', message: err.message, ...(err.operationId ? { operation_id: err.operationId } : {}) };
+    if (err instanceof InterruptedError) {
+        return { code: 'interrupted', message: err.message, ...(err.operationId ? { operation_id: err.operationId } : {}), ...(err.executionId ? { execution_id: err.executionId } : {}) };
+    }
     if (err instanceof ShardfluxProtocolError)
         return { code: 'protocol_error', message: err.message, status: err.status };
     if (isNamed(err, 'TimeoutError'))
@@ -109,15 +197,20 @@ export function exitCodeFor(err, interrupted = false) {
         return EXIT.interrupted;
     if (err instanceof UsageError || err instanceof TemplateFileError)
         return EXIT.usage;
-    if (err instanceof AuthConfigError)
+    if (err instanceof AuthConfigError || err instanceof MfaPendingError)
         return EXIT.auth;
     if (err instanceof TemplateBuildTimeoutError)
         return EXIT.timeout;
     if (err instanceof NotFoundError)
         return EXIT.notFound;
-    if (err instanceof OperationTimeoutError || isNamed(err, 'TimeoutError'))
+    if (err instanceof OperationTimeoutError || err instanceof CheckoutTimeoutError || isNamed(err, 'TimeoutError'))
+        return EXIT.timeout;
+    if (err instanceof OperationFailedError || err instanceof ExecutionFailedError || err instanceof CheckoutEndedError)
+        return EXIT.operationFailed;
+    if (err instanceof ExecutionPendingError)
         return EXIT.timeout;
-    if (err instanceof OperationFailedError)
+    // A command that could not start exits 6 in both modes, as a failed execution does (0.5.1).
+    if (err instanceof ExecStartError)
         return EXIT.operationFailed;
     if (err instanceof ShardfluxApiError) {
         if (AUTH_CODES.has(err.code) || err.status === 401)