@shardflux/cli 0.4.0 → 0.5.0

package/dist/main.js

@@ -1,19 +1,31 @@
 /**
- * `shard` entry: parse, build the SDK client from the environment, run the
- * command, report errors (stderr, with the API error code and request id) and
- * return the exit code. In-process and side-effect free apart from `io`, so
- * the whole CLI can be driven by tests; bin.ts wires it to the real process.
+ * `shard` entry: parse, build the SDK clients from the environment and the credentials file, run the command,
+ * report errors (stderr, with the API error code and request id) and return the exit code. In-process and side-effect
+ * free apart from `io` and the config directory, so the whole CLI can be driven by tests; `main()` wires it to the
+ * real process (bin.ts, and the `shardflux` npm bundle with its own identity for the version check).
+ *
+ * Credentials (0.5.0, README "Credentials file"):
+ * - project API key (workspace commands): SHARDFLUX_API_KEY, else the key `shard setup` saved for this API URL;
+ * - user session (account commands): SHARDFLUX_SESSION_TOKEN, else the session `shard auth login` saved. A rotation
+ *   (step-up, password change, TOTP change) is saved at once; a saved session the API rejects (401) is removed.
+ * Every credential the command loaded is redacted from what it prints on failure.
  */
-import { SDK_VERSION, Shardflux } from '@shardflux/sdk';
+import { hostname } from 'node:os';
+import { SDK_VERSION, Shardflux, ShardfluxAccount, isSessionToken } from '@shardflux/sdk';
 import { CLI_VERSION, parseCommandLine, resolveApiUrl, resolveWake, resolveWakeTimeout } from "./args.js";
-import { HANDLERS } from "./commands.js";
-import { AuthConfigError, EXIT, InterruptedError, UsageError, describeError, exitCodeFor, redact } from "./errors.js";
-import { errorText, json } from "./format.js";
+import { CredentialStore, configDir } from "./credentials.js";
+import { AuthConfigError, EXIT, ExecutionPendingError, InterruptedError, UsageError, describeError, exitCodeFor, ownHint, redact } from "./errors.js";
+import { errorText, feedbackCommand, json } from "./format.js";
+import { HANDLERS } from "./handlers.js";
 import { makeFetch } from "./http.js";
+import { Input } from "./input.js";
 import { TimingRecorder, timingJson, timingText } from "./timing.js";
+import { CLI_DISTRIBUTION, NOTICE_WAIT_MS, UpdateCheck, noticeOf, updateCheckDisabled, updateView } from "./update-check.js";
 const KEY_SHAPE = /^sfk_[a-z2-7]{16}_[A-Za-z0-9]+$/;
 // Printable (no C0 controls or DEL), as the API's AgentLabel pattern.
 const isLabel = (s) => s.length >= 1 && s.length <= 100 && ![...s].some((ch) => ch.charCodeAt(0) < 0x20 || ch.charCodeAt(0) === 0x7f);
