Corymhall/extract convert core

.github/actions/build/action.yml

@@ -11,7 +11,7 @@ runs:
     - name: Setup Node
       uses: actions/setup-node@v4
       with:
-        node-version: 18.x
+        node-version: 22.x
         registry-url: https://registry.npmjs.org
     - name: Install Yarn
       shell: bash

.github/actions/lint/action.yml

@@ -7,7 +7,7 @@ runs:
     - name: Setup Node
       uses: actions/setup-node@v4
       with:
-        node-version: 18.x
+        node-version: 22.x
         registry-url: https://registry.npmjs.org
     - name: Install Yarn
       shell: bash

.github/workflows/acceptance-tests.yml

@@ -38,7 +38,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: 18.x
+          node-version: 22.x
           registry-url: https://registry.npmjs.org
       - name: Install Go
         uses: actions/setup-go@v5

.github/workflows/main.yml

@@ -78,7 +78,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: 18.x
+          node-version: 22.x
           registry-url: https://registry.npmjs.org
       - name: Install Yarn
         run: curl -o- -L https://yarnpkg.com/install.sh | bash -s -- --version 1.13.0

.github/workflows/release.yml

@@ -72,7 +72,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: 18.x
+          node-version: 22.x
           registry-url: https://registry.npmjs.org
       - name: Install Yarn
         run: curl -o- -L https://yarnpkg.com/install.sh | bash -s -- --version 1.13.0

.gitignore

@@ -115,11 +115,17 @@ dist
 test-reports/
 lib/
 
-**/cdk.out
+**/cdk*.out
 **/cdk.context.json
 
 # direnv
 .envrc
 
 # Emacs
 .dir-locals.el
+
+.p
+import.json
+cdk-to-pulumi
+Pulumi.yaml
+Pulumi-*.yaml

AGENTS.md

@@ -0,0 +1,26 @@
+# Agent Handoff
+
+Welcome! To continue the CDK-to-Pulumi CLI prototype:
+
+1. Read `spec.md` for the full implementation plan and TODO checklist.
+2. Update the checklist in `spec.md` as you complete tasks.
+3. Keep this file up to date if the handoff process changes.
+
+Thanks and good luck!
+
+## Status Updates
+
+- See `spec.md` for the authoritative implementation plan, checklist, and latest status.
+- Remember to commit frequently as you land logical chunks so handoffs stay easy to follow.
+
+## CLI Prototype Workflow
+
+- The experimental `cdk-to-pulumi` CLI lives under `src/cli/cli-runner.ts` and is also exposed via `./bin/cdk-to-pulumi`.
+- Usage pattern:
+  1. Synthesize the target CDK app so `cdk.out/` exists.
+  2. Run `npx ts-node src/cli/cli-runner.ts --assembly ./cdk.out --out dist/Pulumi.yaml` (or the bin script) to emit Pulumi YAML. Include `--stage`/`--stacks`/`--skip-custom` as needed.
+  3. The CLI writes `<outFile>.report.json` unless `--no-report` is passed; the report captures per-stack stats, skipped resources, AWS Classic fallbacks, and fan-out rewrites.
+- Targeted tests:
+  - `npm test -- cli-runner` covers argument parsing + CLI plumbing.
+  - `npm test -- conversion-report` covers the report builder.
+- After landing CLI changes, update `spec.md` checklist and keep this file in sync with any workflow adjustments.

Makefile

@@ -2,5 +2,4 @@
 .PHONY: renovate
 renovate:
 	VERSION=$(shell cat package.json | jq -r '.devDependencies["@pulumi/aws-native"]'); \
-	curl -L https://raw.githubusercontent.com/pulumi/pulumi-aws-native/refs/tags/v$${VERSION}/provider/cmd/pulumi-resource-aws-native/metadata.json -o schemas/aws-native-metadata.json
-
+	curl -L https://raw.githubusercontent.com/pulumi/pulumi-aws-native/refs/tags/v$${VERSION}/provider/cmd/pulumi-resource-aws-native/metadata.json -o packages/@pulumi/cdk-convert-core/schemas/aws-native-metadata.json

