@aws/nx-plugin 1.0.0-rc.7 → 1.0.0-rc.71

package/src/connection/scaffold-catalog.js

@@ -0,0 +1,347 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import GeneratorsJson from "../../generators.json" with {
+    type: 'json'
+};
+import { SUPPORTED_CONNECTIONS } from "./supported-connections.js";
+const GENERATORS = GeneratorsJson.generators;
+/** The path `generators.json` records for a generator, relative to the plugin root. */ export const schemaPathOf = (generatorId)=>{
+    const entry = GENERATORS[generatorId];
+    if (!entry) {
+        throw new Error(`Scaffold catalog: '${generatorId}' is not in generators.json`);
+    }
+    return entry.schema;
+};
+/** The language prefix of a generator id: `ts` for `ts#agent`, `` for `license`. */ const languageOf = (id)=>id.includes('#') ? id.slice(0, id.indexOf('#')) : '';
+/** Compare ids ignoring the separators that differ between wrapper and variant. */ const alike = (a, b)=>a.replace(/[^a-z0-9]/gi, '').toLowerCase() === b.replace(/[^a-z0-9]/gi, '').toLowerCase();
+/**
+ * The public generator and option value that select a hidden endpoint type.
+ *
+ * A wrapper like `ts#api` produces several endpoint types, choosing between them
+ * with an enum option: `--framework=trpc` yields `ts#trpc-api`. The pairing is
+ * found by looking for a same-language public generator with an enum value that
+ * reconstructs the endpoint's own name.
+ */ const findWrapper = (endpointType, schemaOf)=>{
+    const language = languageOf(endpointType);
+    const name = endpointType.slice(endpointType.indexOf('#') + 1);
+    for (const [generatorId, entry] of Object.entries(GENERATORS)){
+        if (entry.hidden) continue;
+        if (languageOf(generatorId) !== language) continue;
+        const wrapperName = generatorId.slice(generatorId.indexOf('#') + 1);
+        for (const [option, property] of Object.entries(schemaOf(generatorId).properties ?? {})){
+            for (const value of property.enum ?? []){
+                // Either the value names the variant outright (`react` for
+                // `react-website`), or it qualifies the wrapper's own name
+                // (`trpc` + `api` for `trpc-api`).
+                if (alike(value, name) || alike(`${value}${wrapperName}`, name)) {
+                    return {
+                        generator: generatorId,
+                        options: {
+                            [option]: value
+                        }
+                    };
+                }
+            }
+        }
+    }
+    return undefined;
+};
+/**
+ * Derive the recipe for one endpoint type. Exported so a test can assert the
+ * derivation against every type the plugin supports.
+ */ export const deriveScaffoldRecipe = (endpointType, schemaOf)=>{
+    const own = GENERATORS[endpointType];
+    if (!own) {
+        throw new Error(`Scaffold catalog: connection endpoint '${endpointType}' is not a generator id`);
+    }
+    // A hidden generator is an implementation detail reached through its public
+    // wrapper, which is what a user would actually run.
+    const wrapper = own.hidden ? findWrapper(endpointType, schemaOf) : undefined;
+    if (own.hidden && !wrapper) {
+        throw new Error(`Scaffold catalog: '${endpointType}' is hidden and no public generator selects it`);
+    }
+    // A generator requiring a `project` adds a component to one; anything else
+    // creates its own project.
+    const kind = (schemaOf(endpointType).required ?? []).includes('project') ? 'component' : 'project';
+    const language = languageOf(endpointType);
+    const hostGenerator = `${language}#project`;
+    if (kind === 'component' && !GENERATORS[hostGenerator]) {
+        throw new Error(`Scaffold catalog: '${endpointType}' is a component but '${hostGenerator}' does not exist to host it`);
+    }
+    return {
+        // `x-label` is the short noun a palette entry needs; `title` and
+        // `description` are prose aimed at CLI prompts ("Create a relational database
+        // project"). A generator without one falls back to its id, so a new endpoint
+        // type still appears rather than being dropped.
+        label: schemaOf(endpointType)['x-label'] ?? endpointType,
+        generator: wrapper?.generator ?? endpointType,
+        ...wrapper ? {
+            options: wrapper.options
+        } : {},
+        kind,
+        ...kind === 'component' ? {
+            host: {
+                generator: hostGenerator,
+                // Only options the host's schema actually requires, so a base
+                // project generator gaining a required option is handled here.
+                options: Object.fromEntries((schemaOf(hostGenerator).required ?? []).filter((option)=>option !== 'name').map((option)=>{
+                    const property = schemaOf(hostGenerator).properties?.[option];
+                    const value = property?.default ?? property?.enum?.[0];
+                    if (value === undefined) {
+                        throw new Error(`Scaffold catalog: '${hostGenerator}' requires '${option}' but its schema offers no value to use`);
+                    }
+                    return [
+                        option,
+                        String(value)
+                    ];
+                })),
+                // Python project names are snake_cased when Nx qualifies them.
+                snakeCaseName: language === 'py'
+            }
+        } : {}
+    };
+};
+/** Every endpoint type appearing at either end of a supported connection. */ export const CONNECTION_ENDPOINT_TYPES = [
+    ...new Set(SUPPORTED_CONNECTIONS.flatMap(({ source, target })=>[
+            source,
+            target
+        ]))
+].sort();
+/**
+ * How to scaffold each connection endpoint type, derived from the generator
+ * metadata. A connection added to `SUPPORTED_CONNECTIONS` appears here with no
+ * edit to this file.
+ */ export const buildScaffoldRecipes = (schemaOf)=>Object.fromEntries(CONNECTION_ENDPOINT_TYPES.map((type)=>[
+            type,
+            deriveScaffoldRecipe(type, schemaOf)
+        ]));
+/** Reusable constraint shapes, so the map below states each rule once. */ const AGENT_TO_AGENT = [
+    {
+        side: 'target',
+        option: 'protocol',
+        equals: 'a2a',
+        reason: 'Only an A2A agent can be connected to another agent as a tool.'
+    },
+    {
+        side: 'target',
+        option: 'auth',
+        equals: 'iam',
+        reason: 'A2A agent connections authenticate with IAM.'
+    }
+];
+const WEBSITE_TO_AGENT = [
+    {
+        side: 'target',
+        option: 'protocol',
+        notEquals: 'a2a',
+        reason: 'A2A agents are reached by other agents, not by a website. Use the http or ag-ui protocol.'
+    }
+];
+const AGENT_TO_MCP = [
+    {
+        side: 'target',
+        option: 'auth',
+        equals: 'iam',
+        reason: 'An agent reaches an MCP server with IAM authentication.'
+    }
+];
+const AGENT_TO_GATEWAY = [
+    {
+        side: 'source',
+        option: 'auth',
+        equals: 'iam',
+        reason: 'Only an IAM-authenticated agent can reach an IAM gateway.'
+    },
+    {
+        side: 'target',
+        option: 'auth',
+        equals: 'iam',
+        reason: 'Agent connections require the gateway to authenticate with IAM.'
+    }
+];
+const GATEWAY_TO_MCP = [
+    {
+        side: 'source',
+        option: 'protocol',
+        equals: 'mcp',
+        reason: 'MCP server targets can only be attached to an mcp-protocol gateway.'
+    },
+    {
+        side: 'target',
+        option: 'auth',
+        equals: 'iam',
+        reason: 'A gateway reaches an MCP server target with IAM authentication.'
+    }
+];
+const GATEWAY_TO_AGENT = [
+    {
+        side: 'source',
+        option: 'protocol',
+        equals: 'http',
+        reason: 'Agent runtime targets can only be attached to an http-protocol gateway.'
+    },
+    {
+        side: 'target',
+        option: 'auth',
+        equals: 'iam',
+        reason: 'The gateway signs requests to its agent targets with IAM.'
+    }
+];
+/**
+ * The option-level requirements each connection places on its endpoints.
+ *
+ * Only connections carrying a requirement appear. Keyed by `ConnectionKey`, so a
+ * key that no longer names a supported connection is a compile error.
+ */ export const CONNECTION_CONSTRAINTS = {
+    'ts#react-website -> ts#agent': WEBSITE_TO_AGENT,
+    'ts#react-website -> py#agent': WEBSITE_TO_AGENT,
+    'ts#agent -> ts#agent': AGENT_TO_AGENT,
+    'ts#agent -> py#agent': AGENT_TO_AGENT,
+    'py#agent -> ts#agent': AGENT_TO_AGENT,
+    'py#agent -> py#agent': AGENT_TO_AGENT,
+    'ts#agent -> ts#mcp-server': AGENT_TO_MCP,
+    'ts#agent -> py#mcp-server': AGENT_TO_MCP,
+    'py#agent -> ts#mcp-server': AGENT_TO_MCP,
+    'py#agent -> py#mcp-server': AGENT_TO_MCP,
+    'ts#agent -> agentcore-gateway': AGENT_TO_GATEWAY,
+    'py#agent -> agentcore-gateway': AGENT_TO_GATEWAY,
+    'ts#react-website -> agentcore-gateway': [
+        {
+            side: 'target',
+            option: 'protocol',
+            equals: 'http',
+            reason: 'A website connects to an http-protocol gateway, which proxies requests to its agent targets.'
+        }
+    ],
+    'agentcore-gateway -> ts#agent': [
+        ...GATEWAY_TO_AGENT,
+        {
+            side: 'target',
+            option: 'protocol',
+            notEquals: 'http',
+            reason: 'A TypeScript http agent serves tRPC over WebSocket, which AgentCore Gateway does not support. Use the ag-ui or a2a protocol.'
+        }
+    ],
+    'agentcore-gateway -> py#agent': GATEWAY_TO_AGENT,
+    'agentcore-gateway -> ts#mcp-server': GATEWAY_TO_MCP,
+    'agentcore-gateway -> py#mcp-server': GATEWAY_TO_MCP,
+    'agentcore-gateway -> agentcore-gateway': [
+        {
+            side: 'source',
+            option: 'protocol',
+            equals: 'mcp',
+            reason: 'A gateway is aggregated into another as an MCP target, so both must be mcp-protocol gateways.'
+        },
+        {
+            side: 'target',
+            option: 'protocol',
+            equals: 'mcp',
+            reason: 'A gateway is aggregated into another as an MCP target, so both must be mcp-protocol gateways.'
+        },
+        {
+            side: 'target',
+            option: 'auth',
+            equals: 'iam',
+            reason: 'The source gateway signs its request with IAM, so the target gateway must accept IAM.'
+        }
+    ]
+};
+/**
+ * Generators run automatically after an endpoint type is scaffolded, keyed by
+ * endpoint type.
+ */ export const ENDPOINT_FOLLOW_UPS = {
+    'ts#react-website': [
+        {
+            generator: 'ts#website#auth',
+            // `cognitoDomain` is derived from the npm scope and project name when
+            // omitted, so the command stays short.
+            adds: 'Cognito authentication'
+        }
+    ]
+};
+/** An agent target only attaches to an http gateway, an MCP server only to an mcp one. */ const GATEWAY_PREFERS_HTTP = {
+    side: 'source',
+    option: 'protocol',
+    value: 'http',
+    reason: 'Agent runtime targets are proxied by an http gateway, so attaching an agent selects that protocol.'
+};
+const GATEWAY_PREFERS_MCP = {
+    side: 'source',
+    option: 'protocol',
+    value: 'mcp',
+    reason: 'MCP server targets are aggregated by an mcp gateway, so attaching an MCP server selects that protocol.'
+};
+/**
+ * Preferred option values per connection. Keyed by `ConnectionKey`, so a key that
+ * no longer names a supported connection is a compile error.
+ */ export const CONNECTION_PREFERENCES = {
+    'ts#react-website -> ts#agent': [
+        {
+            side: 'target',
+            option: 'protocol',
+            value: 'ag-ui',
+            reason: 'AG-UI is the protocol built for driving a frontend, so a website connection selects it.'
+        }
+    ],
+    'ts#react-website -> py#agent': [
+        {
+            side: 'target',
+            option: 'protocol',
+            value: 'ag-ui',
+            reason: 'AG-UI is the protocol built for driving a frontend, so a website connection selects it.'
+        }
+    ],
+    // A gateway's protocol is decided by what it fronts, and the two are mutually
+    // exclusive: agent runtime targets need an http gateway, MCP server targets an
+    // mcp one. The gateway schema defaults to mcp, so only the agent side needs a
+    // preference — but both are stated, so whichever target the user attaches
+    // first settles the protocol.
+    'agentcore-gateway -> ts#agent': [
+        GATEWAY_PREFERS_HTTP
+    ],
+    'agentcore-gateway -> py#agent': [
+        GATEWAY_PREFERS_HTTP
+    ],
+    'agentcore-gateway -> ts#mcp-server': [
+        GATEWAY_PREFERS_MCP
+    ],
+    'agentcore-gateway -> py#mcp-server': [
+        GATEWAY_PREFERS_MCP
+    ],
+    'ts#react-website -> agentcore-gateway': [
+        {
+            side: 'target',
+            option: 'protocol',
+            value: 'http',
+            reason: 'A website reaches a gateway’s agent targets over path-based http routing, so the gateway serves the http protocol.'
+        }
+    ]
+};
+/**
+ * Connections that must be generated after another, because the generator reads
+ * state the earlier one records.
+ *
+ * The website→gateway generator publishes a route per agent already attached to
+ * the gateway, reading them from the gateway project's connection metadata. Run
+ * before the gateway→agent connections, it finds none and wires up nothing.
+ *
+ * Keyed by `ConnectionKey`, so a key that no longer names a supported connection
+ * is a compile error.
+ */ export const CONNECTION_ORDERING = {
+    'ts#react-website -> agentcore-gateway': {
+        after: [
+            'agentcore-gateway -> ts#agent',
+            'agentcore-gateway -> py#agent'
+        ],
+        reason: 'The website connection publishes a route per agent attached to the gateway, so the gateway’s agents must be attached first.'
+    }
+};
+/**
+ * Connections whose source and target must be distinct projects, because the
+ * connection generator refuses to wire a project to itself.
+ */ export const SELF_CONNECTION_DISALLOWED = [
+    'agentcore-gateway -> agentcore-gateway'
+];
+
+//# sourceMappingURL=scaffold-catalog.js.map

