@lionrapid/cli 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,55 @@
 All notable changes to `@lionrapid/cli`. Format based on
 [Keep a Changelog](https://keepachangelog.com/); this package follows semver.
 
+## Unreleased
+
+### Added
+
+- **`push` reports the jobs it queued, and `lionrapid status` says what became
+  of them.** `sync/batch` answers `202 Accepted` — queued, not stored — and the
+  CLI discarded that response body at the transport layer (`syncBatch` returned
+  `void`). A push whose backend job later failed or dead-lettered was therefore
+  indistinguishable from one that worked: `pushed N string(s)` described the
+  CLI's own outbox and nothing else. Now:
+
+  - `syncBatch` returns the server's `BatchSyncJobResponse`, and `push` collects
+    every `job_ids` entry (not just the legacy `job_id`, so multi-locale batches
+    stay observable);
+  - `push` prints those ids with a `lionrapid status <job-id>` hint, and says so
+    explicitly when a server returns none;
+  - new **`lionrapid status [job-id|list]`**: one job's verdict from
+    `GET /sync/jobs/{id}` (status, error, retry history, dead-letter reason), or
+    the whole local job log newest-first, falling back to `/sync/queue-health`
+    and `/sync/dead-letter-queue` when this machine has nothing recorded.
+
+- **Push receipts persist in `~/.lionrapid/jobs.json`.** Job id, project,
+  file(s), key count, push time and last-seen status, so `status` still answers
+  after the terminal is closed — and after the server's ~1h job retention has
+  purged the job. Terminal states are recorded and answered from disk with no
+  network call; anything unresolved is re-checked. Deliberately a separate file
+  from `credentials` (different lifetime and sensitivity — a corrupt history
+  must never cost you your login), 0600, written via temp-file + rename, and
+  pruned to 500 entries / 30 days.
+
+- **Field-level drift guard on the sync response.** `BATCH_SYNC_RESPONSE_FIELDS`
+  plus a type-level assertion make a required server field missing from the
+  CLI's `SyncBatchResponse` a `tsc --noEmit` failure — `job_id`/`job_ids` were
+  silently dropped for exactly as long as nothing checked. (Guard lives in
+  `src/`, since tsconfig excludes tests from typechecking.)
+
+### Fixed
+
+- **A `GET` 404 is no longer retried as "sync already processing".** That
+  retry-on-404 heuristic is the enqueue path's; `GET /sync/jobs/{id}` returns the
+  same `SYNC_JOB_NOT_FOUND` code for a job that simply does not exist, which made
+  `status` back off three times before answering.
+
+- **Every request carries `X-LR-Surface: cli`.** The server's surface registry
+  tells a customer which integration surfaces are live, but snippet, WordPress
+  and the CLI share the same project-wide key and were indistinguishable — so
+  each client now tags its requests with which surface it is. Older servers
+  ignore the header; no behavior changes.
+
 ## 0.2.2 — 2026-07-27
 
 ### Added

package/README.md

@@ -22,6 +22,7 @@ Phase 1 (file-sync dev-loop) is implemented. Command surface:
 | ----------------- | ------ | ------------------------------------------------------------------- |
 | `init`            | ✅     | Scaffold a `lionrapid.yml` (detects Flutter/iOS/Android/Rails/JS)   |
 | `push`            | ✅     | Upload source strings to the backend (server handles MT)            |
+| `status [job-id]` | ✅     | What the backend actually did with what `push` queued               |
 | `pull [--types]`  | ✅     | Download translations into target files; optionally regen types     |
 | `validate [--ci]` | ✅     | Check local files vs the backend for missing/orphan/empty keys      |
 | `types generate`  | ✅     | Generate a typed `.d.ts` from your source files (offline)           |
@@ -99,6 +100,17 @@ Built for CI and AI agents — every networked command is resilient and scriptab
   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.
+- **Pushed ≠ stored (`push` → `status`)**: `sync/batch` answers `202 Accepted`,
+  so `push`'s counts are what the CLI **sent**; the backend stores them in a
+  background job that can still fail or dead-letter. `push` therefore prints the
+  job ids it queued and saves them to `~/.lionrapid/jobs.json`, and
+  `lionrapid status <job-id>` reports the server's verdict — stored, still
+  queued, retrying, or dead-lettered (with the reason and every failed attempt).
+  Bare `lionrapid status` lists every job this machine pushed, newest first,
+  re-checking only the unresolved ones; with nothing recorded it falls back to
+  the server's queue health + dead-letter queue. Offline, it still prints the
+  local record, labelled `(last known)`. History is capped at 500 entries /
+  30 days and never shares a file with your credentials.
 - **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.
@@ -178,7 +190,9 @@ already translated on your website are translated in the app for free.
 
 ```bash
 lionrapid init --project <id> --targets es,fr
-lionrapid push
+lionrapid push                 # prints the job ids it queued
+lionrapid status               # …and what the backend did with them
+lionrapid status <job-id>      # the full story on one job
 lionrapid pull --types
 lionrapid validate --ci
 

package/dist/api-client.d.ts

@@ -14,6 +14,90 @@ export interface KeyedTranslation {
     key: string;
     value: ContentUnit;
 }
+/**
+ * The 202 body of `POST /api/integrations/sync/batch` — a mirror of the
+ * server's `BatchSyncJobResponse` (tm-server
+ * `backend/app/domains/integrations/contracts/responses.py`). Field names are
+ * the wire names on purpose: this type IS the contract, and
+ * {@link BATCH_SYNC_RESPONSE_FIELDS} guards it against server drift.
+ *
+ * 202 means **queued, not stored**. The rows only reach the database when the
+ * job queued here actually runs, so a push that returns 202 for every batch is
+ * still compatible with the backend later failing or dead-lettering the work.
+ * The job ids are the only way a client can tell those apart — discarding this
+ * body (as `syncBatch` used to) is what made a failed sync indistinguishable
+ * from a successful one.
+ */
+export interface SyncBatchResponse {
+    /** First queued job id — the server's legacy alias for `job_ids[0]`. */
+    job_id: string;
+    /** ALL queued job ids — one per locale group in the batch. */
+    job_ids: string[];
+    /** Job status at enqueue time (`pending`). */
+    status: string;
+    /** Number of keys the server accepted into the batch. */
+    total_keys: number;
+    /** Human-readable message — carries the server's own poll hint. */
+    message: string;
+}
+/**
+ * The REQUIRED fields of the server's `BatchSyncJobResponse`, transcribed from
+ * `contracts/responses.py` (a field with no default is required there).
+ *
+ * DRIFT GUARD, field level. `job_id`/`job_ids` existed server-side the whole
+ * time and the CLI silently dropped them — a `Promise<void>` cannot be caught
+ * by any test, because there is nothing to assert on. This list plus
+ * {@link SyncBatchResponseCoversContract} makes that failure a *compile* error:
+ * add a required field here without adding it to {@link SyncBatchResponse} and
+ * `npm run typecheck` fails, so the next server field can't vanish the same way.
+ *
+ * (Deliberately not derived from the server's OpenAPI: tm-server is a separate
+ * repo, so that check would need a network fetch or a snapshot to drift on its
+ * own. Hand-transcribing five names is the cheaper, non-flaky half.)
+ */
+export declare const BATCH_SYNC_RESPONSE_FIELDS: readonly ["job_id", "job_ids", "status", "total_keys", "message"];
+/** Compiles only when `T` is `never` — i.e. no contract field is unaccounted for. */
+type NoMissingContractFields<T extends never> = T;
+/**
+ * The guard itself. Exported as a type (not a value) so it costs no runtime and
+ * no lint suppression, and it is checked because `tsc --noEmit` covers `src/`.
+ */
+export type SyncBatchResponseCoversContract = NoMissingContractFields<Exclude<(typeof BATCH_SYNC_RESPONSE_FIELDS)[number], keyof SyncBatchResponse>>;
+/**
+ * A sync job's server-side state — `GET /api/integrations/sync/jobs/{id}`
+ * (`SyncJobStatusResponse`). Camel-cased because, unlike
+ * {@link SyncBatchResponse}, this is the CLI's own view rather than a guarded
+ * contract mirror.
+ *
+ * `status` is one of `pending` / `processing` / `retry_pending` / `completed` /
+ * `failed`. The server only ever sets `failed` from its dead-letter path, so a
+ * `failed` job is one the backend gave up on: those rows were never stored.
+ */
+export interface SyncJobStatus {
+    jobId: string;
+    status: string;
+    createdAt?: string;
+    startedAt?: string;
+    completedAt?: string;
+    /** Sync outcome on success (`keys_added`, `keys_updated`, …). */
+    result?: Record<string, unknown>;
+    error?: string;
+    retryCount: number;
+    maxRetries: number;
+    nextRetryAt?: string;
+    /** One entry per failed attempt, oldest first. */
+    retryErrors: string[];
+    isDeadLettered: boolean;
+    deadLetterReason?: string;
+}
+/** Queue-wide metrics — `GET /api/integrations/sync/queue-health`. */
+export interface QueueHealth {
+    totalJobs: number;
+    queueDepth: number;
+    statusCounts: Record<string, number>;
+    dlqCount: number;
+    workerRunning: boolean;
+}
 /** Result of a namespace pull. `notModified` is true on a 304 (ETag hit). */
 export interface NamespaceBundle {
     translations: Record<string, ContentUnit>;
@@ -89,6 +173,18 @@ export declare class NetworkError extends Error {
  * is dropped with a warning rather than crashing the run.
  */
 export declare function normalizeTranslations(raw: unknown): Record<string, ContentUnit>;
+/**
+ * Project the sync/batch body onto {@link SyncBatchResponse}, field by field.
+ *
+ * Written out explicitly rather than cast, so a dropped field is a *runtime*
+ * regression a test can see as well as a compile error (see
+ * {@link BATCH_SYNC_RESPONSE_FIELDS}). Every field degrades instead of throwing:
+ * an older server, a proxy that eats the body, or a 204 must leave push working
+ * — you simply get no job ids to report, which the CLI says out loud.
+ */
+export declare function normalizeSyncBatchResponse(raw: unknown): SyncBatchResponse;
+/** Project a `SyncJobStatusResponse` (job status, or a DLQ entry) onto {@link SyncJobStatus}. */
+export declare function normalizeSyncJob(raw: unknown): SyncJobStatus;
 export declare class LionRapidApiClient {
     private readonly baseUrl;
     private readonly apiKey;
@@ -117,8 +213,29 @@ export declare class LionRapidApiClient {
     /**
      * 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.
+     *
+     * Returns the server's 202 body. It used to return `void` — the response was
+     * read and thrown away at the transport layer, which is why a push whose jobs
+     * later died looked exactly like one that worked. Callers get the job ids and
+     * can poll {@link getSyncJob}.
+     */
+    syncBatch(sourceLocale: string, namespace: string, items: KeyedTranslation[]): Promise<SyncBatchResponse>;
+    /**
+     * A queued sync job's state. GET /api/integrations/sync/jobs/{id}.
+     *
+     * The lookup is project-scoped server-side, and finished non-DLQ jobs are
+     * purged after ~1h — an unknown id 404s, which is why the CLI also keeps its
+     * own history (a job that completed yesterday can only be answered from disk).
+     */
+    getSyncJob(jobId: string): Promise<SyncJobStatus>;
+    /**
+     * Jobs the backend gave up on. GET /api/integrations/sync/dead-letter-queue.
+     * Needs the `ops:queue` scope (master keys have it; publishable `pk_` keys
+     * do not — those get a 403).
      */
-    syncBatch(sourceLocale: string, namespace: string, items: KeyedTranslation[]): Promise<void>;
+    getDeadLetterQueue(): Promise<SyncJobStatus[]>;
+    /** Queue-wide metrics. GET /api/integrations/sync/queue-health (`ops:queue`). */
+    getQueueHealth(): Promise<QueueHealth>;
     /**
      * Write target-locale translations as drafts (editor-visible, not public
      * until mark-ready). PUT /api/integrations/targets/batch.
@@ -152,4 +269,5 @@ export declare class LionRapidApiClient {
      */
     private doFetch;
 }
+export {};
 //# sourceMappingURL=api-client.d.ts.map

package/dist/api-client.js

@@ -8,6 +8,28 @@
  * uses native `fetch`. `fetch` is injectable so the client is unit-testable
  * without a live server.
  */
+/**
+ * The REQUIRED fields of the server's `BatchSyncJobResponse`, transcribed from
+ * `contracts/responses.py` (a field with no default is required there).
+ *
+ * DRIFT GUARD, field level. `job_id`/`job_ids` existed server-side the whole
+ * time and the CLI silently dropped them — a `Promise<void>` cannot be caught
+ * by any test, because there is nothing to assert on. This list plus
+ * {@link SyncBatchResponseCoversContract} makes that failure a *compile* error:
+ * add a required field here without adding it to {@link SyncBatchResponse} and
+ * `npm run typecheck` fails, so the next server field can't vanish the same way.
+ *
+ * (Deliberately not derived from the server's OpenAPI: tm-server is a separate
+ * repo, so that check would need a network fetch or a snapshot to drift on its
+ * own. Hand-transcribing five names is the cheaper, non-flaky half.)
+ */
+export const BATCH_SYNC_RESPONSE_FIELDS = [
+    'job_id',
+    'job_ids',
+    'status',
+    'total_keys',
+    'message',
+];
 /** Default number of retries for transient failures. */
 export const DEFAULT_RETRIES = 3;
 /** Default per-attempt request timeout. */
@@ -25,6 +47,13 @@ const MAX_RETRY_AFTER_MS = 30_000;
  * 30/min sync limit died at namespace 31).
  */
 const RATE_LIMIT_FALLBACK_MS = 30_000;
+/**
+ * Surface self-identification for the server's surface registry: snippet,
+ * WordPress and the CLI all share the same project-wide key, so each client
+ * tags its requests with which surface it is. Older servers ignore unknown
+ * headers — additive and inert.
+ */
+const SURFACE_HEADER = { 'X-LR-Surface': 'cli' };
 /** Transient statuses worth retrying: rate-limit (429) and any 5xx. */
 function isRetryableStatus(status) {
     return status === 429 || status >= 500;
@@ -151,6 +180,58 @@ export function normalizeTranslations(raw) {
     walk(raw, '');
     return out;
 }
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function asString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function asStringArray(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
+}
+/**
+ * Project the sync/batch body onto {@link SyncBatchResponse}, field by field.
+ *
+ * Written out explicitly rather than cast, so a dropped field is a *runtime*
+ * regression a test can see as well as a compile error (see
+ * {@link BATCH_SYNC_RESPONSE_FIELDS}). Every field degrades instead of throwing:
+ * an older server, a proxy that eats the body, or a 204 must leave push working
+ * — you simply get no job ids to report, which the CLI says out loud.
+ */
+export function normalizeSyncBatchResponse(raw) {
+    const body = isRecord(raw) ? raw : {};
+    const primary = asString(body['job_id']);
+    const ids = asStringArray(body['job_ids']);
+    // The server sets job_id = job_ids[0]; tolerate either side being absent so
+    // one missing field never costs us the other.
+    const jobIds = ids.length > 0 ? ids : primary ? [primary] : [];
+    return {
+        job_id: primary ?? jobIds[0] ?? '',
+        job_ids: jobIds,
+        status: asString(body['status']) ?? '',
+        total_keys: typeof body['total_keys'] === 'number' ? body['total_keys'] : 0,
+        message: asString(body['message']) ?? '',
+    };
+}
+/** Project a `SyncJobStatusResponse` (job status, or a DLQ entry) onto {@link SyncJobStatus}. */
+export function normalizeSyncJob(raw) {
+    const body = isRecord(raw) ? raw : {};
+    return {
+        jobId: asString(body['job_id']) ?? '',
+        status: asString(body['status']) ?? 'unknown',
+        createdAt: asString(body['created_at']),
+        startedAt: asString(body['started_at']),
+        completedAt: asString(body['completed_at']),
+        result: isRecord(body['result']) ? body['result'] : undefined,
+        error: asString(body['error']),
+        retryCount: typeof body['retry_count'] === 'number' ? body['retry_count'] : 0,
+        maxRetries: typeof body['max_retries'] === 'number' ? body['max_retries'] : 0,
+        nextRetryAt: asString(body['next_retry_at']),
+        retryErrors: asStringArray(body['retry_errors']),
+        isDeadLettered: body['is_dead_lettered'] === true,
+        deadLetterReason: asString(body['dead_letter_reason']),
+    };
+}
 export class LionRapidApiClient {
     baseUrl;
     apiKey;
@@ -196,16 +277,62 @@ export class LionRapidApiClient {
     /**
      * 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.
+     *
+     * Returns the server's 202 body. It used to return `void` — the response was
+     * read and thrown away at the transport layer, which is why a push whose jobs
+     * later died looked exactly like one that worked. Callers get the job ids and
+     * can poll {@link getSyncJob}.
      */
     async syncBatch(sourceLocale, namespace, items) {
         const translations = items.map((it) => ({
             key: compositeKey(sourceLocale, namespace, it.key),
             value: it.value,
         }));
-        await this.request('POST', '/api/integrations/sync/batch', {
+        const res = await this.request('POST', '/api/integrations/sync/batch', {
             translations,
             format: 'contentunit',
         });
+        return normalizeSyncBatchResponse(res);
+    }
+    /**
+     * A queued sync job's state. GET /api/integrations/sync/jobs/{id}.
+     *
+     * The lookup is project-scoped server-side, and finished non-DLQ jobs are
+     * purged after ~1h — an unknown id 404s, which is why the CLI also keeps its
+     * own history (a job that completed yesterday can only be answered from disk).
+     */
+    async getSyncJob(jobId) {
+        const res = await this.request('GET', `/api/integrations/sync/jobs/${encodeURIComponent(jobId)}`);
+        return normalizeSyncJob(res);
+    }
+    /**
+     * Jobs the backend gave up on. GET /api/integrations/sync/dead-letter-queue.
+     * Needs the `ops:queue` scope (master keys have it; publishable `pk_` keys
+     * do not — those get a 403).
+     */
+    async getDeadLetterQueue() {
+        const res = await this.request('GET', '/api/integrations/sync/dead-letter-queue');
+        const jobs = isRecord(res) && Array.isArray(res['jobs']) ? res['jobs'] : [];
+        return jobs.map(normalizeSyncJob);
+    }
+    /** Queue-wide metrics. GET /api/integrations/sync/queue-health (`ops:queue`). */
+    async getQueueHealth() {
+        const res = await this.request('GET', '/api/integrations/sync/queue-health');
+        const body = isRecord(res) ? res : {};
+        const counts = {};
+        if (isRecord(body['status_counts'])) {
+            for (const [k, v] of Object.entries(body['status_counts'])) {
+                if (typeof v === 'number')
+                    counts[k] = v;
+            }
+        }
+        return {
+            totalJobs: typeof body['total_jobs'] === 'number' ? body['total_jobs'] : 0,
+            queueDepth: typeof body['queue_depth'] === 'number' ? body['queue_depth'] : 0,
+            statusCounts: counts,
+            dlqCount: typeof body['dlq_count'] === 'number' ? body['dlq_count'] : 0,
+            workerRunning: body['worker_running'] === true,
+        };
     }
     /**
      * Write target-locale translations as drafts (editor-visible, not public
@@ -305,6 +432,7 @@ export class LionRapidApiClient {
                 // is per-attempt, so every retry gets a fresh budget.
                 res = await this.fetchImpl(`${this.baseUrl}${path}`, {
                     ...init,
+                    headers: { ...SURFACE_HEADER, ...init.headers },
                     redirect: 'error',
                     signal: AbortSignal.timeout(this.timeoutMs),
                 });
@@ -321,7 +449,13 @@ export class LionRapidApiClient {
                 // Exception: a 404 that's really "a sync is already processing for this
                 // project" is transient. Peek at the body (only for 404s); retry if it's
                 // that case and attempts remain, otherwise hand the body back intact.
-                if (res.status === 404 && attempt < this.retries) {
+                //
+                // Writes only: that 404 is the enqueue path's answer. `GET
+                // /sync/jobs/{id}` returns the same SYNC_JOB_NOT_FOUND code for a job
+                // that genuinely does not exist (unknown id, or one purged after the
+                // server's ~1h retention), and `lionrapid status` must answer that
+                // immediately instead of backing off three times first.
+                if (res.status === 404 && method !== 'GET' && attempt < this.retries) {
                     const body = await safeText(res);
                     if (isSyncInProgress(body)) {
                         await this.sleep(backoffMs(attempt, Math.random));