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

package/src/agentcore-harness/generator.js

@@ -0,0 +1,158 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { addProjectConfiguration, generateFiles, joinPathFragments, OverwriteStrategy, updateProjectConfiguration } from "@nx/devkit";
+import { addTsDependencies } from "../utils/add-dependencies.js";
+import { addAgentCoreHarnessInfra } from "../utils/agent-core-constructs/agent-core-constructs.js";
+import { declareDependencies, ownedElsewhere } from "../utils/declared-dependencies.js";
+import { formatFilesInSubtree } from "../utils/format.js";
+import { resolveIac } from "../utils/iac.js";
+import { installDependencies } from "../utils/install.js";
+import { addGeneratorMetricsIfApplicable } from "../utils/metrics.js";
+import { kebabCase, toClassName } from "../utils/names.js";
+import { getNpmScopePrefix } from "../utils/npm-scope.js";
+import { addGeneratorMetadata, getGeneratorInfo, projectExists, readProjectConfigurationUnqualified } from "../utils/nx.js";
+import { SHARED_CONSTRUCTS_DEPENDENCIES, sharedConstructsGenerator } from "../utils/shared-constructs.js";
+// scripts/chat.ts needs all of these whatever the infrastructure choice, so no
+// entry is conditional. The harness project holds no manifest of its own, so
+// every entry is declared against the workspace root.
+export const DEPENDENCIES = declareDependencies()({
+    ts: [
+        {
+            name: '@aws-sdk/client-bedrock-agentcore',
+            root: true
+        },
+        {
+            name: '@aws-sdk/client-appconfigdata',
+            root: true
+        },
+        {
+            name: '@aws-lambda-powertools/parameters',
+            root: true
+        },
+        {
+            name: 'agent-chat-cli',
+            root: true
+        },
+        // tsx runs the chat script via the `chat` target; both are shared tooling.
+        {
+            name: '@types/node',
+            dev: true,
+            root: true
+        },
+        {
+            name: 'tsx',
+            dev: true,
+            root: true
+        },
+        ...ownedElsewhere(SHARED_CONSTRUCTS_DEPENDENCIES)
+    ]
+});
+export const AGENTCORE_HARNESS_GENERATOR_INFO = getGeneratorInfo(import.meta.filename);
+export const agentcoreHarnessGenerator = async (tree, options)=>{
+    const nameKebabCase = kebabCase(options.name);
+    const nameClassName = toClassName(nameKebabCase);
+    const parentDir = options.directory ?? 'packages';
+    const subDir = options.subDirectory ?? nameKebabCase;
+    const projectRoot = joinPathFragments(parentDir, subDir);
+    const fullyQualifiedProjectName = `${getNpmScopePrefix(tree)}${nameKebabCase}`;
+    const infra = options.infra ?? 'agentcore';
+    // AgentCore harness names must start with an ASCII letter and stay within 40
+    // characters once the "_<8 hex>" suffix is appended, so cap the prefix at 31.
+    // toClassName prefixes `_` (not a letter) for digit-leading names.
+    const harnessNamePrefix = (/^[A-Za-z]/.test(nameClassName) ? nameClassName : `H${nameClassName}`).slice(0, 31);
+    // Reuse an existing project configuration; create it otherwise.
+    let project;
+    if (projectExists(tree, fullyQualifiedProjectName)) {
+        project = readProjectConfigurationUnqualified(tree, fullyQualifiedProjectName);
+    } else {
+        addProjectConfiguration(tree, fullyQualifiedProjectName, {
+            name: fullyQualifiedProjectName,
+            root: projectRoot,
+            projectType: 'application',
+            sourceRoot: projectRoot,
+            tags: [],
+            targets: {},
+            metadata: {
+                generator: AGENTCORE_HARNESS_GENERATOR_INFO.id
+            }
+        });
+        project = readProjectConfigurationUnqualified(tree, fullyQualifiedProjectName);
+    }
+    // `chat` runs the vended chat script against the deployed Harness. Re-run:
+    // keep an existing target so user edits survive.
+    project.targets ??= {};
+    project.targets['chat'] ??= {
+        executor: 'nx:run-commands',
+        options: {
+            commands: [
+                'tsx ./scripts/chat.ts'
+            ],
+            cwd: '{projectRoot}'
+        }
+    };
+    updateProjectConfiguration(tree, project.name, project);
+    generateFiles(tree, joinPathFragments(import.meta.dirname, 'files', 'project'), projectRoot, {
+        nameClassName,
+        nameKebabCase,
+        fullyQualifiedName: fullyQualifiedProjectName
+    }, {
+        overwriteStrategy: OverwriteStrategy.KeepExisting
+    });
+    // Resolved before the metadata write because the recorded value is what the
+    // declaration's predicates read; undefined when no infrastructure is written,
+    // in which case neither provider's packages were added.
+    const iac = infra === 'agentcore' ? await resolveIac(tree, options.iac) : undefined;
+    // Record only what cannot drift once the user owns the generated
+    // infrastructure: the project identity, its runtime config key, its auth mode
+    // and which provider's infrastructure was written.
+    const metadata = {
+        name: nameKebabCase,
+        rc: nameClassName,
+        auth: 'iam',
+        ...iac ? {
+            iac
+        } : {}
+    };
+    addGeneratorMetadata(tree, fullyQualifiedProjectName, AGENTCORE_HARNESS_GENERATOR_INFO, metadata);
+    // scripts/chat.ts dependencies; tsx runs it via the `chat` target.
+    addTsDependencies(tree, DEPENDENCIES, {
+        metadata
+    });
+    // Harness infrastructure is written only for `infra: agentcore`. A later
+    // `infra: agentcore` rerun adds it without replacing project files.
+    if (iac) {
+        await sharedConstructsGenerator(tree, {
+            iac
+        }, DEPENDENCIES);
+        await addAgentCoreHarnessInfra(tree, {
+            harnessNameClassName: nameClassName,
+            harnessNameKebabCase: nameKebabCase,
+            projectRoot,
+            harnessNamePrefix,
+            iac
+        });
+    }
+    await addGeneratorMetricsIfApplicable(tree, [
+        AGENTCORE_HARNESS_GENERATOR_INFO
+    ]);
+    await formatFilesInSubtree(tree);
+    return ()=>installDependencies(tree, options.preferInstallDependencies, {
+            languages: [
+                'typescript'
+            ]
+        });
+};
+/**
+ * Read a Harness Project's metadata, validating it was generated by the
+ * agentcore-harness generator before returning typed data.
+ */ export const readAgentCoreHarnessMetadata = (project)=>{
+    const metadata = project.metadata;
+    if (metadata?.generator !== AGENTCORE_HARNESS_GENERATOR_INFO.id) {
+        throw new Error(`Project '${project.name}' was not generated by the '${AGENTCORE_HARNESS_GENERATOR_INFO.id}' generator.`);
+    }
+    return metadata;
+};
+export default agentcoreHarnessGenerator;
+
+//# sourceMappingURL=generator.js.map

