@lionrapid/cli 0.2.2 → 0.4.0

package/dist/commands/doctor.js

@@ -10,11 +10,33 @@
  */
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { expandGlobEntries, findConfigPath, loadConfig, resolveApiKey, } from '../config.js';
+import { expandGlobEntries, findConfigPath, loadConfig, resolveApiKey, keyCapability, listCredentialServers, ConfigError, } from '../config.js';
 import { LionRapidApiClient } from '../api-client.js';
+/**
+ * First line only. Right for a network error (whose `cause` chain is long and
+ * repetitive), wrong for a ConfigError — see {@link configDetail}.
+ */
 function msg(err) {
     return err instanceof Error ? err.message.split('\n')[0] : String(err);
 }
+/**
+ * A config failure, with its issues.
+ *
+ * `msg()` kept the first line only, so `Invalid lionrapid config:` printed
+ * with every bullet the validator had produced discarded — a header promising
+ * a list, followed by nothing. Other commands print `err.message` whole and
+ * showed the bullets, which is what made the renderer look inconsistent: it is
+ * not per-field, it is per-command. ConfigError carries the issues as typed
+ * data, so use that rather than re-splitting a string.
+ */
+function configDetail(err) {
+    if (err instanceof ConfigError && err.issues.length > 0) {
+        return `${err.message.split('\n')[0]} ${err.issues
+            .map((i) => `${i.path}: ${i.message}`)
+            .join('; ')}`;
+    }
+    return msg(err);
+}
 export async function runDoctor(opts) {
     const checks = [];
     // 1. Config present + valid.
@@ -39,16 +61,36 @@ export async function runDoctor(opts) {
         }
     }
     catch (err) {
-        checks.push({ name: 'config', ok: false, detail: msg(err) });
+        checks.push({ name: 'config', ok: false, detail: configDetail(err) });
     }
     // 2. API key resolvable (never print the key itself).
+    //
+    // Keys are stored PER SERVER URL, so without a valid config there is no
+    // server to look one up by — the lookup cannot run, it does not fail. Saying
+    // "No API key found" here asserted something false about a key that was
+    // present and correct, and sent the owner hunting through a credentials file
+    // that had nothing wrong with it. Report the truth: skipped, and what IS
+    // saved, so they can see for themselves.
     let apiKey;
