@aws/nx-plugin 1.0.0-rc.67 → 1.0.0-rc.68

package/src/migrations/latest/translate-script-whole-file-writes/migration.js

@@ -0,0 +1,103 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getProjects, joinPathFragments } from "@nx/devkit";
+import { TS_ASTRO_DOCS_GENERATOR_INFO } from "../../../ts/astro-docs/generator.js";
+import { insertViaGritQL, matchGritQL } from "../../../utils/ast.js";
+import { formatFilesInSubtree } from "../../../utils/format.js";
+import { isEsmWorkspace } from "../../../utils/module-format.js";
+import { getPackageManagerDisplayCommands } from "../../../utils/pkg-manager.js";
+/**
+ * Rewrite the docs translate script so it writes whole translated files.
+ *
+ * The script used to tell the agent to update an existing translation with
+ * `str_replace` edits. A replacement that did not match cleanly duplicated or
+ * spliced sections, and nothing checked the result, so the damage was committed.
+ * The rewrite also fixes incremental runs, which never matched a changed file in
+ * a generated workspace, and raises the Bedrock socket timeout that made every
+ * large file fail.
+ *
+ * Most of the script changed, so it is rewritten a declaration at a time. Each
+ * pattern in `grit/` matches one declaration as a previous release wrote it and
+ * rewrites it to a placeholder, which `insertViaGritQL` swaps for today's version
+ * from `files/`. Routing the replacement through a placeholder keeps it out of the
+ * pattern: the script is full of template literals, and a GritQL snippet
+ * containing a backtick cannot be parsed.
+ *
+ * Each pattern recognises its declaration by name *and* by statements the released
+ * body contained, so a declaration the user has edited no longer matches. The
+ * rewrite is all or nothing — every pattern must match before anything is written
+ * — so an edited script keeps its whole file and is reported through `nextSteps`
+ * rather than being half-rewritten from two different versions.
+ */ /**
+ * The declarations that changed, in the order they appear in the script. Each name
+ * pairs a `grit/<name>.grit` pattern matching its previous form with a
+ * `files/<name>.ts.fixture` holding its replacement, which carries any new
+ * declarations that follow it.
+ *
+ * `grit/already-migrated.grit` stands apart: it recognises today's script rather
+ * than rewriting anything.
+ */ const REWRITES = [
+    'project-root',
+    'config-path',
+    'file-to-translate',
+    'log',
+    'get-files-to-translate',
+    'build-system-prompt',
+    'build-user-prompt',
+    'translate-file-for-language',
+    'run-with-concurrency',
+    'main',
+    'main-call'
+];
+/** A leading block comment, which GritQL does not match. */ const HEADER_COMMENT = /^\/\*\*[\s\S]*?\*\/\n/;
+const readGritPattern = (name)=>`language js\n${readFileSync(join(import.meta.dirname, 'grit', `${name}.grit`), 'utf-8').trim()}`;
+const readReplacement = (name)=>readFileSync(join(import.meta.dirname, 'files', `${name}.ts.fixture`), 'utf-8');
+/** Fills in the values the generator interpolates when it vends the script. */ const render = (tree, source, fullyQualifiedName)=>source.replace(/<% if \(esm\) \{ %>(.*?)<% \} else \{ %>(.*?)<% \} %>/g, isEsmWorkspace(tree) ? '$1' : '$2').replace(/<%= pkgMgrCmd %>/g, getPackageManagerDisplayCommands().exec).replace(/<%= fullyQualifiedName %>/g, fullyQualifiedName);
+const editedNextStep = (projectName)=>`${projectName}: its scripts/translate.ts has been customised, so it was left as it is. The script now writes each translation as a whole file rather than editing it in place — see https://awslabs.github.io/nx-plugin-for-aws/guides/astro-docs/ for the version it expects.`;
+export default async function migration(tree) {
+    const nextSteps = [];
+    for (const [name, project] of getProjects(tree)){
+        const metadata = project.metadata;
+        if (metadata?.generator !== TS_ASTRO_DOCS_GENERATOR_INFO.id) {
+            continue;
+        }
+        // Absent when the docs site was generated with --noTranslation.
+        const scriptPath = joinPathFragments(project.root, 'scripts', 'translate.ts');
+        if (!tree.exists(scriptPath)) {
+            continue;
+        }
+        // Already migrated: matched by a declaration only today's script has, so a
+        // second run is a no-op rather than a rewrite.
+        if (await matchGritQL(tree, scriptPath, readGritPattern('already-migrated'))) {
+            continue;
+        }
+        // All or nothing: every declaration must still be the one a release vended,
+        // so a partly edited script is never left half-rewritten.
+        const matches = await Promise.all(REWRITES.map((rewrite)=>matchGritQL(tree, scriptPath, readGritPattern(rewrite))));
+        if (!matches.every(Boolean)) {
+            nextSteps.push(editedNextStep(name));
+            continue;
+        }
+        // The header is a leading comment, which GritQL does not reach. Anchored to
+        // the start of the file so the replacement cannot match anything else.
+        tree.write(scriptPath, (tree.read(scriptPath, 'utf-8') ?? '').replace(HEADER_COMMENT, render(tree, readReplacement('header'), name)));
+        // The first release resolved paths from `__dirname` directly, with no
+        // `SCRIPTS_DIR` for the rewrites below to build on.
+        const script = tree.read(scriptPath, 'utf-8') ?? '';
+        if (!/^const SCRIPTS_DIR /m.test(script)) {
+            tree.write(scriptPath, script.replace(/^const PROJECT_ROOT /m, `${render(tree, readReplacement('scripts-dir'), name).trimEnd()}\nconst PROJECT_ROOT `));
+        }
+        for (const rewrite of REWRITES){
+            await insertViaGritQL(tree, scriptPath, readGritPattern(rewrite), render(tree, readReplacement(rewrite), name).trimEnd());
+        }
+    }
+    await formatFilesInSubtree(tree);
+    return {
+        nextSteps
+    };
+}
+
+//# sourceMappingURL=migration.js.map