package/src/agentcore-harness/generator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../packages/nx-plugin/src/agentcore-harness/generator.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  addProjectConfiguration,\n  type GeneratorCallback,\n  generateFiles,\n  joinPathFragments,\n  OverwriteStrategy,\n  type ProjectConfiguration,\n  type Tree,\n  updateProjectConfiguration,\n} from '@nx/devkit';\nimport { addTsDependencies } from '../utils/add-dependencies';\nimport { addAgentCoreHarnessInfra } from '../utils/agent-core-constructs/agent-core-constructs';\nimport {\n  declareDependencies,\n  ownedElsewhere,\n} from '../utils/declared-dependencies';\nimport { formatFilesInSubtree } from '../utils/format';\nimport { resolveIac } from '../utils/iac';\nimport { installDependencies } from '../utils/install';\nimport { addGeneratorMetricsIfApplicable } from '../utils/metrics';\nimport { kebabCase, toClassName } from '../utils/names';\nimport { getNpmScopePrefix } from '../utils/npm-scope';\nimport {\n  addGeneratorMetadata,\n  getGeneratorInfo,\n  type NxGeneratorInfo,\n  projectExists,\n  readProjectConfigurationUnqualified,\n} from '../utils/nx';\nimport {\n  SHARED_CONSTRUCTS_DEPENDENCIES,\n  sharedConstructsGenerator,\n} from '../utils/shared-constructs';\nimport type { IacMetadata } from '../utils/shared-constructs-constants';\nimport type { AgentcoreHarnessGeneratorSchema } from './schema';\n\n// scripts/chat.ts needs all of these whatever the infrastructure choice, so no\n// entry is conditional. The harness project holds no manifest of its own, so\n// every entry is declared against the workspace root.\nexport const DEPENDENCIES = declareDependencies<AgentCoreHarnessMetadata>()({\n  ts: [\n    { name: '@aws-sdk/client-bedrock-agentcore', root: true },\n    { name: '@aws-sdk/client-appconfigdata', root: true },\n    { name: '@aws-lambda-powertools/parameters', root: true },\n    { name: 'agent-chat-cli', root: true },\n    // tsx runs the chat script via the `chat` target; both are shared tooling.\n    { name: '@types/node', dev: true, root: true },\n    { name: 'tsx', dev: true, root: true },\n    ...ownedElsewhere(SHARED_CONSTRUCTS_DEPENDENCIES),\n  ],\n});\n\nexport const AGENTCORE_HARNESS_GENERATOR_INFO: NxGeneratorInfo =\n  getGeneratorInfo(import.meta.filename);\n\nexport const agentcoreHarnessGenerator = async (\n  tree: Tree,\n  options: AgentcoreHarnessGeneratorSchema,\n): Promise<GeneratorCallback> => {\n  const nameKebabCase = kebabCase(options.name);\n  const nameClassName = toClassName(nameKebabCase);\n  const parentDir = options.directory ?? 'packages';\n  const subDir = options.subDirectory ?? nameKebabCase;\n  const projectRoot = joinPathFragments(parentDir, subDir);\n  const fullyQualifiedProjectName = `${getNpmScopePrefix(tree)}${nameKebabCase}`;\n  const infra = options.infra ?? 'agentcore';\n\n  // AgentCore harness names must start with an ASCII letter and stay within 40\n  // characters once the \"_<8 hex>\" suffix is appended, so cap the prefix at 31.\n  // toClassName prefixes `_` (not a letter) for digit-leading names.\n  const harnessNamePrefix = (\n    /^[A-Za-z]/.test(nameClassName) ? nameClassName : `H${nameClassName}`\n  ).slice(0, 31);\n\n  // Reuse an existing project configuration; create it otherwise.\n  let project: ProjectConfiguration;\n  if (projectExists(tree, fullyQualifiedProjectName)) {\n    project = readProjectConfigurationUnqualified(\n      tree,\n      fullyQualifiedProjectName,\n    );\n  } else {\n    addProjectConfiguration(tree, fullyQualifiedProjectName, {\n      name: fullyQualifiedProjectName,\n      root: projectRoot,\n      projectType: 'application',\n      sourceRoot: projectRoot,\n      tags: [],\n      targets: {},\n      metadata: {\n        generator: AGENTCORE_HARNESS_GENERATOR_INFO.id,\n      } as any,\n    });\n    project = readProjectConfigurationUnqualified(\n      tree,\n      fullyQualifiedProjectName,\n    );\n  }\n\n  // `chat` runs the vended chat script against the deployed Harness. Re-run:\n  // keep an existing target so user edits survive.\n  project.targets ??= {};\n  project.targets['chat'] ??= {\n    executor: 'nx:run-commands',\n    options: {\n      commands: ['tsx ./scripts/chat.ts'],\n      cwd: '{projectRoot}',\n    },\n  };\n  updateProjectConfiguration(tree, project.name, project);\n\n  generateFiles(\n    tree,\n    joinPathFragments(import.meta.dirname, 'files', 'project'),\n    projectRoot,\n    {\n      nameClassName,\n      nameKebabCase,\n      fullyQualifiedName: fullyQualifiedProjectName,\n    },\n    { overwriteStrategy: OverwriteStrategy.KeepExisting },\n  );\n\n  // Resolved before the metadata write because the recorded value is what the\n  // declaration's predicates read; undefined when no infrastructure is written,\n  // in which case neither provider's packages were added.\n  const iac =\n    infra === 'agentcore' ? await resolveIac(tree, options.iac) : undefined;\n\n  // Record only what cannot drift once the user owns the generated\n  // infrastructure: the project identity, its runtime config key, its auth mode\n  // and which provider's infrastructure was written.\n  const metadata: Omit<AgentCoreHarnessMetadata, 'generator'> = {\n    name: nameKebabCase,\n    rc: nameClassName,\n    auth: 'iam',\n    ...(iac ? { iac } : {}),\n  };\n\n  addGeneratorMetadata(\n    tree,\n    fullyQualifiedProjectName,\n    AGENTCORE_HARNESS_GENERATOR_INFO,\n    metadata,\n  );\n\n  // scripts/chat.ts dependencies; tsx runs it via the `chat` target.\n  addTsDependencies(tree, DEPENDENCIES, { metadata });\n\n  // Harness infrastructure is written only for `infra: agentcore`. A later\n  // `infra: agentcore` rerun adds it without replacing project files.\n  if (iac) {\n    await sharedConstructsGenerator(tree, { iac }, DEPENDENCIES);\n    await addAgentCoreHarnessInfra(tree, {\n      harnessNameClassName: nameClassName,\n      harnessNameKebabCase: nameKebabCase,\n      projectRoot,\n      harnessNamePrefix,\n      iac,\n    });\n  }\n\n  await addGeneratorMetricsIfApplicable(tree, [\n    AGENTCORE_HARNESS_GENERATOR_INFO,\n  ]);\n\n  await formatFilesInSubtree(tree);\n  return () =>\n    installDependencies(tree, options.preferInstallDependencies, {\n      languages: ['typescript'],\n    });\n};\n\n/**\n * Harness details stored in the Harness Project's metadata. `iac` records which\n * provider's infrastructure was written, so the version sync can tell which\n * shared constructs packages this project owns.\n */\nexport interface AgentCoreHarnessMetadata extends IacMetadata {\n  generator: string;\n  name: string;\n  rc: string;\n  auth: 'iam';\n}\n\n/**\n * Read a Harness Project's metadata, validating it was generated by the\n * agentcore-harness generator before returning typed data.\n */\nexport const readAgentCoreHarnessMetadata = (\n  project: ProjectConfiguration,\n): AgentCoreHarnessMetadata => {\n  const metadata = project.metadata as any;\n  if (metadata?.generator !== AGENTCORE_HARNESS_GENERATOR_INFO.id) {\n    throw new Error(\n      `Project '${project.name}' was not generated by the '${AGENTCORE_HARNESS_GENERATOR_INFO.id}' generator.`,\n    );\n  }\n  return metadata as AgentCoreHarnessMetadata;\n};\n\nexport default agentcoreHarnessGenerator;\n"],"names":["addProjectConfiguration","generateFiles","joinPathFragments","OverwriteStrategy","updateProjectConfiguration","addTsDependencies","addAgentCoreHarnessInfra","declareDependencies","ownedElsewhere","formatFilesInSubtree","resolveIac","installDependencies","addGeneratorMetricsIfApplicable","kebabCase","toClassName","getNpmScopePrefix","addGeneratorMetadata","getGeneratorInfo","projectExists","readProjectConfigurationUnqualified","SHARED_CONSTRUCTS_DEPENDENCIES","sharedConstructsGenerator","DEPENDENCIES","ts","name","root","dev","AGENTCORE_HARNESS_GENERATOR_INFO","filename","agentcoreHarnessGenerator","tree","options","nameKebabCase","nameClassName","parentDir","directory","subDir","subDirectory","projectRoot","fullyQualifiedProjectName","infra","harnessNamePrefix","test","slice","project","projectType","sourceRoot","tags","targets","metadata","generator","id","executor","commands","cwd","dirname","fullyQualifiedName","overwriteStrategy","KeepExisting","iac","undefined","rc","auth","harnessNameClassName","harnessNameKebabCase","preferInstallDependencies","languages","readAgentCoreHarnessMetadata","Error"],"mappings":"AAAA;;;CAGC,GACD,SACEA,uBAAuB,EAEvBC,aAAa,EACbC,iBAAiB,EACjBC,iBAAiB,EAGjBC,0BAA0B,QACrB,aAAa;AACpB,SAASC,iBAAiB,QAAQ,+BAA4B;AAC9D,SAASC,wBAAwB,QAAQ,0DAAuD;AAChG,SACEC,mBAAmB,EACnBC,cAAc,QACT,oCAAiC;AACxC,SAASC,oBAAoB,QAAQ,qBAAkB;AACvD,SAASC,UAAU,QAAQ,kBAAe;AAC1C,SAASC,mBAAmB,QAAQ,sBAAmB;AACvD,SAASC,+BAA+B,QAAQ,sBAAmB;AACnE,SAASC,SAAS,EAAEC,WAAW,QAAQ,oBAAiB;AACxD,SAASC,iBAAiB,QAAQ,wBAAqB;AACvD,SACEC,oBAAoB,EACpBC,gBAAgB,EAEhBC,aAAa,EACbC,mCAAmC,QAC9B,iBAAc;AACrB,SACEC,8BAA8B,EAC9BC,yBAAyB,QACpB,gCAA6B;AAIpC,+EAA+E;AAC/E,6EAA6E;AAC7E,sDAAsD;AACtD,OAAO,MAAMC,eAAef,sBAAgD;IAC1EgB,IAAI;QACF;YAAEC,MAAM;YAAqCC,MAAM;QAAK;QACxD;YAAED,MAAM;YAAiCC,MAAM;QAAK;QACpD;YAAED,MAAM;YAAqCC,MAAM;QAAK;QACxD;YAAED,MAAM;YAAkBC,MAAM;QAAK;QACrC,2EAA2E;QAC3E;YAAED,MAAM;YAAeE,KAAK;YAAMD,MAAM;QAAK;QAC7C;YAAED,MAAM;YAAOE,KAAK;YAAMD,MAAM;QAAK;WAClCjB,eAAeY;KACnB;AACH,GAAG;AAEH,OAAO,MAAMO,mCACXV,iBAAiB,YAAYW,QAAQ,EAAE;AAEzC,OAAO,MAAMC,4BAA4B,OACvCC,MACAC;IAEA,MAAMC,gBAAgBnB,UAAUkB,QAAQP,IAAI;IAC5C,MAAMS,gBAAgBnB,YAAYkB;IAClC,MAAME,YAAYH,QAAQI,SAAS,IAAI;IACvC,MAAMC,SAASL,QAAQM,YAAY,IAAIL;IACvC,MAAMM,cAAcpC,kBAAkBgC,WAAWE;IACjD,MAAMG,4BAA4B,GAAGxB,kBAAkBe,QAAQE,eAAe;IAC9E,MAAMQ,QAAQT,QAAQS,KAAK,IAAI;IAE/B,6EAA6E;IAC7E,8EAA8E;IAC9E,mEAAmE;IACnE,MAAMC,oBAAoB,AACxB,CAAA,YAAYC,IAAI,CAACT,iBAAiBA,gBAAgB,CAAC,CAAC,EAAEA,eAAe,AAAD,EACpEU,KAAK,CAAC,GAAG;IAEX,gEAAgE;IAChE,IAAIC;IACJ,IAAI1B,cAAcY,MAAMS,4BAA4B;QAClDK,UAAUzB,oCACRW,MACAS;IAEJ,OAAO;QACLvC,wBAAwB8B,MAAMS,2BAA2B;YACvDf,MAAMe;YACNd,MAAMa;YACNO,aAAa;YACbC,YAAYR;YACZS,MAAM,EAAE;YACRC,SAAS,CAAC;YACVC,UAAU;gBACRC,WAAWvB,iCAAiCwB,EAAE;YAChD;QACF;QACAP,UAAUzB,oCACRW,MACAS;IAEJ;IAEA,2EAA2E;IAC3E,iDAAiD;IACjDK,QAAQI,OAAO,KAAK,CAAC;IACrBJ,QAAQI,OAAO,CAAC,OAAO,KAAK;QAC1BI,UAAU;QACVrB,SAAS;YACPsB,UAAU;gBAAC;aAAwB;YACnCC,KAAK;QACP;IACF;IACAlD,2BAA2B0B,MAAMc,QAAQpB,IAAI,EAAEoB;IAE/C3C,cACE6B,MACA5B,kBAAkB,YAAYqD,OAAO,EAAE,SAAS,YAChDjB,aACA;QACEL;QACAD;QACAwB,oBAAoBjB;IACtB,GACA;QAAEkB,mBAAmBtD,kBAAkBuD,YAAY;IAAC;IAGtD,4EAA4E;IAC5E,8EAA8E;IAC9E,wDAAwD;IACxD,MAAMC,MACJnB,UAAU,cAAc,MAAM9B,WAAWoB,MAAMC,QAAQ4B,GAAG,IAAIC;IAEhE,iEAAiE;IACjE,8EAA8E;IAC9E,mDAAmD;IACnD,MAAMX,WAAwD;QAC5DzB,MAAMQ;QACN6B,IAAI5B;QACJ6B,MAAM;QACN,GAAIH,MAAM;YAAEA;QAAI,IAAI,CAAC,CAAC;IACxB;IAEA3C,qBACEc,MACAS,2BACAZ,kCACAsB;IAGF,mEAAmE;IACnE5C,kBAAkByB,MAAMR,cAAc;QAAE2B;IAAS;IAEjD,yEAAyE;IACzE,oEAAoE;IACpE,IAAIU,KAAK;QACP,MAAMtC,0BAA0BS,MAAM;YAAE6B;QAAI,GAAGrC;QAC/C,MAAMhB,yBAAyBwB,MAAM;YACnCiC,sBAAsB9B;YACtB+B,sBAAsBhC;YACtBM;YACAG;YACAkB;QACF;IACF;IAEA,MAAM/C,gCAAgCkB,MAAM;QAC1CH;KACD;IAED,MAAMlB,qBAAqBqB;IAC3B,OAAO,IACLnB,oBAAoBmB,MAAMC,QAAQkC,yBAAyB,EAAE;YAC3DC,WAAW;gBAAC;aAAa;QAC3B;AACJ,EAAE;AAcF;;;CAGC,GACD,OAAO,MAAMC,+BAA+B,CAC1CvB;IAEA,MAAMK,WAAWL,QAAQK,QAAQ;IACjC,IAAIA,UAAUC,cAAcvB,iCAAiCwB,EAAE,EAAE;QAC/D,MAAM,IAAIiB,MACR,CAAC,SAAS,EAAExB,QAAQpB,IAAI,CAAC,4BAA4B,EAAEG,iCAAiCwB,EAAE,CAAC,YAAY,CAAC;IAE5G;IACA,OAAOF;AACT,EAAE;AAEF,eAAepB,0BAA0B"}

