@lionrapid/cli 0.2.1 → 0.3.0

package/dist/commands/doctor.d.ts

@@ -5,7 +5,8 @@
  * turned into a failed check.
  *
  * Checks: config found + valid → API key resolvable → server reachable + the
- * token works (ping) → declared source files present.
+ * token works (config:read probe — pk_-compatible) → declared source files
+ * present.
  */
 import { type FetchImpl } from '../api-client.js';
 export interface DoctorCheck {

package/dist/commands/doctor.js

@@ -5,11 +5,12 @@
  * turned into a failed check.
  *
  * Checks: config found + valid → API key resolvable → server reachable + the
- * token works (ping) → declared source files present.
+ * token works (config:read probe — pk_-compatible) → declared source files
+ * present.
  */
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { findConfigPath, loadConfig, resolveApiKey, } from '../config.js';
+import { expandGlobEntries, findConfigPath, loadConfig, resolveApiKey, } from '../config.js';
 import { LionRapidApiClient } from '../api-client.js';
 function msg(err) {
     return err instanceof Error ? err.message.split('\n')[0] : String(err);
@@ -29,6 +30,7 @@ export async function runDoctor(opts) {
         }
         else {
             config = loadConfig(path);
+            config = { ...config, files: expandGlobEntries(config.files, opts.cwd) };
             checks.push({
                 name: 'config',
                 ok: true,
@@ -57,11 +59,13 @@ export async function runDoctor(opts) {
                 retries: 0,
                 fetchImpl: opts.fetchImpl,
             });
-            const res = await client.ping();
+            // config:read probe — works for every key class incl. publishable pk_
+            // (editor/workflow needs targets:write and would fail pk_ keys).
+            const pc = await client.getProjectConfig();
             checks.push({
                 name: 'server',
                 ok: true,
-                detail: `${config.server} reachable · ${res.isPmAdmin ? 'pm-admin' : 'integration'} token`,
+                detail: `${config.server} reachable · project locales: ${pc.defaultLocale || '?'} → ${pc.languages.filter((l) => l !== pc.defaultLocale).join(', ') || '?'}`,
             });
         }
         catch (err) {

package/dist/commands/init.d.ts

@@ -8,10 +8,42 @@
  * action only supplies overrides and prints next steps.
  */
 import type { FileFormat } from '../config.js';
+import type { LionRapidApiClient } 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
+ * disk instead of a hardcoded guess when the server has nothing to say.
+ * Multi-locale catalogs (no `{locale}` in the path) can't be detected this
+ * way and are skipped. Returns sorted, deduped locales minus `sourceLocale`.
+ */
+export declare function detectLocalesOnDisk(cwd: string, sourceLocale: string): string[];
+/**
+ * What the project-config lookup produced. `no-targets` is deliberately
+ * distinct from `unavailable`: a brand-new project answers perfectly well and
+ * simply has no target languages yet — reporting that as "couldn't read your
+ * locales" hides the one thing the user has to go do.
+ */
+export type LocaleDefaults = {
+    status: 'ok';
+    sourceLocale: string;
+    targetLocales: string[];
+} | {
+    status: 'no-targets';
+    sourceLocale: string;
+} | {
+    status: 'unavailable';
+};
+/**
+ * Fetch the project's configured locales for scaffold prefill. Never throws —
+ * offline, an older server, or a bad key all degrade to `unavailable`, so
+ * `init` keeps working fully offline.
+ */
+export declare function fetchLocaleDefaults(client: Pick<LionRapidApiClient, 'getProjectConfig'>): Promise<LocaleDefaults>;
 interface DetectedFile {
     format: FileFormat;
     source: string;
     target: string;
+    namespace?: string;
 }
 export interface DetectResult {
     stacks: string[];
@@ -26,10 +58,22 @@ export interface InitAnswers {
     targetLocales?: string[];
     force?: boolean;
 }
+/** One field `init` changed, or wanted to change but didn't. */
+export interface InitChange {
+    path: string;
+    from?: string;
+    to: string;
+}
 export interface InitResult {
     configPath: string;
     yaml: string;
     detected: DetectResult;
+    /** True when there was no config before this run. */
+    created: boolean;
+    /** Changes written (new fields/entries — nothing was overwritten). */
+    applied: InitChange[];
+    /** Differences left alone: your value stands until you edit or use --force. */
+    conflicts: InitChange[];
 }
 export declare function runInit(cwd: string, answers?: InitAnswers): InitResult;
 export {};

package/dist/commands/login.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `login` / `logout` — manage `~/.lionrapid/credentials`, the JSON map
+ * (`{ "default": "sk_…", "<server-url>": "sk_…" }`) that `resolveApiKey`
+ * reads. The key is verified against the server BEFORE persisting (a
+ * config:read probe, so publishable pk_ keys work too) — a failed
+ * verification writes nothing. Directory is 0700, file 0600.
+ *
+ * `--server` writes a server-scoped entry (the per-host opt-in that
+ * `resolveApiKey` demands for non-LionRapid hosts); bare `login` writes
+ * `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";
+export interface LoginOptions {
+    /** Save the key scoped to this server URL (omitted: save as `default`). */
+    server?: string;
+    /** The API key (omitted: hidden interactive prompt). */
+    key?: string;
+    /** Credentials file path (defaults to ~/.lionrapid/credentials). */
+    credentialsPath?: string;
+    /** Directory to look for a repo lionrapid.yml whose server becomes the ping target. */
+    cwd?: string;
+    /** Injectable fetch for the verification ping. */
+    fetchImpl?: FetchImpl;
+    /** Injectable prompt (defaults to a muted readline prompt on stderr). */
+    promptKey?: () => Promise<string>;
+}
+export interface LoginResult {
+    server: string;
+    scope: 'default' | 'server';
+    credentialsPath: string;
+}
+export interface LogoutOptions {
+    server?: string;
+    credentialsPath?: string;
+}
+export interface LogoutResult {
+    scope: 'default' | 'server';
+    /** True when an entry was actually deleted. */
+    removed: boolean;
+    credentialsPath: string;
+}
+export declare function runLogin(opts?: LoginOptions): Promise<LoginResult>;
+export declare function runLogout(opts?: LogoutOptions): 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

@@ -0,0 +1,110 @@
+/**
+ * `login` / `logout` — manage `~/.lionrapid/credentials`, the JSON map
+ * (`{ "default": "sk_…", "<server-url>": "sk_…" }`) that `resolveApiKey`
+ * reads. The key is verified against the server BEFORE persisting (a
+ * config:read probe, so publishable pk_ keys work too) — a failed
+ * verification writes nothing. Directory is 0700, file 0600.
+ *
+ * `--server` writes a server-scoped entry (the per-host opt-in that
+ * `resolveApiKey` demands for non-LionRapid hosts); bare `login` writes
+ * `default`. The key itself is never echoed or included in any envelope.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+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';
+export async function runLogin(opts = {}) {
+    const 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)
+        throw new ApiKeyError('No API key provided.');
+    assertKeyCharset(key);
+    // Verify before persisting — a bad key must never land in the file. The
+    // probe is project-config (`config:read`), which every key class carries —
+    // publishable pk_ keys included; the old editor/workflow ping needed
+    // `targets:write` and wrongly rejected pk_ logins.
+    const client = new LionRapidApiClient({
+        baseUrl: server,
+        apiKey: key,
+        fetchImpl: opts.fetchImpl,
+    });
+    await client.getProjectConfig();
+    const path = opts.credentialsPath ?? defaultCredentialsPath();
+    const creds = readCreds(path);
+    creds[scope === 'server' ? server : 'default'] = key;
+    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';
+    const path = opts.credentialsPath ?? defaultCredentialsPath();
+    if (!existsSync(path))
+        return { scope, removed: false, credentialsPath: path };
+    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);
+        }
+    }
+    return { scope, removed, credentialsPath: path };
+}
+/** Match the `config.server` normalization so scoped lookups hit exactly. */
+function normalizeServer(server) {
+    return server.replace(/\/$/, '');
+}
+/** The repo's configured server, when a valid lionrapid.yml is present. */
+function repoServer(cwd) {
+    const path = findConfigPath(cwd);
+    if (!path)
+        return undefined;
+    try {
+        return loadConfig(path).server;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readCreds(path) {
+    if (!existsSync(path))
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (err) {
+        throw new ApiKeyError(`Could not parse credentials file ${path}: ${err instanceof Error ? err.message : String(err)}. Fix or delete it, then retry.`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new ApiKeyError(`Credentials file ${path} is not a JSON object. Fix or delete it, then retry.`);
+    }
+    return parsed;
+}
+function writeCreds(path, creds) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${JSON.stringify(creds, null, 2)}\n`, { mode: 0o600 });
+    // writeFileSync's mode only applies on create — enforce it on merges too.
+    chmodSync(path, 0o600);
+}
+/** Hidden interactive prompt (no echo) via node:readline — no new dependency. */
+export function promptHidden(question = 'API key (input hidden): ') {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+        process.stderr.write(question);
+        rl._writeToOutput = () => { };
+        rl.question('', (answer) => {
+            rl.close();
+            process.stderr.write('\n');
+            resolve(answer);
+        });
+    });
+}
+//# sourceMappingURL=login.js.map

package/dist/commands/pull.d.ts

@@ -9,16 +9,25 @@
  */
 import type { LionRapidConfig } from '../config.js';
 import type { LionRapidApiClient } from '../api-client.js';
+import { type TranslationEntry } from '../adapters/index.js';
 export interface PullOptions {
     cwd: string;
     /** Fetch + count what would be written, but write no files. */
     dryRun?: boolean;
+    /** Overwrite target files wholesale instead of merging (drops local-only keys). */
+    force?: boolean;
     /** Progress callback, invoked as each namespace fetch completes. */
     onProgress?: (done: number, total: number) => void;
 }
 export interface PullFileResult {
     target: string;
     count: number;
+    /** Merge diff vs the existing target (absent on fresh writes and --force). */
+    added?: number;
+    updated?: number;
+    keptLocal?: number;
+    /** Set when this file failed (fetch or write) — the file was not written. */
+    error?: string;
 }
 export interface PullLocaleResult {
     locale: string;
@@ -31,5 +40,18 @@ export interface PullResult {
     /** True when this was a dry run — no files were written. */
     dryRun?: boolean;
 }
+/**
+ * Overlay fetched entries onto the existing local file: server wins per key,
+ * local-only entries survive, existing key order is preserved and new keys
+ * append. Local `comment`s survive even on overlaid keys — the server bundle
+ * 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[]): {
+    entries: TranslationEntry[];
+    added: number;
+    updated: number;
+    keptLocal: number;
+};
 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,40 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { getAdapter } from '../adapters/index.js';
-import { mapLimit, resolveConcurrency } from './context.js';
+import { assertInside, mapLimit, resolveConcurrency } from './context.js';
+/**
+ * Overlay fetched entries onto the existing local file: server wins per key,
+ * local-only entries survive, existing key order is preserved and new keys
+ * append. Local `comment`s survive even on overlaid keys — the server bundle
+ * has no comment channel, so replacing the entry would silently drop them.
+ * Exported for direct unit testing.
+ */
+export function mergeEntries(local, fetched) {
+    const newByKey = new Map(fetched.map((e) => [e.key, e]));
+    const entries = [];
+    let updated = 0;
+    let keptLocal = 0;
+    for (const l of local) {
+        const f = newByKey.get(l.key);
+        if (!f) {
+            keptLocal += 1;
+            entries.push(l);
+            continue;
+        }
+        if (JSON.stringify(f.value) !== JSON.stringify(l.value))
+            updated += 1;
+        entries.push(l.comment !== undefined ? { ...f, comment: l.comment } : f);
+        newByKey.delete(l.key); // consumed — what remains is genuinely new
+    }
+    let added = 0;
+    for (const f of fetched) {
+        if (newByKey.has(f.key)) {
+            entries.push(f);
+            added += 1;
+        }
+    }
+    return { entries, added, updated, keptLocal };
+}
 /** Union of source keys per namespace, for "pending" reporting. */
 function sourceKeysByNamespace(config, cwd) {
     const byNs = new Map();
@@ -31,16 +64,29 @@ export async function runPull(config, client, opts) {
     const sourceKeys = sourceKeysByNamespace(config, opts.cwd);
     const perLocaleFiles = config.files.filter((f) => !getAdapter(f.format).multiLocale);
     const multiFiles = config.files.filter((f) => getAdapter(f.format).multiLocale);
-    // Run-wide namespace cache, keyed `${locale}:${namespace}`.
+    // Run-wide namespace cache, keyed `${locale}:${namespace}`. A failed fetch
+    // is cached as an error instead of aborting the run — one bad namespace
+    // must not zero out a 56-file pull (partial progress, exit 5).
     const nsCache = new Map();
+    const nsErrors = new Map();
+    let firstError;
     const fetchNs = async (locale, namespace) => {
         const cacheKey = `${locale}:${namespace}`;
         const hit = nsCache.get(cacheKey);
         if (hit)
             return hit;
-        const bundle = await client.getNamespace(locale, namespace);
-        nsCache.set(cacheKey, bundle.translations);
-        return bundle.translations;
+        if (nsErrors.has(cacheKey))
+            return null;
+        try {
+            const bundle = await client.getNamespace(locale, namespace);
+            nsCache.set(cacheKey, bundle.translations);
+            return bundle.translations;
+        }
+        catch (err) {
+            firstError ??= err;
+            nsErrors.set(cacheKey, err instanceof Error ? err : new Error(String(err)));
+            return null;
+        }
     };
     // Pre-fetch every needed (locale, namespace) bundle concurrently so the slow
     // network fan-out runs in parallel; the write loops below then read the warm
@@ -75,30 +121,85 @@ export async function runPull(config, client, opts) {
             const adapter = getAdapter(file.format);
             const namespace = file.namespace ?? config.namespace;
             usedNamespaces.add(namespace);
-            const entries = toEntries(await fetchNs(locale, namespace));
             const relPath = file.target.replace('{locale}', locale);
-            // Don't clobber an existing target with an empty result (locked/pending).
-            // Dry run computes counts but writes nothing.
-            if (entries.length > 0 && !opts.dryRun) {
-                const absPath = resolve(opts.cwd, relPath);
-                mkdirSync(dirname(absPath), { recursive: true });
-                writeFileSync(absPath, adapter.serialize(entries, { locale, sourceLocale: config.sourceLocale }));
+            const translations = await fetchNs(locale, namespace);
+            if (translations === null) {
+                fileResults.push({
+                    target: relPath,
+                    count: 0,
+                    error: nsErrors.get(`${locale}:${namespace}`).message,
+                });
+                continue;
+            }
+            const fetched = toEntries(translations);
+            try {
+                const absPath = assertInside(opts.cwd, relPath);
+                // Default is a non-destructive merge with the existing target: server
+                // wins per key, local-only keys survive. `--force` restores the
+                // wholesale overwrite.
+                let toWrite = fetched;
+                let diff;
+                if (!opts.force && fetched.length > 0 && existsSync(absPath)) {
+                    const merged = mergeEntries(adapter.parse(readFileSync(absPath, 'utf8')), fetched);
+                    toWrite = merged.entries;
+                    diff = { added: merged.added, updated: merged.updated, keptLocal: merged.keptLocal };
+                }
+                // Don't clobber an existing target with an empty result (locked/pending).
+                // Dry run computes counts but writes nothing.
+                if (fetched.length > 0 && !opts.dryRun) {
+                    mkdirSync(dirname(absPath), { recursive: true });
+                    writeFileSync(absPath, adapter.serialize(toWrite, {
+                        locale,
+                        sourceLocale: config.sourceLocale,
+                        flat: file.flat,
+                    }));
+                }
+                fileResults.push({ target: relPath, count: fetched.length, ...(diff ?? {}) });
+            }
+            catch (err) {
+                firstError ??= err;
+                fileResults.push({
+                    target: relPath,
+                    count: 0,
+                    error: err instanceof Error ? err.message : String(err),
+                });
             }
-            fileResults.push({ target: relPath, count: entries.length });
         }
         for (const file of multiFiles) {
             const adapter = getAdapter(file.format);
             const namespace = file.namespace ?? config.namespace;
             usedNamespaces.add(namespace);
-            const entries = toEntries(await fetchNs(locale, namespace));
-            if (entries.length > 0) {
-                const merged = adapter.mergeLocale(catalogContent.get(file) ?? null, entries, locale);
-                catalogContent.set(file, merged);
+            const translations = await fetchNs(locale, namespace);
+            if (translations === null) {
+                fileResults.push({
+                    target: file.target,
+                    count: 0,
+                    error: nsErrors.get(`${locale}:${namespace}`).message,
+                });
+                continue;
+            }
+            const entries = toEntries(translations);
+            try {
+                if (entries.length > 0) {
+                    const merged = adapter.mergeLocale(catalogContent.get(file) ?? null, entries, locale);
+                    catalogContent.set(file, merged);
+                }
+                fileResults.push({ target: file.target, count: entries.length });
+            }
+            catch (err) {
+                firstError ??= err;
+                fileResults.push({
+                    target: file.target,
+                    count: 0,
+                    error: err instanceof Error ? err.message : String(err),
+                });
             }
-            fileResults.push({ target: file.target, count: entries.length });
         }
         let pending = 0;
         for (const namespace of usedNamespaces) {
+            // A failed namespace's state is unknown — don't report its keys pending.
+            if (nsErrors.has(`${locale}:${namespace}`))
+                continue;
             const have = new Set(Object.keys(nsCache.get(`${locale}:${namespace}`) ?? {}));
             for (const key of sourceKeys.get(namespace) ?? new Set()) {
                 if (!have.has(key))
@@ -112,12 +213,30 @@ export async function runPull(config, client, opts) {
         for (const file of multiFiles) {
             const content = catalogContent.get(file);
             if (content != null) {
-                const absPath = resolve(opts.cwd, file.target);
-                mkdirSync(dirname(absPath), { recursive: true });
-                writeFileSync(absPath, content);
+                try {
+                    const absPath = assertInside(opts.cwd, file.target);
+                    mkdirSync(dirname(absPath), { recursive: true });
+                    writeFileSync(absPath, content);
+                }
+                catch (err) {
+                    firstError ??= err;
+                    const message = err instanceof Error ? err.message : String(err);
+                    for (const loc of locales) {
+                        for (const f of loc.files) {
+                            if (f.target === file.target && !f.error)
+                                f.error = message;
+                        }
+                    }
+                }
             }
         }
     }
+    // Partial progress is a result; total failure keeps today's error contract —
+    // rethrow the first error so the exit-code mapping is unchanged.
+    const all = locales.flatMap((l) => l.files);
+    if (all.length > 0 && all.every((f) => f.error) && firstError !== undefined) {
+        throw firstError;
+    }
     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,16 +41,29 @@ 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;
 }
 export interface PushFileResult {
     file: string;
     count: number;
     skipped?: boolean;
+    /** 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;
     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. */