package/src/migrations/latest/translate-script-whole-file-writes/migration.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../packages/nx-plugin/src/migrations/latest/translate-script-whole-file-writes/migration.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport { readFileSync } from 'node:fs';\nimport { join } from 'node:path';\nimport {\n  getProjects,\n  joinPathFragments,\n  type MigrationReturnObject,\n  type Tree,\n} from '@nx/devkit';\nimport { TS_ASTRO_DOCS_GENERATOR_INFO } from '../../../ts/astro-docs/generator';\nimport { insertViaGritQL, matchGritQL } from '../../../utils/ast';\nimport { formatFilesInSubtree } from '../../../utils/format';\nimport { isEsmWorkspace } from '../../../utils/module-format';\nimport { getPackageManagerDisplayCommands } from '../../../utils/pkg-manager';\n\n/**\n * Rewrite the docs translate script so it writes whole translated files.\n *\n * The script used to tell the agent to update an existing translation with\n * `str_replace` edits. A replacement that did not match cleanly duplicated or\n * spliced sections, and nothing checked the result, so the damage was committed.\n * The rewrite also fixes incremental runs, which never matched a changed file in\n * a generated workspace, and raises the Bedrock socket timeout that made every\n * large file fail.\n *\n * Most of the script changed, so it is rewritten a declaration at a time. Each\n * pattern in `grit/` matches one declaration as a previous release wrote it and\n * rewrites it to a placeholder, which `insertViaGritQL` swaps for today's version\n * from `files/`. Routing the replacement through a placeholder keeps it out of the\n * pattern: the script is full of template literals, and a GritQL snippet\n * containing a backtick cannot be parsed.\n *\n * Each pattern recognises its declaration by name *and* by statements the released\n * body contained, so a declaration the user has edited no longer matches. The\n * rewrite is all or nothing — every pattern must match before anything is written\n * — so an edited script keeps its whole file and is reported through `nextSteps`\n * rather than being half-rewritten from two different versions.\n */\n\n/**\n * The declarations that changed, in the order they appear in the script. Each name\n * pairs a `grit/<name>.grit` pattern matching its previous form with a\n * `files/<name>.ts.fixture` holding its replacement, which carries any new\n * declarations that follow it.\n *\n * `grit/already-migrated.grit` stands apart: it recognises today's script rather\n * than rewriting anything.\n */\nconst REWRITES = [\n  'project-root',\n  'config-path',\n  'file-to-translate',\n  'log',\n  'get-files-to-translate',\n  'build-system-prompt',\n  'build-user-prompt',\n  'translate-file-for-language',\n  'run-with-concurrency',\n  'main',\n  'main-call',\n] as const;\n\n/** A leading block comment, which GritQL does not match. */\nconst HEADER_COMMENT = /^\\/\\*\\*[\\s\\S]*?\\*\\/\\n/;\n\nconst readGritPattern = (name: string): string =>\n  `language js\\n${readFileSync(join(import.meta.dirname, 'grit', `${name}.grit`), 'utf-8').trim()}`;\n\nconst readReplacement = (name: string): string =>\n  readFileSync(\n    join(import.meta.dirname, 'files', `${name}.ts.fixture`),\n    'utf-8',\n  );\n\n/** Fills in the values the generator interpolates when it vends the script. */\nconst render = (\n  tree: Tree,\n  source: string,\n  fullyQualifiedName: string,\n): string =>\n  source\n    .replace(\n      /<% if \\(esm\\) \\{ %>(.*?)<% \\} else \\{ %>(.*?)<% \\} %>/g,\n      isEsmWorkspace(tree) ? '$1' : '$2',\n    )\n    .replace(/<%= pkgMgrCmd %>/g, getPackageManagerDisplayCommands().exec)\n    .replace(/<%= fullyQualifiedName %>/g, fullyQualifiedName);\n\nconst editedNextStep = (projectName: string): string =>\n  `${projectName}: its scripts/translate.ts has been customised, so it was left as it is. The script now writes each translation as a whole file rather than editing it in place — see https://awslabs.github.io/nx-plugin-for-aws/guides/astro-docs/ for the version it expects.`;\n\nexport default async function migration(\n  tree: Tree,\n): Promise<MigrationReturnObject> {\n  const nextSteps: string[] = [];\n\n  for (const [name, project] of getProjects(tree)) {\n    const metadata = project.metadata as { generator?: string } | undefined;\n    if (metadata?.generator !== TS_ASTRO_DOCS_GENERATOR_INFO.id) {\n      continue;\n    }\n\n    // Absent when the docs site was generated with --noTranslation.\n    const scriptPath = joinPathFragments(\n      project.root,\n      'scripts',\n      'translate.ts',\n    );\n    if (!tree.exists(scriptPath)) {\n      continue;\n    }\n\n    // Already migrated: matched by a declaration only today's script has, so a\n    // second run is a no-op rather than a rewrite.\n    if (\n      await matchGritQL(tree, scriptPath, readGritPattern('already-migrated'))\n    ) {\n      continue;\n    }\n\n    // All or nothing: every declaration must still be the one a release vended,\n    // so a partly edited script is never left half-rewritten.\n    const matches = await Promise.all(\n      REWRITES.map((rewrite) =>\n        matchGritQL(tree, scriptPath, readGritPattern(rewrite)),\n      ),\n    );\n    if (!matches.every(Boolean)) {\n      nextSteps.push(editedNextStep(name));\n      continue;\n    }\n\n    // The header is a leading comment, which GritQL does not reach. Anchored to\n    // the start of the file so the replacement cannot match anything else.\n    tree.write(\n      scriptPath,\n      (tree.read(scriptPath, 'utf-8') ?? '').replace(\n        HEADER_COMMENT,\n        render(tree, readReplacement('header'), name),\n      ),\n    );\n\n    // The first release resolved paths from `__dirname` directly, with no\n    // `SCRIPTS_DIR` for the rewrites below to build on.\n    const script = tree.read(scriptPath, 'utf-8') ?? '';\n    if (!/^const SCRIPTS_DIR /m.test(script)) {\n      tree.write(\n        scriptPath,\n        script.replace(\n          /^const PROJECT_ROOT /m,\n          `${render(tree, readReplacement('scripts-dir'), name).trimEnd()}\\nconst PROJECT_ROOT `,\n        ),\n      );\n    }\n\n    for (const rewrite of REWRITES) {\n      await insertViaGritQL(\n        tree,\n        scriptPath,\n        readGritPattern(rewrite),\n        render(tree, readReplacement(rewrite), name).trimEnd(),\n      );\n    }\n  }\n\n  await formatFilesInSubtree(tree);\n\n  return { nextSteps };\n}\n"],"names":["readFileSync","join","getProjects","joinPathFragments","TS_ASTRO_DOCS_GENERATOR_INFO","insertViaGritQL","matchGritQL","formatFilesInSubtree","isEsmWorkspace","getPackageManagerDisplayCommands","REWRITES","HEADER_COMMENT","readGritPattern","name","dirname","trim","readReplacement","render","tree","source","fullyQualifiedName","replace","exec","editedNextStep","projectName","migration","nextSteps","project","metadata","generator","id","scriptPath","root","exists","matches","Promise","all","map","rewrite","every","Boolean","push","write","read","script","test","trimEnd"],"mappings":"AAAA;;;CAGC,GACD,SAASA,YAAY,QAAQ,UAAU;AACvC,SAASC,IAAI,QAAQ,YAAY;AACjC,SACEC,WAAW,EACXC,iBAAiB,QAGZ,aAAa;AACpB,SAASC,4BAA4B,QAAQ,sCAAmC;AAChF,SAASC,eAAe,EAAEC,WAAW,QAAQ,wBAAqB;AAClE,SAASC,oBAAoB,QAAQ,2BAAwB;AAC7D,SAASC,cAAc,QAAQ,kCAA+B;AAC9D,SAASC,gCAAgC,QAAQ,gCAA6B;AAE9E;;;;;;;;;;;;;;;;;;;;;;CAsBC,GAED;;;;;;;;CAQC,GACD,MAAMC,WAAW;IACf;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD;AAED,0DAA0D,GAC1D,MAAMC,iBAAiB;AAEvB,MAAMC,kBAAkB,CAACC,OACvB,CAAC,aAAa,EAAEb,aAAaC,KAAK,YAAYa,OAAO,EAAE,QAAQ,GAAGD,KAAK,KAAK,CAAC,GAAG,SAASE,IAAI,IAAI;AAEnG,MAAMC,kBAAkB,CAACH,OACvBb,aACEC,KAAK,YAAYa,OAAO,EAAE,SAAS,GAAGD,KAAK,WAAW,CAAC,GACvD;AAGJ,6EAA6E,GAC7E,MAAMI,SAAS,CACbC,MACAC,QACAC,qBAEAD,OACGE,OAAO,CACN,0DACAb,eAAeU,QAAQ,OAAO,MAE/BG,OAAO,CAAC,qBAAqBZ,mCAAmCa,IAAI,EACpED,OAAO,CAAC,8BAA8BD;AAE3C,MAAMG,iBAAiB,CAACC,cACtB,GAAGA,YAAY,gQAAgQ,CAAC;AAElR,eAAe,eAAeC,UAC5BP,IAAU;IAEV,MAAMQ,YAAsB,EAAE;IAE9B,KAAK,MAAM,CAACb,MAAMc,QAAQ,IAAIzB,YAAYgB,MAAO;QAC/C,MAAMU,WAAWD,QAAQC,QAAQ;QACjC,IAAIA,UAAUC,cAAczB,6BAA6B0B,EAAE,EAAE;YAC3D;QACF;QAEA,gEAAgE;QAChE,MAAMC,aAAa5B,kBACjBwB,QAAQK,IAAI,EACZ,WACA;QAEF,IAAI,CAACd,KAAKe,MAAM,CAACF,aAAa;YAC5B;QACF;QAEA,2EAA2E;QAC3E,+CAA+C;QAC/C,IACE,MAAMzB,YAAYY,MAAMa,YAAYnB,gBAAgB,sBACpD;YACA;QACF;QAEA,4EAA4E;QAC5E,0DAA0D;QAC1D,MAAMsB,UAAU,MAAMC,QAAQC,GAAG,CAC/B1B,SAAS2B,GAAG,CAAC,CAACC,UACZhC,YAAYY,MAAMa,YAAYnB,gBAAgB0B;QAGlD,IAAI,CAACJ,QAAQK,KAAK,CAACC,UAAU;YAC3Bd,UAAUe,IAAI,CAAClB,eAAeV;YAC9B;QACF;QAEA,4EAA4E;QAC5E,uEAAuE;QACvEK,KAAKwB,KAAK,CACRX,YACA,AAACb,CAAAA,KAAKyB,IAAI,CAACZ,YAAY,YAAY,EAAC,EAAGV,OAAO,CAC5CV,gBACAM,OAAOC,MAAMF,gBAAgB,WAAWH;QAI5C,sEAAsE;QACtE,oDAAoD;QACpD,MAAM+B,SAAS1B,KAAKyB,IAAI,CAACZ,YAAY,YAAY;QACjD,IAAI,CAAC,uBAAuBc,IAAI,CAACD,SAAS;YACxC1B,KAAKwB,KAAK,CACRX,YACAa,OAAOvB,OAAO,CACZ,yBACA,GAAGJ,OAAOC,MAAMF,gBAAgB,gBAAgBH,MAAMiC,OAAO,GAAG,qBAAqB,CAAC;QAG5F;QAEA,KAAK,MAAMR,WAAW5B,SAAU;YAC9B,MAAML,gBACJa,MACAa,YACAnB,gBAAgB0B,UAChBrB,OAAOC,MAAMF,gBAAgBsB,UAAUzB,MAAMiC,OAAO;QAExD;IACF;IAEA,MAAMvC,qBAAqBW;IAE3B,OAAO;QAAEQ;IAAU;AACrB"}

package/src/migrations/latest/translate-script-whole-file-writes/test-fixtures/released-script-first.ts.fixture

@@ -0,0 +1,430 @@
+/**
+ * Translate documentation files using a Strands agent powered by Claude on
+ * Amazon Bedrock.
+ *
+ * Configuration lives in ./translate.config.json (sibling to this file).
+ * Run from the project root:
+ *
+ *   <%= pkgMgrCmd %> nx translate <%= fullyQualifiedName %> -- --all
+ *   <%= pkgMgrCmd %> nx translate <%= fullyQualifiedName %>            # only files changed since last translate commit
+ *
+ * The driver gathers the set of changed source docs + their git diffs and hands
+ * them to an agent that has read/write access (scoped to the docs directory)
+ * via a wrapped version of the built-in `fileEditor` tool. The agent decides
+ * how to translate each file and writes the output itself.
+ */
+import { Command } from 'commander';
+import fs from 'fs-extra';
+import path from 'path';
+import { simpleGit } from 'simple-git';
+import glob from 'fast-glob';
+import { Agent, BeforeToolCallEvent } from '@strands-agents/sdk';
+import { BedrockModel } from '@strands-agents/sdk/models/bedrock';
+import { fileEditor } from '@strands-agents/sdk/vended-tools/file-editor';
+
+interface TranslateConfig {
+  sourceLanguage: string;
+  targetLanguages: string[];
+  docsDir: string;
+  include: string[];
+  exclude: string[];
+  modelId: string;
+  awsRegion: string;
+  /**
+   * Maximum number of (file x language) translations running in parallel. Each one
+   * is a fresh agent invocation, so this caps concurrent Bedrock requests.
+   * Defaults to 5 when omitted.
+   */
+  concurrency?: number;
+  /**
+   * Commit message marker used to identify previous translation commits, so
+   * incremental runs only re-translate changes since the last translation.
+   * Defaults to "docs: update translations".
+   */
+  translationCommitMessage?: string;
+}
+
+const PROJECT_ROOT = path.resolve(__dirname, '..');
+const CONFIG_PATH = path.resolve(__dirname, 'translate.config.json');
+const config: TranslateConfig = JSON.parse(
+  fs.readFileSync(CONFIG_PATH, 'utf-8'),
+);
+const DOCS_DIR = path.resolve(PROJECT_ROOT, config.docsDir);
+const TRANSLATION_COMMIT_MESSAGE =
+  config.translationCommitMessage ?? 'docs: update translations';
+
+/**
+ * Reject any `fileEditor` call whose `path` resolves outside the configured
+ * docs directory. Runs as a `BeforeToolCallEvent` hook so we reuse the
+ * built-in tool's schema/description verbatim — nothing else uses fileEditor in
+ * this script, so the check is unconditional.
+ */
+function rejectOutsideDocsDir(event: BeforeToolCallEvent): void {
+  if (event.toolUse.name !== 'fileEditor') return;
+  const input = event.toolUse.input as { path?: unknown };
+  if (typeof input.path !== 'string') return;
+  const resolved = path.resolve(input.path);
+  const docsDirWithSep = DOCS_DIR.endsWith(path.sep)
+    ? DOCS_DIR
+    : DOCS_DIR + path.sep;
+  if (resolved !== DOCS_DIR && !resolved.startsWith(docsDirWithSep)) {
+    event.cancel = `Path ${resolved} is outside the docs directory (${DOCS_DIR}); refusing access.`;
+  }
+}
+
+interface FileToTranslate {
+  relativePath: string;
+  sourceAbsPath: string;
+  sourceContent: string;
+  /** Empty when this is a newly-added file. */
+  diff: string;
+}
+
+const program = new Command();
+program
+  .name('translate')
+  .description('Translate documentation files using a Strands agent')
+  .option('-a, --all', 'Translate all source documentation files')
+  .option(
+    '-l, --languages <languages>',
+    'Comma-separated list of target languages (overrides translate.config.json)',
+  )
+  .option(
+    '-d, --dry-run',
+    'Show what would be translated without invoking the agent',
+  )
+  .option('-v, --verbose', 'Show verbose output')
+  .parse(process.argv);
+const options = program.opts();
+
+const log = {
+  info: (m: string) => console.log(`[translate] ${m}`),
+  warn: (m: string) => console.warn(`[translate] ${m}`),
+  error: (m: string) => console.error(`[translate] ERROR ${m}`),
+  verbose: (m: string) =>
+    options.verbose && console.log(`[translate] ${m}`),
+};
+
+/**
+ * Gather the set of source-language files to translate, with their diffs.
+ */
+async function getFilesToTranslate(): Promise<FileToTranslate[]> {
+  const sourceLangRoot = `${DOCS_DIR}/${config.sourceLanguage}`;
+  const includePatterns = config.include.map(
+    (p) => `${sourceLangRoot}/${p}`,
+  );
+  const ignorePatterns = config.exclude.map(
+    (p) => `${sourceLangRoot}/${p}`,
+  );
+
+  if (options.all) {
+    log.info('Translating all source documentation files');
+    const files = await glob(includePatterns, { ignore: ignorePatterns });
+    return Promise.all(
+      files.map(async (file) => ({
+        relativePath: path.relative(sourceLangRoot, file),
+        sourceAbsPath: file,
+        sourceContent: await fs.readFile(file, 'utf-8'),
+        diff: '',
+      })),
+    );
+  }
+
+  const git = simpleGit();
+
+  let currentBranch: string;
+  let mainBranch: string;
+  if (process.env.GITHUB_HEAD_REF) {
+    currentBranch = `origin/${process.env.GITHUB_HEAD_REF}`;
+    mainBranch = 'origin/main';
+  } else {
+    currentBranch = (await git.branch()).current;
+    mainBranch = 'main';
+  }
+
+  try {
+    await git.raw(['rev-parse', '--verify', mainBranch]);
+  } catch {
+    log.warn(
+      `Could not find "${mainBranch}"; falling back to --all behaviour`,
+    );
+    options.all = true;
+    return getFilesToTranslate();
+  }
+
+  const mergeBase = (
+    await git.raw(['merge-base', mainBranch, currentBranch])
+  ).trim();
+
+  const translationCommits = (
+    await git.log({ from: mergeBase, to: 'HEAD' })
+  ).all.filter((c) => c.message.includes(TRANSLATION_COMMIT_MESSAGE));
+
+  const baseCommit =
+    translationCommits.length > 0
+      ? translationCommits[0].hash
+      : mergeBase;
+
+  log.info(
+    translationCommits.length > 0
+      ? `Detecting changed files since last translation commit ${baseCommit.substring(0, 7)}`
+      : `Detecting changed files since branch creation ${baseCommit.substring(0, 7)}`,
+  );
+
+  const diffNames = (
+    await git.diff([
+      `${baseCommit}..HEAD`,
+      '--name-only',
+      '--diff-filter=d',
+    ])
+  )
+    .split('\n')
+    .filter(Boolean);
+
+  const { files: uncommitted } = await git.status();
+  const uncommittedNames = uncommitted.map((f) => f.path);
+
+  const allCandidates = [
+    ...new Set([...diffNames, ...uncommittedNames]),
+  ].map((p) => path.resolve(process.cwd(), p));
+
+  // Filter to files inside the source language dir that match include/exclude
+  const includedGlob = await glob(includePatterns, {
+    ignore: ignorePatterns,
+  });
+  const includedSet = new Set(includedGlob.map((p) => path.resolve(p)));
+
+  const changed = allCandidates.filter((abs) => includedSet.has(abs));
+
+  if (changed.length === 0) {
+    log.warn('No changed source documentation files detected');
+    return [];
+  }
+
+  return Promise.all(
+    changed.map(async (file) => {
+      const sourceContent = await fs.readFile(file, 'utf-8');
+      let diff = '';
+      try {
+        diff = await git.diff([
+          `${baseCommit}..HEAD`,
+          '--',
+          path.relative(process.cwd(), file),
+        ]);
+      } catch {
+        // treat as new file
+      }
+      return {
+        relativePath: path.relative(sourceLangRoot, file),
+        sourceAbsPath: file,
+        sourceContent,
+        diff,
+      };
+    }),
+  );
+}
+
+function buildSystemPrompt(targetLang: string): string {
+  return `You are an expert technical-documentation translator. Your job is to translate a single MDX documentation file from the source locale \`${config.sourceLanguage}\` into the target locale \`${targetLang}\`.
+
+Both values are locale codes (e.g. ISO 639-1 / BCP-47 style, or common short forms like \`jp\`, \`zh\`, \`pt\`). Interpret them yourself and translate naturally into the language they identify. If a code is ambiguous, prefer the most widely used written form.
+
+You have one tool available: \`fileEditor\`. Use it to:
+- Read the source file (\`command: "view"\`). For large files you can read a portion at a time using \`view_range\`, then request the next range.
+- Read the existing translation if one is provided (\`command: "view"\`).
+- Write the translated file (\`command: "create"\` — it overwrites).
+
+Translation rules:
+1. Translate natural-language prose into the target language. Keep technical accuracy.
+2. DO NOT translate:
+   - Code blocks and inline code (text inside backticks)
+   - URLs, link paths, and HTML/JSX/MDX tag names and attributes
+   - \`import\` statements, component names, and frontmatter keys
+   - Proper names of people, products, or AWS services
+3. Preserve every aspect of the MDX structure exactly: frontmatter delimiters, headings, lists, code blocks, MDX components, JSX, whitespace, blank lines.
+4. For frontmatter:
+   - Translate only string values for the \`title\` and \`description\` keys.
+   - Leave \`date\`, \`authors\`, \`template\`, \`slug\`, and all other keys untouched.
+5. If any localised link paths embed the source locale (e.g. \`/${config.sourceLanguage}/foo\`), rewrite them to the target locale (\`/${targetLang}/foo\`).
+6. Efficiency rule: if an existing translation is provided AND a diff is provided, reuse the existing translation verbatim for any section of the document that is NOT touched by the diff. Only retranslate sections that actually changed. Still emit the complete final file.
+7. If no existing translation exists, translate the whole file.
+8. Never wrap the file output in triple backticks.
+9. Always use absolute paths with \`fileEditor\`.
+
+When the translated file has been written, reply with a one-line summary and stop.`;
+}
+
+function buildUserPrompt(
+  file: FileToTranslate,
+  targetLang: string,
+): string {
+  const targetLangRoot = path.join(DOCS_DIR, targetLang);
+  const targetAbsPath = path.join(targetLangRoot, file.relativePath);
+  const existingTranslationExists = fs.existsSync(targetAbsPath);
+
+  const diffBlock = file.diff
+    ? `Git diff showing what changed in the source since the last translation:\n\`\`\`diff\n${file.diff.slice(0, 40_000)}\n\`\`\``
+    : 'There is no prior diff for this file — treat it as new content and translate in full.';
+
+  const existingBlock = existingTranslationExists
+    ? `An existing translation for locale \`${targetLang}\` already lives at:\n  \`${targetAbsPath}\`\nRead it with \`fileEditor\` (\`command: "view"\`) before writing so you can reuse any sections that have not changed.`
+    : `No existing translation exists yet — you will create it fresh.`;
+
+  return `Translate one file from source locale \`${config.sourceLanguage}\` into target locale \`${targetLang}\`.
+
+- Source file (read from here): \`${file.sourceAbsPath}\`
+- Target file (write the translation here, absolute path): \`${targetAbsPath}\`
+
+${existingBlock}
+
+${diffBlock}
+
+Steps:
+1. Read the source file. If it is long, read it in slices using \`view_range\`.
+2. If an existing translation is present, read it first so you can reuse unchanged sections.
+3. Write the full translated file to the target path using \`command: "create"\`.
+4. Reply with a single short confirmation line.`;
+}
+
+async function translateFileForLanguage(
+  file: FileToTranslate,
+  targetLang: string,
+): Promise<void> {
+  const targetAbsPath = path.join(
+    DOCS_DIR,
+    targetLang,
+    file.relativePath,
+  );
+  const beforeMtimeMs = fs.existsSync(targetAbsPath)
+    ? (await fs.stat(targetAbsPath)).mtimeMs
+    : 0;
+
+  const agent = new Agent({
+    model: new BedrockModel({
+      modelId: config.modelId,
+      region: process.env.AWS_REGION ?? config.awsRegion,
+      maxTokens: 64_000,
+      temperature: 0.2,
+    }),
+    systemPrompt: buildSystemPrompt(targetLang),
+    tools: [fileEditor],
+    printer: !!options.verbose,
+  });
+  agent.addHook(BeforeToolCallEvent, rejectOutsideDocsDir);
+
+  const result = await agent.invoke(buildUserPrompt(file, targetLang));
+
+  if (result.stopReason !== 'endTurn') {
+    log.warn(
+      `agent stopped with reason=${result.stopReason} while translating ${file.relativePath} → ${targetLang} — inspect output above`,
+    );
+  }
+
+  // Sanity check: the target file should now exist and have been written during this run.
+  if (!fs.existsSync(targetAbsPath)) {
+    throw new Error(
+      `agent did not write target file ${targetAbsPath} for ${file.relativePath} → ${targetLang}`,
+    );
+  }
+  const afterMtimeMs = (await fs.stat(targetAbsPath)).mtimeMs;
+  if (afterMtimeMs <= beforeMtimeMs) {
+    log.warn(
+      `target ${file.relativePath} → ${targetLang} was not updated (mtime unchanged) — the agent may have decided no change was needed`,
+    );
+  }
+}
+
+/**
+ * Simple concurrency-limited runner.
+ */
+async function runWithConcurrency<T>(
+  tasks: Array<() => Promise<T>>,
+  limit: number,
+): Promise<T[]> {
+  const results: T[] = new Array(tasks.length);
+  let next = 0;
+  async function worker() {
+    while (true) {
+      const i = next++;
+      if (i >= tasks.length) return;
+      results[i] = await tasks[i]();
+    }
+  }
+  const workers = Array.from({ length: Math.min(limit, tasks.length) }, worker);
+  await Promise.all(workers);
+  return results;
+}
+
+async function main() {
+  const requestedLanguages: string[] = options.languages
+    ? options.languages
+        .split(',')
+        .map((l: string) => l.trim())
+        .filter(Boolean)
+    : config.targetLanguages;
+
+  const targetLanguages = requestedLanguages.filter(
+    (l) => l !== config.sourceLanguage,
+  );
+
+  if (targetLanguages.length === 0) {
+    log.error('No target languages configured');
+    process.exit(1);
+  }
+
+  log.info(`Source: ${config.sourceLanguage}`);
+  log.info(`Targets: ${targetLanguages.join(', ')}`);
+
+  const files = await getFilesToTranslate();
+
+  if (files.length === 0) {
+    log.info('Nothing to translate.');
+    return;
+  }
+
+  log.info(`Files to translate: ${files.length}`);
+  for (const f of files) {
+    log.verbose(
+      `  - ${f.relativePath}${f.diff ? ' (changed)' : ' (full)'}`,
+    );
+  }
+
+  if (options.dryRun) {
+    for (const lang of targetLanguages) {
+      for (const f of files) {
+        log.info(`[dry-run] would translate ${f.relativePath} → ${lang}`);
+      }
+    }
+    log.info('Done (dry-run).');
+    return;
+  }
+
+  // Build one task per (file × target language) — each is a fresh agent invocation,
+  // so context windows stay small no matter how big the docs site is.
+  const tasks = targetLanguages.flatMap((lang) =>
+    files.map((file) => async () => {
+      log.info(`  ${file.relativePath} → ${lang}`);
+      try {
+        await translateFileForLanguage(file, lang);
+      } catch (err) {
+        log.error(
+          `${file.relativePath} → ${lang}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+        throw err;
+      }
+    }),
+  );
+
+  const concurrency = Math.max(1, config.concurrency ?? 5);
+  log.info(
+    `Running ${tasks.length} translation(s) with concurrency=${concurrency}`,
+  );
+  await runWithConcurrency(tasks, concurrency);
+
+  log.info('Done.');
+}
+
+main().catch((err) => {
+  log.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});