README.md

@@ -989,6 +989,48 @@ Pulumi CDK does not support native cross stack references. Instead, you can
 convert a value to a Pulumi Output in order to reference the value in a separate
 stack.
 
+## CDK-to-Pulumi CLI Prototype
+
+This repo also ships an experimental CLI named `cdk-to-pulumi` that converts an already synthesized CDK assembly (a `cdk.out` folder) into a Pulumi YAML program.
+
+### Running the CLI
+
+1. Make sure you have synthesized your CDK app (for example, by running `cdk synth` so that `cdk.out/` exists).
+2. From the repo root, run either the Node-based entrypoint or the bundled binary:
+
+```bash
+# From source
+npx ts-node src/cli/cli-runner.ts --assembly ./cdk.out --out dist/Pulumi.yaml
+
+# Or using the bin script
+./bin/cdk-to-pulumi --assembly ./cdk.out --out dist/Pulumi.yaml
+```
+
+Important flags:
+
+- `--assembly <path>`: Required. Points at the CDK `cdk.out` directory (or nested stage directory when used with `--stage`).
+- `--out <file>`: Pulumi YAML destination. Defaults to `Pulumi.yaml` in the current directory.
+- `--report <file>` / `--no-report`: Controls the conversion report JSON output. By default the CLI writes `<outFile>.report.json` next to the YAML. Use `--no-report` to disable or `--report` to override the path.
+- `--stage <name>`: Restrict conversion to a single nested cloud assembly/stage.
+- `--stacks <name1,name2>`: Only emit the listed stack artifacts.
+- `--skip-custom`: Drop CloudFormation custom resources that would otherwise require the CDK bootstrap bucket emulator.
+
+The CLI writes both the Pulumi YAML and, unless disabled, a structured report describing what happened during conversion. The report captures:
+
+- Per-stack counts (original CFN resource count vs emitted Pulumi resources).
+- Each skipped resource (logical ID, type, and reason).
+- Cases where we fell back to AWS Classic providers.
+- Fan-out rewrites where a single CFN resource expands into multiple Pulumi resources (for example IAM policy attachments).
+
+### Tests
+
+The targeted Jest suites for the CLI live under `tests/cli/`. When updating the CLI or conversion report, run the focused suites:
+
+```bash
+npm test -- cli-runner
+npm test -- conversion-report
+```
+
 ## API
 
 See [API Docs](./api-docs/README.md) for more details.
@@ -1000,15 +1042,15 @@ See [API Docs](./api-docs/README.md) for more details.
 Install dependencies, build library, and link for local usage.
 
 ```sh
-$ yarn install
-$ yarn build
-$ yarn link
+$ npm install
+$ npm run build
+$ npm link
 ```
 
 Run unit test:
 
 ```sh
-$ yarn test
+$ npm test
 
   Basic tests
     ✔ Checking single resource registration (124ms)
@@ -1027,6 +1069,5 @@ $ yarn test
 Run Pulumi examples:
 
 ```
-$ yarn test-examples
+$ npm run test-examples
 ```
-

adr/cdk-cli-lib.md

@@ -1,9 +1,8 @@
 # CDK CLI Library
 
 Updating to use the
-[cdk-cli-lib](https://docs.aws.amazon.com/cdk/api/v2/docs/cli-lib-alpha-readme.html#cloud-assembly-directory-producer)
-in order to support CDK Context requires us to make some user-facing API
-changes.
+[@aws-cdk/toolkit-lib](https://github.com/aws/aws-cdk-cli/tree/main/packages/%40aws-cdk/toolkit-lib)
+in order to support CDK Context requires us to make some user-facing API changes.
 
 ## Context
 
@@ -50,27 +49,26 @@ I’ve included whether it should be possible to use a Pulumi lookup instead.
 ## Constraints
 
 1. We can use the
-   [cdk-cli-lib](https://docs.aws.amazon.com/cdk/api/v2/docs/cli-lib-alpha-readme.html#cloud-assembly-directory-producer)
-   to handle gathering context and handle the multiple passes of executing the
-   framework, but we have to create the `cdk.App` within an async method.
+   [@aws-cdk/toolkit-lib](https://github.com/aws/aws-cdk-cli/tree/main/packages/%40aws-cdk/toolkit-lib)
+   to handle gathering context and perform any required lookups. This library
+   provides a `Toolkit` with helpers such as `fromAssemblyBuilder` that allow us
+   to create the `cdk.App` inside an async function with the complete context.
 
 ```javascript
