@lionrapid/cli 0.2.1 → 0.3.0

package/dist/config.js

@@ -9,10 +9,11 @@
  *  - `parseConfig(string)` is split from `loadConfig(path)` so the validator is
  *    unit-testable without touching the filesystem.
  */
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { parse as parseYaml } from 'yaml';
+import { discoverFiles } from './scan/discover.js';
 /** Translation file formats the CLI can parse/serialize. */
 export const FILE_FORMATS = [
     'json',
@@ -29,6 +30,10 @@ export const FILE_FORMATS = [
  * `target` path is one shared file and does not need a `{locale}` placeholder.
  */
 export const MULTI_LOCALE_FORMATS = new Set(['xcstrings']);
+/** True when a `files[].source` is a glob pattern rather than a concrete path. */
+export function isGlobSource(source) {
+    return /[*?]/.test(source);
+}
 /** Thrown when `lionrapid.yml` is missing, unparseable, or invalid. */
 export class ConfigError extends Error {
     issues;
@@ -227,16 +232,79 @@ function validateConfig(raw) {
                     entryNs = entry['namespace'];
                 }
             }
+            // flat (optional): only JSON/YAML re-nest dotted keys on serialize, so
+            // the flag is meaningless (and likely a config mistake) anywhere else.
+            let entryFlat;
+            if (entry['flat'] !== undefined) {
+                if (typeof entry['flat'] !== 'boolean') {
+                    issues.push({ path: `${base}.flat`, message: 'must be a boolean when set' });
+                }
+                else if (validFormat && format !== 'json' && format !== 'yaml') {
+                    issues.push({
+                        path: `${base}.flat`,
+                        message: `only meaningful for json/yaml (${String(format)} output is always flat)`,
+                    });
+                }
+                else {
+                    entryFlat = entry['flat'];
+                }
+            }
+            // Glob sources: {basename} must appear in target AND namespace (else the
+            // expansion is ambiguous — every match would collide); a concrete source
+            // must not use the token at all.
+            const src = entry['source'];
+            const tgt = entry['target'];
+            const glob = isNonEmptyString(src) && isGlobSource(src);
+            const srcHasBase = isNonEmptyString(src) && src.includes('{basename}');
+            const tgtHasBase = isNonEmptyString(tgt) && tgt.includes('{basename}');
+            const nsHasBase = entryNs?.includes('{basename}') ?? false;
+            if (srcHasBase) {
+                issues.push({
+                    path: `${base}.source`,
+                    message: 'the "{basename}" token is only valid in target/namespace',
+                });
+            }
+            if (glob) {
+                if (isNonEmptyString(tgt) && !tgtHasBase) {
+                    issues.push({
+                        path: `${base}.target`,
+                        message: 'must contain the "{basename}" token when source is a glob',
+                    });
+                }
+                if (!nsHasBase) {
+                    issues.push({
+                        path: `${base}.namespace`,
+                        message: 'required for a glob source and must contain the "{basename}" token',
+                    });
+                }
+            }
+            else {
+                if (tgtHasBase) {
+                    issues.push({
+                        path: `${base}.target`,
+                        message: 'the "{basename}" token is only valid when source is a glob',
+                    });
+                }
+                if (nsHasBase) {
+                    issues.push({
+                        path: `${base}.namespace`,
+                        message: 'the "{basename}" token is only valid when source is a glob',
+                    });
+                }
+            }
             // Only push a typed entry if its required fields are sound.
             if (validFormat &&
                 isNonEmptyString(entry['source']) &&
                 isNonEmptyString(entry['target']) &&
-                (isMultiLocale || entry['target'].includes('{locale}'))) {
+                (isMultiLocale || entry['target'].includes('{locale}')) &&
+                !srcHasBase &&
+                (glob ? tgtHasBase && nsHasBase : !tgtHasBase && !nsHasBase)) {
                 files.push({
                     format: format,
                     source: entry['source'],
                     target: entry['target'],
                     ...(entryNs ? { namespace: entryNs } : {}),
+                    ...(entryFlat !== undefined ? { flat: entryFlat } : {}),
                 });
             }
         });
@@ -270,6 +338,41 @@ export function parseConfig(rawYaml) {
     }
     return validateConfig(parsed);
 }
