@lionrapid/cli 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -3,7 +3,134 @@
 All notable changes to `@lionrapid/cli`. Format based on
 [Keep a Changelog](https://keepachangelog.com/); this package follows semver.
 
-## Unreleased
+## 0.5.0
+
+### Changed — behaviour
+
+- **`pushed` now reports what the server wrote, not what went on the wire.** In
+  target mode it is the server's own `created + updated`. The same push can
+  therefore report a smaller number than before — that number was previously
+  describing the CLI's outbox. Source mode is unchanged: a `202` can only
+  honestly claim "queued".
+
+### Added
+
+- **The server can decline to overwrite your translators, and the CLI now says
+  so.** A push from a master or publishable key no longer overwrites a row a
+  human committed — the server skips it and reports which ones back. `push`
+  names the key, the reason, and the wording the server kept:
+
+  ```
+  ✓ pushed 0 target string(s) across 1 file(s)
+    · locales/es/home.json: 0 (1 not written)
+  ⚠ 1 row(s) were NOT overwritten — the server is protecting them:
+      es:home:hero.title  human_committed (server has: "Envia mas rapido")
+    A human committed these. There is no CLI override — change them in the
+    Visual Editor, or use "Use for all" to apply one wording across the project.
+  ```
+
+  There is deliberately **no flag to force past this**. The paths to a
+  deliberate overwrite are the Visual Editor and "Use for all", both of which
+  put a person in the loop. A protected row is also never marked ready.
+
+### Fixed
+
+- **`denied` and `denied_rows` have never been visible to anyone.** The client
+  discarded the `targets/batch` response body entirely (`Promise<void>`), the
+  same way `syncBatch` did before 0.3.0 — so rows the server refused on
+  authorization grounds were reported by the server and shown to nobody, for as
+  long as the field has existed. The body is now returned and normalised, with a
+  `TARGET_BATCH_RESPONSE_FIELDS` drift guard beside the sync one so a third
+  dropped field is a typecheck failure.
+- **A row the server simply had nothing to do with is no longer called
+  "not written".** An unchanged row lands in no server bucket, and the per-file
+  figure was computed as `sent − written`, so a no-op read as a refusal — the
+  output claimed a problem the user could not find, because the row it implied
+  was refused never appeared in the list. Now derived from the server's own
+  buckets.
+- **`push --force` no longer claims to overwrite server values.** It forces past
+  the local lockfile diff; it does not and cannot override server-side
+  protection. The help text says so.
+- **A target whose source row does not exist is no longer reported as pushed.**
+  The server writes nothing and answers `skipped`; the CLI said
+  `pushed 1 target string(s)`.
+
+## 0.4.0
+
+### Changed — behaviour, read this before upgrading
+
+- **`push` is now incremental.** It diffs your sources against a new
+  `.lionrapid/lock.json` and sends only what changed; a second run of an
+  unchanged project pushes nothing. **Commit the lockfile** — like
+  `package-lock.json` it is the shared baseline, and a per-machine one would
+  make CI and a laptop disagree about what changed.
+
+  Recovery matters here: a batch the server accepts with `202` is recorded as
+  sent, and nothing waits for the job. If that job later dead-letters, a plain
+  re-push **skips** those rows. Use `push --backfill-missing` (sends exactly
+  what the server is missing) or `push --force` (resends everything).
+
+- **`LIONRAPID_API_KEY` is now held to the same trusted-host rule as a saved
+  default key.** A `server:` that is not `*.lionrapid.com` or localhost will
+  refuse to receive it, because CI is precisely where a real secret meets a
+  `lionrapid.yml` that arrives by pull request. Self-hosted or staging: set
+  `LIONRAPID_ALLOW_UNTRUSTED_HOST=1` (accepted only as `1`/`true`). This
+  knowingly reverses the earlier position that CI sets the variable
+  deliberately — in CI the operator and the `server:` value are set by
+  different people, so exporting a key is not the same as approving its
+  destination.
+
+- **`DEFAULT_SERVER` is `https://app.lionrapid.com`.** It was
+  `api.lionrapid.com`, which has no DNS record.
+
+- **`targetLocales` is optional.** A config carrying only a source stanza is
+  valid; `push` uploads sources and warns that `pull` has nothing to do.
+  Previously `init` wrote a config its own schema rejected.
+
+- **`project:` (free text) is removed.** The API key selects the project and
+  nothing in the config does; the field was a label nobody checked. A config
+  still carrying one parses and ignores it.
+
+### Added
+
+- **`lionrapid init` is one pass** — detect, resolve the server, prompt/verify
+  and **save** the key, fetch locales, capture `projectId`, write the config.
+  No second `login`, no second `init`, no hand-editing.
+- **`lionrapid whoami`** — which key is about to be used and where it is going.
+  Offline, masked to the last four characters, names an env override explicitly.
+- **A project-mismatch guard.** `push` refuses _before sending a single row_
+  when the config's `projectId` and the key's project disagree, naming both —
+  the fix depends on which one is wrong.
+- **`pull` no longer clobbers local edits.** An edit newer than the server is
+  named and kept; `--force` takes the server's version and snapshots yours to
+  `.lionrapid/history/` first (gitignored — a local safety copy, not a team
+  fact). `push --force` does the same in the other direction.
+- **`push --dry-run`** reports the diff: new, changed, unchanged.
+- **`logout`** removes the only scope when there is one, offers a picker when
+  there are several, refuses non-interactively, and `--all` clears everything.
+- **Key-capability guidance** in `doctor`, `whoami` and `push` — a `pk_` cannot
+  write or publish targets, said before you hit the 403.
+- **`status --refresh`**, which never downgrades a terminal verdict: a
+  `completed` job the server has since purged still reads `completed`.
+
+### Fixed
+
+- `doctor` blamed a missing API key when the config was invalid; it now says
+  **skipped** and prints the config's actual problems.
+- The no-key error named neither the server it wanted nor the scopes it had.
+- `status` showed jobs finishing **before** they were pushed — offset-less
+  server timestamps were parsed as local time against a UTC clock.
+- The credentials path ignored `process.env.HOME`, so the test suite read the
+  real `~/.lionrapid/credentials`.
+- `validate` reported "all source keys translated" against **zero** target
+  locales.
+- Four NUL bytes in `init.ts` made the file invisible to `grep`, for everyone,
+  permanently, because they were committed. A repo-wide guard test now fails on
+  any recurrence. Note `file(1)` does **not** detect this.
+- `types check` is proven to run offline; a lint that needs credentials is a
+  lint nobody runs in CI.
+
+## 0.3.0 — 2026-08-06
 
 ### Added
 
@@ -13,7 +140,6 @@ All notable changes to `@lionrapid/cli`. Format based on
   `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);

package/dist/api-client.d.ts

@@ -63,6 +63,62 @@ type NoMissingContractFields<T extends never> = T;
  * 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>>;
+/** One row the server declined to write, and why. Shared by denied/protected. */
+export interface TargetRowOutcome {
+    /** Composite key of the refused row (`locale:namespace:key`). */
+    key: string;
+    /** `human_committed`, `locked`, `forbidden` — the server's own word. */
+    reason: string;
+    /** What the server currently holds, so a caller can show what survived. */
+    current_text?: string;
+}
+/**
+ * The body of `PUT /api/integrations/targets/batch` — the server's
+ * `TargetBatchUpdateResponse`. Wire names, like {@link SyncBatchResponse},
+ * because this type IS the contract.
+ *
+ * THE SERVER REFUSES ROWS AND SAYS WHICH. `denied` (per-row authorization) has
+ * been reported for as long as it has existed and the CLI never showed it,
+ * because `targetsBatch` returned `void` — the same discard `syncBatch` had
+ * before 0.3.0. `protected` (tm-platform#162) joins it: a MACHINE push no
+ * longer overwrites a human-committed row, and there is deliberately no
+ * override flag.
+ *
+ * `protected` is NOT `skipped`. `skipped` means the source row was not found
+ * or the value would not parse — a different thing, and both can be non-zero
+ * in one push.
+ */
+export interface TargetBatchResponse {
+    status: string;
+    /** New target rows written. */
+    created: number;
+    /** Existing target rows overwritten. */
+    updated: number;
+    /** Source row missing, or the value would not parse. NOT a refusal. */
+    skipped: number;
+    /** Rows the caller was not authorized to edit. */
+    denied: number;
+    denied_rows: TargetRowOutcome[];
+    /** Human-committed rows a machine caller must not overwrite. */
+    protected: number;
+    protected_rows: TargetRowOutcome[];
+    /** Rows refused by the directive-parity gate. */
+    rejected: number;
+    /** Items processed — includes everything above. */
+    total: number;
+}
+/**
+ * Fields of `TargetBatchUpdateResponse` the CLI must carry.
+ *
+ * Same drift guard as {@link BATCH_SYNC_RESPONSE_FIELDS}, and for the same
+ * reason twice over: this is the SECOND response body the CLI silently
+ * dropped. `denied_rows` was reported by the server and invisible to users for
+ * its whole life. A field added here without a matching one on
+ * {@link TargetBatchResponse} is a `tsc --noEmit` failure.
+ */
+export declare const TARGET_BATCH_RESPONSE_FIELDS: readonly ["status", "created", "updated", "skipped", "denied", "denied_rows", "protected", "protected_rows", "rejected", "total"];
+/** Compiles only when every listed field exists on {@link TargetBatchResponse}. */
+export type TargetBatchResponseCoversContract = NoMissingContractFields<Exclude<(typeof TARGET_BATCH_RESPONSE_FIELDS)[number], keyof TargetBatchResponse>>;
 /**
  * A sync job's server-side state — `GET /api/integrations/sync/jobs/{id}`
  * (`SyncJobStatusResponse`). Camel-cased because, unlike
@@ -105,6 +161,16 @@ export interface NamespaceBundle {
     notModified: boolean;
     /** True on a 423 — the namespace exists but nothing is approved for delivery yet. */
     locked: boolean;
+    /**
+     * The project this key resolves to, from `meta.project_uuid`.
+     *
+     * REAL BUT UNDECLARED: the route sets `response_model=TranslationResponse`
+     * yet returns a raw Response so it can attach the ETag header, which bypasses
+     * FastAPI model filtering — so the field ships without being in the contract
+     * (server task #70). Anyone tidying that route to return the declared model
+     * removes it, in a change that reads as cosmetic. Treat as optional forever.
+     */
+    projectId?: string;
 }
 export type FetchImpl = (input: string, init?: RequestInit) => Promise<Response>;
 export interface ApiClientOptions {
@@ -183,6 +249,18 @@ export declare function normalizeTranslations(raw: unknown): Record<string, Cont
  * — you simply get no job ids to report, which the CLI says out loud.
  */
 export declare function normalizeSyncBatchResponse(raw: unknown): SyncBatchResponse;
+/**
+ * Project the targets/batch body onto {@link TargetBatchResponse}, field by
+ * field.
+ *
+ * Every field degrades to zero/empty rather than throwing. That is not
+ * defensive habit: the deployment this was written against does NOT serve
+ * `protected`/`protected_rows` yet — its OpenAPI lists status, created,
+ * updated, skipped, denied, denied_rows, rejected, rejected_keys, total — so
+ * "absent" is the CURRENT reality for most servers, not a theoretical older
+ * one. An absent refusal must read as "nothing was refused", never as a crash.
+ */
+export declare function normalizeTargetBatchResponse(raw: unknown): TargetBatchResponse;
 /** Project a `SyncJobStatusResponse` (job status, or a DLQ entry) onto {@link SyncJobStatus}. */
 export declare function normalizeSyncJob(raw: unknown): SyncJobStatus;
 export declare class LionRapidApiClient {
@@ -240,7 +318,7 @@ export declare class LionRapidApiClient {
      * Write target-locale translations as drafts (editor-visible, not public
      * until mark-ready). PUT /api/integrations/targets/batch.
      */
-    targetsBatch(targetLocale: string, namespace: string, items: KeyedTranslation[]): Promise<void>;
+    targetsBatch(targetLocale: string, namespace: string, items: KeyedTranslation[]): Promise<TargetBatchResponse>;
     /**
      * Publish a single target row. POST /api/integrations/targets/{key}/mark-ready.
      * Requires an editor session token (the integration key is not authorized).

package/dist/api-client.js

@@ -30,6 +30,27 @@ export const BATCH_SYNC_RESPONSE_FIELDS = [
     'total_keys',
     'message',
 ];
+/**
+ * Fields of `TargetBatchUpdateResponse` the CLI must carry.
+ *
+ * Same drift guard as {@link BATCH_SYNC_RESPONSE_FIELDS}, and for the same
+ * reason twice over: this is the SECOND response body the CLI silently
+ * dropped. `denied_rows` was reported by the server and invisible to users for
+ * its whole life. A field added here without a matching one on
+ * {@link TargetBatchResponse} is a `tsc --noEmit` failure.
+ */
+export const TARGET_BATCH_RESPONSE_FIELDS = [
+    'status',
+    'created',
+    'updated',
+    'skipped',
+    'denied',
+    'denied_rows',
+    'protected',
+    'protected_rows',
+    'rejected',
+    'total',
+];
 /** Default number of retries for transient failures. */
 export const DEFAULT_RETRIES = 3;
 /** Default per-attempt request timeout. */
@@ -213,6 +234,40 @@ export function normalizeSyncBatchResponse(raw) {
         message: asString(body['message']) ?? '',
     };
 }
+/**
+ * Project the targets/batch body onto {@link TargetBatchResponse}, field by
+ * field.
+ *
+ * Every field degrades to zero/empty rather than throwing. That is not
+ * defensive habit: the deployment this was written against does NOT serve
+ * `protected`/`protected_rows` yet — its OpenAPI lists status, created,
+ * updated, skipped, denied, denied_rows, rejected, rejected_keys, total — so
+ * "absent" is the CURRENT reality for most servers, not a theoretical older
+ * one. An absent refusal must read as "nothing was refused", never as a crash.
+ */
+export function normalizeTargetBatchResponse(raw) {
+    const body = isRecord(raw) ? raw : {};
+    const count = (key) => typeof body[key] === 'number' && Number.isFinite(body[key]) ? body[key] : 0;
+    const rows = (key) => (Array.isArray(body[key]) ? body[key] : [])
+        .filter(isRecord)
+        .map((row) => ({
+        key: asString(row['key']) ?? '',
+        reason: asString(row['reason']) ?? 'unspecified',
+        ...(asString(row['current_text']) ? { current_text: row['current_text'] } : {}),
+    }));
+    return {
+        status: asString(body['status']) ?? '',
+        created: count('created'),
+        updated: count('updated'),
+        skipped: count('skipped'),
+        denied: count('denied'),
+        denied_rows: rows('denied_rows'),
+        protected: count('protected'),
+        protected_rows: rows('protected_rows'),
+        rejected: count('rejected'),
+        total: count('total'),
+    };
+}
 /** Project a `SyncJobStatusResponse` (job status, or a DLQ entry) onto {@link SyncJobStatus}. */
 export function normalizeSyncJob(raw) {
     const body = isRecord(raw) ? raw : {};
@@ -343,10 +398,11 @@ export class LionRapidApiClient {
             key: compositeKey(targetLocale, namespace, it.key),
             value: it.value,
         }));
-        await this.request('PUT', '/api/integrations/targets/batch', {
+        const res = await this.request('PUT', '/api/integrations/targets/batch', {
             translations,
             format: 'contentunit',
         });
+        return normalizeTargetBatchResponse(res);
     }
     /**
      * Publish a single target row. POST /api/integrations/targets/{key}/mark-ready.
@@ -386,6 +442,9 @@ export class LionRapidApiClient {
         return {
             translations: normalizeTranslations(data.translations),
             version: data.meta?.version != null ? String(data.meta.version) : undefined,
+            ...(typeof data.meta?.project_uuid === 'string' && data.meta.project_uuid
+                ? { projectId: data.meta.project_uuid }
+                : {}),
             notModified: false,
             locked: false,
         };