package/src/connection/scaffold-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../packages/nx-plugin/src/connection/scaffold-catalog.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport GeneratorsJson from '../../generators.json' with { type: 'json' };\nimport {\n  type ConnectionKey,\n  SUPPORTED_CONNECTIONS,\n  type SUPPORTED_PROJECT_TYPES,\n} from './supported-connections';\n\n/**\n * How to scaffold each end of a connection, derived from the plugin's own\n * metadata rather than hand-listed.\n *\n * Every connection endpoint type is also a generator id, which is what makes the\n * derivation possible:\n *\n * - **kind** — a generator whose schema `required`s a `project` adds a component\n *   to an existing project; anything else creates a project of its own.\n * - **host** — a component lands in a project made by its language's base\n *   generator (`ts#project` / `py#project`).\n * - **generator + options** — a type whose own generator is `hidden` is reached\n *   through the public wrapper that selects it, found by matching the wrapper's\n *   enum values against the type's name (`ts#trpc-api` ← `ts#api\n *   --framework=trpc`). A visible generator is run directly.\n *\n * - **label** — the generator schema's own `x-label`.\n *\n * The result is that adding a generator and a connection for it needs no edit\n * here at all. The one thing still declared below is the option constraints,\n * which live as imperative guards inside each connection generator and so cannot\n * be read from metadata.\n */\n\n/**\n * Every type that can sit at either end of a connection: the project-level\n * types resolved by introspection, plus the component generator ids recorded in\n * component metadata.\n */\nexport type ConnectionEndpointType =\n  | (typeof SUPPORTED_PROJECT_TYPES)[number]\n  | (typeof SUPPORTED_CONNECTIONS)[number]['source']\n  | (typeof SUPPORTED_CONNECTIONS)[number]['target'];\n\n/**\n * Whether scaffolding an endpoint creates a project of its own, or adds a\n * component to a project that must already exist.\n */\nexport type ScaffoldKind = 'project' | 'component';\n\n/** How to scaffold one end of a connection from the CLI. */\nexport interface ScaffoldRecipe {\n  /** Human-readable name for this endpoint type. */\n  readonly label: string;\n  /** The generator id in `generators.json` that produces this endpoint. */\n  readonly generator: string;\n  /**\n   * Options that select this endpoint type from its generator, for generators\n   * producing more than one type (e.g. `framework`).\n   */\n  readonly options?: Readonly<Record<string, string>>;\n  /** Whether the generator creates a project or adds a component to one. */\n  readonly kind: ScaffoldKind;\n  /**\n   * The generator producing a project able to host this component, for\n   * `component` recipes. Components are added to an existing project, so one\n   * must be scaffolded first.\n   */\n  readonly host?: {\n    readonly generator: string;\n    readonly options?: Readonly<Record<string, string>>;\n    /**\n     * Whether the host project's name is referenced in snake_case. Python\n     * project names are snake_cased when qualified, TypeScript ones are not.\n     */\n    readonly snakeCaseName?: boolean;\n  };\n}\n\ntype GeneratorEntry = { schema: string; hidden?: boolean };\n/** The subset of JSON Schema the catalogue and the docs builder read. */\nexport type GeneratorSchema = {\n  /**\n   * Short display name for the thing this generator produces, used by the docs\n   * graph builder's palette. Set it on any generator that can take part in a\n   * connection.\n   */\n  'x-label'?: string;\n  properties?: Record<\n    string,\n    {\n      type?: string;\n      description?: string;\n      enum?: string[];\n      default?: unknown;\n      'x-priority'?: string;\n    }\n  >;\n  required?: string[];\n};\n\ntype Schema = GeneratorSchema;\n\nconst GENERATORS = GeneratorsJson.generators as Record<string, GeneratorEntry>;\n\n/**\n * Resolves a generator's JSON schema by generator id.\n *\n * Injected rather than fixed because the two callers load files differently: the\n * plugin reads from disk (see `./schema-resolver`), while the docs site bundles\n * the schemas for the browser, where `node:fs` does not exist. Keeping this\n * module free of `node:fs` is what lets the browser import it at all.\n */\nexport type SchemaResolver = (generatorId: string) => Schema;\n\n/** The path `generators.json` records for a generator, relative to the plugin root. */\nexport const schemaPathOf = (generatorId: string): string => {\n  const entry = GENERATORS[generatorId];\n  if (!entry) {\n    throw new Error(\n      `Scaffold catalog: '${generatorId}' is not in generators.json`,\n    );\n  }\n  return entry.schema;\n};\n\n/** The language prefix of a generator id: `ts` for `ts#agent`, `` for `license`. */\nconst languageOf = (id: string): string =>\n  id.includes('#') ? id.slice(0, id.indexOf('#')) : '';\n\n/** Compare ids ignoring the separators that differ between wrapper and variant. */\nconst alike = (a: string, b: string): boolean =>\n  a.replace(/[^a-z0-9]/gi, '').toLowerCase() ===\n  b.replace(/[^a-z0-9]/gi, '').toLowerCase();\n\n/**\n * The public generator and option value that select a hidden endpoint type.\n *\n * A wrapper like `ts#api` produces several endpoint types, choosing between them\n * with an enum option: `--framework=trpc` yields `ts#trpc-api`. The pairing is\n * found by looking for a same-language public generator with an enum value that\n * reconstructs the endpoint's own name.\n */\nconst findWrapper = (\n  endpointType: string,\n  schemaOf: SchemaResolver,\n): { generator: string; options: Record<string, string> } | undefined => {\n  const language = languageOf(endpointType);\n  const name = endpointType.slice(endpointType.indexOf('#') + 1);\n\n  for (const [generatorId, entry] of Object.entries(GENERATORS)) {\n    if (entry.hidden) continue;\n    if (languageOf(generatorId) !== language) continue;\n    const wrapperName = generatorId.slice(generatorId.indexOf('#') + 1);\n\n    for (const [option, property] of Object.entries(\n      schemaOf(generatorId).properties ?? {},\n    )) {\n      for (const value of property.enum ?? []) {\n        // Either the value names the variant outright (`react` for\n        // `react-website`), or it qualifies the wrapper's own name\n        // (`trpc` + `api` for `trpc-api`).\n        if (alike(value, name) || alike(`${value}${wrapperName}`, name)) {\n          return { generator: generatorId, options: { [option]: value } };\n        }\n      }\n    }\n  }\n  return undefined;\n};\n\n/**\n * Derive the recipe for one endpoint type. Exported so a test can assert the\n * derivation against every type the plugin supports.\n */\nexport const deriveScaffoldRecipe = (\n  endpointType: string,\n  schemaOf: SchemaResolver,\n): ScaffoldRecipe => {\n  const own = GENERATORS[endpointType];\n  if (!own) {\n    throw new Error(\n      `Scaffold catalog: connection endpoint '${endpointType}' is not a generator id`,\n    );\n  }\n\n  // A hidden generator is an implementation detail reached through its public\n  // wrapper, which is what a user would actually run.\n  const wrapper = own.hidden ? findWrapper(endpointType, schemaOf) : undefined;\n  if (own.hidden && !wrapper) {\n    throw new Error(\n      `Scaffold catalog: '${endpointType}' is hidden and no public generator selects it`,\n    );\n  }\n\n  // A generator requiring a `project` adds a component to one; anything else\n  // creates its own project.\n  const kind: ScaffoldKind = (schemaOf(endpointType).required ?? []).includes(\n    'project',\n  )\n    ? 'component'\n    : 'project';\n\n  const language = languageOf(endpointType);\n  const hostGenerator = `${language}#project`;\n  if (kind === 'component' && !GENERATORS[hostGenerator]) {\n    throw new Error(\n      `Scaffold catalog: '${endpointType}' is a component but '${hostGenerator}' does not exist to host it`,\n    );\n  }\n\n  return {\n    // `x-label` is the short noun a palette entry needs; `title` and\n    // `description` are prose aimed at CLI prompts (\"Create a relational database\n    // project\"). A generator without one falls back to its id, so a new endpoint\n    // type still appears rather than being dropped.\n    label: schemaOf(endpointType)['x-label'] ?? endpointType,\n    generator: wrapper?.generator ?? endpointType,\n    ...(wrapper ? { options: wrapper.options } : {}),\n    kind,\n    ...(kind === 'component'\n      ? {\n          host: {\n            generator: hostGenerator,\n            // Only options the host's schema actually requires, so a base\n            // project generator gaining a required option is handled here.\n            options: Object.fromEntries(\n              (schemaOf(hostGenerator).required ?? [])\n                .filter((option) => option !== 'name')\n                .map((option) => {\n                  const property = schemaOf(hostGenerator).properties?.[option];\n                  const value = property?.default ?? property?.enum?.[0];\n                  if (value === undefined) {\n                    throw new Error(\n                      `Scaffold catalog: '${hostGenerator}' requires '${option}' but its schema offers no value to use`,\n                    );\n                  }\n                  return [option, String(value)];\n                }),\n            ),\n            // Python project names are snake_cased when Nx qualifies them.\n            snakeCaseName: language === 'py',\n          },\n        }\n      : {}),\n  };\n};\n\n/** Every endpoint type appearing at either end of a supported connection. */\nexport const CONNECTION_ENDPOINT_TYPES: readonly string[] = [\n  ...new Set(\n    SUPPORTED_CONNECTIONS.flatMap(({ source, target }) => [source, target]),\n  ),\n].sort();\n\n/**\n * How to scaffold each connection endpoint type, derived from the generator\n * metadata. A connection added to `SUPPORTED_CONNECTIONS` appears here with no\n * edit to this file.\n */\nexport const buildScaffoldRecipes = (\n  schemaOf: SchemaResolver,\n): Readonly<Record<string, ScaffoldRecipe>> =>\n  Object.fromEntries(\n    CONNECTION_ENDPOINT_TYPES.map((type) => [\n      type,\n      deriveScaffoldRecipe(type, schemaOf),\n    ]),\n  );\n\n/**\n * A requirement one end of a connection places on the other's options, mirroring\n * the guard the corresponding connection generator enforces.\n *\n * Declared rather than derived: each guard is an imperative `throw` inside its\n * connection generator, reachable only by running it. Recording them here lets a\n * caller choosing options up front check them first, and the paired test asserts\n * every entry names a real option with a value its enum allows.\n */\nexport interface ConnectionConstraint {\n  /** Which end of the connection the constrained option belongs to. */\n  readonly side: 'source' | 'target';\n  /** The generator option carrying the constrained value. */\n  readonly option: string;\n  /** The only value accepted, if the option is pinned to one. */\n  readonly equals?: string;\n  /** A value rejected, for options accepting all but one. */\n  readonly notEquals?: string;\n  /** Why the constraint exists, phrased for the user choosing the option. */\n  readonly reason: string;\n}\n\n/** Reusable constraint shapes, so the map below states each rule once. */\nconst AGENT_TO_AGENT: readonly ConnectionConstraint[] = [\n  {\n    side: 'target',\n    option: 'protocol',\n    equals: 'a2a',\n    reason: 'Only an A2A agent can be connected to another agent as a tool.',\n  },\n  {\n    side: 'target',\n    option: 'auth',\n    equals: 'iam',\n    reason: 'A2A agent connections authenticate with IAM.',\n  },\n];\n\nconst WEBSITE_TO_AGENT: readonly ConnectionConstraint[] = [\n  {\n    side: 'target',\n    option: 'protocol',\n    notEquals: 'a2a',\n    reason:\n      'A2A agents are reached by other agents, not by a website. Use the http or ag-ui protocol.',\n  },\n];\n\nconst AGENT_TO_MCP: readonly ConnectionConstraint[] = [\n  {\n    side: 'target',\n    option: 'auth',\n    equals: 'iam',\n    reason: 'An agent reaches an MCP server with IAM authentication.',\n  },\n];\n\nconst AGENT_TO_GATEWAY: readonly ConnectionConstraint[] = [\n  {\n    side: 'source',\n    option: 'auth',\n    equals: 'iam',\n    reason: 'Only an IAM-authenticated agent can reach an IAM gateway.',\n  },\n  {\n    side: 'target',\n    option: 'auth',\n    equals: 'iam',\n    reason: 'Agent connections require the gateway to authenticate with IAM.',\n  },\n];\n\nconst GATEWAY_TO_MCP: readonly ConnectionConstraint[] = [\n  {\n    side: 'source',\n    option: 'protocol',\n    equals: 'mcp',\n    reason:\n      'MCP server targets can only be attached to an mcp-protocol gateway.',\n  },\n  {\n    side: 'target',\n    option: 'auth',\n    equals: 'iam',\n    reason: 'A gateway reaches an MCP server target with IAM authentication.',\n  },\n];\n\nconst GATEWAY_TO_AGENT: readonly ConnectionConstraint[] = [\n  {\n    side: 'source',\n    option: 'protocol',\n    equals: 'http',\n    reason:\n      'Agent runtime targets can only be attached to an http-protocol gateway.',\n  },\n  {\n    side: 'target',\n    option: 'auth',\n    equals: 'iam',\n    reason: 'The gateway signs requests to its agent targets with IAM.',\n  },\n];\n\n/**\n * The option-level requirements each connection places on its endpoints.\n *\n * Only connections carrying a requirement appear. Keyed by `ConnectionKey`, so a\n * key that no longer names a supported connection is a compile error.\n */\nexport const CONNECTION_CONSTRAINTS = {\n  'ts#react-website -> ts#agent': WEBSITE_TO_AGENT,\n  'ts#react-website -> py#agent': WEBSITE_TO_AGENT,\n  'ts#agent -> ts#agent': AGENT_TO_AGENT,\n  'ts#agent -> py#agent': AGENT_TO_AGENT,\n  'py#agent -> ts#agent': AGENT_TO_AGENT,\n  'py#agent -> py#agent': AGENT_TO_AGENT,\n  'ts#agent -> ts#mcp-server': AGENT_TO_MCP,\n  'ts#agent -> py#mcp-server': AGENT_TO_MCP,\n  'py#agent -> ts#mcp-server': AGENT_TO_MCP,\n  'py#agent -> py#mcp-server': AGENT_TO_MCP,\n  'ts#agent -> agentcore-gateway': AGENT_TO_GATEWAY,\n  'py#agent -> agentcore-gateway': AGENT_TO_GATEWAY,\n  'ts#react-website -> agentcore-gateway': [\n    {\n      side: 'target',\n      option: 'protocol',\n      equals: 'http',\n      reason:\n        'A website connects to an http-protocol gateway, which proxies requests to its agent targets.',\n    },\n  ],\n  'agentcore-gateway -> ts#agent': [\n    ...GATEWAY_TO_AGENT,\n    {\n      side: 'target',\n      option: 'protocol',\n      notEquals: 'http',\n      reason:\n        'A TypeScript http agent serves tRPC over WebSocket, which AgentCore Gateway does not support. Use the ag-ui or a2a protocol.',\n    },\n  ],\n  'agentcore-gateway -> py#agent': GATEWAY_TO_AGENT,\n  'agentcore-gateway -> ts#mcp-server': GATEWAY_TO_MCP,\n  'agentcore-gateway -> py#mcp-server': GATEWAY_TO_MCP,\n  'agentcore-gateway -> agentcore-gateway': [\n    {\n      side: 'source',\n      option: 'protocol',\n      equals: 'mcp',\n      reason:\n        'A gateway is aggregated into another as an MCP target, so both must be mcp-protocol gateways.',\n    },\n    {\n      side: 'target',\n      option: 'protocol',\n      equals: 'mcp',\n      reason:\n        'A gateway is aggregated into another as an MCP target, so both must be mcp-protocol gateways.',\n    },\n    {\n      side: 'target',\n      option: 'auth',\n      equals: 'iam',\n      reason:\n        'The source gateway signs its request with IAM, so the target gateway must accept IAM.',\n    },\n  ],\n} as const satisfies Partial<\n  Record<ConnectionKey, readonly ConnectionConstraint[]>\n>;\n\n/**\n * A generator run automatically after an endpoint is scaffolded, adding something\n * that endpoint should always have.\n *\n * A website is only useful with authentication in front of it, and `ts#website`\n * does not add it — `ts#website#auth` is a separate follow-up generator. Declared\n * here so the docs graph builder emits it without hardcoding the pairing.\n */\nexport interface FollowUpGenerator {\n  /** The generator id to run after the endpoint's own. */\n  readonly generator: string;\n  /** Options to pass, beyond the `--project` naming the endpoint. */\n  readonly options?: Readonly<Record<string, string>>;\n  /** What it adds, for the emitted command's comment. */\n  readonly adds: string;\n}\n\n/**\n * Generators run automatically after an endpoint type is scaffolded, keyed by\n * endpoint type.\n */\nexport const ENDPOINT_FOLLOW_UPS: Readonly<\n  Record<string, readonly FollowUpGenerator[]>\n> = {\n  'ts#react-website': [\n    {\n      generator: 'ts#website#auth',\n      // `cognitoDomain` is derived from the npm scope and project name when\n      // omitted, so the command stays short.\n      adds: 'Cognito authentication',\n    },\n  ],\n};\n\n/**\n * An option value a connection works best against, without requiring it.\n *\n * Distinct from `CONNECTION_CONSTRAINTS`: a constraint is a rule the connection\n * generator enforces, whereas a preference is the setting most users want. A\n * React website can call an `http` agent perfectly well, but AG-UI is the\n * protocol built for driving a frontend, so that is what a new connection picks.\n *\n * A caller applies these only where the user has not chosen the option, so a\n * preference never overrides a deliberate decision.\n */\nexport interface ConnectionPreference {\n  readonly side: 'source' | 'target';\n  readonly option: string;\n  readonly value: string;\n  /** Why this is the better default, phrased for the user. */\n  readonly reason: string;\n}\n\n/** An agent target only attaches to an http gateway, an MCP server only to an mcp one. */\nconst GATEWAY_PREFERS_HTTP: ConnectionPreference = {\n  side: 'source',\n  option: 'protocol',\n  value: 'http',\n  reason:\n    'Agent runtime targets are proxied by an http gateway, so attaching an agent selects that protocol.',\n};\n\nconst GATEWAY_PREFERS_MCP: ConnectionPreference = {\n  side: 'source',\n  option: 'protocol',\n  value: 'mcp',\n  reason:\n    'MCP server targets are aggregated by an mcp gateway, so attaching an MCP server selects that protocol.',\n};\n\n/**\n * Preferred option values per connection. Keyed by `ConnectionKey`, so a key that\n * no longer names a supported connection is a compile error.\n */\nexport const CONNECTION_PREFERENCES = {\n  'ts#react-website -> ts#agent': [\n    {\n      side: 'target',\n      option: 'protocol',\n      value: 'ag-ui',\n      reason:\n        'AG-UI is the protocol built for driving a frontend, so a website connection selects it.',\n    },\n  ],\n  'ts#react-website -> py#agent': [\n    {\n      side: 'target',\n      option: 'protocol',\n      value: 'ag-ui',\n      reason:\n        'AG-UI is the protocol built for driving a frontend, so a website connection selects it.',\n    },\n  ],\n  // A gateway's protocol is decided by what it fronts, and the two are mutually\n  // exclusive: agent runtime targets need an http gateway, MCP server targets an\n  // mcp one. The gateway schema defaults to mcp, so only the agent side needs a\n  // preference — but both are stated, so whichever target the user attaches\n  // first settles the protocol.\n  'agentcore-gateway -> ts#agent': [GATEWAY_PREFERS_HTTP],\n  'agentcore-gateway -> py#agent': [GATEWAY_PREFERS_HTTP],\n  'agentcore-gateway -> ts#mcp-server': [GATEWAY_PREFERS_MCP],\n  'agentcore-gateway -> py#mcp-server': [GATEWAY_PREFERS_MCP],\n  'ts#react-website -> agentcore-gateway': [\n    {\n      side: 'target',\n      option: 'protocol',\n      value: 'http',\n      reason:\n        'A website reaches a gateway’s agent targets over path-based http routing, so the gateway serves the http protocol.',\n    },\n  ],\n} as const satisfies Partial<\n  Record<ConnectionKey, readonly ConnectionPreference[]>\n>;\n\n/**\n * Connections that must be generated after another, because the generator reads\n * state the earlier one records.\n *\n * The website→gateway generator publishes a route per agent already attached to\n * the gateway, reading them from the gateway project's connection metadata. Run\n * before the gateway→agent connections, it finds none and wires up nothing.\n *\n * Keyed by `ConnectionKey`, so a key that no longer names a supported connection\n * is a compile error.\n */\nexport const CONNECTION_ORDERING = {\n  'ts#react-website -> agentcore-gateway': {\n    after: ['agentcore-gateway -> ts#agent', 'agentcore-gateway -> py#agent'],\n    reason:\n      'The website connection publishes a route per agent attached to the gateway, so the gateway’s agents must be attached first.',\n  },\n} as const satisfies Partial<\n  Record<\n    ConnectionKey,\n    { readonly after: readonly ConnectionKey[]; readonly reason: string }\n  >\n>;\n\n/**\n * Connections whose source and target must be distinct projects, because the\n * connection generator refuses to wire a project to itself.\n */\nexport const SELF_CONNECTION_DISALLOWED = [\n  'agentcore-gateway -> agentcore-gateway',\n] as const satisfies readonly ConnectionKey[];\n"],"names":["GeneratorsJson","type","SUPPORTED_CONNECTIONS","GENERATORS","generators","schemaPathOf","generatorId","entry","Error","schema","languageOf","id","includes","slice","indexOf","alike","a","b","replace","toLowerCase","findWrapper","endpointType","schemaOf","language","name","Object","entries","hidden","wrapperName","option","property","properties","value","enum","generator","options","undefined","deriveScaffoldRecipe","own","wrapper","kind","required","hostGenerator","label","host","fromEntries","filter","map","default","String","snakeCaseName","CONNECTION_ENDPOINT_TYPES","Set","flatMap","source","target","sort","buildScaffoldRecipes","AGENT_TO_AGENT","side","equals","reason","WEBSITE_TO_AGENT","notEquals","AGENT_TO_MCP","AGENT_TO_GATEWAY","GATEWAY_TO_MCP","GATEWAY_TO_AGENT","CONNECTION_CONSTRAINTS","ENDPOINT_FOLLOW_UPS","adds","GATEWAY_PREFERS_HTTP","GATEWAY_PREFERS_MCP","CONNECTION_PREFERENCES","CONNECTION_ORDERING","after","SELF_CONNECTION_DISALLOWED"],"mappings":"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"}

package/src/connection/schema-resolver.d.ts

@@ -0,0 +1,5 @@
+import { type ScaffoldRecipe, type SchemaResolver } from './scaffold-catalog';
+/** Reads schemas from disk, for the plugin and its tests. */
+export declare const nodeSchemaResolver: SchemaResolver;
+/** The scaffold recipes, resolved from the schemas on disk. */
+export declare const SCAFFOLD_RECIPES: Readonly<Record<string, ScaffoldRecipe>>;

package/src/connection/schema-resolver.js

@@ -0,0 +1,27 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { readFileSync } from "node:fs";
+import * as path from "node:path";
+import { buildScaffoldRecipes, schemaPathOf } from "./scaffold-catalog.js";
+/** Reads schemas from disk, for the plugin and its tests. */ export const nodeSchemaResolver = (()=>{
+    const cache = new Map();
+    return (generatorId)=>{
+        const cached = cache.get(generatorId);
+        if (cached) return cached;
+        // This module lives at src/connection/, and the recorded path is relative to
+        // the plugin root, so resolve from two levels up.
+        const schemaPath = path.resolve(import.meta.dirname, '..', '..', schemaPathOf(generatorId));
+        let schema;
+        try {
+            schema = JSON.parse(readFileSync(schemaPath, 'utf-8'));
+        } catch (error) {
+            throw new Error(`Scaffold catalog: could not read the schema for '${generatorId}' at ${schemaPath}: ${error}`);
+        }
+        cache.set(generatorId, schema);
+        return schema;
+    };
+})();
+/** The scaffold recipes, resolved from the schemas on disk. */ export const SCAFFOLD_RECIPES = buildScaffoldRecipes(nodeSchemaResolver);
+
+//# sourceMappingURL=schema-resolver.js.map

package/src/connection/schema-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../packages/nx-plugin/src/connection/schema-resolver.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 * as path from 'node:path';\nimport {\n  buildScaffoldRecipes,\n  type GeneratorSchema,\n  type ScaffoldRecipe,\n  type SchemaResolver,\n  schemaPathOf,\n} from './scaffold-catalog';\n\n/** Reads schemas from disk, for the plugin and its tests. */\nexport const nodeSchemaResolver: SchemaResolver = (() => {\n  const cache = new Map<string, GeneratorSchema>();\n  return (generatorId: string): GeneratorSchema => {\n    const cached = cache.get(generatorId);\n    if (cached) return cached;\n    // This module lives at src/connection/, and the recorded path is relative to\n    // the plugin root, so resolve from two levels up.\n    const schemaPath = path.resolve(\n      import.meta.dirname,\n      '..',\n      '..',\n      schemaPathOf(generatorId),\n    );\n    let schema: GeneratorSchema;\n    try {\n      schema = JSON.parse(readFileSync(schemaPath, 'utf-8'));\n    } catch (error) {\n      throw new Error(\n        `Scaffold catalog: could not read the schema for '${generatorId}' at ${schemaPath}: ${error}`,\n      );\n    }\n    cache.set(generatorId, schema);\n    return schema;\n  };\n})();\n\n/** The scaffold recipes, resolved from the schemas on disk. */\nexport const SCAFFOLD_RECIPES: Readonly<Record<string, ScaffoldRecipe>> =\n  buildScaffoldRecipes(nodeSchemaResolver);\n"],"names":["readFileSync","path","buildScaffoldRecipes","schemaPathOf","nodeSchemaResolver","cache","Map","generatorId","cached","get","schemaPath","resolve","dirname","schema","JSON","parse","error","Error","set","SCAFFOLD_RECIPES"],"mappings":"AAAA;;;CAGC,GACD,SAASA,YAAY,QAAQ,UAAU;AACvC,YAAYC,UAAU,YAAY;AAClC,SACEC,oBAAoB,EAIpBC,YAAY,QACP,wBAAqB;AAE5B,2DAA2D,GAC3D,OAAO,MAAMC,qBAAqC,AAAC,CAAA;IACjD,MAAMC,QAAQ,IAAIC;IAClB,OAAO,CAACC;QACN,MAAMC,SAASH,MAAMI,GAAG,CAACF;QACzB,IAAIC,QAAQ,OAAOA;QACnB,6EAA6E;QAC7E,kDAAkD;QAClD,MAAME,aAAaT,KAAKU,OAAO,CAC7B,YAAYC,OAAO,EACnB,MACA,MACAT,aAAaI;QAEf,IAAIM;QACJ,IAAI;YACFA,SAASC,KAAKC,KAAK,CAACf,aAAaU,YAAY;QAC/C,EAAE,OAAOM,OAAO;YACd,MAAM,IAAIC,MACR,CAAC,iDAAiD,EAAEV,YAAY,KAAK,EAAEG,WAAW,EAAE,EAAEM,OAAO;QAEjG;QACAX,MAAMa,GAAG,CAACX,aAAaM;QACvB,OAAOA;IACT;AACF,CAAA,IAAK;AAEL,6DAA6D,GAC7D,OAAO,MAAMM,mBACXjB,qBAAqBE,oBAAoB"}

package/src/connection/schema.d.js

@@ -0,0 +1,6 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ export { };
+
+//# sourceMappingURL=schema.d.js.map

package/src/connection/schema.d.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../packages/nx-plugin/src/connection/schema.d.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\n\nexport interface ConnectionGeneratorSchema {\n  sourceProject: string;\n  targetProject: string;\n  sourceComponent?: string;\n  targetComponent?: string;\n  preferInstallDependencies?: boolean;\n}\n"],"names":[],"mappings":"AAAA;;;CAGC,GAED,WAMC"}

package/src/connection/schema.d.ts

@@ -8,4 +8,5 @@ export interface ConnectionGeneratorSchema {
   targetProject: string;
   sourceComponent?: string;
   targetComponent?: string;
+  preferInstallDependencies?: boolean;
 }

package/src/connection/schema.json

@@ -27,6 +27,11 @@
     "targetComponent": {
       "type": "string",
       "description": "The target component to connect to (component name, path relative to target project root, or generator id). Use '.' to explicitly select the project as the target."
+    },
+    "preferInstallDependencies": {
+      "type": "boolean",
+      "description": "Whether to prefer installing dependencies after the generator runs. 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.",
+      "default": true
     }
   },
   "required": ["sourceProject", "targetProject"]

package/src/connection/supported-connections.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export type Connection = {
+    source: string;
+    target: string;
+};
+export declare const SUPPORTED_PROJECT_TYPES: readonly ["ts#trpc-api", "py#fast-api", "ts#react-website", "ts#smithy-api", "ts#rdb", "py#rdb", "ts#dynamodb", "py#dynamodb", "agentcore-gateway"];
+export declare const SUPPORTED_CONNECTIONS: readonly [{
+    readonly source: "ts#trpc-api";
+    readonly target: "ts#rdb";
+}, {
+    readonly source: "ts#trpc-api";
+    readonly target: "ts#dynamodb";
+}, {
+    readonly source: "ts#agent";
+    readonly target: "ts#rdb";
+}, {
+    readonly source: "ts#smithy-api";
+    readonly target: "ts#rdb";
+}, {
+    readonly source: "ts#smithy-api";
+    readonly target: "ts#dynamodb";
+}, {
+    readonly source: "ts#mcp-server";
+    readonly target: "ts#rdb";
+}, {
+    readonly source: "ts#mcp-server";
+    readonly target: "ts#dynamodb";
+}, {
+    readonly source: "ts#react-website";
+    readonly target: "ts#trpc-api";
+}, {
+    readonly source: "ts#react-website";
+    readonly target: "py#fast-api";
+}, {
+    readonly source: "ts#react-website";
+    readonly target: "ts#smithy-api";
+}, {
+    readonly source: "ts#react-website";
+    readonly target: "ts#agent";
+}, {
+    readonly source: "ts#react-website";
+    readonly target: "py#agent";
+}, {
+    readonly source: "ts#agent";
+    readonly target: "ts#mcp-server";
+}, {
+    readonly source: "ts#agent";
+    readonly target: "py#mcp-server";
+}, {
+    readonly source: "ts#agent";
+    readonly target: "ts#dynamodb";
+}, {
+    readonly source: "py#agent";
+    readonly target: "ts#mcp-server";
+}, {
+    readonly source: "py#agent";
+    readonly target: "py#mcp-server";
+}, {
+    readonly source: "ts#agent";
+    readonly target: "ts#agent";
+}, {
+    readonly source: "ts#agent";
+    readonly target: "py#agent";
+}, {
+    readonly source: "py#agent";
+    readonly target: "ts#agent";
+}, {
+    readonly source: "py#agent";
+    readonly target: "py#agent";
+}, {
+    readonly source: "ts#agent";
+    readonly target: "agentcore-gateway";
+}, {
+    readonly source: "py#agent";
+    readonly target: "agentcore-gateway";
+}, {
+    readonly source: "ts#react-website";
+    readonly target: "agentcore-gateway";
+}, {
+    readonly source: "agentcore-gateway";
+    readonly target: "ts#agent";
+}, {
+    readonly source: "agentcore-gateway";
+    readonly target: "py#agent";
+}, {
+    readonly source: "agentcore-gateway";
+    readonly target: "ts#mcp-server";
+}, {
+    readonly source: "agentcore-gateway";
+    readonly target: "py#mcp-server";
+}, {
+    readonly source: "agentcore-gateway";
+    readonly target: "agentcore-gateway";
+}, {
+    readonly source: "py#fast-api";
+    readonly target: "py#dynamodb";
+}, {
+    readonly source: "py#agent";
+    readonly target: "py#dynamodb";
+}, {
+    readonly source: "py#mcp-server";
+    readonly target: "py#dynamodb";
+}, {
+    readonly source: "py#fast-api";
+    readonly target: "py#rdb";
+}, {
+    readonly source: "py#agent";
+    readonly target: "py#rdb";
+}, {
+    readonly source: "py#mcp-server";
+    readonly target: "py#rdb";
+}];
+export type ConnectionKey = (typeof SUPPORTED_CONNECTIONS)[number] extends infer C ? C extends Connection ? `${C['source']} -> ${C['target']}` : never : never;