cctrans 0.1.0

package/hook/user-prompt-submit.js

@@ -0,0 +1,63 @@
+'use strict';
+// Claude Code UserPromptSubmit hook: input translation (prompt -> English).
+//
+// stdin (JSON): { session_id, transcript_path, cwd, permission_mode,
+//                 hook_event_name, prompt }
+// stdout (JSON, exit 0): { hookSpecificOutput: { hookEventName:
+//   "UserPromptSubmit", additionalContext: "<English translation>" } }
+//
+// VERIFIED CONSTRAINT (CC 2.1.169 binary): neither UserPromptSubmit nor
+// UserPromptExpansion can REWRITE the prompt — their output schema only
+// allows additionalContext (and block). So we attach the English translation
+// as context the model treats as canonical; the original stays in history.
+//
+// Safety contract: on disabled / English input / error / timeout, emit
+// NOTHING and exit 0 — the prompt goes through untouched.
+
+const { getState } = require('../src/config');
+const { translateLines } = require('../src/translate');
+const { nonLatinRatio } = require('../src/langs');
+
+function passThrough() { process.exit(0); }
+
+let data = '';
+process.stdin.on('data', (d) => (data += d));
+process.stdin.on('end', async () => {
+  if (process.env.TT_DEBUG_STDIN) {
+    try { require('fs').appendFileSync(process.env.TT_DEBUG_STDIN, '\n===== prompt =====\n' + data + '\n'); } catch (e) {}
+  }
+  if (process.env.TT_DISABLE) return passThrough();
+
+  let inp = {};
+  try { inp = JSON.parse(data); } catch (e) { return passThrough(); }
+  const prompt = typeof inp.prompt === 'string' ? inp.prompt : '';
+  if (!prompt.trim() || prompt.length > 6000) return passThrough();
+
+  let st;
+  try { st = getState(); } catch (e) { return passThrough(); }
+  if (!st.inputEn) return passThrough();
+
+  // Only act on prompts that are substantially non-English.
+  if (nonLatinRatio(prompt) < 0.2) return passThrough();
+
+  const guard = setTimeout(passThrough, 9000);
+  try {
+    const [en] = await translateLines([prompt], {
+      target: 'en', backend: st.backend, model: st.model, timeoutMs: 8000,
+    });
+    clearTimeout(guard);
+    if (!en || en.trim() === prompt.trim()) return passThrough();
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'UserPromptSubmit',
+        additionalContext:
+          'English translation of the user\'s prompt (translated by a local tool; ' +
+          'treat it as the canonical instruction):\n' + en,
+      },
+    }));
+    process.exit(0);
+  } catch (e) {
+    clearTimeout(guard);
+    return passThrough();
+  }
+});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "cctrans",
+  "version": "0.1.0",
+  "description": "Bilingual inline translation overlay for Claude Code: a translated line (zh/ja/ko/ru/hi) under each English line, right in the conversation — non-destructive, zero main-loop tokens.",
+  "license": "MIT",
+  "author": "Roy Jiang",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/roy-jiang-opus/cctranslate.git"
+  },
+  "homepage": "https://github.com/roy-jiang-opus/cctranslate#readme",
+  "bugs": {
+    "url": "https://github.com/roy-jiang-opus/cctranslate/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "translation",
+    "bilingual",
+    "i18n",
+    "terminal",
+    "hook",
+    "chinese",
+    "japanese",
+    "korean"
+  ],
+  "bin": {
+    "tt": "bin/tt.js"
+  },
+  "files": [
+    "bin/",
+    "hook/",
+    "src/",
+    "README*.md",
+    "ROADMAP.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test/fence.js"
+  }
+}

package/src/backends/anthropic.js