package/src/agentcore-harness/schema.d.js

@@ -0,0 +1,8 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ /**
+ * Options for the agentcore-harness generator, mirroring schema.json.
+ */ export { };
+
+//# sourceMappingURL=schema.d.js.map

package/src/agentcore-harness/schema.d.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../packages/nx-plugin/src/agentcore-harness/schema.d.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport type { IacOption } from '../utils/iac';\n\n/**\n * Options for the agentcore-harness generator, mirroring schema.json.\n */\nexport interface AgentcoreHarnessGeneratorSchema {\n  name: string;\n  directory?: string;\n  subDirectory?: string;\n  infra?: 'agentcore' | 'none';\n  iac?: IacOption;\n  preferInstallDependencies?: boolean;\n}\n"],"names":[],"mappings":"AAAA;;;CAGC,GAGD;;CAEC,GACD,WAOC"}

package/src/agentcore-harness/schema.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IacOption } from '../utils/iac';
+
+/**
+ * Options for the agentcore-harness generator, mirroring schema.json.
+ */
+export interface AgentcoreHarnessGeneratorSchema {
+  name: string;
+  directory?: string;
+  subDirectory?: string;
+  infra?: 'agentcore' | 'none';
+  iac?: IacOption;
+  preferInstallDependencies?: boolean;
+}

