@lionrapid/cli 0.2.2 → 0.3.0

package/dist/job-history.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Local record of the sync jobs this machine has queued — `~/.lionrapid/jobs.json`.
+ *
+ * Why a file at all: `sync/batch` answers 202 (queued), so the only proof a push
+ * actually landed is the job's later state. You push, close the terminal, and
+ * come back — without this file the job ids are gone with the scrollback and
+ * there is nothing left to ask the server about.
+ *
+ * Why NOT in `~/.lionrapid/credentials`: different lifetime (history is
+ * disposable, a key is not) and different sensitivity. A corrupt or truncated
+ * history must never cost someone their login, so the two files never share a
+ * parser or a write. Everything here degrades to "no history" instead of
+ * throwing — losing visibility is bad, but failing a push because a cache file
+ * is unreadable is worse.
+ *
+ * The server purges finished non-DLQ jobs after ~1h, so for anything older this
+ * file is the ONLY answer available: a terminal status is recorded when we see
+ * it, and later reads report it from disk without a network call.
+ */
+/**
+ * One queued job, as this machine knew it. `files`/`keys` describe what was in
+ * the batch, so `lionrapid status` can say *what* is at risk without a network
+ * call.
+ */
+export interface JobHistoryEntry {
+    /** Server-assigned job id — the key for `GET /sync/jobs/{id}`. */
+    id: string;
+    /** Server this job was queued on (a machine may push to more than one). */
+    server: string;
+    /** The `project:` label from lionrapid.yml. */
+    project: string;
+    namespace: string;
+    /** Source locale of the batch. */
+    locale: string;
+    /** Files whose keys were in this batch (one, unless a file was chunked). */
+    files: string[];
+    /** Keys in the batch. */
+    keys: number;
+    /** ISO timestamp of the push that queued it. */
+    pushedAt: string;
+    /**
+     * Last status seen: the server's own vocabulary (`pending`, `processing`,
+     * `retry_pending`, `completed`, `failed`), or `gone` when the server no
+     * longer knows the job.
+     */
+    status: string;
+    /** ISO timestamp of the last status check against the server. */
+    checkedAt?: string;
+    /** Last error the server reported for this job. */
+    error?: string;
+    /** Why the backend gave up, when it did. */
+    deadLetterReason?: string;
+}
+/** Newest first — the order the file is stored in and the order callers get. */
+export type JobHistory = JobHistoryEntry[];
+/**
+ * Pruning. Both bounds apply on every write, so the file cannot grow forever:
+ *
+ * - 500 entries: a single big push is one job per file per 500-key chunk, so a
+ *   large repo can queue dozens at once. 500 keeps weeks of real use while
+ *   staying a ~100KB file.
+ * - 30 days: the server purges finished jobs after ~1h, so an entry older than
+ *   this can never be re-checked — it is a receipt, and a month-old receipt for
+ *   a push you have long since repeated is not worth carrying.
+ *
+ * Whichever bites first wins; entries are dropped oldest-first.
+ */
+export declare const JOB_HISTORY_MAX_ENTRIES = 500;
+export declare const JOB_HISTORY_MAX_AGE_DAYS = 30;
+/**
+ * True when there is no point asking the server again. `failed` counts: the
+ * server only sets it from its dead-letter path, so a failed job is one it gave
+ * up on. `gone` is ours — the job 404s (unknown id, or purged after retention).
+ */
+export declare function isTerminalJobStatus(status: string): boolean;
+/** Where the history lives: `~/.lionrapid/jobs.json`, beside the credentials file. */
+export declare function defaultJobHistoryPath(): string;
+/**
+ * Read the history, newest first. A missing, unreadable, or corrupt file is
+ * simply "no history" — never an exception, and the next write replaces it.
+ */
+export declare function readJobHistory(path?: string): JobHistory;
+/**
+ * Upsert `entries` (by job id) and write the pruned result. Returns what is now
+ * on disk, newest first. A failed write warns and returns the merged list — a
+ * push must not fail because its receipt could not be saved.
+ */
+export declare function recordJobs(entries: JobHistoryEntry[], path?: string): JobHistory;
+/** A status refresh for one job: everything except its identity may change. */
+export type JobStatusPatch = Pick<JobHistoryEntry, 'id'> & Partial<Pick<JobHistoryEntry, 'status' | 'checkedAt' | 'error' | 'deadLetterReason'>>;
+/**
+ * Fold status updates into the stored entries in a single read-modify-write.
+ * Unknown ids are ignored (the history is not a job database — it only tracks
+ * what this machine pushed).
+ */
+export declare function updateJobStatuses(patches: JobStatusPatch[], path?: string): JobHistory;
+//# sourceMappingURL=job-history.d.ts.map

