@lionrapid/cli 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -3,6 +3,163 @@
 All notable changes to `@lionrapid/cli`. Format based on
 [Keep a Changelog](https://keepachangelog.com/); this package follows semver.
 
+## 0.2.2 — 2026-07-27
+
+### Added
+
+- **`files[].flat` — dotted keys round-trip as dotted.** JSON/YAML targets are
+  written nested by default, so a key pushed flat (`hero.title`) came back as
+  `{"hero": {"title": …}}` — breaking flat-keyed consumers (CMS imports,
+  webhook payloads) that fed the file back in. `flat: true` on a `files` entry
+  keeps dotted keys literal on `pull`. Only valid for `json`/`yaml` (every
+  other format is flat by nature); glob entries carry the flag onto each
+  expanded file.
+
+- **`lionrapid login` / `lionrapid logout`.** The credentials file the CLI
+  reads finally has an author: `login` verifies the key against the server
+  _before_ persisting (a failed ping writes nothing), writes
+  `~/.lionrapid/credentials` `0600` in a `0700` dir, and merges entries — bare
+  `login` writes `default`, `--server <url>` writes the server-scoped entry
+  that 0.2.1's trust boundary requires for non-LionRapid hosts. Omitting
+  `--key` gives a hidden interactive prompt; the key is never echoed. `logout`
+  removes an entry and deletes the file when empty. At read time the CLI now
+  warns (once per file) when the credentials file is world-readable.
+- **Glob file entries with derived namespaces.** `files[].source` may be a
+  glob (`locales/en/*.json`); `target` and `namespace` then carry a
+  `{basename}` token substituted per matched file with its extension-less
+  name. One stanza replaces N hand-written entries (e.g. one file per page
+  slug → one namespace per page). Expansion happens at config load, is
+  deterministic (sorted), and a glob matching nothing warns instead of
+  silently doing nothing. A glob without `{basename}` in _both_ `target` and
+  `namespace` is rejected as ambiguous.
+- **Per-attempt request timeouts.** Every request carries a fresh
+  `AbortSignal.timeout` budget (default 30 s) so a hung connection can no
+  longer block `push`/`pull`/`doctor` forever. Timeouts are retried like other
+  transient failures and report "timed out after Xms". Tune via
+  `LIONRAPID_TIMEOUT` or the global `--timeout <ms>` flag.
+- **`validate --allow-locked`** downgrades locked (unapproved) namespaces to a
+  warning so brand-new namespaces don't fail CI.
+- **Modern `init`: layout detection, prompts, and locale prefill.** `init`
+  detects a per-namespace `locales/en/<ns>.json` layout and scaffolds the glob
+  stanza for it (flat layouts keep the concrete entry). On a TTY it prompts
+  for the project label, server URL, and — new — an optional API key
+  (`--key`, stored credentials, or a hidden prompt) used to prefill
+  `sourceLocale`/`targetLocales` from the project's dashboard configuration
+  via `GET /api/integrations/project-config`. Everything degrades gracefully:
+  non-TTY runs never block, and offline/older servers fall back to the static
+  defaults. A project that simply has **no target languages yet** is reported
+  as exactly that — with the remediation (add them in the dashboard, re-run
+  `init --force`) and a warning that the scaffolded `targetLocales` are
+  placeholders — rather than being misreported as an unreachable server. The
+  overwrite guard fires before any prompt, and next-steps route credentials
+  through `lionrapid login` (and skip that advice when a stored credential
+  was already used).
+- **`init` re-runs safely and stops asking for what it already knows.** It
+  defaults its server to the repo's config or the one you logged into (so
+  `lionrapid login` then a bare `lionrapid init` is the whole setup), and
+  re-running it is no longer an error: newly-detected files and locales merge
+  in and are listed, anything that would _change_ a value you set is reported
+  as a conflict (`yours:` / `project:`) and left untouched, and a run with
+  nothing new leaves the file byte-identical — hand-edits and comments
+  survive. `--force` still rewrites wholesale.
+- **`init` no longer invents locales.** When neither the project nor the repo
+  yields target languages, `targetLocales` is written empty with a warning
+  saying so, instead of scaffolding a fabricated `[es, fr]` that produced
+  phantom pending keys on every later `pull`/`validate`.
+- **`init` detects `.po`, XLIFF and standalone YAML catalogs.** Detection is
+  no longer limited to Flutter/iOS/Android/Rails/JSON: conventional catalog
+  roots (`po/`, `locale/`, `locales/`, `translations/`, `i18n/`, `src/locale/`,
+  `Content/Localization/`, …) are searched for `.po`, `.xlf`/`.xliff` and
+  `.yml`/`.yaml`, and the source→target stanza is derived from the files that
+  actually exist — covering gettext `locale/{locale}/LC_MESSAGES/…`, flat
+  `po/{locale}.po`, locale-suffixed `messages.{locale}.xlf`, and Unreal/Godot's
+  `Content/Localization/<Target>/{locale}/…`. Formats accumulate, so a repo
+  with both JSON and PO trees gets both stanzas.
+- **`init` detects the locales already in your repo.** Locale resolution is
+  now a ladder — explicit `--source`/`--targets`, then the project's server
+  config, then locales found on disk by matching the detected `target`
+  pattern (`locales/{locale}/…`, `app_{locale}.arb`, `values-{locale}/…`,
+  `{locale}.lproj/…`), then static placeholders. Offline or on a project with
+  no targets yet, `init` scaffolds what the repo actually has instead of
+  guessing. When the server _does_ have targets it stays authoritative, and a
+  locale that exists only on disk is reported as a mismatch (`present in your
+files but not configured on the project`) rather than silently merged —
+  those files would never be filled by `pull`.
+
+### Changed
+
+- **`push` makes partial progress instead of aborting.** One failing
+  file/namespace (a rate limit on a many-namespace site, one corrupt source
+  file) no longer zeroes the run: the remaining files still upload, failures
+  render per file with a summary and appear as `error` fields in the `--json`
+  envelope (`ok: false`), and the exit code is 5 (PARTIAL). Because the sync
+  endpoints upsert by composite key, re-running `push` retries just the
+  failures. When every attempted file fails, the first error is rethrown with
+  the usual exit taxonomy.
+- **A `429` without `Retry-After` now waits a rate-limit window (30 s), not
+  millisecond jitter.** The server's rate-limit responses carry no
+  `Retry-After` header and its limits are per-minute windows — the old jittered
+  backoff (~2 s total across all retries) could never outlive one, so every
+  429 exhausted its retries and was effectively fatal. Concretely: a site with
+  more than 30 namespaces died mid-push at the sync endpoint's 30/min limit;
+  now push rides the window out and completes.
+- **`pull` makes partial progress instead of aborting.** On a multi-namespace
+  pull, a failing namespace (or a corrupt local target) no longer zeroes the
+  run: successful files still write, failures render per file with a summary
+  and appear as `error` fields in the `--json` envelope (`ok: false`), and the
+  exit code is 5 (PARTIAL). When every file fails, the first error is rethrown
+  with the usual exit taxonomy.
+- **`login` and `doctor` verify via `project-config` (`config:read`).** The
+  previous probe (`editor/workflow`) requires `targets:write`, which
+  publishable keys don't carry — so pk\_ keys failed verification even though
+  the whole standard loop (push/pull/validate/prefill) runs on them. Doctor's
+  server check now also echoes the project's configured locales.
+- **`pull` is non-destructive by default.** Existing targets are merged, not
+  overwritten: the server wins per key, local-only keys and comments survive
+  (comments even on server-updated keys), existing key order is preserved and
+  new keys append. Each file reports `{added, updated, keptLocal}` diff counts
+  in prose and `--json`; `--dry-run` computes the diff without writing.
+  `pull --force` restores the previous wholesale overwrite.
+- **`validate` reports a locked (423) namespace as one namespace-level
+  `locked` issue** per locale instead of N spurious `missing` lines. Locked
+  still fails `--ci` by default. Envelope note: `issues[].key` is now optional
+  and `locked` joins the issue types.
+
+### Fixed
+
+- **Nested keys were silently lost on `pull`.** The endpoint accepts flat
+  dotted keys on write but answers **nested** on read (a pushed `nav.cart`
+  comes back as `{"nav": {"cart": …}}`, because the SDK resolves nested
+  paths). Every CLI adapter is built on flat keys, so whole subtrees vanished:
+  `pull` wrote fewer keys than it pushed and `validate` reported the missing
+  ones forever. `getNamespace` now flattens the tree back to `dotted.key`
+  using the server's own leaf rule (a string, or an object carrying `text`, is
+  a value; any other object is a container).
+- **`validate` no longer crashes on a malformed server value.** Reading
+  `.text` off a value that wasn't a ContentUnit threw
+  `Cannot read properties of undefined (reading 'trim')` and exit 1 — an
+  uncategorized crash on a normal run. The same normalization pass wraps bare
+  strings into `{ text, styles: {} }`, defaults a missing `styles`, and drops
+  a genuinely unusable leaf with a warning; `validate` treats an unusable
+  value as `empty` rather than assuming shape.
+- **Clear error for keys with non-header-safe characters.** Pasting the
+  dashboard's truncated key display (`sk_eng_…last4`) used to surface as a
+  misleading "server could not be reached" network error — the U+2026
+  ellipsis can't be encoded into the `Authorization` header. The CLI now
+  rejects such keys at every resolution point (env, credentials file,
+  `login`) with exit 3, naming the offending character and the likely
+  truncated-copy cause, before any request is sent.
+- **Security — codegen injection in `types generate`.** With `--server`, keys
+  and select-option labels are server-controlled; labels are now whitelisted
+  to `[A-Za-z0-9_]+` before reaching type position (non-conforming ones drop,
+  all-hostile falls back to `string`) and key escaping `\u`-escapes control
+  characters and JS line terminators, so no remote string can inject
+  declarations into the generated `.d.ts`.
+- **Security — path containment for config-derived writes.** Pull targets,
+  multi-locale catalogs, snapshot outputs, and the generated `.d.ts` path must
+  resolve inside the project directory; `../` escapes and absolute paths are
+  rejected with exit 2 naming the offending path.
+
 ## 0.2.1 — 2026-07-20
 
 Security batch (PLAN items 19–23).