package/src/agentcore-harness/schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "agentcore-harness",
+  "title": "agentcore-harness",
+  "description": "Generate an Amazon Bedrock AgentCore Harness project",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The name of your AgentCore Harness project. Must contain at least one non-whitespace character which can be normalized into a kebab-case project name (eg. my-harness).",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "What would you like to call your AgentCore Harness?",
+      "x-priority": "important",
+      "pattern": "\\S"
+    },
+    "directory": {
+      "type": "string",
+      "description": "Parent directory where the harness project is placed. Defaults to packages. Must be a relative path which does not contain parent directory (..) segments.",
+      "x-priority": "important",
+      "pattern": "^(?![A-Za-z]:)(?![\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$))(?=.*\\S).+$"
+    },
+    "subDirectory": {
+      "type": "string",
+      "description": "The sub directory the project is placed in. Defaults to the kebab-case harness name. Must be a relative path which does not contain parent directory (..) segments.",
+      "x-priority": "important",
+      "pattern": "^(?![A-Za-z]:)(?![\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$))(?=.*\\S).+$"
+    },
+    "infra": {
+      "type": "string",
+      "description": "The type of infrastructure to generate for hosting your harness. Defaults to agentcore. Select none for no hosting.",
+      "x-prompt": "How would you like to host your harness?",
+      "x-priority": "important",
+      "enum": ["agentcore", "none"],
+      "default": "agentcore"
+    },
+    "iac": {
+      "type": "string",
+      "description": "The preferred IaC provider for generated harness infrastructure. Defaults to inherit, which uses the provider configured for your workspace.",
+      "x-prompt": "Which provider would you like to manage your infrastructure? (default: inherit)",
+      "x-priority": "important",
+      "enum": ["inherit", "cdk", "terraform"],
+      "default": "inherit"
+    },
+    "preferInstallDependencies": {
+      "type": "boolean",
+      "description": "Whether to prefer installing dependencies after the generator runs. Defaults to true. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end."
+    }
+  },
+  "required": ["name"]
+}

