zames_pro 2.65.1 → 2.66.1

package/dist/index.js

@@ -19,13 +19,10 @@ import { Transcript } from './transcript.js';
 import { UndoStore } from './undo.js';
 import { CheckpointStore, pickRecord as pickCheckpoint } from './checkpoint.js';
 import { selfReview, selfDiff, selfApply, selfList } from './self-review.js';
-import { formatDiff, formatDiffStat, formatContextSources, diffGitArgs, parseTranscript, summarizeTranscript, renderCost, formatExport, defaultExportPath, renderDoctor, resolveExtraDir, buildReviewPrompt, isDevOnlyCommand, parseBacklogItems, nextBacklogItem, buildImprovePrompt, formatRelativeTime, trimRestoredMessages, RESTORED_HISTORY_LIMIT, hasQueuedJob, buildSlashCommandHints, parseQueueCommand, parseLiveToggle, parseGoalCommand, isLiveConfigCommand, formatQueueList, ctrlCEscalation, expandCommandArgs, missingCommandArgs, } from './commands.js';
 import { performCompact } from './compact.js';
 import { Scheduler, parseInterval, formatInterval, formatJobLine, parseCron, } from './scheduler.js';
 import { renderMarkdown, setAnswerWidth } from './markdown.js';
-import { resolveAttachPath, inlineAtRefs } from './attach-refs.js';
 import { parseBacklogNote } from './backlog.js';
-import { runTask } from './run-task.js';
 import { closeWeb } from './web.js';
 import { assertCommandInsideRoot, runShell } from './shell.js';
 import { saveSession, loadLastSession, readSession, listSessions, sessionsDir, loadHistory, saveHistory, } from './sessions.js';