-class MyProducer implements ICloudAssemblyDirectoryProducer {
-  async produce(context: Record<string, any>) {
-    const app = new cdk.App({ context });
-    const stack = new cdk.Stack(app);
-    return app.synth().directory;
-  }
-}
+const toolkit = new Toolkit();
+
+const source = await toolkit.fromAssemblyBuilder(async ({ context, outdir }) => {
+  const app = new cdk.App({ context, outdir });
+  const stack = new cdk.Stack(app);
+  return app.synth();
+});
 
-const cli = AwsCdkCli.fromCloudAssemblyDirectoryProducer(new MyProducer());
-await cli.synth();
+await toolkit.synth(source);
 ```
 
-This library requires us to create the `cdk.App` within the `produce` method of
-`ICloudAssemblyDirectoryProducer`. This is because the `App` and all constructs
-within it must be constructed with the full `context` value. It is not possible
-to add context after a construct has been constructed.
+This approach requires us to create the `cdk.App` inside the assembly builder,
+because the `App` and all constructs must be constructed with the full context
+value. It is not possible to add context after a construct has been constructed.
 
 2. Because the constructs can be called multiple times, any Pulumi resources
    which are created inside a construct class will also be constructed multiple
@@ -139,16 +137,17 @@ in core. At a very high level it could look something like this.
 ```javascript
 export class App extends pulumi.ComponentResource {
     async initialize() {
-        const cli = AwsCdkCli.fromCloudAssemblyDirectoryProducer(this);
+        const toolkit = new Toolkit();
+        const source = await toolkit.fromAssemblyBuilder(async (props) => this.synthesizeAssembly(props));
         // set mocks before we synth
         pulumi.runtime.setMocks();
         // multiple passes will occur within this. Once we are done
         // it will proceed past this.
-        await cli.synth();
+        await toolkit.synth(source);
         // restore
         pulumi.runtime.resetMocks();
         // create resources 1 last time with all context available.
-        await cli.synth();
+        await toolkit.synth(source);
     }
 }
 ```

api-docs/Namespace.interop.md

@@ -21,8 +21,8 @@ attribute
 
 | Name | Type | Defined in |
 | ------ | ------ | ------ |
-| `attributes`? | `object` | [interop.ts:78](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L78) |
-| `resource` | `pulumi.Resource` | [interop.ts:77](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L77) |
+| `attributes`? | `object` | [src/interop.ts:84](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L84) |
+| `resource` | `pulumi.Resource` | [src/interop.ts:83](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L83) |
 
 #### Example
 
@@ -37,7 +37,7 @@ return {
 
 #### Defined in
 
-[interop.ts:76](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L76)
+[src/interop.ts:82](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L82)
 
 ***
 
@@ -49,7 +49,7 @@ Use this type if a single CFN resource maps to multiple AWS resources
 
 #### Defined in
 
-[interop.ts:84](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L84)
+[src/interop.ts:90](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L90)
 
 ***
 
@@ -59,7 +59,7 @@ Use this type if a single CFN resource maps to multiple AWS resources
 
 #### Defined in
 
-[interop.ts:86](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L86)
+[src/interop.ts:92](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L92)
 
 ## Functions
 
@@ -86,4 +86,4 @@ The normalized resource properties
 
 #### Defined in
 
-[interop.ts:31](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L31)
+[src/interop.ts:30](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L30)