@lionrapid/cli 0.2.1 → 0.3.0

package/dist/cli.js

@@ -4,20 +4,23 @@
  * PO) with the LionRapid backend.
  *
  * This file wires up the command surface. Each command's behaviour lives in
- * `src/commands/*`; commands not yet implemented print a clear "not implemented
- * yet" notice and exit non-zero so scripts never silently succeed.
+ * `src/commands/*`.
  */
 import { Command } from 'commander';
 import { readFileSync, realpathSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
+import { createInterface } from 'node:readline';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { ConfigError, ApiKeyError } from './config.js';
-import { ApiError, NetworkError } from './api-client.js';
+import { ConfigError, ApiKeyError, 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 } from './commands/init.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';
@@ -57,11 +60,167 @@ 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.
+ */
+function askText(question, def) {
+    if (!process.stdin.isTTY)
+        return Promise.resolve(def);
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: process.stdin, output: process.stderr });
+        rl.question(`${question} [${def}]: `, (answer) => {
+            rl.close();
+            resolve(answer.trim() || def);
+        });
+    });
+}
 /**
  * Build the commander program. Exported (rather than parsed inline) so tests
  * can construct and inspect the program without executing it.
@@ -71,7 +230,14 @@ export function buildProgram() {
     program
         .name('lionrapid')
         .description('Sync translation files (iOS, Android, Flutter, JSON, YAML, PO) with the LionRapid backend')
-        .version(readVersion(), '-v, --version', 'output the current version');
+        .version(readVersion(), '-v, --version', 'output the current version')
+        .option('--timeout <ms>', 'per-attempt request timeout in ms (default 30000)')
+        // Global flag → env, so loadContext picks it up uniformly in every command.
+        .hook('preAction', (thisCommand) => {
+        const timeout = thisCommand.opts().timeout;
+        if (timeout)
+            process.env['LIONRAPID_TIMEOUT'] = timeout;
+    });
     program
         .command('init')
         .description('Scaffold a lionrapid.yml config in the current project')
@@ -79,24 +245,190 @@ export function buildProgram() {
         .option('--server <url>', 'API server URL')
         .option('--source <locale>', 'source locale')
         .option('--targets <list>', 'comma-separated target locales')
+        .option('--key <key>', 'API key used to prefill locales from the project config')
         .option('--force', 'overwrite an existing lionrapid.yml')
-        .action((options) => {
+        .action(async (options) => {
         try {
+            // Reuse what's already known before asking: the repo's own config,
+            // then the server you logged into. Re-running `init` should not make
+            // you re-type things you've already told the CLI.
+            const existingServer = (() => {
+                const path = findConfigPath(process.cwd());
+                try {
+                    return path ? loadConfig(path).server : undefined;
+                }
+                catch {
+                    return undefined;
+                }
+            })();
+            const loggedIn = listCredentialServers();
+            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.
+            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());
+            // 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.
+            let source = options.source;
+            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;
+                }
+                let serverStatus = 'no-key';
+                let serverTargets;
+                if (key) {
+                    const client = new LionRapidApiClient({
+                        baseUrl: server,
+                        apiKey: key,
+                        retries: 0,
+                        timeoutMs: 5000,
+                    });
+                    const prefill = await fetchLocaleDefaults(client);
+                    serverStatus = prefill.status;
+                    if (prefill.status === 'ok') {
+                        source ??= prefill.sourceLocale;
+                        serverTargets = prefill.targetLocales;
+                        targets ??= prefill.targetLocales;
+                    }
+                    else if (prefill.status === 'no-targets') {
+                        source ??= prefill.sourceLocale; // the source locale IS real
+                    }
+                }
+                const onDisk = detectLocalesOnDisk(process.cwd(), source ?? 'en');
+                if (serverStatus === 'ok' && serverTargets) {
+                    notes.push(`locales from ${server}: ${source} → ${serverTargets.join(', ')}`);
+                    // The project decides what actually gets delivered — a locale
+                    // that exists only on disk is a real mismatch, worth saying out
+                    // loud rather than silently merging into the scaffold.
+                    const extra = onDisk.filter((l) => !serverTargets.includes(l));
+                    if (extra.length > 0) {
+                        notes.push(`note: ${extra.join(', ')} present in your files but not configured on the project —\n` +
+                            '    add them in the dashboard, or pull will never fill those files.');
+                    }
+                }
+                else if (onDisk.length > 0) {
+                    targets ??= onDisk;
+                    notes.push(serverStatus === 'no-targets'
+                        ? `⚠ the project has no target languages configured (source: ${source}) — used ${onDisk.join(', ')} from the files in your repo.\n` +
+                            '    Add them in the dashboard, then re-run `lionrapid init`.'
+                        : `locales from your files: ${source ?? 'en'} → ${onDisk.join(', ')}`);
+                }
+                else if (serverStatus === 'no-targets') {
+                    // Nothing invented: an empty targetLocales is honest, and the
+                    // config stays invalid until the real languages exist.
+                    notes.push(`⚠ the project has no target languages configured (source: ${source}), and none\n` +
+                        '    were found in your files — targetLocales is empty and the config is not\n' +
+                        '    usable yet. Add your languages in the dashboard, then re-run `lionrapid init`.');
+                }
+                else if (serverStatus === 'unavailable') {
+                    notes.push('⚠ could not reach the project config — targetLocales left empty.\n' +
+                        '    Fill it in by hand, or re-run `lionrapid init` once the server is reachable.');
+                }
+                else {
+                    notes.push('⚠ no API key, so no project config to read — targetLocales left empty.\n' +
+                        '    Run `lionrapid login`, then re-run `lionrapid init`.');
+                }
+            }
             const res = runInit(process.cwd(), {
-                project: options.project,
-                server: options.server,
-                sourceLocale: options.source,
-                targetLocales: options.targets?.split(',').map((s) => s.trim()),
+                project,
+                server,
+                sourceLocale: source,
+                targetLocales: targets,
                 force: options.force,
             });
-            console.log(`✓ wrote ${res.configPath}`);
+            if (res.created || options.force) {
+                console.log(`✓ wrote ${res.configPath}`);
+            }
+            else if (res.applied.length > 0) {
+                console.log(`✓ updated ${res.configPath}`);
+                for (const c of res.applied)
+                    console.log(`    + ${c.path}: ${c.to}`);
+            }
+            else {
+                console.log(`✓ ${res.configPath} is already up to date`);
+            }
             console.log(`  detected: ${res.detected.stacks.join(', ')}`);
-            console.log('  edit the project id + locales, then run `lionrapid push`.');
+            for (const note of notes)
+                console.log(`  ${note}`);
+            if (res.conflicts.length > 0) {
+                // Never silently overwrite a value the developer set. Show the
+                // difference and let them resolve it in the file.
+                console.log(`  ⚠ ${res.conflicts.length} value(s) differ from the project — left as-is:`);
+                for (const c of res.conflicts) {
+                    console.log(`    ${c.path}`);
+                    console.log(`      yours:   ${c.from}`);
+                    console.log(`      project: ${c.to}`);
+                }
+                console.log('    Edit lionrapid.yml to resolve, or re-run with --force to take the');
+                console.log('    project values wholesale.');
+            }
+            const ready = res.conflicts.length === 0 && (targets?.length ?? 0) > 0;
+            console.log(ready
+                ? '  next: `lionrapid doctor` to check the setup, then `lionrapid push`.'
+                : '  next: fix the above in lionrapid.yml, then run `lionrapid doctor`.');
         }
         catch (err) {
             fail(err);
         }
     });
+    program
+        .command('login')
+        .description('Verify an API key against the server and save it to ~/.lionrapid/credentials')
+        .option('--server <url>', 'save the key scoped to this server URL (default: save as "default")')
+        .option('--key <key>', 'the API key (omit for a hidden interactive prompt)')
+        .option('--json', 'emit the result as JSON on stdout (prose to stderr)')
+        .action(async (options) => {
+        try {
+            const res = await runLogin({
+                server: options.server,
+                key: options.key,
+                cwd: process.cwd(),
+            });
+            const out = options.json ? console.error : console.log;
+            out(`✓ key verified against ${res.server}`);
+            out(`  saved ${res.scope === 'server' ? `for ${res.server}` : 'as default'} → ${res.credentialsPath}`);
+            // Never echo the key — the envelope carries scope + server only.
+            if (options.json)
+                emitJson('login', true, { server: res.server, scope: res.scope });
+        }
+        catch (err) {
+            fail(err, { json: options.json, command: 'login' });
+        }
+    });
+    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")')
+        .option('--json', 'emit the result as JSON on stdout (prose to stderr)')
+        .action((options) => {
+        try {
+            const res = runLogout({ server: options.server });
+            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`);
+            if (options.json)
+                emitJson('logout', true, { scope: res.scope, removed: res.removed });
+        }
+        catch (err) {
+            fail(err, { json: options.json, command: 'logout' });
+        }
+    });
     program
         .command('push')
         .description('Upload source strings to the LionRapid backend')
@@ -106,29 +438,103 @@ 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';
             out(`${tag} ${res.pushed} ${res.mode} string(s) across ${res.files.length} file(s)`);
             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 failed = res.files.filter((f) => f.error);
+            if (failed.length > 0) {
+                out(`⚠ ${failed.length} file(s) failed — the rest were pushed. Re-run push to retry\n` +
+                    '  the failures (already-pushed strings are simply upserted again).');
+            }
             if (res.publishSkipped) {
                 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', true, res);
+                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
@@ -137,6 +543,7 @@ export function buildProgram() {
         .option('-c, --config <path>', 'path to lionrapid.yml')
         .option('--types', 'regenerate TypeScript types after pulling')
         .option('--dry-run', 'fetch + count what would be written, but write no files')
+        .option('--force', 'overwrite target files wholesale instead of merging (drops local-only keys)')
         .option('--json', 'emit the result as JSON on stdout (prose to stderr)')
         .action(async (options) => {
         try {
@@ -144,6 +551,7 @@ export function buildProgram() {
             const res = await runPull(ctx.config, ctx.client, {
                 cwd: ctx.cwd,
                 dryRun: options.dryRun,
+                force: options.force,
                 onProgress: (done, total) => {
                     // Interactive feedback only — never pollute CI logs or --json stdout.
                     if (process.stderr.isTTY && total > 1) {
@@ -159,16 +567,29 @@ export function buildProgram() {
                 const pending = loc.pending > 0 ? ` (${loc.pending} pending)` : '';
                 out(`${mark} ${loc.locale}${pending}`);
                 for (const f of loc.files) {
-                    out(`  · ${f.target}: ${f.count}${res.dryRun ? ' (not written)' : ''}`);
+                    if (f.error) {
+                        out(`  · ${f.target}: ✖ ${f.error}`);
+                        continue;
+                    }
+                    const diff = f.added !== undefined
+                        ? ` (+${f.added} new, ~${f.updated} updated, ${f.keptLocal} local kept)`
+                        : '';
+                    out(`  · ${f.target}: ${f.count}${diff}${res.dryRun ? ' (not written)' : ''}`);
                 }
             }
+            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`);
+            }
             let types;
             if ((options.types || ctx.config.generateTypes) && !options.dryRun) {
                 types = runTypesGenerate(ctx.config, { cwd: ctx.cwd });
                 out(`✓ types: ${types.keys} key(s) → ${types.output}`);
             }
             if (options.json)
-                emitJson('pull', true, { ...res, types });
+                emitJson('pull', failed.length === 0, { ...res, types });
+            if (failed.length > 0)
+                process.exit(ExitCode.PARTIAL);
         }
         catch (err) {
             fail(err, { json: options.json, command: 'pull' });
@@ -179,19 +600,23 @@ export function buildProgram() {
         .description('Check local files against the backend for missing/extra keys')
         .option('-c, --config <path>', 'path to lionrapid.yml')
         .option('--ci', 'exit non-zero if any issue is found')
+        .option('--allow-locked', 'treat locked (unapproved) namespaces as a warning, not a failure')
         .option('--json', 'emit the result as JSON on stdout (prose to stderr)')
         .action(async (options) => {
         try {
             const ctx = loadContext({ config: options.config });
-            const res = await runValidate(ctx.config, ctx.client, { cwd: ctx.cwd });
+            const res = await runValidate(ctx.config, ctx.client, {
+                cwd: ctx.cwd,
+                allowLocked: options.allowLocked,
+            });
             const out = options.json ? console.error : console.log;
-            if (res.ok) {
+            if (res.issues.length === 0) {
                 out(`✓ all ${res.sourceKeys} source key(s) translated across target locales`);
             }
             else {
-                out(`✖ ${res.issues.length} issue(s):`);
+                out(`${res.ok ? '⚠' : '✖'} ${res.issues.length} issue(s):`);
                 for (const i of res.issues) {
-                    out(`  [${i.type}] ${i.locale}/${i.namespace} ${i.key}`);
+                    out(`  [${i.type}] ${i.locale}/${i.namespace}${i.key ? ` ${i.key}` : ''}`);
                 }
             }
             if (options.json)

package/dist/commands/context.d.ts

@@ -22,8 +22,17 @@ export interface OfflineContext {
 export declare function loadOfflineContext(opts?: ContextOptions): OfflineContext;
 /** Load config + resolve the API key + build the client — for networked commands. */
 export declare function loadContext(opts?: ContextOptions): CliContext;