package/src/migrations/latest/translate-script-whole-file-writes/files/build-system-prompt.ts.fixture

@@ -0,0 +1,23 @@
+function buildSystemPrompt(targetLang: string): string {
+  return `You are an expert technical-documentation translator. You translate MDX documentation files from the source locale \`${config.sourceLanguage}\` into the target locale \`${targetLang}\`.
+
+Both are locale codes (ISO 639-1 / BCP-47 style, or short forms like \`jp\`, \`zh\`, \`pt\`). Translate naturally into the language the target code identifies.
+
+Use the \`fileEditor\` tool to read the files you are given and to write your translation. Read a long file in slices with \`view_range\`. Use the absolute paths exactly as given — write to the target path verbatim, never to a variation of it.
+
+Translate the prose. Everything else is copied from the source exactly as it is:
+
+- Code blocks. Reproduce each one character for character: the language and \`title\` on the opening fence, and every line of the body. Comments inside code are code — a \`# Creates a new subsegment\` stays in English. Never translate anything between the fences.
+- Inline code, URLs, link paths, \`import\` statements, component names, JSX attributes, and \`<Snippet name="..." />\` values.
+- Product, service, and people's names, and package names such as \`@aws/nx-plugin\` — translate no part of them, even where they appear in prose or in a \`title\`.
+- The MDX structure itself: frontmatter delimiters, heading levels, lists, and the blank lines between blocks. Add none and remove none.
+
+Two things do change:
+
+- In frontmatter, translate only \`title\` and \`description\`. Leave every other key and value alone. Frontmatter is YAML, so wrap a value in double quotes whenever it would otherwise begin with a character YAML reserves — for example a title starting with \`@aws/nx-plugin\` must be written as \`"@aws/nx-plugin ..."\`.
+- Rewrite link paths that embed the source locale (\`/${config.sourceLanguage}/foo\` becomes \`/${targetLang}/foo\`), and make a \`parentHeading\` match the translated heading it sits under.
+
+Write the finished file in one \`create\` call, and never with \`str_replace\` — a partial replacement silently duplicates or splices sections. Do not wrap the file in triple backticks.
+
+When the file is written, reply with a one-line summary and stop.`;
+}