@@ -198,8 +195,19 @@ const RELOADABLE = [
     'config',
     'fsutil',
     'backlog',
+    // C3 modules index.ts now calls through the mod bag (G2): without this a
+    // /reload silently kept the OLD commands/run-task/attach-refs until a restart.
+    // 'input/layout' is NOT listed: its only live consumers are input.ts (the
+    // long-lived LineEditor, itself not reloadable) and spinner.ts, which already
+    // picks up a fresh copy transitively.
+    'commands',
+    'run-task',
+    'attach-refs',
 ];
 const mod = {
+    commands: null,
+    attach: null,
+    runTask: null,
     createTools,
     runAgentLoop,
     buildSystemPrompt: null,
@@ -260,6 +268,12 @@ async function reloadModules() {
         mod.backlogStats = pick('backlog', 'backlogStats');
     if (pick('backlog', 'backlogNeedsPruning'))
         mod.backlogNeedsPruning = pick('backlog', 'backlogNeedsPruning');
+    if (pick('commands', 'missingCommandArgs'))
+        mod.commands = loaded.get('commands');
+    if (pick('attach-refs', 'resolveAttachPath'))
+        mod.attach = loaded.get('attach-refs');
+    if (pick('run-task', 'runTask'))
+        mod.runTask = pick('run-task', 'runTask');
     return { count: loaded.size, errors };
 }
 // Initial load so that mod.buildSystemPrompt and the rest are populated.
@@ -508,10 +522,10 @@ async function expandSlashTarget(workdir, name, rest) {
         const cmd = commands.find((c) => c.name.toLowerCase() === name.toLowerCase());
         if (cmd) {
             // B7: refuse to run when declared positional arguments are missing.
-            const missing = missingCommandArgs(cmd.arguments, rest);
+            const missing = mod.commands.missingCommandArgs(cmd.arguments, rest);
             if (missing.length)
                 return { missing };
-            const body = expandCommandArgs(cmd.body, rest, cmd.arguments);
+            const body = mod.commands.expandCommandArgs(cmd.body, rest, cmd.arguments);
             return { text: body || rest };
         }
         const skills = await loadSkills(workdir);
@@ -549,7 +563,11 @@ async function expandSlashTarget(workdir, name, rest) {
 // in commands.ts (buildSlashCommandHints); here we only supply the runtime
 // data (dev flag, translator, dynamic skills/commands).
 function buildSlashCommands() {
-    return buildSlashCommandHints({ devMode, t, dynamic: dynamicCommands });
+    return mod.commands.buildSlashCommandHints({
+        devMode,
+        t,
+        dynamic: dynamicCommands,
+    });
 }
 // We put the agent's temporary files (one-off scripts, etc.) in
 // <project>/tmp — this folder is in .gitignore and is cleaned on every launch.
@@ -805,8 +823,8 @@ async function printRestoredHistory(browser, ui, chatId = null) {
     // those. The "truncated" note must compare the DISPLAYABLE count with the
     // limit (comparing `all.length` always fired, because tool-calls are
     // dropped and the raw history is always longer).
-    const displayable = trimRestoredMessages(all, 0);
-    const messages = trimRestoredMessages(all);
+    const displayable = mod.commands.trimRestoredMessages(all, 0);
+    const messages = mod.commands.trimRestoredMessages(all);
     // Always surface the diagnostic line when the history could not be turned
     // into anything printable — otherwise "the dialogue is empty" is a dead end
     // (was the fetch blocked? did the chat really have no user turns?).
@@ -857,7 +875,9 @@ async function printRestoredHistory(browser, ui, chatId = null) {
         }
     }
     if (displayable.length > messages.length) {
-        out(theme.dim(t('chats.history_truncated', { n: String(RESTORED_HISTORY_LIMIT) })));
+        out(theme.dim(t('chats.history_truncated', {
+            n: String(mod.commands.RESTORED_HISTORY_LIMIT),
+        })));
     }
 }
 // Build the explicit dependency bag for runTask() (src/run-task.ts). The
@@ -1011,7 +1031,7 @@ async function main() {
             }
         }
         await autoReload();
-        await runTask(runTaskDeps(), browser, tools, task, currentWorkdir, {
+        await mod.runTask(runTaskDeps(), browser, tools, task, currentWorkdir, {
             transcript,
             freshChat,
             sendSystemPrompt,
@@ -1132,7 +1152,7 @@ async function main() {
                 // this job already has a pending message in the queue, skip this fire.
                 // Otherwise a 1-minute loop would add a new task every minute while a
                 // long task is in flight, and they would all run back-to-back.
-                if (hasQueuedJob(pendingQueue, job.id)) {
+                if (mod.commands.hasQueuedJob(pendingQueue, job.id)) {
                     transcript.log('scheduled_skip_queued', {
                         id: job.id,
                         task: job.task,
@@ -1300,7 +1320,7 @@ async function main() {
                 return att;
             }
             // Case 2: the paste is a path to a local file (drag&drop or copy path).
-            const filePath = await resolveAttachPath(currentWorkdir, raw);
+            const filePath = await mod.attach.resolveAttachPath(currentWorkdir, raw);
             if (!filePath)
                 return null;
             const data = await fs.readFile(filePath).catch(() => null);
@@ -1378,7 +1398,7 @@ async function main() {
             // `await runTask()`, so ONLY commands that make sense without the main
             // loop are handled here (a queued slash-command would run too late).
             if (ed.busy) {
-                const q = parseQueueCommand(text);
+                const q = mod.commands.parseQueueCommand(text);
                 if (q) {
                     if (q.sub === 'clear') {
                         const n = pendingQueue.length;
@@ -1390,7 +1410,7 @@ async function main() {
                     }
                     else {
                         ed.printAbove(theme.system(t('msg.queue_title')));
-                        for (const line of formatQueueList(pendingQueue)) {
+                        for (const line of mod.commands.formatQueueList(pendingQueue)) {
                             ed.printAbove(theme.assistant(line));
                         }
                         ed.printAbove(theme.dim(t('msg.queue_cleared_hint')));
@@ -1401,7 +1421,7 @@ async function main() {
                 // browser's DESIRED state and the status icons; it does not touch the
                 // in-flight generation, so it is safe mid-run. The actual DeepSeek
                 // toggles are applied on the next send by _applyToggles().
-                const tg = parseLiveToggle(text);
+                const tg = mod.commands.parseLiveToggle(text);
                 if (tg) {
                     applyLiveToggle(tg);
                     return;
@@ -1412,7 +1432,7 @@ async function main() {
                 // it pauses the editor and would fight the running task, so it stays
                 // queued. `setConfigRuntime` already applies hot values (locale,
                 // toggles, context limit) to the live objects immediately.
-                if (isLiveConfigCommand(text)) {
+                if (mod.commands.isLiveConfigCommand(text)) {
                     void handleConfigCommand(text);
                     return;
                 }
@@ -1458,7 +1478,7 @@ async function main() {
                 // (sets _stopped, which also halts the queue). This makes the two
                 // intents distinguishable instead of one press doing everything.
                 const now = Date.now();
-                if (ctrlCEscalation(now - lastCtrlCAt) === 'run') {
+                if (mod.commands.ctrlCEscalation(now - lastCtrlCAt) === 'run') {
                     ed.printAbove(theme.warn(t('msg.abort_ctrlc_short')));
                     browser.stopGeneration().catch(() => { });
                 }
@@ -1605,7 +1625,7 @@ async function main() {
     // variable and a file, never the chat). Output goes above the input line
     // when the editor is active, otherwise to stdout.
     async function handleGoal(input) {
-        const g = parseGoalCommand(input);
+        const g = mod.commands.parseGoalCommand(input);
         if (!g)
             return;
         const emit = (line) => {
@@ -1864,7 +1884,7 @@ async function main() {
         // Hiding them from /help is not enough: a user could type the command by
         // hand, and it would rewrite their project's BACKLOG.md or snapshot src/.
         if (!devMode) {
-            const devCmd = isDevOnlyCommand(lower);
+            const devCmd = mod.commands.isDevOnlyCommand(lower);
             if (devCmd) {
                 console.error(theme.warn(t('msg.dev_only', { v: devCmd })));
                 continue;
@@ -2240,7 +2260,7 @@ async function main() {
                     const mark = s.id === currentChatId ? theme.user(' *') : '';
                     const title = s.title ? `  ${s.title}` : '';
                     const wd = s.workdir ? theme.dim(`  [${dirLabel(s.workdir)}]`) : '';
-                    const age = formatRelativeTime(s.updatedAt, t);
+                    const age = mod.commands.formatRelativeTime(s.updatedAt, t);
                     const ageText = age ? theme.dim('  ' + age) : '';
                     console.log(`  ${theme.user(n)}. ${s.id.slice(0, 8)}…${title}${wd}${ageText}${mark}`);
                 });
@@ -2415,7 +2435,7 @@ async function main() {
             continue;
         }
         if (lower === '/queue' || lower.startsWith('/queue ')) {
-            const q = parseQueueCommand(trimmed);
+            const q = mod.commands.parseQueueCommand(trimmed);
             if (!q) {
                 console.error(theme.error(t('msg.queue_usage')));
                 continue;
@@ -2431,7 +2451,7 @@ async function main() {
                 continue;
             }
             console.log(theme.system(t('msg.queue_title')));
-            for (const line of formatQueueList(pendingQueue)) {
+            for (const line of mod.commands.formatQueueList(pendingQueue)) {
                 console.log(theme.assistant(line));
             }
             console.log(theme.dim(t('msg.queue_cleared_hint')));
@@ -2452,7 +2472,7 @@ async function main() {
             continue;
         }
         if (lower.startsWith('/thinking') || lower.startsWith('/web')) {
-            const tg = parseLiveToggle(trimmed);
+            const tg = mod.commands.parseLiveToggle(trimmed);
             if (tg) {
                 applyLiveToggle(tg);
                 continue;
@@ -2751,7 +2771,7 @@ async function main() {
                     locale: currentLocale,
                     context: ctx,
                 }).length;
-                console.log(theme.system(formatContextSources(ctx.agents, ctx.memory, ctx.skills, ctx.commands, { systemPromptChars: sysLen }, t)));
+                console.log(theme.system(mod.commands.formatContextSources(ctx.agents, ctx.memory, ctx.skills, ctx.commands, { systemPromptChars: sysLen }, t)));
             }
             catch (e) {
                 console.error(theme.error(e.message));
@@ -2807,7 +2827,7 @@ async function main() {
             if (editor)
                 editor.busy = true;
             try {
-                await runTask(runTaskDeps(), browser, tools, lastTaskText, currentWorkdir, {
+                await mod.runTask(runTaskDeps(), browser, tools, lastTaskText, currentWorkdir, {
                     transcript,
                     freshChat: false,
                     sendSystemPrompt: false,
@@ -2838,8 +2858,8 @@ async function main() {
                 console.error(theme.error(t('diff.not_repo')));
                 continue;
             }
-            const out = await runGit(diffGitArgs(staged), currentWorkdir, 20_000);
-            console.log(theme.system(formatDiff(out, { maxLines: 400 }, t)));
+            const out = await runGit(mod.commands.diffGitArgs(staged), currentWorkdir, 20_000);
+            console.log(theme.system(mod.commands.formatDiff(out, { maxLines: 400 }, t)));
             continue;
         }
         if (lower === '/diffstat') {
@@ -2850,28 +2870,28 @@ async function main() {
                 continue;
             }
             const out = await runGit('git diff --stat', currentWorkdir, 20_000);
-            console.log(theme.system(formatDiffStat(out, { maxLines: 60 }, t)));
+            console.log(theme.system(mod.commands.formatDiffStat(out, { maxLines: 60 }, t)));
             continue;
         }
         if (lower === '/cost' || lower === '/usage') {
-            let stats = summarizeTranscript([]);
+            let stats = mod.commands.summarizeTranscript([]);
             if (transcript.file) {
                 try {
                     const body = await fs.readFile(transcript.file, 'utf-8');
-                    stats = summarizeTranscript(parseTranscript(body));
+                    stats = mod.commands.summarizeTranscript(mod.commands.parseTranscript(body));
                 }
                 catch {
                     // best-effort
                 }
             }
-            console.log(theme.system(renderCost(stats, transcript.file, browser.getLastTokenUsage(), t)));
+            console.log(theme.system(mod.commands.renderCost(stats, transcript.file, browser.getLastTokenUsage(), t)));
             continue;
         }
         if (lower === '/export' || lower.startsWith('/export ')) {
             const arg = trimmed.slice('/export'.length).trim();
             const target = arg
                 ? path.resolve(currentWorkdir, arg)
-                : defaultExportPath(currentWorkdir);
+                : mod.commands.defaultExportPath(currentWorkdir);
             const rel = path.relative(sandboxRoot, target);
             if (rel.startsWith('..') || path.isAbsolute(rel)) {
                 console.error(theme.error(t('export.outside')));
@@ -2880,13 +2900,13 @@ async function main() {
             let entries = [];
             if (transcript.file) {
                 try {
-                    entries = parseTranscript(await fs.readFile(transcript.file, 'utf-8'));
+                    entries = mod.commands.parseTranscript(await fs.readFile(transcript.file, 'utf-8'));
                 }
                 catch {
                     entries = [];
                 }
             }
-            const md = formatExport(entries, {
+            const md = mod.commands.formatExport(entries, {
                 chatId: currentChatId,
                 workdir: currentWorkdir,
             });
@@ -2918,7 +2938,7 @@ async function main() {
             const mcpStatus = mcpPool
                 ? mcpPool.status()
                 : { servers: [], toolCount: 0 };
-            console.log(theme.system(renderDoctor({
+            console.log(theme.system(mod.commands.renderDoctor({
                 nodeVersion: process.version,
                 platform: process.platform,
                 workdir: currentWorkdir,
@@ -2944,7 +2964,7 @@ async function main() {
         }
         if (lower === '/add-dir' || lower.startsWith('/add-dir ')) {
             const arg = trimmed.slice('/add-dir'.length).trim();
-            const res = resolveExtraDir(arg, currentWorkdir, t);
+            const res = mod.commands.resolveExtraDir(arg, currentWorkdir, t);
             if ('error' in res) {
                 console.error(theme.warn(res.error));
                 continue;
@@ -3000,8 +3020,8 @@ async function main() {
                 console.error(theme.warn(t('improve.no_backlog')));
                 continue;
             }
-            const items = parseBacklogItems(backlogText);
-            const item = nextBacklogItem(items, arg || undefined);
+            const items = mod.commands.parseBacklogItems(backlogText);
+            const item = mod.commands.nextBacklogItem(items, arg || undefined);
             if (!item) {
                 console.log(theme.dim(arg ? t('improve.not_found', { v: arg }) : t('improve.all_done')));
                 continue;
@@ -3017,7 +3037,7 @@ async function main() {
             if (editor)
                 editor.busy = true;
             try {
-                await runTask(runTaskDeps(), browser, improveTools, buildImprovePrompt(item), currentWorkdir, {
+                await mod.runTask(runTaskDeps(), browser, improveTools, mod.commands.buildImprovePrompt(item), currentWorkdir, {
                     transcript,
                     freshChat: false,
                     sendSystemPrompt: false,
@@ -3094,7 +3114,7 @@ async function main() {
             const rest = trimmed.slice('/review'.length).trim();
             const staged = rest.indexOf('--staged') !== -1;
             const focus = rest.replace(/--staged/g, '').trim();
-            const reviewTask = buildReviewPrompt(focus, staged);
+            const reviewTask = mod.commands.buildReviewPrompt(focus, staged);
             const reviewTools = mod.createTools(currentWorkdir, {
                 undo,
                 todos: todoStore,
@@ -3102,7 +3122,7 @@ async function main() {
             if (editor)
                 editor.busy = true;
             try {
-                await runTask(runTaskDeps(), browser, reviewTools, reviewTask, currentWorkdir, {
+                await mod.runTask(runTaskDeps(), browser, reviewTools, reviewTask, currentWorkdir, {
                     transcript,
                     freshChat: false,
                     sendSystemPrompt: false,
@@ -3317,7 +3337,7 @@ async function main() {
         // existing files are inlined; a bare `@name` in prose is left untouched.
         let finalTaskText = taskText;
         {
-            const refRes = await inlineAtRefs(currentWorkdir, taskText);
+            const refRes = await mod.attach.inlineAtRefs(currentWorkdir, taskText);
             if (refRes.inlined.length) {
                 finalTaskText = refRes.text;
                 console.log(theme.system(t('msg.at_refs', { n: refRes.inlined.length }) +
@@ -3357,7 +3377,7 @@ async function main() {
         if (editor)
             editor.busy = true;
         try {
-            await runTask(runTaskDeps(), browser, tools, finalTaskText, currentWorkdir, {
+            await mod.runTask(runTaskDeps(), browser, tools, finalTaskText, currentWorkdir, {
                 transcript,
                 freshChat: freshChatNext,
                 sendSystemPrompt: sendSystemPromptNext,

package/dist/system-prompt.js

@@ -98,11 +98,20 @@ export function renderContextSection(context) {
     }
     return out;
 }
-export function buildSystemPrompt({ workdir, tools, gitContext = null, locale = 'ru', attachments = [], context = null, selfImprovement = false, }) {
-    const t = translate(locale);
-    const toolDescriptions = tools
+// The tool list in the prompt is GENERATED from the ToolDefs (createTools),
+// never hand-written: a second copy drifts (the prompt promises a tool that
+// no longer exists, or misses one that was added). This is the single source
+// of truth for `### <Tool>` blocks; the prose that cannot be derived
+// ("Choosing the right tool", the call formats) stays hard-coded below.
+// Guarded by test/system-prompt-tools.test.ts.
+export function renderToolSection(tools) {
+    return tools
         .map((t2) => `### ${t2.name}\n${t2.description}\nParameters: ${JSON.stringify(t2.parameters)}`)
         .join('\n\n');
+}
+export function buildSystemPrompt({ workdir, tools, gitContext = null, locale = 'ru', attachments = [], context = null, selfImprovement = false, }) {
+    const t = translate(locale);
+    const toolDescriptions = renderToolSection(tools);
     const gitSection = gitContext
         ? `\n## Git context\n\n${gitContext}\n`
         : '\n## Git context\n\nNot a git repository (or git is not installed).\n';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zames_pro",
-  "version": "2.65.1",
-  "description": "Terminal coding agent that drives chat.deepseek.com through Playwright: reads and edits files, runs commands, commits to git.",
+  "version": "2.66.1",
+  "description": "Terminal coding agent that drives chat.deepseek.com through Playwright — no API key required. Reads and edits files, runs commands, commits to git, like Claude Code / Codex CLI.",
   "type": "module",
   "bin": {
     "zames": "dist/index.js"
@@ -10,6 +10,7 @@
     "dist",
     "scripts",
     "README.md",
+    "README.ru.md",
     "CHANGELOG.md",
     "LICENSE",
     "logo-small.jpg"
@@ -21,6 +22,7 @@
     "build": "node scripts/clean-dist.mjs && tsc -p tsconfig.build.json",
     "coverage:gate": "node scripts/coverage-gate.mjs",
     "changelog:draft": "tsx scripts/changelog-draft.mts",
+    "release": "tsx scripts/release.mts",
     "typecheck": "tsc --noEmit",
     "lint": "node scripts/eslint-ts6.mjs",
     "lint:fix": "node scripts/eslint-ts6.mjs --fix",
@@ -31,20 +33,28 @@
     "test:watch": "tsx --test --watch test/*.test.ts",
     "self-smoke": "tsx scripts/self-smoke.mjs",
     "render-demo": "node scripts/render-demo.mjs",
+    "build:readme": "tsx scripts/build-readme.mts",
     "postinstall": "node scripts/postinstall.mjs",
     "prepare": "husky"
   },
   "keywords": [
     "agent",
     "ai",
-    "deepseek",
-    "cli",
+    "ai-agent",
+    "ai-coding-assistant",
     "coding-agent",
+    "code-assistant",
+    "terminal-agent",
+    "deepseek",
+    "deepseek-chat",
     "claude-code",
     "codex",
+    "cli",
     "terminal",
     "playwright",
+    "browser-automation",
     "llm",
+    "no-api-key",
     "automation"
   ],
   "license": "MIT",

package/scripts/build-readme.mts

@@ -0,0 +1,129 @@
+// Assemble README.md and README.ru.md from two language sources.
+//
+// Why: npm renders exactly ONE readme per package (README.md in the root) and
+// has no language tabs, so a separate README.ru.md is invisible on the npm
+// page. But npm renders the readme with GitHub Flavored Markdown (via GitHub's
+// API), so a <details> block DOES work there -- and on GitHub too. We therefore
+// keep the English text on top and fold the other language into a collapsible
+// block at the bottom.
+//
+// The two sources (docs/readme.en.md, docs/readme.ru.md) are the single point
+// of edit for each language; this script wires the switcher and the collapsible
+// cross-language block so neither README has to be maintained by hand. The
+// generated files are committed; test/readme-built.test.ts re-runs buildReadmes()
+// and fails if they drift from the sources.
+//
+// Usage:  node scripts/build-readme.mjs   (or: npm run build:readme)
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const NL = String.fromCharCode(10)
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+export const SWITCHER = '<!-- SWITCHER -->'
+
+const REPO = 'https://github.com/Viqto0r/zames_pro/blob/master'
+const EN_SWITCH = [
+  '<p align="center">',
+  '  <strong>English</strong> | <a href="' +
+    REPO +
+    '/README.ru.md">Русский</a>',
+  '</p>',
+].join(NL)
+const RU_SWITCH = [
+  '<p align="center">',
+  '  <a href="' + REPO + '/README.md">English</a> | <strong>Русский</strong>',
+  '</p>',
+].join(NL)
+
+export function readSource(
+  rootDir: string,
+  name: string,
+): { head: string; body: string } {
+  const file = path.join(rootDir, 'docs', name)
+  const text = fs.readFileSync(file, 'utf-8')
+  const i = text.indexOf(SWITCHER)
+  if (i < 0) {
+    throw new Error(
+      file + ' has no ' + SWITCHER + ' marker (was it edited by hand?)',
+    )
+  }
+  return {
+    // Everything above the marker: logo, title, badges.
+    head: text.slice(0, i).replace(/\n+$/, ''),
+    // Everything below: the actual documentation.
+    body: text
+      .slice(i + SWITCHER.length)
+      .replace(/^\n+/, '')
+      .replace(/\n+$/, ''),
+  }
+}
+
+function details(summary: string, body: string): string {
+  return [
+    '<details>',
+    '<summary>' + summary + '</summary>',
+    '',
+    body,
+    '',
+    '</details>',
+  ].join(NL)
+}
+
+function assemble(opts: {
+  head: string
+  switchLine: string
+  body: string
+  foldSummary: string
+  foldBody: string
+}): string {
+  const { head, switchLine, body, foldSummary, foldBody } = opts
+  return [
+    head,
+    '',
+    switchLine,
+    '',
+    body,
+    '',
+    details(foldSummary, foldBody),
+    '',
+  ].join(NL)
+}
+
+// Returns the two generated readmes WITHOUT touching the disk, so a test can
+// compare them against the committed files.
+export function buildReadmes(rootDir: string): {
+  readmeEn: string
+  readmeRu: string
+} {
+  const en = readSource(rootDir, 'readme.en.md')
+  const ru = readSource(rootDir, 'readme.ru.md')
+  return {
+    readmeEn: assemble({
+      head: en.head,
+      switchLine: EN_SWITCH,
+      body: en.body,
+      foldSummary: '🇷🇺 Читать по-русски (Russian)',
+      foldBody: ru.body,
+    }),
+    readmeRu: assemble({
+      head: ru.head,
+      switchLine: RU_SWITCH,
+      body: ru.body,
+      foldSummary: '🇬🇧 Read in English',
+      foldBody: en.body,
+    }),
+  }
+}
+
+// Run only when invoked directly (not when imported by a test).
+const invoked =
+  process.argv[1] &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (invoked) {
+  const { readmeEn, readmeRu } = buildReadmes(root)
+  fs.writeFileSync(path.join(root, 'README.md'), readmeEn)
+  fs.writeFileSync(path.join(root, 'README.ru.md'), readmeRu)
+  console.log('build-readme: wrote README.md and README.ru.md')
+}