+/** Read LIONRAPID_TIMEOUT (a positive integer, ms) if set; otherwise the client default. */
+export declare function resolveTimeout(): number | undefined;
 /** Read LIONRAPID_RETRIES (a non-negative integer) if set; otherwise the client default. */
 export declare function resolveRetries(): number | undefined;
+/**
+ * Resolve `rel` against `cwd`, refusing paths that escape it. Every
+ * config-derived file *write* goes through this — defense-in-depth so a
+ * `../`-authored target/output in lionrapid.yml can't write outside the
+ * project directory. Returns the absolute path.
+ */
+export declare function assertInside(cwd: string, rel: string): string;
 export declare function chunk<T>(items: T[], size: number): T[][];
 /** Default parallel in-flight requests for fan-out work (pull). */
 export declare const DEFAULT_CONCURRENCY = 6;

package/dist/commands/context.js

@@ -3,7 +3,8 @@
  * build the API client. Kept separate from the commander wiring so command
  * logic can be driven with a fake client in tests.
  */
-import { findConfigPath, loadConfig, resolveApiKey, ConfigError, } from '../config.js';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { expandGlobEntries, findConfigPath, loadConfig, resolveApiKey, ConfigError, } from '../config.js';
 import { LionRapidApiClient } from '../api-client.js';
 /** Load + validate config only (no API key) — for offline commands like `types`. */
 export function loadOfflineContext(opts = {}) {
@@ -12,7 +13,9 @@ export function loadOfflineContext(opts = {}) {
     if (!path) {
         throw new ConfigError('No lionrapid.yml found in this directory. Run `lionrapid init` to create one.');
     }
-    return { config: loadConfig(path), cwd };
+    const config = loadConfig(path);
+    // Glob entries expand here, once — commands only ever see concrete files.
+    return { config: { ...config, files: expandGlobEntries(config.files, cwd) }, cwd };
 }
 /** Load config + resolve the API key + build the client — for networked commands. */
 export function loadContext(opts = {}) {
@@ -25,9 +28,18 @@ export function loadContext(opts = {}) {
         apiKey,
         editorToken,
         retries: resolveRetries(),
+        timeoutMs: resolveTimeout(),
     });
     return { config, client, cwd };
 }