package/README.md

@@ -47,6 +47,35 @@ files:
   - { format: json, source: app/en.json,    target: app/{locale}.json } # → namespace: app
 ```
 
+**Glob entries:** `source` may be a glob (`*`/`?`); `target` and `namespace`
+must then carry a `{basename}` token, replaced per matched file with its
+extension-less name. One stanza covers a whole directory of per-page (or
+per-feature) catalogs, each in its own namespace:
+
+```yaml
+files:
+  - format: json
+    source: locales/en/*.json # locales/en/home.json, pricing.json, …
+    target: locales/{locale}/{basename}.json
+    namespace: '{basename}' # → namespaces home, pricing, …
+```
+
+Globs expand once at config load (sorted, so behavior is deterministic) —
+`push`/`pull`/`validate` see one concrete entry per matched file, and `doctor`
+reports the expanded count. A glob that matches nothing prints a warning
+instead of silently doing nothing; a glob entry without `{basename}` in _both_
+`target` and `namespace` is rejected as ambiguous.
+
+**Flat output:** JSON/YAML targets are written nested by default (a pushed
+`hero.title` comes back as `{"hero": {"title": …}}`). Set `flat: true` on a
+`files` entry to keep dotted keys literal on `pull`, so a flat-keyed file
+round-trips flat for flat-keyed consumers (CMS imports, webhook payloads):
+
+```yaml
+files:
+  - { format: json, source: locales/en.json, target: locales/{locale}.json, flat: true }
+```
+
 ## Reliability & automation
 
 Built for CI and AI agents — every networked command is resilient and scriptable.
@@ -61,9 +90,15 @@ Built for CI and AI agents — every networked command is resilient and scriptab
 - **Exit codes** (stable, gate CI on them): `0` ok · `1` unexpected · `2`
   validation/config · `3` auth · `4` network/5xx · `5` partial.
 - **Automatic retries**: transient failures (network error, `5xx`, `429`) are
-  retried with exponential backoff + jitter; a `429` honors `Retry-After`. Tune
-  with `LIONRAPID_RETRIES` (default `3`; `0` disables). Writes are safe to retry —
-  the integration endpoints upsert by composite key.
+  retried with exponential backoff + jitter. A `429` honors `Retry-After` when
+  the server sends it; when it doesn't, the CLI waits a rate-limit-window 30 s
+  instead of jittering, so a many-namespace push rides out a per-minute limit.
+  Tune with `LIONRAPID_RETRIES` (default `3`; `0` disables). Writes are safe to
+  retry — the integration endpoints upsert by composite key.
+- **Partial progress** (`push`, `pull`): one failing namespace or file doesn't
+  zero the run — the rest complete, failures are listed per file (and as
+  `error` fields under `--json`), and the exit code is `5` (partial).
+  Re-running retries just the failures; pushes upsert, so that's always safe.
 - **Concurrent `pull`**: namespace fetches fan out with bounded concurrency
   (`LIONRAPID_CONCURRENCY`, default `6`) and show interactive progress on a TTY.
   Output stays deterministic — only the network fan-out is parallelized.

package/dist/adapters/json.d.ts

@@ -3,10 +3,10 @@
  * node backends). Nested objects flatten to dot-notation keys (`home.cta`) and
  * unflatten back on serialize, preserving insertion order.
  */
