@aws/nx-plugin 1.0.0-rc.8 → 1.0.0-rc.80

package/src/migrations/v1.0.0-rc.68/0001-translate-script-whole-file-writes/test-fixtures/released-script.ts.fixture

@@ -0,0 +1,431 @@
+/**
+ * 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 SCRIPTS_DIR = <% if (esm) { %>import.meta.dirname<% } else { %>__dirname<% } %>;
+const PROJECT_ROOT = path.resolve(SCRIPTS_DIR, '..');
+const CONFIG_PATH = path.resolve(SCRIPTS_DIR, '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);
+});

package/src/migrations/v1.0.0-rc.70/0001-py-agent-a2a-lifespan-construction/metadata.json

@@ -0,0 +1,3 @@
+{
+  "description": "Move py#agent A2A agent construction (Strands and LangChain) out of module import time and into a FastAPI lifespan handler, stored on app.state; also updates with_session_id/session_id_context to use Generator instead of the deprecated Iterator return type"
+}

package/src/migrations/v1.0.0-rc.70/0001-py-agent-a2a-lifespan-construction/migration.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type MigrationReturnObject, type Tree } from '@nx/devkit';
+export default function migration(tree: Tree): Promise<MigrationReturnObject>;

package/src/migrations/v1.0.0-rc.70/0001-py-agent-a2a-lifespan-construction/migration.js

@@ -0,0 +1,246 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { getProjects, joinPathFragments, visitNotIgnoredFiles } from "@nx/devkit";
+import { PY_AGENT_GENERATOR_INFO } from "../../../py/agent/generator.js";
+import { addPythonDestructuredImport, applyGritQL, captureGritQLVariable, matchGritQL } from "../../../utils/ast.js";
+import { formatFilesInSubtree } from "../../../utils/format.js";
+/**
+ * Move py#agent A2A agent construction (Strands and LangChain) out of module
+ * import time and into a FastAPI `lifespan` handler, stored on `app.state`.
+ *
+ * The `v1.0.0-rc.61/0001-py-agent-lifespan-construction` migration (HTTP/AG-UI)
+ * deliberately left A2A alone, reasoning that `with_session_id` only touches
+ * its agent factory lazily on first use, so the eager `_agent_ctx.__enter__()`
+ * was never actually eager in practice. That held for `with_session_id`'s own
+ * laziness, but missed a separate trigger: `strands.multiagent.a2a.executor
+ * .StrandsA2AExecutor.__init__`, in its deprecated single-`agent=` mode, does
+ * `getattr(agent, "_session_manager", None)` - which the session-routing
+ * proxy's `__getattr__` happily serves by building the real underlying Agent
+ * right then, under a bogus "default" session, since no request has bound a
+ * real session id yet. That call happens inside `A2AServer.__init__`, which
+ * the old template constructed at plain module import time - so the "lazy"
+ * proxy was forced eager anyway, just one layer further down than the
+ * previous migration checked.
+ *
+ * Strands: `agent_factory=` mode sidesteps this - `StrandsA2AExecutor` takes
+ * an entirely different branch when given a factory (no `_session_manager`
+ * probe at all), and the one placeholder call `A2AServer.__init__` makes
+ * before `lifespan` has run returns a bare `SimpleNamespace` with just
+ * `name`/`description` - no `__getattr__`, nothing to force construction.
+ *
+ * LangChain: the compiled graph from `get_agent()` has no such trap, but was
+ * still built eagerly at import time (`_graph = get_agent()`). Moved into
+ * `lifespan` for the same reason HTTP/AG-UI were: it can require env vars
+ * (model id, region) or do network setup that isn't guaranteed available at
+ * import - e.g. under test collection or OpenAPI spec generation tooling.
+ *
+ * Also folds in an unrelated but adjacent fix: Pylance (Pyright) deprecates
+ * annotating a `@contextmanager`-decorated function's return type as
+ * `Iterator[T]`, in favor of the single-argument `Generator[T]` form enabled
+ * by PEP 696 default type parameters (Python 3.13+ - generated projects
+ * target >=3.14). `with_session_id_strands.py` and `session_context.py` both
+ * use this pattern. Both files are shared, protocol-agnostic files copied
+ * once per workspace (not per py#agent component), so that part scans the
+ * whole tree by basename rather than going through component metadata.
+ */ const pyMatch = (snippet)=>`language python\n\`${snippet}\``;
+const pyDelete = (snippet)=>`${pyMatch(snippet)} => .`;
+const pyRewrite = (from, to)=>{
+    const replacement = to.includes('\n') ? `raw\`${to}\`` : `\`${to}\``;
+    return `${pyMatch(from)} => ${replacement}`;
+};
+const AGENT_ENTER = '_agent = _agent_ctx.__enter__()';
+const OLD_AGENT_CONTEXT = `_agent_ctx = with_session_id(
+    get_agent,
+    name="$name",
+    description="A Strands Agent exposed via the Agent-to-Agent (A2A) protocol.",
+)`;
+const NEW_CONSTANTS_AND_LIFESPAN = `AGENT_NAME = "$name"
+AGENT_DESCRIPTION = "A Strands Agent exposed via the Agent-to-Agent (A2A) protocol."
+
+# A2AServer.__init__ calls agent_factory once, synchronously, before the lifespan
+# below has run - this is what it reads name/description from at that point.
+# The cast is a lie about runtime shape, not behavior: only .name/.description
+# are ever read off this value.
+_card_placeholder = cast(
+    Agent, SimpleNamespace(name=AGENT_NAME, description=AGENT_DESCRIPTION)
+)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    with with_session_id(
+        get_agent,
+        name=AGENT_NAME,
+        description=AGENT_DESCRIPTION,
+    ) as agent:
+        app.state.agent = agent
+        yield`;
+const A2A_SERVER_STATEMENT = 'a2a_server = A2AServer($args)';
+const OLD_MOUNT_STATEMENT = 'app.mount("/", a2a_server.to_fastapi_app())';
+const OLD_FASTAPI_APP = 'app = FastAPI()';
+const NEW_FASTAPI_APP = 'app = FastAPI(lifespan=lifespan)';
+const SERVER_MATCH = 'language python\n`A2AServer($args)` where { $args <: contains `agent=_agent` }';
+const allMatch = async (tree, filePath, patterns)=>{
+    for (const pattern of patterns){
+        if (!await matchGritQL(tree, filePath, pattern)) return false;
+    }
+    return true;
+};
+const migrateStrandsA2AAgent = async (tree, mainPath, nextSteps)=>{
+    if (!tree.exists(mainPath)) return;
+    const contents = tree.read(mainPath, 'utf-8') ?? '';
+    if (!contents.includes('_agent_ctx = with_session_id(')) return;
+    const ready = await allMatch(tree, mainPath, [
+        pyMatch('import logging'),
+        pyMatch('from $mod import session_id_context, with_session_id'),
+        pyMatch(OLD_AGENT_CONTEXT),
+        pyMatch(AGENT_ENTER),
+        pyMatch(OLD_FASTAPI_APP),
+        pyMatch(OLD_MOUNT_STATEMENT),
+        SERVER_MATCH
+    ]);
+    const diverged = ()=>{
+        nextSteps.push(`${mainPath}: diverged from the generated Strands A2A shape - left untouched. Manually rebuild the agent inside the FastAPI \`lifespan\` and have \`agent_factory\` read it off \`app.state\` (see the py#agent generator's strands/a2a template).`);
+    };
+    if (!ready) {
+        diverged();
+        return;
+    }
+    await addPythonDestructuredImport(tree, mainPath, [
+        'asynccontextmanager'
+    ], 'contextlib');
+    await addPythonDestructuredImport(tree, mainPath, [
+        'SimpleNamespace'
+    ], 'types');
+    await addPythonDestructuredImport(tree, mainPath, [
+        'cast'
+    ], 'typing');
+    await addPythonDestructuredImport(tree, mainPath, [
+        'Agent'
+    ], 'strands');
+    await applyGritQL(tree, mainPath, pyRewrite(OLD_AGENT_CONTEXT, NEW_CONSTANTS_AND_LIFESPAN));
+    await applyGritQL(tree, mainPath, pyDelete(AGENT_ENTER));
+    // Swap the kwarg while the call is still in its original spot (any extra
+    // kwargs a user added are left alone), then capture the whole arg list so
+    // it can be reinserted at the call's new home below.
+    await applyGritQL(tree, mainPath, pyRewrite('agent=_agent', 'agent_factory=lambda _context_id: getattr(app.state, "agent", _card_placeholder)'));
+    const capturedArgs = await captureGritQLVariable(tree, mainPath, `language python\n\`${A2A_SERVER_STATEMENT}\``, 'args');
+    if (capturedArgs === undefined) {
+        diverged();
+        return;
+    }
+    await applyGritQL(tree, mainPath, pyDelete(A2A_SERVER_STATEMENT));
+    await applyGritQL(tree, mainPath, pyRewrite(OLD_FASTAPI_APP, NEW_FASTAPI_APP));
+    await applyGritQL(tree, mainPath, pyRewrite(OLD_MOUNT_STATEMENT, `a2a_server = A2AServer(${capturedArgs})\n\n${OLD_MOUNT_STATEMENT}`));
+};
+// --- LangChain A2A -----------------------------------------------------------
+const LANGCHAIN_GRAPH_OLD = '_graph = get_agent()';
+const LANGCHAIN_LIFESPAN_NEW = `@asynccontextmanager
+async def lifespan(app: FastAPI):
+    app.state.agent = get_agent()
+    yield`;
+const LANGCHAIN_GRAPH_INVOKE_OLD = '_graph.ainvoke($args)';
+const LANGCHAIN_GRAPH_INVOKE_NEW = 'app.state.agent.ainvoke($args)';
+const LANGCHAIN_APP_OLD = 'app = FastAPI(title="$name")';
+const LANGCHAIN_APP_NEW = 'app = FastAPI(title="$name", lifespan=lifespan)';
+const migrateLangchainA2AAgent = async (tree, mainPath, nextSteps)=>{
+    if (!tree.exists(mainPath)) return;
+    const contents = tree.read(mainPath, 'utf-8') ?? '';
+    if (!contents.includes(LANGCHAIN_GRAPH_OLD)) return;
+    const ready = await allMatch(tree, mainPath, [
+        pyMatch(LANGCHAIN_GRAPH_OLD),
+        pyMatch('from .agent import get_agent'),
+        pyMatch(LANGCHAIN_GRAPH_INVOKE_OLD),
+        pyMatch(LANGCHAIN_APP_OLD)
+    ]);
+    if (!ready) {
+        nextSteps.push(`${mainPath}: diverged from the generated LangChain A2A shape - left untouched. Manually wrap \`get_agent()\` in a \`lifespan\` handler storing the graph on \`app.state.agent\` (see the py#agent generator's langchain/a2a template).`);
+        return;
+    }
+    await addPythonDestructuredImport(tree, mainPath, [
+        'asynccontextmanager'
+    ], 'contextlib');
+    await applyGritQL(tree, mainPath, pyRewrite(LANGCHAIN_GRAPH_OLD, LANGCHAIN_LIFESPAN_NEW));
+    await applyGritQL(tree, mainPath, pyRewrite(LANGCHAIN_GRAPH_INVOKE_OLD, LANGCHAIN_GRAPH_INVOKE_NEW));
+    await applyGritQL(tree, mainPath, pyRewrite(LANGCHAIN_APP_OLD, LANGCHAIN_APP_NEW));
+};
+// --- Iterator -> Generator (with_session_id_strands.py / session_context.py) ---
+const WITH_SESSION_ID_IMPORT_OLD = 'from collections.abc import Callable, Iterator';
+const WITH_SESSION_ID_IMPORT_NEW = 'from collections.abc import Callable, Generator';
+/**
+ * Whether every `Iterator` reference in the file is one this migration is about
+ * to convert, so dropping the import cannot leave an undefined name behind. A
+ * user's own `Iterator[...]` annotation elsewhere in the file is not rewritten
+ * (the rewrite targets one exact annotation), so removing the import would leave
+ * the module raising `NameError` on import.
+ */ const onlyIteratorUseIs = (contents, annotation)=>{
+    const withoutImport = contents.replace(/^from collections\.abc import .*$/m, '');
+    const uses = withoutImport.match(/\bIterator\b/g) ?? [];
+    const converted = withoutImport.match(new RegExp(annotation.replace(/[[\]]/g, '\\$&'), 'g'));
+    return uses.length === (converted?.length ?? 0);
+};
+const migrateWithSessionId = async (tree, filePath, nextSteps)=>{
+    const contents = tree.read(filePath, 'utf-8') ?? '';
+    if (!contents.includes('Iterator[Any]')) return;
+    const ready = await allMatch(tree, filePath, [
+        pyMatch(WITH_SESSION_ID_IMPORT_OLD),
+        pyMatch('Iterator[Any]')
+    ]) && onlyIteratorUseIs(contents, 'Iterator[Any]');
+    if (!ready) {
+        nextSteps.push(`${filePath}: diverged from the generated shape - left untouched. Manually change the \`Iterator\` import and \`Iterator[Any]\` return annotation on \`with_session_id\` to \`Generator\`/\`Generator[Any]\` (see the agent-connection generator's with_session_id_strands.py template).`);
+        return;
+    }
+    await applyGritQL(tree, filePath, pyRewrite(WITH_SESSION_ID_IMPORT_OLD, WITH_SESSION_ID_IMPORT_NEW));
+    await applyGritQL(tree, filePath, pyRewrite('Iterator[Any]', 'Generator[Any]'));
+};
+const SESSION_CONTEXT_IMPORT_OLD = 'from collections.abc import Iterator';
+const SESSION_CONTEXT_IMPORT_NEW = 'from collections.abc import Generator';
+const migrateSessionContext = async (tree, filePath, nextSteps)=>{
+    const contents = tree.read(filePath, 'utf-8') ?? '';
+    if (!contents.includes('Iterator[None]')) return;
+    const ready = await allMatch(tree, filePath, [
+        pyMatch(SESSION_CONTEXT_IMPORT_OLD),
+        pyMatch('Iterator[None]')
+    ]) && onlyIteratorUseIs(contents, 'Iterator[None]');
+    if (!ready) {
+        nextSteps.push(`${filePath}: diverged from the generated shape - left untouched. Manually change the \`Iterator\` import and \`Iterator[None]\` return annotation on \`session_id_context\` to \`Generator\`/\`Generator[None]\` (see the agent-connection generator's session_context.py template).`);
+        return;
+    }
+    await applyGritQL(tree, filePath, pyRewrite(SESSION_CONTEXT_IMPORT_OLD, SESSION_CONTEXT_IMPORT_NEW));
+    await applyGritQL(tree, filePath, pyRewrite('Iterator[None]', 'Generator[None]'));
+};
+const findAgentComponents = (components)=>(components ?? []).filter((component)=>component.generator === PY_AGENT_GENERATOR_INFO.id);
+export default async function migration(tree) {
+    const nextSteps = [];
+    for (const project of getProjects(tree).values()){
+        const components = findAgentComponents(project.metadata?.components);
+        for (const component of components){
+            if (!component.path || component.protocol !== 'a2a') {
+                continue;
+            }
+            const componentDir = component.path.endsWith('/agent.py') ? component.path.slice(0, -'/agent.py'.length) : component.path;
+            const mainPath = joinPathFragments(project.root, componentDir, 'main.py');
+            if ((component.framework ?? 'strands') === 'langchain') {
+                await migrateLangchainA2AAgent(tree, mainPath, nextSteps);
+            } else {
+                await migrateStrandsA2AAgent(tree, mainPath, nextSteps);
+            }
+        }
+    }
+    const filePaths = [];
+    visitNotIgnoredFiles(tree, '', (filePath)=>filePaths.push(filePath));
+    for (const filePath of filePaths){
+        if (filePath.endsWith('/with_session_id_strands.py')) {
+            await migrateWithSessionId(tree, filePath, nextSteps);
+        } else if (filePath.endsWith('/session_context.py')) {
+            await migrateSessionContext(tree, filePath, nextSteps);
+        }
+    }
+    await formatFilesInSubtree(tree);
+    return {
+        nextSteps
+    };
+}
+
+//# sourceMappingURL=migration.js.map