@lionrapid/cli 0.2.2 → 0.4.0

package/dist/commands/push.js

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

package/dist/commands/status.d.ts

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

package/dist/commands/status.js

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

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