-import type { FormatAdapter, TranslationEntry } from './types.js';
+import type { FormatAdapter, SerializeOptions, TranslationEntry } from './types.js';
 export declare class JsonAdapter implements FormatAdapter {
     readonly format: "json";
     parse(content: string): TranslationEntry[];
-    serialize(entries: TranslationEntry[]): string;
+    serialize(entries: TranslationEntry[], options?: SerializeOptions): string;
 }
 //# sourceMappingURL=json.d.ts.map

package/dist/adapters/json.js

@@ -3,7 +3,7 @@
  * node backends). Nested objects flatten to dot-notation keys (`home.cta`) and
  * unflatten back on serialize, preserving insertion order.
  */
-import { flattenObject, unflattenEntries } from './nested.js';
+import { flatEntriesObject, flattenObject, unflattenEntries } from './nested.js';
 export class JsonAdapter {
     format = 'json';
     parse(content) {
@@ -24,8 +24,9 @@ export class JsonAdapter {
         flattenObject(data, '', out);
         return out;
     }
-    serialize(entries) {
-        return `${JSON.stringify(unflattenEntries(entries), null, 2)}\n`;
+    serialize(entries, options) {
+        const tree = options?.flat ? flatEntriesObject(entries) : unflattenEntries(entries);
+        return `${JSON.stringify(tree, null, 2)}\n`;
     }
 }
 //# sourceMappingURL=json.js.map

package/dist/adapters/nested.d.ts

@@ -5,5 +5,11 @@
  */
 import type { TranslationEntry } from './types.js';
 export declare function flattenObject(obj: Record<string, unknown>, prefix: string, out: TranslationEntry[]): void;
+/**
+ * Flat serialize: dotted keys stay literal (`"hero.title"`), nothing re-nests.
+ * Built with Object.fromEntries so a hostile key like `__proto__` lands as a
+ * plain own property instead of touching the prototype.
+ */
+export declare function flatEntriesObject(entries: TranslationEntry[]): Record<string, unknown>;
 export declare function unflattenEntries(entries: TranslationEntry[], onSkippedKey?: (key: string) => void): Record<string, unknown>;
 //# sourceMappingURL=nested.d.ts.map

package/dist/adapters/nested.js

@@ -18,6 +18,14 @@ export function flattenObject(obj, prefix, out) {
         }
     }
 }
