@lionrapid/cli 0.3.0 → 0.4.0

package/dist/commands/push.js

@@ -17,10 +17,53 @@ import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { ConfigError } from '../config.js';
 import { getAdapter } from '../adapters/index.js';
+import { saveHistory } from '../history.js';
+import { hashSource, lockKey, readLock, writeLock } from '../lockfile.js';
 import { chunk } from './context.js';
 // The server's enforced ceiling is 1000 items per sync/targets batch (Pydantic
 // `max_length` on the request model) — 500 stays comfortably under it.
 const BATCH = 500;
+/**
+ * The source rows the server actually holds for a namespace.
+ *
+ * A locked or missing namespace answers "nothing", which is the right reading
+ * for both callers: `--backfill-missing` then sends everything, and
+ * `--force` has nothing to snapshot.
+ */
+async function sourceRowsOnServer(client, sourceLocale, namespace) {
+    try {
+        const bundle = await client.getNamespace(sourceLocale, namespace);
+        return new Map(Object.entries(bundle.translations));
+    }
+    catch {
+        return new Map();
+    }
+}
+/**
+ * The project this API KEY resolves to, or undefined when the server does not
+ * say.
+ *
+ * Read from `meta.project_uuid` on a translations fetch. That field is real
+ * but UNDECLARED — the route returns a raw Response to set its ETag header,
+ * bypassing the declared response model (server task #70) — so "absent" must
+ * stay a normal, non-blocking answer forever, not an error. A locked (423) or
+ * missing namespace also answers nothing, which is right: a project with no
+ * rows yet cannot identify itself this way.
+ */
+async function resolveKeyProject(client, config) {
+    const namespaces = new Set(config.files.map((f) => f.namespace ?? config.namespace));
+    for (const namespace of namespaces) {
+        try {
+            const bundle = await client.getNamespace(config.sourceLocale, namespace);
+            if (bundle.projectId)
+                return bundle.projectId;
+        }
+        catch {
+            // Try the next namespace; an unreachable server is the caller's problem.
+        }
+    }
+    return undefined;
+}
 export async function runPush(config, client, opts) {
     const mode = opts.target ? 'target' : 'source';
     // The backend does NOT validate target locales — `targets/batch` silently
@@ -40,6 +83,43 @@ export async function runPush(config, client, opts) {
     const canPublish = mode === 'target' && opts.publish === true && client.canPublish;
     const publishSkipped = mode === 'target' && opts.publish === true && !client.canPublish;
     let pushed = 0;
+    let skipped = 0;
+    let diffAdded = 0;
+    let diffChanged = 0;
+    // INCREMENTAL. The lock says what the server already has, so a second run
+    // sends "4 changed" rather than all 653. No lock (first run, or a fresh
+    // checkout) means we know nothing, which is a backfill — send everything.
+    //
+    // Source mode only: `push --target` sends LOCAL values, and recording those
+    // as server state would be the fabrication `pull` is careful to avoid.
+    const lock = opts.lockPath && mode === 'source' ? readLock(opts.lockPath) : undefined;
+    // One asks "what is the server missing", the other says "ignore all of that
+    // and take mine". Silently picking one would be a coin toss with the user's
+    // data.
+    if (opts.force && opts.backfillMissing) {
+        throw new ConfigError('--force and --backfill-missing ask for opposite things: one overwrites every server\n' +
+            '  row, the other touches only the rows that are missing. Pick one.');
+    }
+    // THE GUARD. Runs before a single row is sent, because it is worthless
+    // afterwards — on 2026-08-07, 653 strings reported as `tm-frontpage` landed
+    // in another project, and nothing said so until an hour of hunting later.
+    let projectCheck;
+    if (config.projectId) {
+        const actual = await resolveKeyProject(client, config);
+        if (actual === undefined) {
+            projectCheck = 'unavailable';
+        }
+        else if (actual !== config.projectId) {
+            throw new ConfigError('project mismatch — this push would go somewhere else.\n' +
+                `  lionrapid.yml projectId:  ${config.projectId}\n` +
+                `  this API key resolves to: ${actual}\n` +
+                '  The API key selects the project; the config cannot. Update projectId in\n' +
+                '  lionrapid.yml, or switch keys.');
+        }
+        else {
+            projectCheck = 'ok';
+        }
+    }
     let firstError;
     for (const file of config.files) {
         const adapter = getAdapter(file.format);
@@ -57,7 +137,54 @@ export async function runPush(config, client, opts) {
         try {
             const parseLocale = mode === 'source' ? config.sourceLocale : opts.target;
             const entries = adapter.parse(readFileSync(absPath, 'utf8'), { locale: parseLocale });
-            const items = entries.map((e) => ({ key: e.key, value: e.value }));
+            const all = entries.map((e) => ({ key: e.key, value: e.value }));
+            const hashes = new Map(all.map((it) => [it.key, hashSource(it.value)]));
+            // Three modes. `--force` and `--backfill-missing` both ASK THE SERVER
+            // rather than trusting the lock, which is what makes them a recovery
+            // path: the lock can be wrong (a 202 whose job later died records rows
+            // as sent that never landed), and only the server knows the truth.
+            let items;
+            if (opts.force) {
+                const onServer = await sourceRowsOnServer(client, config.sourceLocale, namespace);
+                if (!opts.dryRun) {
+                    saveHistory(opts.lockPath ?? opts.cwd, {
+                        direction: 'push',
+                        namespace,
+                        locale: config.sourceLocale,
+                        reason: `push --force overwrote these server rows from ${relPath}`,
+                        entries: all
+                            .filter((it) => onServer.has(it.key))
+                            .map((it) => ({ key: it.key, value: onServer.get(it.key) })),
+                    });
+                }
+                items = all;
+            }
+            else if (opts.backfillMissing) {
+                const onServer = await sourceRowsOnServer(client, config.sourceLocale, namespace);
+                items = all.filter((it) => !onServer.has(it.key));
+            }
+            else {
+                // Default: incremental against the lock — new keys and changed text.
+                items = lock
+                    ? all.filter((it) => lock.entries[lockKey(namespace, it.key)]?.sourceHash !== hashes.get(it.key))
+                    : all;
+            }
+            skipped += all.length - items.length;
+            // A key the lock has never seen is NEW; one it has seen with a different
+            // hash is CHANGED. Counted from the lock even under --force, so the
+            // report describes the repo's relationship to the server rather than
+            // just restating the flag.
+            for (const it of items) {
+                const known = lock?.entries[lockKey(namespace, it.key)]?.sourceHash;
+                if (known === undefined || known === '')
+                    diffAdded += 1;
+                else
+                    diffChanged += 1;
+            }
+            if (items.length === 0) {
+                files.push({ file: relPath, count: 0, unchanged: all.length });
+                continue;
+            }
             // Dry run: parse + count only, never touch the network.
             if (!opts.dryRun) {
                 for (const batch of chunk(items, BATCH)) {
@@ -89,8 +216,21 @@ export async function runPush(config, client, opts) {
                     }
                 }
             }
+            // Record ONLY what the server accepted, and only for a file that got
+            // through cleanly — a hash written for rows the server never took would
+            // make the next push skip them silently.
+            if (lock && !opts.dryRun) {
+                for (const it of items) {
+                    const key = lockKey(namespace, it.key);
+                    lock.entries[key] = { ...lock.entries[key], sourceHash: hashes.get(it.key) };
+                }
+            }
             pushed += items.length;
-            files.push({ file: relPath, count: items.length });
+            files.push({
+                file: relPath,
+                count: items.length,
+                ...(all.length > items.length ? { unchanged: all.length - items.length } : {}),
+            });
         }
         catch (err) {
             firstError ??= err;
@@ -107,9 +247,19 @@ export async function runPush(config, client, opts) {
     if (attempted.length > 0 && attempted.every((f) => f.error) && firstError !== undefined) {
         throw firstError;
     }
+    // Persist what the server accepted. Written even on the partial path: the
+    // files that succeeded really did land, and re-sending them next run is
+    // exactly the waste the lock exists to remove.
+    if (lock && opts.lockPath && !opts.dryRun)
+        writeLock(opts.lockPath, lock);
     return {
         mode,
         pushed,
+        skipped,
+        ...(projectCheck ? { projectCheck } : {}),
+        ...(mode === 'source'
+            ? { diff: { added: diffAdded, changed: diffChanged, unchanged: skipped } }
+            : {}),
         files,
         jobs,
         ...(publishSkipped ? { publishSkipped: true } : {}),

package/dist/commands/status.d.ts

@@ -47,6 +47,12 @@ export interface StatusResult {
     queueUnavailable?: string;
     /** `status <id>`: the id is known neither to the server nor to this machine. */
     notFound?: boolean;
+    /**
+     * Set to `purged` when a forced refresh met a 404 for a job we already knew
+     * the outcome of. Expected, not a failure: the server keeps finished jobs
+     * about an hour, and the recorded verdict stands.
+     */
+    retention?: 'purged';
 }
 export interface StatusOptions {
     /** A job id, `list`, or nothing (both of the latter mean "list"). */
@@ -60,6 +66,15 @@ export interface StatusOptions {
     client?: LionRapidApiClient;
     /** Limit the listing to jobs pushed to this server. */
     server?: string;
+    /**
+     * Re-ask the server even for a receipt that already looks final.
+     *
+     * The short-circuit is right by default — a terminal state cannot change,
+     * and the server forgets a finished job after ~1h. But it is wrong at the
+     * one moment that matters: someone standing in front of an empty dashboard
+     * saying "it is not there" deserves a fresh answer, not a cached tick.
+     */
+    refresh?: boolean;
 }
 /** True for the bare command and the explicit `list` form. */
 export declare function isListRequest(jobId?: string): boolean;

package/dist/commands/status.js

@@ -41,8 +41,9 @@ 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)) {
+    // forgotten the job entirely. Answer from the receipt and skip the call —
+    // unless the caller explicitly asked for a fresh one.
+    if (recorded && isTerminalJobStatus(recorded.status) && !opts.refresh) {
         return { ...base, jobs: [localView(recorded)] };
     }
     if (!opts.client) {
@@ -63,6 +64,13 @@ async function showJob(jobId, history, historyPath, opts) {
         // 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) {
+            // THE RULE. Past retention a 404 is expected, so a forced refresh of a
+            // job we already have a verdict for must KEEP that verdict. Downgrading
+            // it to `gone` would make --refresh a way of destroying the only answer
+            // that outlives the server's memory.
+            if (recorded && isTerminalJobStatus(recorded.status)) {
+                return { ...base, jobs: [localView(recorded)], retention: 'purged' };
+            }
             if (recorded) {
                 persist(historyPath, [{ id: jobId, status: 'gone', checkedAt: new Date().toISOString() }]);
                 return { ...base, jobs: [{ ...localView({ ...recorded, status: 'gone' }), source: 'server' }] };
@@ -86,7 +94,7 @@ async function listJobs(history, historyPath, opts) {
         // 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 stale = (opts.refresh ? scoped : scoped.filter((e) => !isTerminalJobStatus(e.status))).slice(0, MAX_REFRESH);
     const views = new Map();
     let offline;
     if (opts.client && stale.length > 0) {
@@ -97,8 +105,11 @@ async function listJobs(history, historyPath, opts) {
                 return await client.getSyncJob(entry.id);
             }
             catch (err) {
-                if (err instanceof ApiError && err.status === 404)
-                    return 'gone';
+                // Same rule as the single-job path: never turn a known verdict into
+                // 'gone' just because the server has since forgotten the job.
+                if (err instanceof ApiError && err.status === 404) {
+                    return isTerminalJobStatus(entry.status) ? undefined : 'gone';
+                }
                 if (err instanceof NetworkError) {
                     offline ??= err.message;
                     return undefined;

package/dist/commands/whoami.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `whoami` — which key am I about to use, and where is it going?
+ *
+ * The hour lost on 2026-08-07 was spent between a push and a dashboard, not
+ * knowing which credential had routed it. `doctor` can answer, but it needs a
+ * valid config and a reachable server; this answers from disk alone, so it
+ * still works when the thing you are debugging is the config itself.
+ *
+ * Deliberately OFFLINE. `doctor` is the networked check; duplicating its probe
+ * here would make the fast question slow and would fail for the exact users
+ * who need it (bad server URL, no connectivity). Nothing here can leak key
+ * material: every value goes through {@link maskKey}.
+ *
+ * NOT YET SHOWN: the project the key resolves to. That needs `projectId` /
+ * `projectName` on the server's project-config response (spec C4/S2), which
+ * this deployment does not serve yet — inventing a name here would repeat the
+ * exact bug the spec is fixing, where a displayed project was never verified.
+ */
+import { type KeyCapability, type KeySource } from '../config.js';
+export interface WhoamiKey {
+    source: KeySource;
+    /** What this key class can do — the pk_/sk_ line, stated before you hit it. */
+    capability: KeyCapability;
+    /** `LIONRAPID_API_KEY`, `default`, or the server URL the key is scoped to. */
+    scope: string;
+    masked: string;
+}
+export interface WhoamiResult {
+    /** Absolute path of the lionrapid.yml in play, if there is one. */
+    configPath?: string;
+    /** The server this directory would talk to. */
+    server?: string;
+    /** The credential that would be used. Absent when none resolves. */
+    key?: WhoamiKey;
+    /** Every saved credential, masked — shown even when none of them applies. */
+    scopes: {
+        scope: string;
+        masked: string;
+    }[];
+    /** Why there is no answer (no config, invalid config, no matching key). */
+    problem?: string;
+}
+export interface WhoamiOptions {
+    cwd: string;
+    config?: string;
+    credentialsPath?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function runWhoami(opts: WhoamiOptions): WhoamiResult;
+//# sourceMappingURL=whoami.d.ts.map

package/dist/commands/whoami.js

@@ -0,0 +1,66 @@
+/**
+ * `whoami` — which key am I about to use, and where is it going?
+ *
+ * The hour lost on 2026-08-07 was spent between a push and a dashboard, not
+ * knowing which credential had routed it. `doctor` can answer, but it needs a
+ * valid config and a reachable server; this answers from disk alone, so it
+ * still works when the thing you are debugging is the config itself.
+ *
+ * Deliberately OFFLINE. `doctor` is the networked check; duplicating its probe
+ * here would make the fast question slow and would fail for the exact users
+ * who need it (bad server URL, no connectivity). Nothing here can leak key
+ * material: every value goes through {@link maskKey}.
+ *
+ * NOT YET SHOWN: the project the key resolves to. That needs `projectId` /
+ * `projectName` on the server's project-config response (spec C4/S2), which
+ * this deployment does not serve yet — inventing a name here would repeat the
+ * exact bug the spec is fixing, where a displayed project was never verified.
+ */
+import { ApiKeyError, ConfigError, findConfigPath, loadConfig, listCredentials, maskKey, keyCapability, resolveApiKeyDetailed, } from '../config.js';
+export function runWhoami(opts) {
+    const scopes = listCredentials(opts.credentialsPath);
+    const result = { scopes };
+    // The config is optional: run from anywhere and the saved scopes are still
+    // worth seeing. A broken config is reported, not thrown — whoami is what you
+    // reach for WHEN something is broken.
+    const path = opts.config ?? findConfigPath(opts.cwd);
+    if (!path) {
+        result.problem = 'no lionrapid.yml here — run `lionrapid init`';
+    }
+    else {
+        result.configPath = path;
+        try {
+            result.server = loadConfig(path).server;
+        }
+        catch (err) {
+            result.problem =
+                err instanceof ConfigError
+                    ? `lionrapid.yml is not valid: ${err.issues.map((i) => `${i.path}: ${i.message}`).join('; ') || err.message}`
+                    : String(err);
+        }
+    }
+    try {
+        const resolved = resolveApiKeyDetailed({
+            server: result.server,
+            credentialsPath: opts.credentialsPath,
+            env: opts.env,
+        });
+        result.key = {
+            source: resolved.source,
+            scope: resolved.scope,
+            masked: maskKey(resolved.key),
+            capability: keyCapability(resolved.key),
+        };
+    }
+    catch (err) {
+        // An unresolvable key is the ANSWER here, not a failure: it is precisely
+        // what the user came to find out.
+        if (!(err instanceof ApiKeyError))
+            throw err;
+        result.problem = result.problem
+            ? `${result.problem}\n${err.message}`
+            : err.message;
+    }
+    return result;
+}
+//# sourceMappingURL=whoami.js.map

package/dist/config.d.ts

@@ -41,7 +41,22 @@ export interface FileEntry {
 /** True when a `files[].source` is a glob pattern rather than a concrete path. */
 export declare function isGlobSource(source: string): boolean;
 export interface LionRapidConfig {
-    project: string;
+    /**
+     * The project the API key must resolve to — checked on every push.
+     *
+     * Replaces the old free-text `project:`, which nothing verified. Proven on
+     * 2026-08-07: a push declaring `project: cli-verify`, a name that does not
+     * exist, landed in the project the KEY belongs to, while the CLI reported
+     * the config's label for 30 jobs that went somewhere else. THE API KEY
+     * SELECTS THE PROJECT; the config never could.
+     *
+     * OPTIONAL, because the server field it comes from (`meta.project_uuid`) is
+     * real but UNDECLARED — the translations route returns a raw Response to set
+     * its ETag header, bypassing the response model, so a later tidy-up could
+     * remove it in what looks like a cosmetic change (server task #70). A guard
+     * that cannot arm must not block a push.
+     */
+    projectId?: string;
     server: string;
     sourceLocale: string;
     targetLocales: string[];
@@ -71,8 +86,26 @@ export declare class ConfigError extends Error {
 export declare class ApiKeyError extends Error {
     constructor(message: string);
 }
+/** Opt-in for sending a key to a host we do not recognize (self-hosted). */
+export declare const ALLOW_UNTRUSTED_HOST_ENV = "LIONRAPID_ALLOW_UNTRUSTED_HOST";
 /** Locate the config file in `cwd`, returning its path or null. */
 export declare function findConfigPath(cwd?: string): string | null;
+/**
+ * What a source-only config costs you. Named commands, not a vague "no
+ * targets": the point is that nothing is broken — two commands simply have
+ * nothing to do until the project has target languages.
+ */
+export declare const NO_TARGETS_WARNING: string;
+/**
+ * The warning, but only for the commands it applies to.
+ *
+ * Emitting it at parse time meant every command carried it — including
+ * `status`, which reports what the backend did with a job and has nothing to
+ * do with target locales. A warning that fires where it does not apply is how
+ * people learn to ignore warnings, so the three commands that are actually
+ * affected ask for it and nobody else sees it.
+ */
+export declare function noTargetsNotice(config: LionRapidConfig): string | undefined;
 /** Parse + validate a YAML config string into a typed config. */
 export declare function parseConfig(rawYaml: string): LionRapidConfig;
 /**
@@ -88,6 +121,19 @@ export declare function parseConfig(rawYaml: string): LionRapidConfig;
 export declare function expandGlobEntries(files: FileEntry[], cwd: string, warn?: (message: string) => void): FileEntry[];
 /** Read + parse + validate the config at `path`. */
 export declare function loadConfig(path: string): LionRapidConfig;
+/**
+ * The user's home directory, `$HOME` first.
+ *
+ * Identical to `os.homedir()` for real users on POSIX (it reads `$HOME` too),
+ * but a JS-level `process.env.HOME` assignment is invisible to `homedir()`'s
+ * native `getenv` inside a worker thread — which is where vitest runs. Without
+ * this, the suite reads (and could write) the developer's real
+ * `~/.lionrapid/`: a test asserting "no credentials" passes in CI and fails on
+ * a laptop that has logged in, which is a silent source of divergence.
+ *
+ * Shared by {@link defaultCredentialsPath} and the job history.
+ */
+export declare function homeDir(): string;
 /** Where the CLI reads/writes credentials: `~/.lionrapid/credentials`. */
 export declare function defaultCredentialsPath(): string;
 /**
@@ -116,10 +162,59 @@ export interface ResolveApiKeyOptions {
  *   2. credentials file (JSON: `{ "default": "sk_...", "<server>": "sk_..." }`)
  * The key is never read from `lionrapid.yml` (which is committed to git).
  *
- * Trust rule: the `default` credential is only handed out for recognized
- * LionRapid hosts (`*.lionrapid.com`) and localhost. Any other server needs
- * its own server-scoped entry — otherwise a committed lionrapid.yml pointing
- * at an attacker host would exfiltrate the key of anyone running `push`.
+ * Trust rule: a key is only handed out for recognized LionRapid hosts
+ * (`*.lionrapid.com`) and localhost. Any other server needs either its own
+ * server-scoped credentials entry or {@link ALLOW_UNTRUSTED_HOST_ENV} —
+ * otherwise a committed lionrapid.yml pointing at an attacker host would
+ * exfiltrate the key of anyone running `push`.
  */
 export declare function resolveApiKey(opts?: ResolveApiKeyOptions): string;
+/** Where a resolved key came from. `whoami` shows this; nothing else needs it. */
+export type KeySource = 'env' | 'server-scoped' | 'default';
+export interface ResolvedKey {
+    key: string;
+    source: KeySource;
+    /** The env var name, or the credentials entry the key was read from. */
+    scope: string;
+}
+/**
+ * {@link resolveApiKey}, plus WHERE the key came from.
+ *
+ * One implementation, two views: `whoami` has to say which credential is about
+ * to be used, and a second copy of this precedence ladder would be a place for
+ * the two to drift — the displayed key would stop being the sent key, which is
+ * the exact confusion `whoami` exists to end.
+ */
+export declare function resolveApiKeyDetailed(opts?: ResolveApiKeyOptions): ResolvedKey;
+/**
+ * Display form of a key: prefix + last four, never the middle.
+ *
+ * A key shorter than the prefix+last4 window would otherwise be echoed almost
+ * whole, so a short (malformed, truncated) value drops the prefix entirely —
+ * "mask" must not become "print" for the one input where it matters.
+ */
+export declare function maskKey(key: string): string;
+/** What a key class can and cannot do, in the terms a user actually hits. */
+export interface KeyCapability {
+    kind: 'publishable' | 'master' | 'editor-session' | 'unknown';
+    /** One line, naming the functional line rather than the scope vocabulary. */
+    summary: string;
+    /** True when `push --target` / `--publish` will work (needs `targets:write`). */
+    canWriteTargets: boolean;
+}
+/**
+ * A key's class, from its prefix.
+ *
+ * The functional line is `targets:write`, NOT the queue scopes. A `pk_` holder
+ * can push sources, pull and read status, but `push --target` dies on a bare
+ * 403 from `targets/batch` — hit for real on 2026-08-07 while trying to
+ * publish a row, and exactly the kind of thing worth saying BEFORE the request
+ * instead of after it.
+ */
+export declare function keyCapability(key: string): KeyCapability;
+/** Every saved credential, as `{ scope, masked }`. Never returns key material. */
+export declare function listCredentials(credentialsPath?: string): {
+    scope: string;
+    masked: string;
+}[];
 //# sourceMappingURL=config.d.ts.map