+const LOGIN_HINT = 'shard auth login --email <you@example.com>';
+const STEP_UP_HINT = `confirm your password, then run the command again (valid 10 minutes): printf '%s\\n' "$PASSWORD" | shard auth step-up (add --code <totp> with two-factor authentication)`;
 /** A sleep that ends early when the signal aborts (so Ctrl-C never waits out a poll interval). */
 export function abortableSleep(signal) {
     return (ms) => new Promise((resolve) => {
@@ -28,7 +40,10 @@ export function abortableSleep(signal) {
         signal.addEventListener('abort', done, { once: true });
     });
 }
-function hintFor(info) {
+function reasonOf(info) {
+    return typeof info.details?.reason === 'string' ? info.details.reason : undefined;
+}
+function hintFor(info, cred, file) {
     if (info.code === 'timeout' && info.operation_id)
         return `the operation continues server side; keep waiting with: shard operations wait ${info.operation_id}`;
     if (info.code === 'operation_failed' && info.retryable) {
@@ -36,21 +51,177 @@ function hintFor(info) {
     }
     if (info.code === 'interrupted' && info.operation_id)
         return `keep waiting with: shard operations wait ${info.operation_id}`;
-    if (info.code === 'unauthenticated' && info.status === undefined)
-        return 'export SHARDFLUX_API_KEY=<project API key> (create one in the console under Project > API keys)';
     if (info.code === 'usage')
         return 'run "shard --help" or "shard <command> --help"';
     if (info.source === 'cell' && info.code === 'workspace_not_running')
         return 'open or resume the workspace first: shard workspaces open <key> --template <slug>';
-    return undefined;
+    if (info.status === 401 && info.code === 'unauthenticated') {
+        if (cred.sessionRejected && cred.sessionSource === 'file')
+            return `the saved session expired or was revoked (removed from ${file}); sign in again: shard auth login --email ${cred.email ?? '<you@example.com>'}`;
+        if (cred.sessionRejected && cred.sessionSource === 'env')
+            return `SHARDFLUX_SESSION_TOKEN expired or was revoked; sign in again (${LOGIN_HINT}) and unset it`;
+        if (cred.keyRejected && cred.keySource === 'file')
+            return `the API key saved in ${file} was revoked or expired; save a new one: shard setup --new-key`;
+        return undefined;
+    }
+    if (info.code === 'step_up_required')
+        return STEP_UP_HINT;
+    if (info.code === 'mfa_required')
+        return 'finish signing in with the code of your authenticator app: shard auth mfa --code <code>';
+    if (info.code === 'email_unverified')
+        return `verify your email first: shard auth verify-email '<link from the email>' (a new link: shard auth resend-verification)`;
+    if (info.code === 'conflict' && reasonOf(info) === 'subscription_exists')
+        return 'change plans in the billing portal: shard billing portal --open';
+    if (info.code === 'dependency_unavailable' && reasonOf(info) === 'billing_disabled')
+        return 'this API has no billing configured: plans cannot be bought here';
+    // File patches (contracts §26.2): what to do about each refusal. details.index is the 0-based edit (--old) index.
+    const reason = info.details?.reason;
+    const index = typeof info.details?.index === 'number' ? ` #${info.details.index + 1}` : '';
+    if (reason === 'revision_mismatch') {
+        const current = typeof info.details?.current_revision === 'string' ? info.details.current_revision : 'unknown';
+        return `the file changed since that revision (current revision: ${current}); read it again, then retry with --expected-revision ${current}`;
+    }
+    if (reason === 'edit_not_found')
+        return `--old${index} does not occur in the file (it must match exactly, including whitespace)`;
+    if (reason === 'edit_ambiguous')
+        return `--old${index} occurs more than once; include surrounding text to make it unique, or pass --replace-all`;
+    if (reason === 'edit_not_text')
+        return 'the file is not UTF-8 text; use files write for binary data';
+    if (reason === 'host_capacity')
+        return 'the workspace’s host has no room to run it right now; retry in a few seconds';
+    if (reason === 'host_feature_unavailable')
+        return hostFeatureHint(info.details?.feature);
+    return fileFirstHint(info);
+}
+/**
+ * 409 conflict host_feature_unavailable (contracts §26.7; 0.5.0): the workspace runs on a host agent that predates the
+ * call. Not retryable: it lasts until the workspace runs on an upgraded host (minutes to hours), so the hint names
+ * another way to do it now.
+ */
+function hostFeatureHint(feature) {
+    const later = 'it will once the workspace runs on an upgraded host (retrying now does not help)';
+    if (feature === 'file_search')
+        return `the workspace’s host does not support files search yet; ${later}. Search with a command instead: shard ws exec <id|key> -- grep -rn <pattern> <path>`;
+    if (feature === 'file_patch')
+        return `the workspace’s host does not support files patch yet; ${later}. Rewrite the file instead: shard files read <id|key> <path> --out F, edit F, then shard files write <id|key> <path> --from F`;
+    return `the workspace’s host does not support this call yet; ${later}`;
+}
+/** What an execution that ended failed or lost ran into (error.details.reason), where the reason alone says little. */
+const EXECUTION_CAUSES = {
+    exec_failed_to_start: 'the command could not start (is argv[0] installed and on PATH? shell syntax needs -- bash -lc "...")',
+    lease_expired: 'its host stopped reporting',
+    host_unreachable: 'its host stopped answering',
+    host_restarted: 'its host restarted',
+    tree_moved: 'the tree changed while it ran',
+    no_execution_host: 'no host had room to run it',
+    workspace_deleted: 'the workspace was deleted',
+};
+/** Hints for file-first workspaces (0.5.0; contracts §29.7, §29.8): the mode refusals, tree revisions and executions. */
+function fileFirstHint(info) {
+    const d = info.details ?? {};
+    const reason = d.reason;
+    if (info.code === 'execution_failed') {
+        const cause = typeof reason === 'string' ? EXECUTION_CAUSES[reason] : undefined;
+        return `${cause ? `${cause}; ` : ''}nothing was published (the tree is unchanged). Running it again needs a new --execution-id (omit it for a fresh one)${info.retryable ? '; a retry may succeed' : ''}.`;
+    }
+    switch (reason) {
+        case 'not_supported_for_mode':
+            if (d.mode === 'processful')
+                return 'executions and tree revisions exist only in file-first workspaces; open a new key with --mode file-first';
+            if (d.field === 'lifetime')
+                return 'a file-first workspace is persistent: leave out --lifetime session';
+            return 'this is a file-first workspace: there is no VM between executions, so suspend, resume, fork, reset, snapshot, save-as-template, changes, PTY and exec sessions do not exist. Run commands with: shard ws exec <ws> -- <command> (each runs as an execution in a fresh VM and keeps the files it changes under /home/user)';
+        case 'mode_mismatch': {
+            const has = d.mode === 'file_first' ? 'file-first' : typeof d.mode === 'string' ? d.mode : 'another';
+            const wants = d.requested_mode === 'file_first' ? 'file-first' : typeof d.requested_mode === 'string' ? d.requested_mode : 'differently moded';
+            return `this key already belongs to a ${has} workspace and a workspace’s mode never changes; use another key for a ${wants} workspace (or reopen this one without --mode)`;
+        }
+        case 'mode_not_available':
+            return 'this deployment does not offer file-first workspaces yet; leave out --mode file-first to open a processful workspace';
+        case 'layout_unsupported':
+            return d.mode === 'file_first' ? 'file-first workspaces run on layered template versions only; open a template version whose disk layouts include layered (shard templates get <slug> lists them)' : undefined;
+        case 'tree_revision_mismatch': {
+            const cur = d.current_tree_revision;
+            if (typeof cur !== 'number')
+                return 'the tree kept changing during the call; nothing changed. Retry';
+            return `the tree is at revision ${cur} now (another write or execution changed it); nothing changed. Read what you need again, then retry with --if-revision ${cur}`;
+        }
+        case 'outside_tree_root':
+            return `only paths under ${typeof d.tree_root === 'string' ? d.tree_root : '/home/user'} exist in a file-first workspace`;
+        case 'execution_in_progress': {
+            const id = typeof d.execution_id === 'string' ? d.execution_id : undefined;
+            return `another execution${id ? ` (${id})` : ''} holds the workspace and did not end within --wake-timeout; retry when it ended${id ? ` (follow it with: shard executions get <ws> ${id} --wait 10m)` : ''}`;
+        }
+        case 'execution_id_reused':
+            return 'this --execution-id was already used for a different request (the same id with the same request returns its recorded result); pass a new --execution-id';
+        case 'no_execution_host':
+            return 'no host had room to run the execution, also after retries with the same execution id; nothing ran. Retry later';
+        default:
+            return undefined;
+    }
+}
+const FEEDBACK_EMAIL = 'shardflux@heliosone.fi';
+/**
+ * Codes and reasons that are the expected flow rather than a problem: the caller's own input or credentials, a sign-in
+ * or step-up to finish, a wait that gave up while the work continues, a checkout nobody paid, and the refusals whose
+ * hint names the exact next step (a stale revision, an edit that does not match, a mode the workspace lacks).
+ */
+const NO_NUDGE_CODES = new Set(['usage', 'interrupted', 'unauthenticated', 'validation_failed', 'mfa_required', 'step_up_required', 'email_unverified', 'timeout', 'checkout_ended']);
+const NO_NUDGE_REASONS = new Set([
+    'revision_mismatch',
+    'tree_revision_mismatch',
+    'edit_not_found',
+    'edit_ambiguous',
+    'edit_not_text',
+    'execution_id_reused',
+    'execution_in_progress',
+    'exec_failed_to_start',
+    'mode_mismatch',
+    'not_supported_for_mode',
+    'outside_tree_root',
+    'layout_unsupported',
+    'host_feature_unavailable',
+    'subscription_exists',
+]);
+/**
+ * Whether a failure ends with the `feedback:` line (0.5.0+): every failure except the expected flow above (feedback
+ * needs a valid key too, so never a credential failure) and the failures of `shard feedback` itself.
+ */
+function nudges(info, command) {
+    if (command === undefined || command === 'feedback')
+        return false;
+    const reason = reasonOf(info);
+    return !NO_NUDGE_CODES.has(info.code) && !(reason !== undefined && NO_NUDGE_REASONS.has(reason));
+}
+/** `shard feedback` could not send: how to fix it, and the way to still reach the founder. */
+function feedbackHint(info, credentialHint) {
+    if (info.code === 'usage')
+        return 'run "shard feedback --help"';
+    if (info.code === 'interrupted')
+        return undefined;
+    if (info.code === 'unauthenticated')
+        return `${credentialHint ?? 'export SHARDFLUX_API_KEY=<project API key>'}; or email the feedback to ${FEEDBACK_EMAIL}`;
+    if (info.code === 'rate_limited') {
+        const s = info.details?.retry_after_seconds;
+        return `feedback is rate limited per API key; send it again ${typeof s === 'number' ? `in ${s} s` : 'later'}, or email it to ${FEEDBACK_EMAIL}`;
+    }
+    return `the feedback was not sent; email it to ${FEEDBACK_EMAIL} instead`;
 }
 export async function run(argv, io, opts = {}) {
     const signal = opts.signal ?? new AbortController().signal;
+    const distribution = opts.distribution ?? CLI_DISTRIBUTION;
     const rawKey = io.env.SHARDFLUX_API_KEY;
+    // Every credential this command loaded or received: redacted from anything printed on failure.
+    const secrets = [rawKey ?? '', io.env.SHARDFLUX_SESSION_TOKEN ?? ''].filter((s) => s.trim().length >= 8).map((s) => s.trim());
     const wantsJson = argv.slice(0, argv.includes('--') ? argv.indexOf('--') : argv.length).includes('--json');
+    const cred = { keySource: null, sessionSource: null, sessionRejected: false, keyRejected: false, email: null };
+    const store = new CredentialStore(configDir(io.env), (m) => void io.stderr.write(`${m}\n`));
     // Every traced SDK call of the command (open, waited lifecycle calls, waits, wakes) reports here; --timing prints it.
     const traces = new TimingRecorder();
     let showTiming = false;
+    let apiUrlForCleanup = null;
+    /** The command words once parsed (the error line's hint and feedback suggestion depend on them). */
+    let command = undefined;
     const report = (err) => {
         const code = exitCodeFor(err, signal.aborted);
         const info = describeError(err);
@@ -58,12 +229,30 @@ export async function run(argv, io, opts = {}) {
             info.code = 'interrupted';
             info.message = 'Interrupted.';
         }
-        info.message = redact(info.message, rawKey);
+        info.message = redact(info.message, ...secrets);
+        // A saved session the API no longer accepts is removed, so the next command says "not signed in" at once.
+        if (cred.sessionRejected && cred.sessionSource === 'file' && info.status === 401 && info.code === 'unauthenticated' && apiUrlForCleanup) {
+            try {
+                store.update(apiUrlForCleanup, (p) => {
+                    delete p.session;
+                });
+            }
+            catch {
+                // The hint still says to sign in again.
+            }
+        }
+        // An error that knows the command to continue with (an interrupted or still running execution) brings its own hint.
+        const own = ownHint(err) ?? ((err instanceof InterruptedError || err instanceof ExecutionPendingError) && err.hint ? err.hint : undefined);
+        const hint = command === 'feedback' ? feedbackHint(info, own ?? hintFor(info, cred, store.file)) : (own ?? hintFor(info, cred, store.file));
         // --timing on a failure: the failed call's timing (err.timing, else the last recorded), before the error; with
         // --json a `timing` field next to `error`.
         const timing = showTiming ? traces.forError(err) : null;
-        const text = wantsJson ? json(showTiming ? { error: info, timing: timingJson(timing) } : { error: info }) : `${timing ? timingText(timing) : ''}${errorText(info, hintFor(info))}`;
-        io.stderr.write(redact(text, rawKey));
+        // A failure suggests reporting it with `shard feedback` (text: a `feedback:` line; --json: a `feedback` field).
+        const feedback = nudges(info, command) ? feedbackCommand(info) : undefined;
+        const text = wantsJson
+            ? json({ error: info, ...(showTiming ? { timing: timingJson(timing) } : {}), ...(feedback ? { feedback } : {}) })
+            : `${timing ? timingText(timing) : ''}${errorText(info, hint, feedback)}`;
+        io.stderr.write(redact(text, ...secrets));
         return code;
     };
     let parsed;
@@ -81,16 +270,84 @@ export async function run(argv, io, opts = {}) {
         io.stdout.write(wantsJson ? json({ cli: CLI_VERSION, sdk: SDK_VERSION }) : `shard ${CLI_VERSION} (@shardflux/sdk ${SDK_VERSION})\n`);
         return EXIT.ok;
     }
+    command = parsed.command.path.join(' ');
     let ctx;
+    let updates = null;
     try {
         const apiUrl = resolveApiUrl(parsed.global.apiUrl, io.env.SHARDFLUX_API_URL);
+        apiUrlForCleanup = apiUrl;
         const agentLabel = parsed.global.agentLabel ?? io.env.SHARDFLUX_AGENT_LABEL ?? 'cli';
         if (!isLabel(agentLabel))
             throw new UsageError('--agent-label must be 1-100 printable characters');
         const wake = resolveWake(parsed.global.wake, io.env.SHARDFLUX_NO_WAKE);
         const wakeTimeoutMs = resolveWakeTimeout(parsed.global.wakeTimeout, io.env.SHARDFLUX_WAKE_TIMEOUT_MS);
         showTiming = parsed.values.timing === true;
+        const userAgent = `shard-cli/${CLI_VERSION} shardflux-sdk-ts/${SDK_VERSION}${distribution.package === CLI_DISTRIBUTION.package ? '' : ` ${distribution.package}/${distribution.version}`}`;
+        const base = makeFetch(io.env, fetch, signal);
+        // Notes which credential a 401 unauthenticated answered (the hint, and removing a dead saved session).
+        const watchedFetch = async (input, init) => {
+            const res = await base(input, init);
+            if (res.status === 401) {
+                const auth = new Headers(init?.headers).get('authorization') ?? '';
+                const kind = auth.startsWith('Bearer sfu_') ? 'session' : auth.startsWith('Bearer sfk_') ? 'key' : null;
+                if (kind) {
+                    try {
+                        const body = (await res.clone().json());
+                        if (body.error?.code === 'unauthenticated') {
+                            if (kind === 'session')
+                                cred.sessionRejected = true;
+                            else
+                                cred.keyRejected = true;
+                        }
+                    }
+                    catch {
+                        // Not the documented error body: nothing to note.
+                    }
+                }
+            }
+            return res;
+        };
+        const sleep = abortableSleep(signal);
+        const accountOptions = () => ({ baseUrl: apiUrl, fetch: watchedFetch, userAgent, sleep, versionCheck: false, onProgress: traces.listener });
+        let envSessionNoted = false;
+        /** Saves a rotated token of the session in use (the previous one no longer works). */
+        const rotated = (s) => {
+            secrets.push(s.token);
+            if (cred.sessionSource === 'env' && !envSessionNoted) {
+                // The variable cannot be updated from here, and printing the token would expose it: save it instead.
+                envSessionNoted = true;
+                const replaced = store.profile(apiUrl).session !== undefined;
+                store.update(apiUrl, (p) => {
+                    p.session = { token: s.token, expires_at: s.expiresAt || null, user: null, state: 'active' };
+                });
+                io.stderr.write(`note: the session was renewed; SHARDFLUX_SESSION_TOKEN no longer works. The new session is saved in ${store.file}${replaced ? ' (replacing the one saved there)' : ''}: unset SHARDFLUX_SESSION_TOKEN to use it.\n`);
+                return;
+            }
+            store.update(apiUrl, (p) => {
+                p.session = { ...(p.session ?? { user: null, state: 'active' }), token: s.token, expires_at: s.expiresAt || p.session?.expires_at || null };
+            });
+        };
+        /** The project API key: SHARDFLUX_API_KEY, else the key saved for this API URL. */
+        const apiKey = () => {
+            const env = rawKey?.trim();
+            if (env) {
+                cred.keySource = 'env';
+                if (!KEY_SHAPE.test(env))
+                    throw new AuthConfigError('SHARDFLUX_API_KEY is not a Shardflux project key (expected sfk_<key id>_<secret>).');
+                return { token: env, source: 'env' };
+            }
+            const saved = store.profile(apiUrl).api_key;
+            if (!saved) {
+                throw new AuthConfigError('SHARDFLUX_API_KEY is not set.', `sign in and save a key: ${LOGIN_HINT}, then shard setup (or export SHARDFLUX_API_KEY=<project API key>)`);
+            }
+            cred.keySource = 'file';
+            secrets.push(saved.token);
+            if (!KEY_SHAPE.test(saved.token))
+                throw new AuthConfigError(`The API key saved in ${store.file} is not a Shardflux project key.`, 'save a new one: shard setup --new-key');
+            return { token: saved.token, source: 'file', saved };
+        };
         let cloud;
+        let account;
         ctx = {
             io,
             json: parsed.global.json,
@@ -101,25 +358,106 @@ export async function run(argv, io, opts = {}) {
             signal,
             timing: showTiming,
             traces,
+            store,
+            input: new Input(io.stdin, io.stderr),
+            distribution,
+            hostname: () => {
+                try {
+                    return hostname();
+                }
+                catch {
+                    return 'unknown host';
+                }
+            },
             cloud() {
                 if (cloud)
                     return cloud;
-                const key = rawKey?.trim();
-                if (!key)
-                    throw new AuthConfigError('SHARDFLUX_API_KEY is not set.');
-                if (!KEY_SHAPE.test(key))
-                    throw new AuthConfigError('SHARDFLUX_API_KEY is not a Shardflux project key (expected sfk_<key id>_<secret>).');
+                const key = apiKey();
                 cloud = new Shardflux({
-                    apiKey: key,
+                    apiKey: key.token,
                     baseUrl: apiUrl,
-                    userAgent: `shard-cli/${CLI_VERSION} shardflux-sdk-ts/${SDK_VERSION}`,
-                    fetch: makeFetch(io.env, fetch, signal),
-                    sleep: abortableSleep(signal),
+                    userAgent,
+                    fetch: watchedFetch,
+                    sleep,
                     onProgress: traces.listener,
+                    versionCheck: false,
                 });
                 return cloud;
             },
+            apiKey,
+            account() {
+                if (account)
+                    return account;
+                const env = io.env.SHARDFLUX_SESSION_TOKEN?.trim();
+                let token;
+                if (env) {
+                    cred.sessionSource = 'env';
+                    if (!isSessionToken(env))
+                        throw new AuthConfigError('SHARDFLUX_SESSION_TOKEN is not a Shardflux session token (expected sfu_ and 43 characters).', `unset it, or sign in: ${LOGIN_HINT}`);
+                    token = env;
+                }
+                else {
+                    const saved = store.profile(apiUrl).session;
+                    if (!saved)
+                        throw new AuthConfigError(`Not signed in to ${apiUrl}.`, `sign in: ${LOGIN_HINT} (new here? shard auth register --email <you@example.com>)`);
+                    cred.sessionSource = 'file';
+                    cred.email = saved.user?.email ?? null;
+                    secrets.push(saved.token);
+                    if (!isSessionToken(saved.token))
+                        throw new AuthConfigError(`The session saved in ${store.file} is malformed.`, `sign in again: ${LOGIN_HINT}`);
+                    token = saved.token;
+                }
+                account = new ShardfluxAccount({ ...accountOptions(), sessionToken: token, onSessionToken: rotated });
+                return account;
+            },
+            sessionSource() {
+                if (io.env.SHARDFLUX_SESSION_TOKEN?.trim())
+                    return 'env';
+                return store.profile(apiUrl).session ? 'file' : null;
+            },
+            accountOptions,
+            saveSession(session, email) {
+                secrets.push(session.token);
+                const previous = store.profile(apiUrl);
+                const before = previous.session?.user;
+                // Another person: a different user id, or (a sign-in still waiting for its code) a different email.
+                const switched = before != null && ((session.user !== null && before.id !== session.user.id) || (email !== undefined && before.email.toLowerCase() !== email.toLowerCase()));
+                store.update(apiUrl, (p) => {
+                    p.session = session;
+                    if (switched) {
+                        // Another person's defaults and key must not follow the new user.
+                        delete p.organization_id;
+                        delete p.project_id;
+                        delete p.api_key;
+                    }
+                });
+                return { replaced: previous.session ?? null, switched };
+            },
+            addSecret(value) {
+                if (value.length >= 8)
+                    secrets.push(value);
+            },
+            async versionStatus(force) {
+                const check = new UpdateCheck({ dir: store.dir, apiUrl, distribution, fetch: base, userAgent });
+                if (!force && updateCheckDisabled(io.env)) {
+                    const cached = check.peek();
+                    return cached ? updateView(cached.status, cached.checkedAt) : null;
+                }
+                check.start(force);
+                const r = await check.result(5_000);
+                return r ? updateView(r.status, r.checkedAt) : null;
+            },
         };
+        // The update check runs next to the command (not for `version`, which reports it itself).
+        if (!updateCheckDisabled(io.env) && parsed.command.path[0] !== 'version') {
+            try {
+                updates = new UpdateCheck({ dir: store.dir, apiUrl, distribution, fetch: base, userAgent });
+                updates.start();
+            }
+            catch {
+                updates = null;
+            }
+        }
     }
     catch (err) {
         return report(err);
@@ -137,12 +475,42 @@ export async function run(argv, io, opts = {}) {
             signal.addEventListener('abort', onAbort, { once: true });
     });
     const outcome = await Promise.race([running, interrupted]);
+    let code;
     if ('interrupted' in outcome)
-        return report(new InterruptedError('Interrupted.'));
-    if ('err' in outcome)
-        return report(outcome.err);
-    // With --json the handler put the timing into its output; otherwise it follows the output, on stderr.
-    if (showTiming && !ctx.json && traces.last)
-        io.stderr.write(timingText(traces.last));
-    return outcome.code;
+        code = report(new InterruptedError('Interrupted.'));
+    else if ('err' in outcome)
+        code = report(outcome.err);
+    else {
+        // With --json the handler put the timing into its output; otherwise it follows the output, on stderr.
+        if (showTiming && !ctx.json && traces.last)
+            io.stderr.write(timingText(traces.last));
+        code = outcome.code;
+    }
+    // The update notice: after the output, never after Ctrl-C or a --json failure (stderr then holds only the error).
+    if (updates && code !== EXIT.interrupted && !(ctx.json && code !== EXIT.ok)) {
+        const r = await updates.result(NOTICE_WAIT_MS);
+        const notice = noticeOf(r?.status);
+        if (notice)
+            io.stderr.write(notice);
+    }
+    return code;
+}
+/**
+ * Runs `shard` as the process: argv, stdio and environment of this process. Ctrl-C aborts in-flight waits and
+ * streams cleanly (exit 130); a second Ctrl-C exits at once. Output is flushed before exiting (stdout/stderr pipes
+ * are asynchronous on macOS).
+ */
+export async function main(opts = {}) {
+    const controller = new AbortController();
+    let interrupts = 0;
+    process.on('SIGINT', () => {
+        interrupts += 1;
+        if (interrupts > 1)
+            process.exit(130);
+        controller.abort(new Error('interrupted'));
+    });
+    const flush = (stream) => new Promise((resolve) => stream.write('', () => resolve()));
+    const code = await run(process.argv.slice(2), { stdout: process.stdout, stderr: process.stderr, stdin: process.stdin, env: process.env }, { signal: controller.signal, ...(opts.distribution ? { distribution: opts.distribution } : {}) });
+    await Promise.all([flush(process.stdout), flush(process.stderr)]);
+    process.exit(code);
 }

package/dist/update-check.d.ts

@@ -0,0 +1,64 @@
+import type { ClientVersionStatus } from '@shardflux/sdk';
+export declare const UPDATE_CHECK_FILE = "update-check.json";
+export declare const CHECK_INTERVAL_MS: number;
+/** How long the end of a command waits for a check that is still running. */
+export declare const NOTICE_WAIT_MS = 300;
+/** What runs the CLI: `@shardflux/cli` itself, or a package that embeds it (the `shardflux` bundle). */
+export interface Distribution {
+    package: string;
+    version: string;
+}
+export declare const CLI_DISTRIBUTION: Distribution;
+interface CacheEntry {
+    checked_at: string;
+    latest: string | null;
+    minimum_supported: string | null;
+    upgrade_command: string | null;
+    release_notes_url: string | null;
+}
+/** The `update` object of `shard version --json`. */
+export interface UpdateView {
+    package: string;
+    current: string;
+    status: ClientVersionStatus['status'];
+    latest: string | null;
+    minimum_supported: string | null;
+    upgrade_command: string | null;
+    /** When the API was last asked (null: never, from this config directory). */
+    checked_at: string | null;
+}
+export declare function updateCheckDisabled(env: Record<string, string | undefined>): boolean;
+/** The status the cached answer gives this distribution (the same rules as the SDK; no request). */
+export declare function statusFromEntry(entry: Pick<CacheEntry, 'latest' | 'minimum_supported' | 'upgrade_command' | 'release_notes_url'> | null, d: Distribution): ClientVersionStatus;
+export declare function updateView(s: ClientVersionStatus, checkedAt: string | null): UpdateView;
+export interface UpdateCheckOptions {
+    dir: string;
+    apiUrl: string;
+    distribution: Distribution;
+    fetch: typeof fetch;
+    userAgent: string;
+    now?: () => number;
+}
+/**
+ * One command's check: `start()` returns at once (a fresh cache answers without a request); `result(waitMs)` is the
+ * status, or null when the request has not finished within `waitMs`.
+ */
+export declare class UpdateCheck {
+    #private;
+    constructor(opts: UpdateCheckOptions);
+    /** The cached answer, whatever its age (no request). */
+    peek(): {
+        status: ClientVersionStatus;
+        checkedAt: string | null;
+    } | null;
+    /** Starts the check: from the cache when it is younger than 24 h (unless `force`), else one request. */
+    start(force?: boolean): void;
+    /** The status (with when it was fetched), or null when not started or still running after `waitMs`. */
+    result(waitMs: number): Promise<{
+        status: ClientVersionStatus;
+        checkedAt: string | null;
+    } | null>;
+}
+/** The one-line notice for stderr, or null when there is nothing to say. */
+export declare function noticeOf(s: ClientVersionStatus | undefined | null): string | null;
+export {};