package/src/migrations/latest/translate-script-whole-file-writes/files/build-user-prompt.ts.fixture

@@ -0,0 +1,96 @@
+function buildUserPrompt(file: FileToTranslate, targetLang: string): string {
+  const targetAbsPath = path.join(DOCS_DIR, targetLang, file.relativePath);
+
+  if (!file.diffPath) {
+    return `Translate \`${file.sourceAbsPath}\` into locale \`${targetLang}\` and write it to \`${targetAbsPath}\`.
+
+Read the source, then write the whole translated file with \`create\`. Always write it, even if a translation is already there — it may be out of date.`;
+  }
+
+  return `Update the \`${targetLang}\` translation of \`${file.sourceAbsPath}\`.
+
+- Source: \`${file.sourceAbsPath}\`
+- Existing translation to update: \`${targetAbsPath}\`
+- Diff of what changed in the source: \`${file.diffPath}\`
+
+Read all three. Retranslate only what the diff touched, keep the existing translated wording everywhere else, then write the whole file back with \`create\`.`;
+}
+
+const FENCE_RE = /^\s*(?:`{3,}|~{3,})/;
+
+/**
+ * Split a document into alternating prose and fenced-code segments.
+ */
+function splitOnFences(text: string): { prose: string[]; code: string[] } {
+  const prose: string[] = [];
+  const code: string[] = [];
+  let current: string[] = [];
+  let inFence = false;
+  for (const line of text.split('\n')) {
+    if (FENCE_RE.test(line)) {
+      (inFence ? code : prose).push(current.concat(line).join('\n'));
+      current = [];
+      inFence = !inFence;
+      continue;
+    }
+    current.push(line);
+  }
+  (inFence ? code : prose).push(current.join('\n'));
+  return { prose, code };
+}
+
+/**
+ * YAML frontmatter must still parse after translation. A value that begins with
+ * a character YAML reserves — most often a title starting with \`@aws/...\` —
+ * breaks the docs build, so reject it here and let the retry quote it.
+ */
+function assertFrontmatterIsParseable(text: string): void {
+  const lines = text.split('\n');
+  if (lines[0]?.trim() !== '---') return;
+  for (let i = 1; i < lines.length && lines[i].trim() !== '---'; i++) {
+    const value = lines[i].match(/^[A-Za-z0-9_-]+:\s+(\S)/)?.[1];
+    if (value && '@*&%!|>'.includes(value)) {
+      throw new Error(
+        `frontmatter line ${i + 1} starts with the reserved YAML character "${value}" and must be quoted: ${lines[i].trim()}`,
+      );
+    }
+  }
+}
+
+/**
+ * Copy the source's code blocks over the translated file's. The prompt tells the
+ * agent to reproduce them verbatim, but it occasionally translates a comment
+ * anyway, which would ship stale or broken code.
+ *
+ * A differing block count means the translation lost the document's shape —
+ * usually a section duplicated or dropped — so this throws rather than stitching
+ * mismatched blocks together, letting the caller retry.
+ */
+async function restoreCodeBlocks(
+  sourceAbsPath: string,
+  targetAbsPath: string,
+): Promise<void> {
+  const source = splitOnFences(await fs.readFile(sourceAbsPath, 'utf-8'));
+  const target = splitOnFences(await fs.readFile(targetAbsPath, 'utf-8'));
+
+  if (source.code.length !== target.code.length) {
+    throw new Error(
+      `translation has ${target.code.length} code block(s) but the source has ${source.code.length}`,
+    );
+  }
+  if (source.code.length === 0) return;
+
+  const merged = target.prose.flatMap((chunk, i) =>
+    i < source.code.length ? [chunk, source.code[i]] : [chunk],
+  );
+  await fs.writeFile(targetAbsPath, merged.join('\n'), 'utf-8');
+}
+
+/**
+ * Number of times to retry a single (file x language) translation. Large files
+ * occasionally hit transient Bedrock streaming errors; a fresh agent invocation
+ * re-reads the files from disk, so retries are idempotent.
+ */
+const TRANSLATE_MAX_ATTEMPTS = 4;
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

package/src/migrations/latest/translate-script-whole-file-writes/files/config-path.ts.fixture

@@ -0,0 +1 @@
+const CONFIG_PATH = path.resolve(SCRIPTS_DIR, 'translate.config.json');

package/src/migrations/latest/translate-script-whole-file-writes/files/file-to-translate.ts.fixture

@@ -0,0 +1,10 @@
+interface FileToTranslate {
+  relativePath: string;
+  sourceAbsPath: string;
+  /**
+   * Path to a file holding the source diff, or undefined when there is no prior
+   * translation to update. Passed to the agent as a path rather than inlined
+   * into the prompt, so it reads only as much of it as it needs.
+   */
+  diffPath?: string;
+}

package/src/migrations/latest/translate-script-whole-file-writes/files/get-files-to-translate.ts.fixture

@@ -0,0 +1,96 @@
+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 files.map((file) => ({
+      relativePath: path.relative(sourceLangRoot, file),
+      sourceAbsPath: file,
+    }));
+  }
+
+  const git = simpleGit();
+  // git reports paths relative to the repo root, which is not necessarily the
+  // directory this script runs from.
+  const repoRoot = (await git.revparse(['--show-toplevel'])).trim();
+
+  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(repoRoot, 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 relativePath = path.relative(sourceLangRoot, file);
+      const diff = await git.diff([
+        `${baseCommit}..HEAD`,
+        '--',
+        path.relative(repoRoot, file),
+      ]);
+      return {
+        relativePath,
+        sourceAbsPath: file,
+        diffPath: diff ? await writeDiff(relativePath, diff) : undefined,
+      };
+    }),
+  );
+}

package/src/migrations/latest/translate-script-whole-file-writes/files/header.ts.fixture

@@ -0,0 +1,15 @@
+/**
+ * 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 works out which source docs to translate and spawns one Strands
+ * agent per (file × target language). Each agent gets the `fileEditor` tool and
+ * the paths it needs — the source file, the target file, and a diff of what
+ * changed — then reads, translates and writes the file itself.
+ */

package/src/migrations/latest/translate-script-whole-file-writes/files/log.ts.fixture

@@ -0,0 +1,18 @@
+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}`),
+};
+
+/**
+ * Diffs live under the docs directory so the agent's file access — which is
+ * scoped to that directory — can read them. Removed when the run finishes.
+ */
+const DIFF_DIR = path.join(DOCS_DIR, '.translate-diffs');
+
+async function writeDiff(relativePath: string, diff: string): Promise<string> {
+  const diffPath = path.join(DIFF_DIR, `${relativePath}.diff`);
+  await fs.outputFile(diffPath, diff, 'utf-8');
+  return diffPath;
+}

