@lionrapid/cli 0.2.2 → 0.3.0

package/dist/cli.js

@@ -15,10 +15,12 @@ import { ConfigError, ApiKeyError, resolveApiKey, listCredentialServers, findCon
 import { ApiError, NetworkError, LionRapidApiClient } from './api-client.js';
 import { ExitCode, exitCodeForError } from './exit-codes.js';
 import { emitJson, errorEnvelope } from './output.js';
+import { defaultJobHistoryPath, recordJobs, } from './job-history.js';
 import { loadContext, loadOfflineContext } from './commands/context.js';
 import { runInit, fetchLocaleDefaults, detectLocalesOnDisk } from './commands/init.js';
 import { runLogin, runLogout, promptHidden, DEFAULT_SERVER } from './commands/login.js';
 import { runPush } from './commands/push.js';
+import { runStatus, explainStatus } from './commands/status.js';
 import { runPull } from './commands/pull.js';
 import { runValidate } from './commands/validate.js';
 import { runTypesGenerate, runTypesGenerateServer, runTypesCheck } from './commands/types.js';
@@ -58,11 +60,152 @@ function fail(err, ctx = {}) {
     else {
         console.error(`✖ ${err instanceof Error ? err.message : String(err)}`);
     }
+    // Anything still true despite the failure — e.g. batches that were accepted
+    // before it. Printed after the error so the cause reads first.
+    for (const note of ctx.notes ?? [])
+        console.error(note);
     if (ctx.json) {
         process.stdout.write(`${JSON.stringify(errorEnvelope(ctx.command ?? 'lionrapid', err), null, 2)}\n`);
     }
     process.exit(exitCodeForError(err));
 }
+/**
+ * Save this push's receipts to `~/.lionrapid/jobs.json`. Called on the success
+ * path AND from push's catch: a batch that was accepted before a later failure
+ * is still queued on the server, and its id is the only way to find out how it
+ * ended.
+ */
+function saveQueuedJobs(jobs, ctx) {
+    const pushedAt = new Date().toISOString();
+    const entries = jobs.map((job) => ({
+        id: job.id,
+        server: ctx.config.server,
+        project: ctx.config.project,
+        namespace: job.namespace,
+        locale: ctx.config.sourceLocale,
+        files: [job.file],
+        keys: job.keys,
+        pushedAt,
+        status: job.status,
+    }));
+    recordJobs(entries);
+    return entries;
+}
+/** `2026-08-05 14:21:07` in local time, or the raw value if it isn't a date. */
+function when(iso) {
+    if (!iso)
+        return '—';
+    const t = Date.parse(iso);
+    if (Number.isNaN(t))
+        return iso;
+    const d = new Date(t);
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+/** "128 key(s) from locales/en.json → app" — what a job is carrying. */
+function jobPayload(view) {
+    const h = view.history;
+    if (!h)
+        return 'pushed from another machine or checkout';
+    return `${h.keys} key(s) from ${h.files.join(', ')} → ${h.namespace}`;
+}
+/** The detail view for `lionrapid status <job-id>`. */
+function printJobDetail(view, out) {
+    const { icon, label, detail } = explainStatus(view);
+    out(`${icon} job ${view.id} — ${label}`);
+    out(`    what      ${jobPayload(view)}`);
+    if (view.history)
+        out(`    pushed    ${when(view.history.pushedAt)}`);
+    out(`    verdict   ${detail}`);
+    const job = view.job;
+    if (job?.deadLetterReason)
+        out(`    reason    ${job.deadLetterReason}`);
+    else if (view.history?.deadLetterReason)
+        out(`    reason    ${view.history.deadLetterReason}`);
+    const error = job?.error ?? view.history?.error;
+    if (error)
+        out(`    error     ${error}`);
+    if (job && job.retryCount > 0) {
+        out(`    attempts  ${job.retryCount} of ${job.maxRetries}`);
+        for (const e of job.retryErrors)
+            out(`              · ${e}`);
+    }
+    if (job?.nextRetryAt)
+        out(`    next try  ${when(job.nextRetryAt)}`);
+    if (job?.completedAt)
+        out(`    finished  ${when(job.completedAt)}`);
+    // Never let a remembered status read as a live one.
+    if (view.source === 'local') {
+        out(`    ⚠ last known on this machine${view.history?.checkedAt ? ` (checked ${when(view.history.checkedAt)})` : ''} — not confirmed with the server just now`);
+    }
+    else if (view.source === 'local-final') {
+        out('    · answered from this machine\'s record — the state is final, so no server call was needed');
+    }
+    if (label === 'dead-lettered') {
+        out('    next: fix the cause, then re-run `lionrapid push` — pushes upsert, so re-running is safe.');
+    }
+    else if (label === 'queued' || label === 'processing' || label === 'retrying') {
+        out(`    next: \`lionrapid status ${view.id}\` again in a moment.`);
+    }
+}
+/** The listing for bare `lionrapid status` / `lionrapid status list`. */
+function printJobList(res, out) {
+    out(`· ${res.jobs.length} job(s) pushed from this machine, newest first:`);
+    for (const view of res.jobs) {
+        const { icon, label } = explainStatus(view);
+        const h = view.history;
+        const where = h ? `${h.files.join(', ')} → ${h.namespace} · ${h.keys} key(s)` : '';
+        const stale = view.source === 'local' ? '  (last known)' : '';
+        out(`  ${icon} ${view.id}  ${label.padEnd(14)}${where} · ${when(h?.pushedAt)}${stale}`);
+    }
+    out('  next: `lionrapid status <job-id>` for the full story on one of them.');
+}
+/** Human rendering of a status result. Machine callers use `--json`. */
+function printStatus(res, out) {
+    if (res.notFound) {
+        out('✖ no such job — the server does not know that id, and this machine has no record of it.');
+        out('  Finished jobs are kept about an hour server-side; older ones survive only in');
+        out(`  ${res.historyPath}.`);
+        if (res.offline)
+            out(`  (the server could not be asked: ${res.offline})`);
+        return;
+    }
+    if (res.mode === 'job') {
+        const view = res.jobs[0];
+        if (view)
+            printJobDetail(view, out);
+        return;
+    }
+    if (res.jobs.length > 0) {
+        printJobList(res, out);
+        if (res.offline) {
+            out(`  ⚠ the server could not be reached (${res.offline}) — every line above is last known.`);
+        }
+        return;
+    }
+    // Nothing local: say so plainly, then show whatever the server will tell us.
+    out(`· no pushes recorded on this machine (${res.historyPath})`);
+    if (res.queue) {
+        const counts = Object.entries(res.queue.statusCounts)
+            .map(([k, v]) => `${v} ${k}`)
+            .join(', ');
+        out(`  server queue: depth ${res.queue.queueDepth}${counts ? ` · ${counts}` : ''} · worker ${res.queue.workerRunning ? 'running' : 'NOT running'}`);
+    }
+    if (res.deadLettered && res.deadLettered.length > 0) {
+        out(`  ✖ dead-letter queue: ${res.deadLettered.length} job(s) the backend gave up on:`);
+        for (const job of res.deadLettered) {
+            out(`      ${job.jobId}  ${job.deadLetterReason ?? job.error ?? 'no reason given'}`);
+        }
+    }
+    else if (res.deadLettered) {
+        out('  ✓ dead-letter queue is empty — nothing was dropped.');
+    }
+    if (res.queueUnavailable)
+        out(`  · queue view unavailable: ${res.queueUnavailable}`);
+    if (res.offline)
+        out(`  · the server could not be reached: ${res.offline}`);
+    out('  next: run `lionrapid push`, then `lionrapid status`.');
+}
 /**
  * One-line interactive prompt on stderr with a default. Non-TTY (CI, pipes)
  * never blocks — it returns the default immediately.
@@ -295,13 +438,19 @@ export function buildProgram() {
         .option('--json', 'emit the result as JSON on stdout (prose to stderr)')
         .option('-c, --config <path>', 'path to lionrapid.yml')
         .action(async (options) => {
+        // Receipts are collected as they arrive, not from the result, so a
+        // total failure (which rethrows) still saves the ids of the batches
+        // that DID reach the server.
+        const queued = [];
+        let ctx;
         try {
-            const ctx = loadContext({ config: options.config });
+            ctx = loadContext({ config: options.config });
             const res = await runPush(ctx.config, ctx.client, {
                 cwd: ctx.cwd,
                 target: options.target,
                 publish: options.publish,
                 dryRun: options.dryRun,
+                onJob: (job) => queued.push(job),
             });
             const out = options.json ? console.error : console.log;
             const tag = res.dryRun ? '[dry-run] would push' : '✓ pushed';
@@ -322,13 +471,70 @@ export function buildProgram() {
                 out('⚠ uploaded as drafts but not published — publishing needs an editor session token.\n' +
                     '  Set LIONRAPID_EDITOR_TOKEN, or publish in the dashboard.');
             }
+            // The whole point: "pushed" above is what we SENT. The server stores
+            // it in the background, so print what to watch and where it is saved.
+            if (res.jobs.length > 0) {
+                saveQueuedJobs(res.jobs, ctx);
+                out(`⧗ queued as ${res.jobs.length} background job(s) — the server stores these rows\n` +
+                    '  asynchronously, so "pushed" means sent, not yet stored:');
+                for (const job of res.jobs) {
+                    out(`    ${job.id}  ${job.file} (${job.keys} key(s))`);
+                }
+                out(`  next: lionrapid status ${res.jobs[0].id}`);
+                out(`  (saved to ${defaultJobHistoryPath()} — bare \`lionrapid status\` lists them)`);
+            }
+            else if (res.mode === 'source' && !res.dryRun && res.pushed > 0) {
+                // Accepted, but no ids came back — an older server or a proxy that
+                // ate the body. Say it rather than implying everything is confirmed.
+                out('⚠ the server accepted the batches but returned no job ids, so there is nothing\n' +
+                    '  to poll — `lionrapid validate` is the way to confirm these rows landed.');
+            }
             if (options.json)
                 emitJson('push', failed.length === 0, res);
             if (failed.length > 0)
                 process.exit(ExitCode.PARTIAL);
         }
         catch (err) {
-            fail(err, { json: options.json, command: 'push' });
+            // Batches accepted before the failure are still queued on the server.
+            // Save their ids and say so — the whole point is never being blind.
+            const notes = [];
+            if (ctx && queued.length > 0) {
+                saveQueuedJobs(queued, ctx);
+                notes.push(`  · ${queued.length} batch(es) had already been queued before this failure:`, ...queued.map((job) => `      ${job.id}  ${job.file} (${job.keys} key(s))`), '    Run `lionrapid status` to see how they ended.');
+            }
+            fail(err, { json: options.json, command: 'push', notes });
+        }
+    });
+    program
+        .command('status')
+        .argument('[job-id]', 'a job id from `push` (omit, or pass "list", for every recorded job)')
+        .description('Show what the server actually did with the strings `push` queued')
+        .option('--json', 'emit the result as JSON on stdout (prose to stderr)')
+        .option('-c, --config <path>', 'path to lionrapid.yml')
+        .action(async (jobId, options) => {
+        try {
+            // `status` must answer from anywhere: run outside a project, or with no
+            // saved key, it falls back to the on-disk history instead of failing.
+            let ctx;
+            try {
+                ctx = loadContext({ config: options.config });
+            }
+            catch {
+                ctx = undefined;
+            }
+            const res = await runStatus({
+                jobId,
+                client: ctx?.client,
+                server: ctx?.config.server,
+            });
+            printStatus(res, options.json ? console.error : console.log);
+            if (options.json)
+                emitJson('status', !res.notFound, res);
+            if (res.notFound)
+                process.exit(ExitCode.VALIDATION);
+        }
+        catch (err) {
+            fail(err, { json: options.json, command: 'status' });
         }
     });
     program

package/dist/commands/push.d.ts

@@ -5,11 +5,34 @@
  * rows via `sync/batch`; the server then queues machine translation for the
  * configured target locales.
  *
+ * `sync/batch` answers 202 Accepted — the rows are QUEUED, not yet stored. So
+ * every batch also yields job ids ({@link PushedJob}), which is the only thing
+ * that lets a caller tell "the backend stored this" from "the backend dropped
+ * it". Without them a push that dead-letters looks exactly like one that worked.
+ *
  * `--target <locale>` mode uploads an already-translated target file as drafts
  * via `targets/batch`, optionally publishing them with `--publish`.
  */
 import { type LionRapidConfig } from '../config.js';
 import type { LionRapidApiClient } from '../api-client.js';
+/**
+ * A sync job the server queued for one batch of this push.
+ *
+ * `sync/batch` answers 202 — accepted, not stored. This is the receipt that
+ * makes the difference observable: it says which file's keys are riding on
+ * which job, so `lionrapid status <id>` can later answer "stored" or "dropped".
+ * Target mode has no equivalent because `targets/batch` writes synchronously.
+ */
+export interface PushedJob {
+    id: string;
+    /** The file whose keys were in this batch. */
+    file: string;
+    namespace: string;
+    /** Keys in this batch (a large file is chunked into several jobs). */
+    keys: number;
+    /** Status the server reported at enqueue time (`pending`). */
+    status: string;
+}
 export interface PushOptions {
     cwd: string;
     /** Push an already-translated target locale instead of the source. */
@@ -18,6 +41,11 @@ export interface PushOptions {
     publish?: boolean;
     /** Parse + count what would be pushed, but make no network calls. */
     dryRun?: boolean;
+    /**
+     * Called as each batch is accepted. The caller persists these, so ids queued
+     * before a later total failure are not lost when `runPush` rethrows.
+     */
+    onJob?: (job: PushedJob) => void;
 }
 export interface PushFileResult {
     file: string;
@@ -28,8 +56,14 @@ export interface PushFileResult {
 }
 export interface PushResult {
     mode: 'source' | 'target';
+    /**
+     * Keys the CLI SENT. Not the number stored — the server queues them, so
+     * `jobs` is what says whether they landed.
+     */
     pushed: number;
     files: PushFileResult[];
+    /** Jobs the server queued for this push (source mode only; empty on a dry run). */
+    jobs: PushedJob[];
     /** True when `--publish` was requested but no editor token was available. */
     publishSkipped?: boolean;
     /** True when this was a dry run — nothing was sent to the server. */

package/dist/commands/push.js

@@ -5,6 +5,11 @@
  * rows via `sync/batch`; the server then queues machine translation for the
  * configured target locales.
  *
+ * `sync/batch` answers 202 Accepted — the rows are QUEUED, not yet stored. So
+ * every batch also yields job ids ({@link PushedJob}), which is the only thing
+ * that lets a caller tell "the backend stored this" from "the backend dropped
+ * it". Without them a push that dead-letters looks exactly like one that worked.
+ *
  * `--target <locale>` mode uploads an already-translated target file as drafts
  * via `targets/batch`, optionally publishing them with `--publish`.
  */
@@ -29,6 +34,7 @@ export async function runPush(config, client, opts) {
             'it in the dashboard before pushing target translations.');
     }
     const files = [];
+    const jobs = [];
     // Publishing (mark-ready) needs an editor token; if asked to publish without
     // one, we still upload the drafts and report that publishing was skipped.
     const canPublish = mode === 'target' && opts.publish === true && client.canPublish;
@@ -56,7 +62,22 @@ export async function runPush(config, client, opts) {
             if (!opts.dryRun) {
                 for (const batch of chunk(items, BATCH)) {
                     if (mode === 'source') {
-                        await client.syncBatch(config.sourceLocale, namespace, batch);
+                        const queued = await client.syncBatch(config.sourceLocale, namespace, batch);
+                        // Every id, not just job_id: a batch spanning several locales queues
+                        // one job each, and the ones after the first would otherwise be
+                        // unobservable. Reported as they happen so a later total failure
+                        // cannot take the earlier receipts down with it.
+                        for (const id of queued.job_ids) {
+                            const job = {
+                                id,
+                                file: relPath,
+                                namespace,
+                                keys: batch.length,
+                                status: queued.status || 'pending',
+                            };
+                            jobs.push(job);
+                            opts.onJob?.(job);
+                        }
                     }
                     else {
                         await client.targetsBatch(opts.target, namespace, batch);
@@ -90,6 +111,7 @@ export async function runPush(config, client, opts) {
         mode,
         pushed,
         files,
+        jobs,
         ...(publishSkipped ? { publishSkipped: true } : {}),
         ...(opts.dryRun ? { dryRun: true } : {}),
     };

package/dist/commands/status.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `status` — answer the question a 202 leaves open: did the backend actually
+ * store what `push` sent?
+ *
+ * `push` reports what the CLI put on the wire. The server queues that work and
+ * answers 202, so a clean push is still compatible with the job failing later.
+ * This command closes the loop three ways:
+ *
+ *   status <job-id>  → GET /sync/jobs/{id}, the server's own verdict
+ *   status [list]    → every job this machine pushed, newest first
+ *   (nothing local)  → fall back to queue-health + the dead-letter queue
+ *
+ * Everything degrades. With no network, the local history is still shown and
+ * every line is marked as last-known rather than current; with no config or API
+ * key (running from some other directory) the disk view still works.
+ */
+import { type LionRapidApiClient, type QueueHealth, type SyncJobStatus } from '../api-client.js';
+import { type JobHistoryEntry } from '../job-history.js';
+/** Where a line's status came from — the difference between "is" and "was". */
+export type StatusSource = 
+/** Fetched from the server just now. */
+'server'
+/** Read from `~/.lionrapid/jobs.json` — last known, not current. */
+ | 'local'
+/** Terminal on disk: last known IS current, the server cannot change it. */
+ | 'local-final';
+export interface JobView {
+    id: string;
+    status: string;
+    source: StatusSource;
+    /** What this machine recorded when it pushed (absent for a server-only job). */
+    history?: JobHistoryEntry;
+    /** The server's answer (absent when offline, or when answered from disk). */
+    job?: SyncJobStatus;
+}
+export interface StatusResult {
+    mode: 'job' | 'list';
+    jobs: JobView[];
+    /** Path of the history file the listing came from. */
+    historyPath: string;
+    /** Set when the server could not be reached — everything shown is last-known. */
+    offline?: string;
+    /** Queue fallback, only when there is nothing local to show. */
+    queue?: QueueHealth;
+    deadLettered?: SyncJobStatus[];
+    /** Why the queue fallback is missing (e.g. the key lacks `ops:queue`). */
+    queueUnavailable?: string;
+    /** `status <id>`: the id is known neither to the server nor to this machine. */
+    notFound?: boolean;
+}
+export interface StatusOptions {
+    /** A job id, `list`, or nothing (both of the latter mean "list"). */
+    jobId?: string;
+    /** Override the history file (tests; also keeps a push's receipts together). */
+    historyPath?: string;
+    /**
+     * The API client. Omitted when there is no config/API key here — the command
+     * then reports from disk only.
+     */
+    client?: LionRapidApiClient;
+    /** Limit the listing to jobs pushed to this server. */
+    server?: string;
+}
+/** True for the bare command and the explicit `list` form. */
+export declare function isListRequest(jobId?: string): boolean;
+export declare function runStatus(opts?: StatusOptions): Promise<StatusResult>;
+/**
+ * One-line verdict for a job state, in the terms the incident was about: were
+ * these rows stored or not. Shared by the detail and list renderings.
+ */
+export declare function explainStatus(view: JobView): {
+    icon: string;
+    label: string;
+    detail: string;
+};
+//# sourceMappingURL=status.d.ts.map

package/dist/commands/status.js

@@ -0,0 +1,221 @@
+/**
+ * `status` — answer the question a 202 leaves open: did the backend actually
+ * store what `push` sent?
+ *
+ * `push` reports what the CLI put on the wire. The server queues that work and
+ * answers 202, so a clean push is still compatible with the job failing later.
+ * This command closes the loop three ways:
+ *
+ *   status <job-id>  → GET /sync/jobs/{id}, the server's own verdict
+ *   status [list]    → every job this machine pushed, newest first
+ *   (nothing local)  → fall back to queue-health + the dead-letter queue
+ *
+ * Everything degrades. With no network, the local history is still shown and
+ * every line is marked as last-known rather than current; with no config or API
+ * key (running from some other directory) the disk view still works.
+ */
+import { ApiError, NetworkError, } from '../api-client.js';
+import { defaultJobHistoryPath, isTerminalJobStatus, readJobHistory, updateJobStatuses, } from '../job-history.js';
+import { mapLimit } from './context.js';
+/**
+ * How many stale (non-terminal) jobs a bare `status` re-checks against the
+ * server. A listing is a glance, not a poll loop: the newest unresolved jobs
+ * are the ones anyone is actually waiting on, and the rest still print from
+ * disk — labelled as such, never silently stale.
+ */
+const MAX_REFRESH = 20;
+const REFRESH_CONCURRENCY = 4;
+/** True for the bare command and the explicit `list` form. */
+export function isListRequest(jobId) {
+    return jobId === undefined || jobId === 'list';
+}
+export async function runStatus(opts = {}) {
+    const historyPath = opts.historyPath ?? defaultJobHistoryPath();
+    const history = readJobHistory(historyPath);
+    return isListRequest(opts.jobId)
+        ? listJobs(history, historyPath, opts)
+        : showJob(opts.jobId, history, historyPath, opts);
+}
+/** `status <job-id>` — the server's verdict, or the local receipt if it can't answer. */
+async function showJob(jobId, history, historyPath, opts) {
+    const recorded = history.find((e) => e.id === jobId);
+    const base = { mode: 'job', jobs: [], historyPath };
+    // Already final: the server cannot change its mind, and after ~1h it has
+    // forgotten the job entirely. Answer from the receipt and skip the call.
+    if (recorded && isTerminalJobStatus(recorded.status)) {
+        return { ...base, jobs: [localView(recorded)] };
+    }
+    if (!opts.client) {
+        // No client at all (no config or no key here). The receipt is all there is.
+        return recorded
+            ? { ...base, jobs: [localView(recorded)], offline: 'no API key or project config here' }
+            : { ...base, notFound: true, offline: 'no API key or project config here' };
+    }
+    try {
+        const job = await opts.client.getSyncJob(jobId);
+        if (recorded) {
+            persist(historyPath, [patchFor(job)]);
+        }
+        return { ...base, jobs: [{ id: jobId, status: job.status, source: 'server', history: recorded, job }] };
+    }
+    catch (err) {
+        // A 404 is an answer, not a failure: the id is unknown, or the job finished
+        // long enough ago that the server purged it (~1h retention). A job we
+        // already knew to be final never reaches here — it short-circuits above.
+        if (err instanceof ApiError && err.status === 404) {
+            if (recorded) {
+                persist(historyPath, [{ id: jobId, status: 'gone', checkedAt: new Date().toISOString() }]);
+                return { ...base, jobs: [{ ...localView({ ...recorded, status: 'gone' }), source: 'server' }] };
+            }
+            return { ...base, notFound: true };
+        }
+        if (!(err instanceof NetworkError))
+            throw err;
+        // Unreachable server: show the receipt, clearly marked as last-known.
+        if (!recorded)
+            return { ...base, notFound: true, offline: err.message };
+        return { ...base, jobs: [localView(recorded)], offline: err.message };
+    }
+}
+/** Bare `status` / `status list` — the local job log, refreshed where it matters. */
+async function listJobs(history, historyPath, opts) {
+    const scoped = opts.server ? history.filter((e) => e.server === opts.server) : history;
+    if (scoped.length === 0) {
+        // Nothing local — ask the server what its queue looks like instead of
+        // shrugging. This is also the honest answer for "I pushed from another
+        // machine / another checkout".
+        return { mode: 'list', jobs: [], historyPath, ...(await queueFallback(opts.client)) };
+    }
+    const stale = scoped.filter((e) => !isTerminalJobStatus(e.status)).slice(0, MAX_REFRESH);
+    const views = new Map();
+    let offline;
+    if (opts.client && stale.length > 0) {
+        const client = opts.client;
+        const patches = [];
+        const refreshed = await mapLimit(stale, REFRESH_CONCURRENCY, async (entry) => {
+            try {
+                return await client.getSyncJob(entry.id);
+            }
+            catch (err) {
+                if (err instanceof ApiError && err.status === 404)
+                    return 'gone';
+                if (err instanceof NetworkError) {
+                    offline ??= err.message;
+                    return undefined;
+                }
+                throw err;
+            }
+        });
+        refreshed.forEach((job, i) => {
+            const entry = stale[i];
+            if (job === undefined)
+                return;
+            if (job === 'gone') {
+                patches.push({ id: entry.id, status: 'gone', checkedAt: new Date().toISOString() });
+                views.set(entry.id, { id: entry.id, status: 'gone', source: 'server', history: entry });
+                return;
+            }
+            patches.push(patchFor(job));
+            views.set(entry.id, { id: entry.id, status: job.status, source: 'server', history: entry, job });
+        });
+        persist(historyPath, patches);
+    }
+    else if (!opts.client) {
+        offline = 'no API key or project config here';
+    }
+    const jobs = scoped.map((entry) => views.get(entry.id) ?? localView(entry));
+    return { mode: 'list', jobs, historyPath, ...(offline ? { offline } : {}) };
+}
+/** Queue-wide view for when this machine has no receipts to show. */
+async function queueFallback(client) {
+    if (!client)
+        return { queueUnavailable: 'no API key or project config here' };
+    try {
+        const [queue, deadLettered] = await Promise.all([
+            client.getQueueHealth(),
+            client.getDeadLetterQueue(),
+        ]);
+        return { queue, deadLettered };
+    }
+    catch (err) {
+        if (err instanceof NetworkError)
+            return { offline: err.message };
+        // 403 is the common one: queue introspection needs the `ops:queue` scope,
+        // which publishable pk_ keys do not carry.
+        if (err instanceof ApiError) {
+            return {
+                queueUnavailable: err.status === 403
+                    ? 'this API key may not read the queue (needs a master key)'
+                    : `server returned ${err.status}`,
+            };
+        }
+        throw err;
+    }
+}
+function localView(entry) {
+    return {
+        id: entry.id,
+        status: entry.status,
+        source: isTerminalJobStatus(entry.status) ? 'local-final' : 'local',
+        history: entry,
+    };
+}
+function patchFor(job) {
+    return {
+        id: job.jobId,
+        status: job.status,
+        checkedAt: new Date().toISOString(),
+        error: job.error,
+        deadLetterReason: job.deadLetterReason,
+    };
+}
+/** History writes are best-effort — a read-only home must not fail `status`. */
+function persist(historyPath, patches) {
+    if (patches.length > 0)
+        updateJobStatuses(patches, historyPath);
+}
+/**
+ * One-line verdict for a job state, in the terms the incident was about: were
+ * these rows stored or not. Shared by the detail and list renderings.
+ */
+export function explainStatus(view) {
+    const dead = view.job?.isDeadLettered === true || view.status === 'failed';
+    switch (true) {
+        case dead:
+            return {
+                icon: '✖',
+                label: 'dead-lettered',
+                detail: 'the backend gave up — these rows were NOT stored',
+            };
+        case view.status === 'completed':
+            return { icon: '✓', label: 'completed', detail: storedDetail(view) };
+        case view.status === 'retry_pending':
+            return {
+                icon: '⚠',
+                label: 'retrying',
+                detail: 'a previous attempt failed; the backend will try again',
+            };
+        case view.status === 'processing':
+            return { icon: '·', label: 'processing', detail: 'the backend is storing these rows now' };
+        case view.status === 'pending':
+            return { icon: '·', label: 'queued', detail: 'accepted, not stored yet' };
+        case view.status === 'gone':
+            return {
+                icon: '?',
+                label: 'gone',
+                detail: 'the server no longer has this job — finished jobs are kept ~1h',
+            };
+        default:
+            return { icon: '?', label: view.status || 'unknown', detail: '' };
+    }
+}
+/** "128 key(s) stored (5 added, 3 updated)" when the server reported counts. */
+function storedDetail(view) {
+    const result = view.job?.result;
+    const added = typeof result?.['keys_added'] === 'number' ? result['keys_added'] : undefined;
+    const updated = typeof result?.['keys_updated'] === 'number' ? result['keys_updated'] : undefined;
+    if (added === undefined && updated === undefined)
+        return 'the rows were stored';
+    return `stored — ${added ?? 0} added, ${updated ?? 0} updated`;
+}
+//# sourceMappingURL=status.js.map