@lionrapid/cli 0.2.2 → 0.4.0

package/dist/config.d.ts

@@ -41,7 +41,22 @@ export interface FileEntry {
 /** True when a `files[].source` is a glob pattern rather than a concrete path. */
 export declare function isGlobSource(source: string): boolean;
 export interface LionRapidConfig {
-    project: string;
+    /**
+     * The project the API key must resolve to — checked on every push.
+     *
+     * Replaces the old free-text `project:`, which nothing verified. Proven on
+     * 2026-08-07: a push declaring `project: cli-verify`, a name that does not
+     * exist, landed in the project the KEY belongs to, while the CLI reported
+     * the config's label for 30 jobs that went somewhere else. THE API KEY
+     * SELECTS THE PROJECT; the config never could.
+     *
+     * OPTIONAL, because the server field it comes from (`meta.project_uuid`) is
+     * real but UNDECLARED — the translations route returns a raw Response to set
+     * its ETag header, bypassing the response model, so a later tidy-up could
+     * remove it in what looks like a cosmetic change (server task #70). A guard
+     * that cannot arm must not block a push.
+     */
+    projectId?: string;
     server: string;
     sourceLocale: string;
     targetLocales: string[];
@@ -71,8 +86,26 @@ export declare class ConfigError extends Error {
 export declare class ApiKeyError extends Error {
     constructor(message: string);
 }
+/** Opt-in for sending a key to a host we do not recognize (self-hosted). */
+export declare const ALLOW_UNTRUSTED_HOST_ENV = "LIONRAPID_ALLOW_UNTRUSTED_HOST";
 /** Locate the config file in `cwd`, returning its path or null. */
 export declare function findConfigPath(cwd?: string): string | null;
+/**
+ * What a source-only config costs you. Named commands, not a vague "no
+ * targets": the point is that nothing is broken — two commands simply have
+ * nothing to do until the project has target languages.
+ */
+export declare const NO_TARGETS_WARNING: string;
+/**
+ * The warning, but only for the commands it applies to.
+ *
+ * Emitting it at parse time meant every command carried it — including
+ * `status`, which reports what the backend did with a job and has nothing to
+ * do with target locales. A warning that fires where it does not apply is how
+ * people learn to ignore warnings, so the three commands that are actually
+ * affected ask for it and nobody else sees it.
+ */
+export declare function noTargetsNotice(config: LionRapidConfig): string | undefined;
 /** Parse + validate a YAML config string into a typed config. */
 export declare function parseConfig(rawYaml: string): LionRapidConfig;
 /**
@@ -88,6 +121,19 @@ export declare function parseConfig(rawYaml: string): LionRapidConfig;
 export declare function expandGlobEntries(files: FileEntry[], cwd: string, warn?: (message: string) => void): FileEntry[];
 /** Read + parse + validate the config at `path`. */
 export declare function loadConfig(path: string): LionRapidConfig;
+/**
+ * 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. Without
+ * this, the suite reads (and could write) the developer's real
+ * `~/.lionrapid/`: a test asserting "no credentials" passes in CI and fails on
+ * a laptop that has logged in, which is a silent source of divergence.
+ *
+ * Shared by {@link defaultCredentialsPath} and the job history.
+ */
+export declare function homeDir(): string;
 /** Where the CLI reads/writes credentials: `~/.lionrapid/credentials`. */
 export declare function defaultCredentialsPath(): string;
 /**
@@ -116,10 +162,59 @@ export interface ResolveApiKeyOptions {
  *   2. credentials file (JSON: `{ "default": "sk_...", "<server>": "sk_..." }`)
  * The key is never read from `lionrapid.yml` (which is committed to git).
  *
- * Trust rule: the `default` credential is only handed out for recognized
- * LionRapid hosts (`*.lionrapid.com`) and localhost. Any other server needs
- * its own server-scoped entry — otherwise a committed lionrapid.yml pointing
- * at an attacker host would exfiltrate the key of anyone running `push`.
+ * Trust rule: a key is only handed out for recognized LionRapid hosts
+ * (`*.lionrapid.com`) and localhost. Any other server needs either its own
+ * server-scoped credentials entry or {@link ALLOW_UNTRUSTED_HOST_ENV} —
+ * otherwise a committed lionrapid.yml pointing at an attacker host would
+ * exfiltrate the key of anyone running `push`.
  */
 export declare function resolveApiKey(opts?: ResolveApiKeyOptions): string;
+/** Where a resolved key came from. `whoami` shows this; nothing else needs it. */
+export type KeySource = 'env' | 'server-scoped' | 'default';
+export interface ResolvedKey {
+    key: string;
+    source: KeySource;
+    /** The env var name, or the credentials entry the key was read from. */
+    scope: string;
+}
+/**
+ * {@link resolveApiKey}, plus WHERE the key came from.
+ *
+ * One implementation, two views: `whoami` has to say which credential is about
+ * to be used, and a second copy of this precedence ladder would be a place for
+ * the two to drift — the displayed key would stop being the sent key, which is
+ * the exact confusion `whoami` exists to end.
+ */
+export declare function resolveApiKeyDetailed(opts?: ResolveApiKeyOptions): ResolvedKey;
+/**
+ * Display form of a key: prefix + last four, never the middle.
+ *
+ * A key shorter than the prefix+last4 window would otherwise be echoed almost
+ * whole, so a short (malformed, truncated) value drops the prefix entirely —
+ * "mask" must not become "print" for the one input where it matters.
+ */
+export declare function maskKey(key: string): string;
+/** What a key class can and cannot do, in the terms a user actually hits. */
+export interface KeyCapability {
+    kind: 'publishable' | 'master' | 'editor-session' | 'unknown';
+    /** One line, naming the functional line rather than the scope vocabulary. */
+    summary: string;
+    /** True when `push --target` / `--publish` will work (needs `targets:write`). */
+    canWriteTargets: boolean;
+}
+/**
+ * A key's class, from its prefix.
+ *
+ * The functional line is `targets:write`, NOT the queue scopes. A `pk_` holder
+ * can push sources, pull and read status, but `push --target` dies on a bare
+ * 403 from `targets/batch` — hit for real on 2026-08-07 while trying to
+ * publish a row, and exactly the kind of thing worth saying BEFORE the request
+ * instead of after it.
+ */
+export declare function keyCapability(key: string): KeyCapability;
+/** Every saved credential, as `{ scope, masked }`. Never returns key material. */
+export declare function listCredentials(credentialsPath?: string): {
+    scope: string;
+    masked: string;
+}[];
 //# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -72,6 +72,42 @@ function isTrustedDefaultHost(server) {
     const host = url.hostname;
     return host === 'lionrapid.com' || host.endsWith('.lionrapid.com') || LOCAL_HOSTS.has(host);
 }
+/** Opt-in for sending a key to a host we do not recognize (self-hosted). */
+export const ALLOW_UNTRUSTED_HOST_ENV = 'LIONRAPID_ALLOW_UNTRUSTED_HOST';
+/**
+ * True only for an explicit `1`/`true`. A flag someone set to `0` or `false`
+ * to turn the behaviour OFF must never turn it on — "any non-empty value"
+ * would do exactly that.
+ */
+function allowsUntrustedHost(env) {
+    const raw = env[ALLOW_UNTRUSTED_HOST_ENV]?.trim().toLowerCase();
+    return raw === '1' || raw === 'true';
+}
+/**
+ * Hold `LIONRAPID_API_KEY` to the same trust boundary as the credentials-file
+ * `default`.
+ *
+ * The env path used to return before any host check, on the reasoning that an
+ * operator who exports a secret has vetted where it goes (PLAN 19, 34ae81a:
+ * "CI sets it deliberately"). That reasoning fails in the very place it was
+ * written for. In CI the two halves are set by DIFFERENT PEOPLE: the operator
+ * injects the secret once, while `server:` lives in a committed lionrapid.yml
+ * that can arrive by pull request. Setting a key deliberately is not the same
+ * as approving its destination, and a valid key sent to an attacker is not
+ * self-correcting the way a wrong key is (that just 401s).
+ *
+ * No server yet (an invalid config, so `doctor` has nothing to match on) means
+ * there is no host to distrust — allow it, and let the config check report the
+ * real problem.
+ */
+function assertEnvKeyDestination(server, env) {
+    if (!server || isTrustedDefaultHost(server) || allowsUntrustedHost(env))
+        return;
+    throw new ApiKeyError(`Refusing to send LIONRAPID_API_KEY to ${server} — not a recognized LionRapid host.\n` +
+        '  `server:` comes from lionrapid.yml, which can change by pull request, so an\n' +
+        '  unrecognized host means your key travels wherever that file says.\n' +
+        `  If this is your own self-hosted server, set ${ALLOW_UNTRUSTED_HOST_ENV}=1.`);
+}
 /** Validate the `server` config value; returns an issue message or null if OK. */
 function validateServerUrl(server) {
     let url;
@@ -79,7 +115,7 @@ function validateServerUrl(server) {
         url = new URL(server);
     }
     catch {
-        return 'must be a valid https:// URL (e.g. https://api.lionrapid.com)';
+        return 'must be a valid https:// URL (e.g. https://app.lionrapid.com)';
     }
     if (url.protocol === 'https:')
         return null;
@@ -102,16 +138,35 @@ function isRecord(value) {
 function isNonEmptyString(value) {
     return typeof value === 'string' && value.trim().length > 0;
 }
+/**
+ * What a source-only config costs you. Named commands, not a vague "no
+ * targets": the point is that nothing is broken — two commands simply have
+ * nothing to do until the project has target languages.
+ */
+export const NO_TARGETS_WARNING = 'note: no targetLocales in lionrapid.yml — `push` still uploads your source strings,\n' +
+    '  but `pull` and `push --target` have nothing to do until this project has target\n' +
+    '  languages. Add them in the dashboard, then re-run `lionrapid init`.';
+/**
+ * The warning, but only for the commands it applies to.
+ *
+ * Emitting it at parse time meant every command carried it — including
+ * `status`, which reports what the backend did with a job and has nothing to
+ * do with target locales. A warning that fires where it does not apply is how
+ * people learn to ignore warnings, so the three commands that are actually
+ * affected ask for it and nobody else sees it.
+ */
+export function noTargetsNotice(config) {
+    return config.targetLocales.length === 0 ? NO_TARGETS_WARNING : undefined;
+}
 /** Validate a raw parsed object into a typed config, collecting all issues. */
 function validateConfig(raw) {
     const issues = [];
     if (!isRecord(raw)) {
         throw new ConfigError('Config must be a YAML mapping (key: value pairs).');
     }
-    // Scalars
-    if (!isNonEmptyString(raw['project'])) {
-        issues.push({ path: 'project', message: 'required non-empty string' });
-    }
+    // Scalars. NOTE: `project` is deliberately unread — the old free-text
+    // label is gone, and a config that still carries one simply ignores it
+    // rather than failing (pre-customer, but a stale field is not an error).
     if (!isNonEmptyString(raw['server'])) {
         issues.push({ path: 'server', message: 'required non-empty string' });
     }
@@ -123,16 +178,29 @@ function validateConfig(raw) {
     if (!isNonEmptyString(raw['sourceLocale'])) {
         issues.push({ path: 'sourceLocale', message: 'required non-empty string' });
     }
-    // targetLocales
+    if (raw['projectId'] !== undefined && !isNonEmptyString(raw['projectId'])) {
+        issues.push({ path: 'projectId', message: 'must be a non-empty string when set' });
+    }
+    // targetLocales — OPTIONAL. `push` sends source rows and the server decides
+    // what to translate them into, so a config that only declares a source is a
+    // complete, working config. Requiring targets made `init`'s own output
+    // invalid (it writes `targetLocales: []` whenever it cannot reach the
+    // server), and an invalid config makes `doctor` blame the API key instead.
+    //
+    // Absent and empty both warn; a wrong TYPE is still an error, because that
+    // is a typo rather than a choice.
+    // An absent or empty list is simply an empty list — `noTargetsNotice` turns
+    // that into a message for the commands it concerns.
     const targetLocales = [];
-    if (!Array.isArray(raw['targetLocales']) || raw['targetLocales'].length === 0) {
+    const rawTargets = raw['targetLocales'];
+    if (rawTargets !== undefined && rawTargets !== null && !Array.isArray(rawTargets)) {
         issues.push({
             path: 'targetLocales',
-            message: 'required non-empty array of locale codes',
+            message: 'must be an array of locale codes when set',
         });
     }
-    else {
-        raw['targetLocales'].forEach((loc, i) => {
+    else if (Array.isArray(rawTargets) && rawTargets.length > 0) {
+        rawTargets.forEach((loc, i) => {
             if (!isNonEmptyString(loc)) {
                 issues.push({ path: `targetLocales[${i}]`, message: 'must be a non-empty string' });
             }
@@ -313,7 +381,7 @@ function validateConfig(raw) {
         throw new ConfigError('Invalid lionrapid config:', issues);
     }
     return {
-        project: raw['project'],
+        ...(isNonEmptyString(raw['projectId']) ? { projectId: raw['projectId'] } : {}),
         server: raw['server'].replace(/\/$/, ''),
         sourceLocale: raw['sourceLocale'],
         targetLocales,
@@ -380,9 +448,24 @@ export function loadConfig(path) {
     }
     return parseConfig(readFileSync(path, 'utf8'));
 }
+/**
+ * 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. Without
+ * this, the suite reads (and could write) the developer's real
+ * `~/.lionrapid/`: a test asserting "no credentials" passes in CI and fails on
+ * a laptop that has logged in, which is a silent source of divergence.
+ *
+ * Shared by {@link defaultCredentialsPath} and the job history.
+ */
+export function homeDir() {
+    return process.env['HOME'] || process.env['USERPROFILE'] || homedir();
+}
 /** Where the CLI reads/writes credentials: `~/.lionrapid/credentials`. */
 export function defaultCredentialsPath() {
-    return join(homedir(), '.lionrapid', 'credentials');
+    return join(homeDir(), '.lionrapid', 'credentials');
 }
 /** Paths already warned about this process — the perms warning fires once per file. */
 const warnedPerms = new Set();
@@ -435,16 +518,34 @@ export function listCredentialServers(credentialsPath) {
  *   2. credentials file (JSON: `{ "default": "sk_...", "<server>": "sk_..." }`)
  * The key is never read from `lionrapid.yml` (which is committed to git).
  *
- * Trust rule: the `default` credential is only handed out for recognized
- * LionRapid hosts (`*.lionrapid.com`) and localhost. Any other server needs
- * its own server-scoped entry — otherwise a committed lionrapid.yml pointing
- * at an attacker host would exfiltrate the key of anyone running `push`.
+ * Trust rule: a key is only handed out for recognized LionRapid hosts
+ * (`*.lionrapid.com`) and localhost. Any other server needs either its own
+ * server-scoped credentials entry or {@link ALLOW_UNTRUSTED_HOST_ENV} —
+ * otherwise a committed lionrapid.yml pointing at an attacker host would
+ * exfiltrate the key of anyone running `push`.
  */
 export function resolveApiKey(opts = {}) {
+    return resolveApiKeyDetailed(opts).key;
+}
+/**
+ * {@link resolveApiKey}, plus WHERE the key came from.
+ *
+ * One implementation, two views: `whoami` has to say which credential is about
+ * to be used, and a second copy of this precedence ladder would be a place for
+ * the two to drift — the displayed key would stop being the sent key, which is
+ * the exact confusion `whoami` exists to end.
+ */
+export function resolveApiKeyDetailed(opts = {}) {
     const env = opts.env ?? process.env;
     const fromEnv = env['LIONRAPID_API_KEY'];
-    if (isNonEmptyString(fromEnv))
-        return assertKeyCharset(fromEnv.trim());
+    if (isNonEmptyString(fromEnv)) {
+        assertEnvKeyDestination(opts.server, env);
+        return {
+            key: assertKeyCharset(fromEnv.trim()),
+            source: 'env',
+            scope: 'LIONRAPID_API_KEY',
+        };
+    }
     const credentialsPath = opts.credentialsPath ?? defaultCredentialsPath();
     if (existsSync(credentialsPath)) {
         warnIfWorldReadable(credentialsPath);
@@ -457,18 +558,134 @@ export function resolveApiKey(opts = {}) {
         }
         if (isRecord(creds)) {
             const scoped = opts.server ? creds[opts.server] : undefined;
-            if (isNonEmptyString(scoped))
-                return assertKeyCharset(scoped.trim());
+            if (isNonEmptyString(scoped)) {
+                return {
+                    key: assertKeyCharset(scoped.trim()),
+                    source: 'server-scoped',
+                    scope: opts.server,
+                };
+            }
             const fallback = creds['default'];
             if (isNonEmptyString(fallback)) {
                 if (!opts.server || isTrustedDefaultHost(opts.server)) {
-                    return assertKeyCharset(fallback.trim());
+                    return { key: assertKeyCharset(fallback.trim()), source: 'default', scope: 'default' };
                 }
                 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}`);
             }
         }
     }
-    throw new ApiKeyError('No API key found. Set LIONRAPID_API_KEY or add it to ~/.lionrapid/credentials.');
+    throw new ApiKeyError(noKeyMessage(opts.server, credentialsPath));
+}
+/**
+ * Display form of a key: prefix + last four, never the middle.
+ *
+ * A key shorter than the prefix+last4 window would otherwise be echoed almost
+ * whole, so a short (malformed, truncated) value drops the prefix entirely —
+ * "mask" must not become "print" for the one input where it matters.
+ */
+export function maskKey(key) {
+    return maskKeyImpl(key);
+}
+/**
+ * A key's class, from its prefix.
+ *
+ * The functional line is `targets:write`, NOT the queue scopes. A `pk_` holder
+ * can push sources, pull and read status, but `push --target` dies on a bare
+ * 403 from `targets/batch` — hit for real on 2026-08-07 while trying to
+ * publish a row, and exactly the kind of thing worth saying BEFORE the request
+ * instead of after it.
+ */
+export function keyCapability(key) {
+    if (key.startsWith('pk_')) {
+        return {
+            kind: 'publishable',
+            summary: 'publishable — pushes sources, pulls, reads status. CANNOT write or publish targets.',
+            canWriteTargets: false,
+        };
+    }
+    if (key.startsWith('sk_')) {
+        return {
+            kind: 'master',
+            summary: 'master — everything, including `push --target` and `--publish`.',
+            canWriteTargets: true,
+        };
+    }
+    if (key.startsWith('es_')) {
+        return {
+            kind: 'editor-session',
+            summary: 'editor session — writes and publishes targets, but expires within minutes.',
+            canWriteTargets: true,
+        };
+    }
+    return { kind: 'unknown', summary: 'unrecognized key prefix', canWriteTargets: false };
+}
+function maskKeyImpl(key) {
+    const trimmed = key.trim();
+    const last4 = trimmed.slice(-4);
+    return trimmed.length >= 12 ? `${trimmed.slice(0, 3)}…${last4}` : `…${last4}`;
+}
+/** Every saved credential, as `{ scope, masked }`. Never returns key material. */
+export function listCredentials(credentialsPath = defaultCredentialsPath()) {
+    if (!existsSync(credentialsPath))
+        return [];
+    try {
+        const creds = JSON.parse(readFileSync(credentialsPath, 'utf8'));
+        if (!isRecord(creds))
+            return [];
+        return Object.entries(creds)
+            .filter(([, value]) => isNonEmptyString(value))
+            .map(([scope, value]) => ({ scope, masked: maskKey(value) }));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The one dishonest message in the system, rewritten.
+ *
+ * "No API key found. Set LIONRAPID_API_KEY or add it to ~/.lionrapid/
+ * credentials." was routinely FALSE: keys are stored per server URL, so a key
+ * that is present and correct produces this error the moment `server:` points
+ * somewhere else — which is exactly what a dead default host caused. It named
+ * a missing credential when the real problem was a mismatched server, and cost
+ * an hour of hunting through a credentials file that was fine.
+ *
+ * So: name the server we wanted, list the scopes that DO exist, and give the
+ * command that fixes it. The sibling untrusted-host throw a few lines up
+ * already read like this — same file, same author, opposite outcomes.
+ */
+function noKeyMessage(server, credentialsPath) {
+    const saved = listCredentialServers(credentialsPath);
+    const hasDefault = hasDefaultCredential(credentialsPath);
+    const scopes = [...(hasDefault ? ['default'] : []), ...saved];
+    if (scopes.length === 0) {
+        return (`No API key${server ? ` for ${server}` : ''}, and no keys saved yet.\n` +
+            `  Run: lionrapid login${server ? ` --server ${server}` : ''}\n` +
+            '  (or set LIONRAPID_API_KEY for a one-off / CI run.)');
+    }
+    const list = scopes.map((s) => `  · ${s}`).join('\n');
+    if (!server) {
+        // doctor's case: the config did not parse, so there is no server to match
+        // against. Do not invent one — say which server is in question is unknown.
+        return ('No API key could be resolved, because it is not clear which server to use.\n' +
+            `Keys are saved per server. You have:\n${list}\n` +
+            '  Fix `server:` in lionrapid.yml, or set LIONRAPID_API_KEY.');
+    }
+    return (`No API key for ${server}.\n` +
+        `Keys are saved per server. You have:\n${list}\n` +
+        `  Fix \`server:\` in lionrapid.yml, or: lionrapid login --server ${server}`);
+}
+/** True when the credentials file carries a `default` entry. */
+function hasDefaultCredential(credentialsPath) {
+    if (!existsSync(credentialsPath))
+        return false;
+    try {
+        const creds = JSON.parse(readFileSync(credentialsPath, 'utf8'));
+        return isRecord(creds) && isNonEmptyString(creds['default']);
+    }
+    catch {
+        return false;
+    }
 }
 //# sourceMappingURL=config.js.map

package/dist/history.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `.lionrapid/history/` — a local copy of whatever a `--force` is about to
+ * destroy, in either direction.
+ *
+ * The server versions target rows at STAGE BOUNDARIES, not per edit: an
+ * ordinary edit overwrites `targetrow.target` in place. So until per-edit
+ * history lands server-side, the only thing standing between `--force` and a
+ * lost translation is this directory. Writing it makes `--force` safe TODAY,
+ * symmetrically:
+ *
+ *   pull --force  →  save the LOCAL value, then take the server's
+ *   push --force  →  save the SERVER's value, then overwrite it
+ *
+ * GITIGNORED, unlike the lock. The lock is a team fact and belongs in review;
+ * this is a per-machine safety net that may hold a translator's unfinished
+ * work. The CLI writes `.lionrapid/.gitignore` itself so the distinction
+ * survives a fresh clone without anyone having to know about it.
+ */
+import type { ContentUnit } from '@lionrapid/core';
+/** Where snapshots live, relative to the project root. */
+export declare const HISTORY_DIR: string;
+export interface HistoryEntry {
+    key: string;
+    value: ContentUnit;
+}
+export interface SaveHistoryOptions {
+    /** Which side was about to lose data. */
+    direction: 'push' | 'pull';
+    namespace: string;
+    locale: string;
+    /** Why this snapshot exists, in the words the user will read. */
+    reason: string;
+    entries: HistoryEntry[];
+    /** Timestamp, injectable so tests are deterministic. */
+    at?: string;
+}
+/**
+ * Write a snapshot and return its path, or `undefined` when there was nothing
+ * to save. Filenames carry a counter as well as a timestamp: two forces in the
+ * same second must not have the second one silently replace the first, which
+ * would defeat the point.
+ */
+export declare function saveHistory(cwd: string, opts: SaveHistoryOptions): string | undefined;
+//# sourceMappingURL=history.d.ts.map

package/dist/history.js

@@ -0,0 +1,65 @@
+/**
+ * `.lionrapid/history/` — a local copy of whatever a `--force` is about to
+ * destroy, in either direction.
+ *
+ * The server versions target rows at STAGE BOUNDARIES, not per edit: an
+ * ordinary edit overwrites `targetrow.target` in place. So until per-edit
+ * history lands server-side, the only thing standing between `--force` and a
+ * lost translation is this directory. Writing it makes `--force` safe TODAY,
+ * symmetrically:
+ *
+ *   pull --force  →  save the LOCAL value, then take the server's
+ *   push --force  →  save the SERVER's value, then overwrite it
+ *
+ * GITIGNORED, unlike the lock. The lock is a team fact and belongs in review;
+ * this is a per-machine safety net that may hold a translator's unfinished
+ * work. The CLI writes `.lionrapid/.gitignore` itself so the distinction
+ * survives a fresh clone without anyone having to know about it.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Where snapshots live, relative to the project root. */
+export const HISTORY_DIR = join('.lionrapid', 'history');
+/**
+ * Write a snapshot and return its path, or `undefined` when there was nothing
+ * to save. Filenames carry a counter as well as a timestamp: two forces in the
+ * same second must not have the second one silently replace the first, which
+ * would defeat the point.
+ */
+export function saveHistory(cwd, opts) {
+    if (opts.entries.length === 0)
+        return undefined;
+    const dir = join(cwd, HISTORY_DIR);
+    mkdirSync(dir, { recursive: true });
+    ensureGitignore(cwd);
+    const savedAt = opts.at ?? new Date().toISOString();
+    const stamp = savedAt.replace(/[:.]/g, '-');
+    const base = `${stamp}-${opts.direction}-${opts.namespace}-${opts.locale}`;
+    let path = join(dir, `${base}.json`);
+    for (let n = 2; existsSync(path); n += 1)
+        path = join(dir, `${base}.${n}.json`);
+    const entries = {};
+    for (const entry of opts.entries)
+        entries[entry.key] = entry.value;
+    writeFileSync(path, `${JSON.stringify({
+        savedAt,
+        direction: opts.direction,
+        namespace: opts.namespace,
+        locale: opts.locale,
+        reason: opts.reason,
+        entries,
+    }, null, 2)}\n`);
+    return path;
+}
+/** Keep `history/` out of git while leaving `lock.json` committed. */
+function ensureGitignore(cwd) {
+    const path = join(cwd, '.lionrapid', '.gitignore');
+    const line = 'history/';
+    const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
+    if (existing.split('\n').includes(line))
+        return;
+    writeFileSync(path, existing
+        ? `${existing.replace(/\n?$/, '\n')}${line}\n`
+        : `# Local safety copies written before a --force. Not a team fact.\n${line}\n`);
+}
+//# sourceMappingURL=history.js.map