+/**
+ * Expand glob `files` entries into one concrete entry per matched file: the
+ * match's extension-less basename substitutes the `{basename}` token in
+ * `target` and `namespace`. Non-glob entries pass through untouched; matches
+ * come back sorted (deterministic expansion). A glob matching nothing warns
+ * instead of silently vanishing — a typo'd pattern must not no-op a push.
+ *
+ * Called at config load (loadOfflineContext / doctor), so every command
+ * downstream only ever sees concrete entries.
+ */
+export function expandGlobEntries(files, cwd, warn = (m) => console.error(m)) {
+    const out = [];
+    for (const entry of files) {
+        if (!isGlobSource(entry.source)) {
+            out.push(entry);
+            continue;
+        }
+        const matches = discoverFiles(cwd, { include: [entry.source] });
+        if (matches.length === 0) {
+            warn(`warning: files entry "${entry.source}" matched no files`);
+            continue;
+        }
+        for (const rel of matches) {
+            const base = basename(rel).replace(/\.[^.]*$/, '');
+            out.push({
+                format: entry.format,
+                source: rel,
+                target: entry.target.replaceAll('{basename}', base),
+                namespace: (entry.namespace ?? '{basename}').replaceAll('{basename}', base),
+                ...(entry.flat !== undefined ? { flat: entry.flat } : {}),
+            });
+        }
+    }
+    return out;
+}
 /** Read + parse + validate the config at `path`. */
 export function loadConfig(path) {
     if (!existsSync(path)) {
@@ -277,6 +380,55 @@ export function loadConfig(path) {
     }
     return parseConfig(readFileSync(path, 'utf8'));
 }
+/** Where the CLI reads/writes credentials: `~/.lionrapid/credentials`. */
+export function defaultCredentialsPath() {
+    return join(homedir(), '.lionrapid', 'credentials');
+}
+/** Paths already warned about this process — the perms warning fires once per file. */
+const warnedPerms = new Set();
+/** Warn (once per path) when the credentials file is readable by group/other. */
+function warnIfWorldReadable(path) {
+    if (process.platform === 'win32' || warnedPerms.has(path))
+        return;
+    if ((statSync(path).mode & 0o077) !== 0) {
+        warnedPerms.add(path);
+        console.error(`warning: ${path} is readable by other users — run: chmod 600 ${path}`);
+    }
+}
+/**
+ * Reject a key that can't travel in an HTTP header (fetch encodes headers as
+ * Latin-1 and throws an obscure ByteString error otherwise). The classic case
+ * is copying the dashboard's truncated key display, `sk_eng_…last4` — that
+ * ellipsis is U+2026, not part of the key.
+ */
+export function assertKeyCharset(key) {
+    const bad = /[^\x21-\x7e]/.exec(key);
+    if (bad) {
+        const c = bad[0];
+        const cp = c.codePointAt(0).toString(16).padStart(4, '0').toUpperCase();
+        throw new ApiKeyError(`The API key contains a character that can't be sent in an HTTP header: '${c}' (U+${cp}). ` +
+            'This usually means a truncated display value was copied — paste the full key.');
+    }
+    return key;
+}
+/**
+ * Server URLs that have a scoped entry in the credentials file. Lets `init`
+ * default its server to the one you just logged into instead of asking again.
+ */
+export function listCredentialServers(credentialsPath) {
+    const path = credentialsPath ?? defaultCredentialsPath();
+    if (!existsSync(path))
+        return [];
+    try {
+        const creds = JSON.parse(readFileSync(path, 'utf8'));
+        if (!isRecord(creds))
+            return [];
+        return Object.keys(creds).filter((k) => k !== 'default' && isNonEmptyString(creds[k]));
+    }
+    catch {
+        return [];
+    }
+}
 /**
  * Resolve the API key. Precedence:
  *   1. `LIONRAPID_API_KEY` environment variable
@@ -292,9 +444,10 @@ export function resolveApiKey(opts = {}) {
     const env = opts.env ?? process.env;
     const fromEnv = env['LIONRAPID_API_KEY'];
     if (isNonEmptyString(fromEnv))
-        return fromEnv.trim();
-    const credentialsPath = opts.credentialsPath ?? join(homedir(), '.lionrapid', 'credentials');
+        return assertKeyCharset(fromEnv.trim());
+    const credentialsPath = opts.credentialsPath ?? defaultCredentialsPath();
     if (existsSync(credentialsPath)) {
+        warnIfWorldReadable(credentialsPath);
         let creds;
         try {
             creds = JSON.parse(readFileSync(credentialsPath, 'utf8'));
@@ -305,11 +458,12 @@ export function resolveApiKey(opts = {}) {
         if (isRecord(creds)) {
             const scoped = opts.server ? creds[opts.server] : undefined;
             if (isNonEmptyString(scoped))
-                return scoped.trim();
+                return assertKeyCharset(scoped.trim());
             const fallback = creds['default'];
             if (isNonEmptyString(fallback)) {
-                if (!opts.server || isTrustedDefaultHost(opts.server))
-                    return fallback.trim();
+                if (!opts.server || isTrustedDefaultHost(opts.server)) {
+                    return assertKeyCharset(fallback.trim());
+                }
                 throw new ApiKeyError(`Refusing to send the "default" credential to unrecognized host ${opts.server}. ` +
                     `Add a server-scoped key for it first: lionrapid login --server ${opts.server}`);
             }

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/dist/types-gen/extract.js

@@ -52,6 +52,12 @@ function readBlock(text, open) {
     }
     return { body: text.slice(open + 1), end: text.length };
 }
+/**
+ * Only identifier-shaped labels may reach type position — with `types --server`
+ * the message text is server-controlled, and anything looser could break out of
+ * the `'label'` literal in the generated .d.ts.
+ */
+const SAFE_LABEL_RE = /^[A-Za-z0-9_]+$/;
 /** Extract top-level select option labels (excluding `other`). */
 function selectOptions(body) {
     // body looks like: `gender, select, male{…} female{…} other{…}` — strip the
@@ -69,7 +75,7 @@ function selectOptions(body) {
         while (i < rest.length && /\s/.test(rest[i]))
             i += 1;
         if (label && rest[i] === '{') {
-            if (label !== 'other')
+            if (label !== 'other' && SAFE_LABEL_RE.test(label))
                 options.push(label);
             let depth = 1;
             i += 1;

package/dist/types-gen/generate.js

@@ -5,7 +5,15 @@
  */
 import { extractParams } from './extract.js';
 function escapeKey(key) {
-    return key.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+    return (key
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        // Control chars and JS line terminators (incl. U+2028/29) would break out
+        // of the quoted key — keys are server-controlled under `types --server`.
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\u0000-\u001f\u007f\u2028\u2029]/g, (c) => {
+        return `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`;
+    }));
 }
 export function generateDts(keyTexts, options = {}) {
     const keys = [...keyTexts.keys()].sort();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lionrapid/cli",
-  "version": "0.2.1",
-  "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",