@lionrapid/cli 0.2.2 → 0.4.0

package/dist/cli.js

@@ -8,17 +8,21 @@
  */
 import { Command } from 'commander';
 import { readFileSync, realpathSync } from 'node:fs';
-import { basename, dirname, join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { createInterface } from 'node:readline';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { ConfigError, ApiKeyError, resolveApiKey, listCredentialServers, findConfigPath, loadConfig, } from './config.js';
+import { ConfigError, noTargetsNotice, ApiKeyError, keyCapability, resolveApiKey, listCredentialServers, findConfigPath, loadConfig, } from './config.js';
 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 { runInit, detectProject, fetchLocaleDefaults, detectLocalesOnDisk, ensureKey, summarizeSources, } from './commands/init.js';
+import { runLogin, runLogout, DEFAULT_SERVER } from './commands/login.js';
 import { runPush } from './commands/push.js';
+import { runWhoami } from './commands/whoami.js';
+import { runStatus, explainStatus } from './commands/status.js';
+import { formatLocal } from './time.js';
 import { runPull } from './commands/pull.js';
 import { runValidate } from './commands/validate.js';
 import { runTypesGenerate, runTypesGenerateServer, runTypesCheck } from './commands/types.js';
@@ -58,14 +62,197 @@ 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,
+        // The config's free-text label is gone; only a projectId the server
+        // confirmed is worth recording, and it may legitimately be absent.
+        ...(ctx.config.projectId ? { projectId: ctx.config.projectId } : {}),
+        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. Naive server timestamps are read as
+ * UTC — see `time.ts`; a plain `Date.parse` here made a job look like it had
+ * finished three hours before the push that queued it.
+ */
+const when = formatLocal;
+/** Where a key came from, in the terms a user would use to change it. */
+function describeKeySource(key) {
+    switch (key.source) {
+        case 'env':
+            return 'from LIONRAPID_API_KEY — overrides every saved scope';
+        case 'server-scoped':
+            return `saved for ${key.scope}`;
+        default:
+            return 'the default saved key';
+    }
+}
+/** "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') {
+        // This sentence has now been wrong twice, which is why it carries its own
+        // test. "Re-run push" broke when push became incremental (the lock records
+        // these rows as sent, so a plain re-push skips them), and "delete the
+        // lockfile" was a workaround for a file the user was never told they had.
+        // Both flags ask the SERVER what it holds, so neither trusts the lock.
+        out('    next: fix the cause, then `lionrapid push --backfill-missing` to send just the rows');
+        out('          the server is missing, or `lionrapid push --force` to resend everything.');
+        out('          A plain `push` would skip them — the lock recorded them as sent.');
+    }
+    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`.');
+}
+/** Interactive picker: list the scopes and take a number or an exact name. */
+async function askWhich(scopes) {
+    console.error('Which credential do you want to remove?');
+    scopes.forEach((s, i) => console.error(`  ${i + 1}) ${s}`));
+    const answer = (await askText('Number (or blank to cancel)', '')).trim();
+    if (!answer)
+        return undefined;
+    const index = Number(answer);
+    if (Number.isInteger(index) && index >= 1 && index <= scopes.length)
+        return scopes[index - 1];
+    return scopes.includes(answer) ? answer : undefined;
+}
+/**
+ * Thrown when a non-interactive run needs an answer nobody can give.
+ *
+ * Silently accepting a default is how `https://api.lionrapid.com` — a host
+ * with no DNS record — got written into configs by CI and by agents: the
+ * prompt never appeared, so nobody ever declined it. A scaffold that names
+ * what it needs is recoverable; one that invents a value is not.
+ */
+function requireInteractive(what, flag) {
+    throw new ConfigError(`Cannot ask for ${what} — this is not an interactive terminal.\n` +
+        `  Pass ${flag} explicitly (and set LIONRAPID_API_KEY if a key is needed).`);
+}
 /**
  * One-line interactive prompt on stderr with a default. Non-TTY (CI, pipes)
  * never blocks — it returns the default immediately.
+ *
+ * Callers that must not accept an unasked default check `process.stdin.isTTY`
+ * themselves and call {@link requireInteractive}; see `init`.
  */
 function askText(question, def) {
     if (!process.stdin.isTTY)
@@ -98,7 +285,6 @@ export function buildProgram() {
     program
         .command('init')
         .description('Scaffold a lionrapid.yml config in the current project')
-        .option('--project <id>', 'project id')
         .option('--server <url>', 'API server URL')
         .option('--source <locale>', 'source locale')
         .option('--targets <list>', 'comma-separated target locales')
@@ -122,10 +308,20 @@ export function buildProgram() {
             const known = existingServer ?? (loggedIn.length === 1 ? loggedIn[0] : undefined);
             // Only ask when there's genuinely nothing to go on. After a `login`,
             // `lionrapid init` should be a single silent command.
+            // Non-interactive with nothing to go on: refuse. `askText` would
+            // return DEFAULT_SERVER without ever showing the prompt, which is
+            // how a dead host reached a config file in the first place.
+            if (!options.server && !known && !process.stdin.isTTY) {
+                requireInteractive('a server URL', '--server');
+            }
             const server = options.server ?? known ?? (await askText('Server URL', DEFAULT_SERVER));
             // The project field is a local label (the API key selects the real
             // project) — the directory name is a better default than a question.
-            const project = options.project ?? basename(process.cwd());
+            let signedIn = false;
+            let projectId;
+            // The namespaces the scaffold will declare — the only places a
+            // project id can be read from before a config exists.
+            const res0Namespaces = () => detectProject(process.cwd()).files.map((f) => f.namespace ?? 'app');
             // Locale resolution ladder: explicit flags → the project's server
             // config → locales already present in the repo → static placeholders.
             // Every rung degrades quietly, so init still works fully offline.
@@ -133,20 +329,21 @@ export function buildProgram() {
             let targets = options.targets?.split(',').map((s) => s.trim());
             const notes = [];
             if (!source || !targets) {
-                let key = options.key;
-                if (!key) {
-                    try {
-                        key = resolveApiKey({ server });
-                    }
-                    catch {
-                        // no stored key for this server — prefill stays optional
-                    }
-                }
-                if (!key && process.stdin.isTTY) {
-                    key =
-                        (await promptHidden('API key to prefill locales (Enter to skip): ')).trim() ||
-                            undefined;
-                }
+                // ONE PASS: a key typed here is verified and SAVED, so the next
+                // command finds it. `init` used to prompt, use the key to prefill
+                // locales, and throw it away — you then typed the same key into
+                // `login` and ran `init` a second time.
+                const resolved = await ensureKey({
+                    server,
+                    key: options.key,
+                    isTTY: Boolean(process.stdin.isTTY),
+                    // Mirror login: an explicit --server scopes the entry, otherwise
+                    // it is the default "my LionRapid account key".
+                    scope: options.server ? 'server' : 'default',
+                });
+                const key = resolved.key;
+                if (resolved.signedIn)
+                    signedIn = true;
                 let serverStatus = 'no-key';
                 let serverTargets;
                 if (key) {
@@ -167,6 +364,30 @@ export function buildProgram() {
                         source ??= prefill.sourceLocale; // the source locale IS real
                     }
                 }
+                // Capture the project this key resolves to, so the mismatch guard
+                // has something to check on every later push. Best-effort: the
+                // field is undeclared server-side, and a brand-new project has no
+                // rows to read it from.
+                if (key) {
+                    const probe = new LionRapidApiClient({
+                        baseUrl: server,
+                        apiKey: key,
+                        retries: 0,
+                        timeoutMs: 5000,
+                    });
+                    for (const ns of new Set(res0Namespaces())) {
+                        try {
+                            const bundle = await probe.getNamespace(source ?? 'en', ns);
+                            if (bundle.projectId) {
+                                projectId = bundle.projectId;
+                                break;
+                            }
+                        }
+                        catch {
+                            // next namespace
+                        }
+                    }
+                }
                 const onDisk = detectLocalesOnDisk(process.cwd(), source ?? 'en');
                 if (serverStatus === 'ok' && serverTargets) {
                     notes.push(`locales from ${server}: ${source} → ${serverTargets.join(', ')}`);
@@ -203,7 +424,7 @@ export function buildProgram() {
                 }
             }
             const res = runInit(process.cwd(), {
-                project,
+                ...(projectId ? { projectId } : {}),
                 server,
                 sourceLocale: source,
                 targetLocales: targets,
@@ -223,6 +444,14 @@ export function buildProgram() {
             console.log(`  detected: ${res.detected.stacks.join(', ')}`);
             for (const note of notes)
                 console.log(`  ${note}`);
+            // A declared source with nothing behind it is the difference between
+            // `doctor: sources: 1 missing` being a puzzle and being obvious.
+            if (res.missingSources.length > 0) {
+                console.log(`  ⚠ ${res.missingSources.length} declared source(s) do not exist on disk:`);
+                for (const source of res.missingSources)
+                    console.log(`      ${source}`);
+                console.log('    Remove the stale entry from lionrapid.yml, or create the file.');
+            }
             if (res.conflicts.length > 0) {
                 // Never silently overwrite a value the developer set. Show the
                 // difference and let them resolve it in the file.
@@ -235,9 +464,23 @@ export function buildProgram() {
                 console.log('    Edit lionrapid.yml to resolve, or re-run with --force to take the');
                 console.log('    project values wholesale.');
             }
+            // A key typed during this run is now saved — say so, or the user has
+            // no way to know they do not need `login`.
+            if (signedIn)
+                console.log(`  ✓ signed in to ${server} — key saved for next time`);
+            if (projectId) {
+                console.log(`  ✓ project ${projectId} — push will refuse if a key resolves elsewhere`);
+            }
+            // Close on a fact rather than a promise: parse what was just
+            // declared, so "wrote lionrapid.yml" comes with what it will push.
+            const summary = summarizeSources(process.cwd(), res.detected.files);
+            if (summary.files > 0) {
+                const arrow = targets && targets.length > 0 ? `, ${source ?? 'en'} → ${targets.join(', ')}` : '';
+                console.log(`  ✓ ${summary.strings} string(s) across ${summary.namespaces} namespace(s) in ${summary.files} file(s)${arrow}`);
+            }
             const ready = res.conflicts.length === 0 && (targets?.length ?? 0) > 0;
             console.log(ready
-                ? '  next: `lionrapid doctor` to check the setup, then `lionrapid push`.'
+                ? '  next: `lionrapid push --dry-run`, then `lionrapid push`.'
                 : '  next: fix the above in lionrapid.yml, then run `lionrapid doctor`.');
         }
         catch (err) {
@@ -269,18 +512,84 @@ export function buildProgram() {
         }
     });
     program
-        .command('logout')
-        .description('Remove a saved API key from ~/.lionrapid/credentials')
-        .option('--server <url>', 'remove the key scoped to this server URL (default: "default")')
+        .command('whoami')
+        .description('Show which API key this directory would use, and every saved scope')
         .option('--json', 'emit the result as JSON on stdout (prose to stderr)')
+        .option('-c, --config <path>', 'path to lionrapid.yml')
         .action((options) => {
         try {
-            const res = runLogout({ server: options.server });
+            const res = runWhoami({ cwd: process.cwd(), config: options.config });
             const out = options.json ? console.error : console.log;
-            const what = res.scope === 'server' ? `key for ${options.server}` : 'default key';
-            out(res.removed ? `✓ removed ${what}` : `· no ${what} was saved`);
+            // Four combinations, and the two mixed ones are the interesting ones:
+            // a key with no server (run outside a project) is still a real answer,
+            // and a server with no key is the failure worth naming.
+            if (res.server && res.key) {
+                out(`this directory → ${res.server} → ${res.key.masked} (${describeKeySource(res.key)})`);
+                out(`  ${res.key.capability.summary}`);
+            }
+            else if (res.key) {
+                out(`${res.key.masked} (${describeKeySource(res.key)}) — but no server here yet`);
+            }
+            else if (res.server) {
+                out(`this directory → ${res.server}`);
+                out('✖ no key resolves for that server');
+            }
+            else {
+                out('✖ no server and no key resolve here');
+            }
+            if (res.problem)
+                for (const line of res.problem.split('\n'))
+                    out(`  ${line}`);
+            if (res.scopes.length > 0) {
+                out('');
+                out('saved scopes');
+                const width = Math.max(...res.scopes.map((s) => s.scope.length));
+                for (const s of res.scopes)
+                    out(`  · ${s.scope.padEnd(width)}  ${s.masked}`);
+            }
+            else {
+                out('');
+                out('saved scopes: none — run `lionrapid login`');
+            }
             if (options.json)
-                emitJson('logout', true, { scope: res.scope, removed: res.removed });
+                emitJson('whoami', res.key !== undefined, res);
+        }
+        catch (err) {
+            fail(err, { json: options.json, command: 'whoami' });
+        }
+    });
+    program
+        .command('logout')
+        .description('Remove a saved API key from ~/.lionrapid/credentials')
+        .option('--server <url>', 'remove the key scoped to this server URL')
+        .option('--all', 'remove every saved key and delete the credentials file')
+        .option('--json', 'emit the result as JSON on stdout (prose to stderr)')
+        .action(async (options) => {
+        try {
+            const res = await runLogout({
+                server: options.server,
+                all: options.all,
+                // Only offer a picker on a real terminal; otherwise `runLogout`
+                // refuses rather than guessing which credential to delete.
+                choose: process.stdin.isTTY ? askWhich : undefined,
+            });
+            const out = options.json ? console.error : console.log;
+            if (!res.removed) {
+                out('· nothing was removed');
+            }
+            else if (res.scope === 'all') {
+                out(`✓ removed all ${res.removedScopes} saved key(s) — ${res.credentialsPath} deleted`);
+            }
+            else {
+                out(`✓ removed the key for ${res.scope}`);
+            }
+            if (options.json) {
+                emitJson('logout', true, {
+                    scope: res.scope,
+                    removed: res.removed,
+                    removedScopes: res.removedScopes,
+                });
+            }
         }
         catch (err) {
             fail(err, { json: options.json, command: 'logout' });
@@ -292,26 +601,64 @@ export function buildProgram() {
         .option('--target <locale>', 'push an already-translated target locale instead of the source')
         .option('--publish', 'in --target mode, mark pushed rows ready (public)')
         .option('--dry-run', 'parse + count what would be pushed, but make no network calls')
+        .option('--backfill-missing', 'send only the rows the server is missing (asks the server)')
+        .option('--force', 'send everything, overwriting server rows (saves them to .lionrapid/history/ first)')
         .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 });
+            // Say it BEFORE the request. A pk_ key pushes sources fine but
+            // `targets/batch` answers a bare 403 — found the hard way on
+            // 2026-08-07 while trying to publish a row.
+            if (options.target) {
+                const capability = keyCapability(resolveApiKey({ server: ctx.config.server }));
+                if (!capability.canWriteTargets) {
+                    throw new ApiKeyError(`This key cannot write target translations — ${capability.summary}\n` +
+                        '  `push --target` needs targets:write. Use a master (sk_) key:\n' +
+                        `  lionrapid login --server ${ctx.config.server}`);
+                }
+            }
             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),
+                backfillMissing: options.backfillMissing,
+                force: options.force,
+                // Incremental: the lock lives at the project root, beside lionrapid.yml.
+                lockPath: ctx.cwd,
             });
             const out = options.json ? console.error : console.log;
+            const notice = noTargetsNotice(ctx.config);
+            if (notice)
+                out(notice);
             const tag = res.dryRun ? '[dry-run] would push' : '✓ pushed';
-            out(`${tag} ${res.pushed} ${res.mode} string(s) across ${res.files.length} file(s)`);
+            // Name the unchanged count, or an incremental push that sends nothing
+            // reads as a failure. "0 pushed · 653 unchanged" is a success.
+            const unchanged = res.skipped > 0 ? ` · ${res.skipped} unchanged` : '';
+            out(`${tag} ${res.pushed} ${res.mode} string(s) across ${res.files.length} file(s)${unchanged}`);
+            // The diff is the whole value of a dry run: "2 to send" cannot tell
+            // you whether you are adding strings or overwriting existing ones.
+            if (res.projectCheck === 'unavailable') {
+                out('  · project check skipped — this server disclosed no project id');
+            }
+            if (res.diff && res.pushed > 0) {
+                out(`  ${res.diff.added} new · ${res.diff.changed} changed · ${res.diff.unchanged} unchanged`);
+            }
             for (const f of res.files) {
                 if (f.error) {
                     out(`  · ${f.file}: ✖ ${f.error}`);
                     continue;
                 }
-                out(`  ${f.skipped ? '· skipped (missing)' : '·'} ${f.file}: ${f.count}`);
+                const same = f.unchanged ? ` (${f.unchanged} unchanged)` : '';
+                out(`  ${f.skipped ? '· skipped (missing)' : '·'} ${f.file}: ${f.count}${same}`);
             }
             const failed = res.files.filter((f) => f.error);
             if (failed.length > 0) {
@@ -322,13 +669,77 @@ 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('--refresh', 'ask the server again even for a job already recorded as finished')
+        .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,
+                refresh: options.refresh,
+            });
+            const out = options.json ? console.error : console.log;
+            printStatus(res, out);
+            if (res.retention === 'purged') {
+                out('  · the server no longer retains this job (finished jobs are kept ~1h) —');
+                out('    the recorded verdict above stands.');
+            }
+            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
@@ -356,6 +767,9 @@ export function buildProgram() {
                 },
             });
             const out = options.json ? console.error : console.log;
+            const notice = noTargetsNotice(ctx.config);
+            if (notice)
+                out(notice);
             const mark = res.dryRun ? '[dry-run]' : '✓';
             for (const loc of res.locales) {
                 const pending = loc.pending > 0 ? ` (${loc.pending} pending)` : '';
@@ -371,6 +785,17 @@ export function buildProgram() {
                     out(`  · ${f.target}: ${f.count}${diff}${res.dryRun ? ' (not written)' : ''}`);
                 }
             }
+            // Name the file AND the key, or the warning is not actionable — the
+            // whole point is that you can go look at what was kept.
+            const conflicted = res.locales.flatMap((l) => l.files.flatMap((f) => (f.conflicts ?? []).map((key) => ({ target: f.target, key }))));
+            if (conflicted.length > 0) {
+                out(`⚠ ${conflicted.length} local edit(s) are newer than the server and were NOT overwritten:`);
+                const width = Math.max(...conflicted.map((c) => c.target.length));
+                for (const c of conflicted)
+                    out(`    ${c.target.padEnd(width)}  ${c.key}`);
+                out('  keep them and `lionrapid push --target <locale>`, or `lionrapid pull --force`');
+                out('  to take the server\'s version instead.');
+            }
             const failed = res.locales.flatMap((l) => l.files).filter((f) => f.error);
             if (failed.length > 0) {
                 out(`⚠ ${failed.length} file(s) failed — the successful files were still written`);
@@ -404,7 +829,17 @@ export function buildProgram() {
                 allowLocked: options.allowLocked,
             });
             const out = options.json ? console.error : console.log;
-            if (res.issues.length === 0) {
+            const notice = noTargetsNotice(ctx.config);
+            if (notice)
+                out(notice);
+            if (ctx.config.targetLocales.length === 0) {
+                // Zero targets means zero comparisons were made. Saying "all
+                // translated" here is a vacuous truth that reads as a clean bill of
+                // health — the one thing validate exists not to do.
+                out(`· nothing to validate: ${res.sourceKeys} source key(s), but no targetLocales are configured.\n` +
+                    '  Add target languages in the dashboard, then re-run `lionrapid init`.');
+            }
+            else if (res.issues.length === 0) {
                 out(`✓ all ${res.sourceKeys} source key(s) translated across target locales`);
             }
             else {

package/dist/commands/doctor.d.ts

@@ -23,6 +23,8 @@ export interface DoctorOptions {
     config?: string;
     /** Injectable fetch for tests; defaults to the client's global fetch. */
     fetchImpl?: FetchImpl;
+    /** Credentials file path (defaults to ~/.lionrapid/credentials). */
+    credentialsPath?: string;
 }
 export declare function runDoctor(opts: DoctorOptions): Promise<DoctorResult>;
 //# sourceMappingURL=doctor.d.ts.map