fix(cli): make run --key match real keys and stop it poisoning i18n.lock - #2197

No actionable comments were generated in the recent review. 🎉

_{Comment @coderabbitai help to get the list of available commands.}

Update after a structured review: five lenses in parallel, then every load-bearing finding handed to a separate agent whose job was to refute it. Two findings that looked like blockers did not survive that; two real ones did and are fixed in f1d53bc3.

Fixed after review

--key was over-selecting. matchesKeyPattern bounds a prefix on ., / and -. For flat keys the latter two are ordinary characters inside a segment, so --key sign-in also selected sign-in-error and overwrote its translation, and --key items also took items-0 and items.title. On origin/main only the exact key matched, so this was a regression introduced by wiring in the shared matcher.

matchesKeyPattern is left alone — locked/ignored/preserved rely on . and - deliberately, and its docstring cites inbox-0. --key now uses a sibling, matchesFlatKeyPattern, where / is the only separator that can bound a prefix. Measured:

'sign-in'      general -> sign-in, sign-in-error         flat -> sign-in
'items'        general -> items, items-0, items.title    flat -> items
'auth/login'   both    -> auth/login/title, auth/login/button
'auth/*'       both    -> auth/login_url
'auth/**'      both    -> all three

Live end-to-end confirmation: with all three source strings edited, run --key sign-in retranslated sign-in and left sign-in-error holding the translation of its old source text, proving it was filtered rather than silently translated.

The help text promised globs that match nothing. minimatch does not cross a /, so --key 'auth/*' reaches one level only — a user following "globs work too" and typing it for a nested key gets 0 processed, the same silent no-match this PR exists to fix. It also picked _ as its non-separator example, which implied - was safe when - was in fact a separator. Rewritten to state the / separator, that a prefix must end at one, and that a glob does not cross one.

The guard returned after the work was already done. createChecksums(sourceData) hashes every source value and runs before persistChecksums, inside the per-pattern file IO lock, so under --key it was computed, discarded, and paid for while the lock was held: 136 ms per task at 30k keys, roughly 2.7 s of hashing and 2.7 s of held lock across 20 locales. The flag check is now a named narrowsRun predicate consulted before the hashing at both call sites.

Comment and test cleanup. The guard comment stated the --key rationale above a condition that also covers --target-locale, whose reason is different; narrowsRun's docblock now names both. The two added tests that passed against origin/main are folded into an it.each with the case that actually pins the fix, the computeProcessableData fixtures are now /-joined like real keys instead of a second describe explaining that the first one's were not, the encoded alias is gone, and the touched files are prettier-clean.

packages/cli: 955 passed, 60 files. Typecheck clean.

Refuted, and worth recording

A --frozen regression. Real behaviour change, not a defect. --target-locale already fails --frozen on origin/main in the identical scenario, shipped deliberately in #992 for issue #991, so this extends established semantics to a third narrowing flag. More to the point, main's "pass" is a false green: with two keys edited and the run narrowed to one, origin/main returns exit 0 from a CI gate on a provably stale target file, while this branch fails. --frozen is documented to fail when the lockfile is out of sync, and it is. The claim that the error's lingo.dev lockfile advice re-poisons the lock is also wrong — that command skips when the section is already populated and stamps nothing.

Untranslated source text leaking into target files under --key. The mechanism is real: execute.ts merges sourceData under the target data, so unselected keys with no translation land as raw source. But the line is byte-identical to origin/main and equally reachable there via --key pricing/title and --key pricing/**, and main is worse — it stamps the lockfile in the same run rather than the next. It is also not permanent: --force or any source-value edit repairs it. Pre-existing, medium, and it wants its own ticket rather than this PR.

Known gaps, deliberately not in this PR

• frozen.ts bootstraps a full lockfile for a project that has none, and that path does not route through persistChecksums, so a --key run on a fresh project still stamps every key.
• Right after a --key run, a key written without a checksum cannot trigger delta.updated, so editing its source does not retranslate it until the next full run. Transient, low.
• purge.ts:128 still hand-rolls minimatch(safeDecode(k), safeDecode(pattern)), so --key semantics now differ between run and purge.
• _utils.ts compares decoded keys against decoded patterns while the four loader consumers of the shared matcher compare encoded against encoded via encodeKeys(); the pattern-side encode-then-decode is a no-op round trip worth collapsing.
• Pre-existing performance, both in the touched function and dwarfing everything above: delta.added.includes(key) is a linear scan, measured 2982 ms versus 2.19 ms with Sets at 30k keys, and !!force is evaluated last so --force does not short-circuit it. minimatch's functional form compiles the pattern on every call — 148 ms versus 8 ms with the compile hoisted.
• i18n.ts:479, in the deprecated i18n command, carries the same guard defect this PR fixes in run.

Not verified: anything at the scale of the reported case. The end-to-end runs used small fixtures, so the mechanism is confirmed and the volume is not.