@aws/nx-plugin-mcp 1.0.0-rc.52 → 1.0.0-rc.54

package/bin/aws-nx-mcp.js

@@ -54200,9 +54200,9 @@ var generators$1 = {
 	"smithy#project": {
 		"factory": "./src/smithy/project/generator",
 		"schema": "./src/smithy/project/schema.json",
-		"description": "Generate a Smithy model project",
+		"description": "Generate a Smithy model project, either defining a service or a library of reusable shapes",
 		"metric": "g27",
-		"hidden": true
+		"guidePages": ["smithy-project"]
 	},
 	"smithy#react-connection": {
 		"factory": "./src/smithy/react-connection/generator",

package/docs/guides/smithy-project.mdx

@@ -0,0 +1,175 @@
+---
+title: Smithy Projects
+description: Reference documentation for the Smithy project generator
+generator: smithy#project
+---
+import { FileTree, Steps } from '@astrojs/starlight/components';
+import RunGenerator from '@components/run-generator.astro';
+import Link from '@components/link.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import OptionFilter from '@components/option-filter.astro';
+
+[Smithy](https://smithy.io/) is an interface definition language for describing services and the data they exchange. The Smithy project generator creates a project containing a Smithy model.
+
+There are two kinds of Smithy project:
+
+- **Service** (`--type=service`) — a model which defines a service and its operations. This is what the <Link path="guides/ts-smithy-api">`ts#api --framework=smithy` generator</Link> creates for you alongside a TypeScript implementation.
+- **Shape library** (`--type=shapes`) — a model which defines reusable shapes but no service. Connect a shape library to your Smithy projects to share shapes between them, rather than duplicating the definitions in each.
+
+:::tip
+If you want an API with an implementation, use the <Link path="guides/ts-smithy-api">`ts#api` generator</Link> instead. It creates a Smithy model project _and_ a TypeScript server which implements it.
+:::
+
+## Usage
+
+### Generate a Smithy Project
+
+<RunGenerator generator="smithy#project" requiredParameters={{ name: 'my-shapes' }} />
+
+### Options
+
+<GeneratorParameters generator="smithy#project" />
+
+## Generator Output
+
+<OptionFilter when={{ type: 'shapes' }} description="Shape library: a model with no service">
+
+### Shape Library
+
+<FileTree>
+
+  - my-shapes
+    - src
+      - main.smithy Your shared shape definitions
+    - smithy-build.json Smithy build configuration
+    - build.Dockerfile Builds and validates the model
+    - project.json Project configuration and build targets
+
+</FileTree>
+
+A shape library defines shapes and nothing else:
+
+```smithy
+$version: "2.0"
+
+namespace com.example
+
+structure Customer {
+    @required
+    id: String
+
+    name: String
+    email: String
+}
+```
+
+Since a shape library has no service, its `smithy-build.json` configures no code generation — building it validates the model and assembles it into a single JSON model file at `dist/<my-shapes>/build/model/model.json`.
+
+</OptionFilter>
+
+<OptionFilter when={{ type: 'service' }} description="Service: a model which defines a service and its operations">
+
+### Service
+
+<FileTree>
+
+  - my-service
+    - src
+      - main.smithy Your service definition
+      - operations
+        - echo.smithy An example operation
+    - smithy-build.json Smithy build configuration, including code generation
+    - build.Dockerfile Builds the model, OpenAPI spec and TypeScript Server SDK
+    - project.json Project configuration and build targets
+
+</FileTree>
+
+A service model defines a service shape and the operations it exposes:
+
+```smithy
+$version: "2.0"
+
+namespace com.example
+
+use aws.protocols#restJson1
+
+@title("MyService")
+@restJson1
+service MyService {
+    version: "1.0.0"
+    operations: [
+        Echo
+    ]
+}
+```
+
+Building a service project generates an OpenAPI specification and a TypeScript Server SDK into `dist/<my-service>/build/`.
+
+</OptionFilter>
+
+## Building
+
+Smithy projects build using [Docker](https://www.docker.com/), which runs the [Smithy CLI](https://smithy.io/2.0/guides/smithy-cli/index.html) to validate your model:
+
+<NxCommands commands={['build my-shapes']} />
+
+## Depending on a Shape Library
+
+Building a shape library writes an assembled model to `dist/<my-shapes>/build/model/model.json`. This single file contains every shape the library defines, along with any it depends on, so a consumer only ever declares the libraries it references directly.
+
+To depend on a shape library from another Smithy project, make three changes to the consuming project:
+
+<Steps>
+
+1. Smithy projects build inside a container, and the build is given the workspace root as a named build context. Add a `COPY` to the consuming project's `build.Dockerfile`, alongside where its own sources are copied in:
+
+   ```dockerfile ins={4}
+   # Copy project files
+   COPY smithy-build.json .
+   COPY src src
+   COPY --from=workspace dist/packages/my-shapes/build/model/model.json deps/my-shapes.json
+   ```
+
+2. Add the copied file to `imports` in the consuming project's `smithy-build.json`:
+
+   ```json ins={4}
+   {
+     "version": "1.0",
+     "sources": ["src/"],
+     "imports": ["deps/my-shapes.json"],
+     ...
+   }
+   ```
+
+3. Add the library's `build` target as a dependency of the consuming project's `compile` target in its `project.json`, so the model exists before the consumer builds:
+
+   ```json ins={4}
+   {
+     "targets": {
+       "compile": {
+         "dependsOn": ["@my-scope/my-shapes:build"],
+         ...
+       }
+     }
+   }
+   ```
+
+</Steps>
+
+Your model can now reference the library's shapes with `use`:
+
+```smithy
+$version: "2.0"
+
+namespace com.example.api
+
+use com.example.shared#Customer
+
+structure GetCustomerOutput {
+    @required
+    customer: Customer
+}
+```
+
+Shape libraries can depend on other shape libraries the same way. Since each library's built model already contains its own dependencies, you only need to repeat these steps for the libraries you reference directly. A library reached by more than one path is resolved once — Smithy ignores duplicate but equivalent shape definitions.

package/docs/guides/ts-smithy-api.mdx

@@ -224,6 +224,31 @@ You can change the folder structure however you like - all `.smithy` files in th
 For more details on Smithy and its syntax, refer to the [Smithy specification](https://smithy.io/2.0/spec/index.html).
 :::
 
+### Adding a Shape Library
+
+If you have several Smithy APIs which share the same data types, you can define those types once in a shape library rather than duplicating them in each model. A shape library is a Smithy project with no service — just reusable shapes — which any number of Smithy projects can depend on.
+
+Generate one with the <Link path="guides/smithy-project">`smithy#project`</Link> generator:
+
+<RunGenerator generator="smithy#project" requiredParameters={{ name: 'my-shapes', type: 'shapes' }} />
+
+Your API's model can then reference its shapes with `use`:
+
+```smithy
+$version: "2.0"
+
+namespace com.example.api
+
+use com.example.shared#Customer
+
+structure GetCustomerOutput {
+    @required
+    customer: Customer
+}
+```
+
+See the <Link path="guides/smithy-project">Smithy project guide</Link> for how to create a shape library and wire it up as a dependency of your API's model.
+
 ### Implementing Operations in TypeScript
 
 Operation implementations are located in the backend project's `src/operations/` directory. Each operation is implemented using the generated types from the TypeScript Server SDK (generated at build time from your Smithy model).

package/docs/snippets/pdk-migration/faq/type-safe-api.mdx

@@ -77,117 +77,11 @@ For TypeScript, check out [Smithy TypeScript](https://github.com/smithy-lang/smi
 
 Type Safe API provided a Projen project type named `SmithyShapeLibraryProject` which configured a project which contained Smithy models which could be reused by multiple Smithy-based APIs.
 
-The most straightforward way to achieve this is to do the following:
+The equivalent is the <Link path="/guides/smithy-project">`smithy#project` generator</Link> with `type` set to `shapes`:
 
-###### Create a Shape Library
+<RunGenerator generator="smithy#project" requiredParameters={{ name: 'my-shapes', type: 'shapes' }} />
 
-<Steps>
-
-1. Create your shape library using the `smithy#project` generator:
-
-    <RunGenerator generator="smithy#project" />
-
-    Specify any name for the `serviceName` option, as we will remove the `service` shape.
-
-    :::note
-    This generator is hidden at the time of writing and so you will need to execute it via the CLI.
-    :::
-
-1. Replace the default model in `src` with the shapes you wish to define
-
-1. Update `smithy-build.json` to remove the `plugins` and any unused maven dependencies
-
-1. Replace `build.Dockerfile` with minimal build steps:
-
-    ```docker
-    // build.Dockerfile
-    FROM public.ecr.aws/docker/library/node:24 AS builder
-
-    # Output directory
-    RUN mkdir /out
-
-    # Install Smithy CLI
-    # https://smithy.io/2.0/guides/smithy-cli/cli_installation.html
-    WORKDIR /smithy
-    ARG TARGETPLATFORM
-    RUN if [ "$TARGETPLATFORM" = "linux/arm64" ]; then ARCH="aarch64"; else ARCH="x86_64"; fi && \
-        mkdir -p smithy-install/smithy && \
-        curl -L https://github.com/smithy-lang/smithy/releases/download/1.61.0/smithy-cli-linux-$ARCH.zip -o smithy-install/smithy-cli-linux-$ARCH.zip && \
-        unzip -qo smithy-install/smithy-cli-linux-$ARCH.zip -d smithy-install && \
-        mv smithy-install/smithy-cli-linux-$ARCH/* smithy-install/smithy
-    RUN smithy-install/smithy/install
-
-    # Copy project files
-    COPY smithy-build.json .
-    COPY src src
-
-    # Smithy build with Maven cache mount
-    RUN --mount=type=cache,target=/root/.m2/repository,id=maven-cache \
-        smithy build
-
-    RUN cp -r build/* /out/
-
-    # Export the /out directory
-    FROM scratch AS export
-    COPY --from=builder /out /
-    ```
-
-</Steps>
-
-###### Consume the Shape Library
-
-In your service model project(s), make the following changes to consume the shape library:
-
-<Steps>
-
-1. Update the `compile` target in `project.json` to add the workspace as build context, and a dependency on the shape library's `build` target
-
-    ```json {10,15} "--build-context workspace=." "@my-project/shapes:build"
-    // project.json
-    {
-      "cache": true,
-      "outputs": ["{workspaceRoot}/dist/{projectRoot}/build"],
-      "executor": "nx:run-commands",
-      "options": {
-        "commands": [
-          "rimraf dist/packages/api/model/build",
-          "make-dir dist/packages/api/model/build",
-          "docker build --build-context workspace=. -f packages/api/model/build.Dockerfile --target export --output type=local,dest=dist/packages/api/model/build packages/api/model"
-        ],
-        "parallel": false,
-        "cwd": "{workspaceRoot}"
-      },
-      "dependsOn": ["@my-project/shapes:build"]
-    }
-    ```
-
-1. Update the `build.Dockerfile` to copy the `src` directory from your shape library. For example, assuming the shape library is located in `packages/shapes`:
-
-    ```docker {5}
-    // build.Dockerfile
-    # Copy project files
-    COPY smithy-build.json .
-    COPY src src
-    COPY --from=workspace packages/shapes/src shapes
-    ```
-
-1. Update `smithy-build.json` to add the shapes directory to its `sources`:
-
-    ```json {4} "shapes/"
-    // smithy-build.json
-    {
-      "version": "1.0",
-      "sources": ["src/", "shapes/"],
-      "plugins": {
-      ...
-    }
-    ```
-
-</Steps>
-
-:::note
-Please express your interest on the [GitHub issue here](https://github.com/awslabs/nx-plugin-for-aws/issues/304) if you have a use case for a dedicated Smithy shape library generator.
-:::
+Move the shapes from your `SmithyShapeLibraryProject` into the generated project's `src` folder, then refer to the <Link path="/guides/smithy-project#depending-on-a-shape-library">Smithy project guide</Link> for how to wire the library up as a dependency of your API's model.
 
 #### Interceptors
 

package/docs/snippets/prerequisites.mdx

@@ -11,7 +11,7 @@ import Snippet from '@components/snippet.astro';
 ### Recommended
 
 - [AWS Credentials](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) configured to your target AWS account are required to deploy your application (as well as for some local development workflows).
-- [Docker](https://www.docker.com/) or [Finch](https://runfinch.com/) is required for some generators. For Docker, [multi-platform builds](https://docs.docker.com/build/building/multi-platform/) must be set up; Finch supports [multi-platform builds](https://runfinch.com/docs/getting-started/building-images/#building-a-multi-architecture-container-image) out of the box.
+- [Docker](https://www.docker.com/) or [Finch >= 1.6.0](https://runfinch.com/) is required for some generators. For Docker, [multi-platform builds](https://docs.docker.com/build/building/multi-platform/) must be set up; Finch supports [multi-platform builds](https://runfinch.com/docs/getting-started/building-images/#building-a-multi-architecture-container-image) out of the box.
 - [Terraform >= 1.12](https://developer.hashicorp.com/terraform/install) is required if you choose to use this for infrastructure as code instead of CDK
   - verify by running `terraform --version`
 - If you are using [VSCode](https://code.visualstudio.com/), we recommend installing the [Nx Console VSCode Plugin](https://marketplace.visualstudio.com/items?itemName=nrwl.angular-console).

package/generators.json

@@ -165,9 +165,9 @@
     "smithy#project": {
       "factory": "./src/smithy/project/generator",
       "schema": "./src/smithy/project/schema.json",
-      "description": "Generate a Smithy model project",
+      "description": "Generate a Smithy model project, either defining a service or a library of reusable shapes",
       "metric": "g27",
-      "hidden": true
+      "guidePages": ["smithy-project"]
     },
     "smithy#react-connection": {
       "factory": "./src/smithy/react-connection/generator",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/nx-plugin-mcp",
-  "version": "1.0.0-rc.52",
+  "version": "1.0.0-rc.54",
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/nx-plugin-for-aws.git",

package/src/smithy/project/schema.json

@@ -15,9 +15,31 @@
       "x-priority": "important",
       "x-prompt": "What would you like to call your Smithy project?"
     },
+    "type": {
+      "type": "string",
+      "description": "The type of Smithy project to create. Choose between service (a model with a service shape, ready for an implementation) and shapes (a shape library of reusable shapes, shared between multiple Smithy projects).",
+      "default": "service",
+      "enum": ["service", "shapes"],
+      "x-priority": "important",
+      "x-prompt": {
+        "message": "What type of Smithy project would you like to create?",
+        "type": "list",
+        "items": [
+          {
+            "value": "service",
+            "label": "service (a model which defines a service and its operations)"
+          },
+          {
+            "value": "shapes",
+            "label": "shapes (a library of reusable shapes, shared between Smithy projects)"
+          }
+        ],
+        "default": "service"
+      }
+    },
     "serviceName": {
       "type": "string",
-      "description": "The name of your Smithy service. Uses the supplied name by default.",
+      "description": "The name of your Smithy service. Uses the supplied name by default. Not applicable to shape libraries.",
       "x-prompt": "What name would you like your Smithy Service to have? i.e: MyService"
     },
     "namespace": {