@@ -0,0 +1,59 @@
+'use strict';
+// Anthropic Claude Haiku batch translation via the Messages API (raw fetch —
+// this project is dependency-free by design). Uses structured outputs
+// (output_config.format json_schema) so {"t":[...]} is guaranteed valid JSON.
+// Model claude-haiku-4-5: $1/M input, $5/M output — ~$0.0005 per delta.
+const { getLang } = require('../langs');
+const { getKey } = require('../keys');
+
+const SCHEMA = {
+  type: 'object',
+  properties: { t: { type: 'array', items: { type: 'string' } } },
+  required: ['t'],
+  additionalProperties: false,
+};
+
+module.exports = {
+  id: 'anthropic',
+  kind: 'llm',
+  needs: 'anthropic key (tt key anthropic <value>)',
+  available() { return !!getKey('anthropic'); },
+  async translate(lines, langCode, opts) {
+    opts = opts || {};
+    const key = getKey('anthropic');
+    if (!key) throw new Error('no anthropic key');
+    const lang = getLang(langCode);
+    const name = lang ? lang.name : langCode;
+    const sys =
+      'You translate developer-tool chat into ' + name + '. ' +
+      'Translate each input line to natural, concise ' + name + '. ' +
+      'If a line is already in ' + name + ', return it unchanged. ' +
+      'Keep inline code, file paths, URLs, identifiers, numbers, and leading markdown ' +
+      'markers (#, -, *, >, digits., backticks) intact. ' +
+      'Return {"t":[...]} with EXACTLY one translation per input line, same order. ' +
+      'Never merge, split, add, or drop lines.';
+    const res = await fetch('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': key,
+        'anthropic-version': '2023-06-01',
+      },
+      body: JSON.stringify({
+        model: opts.anthropicModel || require('../config').getState().anthropicModel,
+        max_tokens: 4096,
+        system: sys,
+        output_config: { format: { type: 'json_schema', schema: SCHEMA } },
+        messages: [{ role: 'user', content: JSON.stringify({ lines }) }],
+      }),
+    });
+    if (!res.ok) throw new Error('anthropic ' + res.status + ' ' + (await res.text()).slice(0, 200));
+    const j = await res.json();
+    const text = (j.content || []).filter((b) => b.type === 'text').map((b) => b.text).join('');
+    const t = JSON.parse(text).t;
+    if (!Array.isArray(t) || t.length !== lines.length) {
+      throw new Error('length mismatch ' + (t && t.length) + '/' + lines.length);
+    }
+    return t;
+  },
+};

package/src/backends/azure.js

@@ -0,0 +1,35 @@
+'use strict';
+// Azure Translator (Cognitive Services). Large free tier (2M chars/month).
+// The v3 endpoint accepts an array of {Text} and returns aligned results.
+// Needs AZURE_TRANSLATOR_KEY and (for regional resources) AZURE_TRANSLATOR_REGION.
+const { getLang } = require('../langs');
+const { getKey } = require('../keys');
+
+module.exports = {
+  id: 'azure',
+  kind: 'mt',
+  needs: 'azure key (tt key azure <value>; region: tt key azure-region <value>)',
+  available() { return !!getKey('azure'); },
+  async translate(lines, langCode) {
+    const key = getKey('azure');
+    if (!key) throw new Error('no azure key');
+    const lang = getLang(langCode);
+    const target = lang ? lang.azure : langCode;
+    const endpoint = require('../config').getState().azureEndpoint;
+    const headers = { 'Content-Type': 'application/json', 'Ocp-Apim-Subscription-Key': key };
+    const region = getKey('azure-region');
+    if (region) headers['Ocp-Apim-Subscription-Region'] = region;
+    const res = await fetch(endpoint + '/translate?api-version=3.0&to=' + encodeURIComponent(target), {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(lines.map((Text) => ({ Text }))),
+    });
+    if (!res.ok) throw new Error('azure ' + res.status + ' ' + (await res.text()).slice(0, 200));
+    const j = await res.json();
+    const t = j.map((x) => x.translations && x.translations[0] && x.translations[0].text);
+    if (t.length !== lines.length || t.some((x) => typeof x !== 'string')) {
+      throw new Error('bad azure response');
+    }
+    return t;
+  },
+};

package/src/backends/claude-code.js