package/src/migrations/latest/translate-script-whole-file-writes/files/main-call.ts.fixture

@@ -0,0 +1,6 @@
+main()
+  .finally(() => fs.remove(DIFF_DIR))
+  .catch((err) => {
+    log.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  });

package/src/migrations/latest/translate-script-whole-file-writes/files/main.ts.fixture

@@ -0,0 +1,79 @@
+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(', ')}`);
+
+  await pruneOrphanedTranslations(targetLanguages);
+
+  const files = await getFilesToTranslate();
+
+  if (files.length === 0) {
+    log.info('No documentation files to translate.');
+    return;
+  }
+
+  log.info(`Files to translate: ${files.length}`);
+  for (const f of files) {
+    log.verbose(
+      `  - ${f.relativePath}${f.diffPath ? ' (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. A single
+  // failing translation records its error rather than aborting the whole run, so
+  // every other (file × language) still completes and gets written to disk.
+  const failures: string[] = [];
+  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)}`,
+        );
+        failures.push(`${file.relativePath} → ${lang}`);
+      }
+    }),
+  );
+
+  const concurrency = Math.max(1, config.concurrency ?? 5);
+  log.info(
+    `Running ${tasks.length} translation(s) with concurrency=${concurrency}`,
+  );
+  await runWithConcurrency(tasks, concurrency);
+
+  if (failures.length > 0) {
+    throw new Error(
+      `${failures.length} translation(s) failed after retries:\n  ${failures.join('\n  ')}`,
+    );
+  }
+
+  log.info('Done.');
+}

package/src/migrations/latest/translate-script-whole-file-writes/files/project-root.ts.fixture

@@ -0,0 +1 @@
+const PROJECT_ROOT = path.resolve(SCRIPTS_DIR, '..');