@lionrapid/cli 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -3,6 +3,58 @@
 All notable changes to `@lionrapid/cli`. Format based on
 [Keep a Changelog](https://keepachangelog.com/); this package follows semver.
 
+## 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

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
@@ -193,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 {
@@ -250,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.

package/dist/cli.js

@@ -602,7 +602,7 @@ export function buildProgram() {
         .option('--publish', 'in --target mode, mark pushed rows ready (public)')
         .option('--dry-run', 'parse + count what would be pushed, but make no network calls')
         .option('--backfill-missing', 'send only the rows the server is missing (asks the server)')
-        .option('--force', 'send everything, overwriting server rows (saves them to .lionrapid/history/ first)')
+        .option('--force', 'ignore the lockfile and resend every row (saves overwritten server rows to .lionrapid/history/). Does NOT override server-side protection of human-committed rows')
         .option('--json', 'emit the result as JSON on stdout (prose to stderr)')
         .option('-c, --config <path>', 'path to lionrapid.yml')
         .action(async (options) => {
@@ -658,7 +658,8 @@ export function buildProgram() {
                     continue;
                 }
                 const same = f.unchanged ? ` (${f.unchanged} unchanged)` : '';
-                out(`  ${f.skipped ? '· skipped (missing)' : '·'} ${f.file}: ${f.count}${same}`);
+                const held = f.refused ? ` (${f.refused} not written)` : '';
+                out(`  ${f.skipped ? '· skipped (missing)' : '·'} ${f.file}: ${f.count}${held}${same}`);
             }
             const failed = res.files.filter((f) => f.error);
             if (failed.length > 0) {
@@ -669,6 +670,25 @@ export function buildProgram() {
                 out('⚠ uploaded as drafts but not published — publishing needs an editor session token.\n' +
                     '  Set LIONRAPID_EDITOR_TOKEN, or publish in the dashboard.');
             }
+            // Rows the server declined to overwrite. Same voice as pull's
+            // kept-local warning: name the key and the reason, because a bare
+            // count tells you something happened without telling you what.
+            const refused = [
+                ...res.protected.map((r) => ({ ...r, kind: 'protected' })),
+                ...res.denied.map((r) => ({ ...r, kind: 'denied' })),
+            ];
+            if (refused.length > 0) {
+                out(`⚠ ${refused.length} row(s) were NOT overwritten — the server is protecting them:`);
+                const width = Math.max(...refused.map((r) => r.key.length));
+                for (const r of refused) {
+                    const current = r.current_text ? ` (server has: "${r.current_text}")` : '';
+                    out(`    ${r.key.padEnd(width)}  ${r.reason}${current}`);
+                }
+                // There is deliberately no override flag, so do not imply one.
+                // These are the paths that DO change a committed row.
+                out('  A human committed these. There is no CLI override — change them in the');
+                out('  Visual Editor, or use "Use for all" to apply one wording across the project.');
+            }
             // The whole point: "pushed" above is what we SENT. The server stores
             // it in the background, so print what to watch and where it is saved.
             if (res.jobs.length > 0) {

package/dist/commands/push.d.ts

@@ -14,7 +14,7 @@
  * via `targets/batch`, optionally publishing them with `--publish`.
  */
 import { type LionRapidConfig } from '../config.js';
-import type { LionRapidApiClient } from '../api-client.js';
+import type { LionRapidApiClient, TargetRowOutcome } from '../api-client.js';
 /**
  * A sync job the server queued for one batch of this push.
  *
@@ -72,6 +72,11 @@ export interface PushFileResult {
     skipped?: boolean;
     /** Keys this file already had on the server, per the lock — not re-sent. */
     unchanged?: number;
+    /**
+     * Rows sent for this file that the server did not write — protected,
+     * denied, or skipped. Target mode only; `count` is what actually landed.
+     */
+    refused?: number;
     /** Set when this file failed (parse or upload) — it was not (fully) pushed. */
     error?: string;
 }
@@ -84,6 +89,23 @@ export interface PushResult {
     pushed: number;
     /** Keys the lock says the server already has, so they were not sent again. */
     skipped: number;
+    /**
+     * Rows the server REFUSED to overwrite because a human committed them.
+     *
+     * A machine caller (no user identity) does not get to overwrite a
+     * translator's committed work, and there is deliberately no override. These
+     * were NOT written, so they are not in `pushed`.
+     */
+    protected: TargetRowOutcome[];
+    /** Rows the caller was not authorized to edit. Same class: not written. */
+    denied: TargetRowOutcome[];
+    /**
+     * Rows the SERVER skipped — source row missing, or the value would not
+     * parse. Distinct from `protected`: a different cause, and both can be
+     * non-zero in one push. Named to avoid colliding with `skipped` above,
+     * which is this CLI's lockfile diff.
+     */
+    serverSkipped: number;
     /**
      * What this push is doing, split so `--dry-run` can answer the question you
      * ran it to ask: am I ADDING strings, or overwriting ones that already

package/dist/commands/push.js

@@ -86,6 +86,21 @@ export async function runPush(config, client, opts) {
     let skipped = 0;
     let diffAdded = 0;
     let diffChanged = 0;
+    const protectedRows = [];
+    const deniedRows = [];
+    let serverSkipped = 0;
+    /** Rows the server confirmed it wrote (target mode only). */
+    let written = 0;
+    /** The same, for the file currently being processed. */
+    let writtenForFile = 0;
+    /**
+     * Rows the server said it REFUSED for the current file, summed from its own
+     * buckets. Deliberately not (sent − written): a row whose text already
+     * matches is written by nobody and refused by nobody — the server leaves it
+     * out of every bucket and out of `total` — so the subtraction would report a
+     * no-op as a problem. Seen live: 2 sent, `protected: 1`, `total: 1`.
+     */
+    let refusedForFile = 0;
     // INCREMENTAL. The lock says what the server already has, so a second run
     // sends "4 changed" rather than all 653. No lock (first run, or a fresh
     // checkout) means we know nothing, which is a backfill — send everything.
@@ -138,6 +153,10 @@ export async function runPush(config, client, opts) {
             const parseLocale = mode === 'source' ? config.sourceLocale : opts.target;
             const entries = adapter.parse(readFileSync(absPath, 'utf8'), { locale: parseLocale });
             const all = entries.map((e) => ({ key: e.key, value: e.value }));
+            // Reset per file: the header total is the sum of these, so they have to
+            // measure the same thing.
+            writtenForFile = 0;
+            refusedForFile = 0;
             const hashes = new Map(all.map((it) => [it.key, hashSource(it.value)]));
             // Three modes. `--force` and `--backfill-missing` both ASK THE SERVER
             // rather than trusting the lock, which is what makes them a recovery
@@ -207,9 +226,25 @@ export async function runPush(config, client, opts) {
                         }
                     }
                     else {
-                        await client.targetsBatch(opts.target, namespace, batch);
+                        const outcome = await client.targetsBatch(opts.target, namespace, batch);
+                        protectedRows.push(...outcome.protected_rows);
+                        deniedRows.push(...outcome.denied_rows);
+                        serverSkipped += outcome.skipped;
+                        // Count what the SERVER says it wrote, not what we put on the
+                        // wire. A refused row is not a pushed row — the whole point of
+                        // this response is that "sent" and "stored" can differ.
+                        written += outcome.created + outcome.updated;
+                        writtenForFile += outcome.created + outcome.updated;
+                        refusedForFile +=
+                            outcome.protected + outcome.denied + outcome.skipped + outcome.rejected;
                         if (canPublish) {
+                            // Never mark-ready a row the server declined to write: it would
+                            // publish whatever is already there under the guise of this
+                            // push, which is worse than the refusal it followed.
+                            const refused = new Set([...outcome.protected_rows, ...outcome.denied_rows].map((r) => r.key));
                             for (const it of batch) {
+                                if (refused.has(`${opts.target}:${namespace}:${it.key}`))
+                                    continue;
                                 await client.markReady(opts.target, namespace, it.key);
                             }
                         }
@@ -225,10 +260,13 @@ export async function runPush(config, client, opts) {
                     lock.entries[key] = { ...lock.entries[key], sourceHash: hashes.get(it.key) };
                 }
             }
-            pushed += items.length;
+            pushed += mode === 'target' ? 0 : items.length;
             files.push({
                 file: relPath,
-                count: items.length,
+                // Target mode reports what the SERVER wrote; source mode reports what
+                // was queued, which is all a 202 can honestly claim.
+                count: mode === 'target' ? writtenForFile : items.length,
+                ...(mode === 'target' && refusedForFile > 0 ? { refused: refusedForFile } : {}),
                 ...(all.length > items.length ? { unchanged: all.length - items.length } : {}),
             });
         }
@@ -254,8 +292,13 @@ export async function runPush(config, client, opts) {
         writeLock(opts.lockPath, lock);
     return {
         mode,
-        pushed,
+        // Target mode reports what the server confirmed it WROTE. Source mode
+        // reports what was queued, which is all a 202 can honestly claim.
+        pushed: mode === 'target' ? written : pushed,
         skipped,
+        protected: protectedRows,
+        denied: deniedRows,
+        serverSkipped,
         ...(projectCheck ? { projectCheck } : {}),
         ...(mode === 'source'
             ? { diff: { added: diffAdded, changed: diffChanged, unchanged: skipped } }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lionrapid/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "LionRapid CLI — sync translation files (iOS, Android, Flutter, JSON, YAML, PO) with the LionRapid backend",
   "type": "module",
   "main": "./dist/index.js",