@lionrapid/cli 0.3.0 → 0.5.0

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

package/dist/job-history.d.ts

@@ -27,8 +27,17 @@ export interface JobHistoryEntry {
     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;
+    /**
+     * The project uuid this push resolved to, when one is known.
+     *
+     * Replaces the old free-text `project` label copied from lionrapid.yml —
+     * the field that stamped `tm-frontpage` onto 30 jobs that went elsewhere.
+     * Optional both because older entries carry the label instead and because
+     * the server's project id is itself optional.
+     */
+    projectId?: string;
+    /** Legacy: the free-text label, on entries written before the id existed. */
+    project?: string;
     namespace: string;
     /** Source locale of the batch. */
     locale: string;

package/dist/job-history.js

@@ -18,8 +18,8 @@
  * 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';
+import { homeDir } from './config.js';
 /**
  * Pruning. Both bounds apply on every write, so the file cannot grow forever:
  *
@@ -44,18 +44,6 @@ const TERMINAL_STATUSES = new Set(['completed', 'failed', 'gone']);
 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');

package/dist/lockfile.d.ts

@@ -0,0 +1,90 @@
+/**
+ * `.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 { type ContentUnit } from '@lionrapid/core';
+/** Where the lock lives, relative to the project root. */
+export declare const LOCKFILE_PATH: string;
+/** The only shape this CLI writes. A higher number is a newer CLI's file. */
+export declare const LOCK_VERSION = 1;
+export interface LockTarget {
+    /** Hash of the target value as the server last gave it to us. */
+    hash: string;
+    /** When the server last reported this row. Written by `pull`, never by `push`. */
+    serverUpdatedAt?: string;
+}
+export interface LockEntry {
+    /** Hash of the source text this key was last known to carry. */
+    sourceHash: string;
+    /** When the server last reported the source row (pull-only). */
+    serverUpdatedAt?: string;
+    /** Per-target-locale state, keyed by locale. */
+    targets?: Record<string, LockTarget>;
+}
+export interface Lock {
+    version: number;
+    /**
+     * The project this lock was written against. A lock from another project
+     * computes a nonsense diff, so a mismatch stops the run.
+     *
+     * OPTIONAL because nothing serves a project id yet — it arrives with the
+     * server's `projectId` on project-config (spec C4/S2). Until then locks
+     * carry none and the check simply has nothing to compare.
+     */
+    projectId?: string;
+    /** `namespace:key` → what we last knew. */
+    entries: Record<string, LockEntry>;
+}
+export interface ReadLockOptions {
+    /** The config's project id, when one is known, for the mismatch guard. */
+    projectId?: string;
+}
+/** A lock that knows nothing. Distinct from "everything changed" — see `readLock`. */
+export declare function emptyLock(): Lock;
+/**
+ * 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 declare function hashSource(value: ContentUnit): string;
+/** The lock's key for a row: the coordinates a push actually addresses. */
+export declare function lockKey(namespace: string, key: string): string;
+/**
+ * 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 declare function readLock(cwd: string, opts?: ReadLockOptions): Lock;
+/**
+ * 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 declare function writeLock(cwd: string, lock: Lock): void;
+//# sourceMappingURL=lockfile.d.ts.map