@lionrapid/cli 0.3.0 → 0.5.0

package/dist/lockfile.js

@@ -0,0 +1,110 @@
+/**
+ * `.lionrapid/lock.json` — the record of what the SERVER last said.
+ *
+ * Today `push` re-uploads every string every time: 653 on the first run, 653
+ * on the second. And there is no way to know a translator edited a target
+ * locally, so `pull` would silently overwrite it. Both are the same missing
+ * thing — no record of the last known server state — and one mechanism buys
+ * incremental push, conflict detection, and a CI action that does not
+ * re-translate the world on every run.
+ *
+ * COMMITTED to version control, like `package-lock.json`. Per-machine would
+ * mean CI and a laptop disagree about what changed, which is exactly the
+ * disagreement an automated pipeline cannot tolerate.
+ *
+ * Two fields, two owners, and the split matters:
+ *   `sourceHash`       what we last SENT for a source key (push writes it)
+ *   `serverUpdatedAt`  when the server last told us about a row (PULL ONLY)
+ * Push must never fabricate `serverUpdatedAt`, or the lock would claim
+ * knowledge of a server state it never observed.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { generateAutoKey } from '@lionrapid/core';
+import { ConfigError } from './config.js';
+/** Where the lock lives, relative to the project root. */
+export const LOCKFILE_PATH = join('.lionrapid', 'lock.json');
+/** The only shape this CLI writes. A higher number is a newer CLI's file. */
+export const LOCK_VERSION = 1;
+/** A lock that knows nothing. Distinct from "everything changed" — see `readLock`. */
+export function emptyLock() {
+    return { version: LOCK_VERSION, entries: {} };
+}
+/**
+ * Hash a source value.
+ *
+ * Reuses `generateAutoKey`, the md5-12 already shared by core, edge, WordPress
+ * TS and WordPress PHP and pinned by `parity-vectors.json`. A second hash
+ * would be a second thing to keep in lockstep for no gain. Inline markup is
+ * part of the value, so the indexed tags travel into the hash — a bold run
+ * added around a word is a real change to push.
+ */
+export function hashSource(value) {
+    const styles = Object.keys(value.styles ?? {}).length > 0 ? JSON.stringify(value.styles) : '';
+    return generateAutoKey(styles ? `${value.text}
${styles}` : value.text);
+}
+/** The lock's key for a row: the coordinates a push actually addresses. */
+export function lockKey(namespace, key) {
+    return `${namespace}:${key}`;
+}
+/**
+ * Read the lock, or an empty one when there is no file.
+ *
+ * A MISSING lock is "we know nothing" (a backfill), never "everything
+ * changed". A CORRUPT lock throws: silently rebuilding one would mark local
+ * edits as server-known and lose them on the very next pull, which is the
+ * failure this file exists to prevent.
+ */
+export function readLock(cwd, opts = {}) {
+    const path = join(cwd, LOCKFILE_PATH);
+    if (!existsSync(path))
+        return emptyLock();
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (err) {
+        throw new ConfigError(`Could not parse ${LOCKFILE_PATH}: ${err instanceof Error ? err.message : String(err)}.\n` +
+            `  Delete ${LOCKFILE_PATH} and run \`lionrapid pull\` to rebuild it from the server.`);
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new ConfigError(`${LOCKFILE_PATH} is not a JSON object.\n` +
+            `  Delete ${LOCKFILE_PATH} and run \`lionrapid pull\` to rebuild it.`);
+    }
+    const lock = parsed;
+    if (typeof lock.version !== 'number' || lock.version > LOCK_VERSION) {
+        throw new ConfigError(`${LOCKFILE_PATH} is version ${String(lock.version)}, but this CLI understands ${LOCK_VERSION}.\n` +
+            '  Upgrade @lionrapid/cli, or delete the file and re-pull.');
+    }
+    if (opts.projectId && lock.projectId && lock.projectId !== opts.projectId) {
+        throw new ConfigError(`${LOCKFILE_PATH} belongs to project ${lock.projectId}, but this config is ${opts.projectId}.\n` +
+            '  A lock from another project would compute a meaningless diff — delete it and re-pull.');
+    }
+    return {
+        version: lock.version,
+        ...(lock.projectId ? { projectId: lock.projectId } : {}),
+        entries: lock.entries !== null && typeof lock.entries === 'object' && !Array.isArray(lock.entries)
+            ? lock.entries
+            : {},
+    };
+}
+/**
+ * Write the lock, keys sorted.
+ *
+ * Sorted because this file is committed: a lock that reorders itself produces
+ * a diff on every run and stops being reviewable, which is most of the reason
+ * to commit it. Written via temp+rename so an interrupted run cannot leave a
+ * half-written lock that the next run would refuse to parse.
+ */
+export function writeLock(cwd, lock) {
+    const path = join(cwd, LOCKFILE_PATH);
+    const sorted = {};
+    for (const key of Object.keys(lock.entries).sort())
+        sorted[key] = lock.entries[key];
+    const body = `${JSON.stringify({ ...lock, entries: sorted }, null, 2)}\n`;
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, body);
+    renameSync(tmp, path);
+}
+//# sourceMappingURL=lockfile.js.map