+/**
+ * Flat serialize: dotted keys stay literal (`"hero.title"`), nothing re-nests.
+ * Built with Object.fromEntries so a hostile key like `__proto__` lands as a
+ * plain own property instead of touching the prototype.
+ */
+export function flatEntriesObject(entries) {
+    return Object.fromEntries(entries.map((e) => [e.key, fromContentUnit(e.value)]));
+}
 /** Path segments that would write onto the prototype chain instead of plain data. */
 const UNSAFE_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
 function warnSkippedKey(key) {

package/dist/adapters/types.d.ts

@@ -30,6 +30,8 @@ export interface SerializeOptions {
     locale?: string;
     /** Source locale, recorded by bilingual formats (e.g. XLIFF `source-language`). */
     sourceLocale?: string;
+    /** Keep dotted keys flat (JSON/YAML) instead of re-nesting them into objects. */
+    flat?: boolean;
 }
 export interface FormatAdapter {
     readonly format: FileFormat;

package/dist/adapters/yaml.js

@@ -8,7 +8,7 @@
  * JSON adapter; this adapter assumes the Rails/locale-rooted shape.)
  */
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
-import { flattenObject, unflattenEntries } from './nested.js';
+import { flatEntriesObject, flattenObject, unflattenEntries } from './nested.js';
 function isObject(v) {
     return v !== null && typeof v === 'object' && !Array.isArray(v);
 }
@@ -43,8 +43,8 @@ export class YamlAdapter {
         return out;
     }
     serialize(entries, options) {
-        const nested = unflattenEntries(entries);
-        const doc = options?.locale ? { [options.locale]: nested } : nested;
+        const tree = options?.flat ? flatEntriesObject(entries) : unflattenEntries(entries);
+        const doc = options?.locale ? { [options.locale]: tree } : tree;
         return stringifyYaml(doc);
     }
 }

