champollion 0.3.4 → 0.5.0

package/lib/methods/request-capture.js

@@ -0,0 +1,104 @@
+/**
+ * Request capture — see the exact request a method would send, without
+ * sending it (`champollion sync --dry --show-prompt [key]`).
+ *
+ * WHY: nothing showed whether a gettext `msgctxt`, a `#.` comment or any
+ * other per-key instruction actually reaches the model (Round 5, Django
+ * persona). Rebuilding "what the prompt probably looks like" beside the real
+ * code would be a second prompt builder that drifts; instead the methods'
+ * own transports hand their finished request here, at the point where they
+ * would call fetch(), and return as if the call failed — no retry, nothing
+ * sent, nothing billed.
+ *
+ * Scoped with AsyncLocalStorage: only code running inside captureRequests()
+ * is captured, so a capture never swallows an unrelated call. Inside a
+ * capture, fetch() itself is refused (defence in depth: a path that is not
+ * hooked fails closed instead of reaching the network).
+ *
+ * Secrets are redacted before anything is recorded: authorization-type
+ * headers and key-bearing URL parameters print as <redacted>.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+const store = new AsyncLocalStorage();
+
+/** The key a preview passes when none is configured (it never leaves the process). */
+export const PREVIEW_KEY = 'preview-no-key';
+
+const SECRET_HEADERS = new Set([
+  'authorization', 'x-api-key', 'api-key', 'x-goog-api-key', 'ocp-apim-subscription-key',
+  'x-champollion-key', 'proxy-authorization', 'cookie',
+]);
+const SECRET_PARAMS = new Set(['key', 'api_key', 'apikey', 'token', 'access_token', 'auth_key']);
+
+function redactHeaders(headers) {
+  const out = {};
+  for (const [k, v] of Object.entries(headers || {})) {
+    out[k] = SECRET_HEADERS.has(k.toLowerCase()) ? '<redacted>' : v;
+  }
+  return out;
+}
+
+function redactUrl(url) {
+  try {
+    const u = new URL(String(url));
+    for (const name of [...u.searchParams.keys()]) {
+      if (SECRET_PARAMS.has(name.toLowerCase())) u.searchParams.set(name, '<redacted>');
+    }
+    return u.toString().replace(/%3Credacted%3E/g, '<redacted>');
+  } catch {
+    return String(url);
+  }
+}
+
+/** True inside captureRequests(): the caller must record, not send. */
+export function isCapturing() {
+  return store.getStore() !== undefined;
+}
+
+/**
+ * Record the request a transport is about to send. Returns true when it was
+ * captured (the transport must then return without calling fetch), false
+ * when no capture is active (send as normal).
+ *
+ * @param {{ url: string, method?: string, headers?: object, body?: unknown }} request
+ * @returns {boolean}
+ */
+export function captureRequest({ url, method = 'POST', headers = {}, body }) {
+  const sink = store.getStore();
+  if (!sink) return false;
+  let parsed = body;
+  if (typeof body === 'string') {
+    try { parsed = JSON.parse(body); } catch { parsed = body; }
+  }
+  sink.push({ url: redactUrl(url), method, headers: redactHeaders(headers), body: parsed });
+  return true;
+}
+
+let fetchGuarded = false;
+/** Inside a capture fetch() is refused; outside, it is the real fetch. Installed once. */
+function guardFetch() {
+  if (fetchGuarded || typeof globalThis.fetch !== 'function') return;
+  const realFetch = globalThis.fetch;
+  globalThis.fetch = function guardedFetch(...args) {
+    if (store.getStore()) {
+      return Promise.reject(new Error('request preview: nothing is sent while showing a request'));
+    }
+    return realFetch.apply(this, args);
+  };
+  fetchGuarded = true;
+}
+
+/**
+ * Run fn with capture on; return the requests its transports would have sent.
+ *
+ * @param {() => Promise<unknown>} fn
+ * @returns {Promise<Array<{ url: string, method: string, headers: object, body: unknown }>>}
+ */
+export async function captureRequests(fn) {
+  guardFetch();
+  const sink = [];
+  await store.run(sink, fn);
+  return sink;
+}