+/** Read LIONRAPID_TIMEOUT (a positive integer, ms) if set; otherwise the client default. */
+export function resolveTimeout() {
+    const raw = process.env['LIONRAPID_TIMEOUT']?.trim();
+    if (!raw)
+        return undefined;
+    const n = Number(raw);
+    return Number.isInteger(n) && n > 0 ? n : undefined;
+}
 /** Read LIONRAPID_RETRIES (a non-negative integer) if set; otherwise the client default. */
 export function resolveRetries() {
     const raw = process.env['LIONRAPID_RETRIES']?.trim();
@@ -36,6 +48,20 @@ export function resolveRetries() {
     const n = Number(raw);
     return Number.isInteger(n) && n >= 0 ? n : undefined;
 }
+/**
+ * Resolve `rel` against `cwd`, refusing paths that escape it. Every
+ * config-derived file *write* goes through this — defense-in-depth so a
+ * `../`-authored target/output in lionrapid.yml can't write outside the
+ * project directory. Returns the absolute path.
+ */
+export function assertInside(cwd, rel) {
+    const abs = resolve(cwd, rel);
+    const r = relative(cwd, abs);
+    if (r.startsWith('..') || isAbsolute(r)) {
+        throw new ConfigError(`Path escapes the project directory: ${rel}`);
+    }
+    return abs;
+}
 export function chunk(items, size) {
     const out = [];
     for (let i = 0; i < items.length; i += size)