package/dist/job-history.js

@@ -0,0 +1,175 @@
+/**
+ * Local record of the sync jobs this machine has queued — `~/.lionrapid/jobs.json`.
+ *
+ * Why a file at all: `sync/batch` answers 202 (queued), so the only proof a push
+ * actually landed is the job's later state. You push, close the terminal, and
+ * come back — without this file the job ids are gone with the scrollback and
+ * there is nothing left to ask the server about.
+ *
+ * Why NOT in `~/.lionrapid/credentials`: different lifetime (history is
+ * disposable, a key is not) and different sensitivity. A corrupt or truncated
+ * history must never cost someone their login, so the two files never share a
+ * parser or a write. Everything here degrades to "no history" instead of
+ * throwing — losing visibility is bad, but failing a push because a cache file
+ * is unreadable is worse.
+ *
+ * The server purges finished non-DLQ jobs after ~1h, so for anything older this
+ * file is the ONLY answer available: a terminal status is recorded when we see
+ * it, and later reads report it from disk without a network call.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/**
+ * Pruning. Both bounds apply on every write, so the file cannot grow forever:
+ *
+ * - 500 entries: a single big push is one job per file per 500-key chunk, so a
+ *   large repo can queue dozens at once. 500 keeps weeks of real use while
+ *   staying a ~100KB file.
+ * - 30 days: the server purges finished jobs after ~1h, so an entry older than
+ *   this can never be re-checked — it is a receipt, and a month-old receipt for
+ *   a push you have long since repeated is not worth carrying.
+ *
+ * Whichever bites first wins; entries are dropped oldest-first.
+ */
+export const JOB_HISTORY_MAX_ENTRIES = 500;
+export const JOB_HISTORY_MAX_AGE_DAYS = 30;
+/** Statuses the server never leaves, plus the CLI's own `gone`. */
+const TERMINAL_STATUSES = new Set(['completed', 'failed', 'gone']);
+/**
+ * True when there is no point asking the server again. `failed` counts: the
+ * server only sets it from its dead-letter path, so a failed job is one it gave
+ * up on. `gone` is ours — the job 404s (unknown id, or purged after retention).
+ */
+export function isTerminalJobStatus(status) {
+    return TERMINAL_STATUSES.has(status);
+}
+/**
+ * The user's home directory, `$HOME` first.
+ *
+ * Identical to `os.homedir()` for real users on POSIX (it reads `$HOME` too),
+ * but a JS-level `process.env.HOME` assignment is invisible to `homedir()`'s
+ * native `getenv` inside a worker thread — which is where vitest runs. Reading
+ * the variable directly means a relocated `$HOME` is honoured everywhere, so
+ * the test suite cannot write into the developer's real `~/.lionrapid`.
+ */
+function homeDir() {
+    return process.env['HOME'] || process.env['USERPROFILE'] || homedir();
+}
+/** Where the history lives: `~/.lionrapid/jobs.json`, beside the credentials file. */
+export function defaultJobHistoryPath() {
+    return join(homeDir(), '.lionrapid', 'jobs.json');
+}
+/** Paths already warned about this process — an unreadable history warns once. */
+const warned = new Set();
+function warnOnce(path, detail) {
+    if (warned.has(path))
+        return;
+    warned.add(path);
+    console.error(`warning: could not use the push history at ${path} (${detail})`);
+}
+function isEntry(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const e = value;
+    return typeof e['id'] === 'string' && e['id'].length > 0 && typeof e['pushedAt'] === 'string';
+}
+/**
+ * Read the history, newest first. A missing, unreadable, or corrupt file is
+ * simply "no history" — never an exception, and the next write replaces it.
+ */
+export function readJobHistory(path = defaultJobHistoryPath()) {
+    if (!existsSync(path))
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (err) {
+        warnOnce(path, err instanceof Error ? err.message : String(err));
+        return [];
+    }
+    const jobs = parsed !== null && typeof parsed === 'object' && Array.isArray(parsed.jobs)
+        ? parsed.jobs
+        : [];
+    return sortNewestFirst(jobs.filter(isEntry));
+}
+/**
+ * Upsert `entries` (by job id) and write the pruned result. Returns what is now
+ * on disk, newest first. A failed write warns and returns the merged list — a
+ * push must not fail because its receipt could not be saved.
+ */
+export function recordJobs(entries, path = defaultJobHistoryPath()) {
+    if (entries.length === 0)
+        return readJobHistory(path);
+    return mutate(path, (current) => [...entries, ...current]);
+}
+/**
+ * Fold status updates into the stored entries in a single read-modify-write.
+ * Unknown ids are ignored (the history is not a job database — it only tracks
+ * what this machine pushed).
+ */
+export function updateJobStatuses(patches, path = defaultJobHistoryPath()) {
+    if (patches.length === 0)
+        return readJobHistory(path);
+    const byId = new Map(patches.map((p) => [p.id, p]));
+    return mutate(path, (current) => current.map((entry) => {
+        const patch = byId.get(entry.id);
+        return patch ? { ...entry, ...stripUndefined(patch), id: entry.id } : entry;
+    }));
+}
+/** Read → transform → dedupe → prune → write. The one place that touches the file. */
+function mutate(path, transform) {
+    // Re-read immediately before writing: two pushes in different terminals
+    // otherwise clobber each other's ids.
+    const next = prune(dedupe(transform(readJobHistory(path))));
+    try {
+        write(path, next);
+    }
+    catch (err) {
+        warnOnce(path, err instanceof Error ? err.message : String(err));
+    }
+    return next;
+}
+/** First occurrence of an id wins — callers pass their fresher entries first. */
+function dedupe(entries) {
+    const seen = new Set();
+    const out = [];
+    for (const entry of entries) {
+        if (seen.has(entry.id))
+            continue;
+        seen.add(entry.id);
+        out.push(entry);
+    }
+    return out;
+}
+function prune(entries) {
+    const cutoff = Date.now() - JOB_HISTORY_MAX_AGE_DAYS * 24 * 60 * 60 * 1000;
+    const fresh = sortNewestFirst(entries).filter((e) => {
+        const at = Date.parse(e.pushedAt);
+        // An unparseable timestamp is kept: dropping a receipt because we cannot
+        // read its clock loses exactly the information the file exists to hold.
+        return Number.isNaN(at) || at >= cutoff;
+    });
+    return fresh.slice(0, JOB_HISTORY_MAX_ENTRIES);
+}
+function sortNewestFirst(entries) {
+    return [...entries].sort((a, b) => (a.pushedAt < b.pushedAt ? 1 : a.pushedAt > b.pushedAt ? -1 : 0));
+}
+function stripUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+}
+/**
+ * Write via a temp file + rename so a crash mid-write leaves the previous
+ * history intact rather than a half-written one. Same 0700/0600 permissions as
+ * the credentials file: this records project names and file paths.
+ */
+function write(path, entries) {
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = join(dir, `.jobs.${process.pid}.tmp`);
+    const body = `${JSON.stringify({ version: 1, jobs: entries }, null, 2)}\n`;
+    writeFileSync(tmp, body, { mode: 0o600 });
+    renameSync(tmp, path);
+}
+//# sourceMappingURL=job-history.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lionrapid/cli",
-  "version": "0.2.2",
-  "description": "LionRapid CLI — sync translation files (iOS, Android, Flutter, JSON, YAML, PO) with the LionRapid backend",
+  "version": "0.3.0",
+  "description": "LionRapid CLI \u2014 sync translation files (iOS, Android, Flutter, JSON, YAML, PO) with the LionRapid backend",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",