package/lib/methods/tilde.js

@@ -27,11 +27,11 @@ const TILDE_MAX_BATCH = 25;
 class TildeMethod extends TranslationMethod {
   constructor(options = {}) {
     super('tilde', options);
+    this.translatesRawText = true; // see base.js
   }
 
   _resolveApiKey(options = {}) {
     return options.tildeApiKey
-      || getEnvOrFileVar('TILDE_API_KEY')
       || getEnvOrFileVar('TILDE_API_KEY', options.cwd);
   }
 

package/lib/methods/translated.js

@@ -28,6 +28,7 @@ const TRANSLATED_MAX_BATCH = 50;
 class TranslatedMethod extends TranslationMethod {
   constructor(options = {}) {
     super('translated', options);
+    this.translatesRawText = true; // see base.js
     this._client = options.laraClient || null; // injectable for tests
   }
 
@@ -40,10 +41,8 @@ class TranslatedMethod extends TranslationMethod {
    */
   _resolveCredentials(options = {}) {
     const id = options.laraAccessKeyId
-      || getEnvOrFileVar('LARA_ACCESS_KEY_ID')
       || getEnvOrFileVar('LARA_ACCESS_KEY_ID', options.cwd);
     const secret = options.laraAccessKeySecret
-      || getEnvOrFileVar('LARA_ACCESS_KEY_SECRET')
       || getEnvOrFileVar('LARA_ACCESS_KEY_SECRET', options.cwd);
     return id && secret ? { id, secret } : null;
   }

package/lib/missing-key.js

@@ -0,0 +1,93 @@
+/**
+ * What to tell someone whose method cannot run for want of a key — ONE helper
+ * for every place that says it (the sync preflight, real and dry; a method
+ * that returned nothing; the content and Docusaurus lanes; `models`).
+ *
+ * On a CI runner the fix is a repository secret passed to the step, not
+ * `export …` or `.env.local`: the Round 8 fix reached one of these places and
+ * a real CI run still printed the laptop advice from the others (Round 9,
+ * i18next persona). Off CI, the method's own setup help stands as before.
+ */
+
+/**
+ * Is this a CI runner? `CI` or `GITHUB_ACTIONS` set to anything but an empty
+ * string, "false" or "0" (a developer's shell may export CI=false).
+ *
+ * @param {object} [env]
+ * @returns {boolean}
+ */
+export function onCIRunner(env = process.env) {
+  const on = (v) => typeof v === 'string' && v.trim() !== '' && !/^(false|0)$/i.test(v.trim());
+  return on(env.CI) || on(env.GITHUB_ACTIONS);
+}
+
+/**
+ * The secret names a readiness reason names, in its first parenthesis:
+ *   "No OpenRouter API key (OPENROUTER_API_KEY)."                → OPENROUTER_API_KEY
+ *   "No Google Translate API key (GOOGLE_TRANSLATE_API_KEY (or GOOGLE_API_KEY))." → the first (canonical) one
+ *   "No Lara credentials (LARA_ACCESS_KEY_ID + LARA_ACCESS_KEY_SECRET)."            → both (a key pair)
+ *
+ * @param {Iterable<string>} reasons
+ * @returns {string[]} distinct names, in order
+ */
+export function secretNamesIn(reasons) {
+  const names = [];
+  for (const reason of reasons || []) {
+    const m = /\(([A-Z][A-Z0-9]*_[A-Z0-9_]+(?:\s*\+\s*[A-Z][A-Z0-9]*_[A-Z0-9_]+)*)/.exec(String(reason));
+    if (!m) continue;
+    for (const n of m[1].split('+').map(x => x.trim())) if (!names.includes(n)) names.push(n);
+  }
+  return names;
+}
+
+/**
+ * "In CI: add a repository secret named X and pass it to the sync step (env: X: ${{ secrets.X }})."
+ *
+ * @param {string[]} names
+ * @param {string} [step] - what the secret is passed to
+ * @returns {string|null} null when no name is known
+ */
+export function ciSecretLine(names, step = 'the sync step') {
+  if (!names || names.length === 0) return null;
+  const plural = names.length > 1;
+  return `In CI: add ${plural ? 'repository secrets' : 'a repository secret'} named ${names.join(' and ')} and pass `
+    + `${plural ? 'them' : 'it'} to ${step} (env: ${names.map(n => `${n}: \${{ secrets.${n} }}`).join(', ')}).`;
+}
+
+/**
+ * The advice lines for a missing key: on a CI runner, the repository-secret
+ * line INSTEAD of the shell advice; elsewhere, the method's own setup help
+ * (export …, .env.local). A reason that names no secret (a model server that
+ * does not answer) keeps the setup help everywhere — its reason already says
+ * what to do on a runner (lib/methods/local.js).
+ *
+ * @param {object} p
+ * @param {Iterable<string>} p.reasons - readiness reasons
+ * @param {string[]} [p.setupHelp] - the method's getSetupHelp() lines
+ * @param {string} [p.indent]
+ * @param {object} [p.env]
+ * @param {string} [p.step] - what the secret is passed to (default: the sync step)
+ * @returns {string[]}
+ */
+export function missingKeyAdvice({ reasons, setupHelp = [], indent = '  ', env = process.env, step = 'the sync step' }) {
+  const line = ciSecretLine(secretNamesIn(reasons), step);
+  if (onCIRunner(env) && line) return [`${indent}${line}`];
+  return [...setupHelp];
+}
+
+/**
+ * The setup help for a method that returned nothing: when its key is missing
+ * (its readiness check says so), the missing-key advice above; when the key
+ * is there, the method's own HTTP-failure help.
+ *
+ * @param {object} method - a method instance (lib/methods/base.js)
+ * @param {{ apiKey?: string|null, cwd?: string }} [context]
+ * @returns {Promise<string[]>}
+ */
+export async function methodSetupAdvice(method, context = {}) {
+  const help = method.getSetupHelp();
+  let readiness = { ready: true };
+  try { readiness = await method.checkReadiness({ apiKey: context.apiKey ?? null, cwd: context.cwd }); } catch { /* the help stands */ }
+  if (readiness && readiness.ready === false) return missingKeyAdvice({ reasons: [readiness.reason], setupHelp: help });
+  return help;
+}

package/lib/models.js

@@ -24,77 +24,109 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getEnvOrFileVar } from './api-key.js';
+// A cycle (config.js imports this module) that is safe: the default is read
+// only inside requireExactModelId, at call time, never while modules load.
+import { DEFAULT_OPENROUTER_MODEL } from './config.js';
 
 // Per-process cache: provider name → model ID array (or null if fetch failed)
 const _modelCache = new Map();
 
-// Lazy-loaded alias map (loaded once from shared/model-aliases.json)
-let _aliasCache = null;
+// Lazy-loaded retired-name table (loaded once from shared/retired-model-aliases.json)
+let _retiredCache = null;
 
 /**
- * Load the model alias map from shared/model-aliases.json.
+ * Where to look up the models a name could mean — said in every refusal.
+ * `champollion models` lists a direct provider's own names; OpenRouter's
+ * catalogue is its public model list.
+ */
+const MODEL_LIST_HINT = 'List models: https://openrouter.ai/models (OpenRouter slugs), '
+  + 'or champollion models --method <gemini|openai|anthropic> (a direct provider\'s own names).';
+
+/**
+ * Load the RETIRED short model names from shared/retired-model-aliases.json.
  *
- * Resolves the path relative to the monorepo root (two levels up from cli/lib/).
- * Returns an empty object if the file doesn't exist or fails to parse,
- * so callers can always safely check `aliases[name]`.
+ * Founder ruling 2026-10-05: "slugs should be specific, NOT ALIASES — for all
+ * models, all slugs, no aliasing." These names no longer resolve to anything.
+ * The table exists only so a refusal can say which exact slug the old name
+ * used to stand for — it is never used to map a name to a model.
  *
- * @returns {Object<string, string>} Short name → full OpenRouter slug
+ * Prefers the package-bundled copy (cli/shared/, shipped via sync:shared),
+ * then the monorepo-root SSOT for in-repo dev. A missing or unreadable table
+ * leaves the refusal of floating ids intact and only loses the "used to stand
+ * for" hint for a retired name — which then fails as an unknown model at the
+ * provider, still never resolved.
+ *
+ * @returns {Object<string, string>} Retired short name → the slug it stood for
  */
-function _loadAliases() {
-  if (_aliasCache) return _aliasCache;
-
-  try {
-    const __dirname = path.dirname(fileURLToPath(import.meta.url));
-    // Prefer the package-bundled copy (cli/shared/, shipped via the prepack
-    // build-cards-fallback.mjs), then fall back to the monorepo-root SSOT for
-    // in-repo dev. Without the package copy, an installed CLI found no alias map
-    // and `--model <alias>` silently failed to resolve.
-    const aliasPaths = [
-      path.resolve(__dirname, '..', 'shared', 'model-aliases.json'),
-      path.resolve(__dirname, '..', '..', 'shared', 'model-aliases.json'),
-    ];
-    let raw = null;
-    for (const p of aliasPaths) {
-      try { raw = fs.readFileSync(p, 'utf-8'); break; } catch { /* try next */ }
+function _loadRetiredAliases() {
+  if (_retiredCache) return _retiredCache;
+  _retiredCache = Object.create(null);
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    path.resolve(__dirname, '..', 'shared', 'retired-model-aliases.json'),
+    path.resolve(__dirname, '..', '..', 'shared', 'retired-model-aliases.json'),
+  ];
+  for (const p of candidates) {
+    let raw;
+    try { raw = fs.readFileSync(p, 'utf-8'); } catch { continue; }
+    const retired = JSON.parse(raw).retired || {};
+    for (const [key, value] of Object.entries(retired)) {
+      if (typeof value === 'string') _retiredCache[key] = value;
     }
-    const parsed = raw ? JSON.parse(raw) : {};
-    // Strip metadata keys (e.g., _comment) — only keep actual aliases
-    _aliasCache = {};
-    for (const [key, value] of Object.entries(parsed)) {
-      if (!key.startsWith('_') && typeof value === 'string') {
-        _aliasCache[key] = value;
-      }
-    }
-  } catch {
-    _aliasCache = {};
+    break;
   }
+  return _retiredCache;
+}
 
-  return _aliasCache;
+/**
+ * True for a floating id — one that names whatever model a provider points it
+ * at today, so a run could not say which model translated: OpenRouter's
+ * "~vendor/…" router ids and any "…-latest" / "…:latest" name.
+ *
+ * @param {string} id
+ * @returns {boolean}
+ */
+function isFloatingModelId(id) {
+  return typeof id === 'string' && (id.trim().startsWith('~') || /[-:]latest$/i.test(id.trim()));
 }
 
 /**
- * Resolve a model name or alias to a full OpenRouter slug.
+ * Check that a configured model is an EXACT model slug, and return it unchanged.
  *
- * Resolution order:
- *   1. If contains '/' → already a full slug, pass through
- *   2. Check shared/model-aliases.json for a matching alias
- *   3. Pass through as-is (user may know what they're doing)
+ * Founder ruling 2026-10-05: every model is named by its exact provider slug
+ * ("google/gemini-3.5-flash", "anthropic/claude-sonnet-4.6", or a direct
+ * provider's own exact name, "gpt-5.5"). Nothing resolves a short name:
+ *   - a retired alias ("gemini-flash", "gpt", …) is REFUSED, naming the exact
+ *     slug it used to stand for;
+ *   - a floating id ("~google/gemini-flash-latest", "…-latest") is REFUSED.
+ * Anything else passes through as written — the provider judges whether the
+ * model exists (direct providers also check it against their model list).
  *
- * @param {string} nameOrSlug - User-provided model identifier
- * @returns {string} Full OpenRouter model slug
+ * @param {string|null|undefined} id - The model as written
+ * @param {{ from?: string|null }} [where] - Where it was set ("from --model")
+ * @returns {string|null|undefined} The same id
+ * @throws {Error} code CHAMPOLLION_MODEL_ID
  */
-function resolveModel(nameOrSlug) {
-  if (!nameOrSlug || typeof nameOrSlug !== 'string') return nameOrSlug;
-
-  // Already a full slug (contains provider prefix)
-  if (nameOrSlug.includes('/')) return nameOrSlug;
-
-  // Check aliases
-  const aliases = _loadAliases();
-  if (aliases[nameOrSlug]) return aliases[nameOrSlug];
-
-  // Pass through — could be a provider-specific model name (e.g., gemini-2.0-flash)
-  return nameOrSlug;
+function requireExactModelId(id, { from = null } = {}) {
+  if (!id || typeof id !== 'string') return id;
+  const at = from ? ` (${from})` : '';
+  const retired = _loadRetiredAliases();
+  if (Object.prototype.hasOwnProperty.call(retired, id)) {
+    const err = new Error(
+      `"${id}"${at} is not a model id — Champollion takes exact model slugs only, no aliases. `
+      + `Did you mean ${retired[id]} (what "${id}" used to stand for)? ${MODEL_LIST_HINT}`);
+    err.code = 'CHAMPOLLION_MODEL_ID';
+    throw err;
+  }
+  if (isFloatingModelId(id)) {
+    const err = new Error(
+      `"${id}"${at} is a floating model id — it names whatever model the provider points it at today, `
+      + 'so a run could not say which model translated. Champollion takes exact model slugs only: '
+      + `name the model itself (e.g. "${DEFAULT_OPENROUTER_MODEL}", the CLI default). ${MODEL_LIST_HINT}`);
+    err.code = 'CHAMPOLLION_MODEL_ID';
+    throw err;
+  }
+  return id;
 }
 
 /**
@@ -183,7 +215,10 @@ async function fetchAvailableModels(provider, apiKey) {
   if (cached !== undefined) return cached;
 
   try {
-    const models = await config.fetch(apiKey);
+    // Floating ids ("gemini-flash-latest", "chatgpt-4o-latest") are listed by
+    // the providers but refused everywhere (requireExactModelId) — never offer
+    // one, so neither `champollion models` nor init's picker suggests it.
+    const models = (await config.fetch(apiKey))?.filter(id => !isFloatingModelId(id)) ?? null;
     if (models && models.length > 0) {
       _modelCache.set(provider, models);
       return models;
@@ -219,6 +254,16 @@ function getProviderLabel(provider) {
   return PROVIDERS[provider]?.label || provider;
 }
 
+/**
+ * The environment variable a provider's key is read from (null: unknown).
+ *
+ * @param {string} provider - Provider name
+ * @returns {string|null}
+ */
+function getProviderEnvVar(provider) {
+  return PROVIDERS[provider]?.envVar || null;
+}
+
 /**
  * Check if a provider has model listing support.
  *
@@ -248,9 +293,11 @@ function clearModelCache() {
 
 export {
   fetchAvailableModels,
-  resolveModel,
+  requireExactModelId,
+  isFloatingModelId,
   resolveProviderApiKey,
   getProviderLabel,
+  getProviderEnvVar,
   isListableProvider,
   getListableProviders,
   clearModelCache,

package/lib/name-rules.js

@@ -0,0 +1,32 @@
+/**
+ * name-rules.js — the ONE wording every translation prompt uses for names.
+ *
+ * The old rule ("proper nouns, product names, and technical terms … role
+ * descriptions … should stay in English") let models keep short descriptive
+ * labels in English: on the 2026-08-28 dogfood run "Translation CLI" and
+ * "Evaluation harness" came back verbatim in Arabic and Thai and failed
+ * verification. Names stay; descriptions get translated; a project can
+ * declare its real names (config.protectedTerms) so the model never has to
+ * guess.
+ */
+
+/**
+ * Prompt rule lines about names, each starting with "- ".
+ *
+ * @param {string[]} [protectedTerms] - config.protectedTerms
+ * @returns {string} Newline-joined rule lines (no trailing newline)
+ */
+export function nameRules(protectedTerms = []) {
+  const terms = (protectedTerms || []).filter(t => typeof t === 'string' && t.trim());
+  const lines = [
+    '- Proper names (people, companies, products, places) stay exactly as written.',
+  ];
+  if (terms.length > 0) {
+    lines.push(`- Keep these exactly as written wherever they appear: ${terms.map(t => JSON.stringify(t)).join(', ')}.`);
+  }
+  lines.push(
+    '- Descriptive labels and phrases are NOT names, even when short or capitalized (e.g. "Translation CLI", "Evaluation harness", "Getting Started") — translate them.',
+    '- Widely used technical acronyms (API, URL, JSON, CLI) may stay as written inside a translated phrase.',
+  );
+  return lines.join('\n');
+}

package/lib/named-keys.js

@@ -0,0 +1,172 @@
+/**
+ * named-keys.js — keys named for a redo (`--redo keys:` / `--force-keys`)
+ * must exist. ONE rule for every sync path (key-value files, Docusaurus UI
+ * strings), so the two cannot drift apart.
+ *
+ * A name that matched nothing used to do nothing in silence ("fully synced
+ * … 0 keys", exit 0 — in CI exactly a success), so a typo or a gettext msgid
+ * that only exists WITH a context looked like a finished repair (Round 7,
+ * Django persona). Now:
+ *   - no name matches: the run stops before anything is translated or sent
+ *     (exit 1), naming the closest keys that exist;
+ *   - some names match: those are redone, then the run fails (exit 1)
+ *     naming the rest — said again at the very end, where CI looks.
+ *
+ * Each lane says what its key space is (`known`) — the key-value lane adds
+ * the plural forms a target gets and the namespace prefix; the Docusaurus
+ * lane collects every source JSON file's message ids.
+ */
+
+import { fromTypedContext } from './locale-layout.js';
+import { splitKeyList } from './redo.js';
+import { output } from './output.js';
+import { estimateCost } from './pairs.js';
+import { costLabel } from './cost-label.js';
+import { editDistance } from './edit-distance.js';
+
+/** A key as a person reads and types it: the gettext context separator as ␄. */
+export const shownKey = (k) => String(k).replace(/\u0004/g, '\u2404');
+
+/** "`button␄Cancel` (or type button\x04Cancel)" — both spellings, for a key with a context. */
+function bothSpellings(k) {
+  const shown = shownKey(k);
+  return /\u0004/.test(k) ? `\`${shown}\` (or type \`${String(k).replace(/\u0004/g, '\\x04')}\`)` : `\`${shown}\``;
+}
+
+/**
+ * Which of the names match a key in `known`, and — for each that does not —
+ * the closest keys that do: every context variant of a gettext msgid
+ * (`button␄Cancel`, `status␄Cancel` for "Cancel"), the same key in another
+ * case, near spellings.
+ *
+ * @param {string[]} names - As typed (␄ or \x04 for a gettext context)
+ * @param {Set<string>} known - Every key a name may match, in the lane's key space
+ * @param {object} [opts]
+ * @param {(k: string) => string} [opts.bare] - A key without its namespace
+ *   prefix (key-value layouts with several files); identity otherwise
+ * @param {boolean} [opts.bareMatches] - A name with no namespace names that
+ *   key in every file that has it
+ * @returns {{ matched: string[], missed: Array<{ name: string, closest: string[] }> }}
+ */
+export function checkNamedKeys(names, known, { bare = (k) => k, bareMatches = false } = {}) {
+  // A name with no namespace of its own (bare(name) === name) names that key
+  // in every file that has it.
+  const matches = (name) => known.has(name)
+    || (bareMatches && bare(name) === name && [...known].some(k => bare(k) === name));
+  const matched = [];
+  const missed = [];
+  for (const raw of names) {
+    const name = fromTypedContext(raw);
+    if (matches(name)) { matched.push(raw); continue; }
+    const want = bare(name);
+    const msgid = want.includes('\u0004') ? want.slice(want.indexOf('\u0004') + 1) : want;
+    const lower = want.toLowerCase();
+    const max = Math.max(2, Math.floor(want.length / 5));
+    const scored = [];
+    for (const k of known) {
+      const kb = bare(k);
+      const kMsgid = kb.includes('\u0004') ? kb.slice(kb.indexOf('\u0004') + 1) : kb;
+      let score = null;
+      if (kMsgid === msgid) score = 0; // the same msgid, with (another) context
+      else if (kb.toLowerCase() === lower || kMsgid.toLowerCase() === msgid.toLowerCase()) score = 1;
+      else {
+        const d = editDistance(kb.toLowerCase(), lower, max);
+        if (d <= max) score = 1 + d;
+      }
+      if (score !== null) scored.push([score, k]);
+    }
+    scored.sort((a, b) => a[0] - b[0] || a[1].localeCompare(b[1]));
+    missed.push({ name: raw, closest: scored.slice(0, 8).map(([, k]) => k) });
+  }
+  return { matched, missed };
+}
+
+/** The error lines for named keys that matched nothing. */
+export function describeUnmatchedKeys(missed, { flag }) {
+  const lines = missed.map(({ name, closest }) => `${flag} names "${shownKey(fromTypedContext(name))}", which matches no key in the source files`
+    + (closest.length > 0 ? ` — closest: ${closest.map(bothSpellings).join(', ')}` : ' (and nothing close to it)') + '.');
+  if (missed.some(m => m.closest.some(k => k.includes('\u0004')))) {
+    lines.push('A gettext entry with a context is named msgctxt␄msgid; type the ␄ as \\x04 if you cannot (both spellings work).');
+  }
+  return lines;
+}
+
+/** How the run's named keys were given, for its messages. */
+export function namedKeyFlag(cliArgs) {
+  return cliArgs.redo !== undefined ? '--redo keys:' : '--force-keys';
+}
+
+/**
+ * The rule, applied before any work. With no name matching it throws (the
+ * run exits 1, nothing translated or sent). With some matching, it prints
+ * the misses, narrows `cliArgs['force-keys']` and `config.forceKeys` to the
+ * names that exist, and returns the misses — the caller reports them again
+ * at the end (reportUnmatchedKeys) and the run exits 1.
+ *
+ * @param {object} p
+ * @param {object} p.cliArgs - Parsed CLI args (mutated: force-keys narrowed)
+ * @param {object} p.config - Resolved config (mutated: forceKeys narrowed)
+ * @param {Set<string>|(() => Set<string>)} p.known - The lane's key space (lazy: built only when keys are named)
+ * @param {(k: string) => string} [p.bare]
+ * @param {boolean} [p.bareMatches]
+ * @returns {Array<{ name: string, closest: string[] }>} The names that matched nothing
+ */
+export function applyNamedKeyRule({ cliArgs, config, known, bare, bareMatches = false }) {
+  const named = splitKeyList(cliArgs['force-keys'] || '');
+  if (named.length === 0) return [];
+  const keys = typeof known === 'function' ? known() : known;
+  const { matched, missed } = checkNamedKeys(named, keys, { bare, bareMatches });
+  if (missed.length === 0) return [];
+  const lines = describeUnmatchedKeys(missed, { flag: namedKeyFlag(cliArgs) });
+  if (matched.length === 0) {
+    throw new Error(`${lines.join('\n')}\nNothing was translated or sent.`);
+  }
+  for (const l of lines) output.error(l);
+  output.error(`Redoing the ${matched.length} named key(s) that exist; the run then fails (exit 1) for the ${missed.length} that do not.`);
+  cliArgs['force-keys'] = matched.map(k => k.replace(/,/g, '\\,')).join(',');
+  // --redo all / --force re-queues every key anyway; the narrowed names only
+  // decide what a named redo replaces.
+  config.forceKeys = cliArgs.force ? config.forceKeys : splitKeyList(cliArgs['force-keys']);
+  return missed;
+}
+
+/** Said again at the end of the run, where a reader (or CI) looks for the verdict. */
+export function reportUnmatchedKeys(missed, cliArgs) {
+  if (!missed || missed.length === 0) return;
+  for (const l of describeUnmatchedKeys(missed, { flag: namedKeyFlag(cliArgs) })) output.error(l);
+}
+
+/** The --json summary's `unmatchedKeys`: each name with the closest keys that exist. */
+export function unmatchedKeysSummary(missed) {
+  return (missed || []).map(m => ({ name: m.name, closest: m.closest.map(shownKey) }));
+}
+
+/**
+ * Keys NAMED for a redo that the cache answered: the model was not asked, and
+ * a redo without --fresh said nothing about it — the persona's `--redo
+ * keys:<k>` wrote back the text it already had (Round 7, Django). Said, with
+ * the --fresh command and what it costs — by every key lane (key-value files,
+ * Docusaurus UI strings), in the same words.
+ *
+ * @param {object} p
+ * @param {string} p.filename - The file as the run names it
+ * @param {string[]} p.keys - The named keys the cache served
+ * @param {string[]} [p.shown] - The same keys as a person names them (default: keys)
+ * @param {object} [p.served] - key → the text the cache served
+ * @param {object} [p.onDisk] - key → the text the file held before the run
+ * @param {object} p.pairConfig
+ * @param {string|null} [p.cwd]
+ * @param {boolean} [p.dryRun]
+ * @param {string} p.command - The `--redo keys: … --fresh` command that asks the model again
+ */
+export async function reportNamedFromCache({ filename, keys, shown = keys, served = {}, onDisk = {}, pairConfig, cwd = null, dryRun = false, command }) {
+  if (keys.length === 0) return;
+  const same = keys.filter(k => typeof served[k] === 'string' && served[k] === onDisk[k]);
+  let price = 'cost unknown';
+  try { price = costLabel(await estimateCost(keys.length, pairConfig, { cwd })); } catch { /* unknown */ }
+  const sample = `${shown.slice(0, 3).join(', ')}${shown.length > 3 ? `, +${shown.length - 3} more` : ''}`;
+  output.info(`${filename} — ${keys.length} key(s) named for a redo ${dryRun ? 'would be' : 'were'} served from the cache, `
+    + `not asked again (${sample})${same.length === keys.length ? ' — the file already holds that text' : ''}: `
+    + 'a redo re-checks and re-writes what the cache holds, at no cost. To ask the model again: '
+    + `\`${command}\` (sends ${keys.length} key(s) — ${price}).`);
+}

package/lib/no-translate.js

@@ -73,10 +73,11 @@ function isBareUrl(value) {
  *   - a pattern with no wildcard is an exact dot-path
  *
  * @param {string} pattern - e.g. '**.url', 'pages.software.*.repo'
+ * @param {string} [sep='.'] - Segment separator ('/' for file paths — see file-scope.js)
  * @returns {(keySegments: string[]) => boolean} Segment-array matcher
  */
-function compilePattern(pattern) {
-  const patternSegments = pattern.split('.');
+function compilePattern(pattern, sep = '.') {
+  const patternSegments = pattern.split(sep);
 
   // Per-segment regexes, built once. `**` is handled structurally below and
   // never reaches this map.
@@ -88,7 +89,7 @@ function compilePattern(pattern) {
     const source = '^' + seg
       .split('*')
       .map(part => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
-      .join('[^.]*') + '$';
+      .join(`[^${sep.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}]*`) + '$';
     const re = new RegExp(source);
     return (s) => re.test(s);
   });