+    const savedScopes = listCredentialServers(opts.credentialsPath);
     try {
-        apiKey = resolveApiKey({ server: config?.server });
-        checks.push({ name: 'apiKey', ok: true, detail: 'resolved from env/credentials' });
+        apiKey = resolveApiKey({ server: config?.server, credentialsPath: opts.credentialsPath });
+        // Name what the key can DO, not just that it exists. A pk_ holder
+        // otherwise discovers the targets:write line mid-publish, as a bare 403.
+        checks.push({
+            name: 'apiKey',
+            ok: true,
+            detail: `resolved from env/credentials · ${keyCapability(apiKey).summary}`,
+        });
     }
     catch (err) {
-        checks.push({ name: 'apiKey', ok: false, detail: msg(err) });
+        checks.push({
+            name: 'apiKey',
+            ok: false,
+            detail: config
+                ? msg(err)
+                : `skipped — needs a valid config (keys are saved per server URL)${savedScopes.length > 0 ? `; saved: ${savedScopes.join(', ')}` : ''}`,
+        });
     }
     // 3. Server reachable + token accepted (no retries — doctor wants fast feedback).
     if (config && apiKey) {

package/dist/commands/init.d.ts

@@ -8,7 +8,7 @@
  * action only supplies overrides and prints next steps.
  */
 import type { FileFormat } from '../config.js';
-import type { LionRapidApiClient } from '../api-client.js';
+import type { LionRapidApiClient, FetchImpl } from '../api-client.js';
 /**
  * Harvest the target locales a repo *already has* by matching the detected
  * `target` patterns against real files — so `init` can scaffold what's on
@@ -39,6 +39,65 @@ export type LocaleDefaults = {
  * `init` keeps working fully offline.
  */
 export declare function fetchLocaleDefaults(client: Pick<LionRapidApiClient, 'getProjectConfig'>): Promise<LocaleDefaults>;
+export interface EnsureKeyOptions {
+    server: string;
+    /** A key supplied on the command line, if any. */
+    key?: string;
+    credentialsPath?: string;
+    /** Whether we may prompt. False in CI, pipes, agent runs. */
+    isTTY: boolean;
+    /**
+     * Which credentials entry a newly typed key lands in. Mirrors `login`'s own
+     * rule: `--server` given means a scoped entry, omitted means `default` —
+     * "my LionRapid account key". Two commands that both save credentials must
+     * not disagree about where they go.
+     */
+    scope?: 'default' | 'server';
+    /** Injectable hidden prompt (defaults to the muted readline one). */
+    promptKey?: () => Promise<string>;
+    fetchImpl?: FetchImpl;
+    /**
+     * Environment to resolve `LIONRAPID_API_KEY` from (defaults to
+     * `process.env`).
+     *
+     * Explicit because the ambient environment is NOT a constant: the monorepo's
+     * full-suite runner (lerna → nx) loads the repo's tracked `.env`, which sets
+     * `LIONRAPID_API_KEY`. Tests that leave this to `process.env` therefore pass
+     * under `npm test -w packages/cli` and fail under `npm test` — a difference
+     * nobody sees until a pre-merge gate runs the whole suite.
+     */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Get a usable API key, prompting and SAVING one if there is none.
+ *
+ * This is what collapses onboarding from three commands to one. `init` already
+ * prompted for a key — and then threw it away, using it only to prefill
+ * locales. You typed the same key into `login` and re-ran `init`. It is now
+ * verified and persisted through the same path `login` uses, so the key you
+ * just typed is the key the next command finds.
+ *
+ * A missing key is NOT refused the way a missing server is (C9): inventing a
+ * server writes a dead host into a committed file, whereas no key just means
+ * `init` cannot prefill locales — the config it writes is still correct.
+ */
+export declare function ensureKey(opts: EnsureKeyOptions): Promise<{
+    key?: string;
+    signedIn: boolean;
+}>;
+/**
+ * What the scaffold will actually push: strings, namespaces, files.
+ *
+ * `init` otherwise ends on a promise ("wrote lionrapid.yml") that the user can
+ * only check by running `push`. Parsing what it just declared turns the last
+ * line into a fact. A source that will not parse contributes nothing rather
+ * than failing the run — `doctor` and `push` are where that becomes an error.
+ */
+export declare function summarizeSources(cwd: string, files: DetectedFile[]): {
+    strings: number;
+    namespaces: number;
+    files: number;
+};
 interface DetectedFile {
     format: FileFormat;
     source: string;
@@ -52,7 +111,8 @@ export interface DetectResult {
 /** Inspect the project for known i18n stacks and propose file mappings. */
 export declare function detectProject(cwd: string): DetectResult;
 export interface InitAnswers {
-    project?: string;
+    /** The project uuid the key resolved to, when the server disclosed one. */
+    projectId?: string;
     server?: string;
     sourceLocale?: string;
     targetLocales?: string[];
@@ -74,6 +134,17 @@ export interface InitResult {
     applied: InitChange[];
     /** Differences left alone: your value stands until you edit or use --force. */
     conflicts: InitChange[];
+    /**
+     * Declared `files[].source` paths with nothing behind them on disk.
+     *
+     * Reconcile matches entries by format+source, so a stale entry is never
+     * touched — a newly detected stanza is appended BESIDE it and reported as a
+     * cheerful `+ files[…]`. The user then meets `doctor: sources: 1 missing`
+     * with two entries and no idea which is wrong, because the one command that
+     * saw both said nothing. A glob counts as missing only when it matches no
+     * file: the pattern itself is not a path.
+     */
+    missingSources: string[];
 }
 export declare function runInit(cwd: string, answers?: InitAnswers): InitResult;
 export {};

package/dist/commands/login.d.ts

@@ -10,10 +10,25 @@
  * `default`. The key itself is never echoed or included in any envelope.
  */
 import { type FetchImpl } from '../api-client.js';
-export declare const DEFAULT_SERVER = "https://api.lionrapid.com";
+/**
+ * The server a bare `login`/`init` targets. THE only copy of this host — a
+ * second literal in `init.ts` is how it silently drifted before.
+ *
+ * `api.lionrapid.com` (the previous value) has no DNS record, so every fresh
+ * `init` wrote an unreachable server; credentials are then saved per server
+ * URL, the next lookup misses, and the CLI blames a missing API key.
+ */
+export declare const DEFAULT_SERVER = "https://app.lionrapid.com";
 export interface LoginOptions {
     /** Save the key scoped to this server URL (omitted: save as `default`). */
     server?: string;
+    /**
+     * Override which entry to write. `init` needs this: it has already resolved
+     * a server to VERIFY against (possibly from the repo's yml or the single
+     * saved credential), but should still write `default` unless the user
+     * actually passed `--server`. Defaults to login's own rule.
+     */
+    scope?: 'default' | 'server';
     /** The API key (omitted: hidden interactive prompt). */
     key?: string;
     /** Credentials file path (defaults to ~/.lionrapid/credentials). */
@@ -31,17 +46,48 @@ export interface LoginResult {
     credentialsPath: string;
 }
 export interface LogoutOptions {
+    /** Remove exactly this scope. */
     server?: string;
+    /** Remove every scope and delete the file. */
+    all?: boolean;
     credentialsPath?: string;
+    /**
+     * Ask which scope to remove when several are saved. Returning `undefined`
+     * cancels. Omitted = nothing can ask (CI, pipes), which REFUSES rather than
+     * guessing — see {@link runLogout}.
+     */
+    choose?: (scopes: string[]) => Promise<string | undefined> | string | undefined;
 }
 export interface LogoutResult {
-    scope: 'default' | 'server';
-    /** True when an entry was actually deleted. */
+    /** The entry removed: a server URL, `default`, or `all`. */
+    scope: string;
+    /** True when something was actually deleted. */
     removed: boolean;
+    /** How many entries went (1, or the whole file under `--all`). */
+    removedScopes: number;
     credentialsPath: string;
 }
 export declare function runLogin(opts?: LoginOptions): Promise<LoginResult>;
-export declare function runLogout(opts?: LogoutOptions): LogoutResult;
+/**
+ * Remove a saved credential.
+ *
+ * Bare `logout` used to remove ONLY `default` — surprising when you hold three
+ * scopes and expected to be signed out, and a silent no-op when you hold one
+ * scoped key and no default at all. The shape now (owner's decision,
+ * 2026-08-07):
+ *
+ *   logout                  one scope saved  → remove it
+ *                           several saved    → ask which
+ *                           non-interactive  → refuse, naming --server / --all
+ *   logout --server <url>   remove that scope
+ *   logout --all            remove everything, delete the file
+ *
+ * No silent partial sign-out, and no destructive default. The picker appears
+ * only where the answer is genuinely ambiguous, so the common one-scope case
+ * stays a single keystroke. Deleting a credential is not something to guess
+ * at: with several saved and nothing able to ask, it refuses.
+ */
+export declare function runLogout(opts?: LogoutOptions): Promise<LogoutResult>;
 /** Hidden interactive prompt (no echo) via node:readline — no new dependency. */
 export declare function promptHidden(question?: string): Promise<string>;
 //# sourceMappingURL=login.d.ts.map

package/dist/commands/login.js

@@ -14,9 +14,17 @@ import { dirname } from 'node:path';
 import { createInterface } from 'node:readline';
 import { ApiKeyError, assertKeyCharset, defaultCredentialsPath, findConfigPath, loadConfig, } from '../config.js';
 import { LionRapidApiClient } from '../api-client.js';
-export const DEFAULT_SERVER = 'https://api.lionrapid.com';
+/**
+ * The server a bare `login`/`init` targets. THE only copy of this host — a
+ * second literal in `init.ts` is how it silently drifted before.
+ *
+ * `api.lionrapid.com` (the previous value) has no DNS record, so every fresh
+ * `init` wrote an unreachable server; credentials are then saved per server
+ * URL, the next lookup misses, and the CLI blames a missing API key.
+ */
+export const DEFAULT_SERVER = 'https://app.lionrapid.com';
 export async function runLogin(opts = {}) {
-    const scope = opts.server ? 'server' : 'default';
+    const scope = opts.scope ?? (opts.server ? 'server' : 'default');
     const server = normalizeServer(opts.server ?? repoServer(opts.cwd) ?? DEFAULT_SERVER);
     const key = (opts.key ?? (await (opts.promptKey ?? promptHidden)())).trim();
     if (!key)
@@ -38,24 +46,70 @@ export async function runLogin(opts = {}) {
     writeCreds(path, creds);
     return { server, scope, credentialsPath: path };
 }
-export function runLogout(opts = {}) {
-    const scope = opts.server ? 'server' : 'default';
-    const entry = opts.server ? normalizeServer(opts.server) : 'default';
+/**
+ * Remove a saved credential.
+ *
+ * Bare `logout` used to remove ONLY `default` — surprising when you hold three
+ * scopes and expected to be signed out, and a silent no-op when you hold one
+ * scoped key and no default at all. The shape now (owner's decision,
+ * 2026-08-07):
+ *
+ *   logout                  one scope saved  → remove it
+ *                           several saved    → ask which
+ *                           non-interactive  → refuse, naming --server / --all
+ *   logout --server <url>   remove that scope
+ *   logout --all            remove everything, delete the file
+ *
+ * No silent partial sign-out, and no destructive default. The picker appears
+ * only where the answer is genuinely ambiguous, so the common one-scope case
+ * stays a single keystroke. Deleting a credential is not something to guess
+ * at: with several saved and nothing able to ask, it refuses.
+ */
+export async function runLogout(opts = {}) {
     const path = opts.credentialsPath ?? defaultCredentialsPath();
+    const nothing = (scope) => ({
+        scope,
+        removed: false,
+        removedScopes: 0,
+        credentialsPath: path,
+    });
     if (!existsSync(path))
-        return { scope, removed: false, credentialsPath: path };
+        return nothing(opts.all ? 'all' : (opts.server ?? 'default'));
     const creds = readCreds(path);
-    const removed = Object.prototype.hasOwnProperty.call(creds, entry);
-    if (removed) {
-        delete creds[entry];
-        if (Object.keys(creds).length === 0) {
-            rmSync(path);
-        }
-        else {
-            writeCreds(path, creds);
-        }
+    const scopes = Object.keys(creds);
+    if (opts.all) {
+        if (scopes.length === 0)
+            return nothing('all');
+        rmSync(path);
+        return { scope: 'all', removed: true, removedScopes: scopes.length, credentialsPath: path };
+    }
+    const entry = opts.server
+        ? normalizeServer(opts.server)
+        : scopes.length === 1
+            ? scopes[0]
+            : scopes.length === 0
+                ? undefined
+                : await pick(scopes, opts.choose, path);
+    if (entry === undefined)
+        return nothing(opts.server ?? 'default');
+    if (!Object.prototype.hasOwnProperty.call(creds, entry))
+        return nothing(entry);
+    delete creds[entry];
+    if (Object.keys(creds).length === 0)
+        rmSync(path);
+    else
+        writeCreds(path, creds);
+    return { scope: entry, removed: true, removedScopes: 1, credentialsPath: path };
+}
+/** Ask which scope to drop, or refuse when nothing can ask. */
+async function pick(scopes, choose, path) {
+    if (!choose) {
+        throw new ApiKeyError(`${scopes.length} saved credentials in ${path} — which one?\n` +
+            `${scopes.map((s) => `  · ${s}`).join('\n')}\n` +
+            '  Name one with `lionrapid logout --server <url>`, or remove them all with\n' +
+            '  `lionrapid logout --all`.');
     }
-    return { scope, removed, credentialsPath: path };
+    return choose(scopes);
 }
 /** Match the `config.server` normalization so scoped lookups hit exactly. */
 function normalizeServer(server) {

package/dist/commands/pull.d.ts

@@ -26,6 +26,11 @@ export interface PullFileResult {
     added?: number;
     updated?: number;
     keptLocal?: number;
+    /**
+     * Keys kept because the local file was edited since the last pull — the
+     * server value was NOT written over them. Absent is the normal case.
+     */
+    conflicts?: string[];
     /** Set when this file failed (fetch or write) — the file was not written. */
     error?: string;
 }
@@ -40,6 +45,14 @@ export interface PullResult {
     /** True when this was a dry run — no files were written. */
     dryRun?: boolean;
 }
+export interface MergeOptions {
+    /**
+     * Bare key → the hash the server last gave us for this locale, from the
+     * lock. Absent (no lock, or a key the lock has never seen) means today's
+     * behaviour: server wins. A first pull must not look like 653 conflicts.
+     */
+    lockTargets?: Record<string, string>;
+}
 /**
  * Overlay fetched entries onto the existing local file: server wins per key,
  * local-only entries survive, existing key order is preserved and new keys
@@ -47,11 +60,12 @@ export interface PullResult {
  * has no comment channel, so replacing the entry would silently drop them.
  * Exported for direct unit testing.
  */
-export declare function mergeEntries(local: TranslationEntry[], fetched: TranslationEntry[]): {
+export declare function mergeEntries(local: TranslationEntry[], fetched: TranslationEntry[], opts?: MergeOptions): {
     entries: TranslationEntry[];
     added: number;
     updated: number;
     keptLocal: number;
+    conflicts: string[];
 };
 export declare function runPull(config: LionRapidConfig, client: LionRapidApiClient, opts: PullOptions): Promise<PullResult>;
 //# sourceMappingURL=pull.d.ts.map

package/dist/commands/pull.js

@@ -10,7 +10,42 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { getAdapter } from '../adapters/index.js';
+import { saveHistory } from '../history.js';
+import { hashSource, lockKey, readLock, writeLock } from '../lockfile.js';
 import { assertInside, mapLimit, resolveConcurrency } from './context.js';
+/** The lock's last-known server hashes for one namespace+locale, by bare key. */
+function lockTargetsFor(lock, namespace, locale) {
+    const out = {};
+    const prefix = `${namespace}:`;
+    for (const [key, entry] of Object.entries(lock.entries)) {
+        if (!key.startsWith(prefix))
+            continue;
+        const hash = entry.targets?.[locale]?.hash;
+        if (hash)
+            out[key.slice(prefix.length)] = hash;
+    }
+    return out;
+}
+/**
+ * Fold a namespace's fetched rows into the lock, for one target locale.
+ *
+ * `sourceHash` is deliberately left alone: pull sees TARGET rows, and claiming
+ * to know the server's source state from them would let the next push skip a
+ * source string it never actually confirmed.
+ */
+function recordServerState(lock, namespace, locale, fetched, pulledAt) {
+    for (const entry of fetched) {
+        const key = lockKey(namespace, entry.key);
+        const existing = lock.entries[key] ?? { sourceHash: '' };
+        lock.entries[key] = {
+            ...existing,
+            targets: {
+                ...existing.targets,
+                [locale]: { hash: hashSource(entry.value), serverUpdatedAt: pulledAt },
+            },
+        };
+    }
+}
 /**
  * Overlay fetched entries onto the existing local file: server wins per key,
  * local-only entries survive, existing key order is preserved and new keys
@@ -18,9 +53,10 @@ import { assertInside, mapLimit, resolveConcurrency } from './context.js';
  * has no comment channel, so replacing the entry would silently drop them.
  * Exported for direct unit testing.
  */
-export function mergeEntries(local, fetched) {
+export function mergeEntries(local, fetched, opts = {}) {
     const newByKey = new Map(fetched.map((e) => [e.key, e]));
     const entries = [];
+    const conflicts = [];
     let updated = 0;
     let keptLocal = 0;
     for (const l of local) {
@@ -30,6 +66,21 @@ export function mergeEntries(local, fetched) {
             entries.push(l);
             continue;
         }
+        // THE MISSING DIMENSION. Presence alone cannot tell a local EDIT from a
+        // local-only key; the lock's last-known server hash can. A local value
+        // that no longer matches what the server last gave us was edited here
+        // since the last pull, so taking the server's value would destroy it.
+        //
+        // The asymmetry is deliberate: losing a translator's work is worse than a
+        // stale local file, so the destructive direction needs `--force`.
+        const lastKnown = opts.lockTargets?.[l.key];
+        if (lastKnown !== undefined && hashSource(l.value) !== lastKnown) {
+            conflicts.push(l.key);
+            keptLocal += 1;
+            entries.push(l);
+            newByKey.delete(l.key);
+            continue;
+        }
         if (JSON.stringify(f.value) !== JSON.stringify(l.value))
             updated += 1;
         entries.push(l.comment !== undefined ? { ...f, comment: l.comment } : f);
@@ -42,7 +93,7 @@ export function mergeEntries(local, fetched) {
             added += 1;
         }
     }
-    return { entries, added, updated, keptLocal };
+    return { entries, added, updated, keptLocal, conflicts };
 }
 /** Union of source keys per namespace, for "pending" reporting. */
 function sourceKeysByNamespace(config, cwd) {
@@ -113,6 +164,12 @@ export async function runPull(config, client, opts) {
                 : null;
         catalogContent.set(file, base);
     }
+    // The lockfile records what the server last said, so the NEXT push can send
+    // only what changed and the next pull can tell a local edit from a
+    // local-only key. Merged into whatever is already there: another locale or
+    // namespace fetched on an earlier run must not be erased by this one.
+    const lock = readLock(opts.cwd);
+    const pulledAt = new Date().toISOString();
     const locales = [];
     for (const locale of config.targetLocales) {
         const fileResults = [];
@@ -139,10 +196,28 @@ export async function runPull(config, client, opts) {
                 // wholesale overwrite.
                 let toWrite = fetched;
                 let diff;
+                let conflicts;
+                // `--force` is about to discard whatever is in this file. Keep a copy
+                // first — symmetric with `push --force`, and the only thing standing
+                // between the flag and a translator's lost work.
+                if (opts.force && !opts.dryRun && existsSync(absPath)) {
+                    saveHistory(opts.cwd, {
+                        direction: 'pull',
+                        namespace,
+                        locale,
+                        reason: `pull --force replaced ${relPath} with the server's version`,
+                        entries: adapter.parse(readFileSync(absPath, 'utf8')),
+                    });
+                }
                 if (!opts.force && fetched.length > 0 && existsSync(absPath)) {
-                    const merged = mergeEntries(adapter.parse(readFileSync(absPath, 'utf8')), fetched);
+                    const merged = mergeEntries(adapter.parse(readFileSync(absPath, 'utf8')), fetched, {
+                        lockTargets: lockTargetsFor(lock, namespace, locale),
+                    });
                     toWrite = merged.entries;
                     diff = { added: merged.added, updated: merged.updated, keptLocal: merged.keptLocal };
+                    if (merged.conflicts.length > 0) {
+                        conflicts = merged.conflicts.map((key) => lockKey(namespace, key));
+                    }
                 }
                 // Don't clobber an existing target with an empty result (locked/pending).
                 // Dry run computes counts but writes nothing.
@@ -154,7 +229,16 @@ export async function runPull(config, client, opts) {
                         flat: file.flat,
                     }));
                 }
-                fileResults.push({ target: relPath, count: fetched.length, ...(diff ?? {}) });
+                // Record what the SERVER just said. `pull` is the only writer of
+                // `serverUpdatedAt` — push must never fabricate a server state it did
+                // not observe.
+                recordServerState(lock, namespace, locale, fetched, pulledAt);
+                fileResults.push({
+                    target: relPath,
+                    count: fetched.length,
+                    ...(diff ?? {}),
+                    ...(conflicts ? { conflicts } : {}),
+                });
             }
             catch (err) {
                 firstError ??= err;
@@ -237,6 +321,10 @@ export async function runPull(config, client, opts) {
     if (all.length > 0 && all.every((f) => f.error) && firstError !== undefined) {
         throw firstError;
     }
+    // A dry run writes no lock for the same reason it writes no files: it did
+    // not change anything, so nothing new is known.
+    if (!opts.dryRun)
+        writeLock(opts.cwd, lock);
     return { locales, ...(opts.dryRun ? { dryRun: true } : {}) };
 }
 //# sourceMappingURL=pull.js.map

package/dist/commands/push.d.ts

@@ -5,11 +5,34 @@
  * rows via `sync/batch`; the server then queues machine translation for the
  * configured target locales.
  *
+ * `sync/batch` answers 202 Accepted — the rows are QUEUED, not yet stored. So
+ * every batch also yields job ids ({@link PushedJob}), which is the only thing
+ * that lets a caller tell "the backend stored this" from "the backend dropped
+ * it". Without them a push that dead-letters looks exactly like one that worked.
+ *
  * `--target <locale>` mode uploads an already-translated target file as drafts
  * via `targets/batch`, optionally publishing them with `--publish`.
  */
 import { type LionRapidConfig } from '../config.js';
 import type { LionRapidApiClient } from '../api-client.js';
+/**
+ * A sync job the server queued for one batch of this push.
+ *
+ * `sync/batch` answers 202 — accepted, not stored. This is the receipt that
+ * makes the difference observable: it says which file's keys are riding on
+ * which job, so `lionrapid status <id>` can later answer "stored" or "dropped".
+ * Target mode has no equivalent because `targets/batch` writes synchronously.
+ */
+export interface PushedJob {
+    id: string;
+    /** The file whose keys were in this batch. */
+    file: string;
+    namespace: string;
+    /** Keys in this batch (a large file is chunked into several jobs). */
+    keys: number;
+    /** Status the server reported at enqueue time (`pending`). */
+    status: string;
+}
 export interface PushOptions {
     cwd: string;
     /** Push an already-translated target locale instead of the source. */
@@ -18,22 +41,72 @@ export interface PushOptions {
     publish?: boolean;
     /** Parse + count what would be pushed, but make no network calls. */
     dryRun?: boolean;
+    /**
+     * Called as each batch is accepted. The caller persists these, so ids queued
+     * before a later total failure are not lost when `runPush` rethrows.
+     */
+    onJob?: (job: PushedJob) => void;
+    /**
+     * Project root for `.lionrapid/lock.json`. Omitted = no lock at all: every
+     * key is sent, exactly as before L2. Tests use it to point at a scratch dir;
+     * the CLI passes the project root.
+     */
+    lockPath?: string;
+    /**
+     * Send what the SERVER lacks and nothing else, asking the server rather than
+     * trusting the lock. This is the recovery for a job that was accepted (202)
+     * and then dead-lettered: the lock records those rows as sent, so only the
+     * server can say they are missing.
+     */
+    backfillMissing?: boolean;
+    /**
+     * Send everything, overwriting server values — saving the server's current
+     * source rows to `.lionrapid/history/` first, the way `pull --force` saves
+     * the local ones.
+     */
+    force?: boolean;
 }
 export interface PushFileResult {
     file: string;
     count: number;
     skipped?: boolean;
+    /** Keys this file already had on the server, per the lock — not re-sent. */
+    unchanged?: number;
     /** Set when this file failed (parse or upload) — it was not (fully) pushed. */
     error?: string;
 }
 export interface PushResult {
     mode: 'source' | 'target';
+    /**
+     * Keys the CLI SENT. Not the number stored — the server queues them, so
+     * `jobs` is what says whether they landed.
+     */
     pushed: number;
+    /** Keys the lock says the server already has, so they were not sent again. */
+    skipped: number;
+    /**
+     * What this push is doing, split so `--dry-run` can answer the question you
+     * ran it to ask: am I ADDING strings, or overwriting ones that already
+     * exist? "2 to send" hides which two. Source mode only.
+     */
+    diff?: {
+        added: number;
+        changed: number;
+        unchanged: number;
+    };
     files: PushFileResult[];
+    /** Jobs the server queued for this push (source mode only; empty on a dry run). */
+    jobs: PushedJob[];
     /** True when `--publish` was requested but no editor token was available. */
     publishSkipped?: boolean;
     /** True when this was a dry run — nothing was sent to the server. */
     dryRun?: boolean;
+    /**
+     * Whether the config's `projectId` was checked against the key's project.
+     * `unavailable` means the server disclosed none — the guard could not arm,
+     * which is never a reason to block a push.
+     */
+    projectCheck?: 'ok' | 'unavailable';
 }
 export declare function runPush(config: LionRapidConfig, client: LionRapidApiClient, opts: PushOptions): Promise<PushResult>;
 //# sourceMappingURL=push.d.ts.map