package/dist/api-client.d.ts

@@ -41,9 +41,17 @@ export interface ApiClientOptions {
     retries?: number;
     /** Injectable delay (defaults to real `setTimeout`). Tests pass a no-op. */
     sleep?: (ms: number) => Promise<void>;
+    /**
+     * Per-attempt request timeout in ms (each retry gets a fresh budget).
+     * Default {@link DEFAULT_TIMEOUT_MS}. A hung connection must never block
+     * push/pull/doctor forever — poison for CI.
+     */
+    timeoutMs?: number;
 }
 /** Default number of retries for transient failures. */
 export declare const DEFAULT_RETRIES = 3;
+/** Default per-attempt request timeout. */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
 /**
  * Parse a `Retry-After` header → ms, or null if absent/unparseable. Accepts the
  * delta-seconds form (`120`) and the HTTP-date form; clamps to
@@ -68,6 +76,19 @@ export declare class ApiError extends Error {
 export declare class NetworkError extends Error {
     constructor(method: string, path: string, cause: unknown);
 }
+/**
+ * Coerce a namespace payload into flat `dotted.key` → {@link ContentUnit}.
+ *
+ * The endpoint takes flat keys on write but answers **nested** on read
+ * (`{"nav": {"cart": …}}` for a pushed `nav.cart`), because the SDK resolves
+ * nested paths. Every CLI adapter is built on flat dotted keys, so the tree
+ * has to be flattened back here or whole subtrees silently vanish. The leaf
+ * rule mirrors the server's: a string, or an object carrying `text`, is a
+ * value; any other object is a container to descend into. Bare strings are
+ * wrapped, a missing `styles` defaults to `{}`, and a genuinely unusable leaf
+ * is dropped with a warning rather than crashing the run.
+ */
+export declare function normalizeTranslations(raw: unknown): Record<string, ContentUnit>;
 export declare class LionRapidApiClient {
     private readonly baseUrl;
     private readonly apiKey;
@@ -75,6 +96,7 @@ export declare class LionRapidApiClient {
     private readonly fetchImpl;
     private readonly retries;
     private readonly sleep;
+    private readonly timeoutMs;
     constructor(opts: ApiClientOptions);
     /** True when this client holds an editor token and can publish (mark-ready). */
     get canPublish(): boolean;
@@ -82,6 +104,16 @@ export declare class LionRapidApiClient {
     ping(): Promise<{
         isPmAdmin: boolean;
     }>;
+    /**
+     * The project's dashboard-configured locales (for `init` prefill).
+     * GET /api/integrations/project-config — flat `{ defaultLocale, languages }`;
+     * `languages` includes the default locale. Malformed bodies normalize to
+     * empty values rather than throwing.
+     */
+    getProjectConfig(): Promise<{
+        defaultLocale: string;
+        languages: string[];
+    }>;
     /**
      * Register source-row text for `sourceLocale`. Mirrors what the edge does on
      * first visit when it encounters a missing key. POST /api/integrations/sync/batch.

package/dist/api-client.js

@@ -10,11 +10,21 @@
  */
 /** Default number of retries for transient failures. */
 export const DEFAULT_RETRIES = 3;
+/** Default per-attempt request timeout. */
+export const DEFAULT_TIMEOUT_MS = 30_000;
 /** Base backoff in ms; grows exponentially per attempt, capped at {@link MAX_BACKOFF_MS}. */
 const BASE_BACKOFF_MS = 300;
 const MAX_BACKOFF_MS = 10_000;
 /** Cap on an honored `Retry-After` so a hostile/misconfigured header can't hang the CLI. */
 const MAX_RETRY_AFTER_MS = 30_000;
+/**
+ * Wait for a 429 that carries no `Retry-After` header. tm-server's rate-limit
+ * responses send none, and its limits are per-minute windows — the jittered
+ * sub-second backoff below can never outlive one, so without this floor every
+ * 429 exhausted its retries and was effectively fatal (e.g. a push past the
+ * 30/min sync limit died at namespace 31).
+ */
+const RATE_LIMIT_FALLBACK_MS = 30_000;
 /** Transient statuses worth retrying: rate-limit (429) and any 5xx. */
 function isRetryableStatus(status) {
     return status === 429 || status >= 500;
@@ -98,6 +108,49 @@ export class NetworkError extends Error {
 function compositeKey(locale, namespace, key) {
     return `${locale}:${namespace}:${key}`;
 }
+/**
+ * Coerce a namespace payload into flat `dotted.key` → {@link ContentUnit}.
+ *
+ * The endpoint takes flat keys on write but answers **nested** on read
+ * (`{"nav": {"cart": …}}` for a pushed `nav.cart`), because the SDK resolves
+ * nested paths. Every CLI adapter is built on flat dotted keys, so the tree
+ * has to be flattened back here or whole subtrees silently vanish. The leaf
+ * rule mirrors the server's: a string, or an object carrying `text`, is a
+ * value; any other object is a container to descend into. Bare strings are
+ * wrapped, a missing `styles` defaults to `{}`, and a genuinely unusable leaf
+ * is dropped with a warning rather than crashing the run.
+ */
+export function normalizeTranslations(raw) {
+    const out = {};
+    const walk = (node, prefix) => {
+        if (node === null || typeof node !== 'object') {
+            console.error(`warning: skipped key "${prefix}" — server returned no usable text`);
+            return;
+        }
+        for (const [key, value] of Object.entries(node)) {
+            const path = prefix ? `${prefix}.${key}` : key;
+            if (typeof value === 'string') {
+                out[path] = { text: value, styles: {} };
+                continue;
+            }
+            if (value !== null && typeof value === 'object') {
+                const unit = value;
+                if (typeof unit.text === 'string') {
+                    out[path] = { text: unit.text, styles: (unit.styles ?? {}) };
+                }
+                else {
+                    walk(value, path); // a container, not a value
+                }
+                continue;
+            }
+            console.error(`warning: skipped key "${path}" — server returned no usable text`);
+        }
+    };
+    if (raw === null || typeof raw !== 'object')
+        return {};
+    walk(raw, '');
+    return out;
+}
 export class LionRapidApiClient {
     baseUrl;
     apiKey;
@@ -105,6 +158,7 @@ export class LionRapidApiClient {
     fetchImpl;
     retries;
     sleep;
+    timeoutMs;
     constructor(opts) {
         this.baseUrl = opts.baseUrl.replace(/\/$/, '');
         this.apiKey = opts.apiKey;
@@ -113,6 +167,7 @@ export class LionRapidApiClient {
         this.retries = Math.max(0, opts.retries ?? DEFAULT_RETRIES);
         this.sleep =
             opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.timeoutMs = Math.max(1, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
     }
     /** True when this client holds an editor token and can publish (mark-ready). */
     get canPublish() {
@@ -123,6 +178,21 @@ export class LionRapidApiClient {
         const res = (await this.request('GET', '/api/integrations/editor/workflow'));
         return { isPmAdmin: !!res?.is_pm_admin };
     }
+    /**
+     * The project's dashboard-configured locales (for `init` prefill).
+     * GET /api/integrations/project-config — flat `{ defaultLocale, languages }`;
+     * `languages` includes the default locale. Malformed bodies normalize to
+     * empty values rather than throwing.
+     */
+    async getProjectConfig() {
+        const res = (await this.request('GET', '/api/integrations/project-config'));
+        return {
+            defaultLocale: typeof res?.defaultLocale === 'string' ? res.defaultLocale : '',
+            languages: Array.isArray(res?.languages)
+                ? res.languages.filter((l) => typeof l === 'string')
+                : [],
+        };
+    }
     /**
      * Register source-row text for `sourceLocale`. Mirrors what the edge does on
      * first visit when it encounters a missing key. POST /api/integrations/sync/batch.
@@ -187,7 +257,7 @@ export class LionRapidApiClient {
         }
         const data = (await res.json());
         return {
-            translations: data.translations ?? {},
+            translations: normalizeTranslations(data.translations),
             version: data.meta?.version != null ? String(data.meta.version) : undefined,
             notModified: false,
             locked: false,
@@ -231,11 +301,17 @@ export class LionRapidApiClient {
             try {
                 // `redirect: 'error'` pins every request to the configured host: a 3xx
                 // fails loudly instead of relying on the runtime to strip the
-                // Authorization header on a cross-origin redirect.
-                res = await this.fetchImpl(`${this.baseUrl}${path}`, { ...init, redirect: 'error' });
+                // Authorization header on a cross-origin redirect. The timeout signal
+                // is per-attempt, so every retry gets a fresh budget.
+                res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                    ...init,
+                    redirect: 'error',
+                    signal: AbortSignal.timeout(this.timeoutMs),
+                });
             }
             catch (err) {
-                netErr = new NetworkError(method, path, err);
+                const isTimeout = err instanceof Error && err.name === 'TimeoutError';
+                netErr = new NetworkError(method, path, isTimeout ? new Error(`timed out after ${this.timeoutMs}ms`, { cause: err }) : err);
                 // A refused redirect is the server's answer, not a transient failure.
                 if (isRedirectFailure(err))
                     throw netErr;
@@ -261,8 +337,11 @@ export class LionRapidApiClient {
                     return res;
                 throw netErr;
             }
-            const retryAfter = res?.status === 429 ? parseRetryAfter(res.headers.get('retry-after'), Date.now()) : null;
-            const delay = retryAfter ?? backoffMs(attempt, Math.random);
+            // A 429 is a rate-limit window, not a blip: honor `Retry-After` when the
+            // server sent one, else wait window-sized instead of jittering.
+            const delay = res?.status === 429
+                ? (parseRetryAfter(res.headers.get('retry-after'), Date.now()) ?? RATE_LIMIT_FALLBACK_MS)
+                : backoffMs(attempt, Math.random);
             await this.sleep(delay);
         }
     }

package/dist/cli.d.ts

@@ -4,8 +4,7 @@
  * PO) with the LionRapid backend.
  *
  * This file wires up the command surface. Each command's behaviour lives in
- * `src/commands/*`; commands not yet implemented print a clear "not implemented
- * yet" notice and exit non-zero so scripts never silently succeed.
+ * `src/commands/*`.
  */
 import { Command } from 'commander';
 /**