champollion 0.3.3 → 0.4.0

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

@@ -219,6 +219,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.
  *
@@ -251,6 +261,7 @@ export {
   resolveModel,
   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);
   });

package/lib/output.js

@@ -31,6 +31,44 @@
  */
 let mode = 'default';
 
+/**
+ * Keys as people can copy them. A gettext key with a context is
+ * `msgctxt + U+0004 + msgid` — gettext's own encoding — and U+0004 is an
+ * invisible control character on a terminal: a key copied from a report
+ * could not be pasted back into `--redo keys:`. Every message printed here
+ * shows it as "␄" (U+2404), which `--redo keys:` / `--force-keys` accept
+ * back (lib/locale-layout.js keysForNamespace). Structured `data` fields in
+ * --json keep the exact key.
+ *
+ * @param {*} msg
+ * @returns {*} msg with U+0004 shown as ␄ (non-strings unchanged)
+ */
+function showKey(msg) {
+  return typeof msg === 'string' ? msg.replace(/\u0004/g, '\u2404') : msg;
+}
+
+/**
+ * LINE-ATOMIC OUTPUT. Locales are translated in parallel, and a progress
+ * bar used to be a partial line (`\r…` with no newline) that any other
+ * locale's message was appended to mid-line ("Translating 3 key(s) to
+ * French (local)...[INFO] ru/django.po — 3 missing"). Now:
+ *   - every message is one complete line;
+ *   - a progress bar names its file, and is redrawn in place only on a
+ *     terminal and only while nothing else has printed since — any other
+ *     output first ends the open bar line, so nothing is lost or overwritten;
+ *   - off a terminal (CI logs, pipes) every bar update is its own line.
+ *
+ * `openBar` is the item whose bar line is currently unterminated.
+ */
+let openBar = null;
+
+function endOpenBar() {
+  if (openBar !== null) {
+    process.stdout.write('\n');
+    openBar = null;
+  }
+}
+
 /**
  * Set the output mode. Call once during CLI bootstrap.
  *
@@ -64,10 +102,11 @@ function getMode() {
 function info(msg, data) {
   if (mode === 'quiet') return;
   if (mode === 'json') {
-    console.log(JSON.stringify({ level: 'info', message: msg, ...data }));
+    console.log(JSON.stringify({ level: 'info', message: showKey(msg), ...data }));
     return;
   }
-  console.log(`[INFO] ${msg}`);
+  endOpenBar();
+  console.log(`[INFO] ${showKey(msg)}`);
 }
 
 /**
@@ -80,10 +119,11 @@ function info(msg, data) {
 function ok(msg, data) {
   if (mode === 'quiet') return;
   if (mode === 'json') {
-    console.log(JSON.stringify({ level: 'ok', message: msg, ...data }));
+    console.log(JSON.stringify({ level: 'ok', message: showKey(msg), ...data }));
     return;
   }
-  console.log(`[OK] ${msg}`);
+  endOpenBar();
+  console.log(`[OK] ${showKey(msg)}`);
 }
 
 /**
@@ -95,10 +135,11 @@ function ok(msg, data) {
  */
 function warn(msg, data) {
   if (mode === 'json') {
-    console.error(JSON.stringify({ level: 'warn', message: msg, ...data }));
+    console.error(JSON.stringify({ level: 'warn', message: showKey(msg), ...data }));
     return;
   }
-  console.error(`[WARN] ${msg}`);
+  endOpenBar();
+  console.error(`[WARN] ${showKey(msg)}`);
 }
 
 /**
@@ -110,21 +151,48 @@ function warn(msg, data) {
  */
 function error(msg, data) {
   if (mode === 'json') {
-    console.error(JSON.stringify({ level: 'error', message: msg, ...data }));
+    console.error(JSON.stringify({ level: 'error', message: showKey(msg), ...data }));
     return;
   }
-  console.error(`[ERR] ${msg}`);
+  endOpenBar();
+  console.error(`[ERR] ${showKey(msg)}`);
 }
 
 /**
- * Progress message — inline status for long-running operations.
+ * Progress message — status for long-running operations, one complete line
+ * (a trailing newline is added; see LINE-ATOMIC OUTPUT above). Callers name
+ * what the line is about: with locales running in parallel, a bare
+ * " [OK]" could belong to any of them.
  * Suppressed in quiet and json modes.
  *
  * @param {string} msg - Progress description
  */
 function progress(msg) {
   if (mode === 'quiet' || mode === 'json') return;
-  process.stdout.write(msg);
+  const line = showKey(String(msg)).replace(/\n+$/, '');
+  if (line.trim() === '') return;
+  endOpenBar();
+  process.stdout.write(`${line}\n`);
+}
+
+/**
+ * Finish an item's progress: " [OK]" after its own bar when that bar is the
+ * line still open on a terminal, else a complete line naming the item.
+ * Suppressed in quiet and json modes.
+ *
+ * @param {string} item - What finished (the file name the bar showed)
+ * @param {string} status - e.g. "[OK]", "[ERR] all translations failed quality gate"
+ */
+function progressDone(item, status) {
+  if (mode === 'quiet' || mode === 'json') return;
+  const label = showKey(String(item));
+  if (openBar === label) {
+    process.stdout.write(` ${status}\n`);
+    openBar = null;
+    return;
+  }
+  endOpenBar();
+  process.stdout.write(`     ${label} ${status}\n`);
 }
 
 /**
@@ -135,7 +203,24 @@ function progress(msg) {
  */
 function debug(msg, data) {
   if (mode !== 'verbose') return;
-  console.log(`[DEBUG] ${msg}`);
+  endOpenBar();
+  console.log(`[DEBUG] ${showKey(msg)}`);
+}
+
+/**
+ * Event — one machine-readable progress record (json mode only).
+ * Emits `{level:'event', event, ...fields}` on stdout; silent otherwise —
+ * the human output already says the same thing in prose.
+ *
+ * Event types used by sync: 'cost' (the pre-run estimate, before the
+ * --max-cost gate) and 'file' (one per content file × locale processed).
+ *
+ * @param {string} event - Event type
+ * @param {object} [fields] - Structured data
+ */
+function event(eventType, fields) {
+  if (mode !== 'json') return;
+  console.log(JSON.stringify({ level: 'event', event: eventType, ...fields }));
 }
 
 /**
@@ -153,6 +238,7 @@ function summary(data) {
     return;
   }
   if (data.title) {
+    endOpenBar();
     console.log(`\n${data.title}`);
   }
 }
@@ -165,14 +251,18 @@ function summary(data) {
  */
 function banner(version) {
   if (mode === 'quiet' || mode === 'json') return;
+  endOpenBar();
   console.log(`champollion v${version}\n`);
 }
 
 /**
- * Progress bar — inline key-count progress indicator.
+ * Progress bar — key-count progress for one item (a locale file).
  *
- * Renders a bar like: `     ████████░░░░░░░░ 1,440/2,847 keys`
- * Uses carriage return (\r) to overwrite the current line in-place.
+ * Renders a line like: `     fr.json ████████░░░░░░░░ 1,440/2,847 keys`
+ * On a terminal the line is redrawn in place (\r) while it is still the
+ * last thing printed and belongs to the same item; otherwise (another
+ * locale's bar, any other message, or output that is not a terminal) each
+ * update is its own complete line — see LINE-ATOMIC OUTPUT.
  * Call with `done = true` to finalize the line with a newline.
  *
  * Suppressed in quiet and json modes.
@@ -180,12 +270,14 @@ function banner(version) {
  * @param {number} completed - Number of items completed
  * @param {number} total - Total number of items
  * @param {object} [opts] - Options
+ * @param {string} [opts.item=''] - What the bar is for (e.g. the locale file)
  * @param {string} [opts.label='keys'] - Unit label
  * @param {boolean} [opts.done=false] - Whether this is the final update (appends newline)
  */
 function progressBar(completed, total, opts = {}) {
   if (mode === 'quiet' || mode === 'json') return;
   const { label = 'keys', done = false } = opts;
+  const item = showKey(String(opts.item || ''));
 
   // Calculate bar width based on terminal width, with sane defaults
   const termWidth = process.stdout.columns || 80;
@@ -195,12 +287,34 @@ function progressBar(completed, total, opts = {}) {
   const filled = Math.round(ratio * barWidth);
   const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
   const nums = `${completed.toLocaleString()}/${total.toLocaleString()} ${label}`;
+  const line = `     ${item ? `${item} ` : ''}${bar} ${nums}`;
 
-  if (done) {
-    process.stdout.write(`\r     ${bar} ${nums}\n`);
+  if (!process.stdout.isTTY) {
+    endOpenBar();
+    process.stdout.write(`${line}\n`);
+    return;
+  }
+  if (openBar === item) {
+    process.stdout.write(`\r${line}`);
   } else {
-    process.stdout.write(`\r     ${bar} ${nums}`);
+    endOpenBar();
+    process.stdout.write(line);
   }
+  openBar = item;
+  if (done) endOpenBar();
+}
+
+/**
+ * A warning block: pre-formatted lines on stderr (the quality-gate and
+ * glossary reports), each a complete line with keys shown copyably.
+ * Emitted in every human mode, like warn(); callers emit structured
+ * records themselves in json mode.
+ *
+ * @param {string[]} lines
+ */
+function block(lines) {
+  endOpenBar();
+  for (const line of lines) console.error(showKey(line));
 }
 
 /**
@@ -217,7 +331,8 @@ function progressBar(completed, total, opts = {}) {
  */
 function raw(msg) {
   if (mode === 'quiet' || mode === 'json') return;
-  console.log(msg);
+  endOpenBar();
+  console.log(showKey(msg));
 }
 
 const output = {
@@ -228,11 +343,37 @@ const output = {
   warn,
   error,
   progress,
+  progressDone,
   debug,
   summary,
+  event,
   banner,
   progressBar,
   raw,
+  block,
 };
 
-export { output };
+/**
+ * A stored ISO timestamp as this machine's local date and time, with the
+ * zone named: "2026-10-03 18:20 MDT". The caches store UTC (`…Z`); printing
+ * the UTC date bare read as a day ahead of local time in the evening
+ * (Round 5, Next.js persona: `tm stats` "Created"). Zones without an
+ * abbreviation print as an offset ("GMT+5:30"). An unparsable value is
+ * returned unchanged; a missing one as "unknown".
+ *
+ * @param {string|null|undefined} iso
+ * @param {{ timeZone?: string }} [opts] - For tests; defaults to the machine's zone
+ * @returns {string}
+ */
+function localTimestamp(iso, opts = {}) {
+  if (!iso) return 'unknown';
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return String(iso);
+  const parts = Object.fromEntries(new Intl.DateTimeFormat('en-US', {
+    year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit',
+    hourCycle: 'h23', timeZoneName: 'short', ...(opts.timeZone && { timeZone: opts.timeZone }),
+  }).formatToParts(d).map(p => [p.type, p.value]));
+  return `${parts.year}-${parts.month}-${parts.day} ${parts.hour}:${parts.minute} ${parts.timeZoneName}`;
+}
+
+export { output, showKey, localTimestamp };