package/dist/time.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Timestamp handling for values that come off the wire.
+ *
+ * tm-server serialises with `datetime.isoformat()` and its clock is UTC, so a
+ * job's `completed_at` arrives as `2026-08-07T16:35:24.248993` — an ISO
+ * date-time with NO timezone designator. `Date.parse` reads that as LOCAL
+ * time, which on a UTC+3 machine rendered every server timestamp three hours
+ * early: `lionrapid status` showed a job finishing three hours before the push
+ * that created it.
+ *
+ * The rule is about the STRING, not about tm-server: no offset means UTC, an
+ * offset means exactly what it says. Appending `Z` unconditionally would fix
+ * today and break the day the server starts sending real offsets.
+ */
+/**
+ * Epoch milliseconds for a server timestamp, or null if it is absent or
+ * unparseable. An offset-less date-time is read as UTC; anything already
+ * carrying a zone is passed through untouched.
+ */
+export declare function parseServerTime(value: string | undefined | null): number | null;
+/**
+ * `2026-08-07 19:35:24` in the reader's own timezone. A value we cannot parse
+ * is echoed verbatim rather than rendered as "Invalid Date" — showing the raw
+ * string at least tells you what the server said.
+ */
+export declare function formatLocal(value: string | undefined | null): string;
+//# sourceMappingURL=time.d.ts.map

package/dist/time.js

@@ -0,0 +1,53 @@
+/**
+ * Timestamp handling for values that come off the wire.
+ *
+ * tm-server serialises with `datetime.isoformat()` and its clock is UTC, so a
+ * job's `completed_at` arrives as `2026-08-07T16:35:24.248993` — an ISO
+ * date-time with NO timezone designator. `Date.parse` reads that as LOCAL
+ * time, which on a UTC+3 machine rendered every server timestamp three hours
+ * early: `lionrapid status` showed a job finishing three hours before the push
+ * that created it.
+ *
+ * The rule is about the STRING, not about tm-server: no offset means UTC, an
+ * offset means exactly what it says. Appending `Z` unconditionally would fix
+ * today and break the day the server starts sending real offsets.
+ */
+/** True when the time part already carries `Z` or a `±HH:MM` / `±HHMM` offset. */
+function hasTimezone(value) {
+    const timePart = value.slice(value.indexOf('T') + 1);
+    return /[Zz]$/.test(timePart) || /[+-]\d{2}:?\d{2}$/.test(timePart);
+}
+/**
+ * Epoch milliseconds for a server timestamp, or null if it is absent or
+ * unparseable. An offset-less date-time is read as UTC; anything already
+ * carrying a zone is passed through untouched.
+ */
+export function parseServerTime(value) {
+    if (!value)
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    // A date-only value has no time to misinterpret — JS already reads those as
+    // UTC, and appending `Z` would make it unparseable.
+    const naive = trimmed.includes('T') && !hasTimezone(trimmed);
+    const ms = Date.parse(naive ? `${trimmed}Z` : trimmed);
+    return Number.isNaN(ms) ? null : ms;
+}
+/**
+ * `2026-08-07 19:35:24` in the reader's own timezone. A value we cannot parse
+ * is echoed verbatim rather than rendered as "Invalid Date" — showing the raw
+ * string at least tells you what the server said.
+ */
+export function formatLocal(value) {
+    if (!value)
+        return '—';
+    const ms = parseServerTime(value);
+    if (ms === null)
+        return value;
+    const d = new Date(ms);
+    const pad = (n) => String(n).padStart(2, '0');
+    return (`${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ` +
+        `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`);
+}
+//# sourceMappingURL=time.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lionrapid/cli",
-  "version": "0.3.0",
-  "description": "LionRapid CLI \u2014 sync translation files (iOS, Android, Flutter, JSON, YAML, PO) with the LionRapid backend",
+  "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",
   "types": "./dist/index.d.ts",