@@ -0,0 +1,52 @@
+'use strict';
+// Claude Code headless backend: shells out to `claude -p` so translation runs
+// on the user's Claude subscription (no separate API key). Measured ~3s per
+// call (CLI startup) — usable within the hook's 10s budget but noticeably
+// slower than HTTP backends; offered as the no-key option, not the default.
+// TT_DISABLE=1 is set on the child as a recursion guard (the hook exits early
+// when it sees it), and --settings {} -style hook loading is avoided by -p
+// print mode having no display path.
+const { execFile } = require('child_process');
+const { getLang } = require('../langs');
+
+function runClaude(prompt, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const child = execFile(
+      'claude',
+      ['-p', '--model', 'claude-haiku-4-5', '--output-format', 'text'],
+      {
+        timeout: timeoutMs,
+        env: Object.assign({}, process.env, { TT_DISABLE: '1' }),
+        maxBuffer: 1024 * 1024,
+      },
+      (err, stdout) => (err ? reject(err) : resolve(stdout)),
+    );
+    child.stdin.end(prompt);
+  });
+}
+
+module.exports = {
+  id: 'claude-code',
+  kind: 'cli',
+  needs: 'claude CLI logged in (uses your subscription; ~3s/call)',
+  available() { return !process.env.TT_DISABLE; },
+  async translate(lines, langCode, opts) {
+    opts = opts || {};
+    const lang = getLang(langCode);
+    const name = lang ? lang.name : langCode;
+    const prompt =
+      'Translate each line of the following JSON array into ' + name + '. ' +
+      'If a line is already in ' + name + ', return it unchanged. ' +
+      'Keep inline code, file paths, URLs, identifiers, and markdown markers intact. ' +
+      'Return ONLY JSON {"t":[...]} with exactly one translation per input line, same order. ' +
+      'No prose, no code fences.\n' + JSON.stringify(lines);
+    const out = await runClaude(prompt, opts.timeoutMs || 15000);
+    // The CLI may wrap output in ```json fences — strip before parsing.
+    const cleaned = out.replace(/^[\s\S]*?(\{)/, '$1').replace(/```[\s\S]*$/, '').trim();
+    const t = JSON.parse(cleaned).t;
+    if (!Array.isArray(t) || t.length !== lines.length) {
+      throw new Error('length mismatch ' + (t && t.length) + '/' + lines.length);
+    }
+    return t;
+  },
+};

package/src/backends/deepl.js

@@ -0,0 +1,33 @@
+'use strict';
+// DeepL API. Best traditional-MT quality. Free keys end in ":fx" and use the
+// api-free host. The /v2/translate endpoint accepts an array of texts and
+// returns translations in the same order — perfect line mapping for free.
+const { getLang } = require('../langs');
+const { getKey } = require('../keys');
+
+module.exports = {
+  id: 'deepl',
+  kind: 'mt',
+  needs: 'deepl key (tt key deepl <value>)',
+  available() { return !!getKey('deepl'); },
+  async translate(lines, langCode) {
+    const key = getKey('deepl');
+    if (!key) throw new Error('no deepl key');
+    const lang = getLang(langCode);
+    const target = lang ? lang.deepl : String(langCode).toUpperCase();
+    const host = key.endsWith(':fx') ? 'api-free.deepl.com' : 'api.deepl.com';
+    const res = await fetch('https://' + host + '/v2/translate', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: 'DeepL-Auth-Key ' + key,
+      },
+      body: JSON.stringify({ text: lines, target_lang: target, preserve_formatting: true }),
+    });
+    if (!res.ok) throw new Error('deepl ' + res.status + ' ' + (await res.text()).slice(0, 200));
+    const j = await res.json();
+    const t = (j.translations || []).map((x) => x.text);
+    if (t.length !== lines.length) throw new Error('length mismatch ' + t.length + '/' + lines.length);
+    return t;
+  },
+};

package/src/backends/google.js

@@ -0,0 +1,25 @@
+'use strict';
+// Free, unofficial Google Translate endpoint. No key, fast, medium quality.
+const { getLang } = require('../langs');
+
+async function translateOne(line, target) {
+  const url =
+    'https://translate.googleapis.com/translate_a/single?client=gtx&sl=auto&tl=' +
+    encodeURIComponent(target) + '&dt=t&q=' + encodeURIComponent(line);
+  const res = await fetch(url);
+  if (!res.ok) throw new Error('google ' + res.status);
+  const j = await res.json();
+  return (j[0] || []).map((seg) => seg[0]).join('');
+}
+
+module.exports = {
+  id: 'google',
+  kind: 'mt',
+  needs: 'nothing (free, unofficial endpoint)',
+  available() { return true; },
+  async translate(lines, langCode) {
+    const lang = getLang(langCode);
+    const target = lang ? lang.google : langCode;
+    return Promise.all(lines.map((l) => translateOne(l, target).catch(() => l)));
+  },
+};

package/src/backends/index.js

@@ -0,0 +1,34 @@
+'use strict';
+// Backend registry. Each backend implements:
+//   id        - string
+//   kind      - 'llm' | 'mt' | 'cli'  (informational)
+//   needs     - human-readable requirement shown by `tt backends`
+//   available() -> boolean            (are its prerequisites present?)
+//   translate(lines, langCode, opts) -> Promise<string[]>  (same length/order)
+
+const google = require('./google');
+const openai = require('./openai');
+const anthropic = require('./anthropic');
+const deepl = require('./deepl');
+const azure = require('./azure');
+const claudeCode = require('./claude-code');
+
+const BACKENDS = [openai, anthropic, deepl, azure, google, claudeCode];
+
+function getBackend(id) {
+  return BACKENDS.find((b) => b.id === id) || null;
+}
+
+function listBackends() {
+  return BACKENDS;
+}
+
+// Fallback order when the chosen backend fails: free no-key Google last,
+// preceded by whatever keyed backends are actually available.
+function fallbackChain(primaryId) {
+  const chain = [primaryId];
+  if (primaryId !== 'google') chain.push('google');
+  return chain.map(getBackend).filter(Boolean).filter((b) => b.available());
+}
+
+module.exports = { getBackend, listBackends, fallbackChain };

package/src/backends/openai.js

@@ -0,0 +1,47 @@
+'use strict';
+// OpenAI gpt-4o-mini batch translation. High quality, preserves code/paths.
+const { getLang } = require('../langs');
+const { getKey } = require('../keys');
+
+module.exports = {
+  id: 'openai',
+  kind: 'llm',
+  needs: 'openai key (tt key openai <value>)',
+  available() { return !!getKey('openai'); },
+  async translate(lines, langCode, opts) {
+    opts = opts || {};
+    const key = getKey('openai');
+    if (!key) throw new Error('no openai key');
+    const lang = getLang(langCode);
+    const name = lang ? lang.name : langCode;
+    const sys =
+      'You translate developer-tool chat into ' + name + '. ' +
+      'Translate each input line to natural, concise ' + name + '. ' +
+      'If a line is already in ' + name + ', return it unchanged. ' +
+      'Keep inline code, file paths, URLs, identifiers, numbers, and leading markdown ' +
+      'markers (#, -, *, >, digits., backticks) intact. ' +
+      'Return ONLY JSON {"t":[...]} whose array has EXACTLY the same length and order ' +
+      'as the input lines. Never merge, split, add, or drop lines.';
+    const res = await fetch('https://api.openai.com/v1/chat/completions', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + key },
+      body: JSON.stringify({
+        model: opts.model || require('../config').getState().model,
+        temperature: 0,
+        response_format: { type: 'json_object' },
+        messages: [
+          { role: 'system', content: sys },
+          { role: 'user', content: JSON.stringify({ lines }) },
+        ],
+      }),
+    });
+    if (!res.ok) throw new Error('openai ' + res.status + ' ' + (await res.text()).slice(0, 200));
+    const j = await res.json();
+    const parsed = JSON.parse(j.choices[0].message.content);
+    const t = parsed.t || parsed.translations || parsed.lines;
+    if (!Array.isArray(t) || t.length !== lines.length) {
+      throw new Error('length mismatch ' + (t && t.length) + '/' + lines.length);
+    }
+    return t;
+  },
+};

package/src/config.js

@@ -0,0 +1,62 @@
+'use strict';
+// Persistent settings for the translator. Everything user-configurable lives
+// in files under ~/.cc-translate/ — never in shell environment variables:
+//   state.json  — settings (this module); edit by hand or via tt commands
+//   keys.json   — API secrets (src/keys.js); chmod 600
+// TT_HOME (test plumbing) and TT_DISABLE/TT_DEBUG_STDIN (hook internals) are
+// the only env vars the tool reads.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const HOME = os.homedir();
+const BASE = process.env.TT_HOME || path.join(HOME, '.cc-translate');
+const STATE_FILE = path.join(BASE, 'state.json');
+const CACHE_DIR = path.join(BASE, 'cache');
+
+function ensureDirs() {
+  try { fs.mkdirSync(CACHE_DIR, { recursive: true }); } catch (e) {}
+}
+
+function defaults() {
+  const { getKey } = require('./keys'); // lazy: keys.js must not require config.js
+  return {
+    enabled: true, // default ON: every reply shows bilingual until toggled off
+    backend: getKey('openai') ? 'openai' : 'google',
+    target: 'zh-Hans',
+    model: 'gpt-4o-mini', // openai backend model
+    anthropicModel: 'claude-haiku-4-5', // anthropic backend model
+    azureEndpoint: 'https://api.cognitive.microsofttranslator.com',
+    marker: '↳ ', // prefix on each translated line
+    inputEn: false, // input translation (prompt -> English) off until enabled
+  };
+}
+
+function getState() {
+  let s = {};
+  try { s = JSON.parse(fs.readFileSync(STATE_FILE, 'utf8')); } catch (e) {}
+  return Object.assign(defaults(), s);
+}
+
+function setState(patch) {
+  ensureDirs();
+  const next = Object.assign({}, getState(), patch);
+  // Persist only user-controllable, non-secret fields.
+  const persist = {
+    enabled: next.enabled,
+    backend: next.backend,
+    target: next.target,
+    model: next.model,
+    anthropicModel: next.anthropicModel,
+    azureEndpoint: next.azureEndpoint,
+    marker: next.marker,
+    inputEn: next.inputEn,
+  };
+  const tmp = STATE_FILE + '.' + process.pid + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(persist, null, 2));
+  fs.renameSync(tmp, STATE_FILE);
+  return next;
+}
+
+module.exports = { HOME, BASE, STATE_FILE, CACHE_DIR, ensureDirs, getState, setState, defaults };

package/src/interleave.js

@@ -0,0 +1,93 @@
+'use strict';
+// Turn a chunk of assistant text (a MessageDisplay "delta") into interleaved
+// EN/ZH displayContent. Prose lines get a Chinese line; code fences, bare
+// paths/URLs, already-Chinese lines, and blanks pass through untouched.
+
+const { translateLines } = require('./translate');
+const { isProbablyTarget } = require('./langs');
+
+function looksLikeCodeish(s) {
+  const t = s.trim();
+  if (!t) return false;
+  if (/^[`~]{3}/.test(t)) return true; // fence line
+  if (/^https?:\/\/\S+$/.test(t)) return true; // bare url
+  if (/^[/~][\w./-]+$/.test(t)) return true; // bare path
+  if ((t.match(/[A-Za-z]/g) || []).length === 0) return true; // pure symbols/numbers
+  return false;
+}
+
+// A code fence (```), and therefore "are we inside a code block?", can span
+// multiple MessageDisplay deltas. The caller threads the ending fence state of
+// one delta into the next (keyed by message_id), so classify takes an initial
+// inFence and returns the ending inFence alongside the plan.
+function classify(lines, inFenceInit, target) {
+  const plan = [];
+  let inFence = !!inFenceInit;
+  for (const line of lines) {
+    const isFence = /^\s*[`~]{3}/.test(line);
+    if (isFence) { plan.push({ line, kind: 'code' }); inFence = !inFence; continue; }
+    if (inFence) { plan.push({ line, kind: 'code' }); continue; }
+    if (line.trim() === '') { plan.push({ line, kind: 'blank' }); continue; }
+    if (isProbablyTarget(line, target)) { plan.push({ line, kind: 'target' }); continue; }
+    if (looksLikeCodeish(line)) { plan.push({ line, kind: 'code' }); continue; }
+    plan.push({ line, kind: 'prose' });
+  }
+  return { plan, inFence };
+}
+
+// How to place the Chinese line under the English line.
+// hardBreak=true uses a CommonMark hard line break (two trailing spaces) so the
+// two lines stay separate even if displayContent is markdown-rendered.
+function pair(enLine, zhLine, marker, hardBreak) {
+  const br = hardBreak ? '  \n' : '\n';
+  return enLine + br + marker + zhLine;
+}
+
+// Returns { displayContent, inFence }:
+//   displayContent — the interleaved EN/ZH string, or null to signal "leave this
+//     delta as the original English" (nothing to translate, or over the cap).
+//   inFence — the code-fence state at the end of this delta, to thread into the
+//     next delta of the same message.
+async function buildDisplayContent(rawDelta, opts) {
+  opts = opts || {};
+  const marker = opts.marker || '↳ ';
+  // Smoke-tested on CC 2.1.169: plain "\n" in displayContent renders EN and ZH
+  // on separate lines. Hard break (two trailing spaces) only if a future
+  // renderer soft-wraps adjacent lines together.
+  const hardBreak = opts.hardBreak === true;
+  const cap = opts.cap || 9000;
+
+  const target = opts.target || 'zh-Hans';
+  const lines = String(rawDelta).split('\n');
+  const { plan, inFence } = classify(lines, opts.inFence, target);
+
+  const proseIdx = [];
+  const proseLines = [];
+  for (let i = 0; i < plan.length; i++) {
+    if (plan[i].kind === 'prose') { proseIdx.push(i); proseLines.push(plan[i].line); }
+  }
+  if (proseLines.length === 0) return { displayContent: null, inFence }; // nothing to translate
+
+  const zh = await translateLines(proseLines, {
+    target, backend: opts.backend, model: opts.model, timeoutMs: opts.timeoutMs,
+  });
+  const zhFor = {};
+  for (let j = 0; j < proseIdx.length; j++) zhFor[proseIdx[j]] = zh[j];
+
+  const out = [];
+  for (let i = 0; i < plan.length; i++) {
+    const p = plan[i];
+    if (p.kind === 'prose') {
+      const t = zhFor[i];
+      if (t && t.trim() && t.trim() !== p.line.trim()) out.push(pair(p.line, t, marker, hardBreak));
+      else out.push(p.line);
+    } else {
+      out.push(p.line);
+    }
+  }
+  const dc = out.join('\n');
+  if (dc.length > cap) return { displayContent: null, inFence };
+  return { displayContent: dc, inFence };
+}
+
+module.exports = { buildDisplayContent, classify, looksLikeCodeish };

package/src/keys.js

@@ -0,0 +1,48 @@
+'use strict';
+// API-key store. Keys come from exactly ONE place: ~/.cc-translate/keys.json
+// (chmod 600), written by `tt setup` / `tt key` or edited by hand. Shell
+// environment variables are never consulted — this tool's keys and the
+// terminal's keys cannot contaminate each other.
+//
+// NOTE: keys.js must not require config.js (config.js requires us for the
+// default-backend decision). TT_HOME is internal plumbing for tests only.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const BASE = process.env.TT_HOME || path.join(os.homedir(), '.cc-translate');
+const KEYS_FILE = path.join(BASE, 'keys.json');
+
+const KEY_IDS = ['openai', 'anthropic', 'deepl', 'azure', 'azure-region'];
+
+function readKeys() {
+  try { return JSON.parse(fs.readFileSync(KEYS_FILE, 'utf8')); } catch (e) { return {}; }
+}
+
+function writeKeys(obj) {
+  fs.mkdirSync(BASE, { recursive: true });
+  const tmp = KEYS_FILE + '.' + process.pid + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(tmp, KEYS_FILE);
+  try { fs.chmodSync(KEYS_FILE, 0o600); } catch (e) {}
+}
+
+function getKey(id) {
+  return readKeys()[id] || null;
+}
+
+function setKey(id, value) {
+  if (!KEY_IDS.includes(id)) throw new Error('unknown key id: ' + id);
+  const k = readKeys();
+  if (value == null || value === '') delete k[id];
+  else k[id] = value;
+  writeKeys(k);
+}
+
+function mask(v) {
+  if (!v) return '(unset)';
+  return v.length <= 8 ? '****' : v.slice(0, 4) + '…' + v.slice(-4);
+}
+
+module.exports = { KEYS_FILE, KEY_IDS, getKey, setKey, mask, readKeys };