@macedon-technologies/batman 1.32.0 → 1.32.1

package/.jsii

@@ -97,7 +97,7 @@
   },
   "name": "@macedon-technologies/batman",
   "readme": {
-    "markdown": "# Platform Common Projen\n\nA baseline architecture template for new projects using Projen. This project provides a standardized foundation that includes both frontend and backend components with authentication.\n\n## Project Intention\n\nThis template serves as a starting point for new projects, providing:\n- Consistent project structure and configuration\n- Pre-configured development tooling\n- Integrated authentication system\n- Full-stack application foundation\n\n## Components Created\n\nThe BatmanProject generates:\n\n### Frontend\n- **React Application** - Modern React app with TypeScript\n- **Clerk Authentication** - Integrated user authentication and management\n- **Playwright e2e Testing** - `@playwright/test` + `@clerk/testing` devDeps, a `test:e2e` task, and a scaffolded `playwright.config.ts` + `e2e/` starter suite (see the generated `web/e2e/README.md`); disable with `e2eTesting: false`. The generated `pr-deploy.yml` workflow also runs this suite against each PR's deployed URL unless `e2eTesting: false` is set.\n\n### Backend/Infrastructure\n- **AWS Infrastructure** - CDK-based cloud resources\n- **API Gateway** - RESTful API endpoints\n- **Lambda Functions** - Serverless compute\n- **Database** - Persistent data storage\n\n## Usage Examples\n\n### Basic Project Creation\n\nCreate a `.projenrc.ts` file in your project root:\n\n```typescript\nimport { BatmanProject } from '@macedon-technologies/batman';\n\nconst project = new BatmanProject({\n  name: 'my-new-app',\n  defaultReleaseBranch: 'main',\n});\n\nproject.synth();\n```\n\nThen run:\n```bash\nnpx projen\n```\n\n### With Custom Configuration\n\nCreate a `.projenrc.ts` file with additional options:\n\n```typescript\nimport { BatmanProject } from '@macedon-technologies/batman';\n\nconst project = new BatmanProject({\n  name: 'my-enterprise-app',\n  defaultReleaseBranch: 'main',\n  description: 'Enterprise application with authentication',\n  authorName: 'Your Name',\n  authorEmail: 'your.email@company.com',\n});\n\nproject.synth();\n```\n\nThen run:\n```bash\nnpx projen\n```\n\n### Development Workflow\n\n```bash\n# Install dependencies\nyarn install\n\n# Start development server\nyarn dev\n\n# Deploy infrastructure\nyarn deploy\n\n# Run tests\nyarn test\n```\n\n## Deploying staging on demand\n\nThe generated `Staging Deploy` workflow runs on every push to `main` and can also be run manually from the Actions tab (\"Run workflow\"). Use that to redeploy `main` when a merge raised no push event or a deploy needs re-running. Pick `main` as the branch: the workflow deploys whichever branch you select.\n\n## Auto-merging pull requests with a GitHub App\n\nSetting `prAutoMerge: true` generates `.github/workflows/pr-auto-merge.yml`. It turns on GitHub's squash auto-merge for every pull request into the default branch when the pull request is opened, reopened or marked ready for review. Drafts and pull requests into other branches are left alone. The pull request then merges by itself once your branch ruleset is satisfied.\n\nThe workflow arms the merge with a GitHub App token, not `GITHUB_TOKEN`. GitHub attributes an auto-merge to whoever armed it and raises no events for anything `GITHUB_TOKEN` does, so a merge armed with it would never trigger `Staging Deploy` or `PR Cleanup`.\n\nThe App's private key can mint tokens for every repository the App is installed on, so it lives in an `auto-merge` environment that only `main` can use, not in the repository's secrets. Anyone with write access can read repository secrets from a workflow on their own branch. The workflow runs on `pull_request_target`, which uses the workflow file from the default branch and so passes the environment's branch rule; it never checks out pull request code. Use one App per repository so a leaked key reaches only that repository.\n\nSet it up in this order. Until the App and credentials exist, every pull request's `pr-auto-merge` run fails.\n\n1. **Create a GitHub App** in the organization (Settings → Developer settings → GitHub Apps → New GitHub App). It needs no webhook. Under Repository permissions give it **Read and write** on Contents, Pull requests, Workflows and Issues. Workflows is needed because Batman upgrades change files under `.github/workflows/`. Issues lets the merge close linked issues.\n2. **Generate a private key** on the App's page, and note its **Client ID**.\n3. **Install the App** on the repository (the App's page → Install App → Only select repositories).\n4. **Create an `auto-merge` environment** (Settings → Environments → New environment). Under Deployment branches and tags choose **Selected branches and tags** and add `main`. Then add to the environment:\n   - an environment **variable** `AUTO_MERGE_APP_CLIENT_ID` set to the Client ID;\n   - an environment **secret** `AUTO_MERGE_APP_PRIVATE_KEY` set to the full contents of the `.pem` file.\n\n   Don't add them as repository variables or secrets.\n5. **Turn on \"Allow auto-merge\"** in the repository's Settings → General → Pull Requests.\n6. **Protect the default branch** with a ruleset that requires an approving review and your required status checks. `prAutoMerge` doesn't create one. Without it, an armed pull request merges as soon as it can, unreviewed.\n7. Set `prAutoMerge: true` in `.projenrc.ts` and run projen.\n\nIf the variable or the secret is missing from the environment, the run fails with an error naming both. If the App's installation lacks one of the four permissions, minting the token fails. Pull requests from forks are armed like any other, since the workflow runs from the default branch, and still wait for the ruleset's review. Dependabot pull requests don't receive the environment's secret, so their runs fail the credential check. Merge those by hand. Each run also records a deployment to the `auto-merge` environment.\n\n## Upgrading\n\n### Datadog tracing defaults changed\n\n`BaseApplicationStack` now defaults `datadog.nodeLayerVersion` to 143 (dd-trace 6.x) instead of 132, and passes `enableMergeXrayTraces: false` to `DatadogLambda`. These reach every project on its next `npx projen`. With merging off, the `aws.apigateway` span Datadog infers starts the API trace; API Gateway stage X-Ray tracing stays on. A stack that set its own `nodeLayerVersion` keeps it. To merge X-Ray traces again, override `createDatadogExtension()` in your `ApplicationStack`:\n\n```ts\nprotected override createDatadogExtension() {\n  super.createDatadogExtension();\n  Object.assign(this.datadog.props, { enableMergeXrayTraces: true });\n}\n```\n\nNew projects' `src/constructs/Api.ts` installs `express` and `pg` into the Lambda artifact instead of bundling them, so dd-trace can trace router and `pg.query` calls. `Api.ts` is yours once generated, so existing projects add `express` and `pg` to `bundling.nodeModules` on the `NodejsFunction` in `createLambdaFunction()`, creating the block if it has none:\n\n```ts\nbundling: {\n  nodeModules: ['express', 'pg'],\n},\n```\n\nCDK installs each package at the version spec in your root `package.json`, so `express` and `pg` must have plain version ranges there. A `catalog:` spec fails synth.\n\n### The base stack no longer creates a VPC\n\n`BaseApplicationStack` used to create a VPC with a NAT gateway and attach the API Lambda to it.\nIt now creates neither unless the stack props set `enableVpc: true`. A stack that upgrades\nwithout it deletes its VPC and NAT gateway on the next deploy.\n\nAdd `enableVpc: true` to every `ApplicationStack` in `src/main.ts` and `src/LocalDevApp.ts` (new projects: `additionalStackProps: { enableVpc: true }` on each environment) if any of these apply:\n\n- your `ApplicationStack` uses `this.vpc` or overrides `createVpc()`; the override is not called otherwise;\n- the Lambda reaches anything private, such as RDS or a VPC endpoint;\n- another stack imports this stack's VPC outputs; CloudFormation refuses to delete them.\n\n`this.vpc` is now typed `IVpc | undefined`, even with `enableVpc: true`, so code that passes it where an `IVpc` is required (such as `new SecurityGroup(this, 'Sg', { vpc: this.vpc })`) stops compiling. With `enableVpc: true` the VPC is created before your `ApplicationStack` constructor runs, so use `this.vpc!` there, or check it and throw if it's missing.\n\nOtherwise, make `vpc` optional in `src/constructs/Api.ts` (`readonly vpc?: IVpc;`) so the project compiles. Deleting the VPC can take a while as Lambda releases its network interfaces.\n\nWith `enableVpc: true`, the Lambda is attached only if your `Api.ts` still accepts a `vpc` prop and your stack doesn't override `createApi()` without passing it.\n\n### n8n support is removed\n\n`BatmanProject` and `BootcampProject` no longer generate any n8n wiring. The base stacks have no `n8nEndpoint` prop, `src/constructs/WorkflowProvider.ts` and a construct per `src/workflows/*.json` are no longer generated, and new projects get an `Api.ts`, `main.ts` and `LocalDevApp.ts` without n8n. The `n8nWorkflows` option, the `n8nEndpoint` environment config field and the exported `WorkflowAutoDiscover` class are gone, so every project removes `n8nWorkflows` and `n8nEndpoint` from its `.projenrc.ts`.\n\nA project that doesn't use n8n stops compiling until it also removes:\n\n- `n8nEndpoint` from every `ApplicationStack` in `src/main.ts` and `src/LocalDevApp.ts`;\n- the `n8nEndpoint` prop, the n8n JWT key secret and its `grantRead` from `src/constructs/Api.ts`;\n- any `n8nEndpoint: this.props.n8nEndpoint` in a `createApi()` override;\n- any generated `src/constructs/*Workflow.ts` files and `src/workflows/`, which import the now-deleted `WorkflowProvider`.\n\nA project that uses n8n takes ownership of it:\n\n1. Upgrading makes projen delete `src/constructs/WorkflowProvider.ts`. Restore it from the last commit that had it, which works whether or not the deletion is already committed:\n\n   ```bash\n   git checkout \"$(git log -n1 --format=%H --diff-filter=AM -- src/constructs/WorkflowProvider.ts)\" -- src/constructs/WorkflowProvider.ts\n   ```\n\n   Then delete the `~~ Generated by projen` header line from it and from your per-workflow constructs (such as `AlfredWorkflow.ts`). They're yours from now on, and a new workflow needs its construct written by hand.\n2. Move `n8nEndpoint` from `Api` to your `ApplicationStack`. Remove the `n8nEndpoint` prop and its `N8N_ENDPOINT` environment entry from `src/constructs/Api.ts`, add `readonly n8nEndpoint: string;` to `ApplicationStackProps` (your `main.ts` and `LocalDevApp.ts` already pass it), and set the variable after `super()`:\n\n   ```typescript\n   this.api.lambdaFunction.addEnvironment('N8N_ENDPOINT', props.n8nEndpoint);\n   ```\n\n## SoftwareFactoryFiles (standalone, non-Batman projects)\n\n`SoftwareFactoryFiles` is independently exported and can be attached to any\n`projen` `NodeProject` — it does not require `BatmanProject` or\n`BootcampProject`. It generates the `@swamp/software-factory` state machine,\nthe architecture rule registry, the pre-PR attestation gate, the OpenSpec\ntask-completion gate, and the swamp workflows that wire them together.\n\n```typescript\nimport { javascript } from 'projen';\nimport { SoftwareFactoryFiles } from '@macedon-technologies/batman';\n\nconst project = new javascript.NodeProject({\n  name: 'my-other-project',\n  defaultReleaseBranch: 'main',\n});\n\nnew SoftwareFactoryFiles(project, {\n  repoName: 'my-other-project',\n  githubOwner: 'my-github-org', // defaults to 'macedon-technologies' if omitted\n  baseBranch: 'main', // defaults to 'main'\n});\n\nproject.synth();\n```\n\nAfter running `npx projen`, follow the printed `swamp:bootstrap` task to pull\nthe required swamp extensions and create the project's secrets vault.\n\n### Work items and `factory/work-item-sources.md`\n\nA factory run's `workItem` is the ticket's bare key in its own tracker, such as\n`108` for a GitHub issue or `AI-123`, with nothing naming the tracker. The run's\nrecords and scratch paths are named after it, so a run is always started with\nthe bare key, even when the request names the tracker.\n\nThe factory's intake stage resolves the work item by following the managed\n`factory/work-item-sources.md`: which sources' key formats fit it, which model\nand method fetch it, how its fields map into the `issue-context` artifact, and\nwhich link line `open-pr` writes in the PR body (`Closes #<key>` for GitHub).\nWhen more than one source finds the key, intake stops and asks which was meant. Batman regenerates this file on every\nsynth, so supporting another tracker never needs a factory definition edit. The\nfile is part of the PR attestation manifest. The first synth that adds it changes\n`attestation/manifest.ts`, so any factory PR that's already open needs\nre-attesting.\n\n#### Updating an already-scaffolded factory\n\nThe factory definition (`models/@swamp/software-factory/<repo>-factory.yaml`)\nis written once, so a repo scaffolded before the routing file existed\nregenerates it:\n\n1. Note the file's `id:` line and any changes the repo has made to it since it\n   was scaffolded (`git log -p -- <file>`).\n2. Delete the file and run `npx projen`, which writes the current template.\n3. Put the old `id:` line back, so swamp still treats it as the same model, and\n   re-apply the repo's changes.\n\nRuns that recorded the old `issue-context` (`number` instead of `source`/`key`)\nkeep working: the routing file tells later stages to treat them as GitHub issues."
+    "markdown": "# Platform Common Projen\n\nA baseline architecture template for new projects using Projen. This project provides a standardized foundation that includes both frontend and backend components with authentication.\n\n## Project Intention\n\nThis template serves as a starting point for new projects, providing:\n- Consistent project structure and configuration\n- Pre-configured development tooling\n- Integrated authentication system\n- Full-stack application foundation\n\n## Components Created\n\nThe BatmanProject generates:\n\n### Frontend\n- **React Application** - Modern React app with TypeScript\n- **Clerk Authentication** - Integrated user authentication and management\n- **Playwright e2e Testing** - `@playwright/test` + `@clerk/testing` devDeps, a `test:e2e` task, and a scaffolded `playwright.config.ts` + `e2e/` starter suite (see the generated `web/e2e/README.md`); disable with `e2eTesting: false`. The generated `pr-deploy.yml` workflow also runs this suite against each PR's deployed URL unless `e2eTesting: false` is set.\n\n### Backend/Infrastructure\n- **AWS Infrastructure** - CDK-based cloud resources\n- **API Gateway** - RESTful API endpoints\n- **Lambda Functions** - Serverless compute\n- **Database** - Persistent data storage\n\n## Usage Examples\n\n### Basic Project Creation\n\nCreate a `.projenrc.ts` file in your project root:\n\n```typescript\nimport { BatmanProject } from '@macedon-technologies/batman';\n\nconst project = new BatmanProject({\n  name: 'my-new-app',\n  defaultReleaseBranch: 'main',\n});\n\nproject.synth();\n```\n\nThen run:\n```bash\nnpx projen\n```\n\n### With Custom Configuration\n\nCreate a `.projenrc.ts` file with additional options:\n\n```typescript\nimport { BatmanProject } from '@macedon-technologies/batman';\n\nconst project = new BatmanProject({\n  name: 'my-enterprise-app',\n  defaultReleaseBranch: 'main',\n  description: 'Enterprise application with authentication',\n  authorName: 'Your Name',\n  authorEmail: 'your.email@company.com',\n});\n\nproject.synth();\n```\n\nThen run:\n```bash\nnpx projen\n```\n\n### Development Workflow\n\n```bash\n# Install dependencies\nyarn install\n\n# Start development server\nyarn dev\n\n# Deploy infrastructure\nyarn deploy\n\n# Run tests\nyarn test\n```\n\n## Deploying staging on demand\n\nThe generated `Staging Deploy` workflow runs on every push to `main` and can also be run manually from the Actions tab (\"Run workflow\"). Use that to redeploy `main` when a merge raised no push event or a deploy needs re-running. Pick `main` as the branch: the workflow deploys whichever branch you select.\n\n## Auto-merging pull requests with a GitHub App\n\nSetting `prAutoMerge: true` generates `.github/workflows/pr-auto-merge.yml`. It turns on GitHub's squash auto-merge for every pull request into the default branch when the pull request is opened, reopened or marked ready for review. Drafts and pull requests into other branches are left alone. The pull request then merges by itself once your branch ruleset is satisfied.\n\nThe workflow arms the merge with a GitHub App token, not `GITHUB_TOKEN`. GitHub attributes an auto-merge to whoever armed it and raises no events for anything `GITHUB_TOKEN` does, so a merge armed with it would never trigger `Staging Deploy` or `PR Cleanup`.\n\nThe App's private key can mint tokens for every repository the App is installed on, so it lives in an `auto-merge` environment that only `main` can use, not in the repository's secrets. Anyone with write access can read repository secrets from a workflow on their own branch. The workflow runs on `pull_request_target`, which uses the workflow file from the default branch and so passes the environment's branch rule; it never checks out pull request code. Use one App per repository so a leaked key reaches only that repository.\n\nSet it up in this order. Until the App and credentials exist, every pull request's `pr-auto-merge` run fails.\n\n1. **Create a GitHub App** in the organization (Settings → Developer settings → GitHub Apps → New GitHub App). It needs no webhook. Under Repository permissions give it **Read and write** on Contents, Pull requests, Workflows and Issues. Workflows is needed because Batman upgrades change files under `.github/workflows/`. Issues lets the merge close linked issues.\n2. **Generate a private key** on the App's page, and note its **Client ID**.\n3. **Install the App** on the repository (the App's page → Install App → Only select repositories).\n4. **Create an `auto-merge` environment** (Settings → Environments → New environment). Under Deployment branches and tags choose **Selected branches and tags** and add `main`. Then add to the environment:\n   - an environment **variable** `AUTO_MERGE_APP_CLIENT_ID` set to the Client ID;\n   - an environment **secret** `AUTO_MERGE_APP_PRIVATE_KEY` set to the full contents of the `.pem` file.\n\n   Don't add them as repository variables or secrets.\n5. **Turn on \"Allow auto-merge\"** in the repository's Settings → General → Pull Requests.\n6. **Protect the default branch** with a ruleset that requires an approving review and your required status checks. `prAutoMerge` doesn't create one. Without it, an armed pull request merges as soon as it can, unreviewed.\n7. Set `prAutoMerge: true` in `.projenrc.ts` and run projen.\n\nIf the variable or the secret is missing from the environment, the run fails with an error naming both. If the App's installation lacks one of the four permissions, minting the token fails. Pull requests from forks are armed like any other, since the workflow runs from the default branch, and still wait for the ruleset's review. Dependabot pull requests don't receive the environment's secret, so their runs fail the credential check. Merge those by hand. Each run also records a deployment to the `auto-merge` environment.\n\n## Upgrading\n\nEach note names the Batman release that introduced it. Read every note newer than the version you're upgrading from. A note is removed once every known Batman project is on that release or later.\n\n### Datadog tracing defaults changed (v1.32.0)\n\n`BaseApplicationStack` now defaults `datadog.nodeLayerVersion` to 143 (dd-trace 6.x) instead of 132, and passes `enableMergeXrayTraces: false` to `DatadogLambda`. These reach every project on its next `npx projen`. With merging off, the `aws.apigateway` span Datadog infers starts the API trace; API Gateway stage X-Ray tracing stays on. A stack that set its own `nodeLayerVersion` keeps it. To merge X-Ray traces again, override `createDatadogExtension()` in your `ApplicationStack`:\n\n```ts\nprotected override createDatadogExtension() {\n  super.createDatadogExtension();\n  Object.assign(this.datadog.props, { enableMergeXrayTraces: true });\n}\n```\n\nNew projects' `src/constructs/Api.ts` installs `express` and `pg` into the Lambda artifact instead of bundling them, so dd-trace can trace router and `pg.query` calls. `Api.ts` is yours once generated, so existing projects add `express` and `pg` to `bundling.nodeModules` on the `NodejsFunction` in `createLambdaFunction()`, creating the block if it has none:\n\n```ts\nbundling: {\n  nodeModules: ['express', 'pg'],\n},\n```\n\nCDK installs each package at the version spec in your root `package.json`, so `express` and `pg` must have plain version ranges there. A `catalog:` spec fails synth.\n\n### The base stack no longer creates a VPC (v1.30.0)\n\n`BaseApplicationStack` used to create a VPC with a NAT gateway and attach the API Lambda to it.\nIt now creates neither unless the stack props set `enableVpc: true`. A stack that upgrades\nwithout it deletes its VPC and NAT gateway on the next deploy.\n\nAdd `enableVpc: true` to every `ApplicationStack` in `src/main.ts` and `src/LocalDevApp.ts` (new projects: `additionalStackProps: { enableVpc: true }` on each environment) if any of these apply:\n\n- your `ApplicationStack` uses `this.vpc` or overrides `createVpc()`; the override is not called otherwise;\n- the Lambda reaches anything private, such as RDS or a VPC endpoint;\n- another stack imports this stack's VPC outputs; CloudFormation refuses to delete them.\n\n`this.vpc` is now typed `IVpc | undefined`, even with `enableVpc: true`, so code that passes it where an `IVpc` is required (such as `new SecurityGroup(this, 'Sg', { vpc: this.vpc })`) stops compiling. With `enableVpc: true` the VPC is created before your `ApplicationStack` constructor runs, so use `this.vpc!` there, or check it and throw if it's missing.\n\nOtherwise, make `vpc` optional in `src/constructs/Api.ts` (`readonly vpc?: IVpc;`) so the project compiles. Deleting the VPC can take a while as Lambda releases its network interfaces.\n\nWith `enableVpc: true`, the Lambda is attached only if your `Api.ts` still accepts a `vpc` prop and your stack doesn't override `createApi()` without passing it.\n\n### n8n support is removed (v1.30.0)\n\n`BatmanProject` and `BootcampProject` no longer generate any n8n wiring. The base stacks have no `n8nEndpoint` prop, `src/constructs/WorkflowProvider.ts` and a construct per `src/workflows/*.json` are no longer generated, and new projects get an `Api.ts`, `main.ts` and `LocalDevApp.ts` without n8n. The `n8nWorkflows` option, the `n8nEndpoint` environment config field and the exported `WorkflowAutoDiscover` class are gone, so every project removes `n8nWorkflows` and `n8nEndpoint` from its `.projenrc.ts`.\n\nA project that doesn't use n8n stops compiling until it also removes:\n\n- `n8nEndpoint` from every `ApplicationStack` in `src/main.ts` and `src/LocalDevApp.ts`;\n- the `n8nEndpoint` prop, the n8n JWT key secret and its `grantRead` from `src/constructs/Api.ts`;\n- any `n8nEndpoint: this.props.n8nEndpoint` in a `createApi()` override;\n- any generated `src/constructs/*Workflow.ts` files and `src/workflows/`, which import the now-deleted `WorkflowProvider`.\n\nA project that uses n8n takes ownership of it:\n\n1. Upgrading makes projen delete `src/constructs/WorkflowProvider.ts`. Restore it from the last commit that had it, which works whether or not the deletion is already committed:\n\n   ```bash\n   git checkout \"$(git log -n1 --format=%H --diff-filter=AM -- src/constructs/WorkflowProvider.ts)\" -- src/constructs/WorkflowProvider.ts\n   ```\n\n   Then delete the `~~ Generated by projen` header line from it and from your per-workflow constructs (such as `AlfredWorkflow.ts`). They're yours from now on, and a new workflow needs its construct written by hand.\n2. Move `n8nEndpoint` from `Api` to your `ApplicationStack`. Remove the `n8nEndpoint` prop and its `N8N_ENDPOINT` environment entry from `src/constructs/Api.ts`, add `readonly n8nEndpoint: string;` to `ApplicationStackProps` (your `main.ts` and `LocalDevApp.ts` already pass it), and set the variable after `super()`:\n\n   ```typescript\n   this.api.lambdaFunction.addEnvironment('N8N_ENDPOINT', props.n8nEndpoint);\n   ```\n\n### `BaseService.ts` is no longer generated (v1.28.0)\n\n`ViteReactProject` no longer writes `web/src/services/BaseService.ts` or `web/src/services/RootService.ts`. `BaseService.ts` was managed, so upgrading makes projen delete it; `RootService.ts` was yours and stays. New projects get `web/src/services/ApiService.ts` and `web/src/helpers/` instead, and existing projects get them too wherever those files don't already exist.\n\nAnything that imports `BaseService.ts`, such as the old sample `App.tsx` or `RootService.ts`, stops compiling. Switch it to `useApiQuery` / `useApiMutation` from `ApiService.ts`, or keep your own copy of `BaseService.ts` by restoring it from the last commit that had it:\n\n```bash\ngit checkout \"$(git log -n1 --format=%H --diff-filter=AM -- web/src/services/BaseService.ts)\" -- web/src/services/BaseService.ts\n```\n\n## SoftwareFactoryFiles (standalone, non-Batman projects)\n\n`SoftwareFactoryFiles` is independently exported and can be attached to any\n`projen` `NodeProject` — it does not require `BatmanProject` or\n`BootcampProject`. It generates the `@swamp/software-factory` state machine,\nthe architecture rule registry, the pre-PR attestation gate, the OpenSpec\ntask-completion gate, and the swamp workflows that wire them together.\n\n```typescript\nimport { javascript } from 'projen';\nimport { SoftwareFactoryFiles } from '@macedon-technologies/batman';\n\nconst project = new javascript.NodeProject({\n  name: 'my-other-project',\n  defaultReleaseBranch: 'main',\n});\n\nnew SoftwareFactoryFiles(project, {\n  repoName: 'my-other-project',\n  githubOwner: 'my-github-org', // defaults to 'macedon-technologies' if omitted\n  baseBranch: 'main', // defaults to 'main'\n});\n\nproject.synth();\n```\n\nAfter running `npx projen`, follow the printed `swamp:bootstrap` task to pull\nthe required swamp extensions and create the project's secrets vault.\n\n### Work items and `factory/work-item-sources.md`\n\nA factory run's `workItem` is the ticket's bare key in its own tracker, such as\n`108` for a GitHub issue or `AI-123`, with nothing naming the tracker. The run's\nrecords and scratch paths are named after it, so a run is always started with\nthe bare key, even when the request names the tracker.\n\nThe factory's intake stage resolves the work item by following the managed\n`factory/work-item-sources.md`: which sources' key formats fit it, which model\nand method fetch it, how its fields map into the `issue-context` artifact, and\nwhich link line `open-pr` writes in the PR body (`Closes #<key>` for GitHub).\nWhen more than one source finds the key, intake stops and asks which was meant. Batman regenerates this file on every\nsynth, so supporting another tracker never needs a factory definition edit. The\nfile is part of the PR attestation manifest. The first synth that adds it changes\n`attestation/manifest.ts`, so any factory PR that's already open needs\nre-attesting.\n\n#### Updating an already-scaffolded factory\n\nThe factory definition (`models/@swamp/software-factory/<repo>-factory.yaml`)\nis written once, so a repo scaffolded before the routing file existed\nregenerates it:\n\n1. Note the file's `id:` line and any changes the repo has made to it since it\n   was scaffolded (`git log -p -- <file>`).\n2. Delete the file and run `npx projen`, which writes the current template.\n3. Put the old `id:` line back, so swamp still treats it as the same model, and\n   re-apply the repo's changes.\n\nRuns that recorded the old `issue-context` (`number` instead of `source`/`key`)\nkeep working: the routing file tells later stages to treat them as GitHub issues."
   },
   "repository": {
     "type": "git",
@@ -1393,6 +1393,6 @@
       "symbolId": "src/WorkflowActionVersions:WorkflowActionVersions"
     }
   },
-  "version": "1.32.0",
-  "fingerprint": "mzAhut3YlIggln/fITyEpqCI9pvzHMHbEObX8fjAVW4="
+  "version": "1.32.1",
+  "fingerprint": "SA1psU4XUCoyznTMo0IHlvOXqLkoIjQxxTlCYAZMqR0="
 }

package/README.md

@@ -116,7 +116,9 @@ If the variable or the secret is missing from the environment, the run fails wit
 
 ## Upgrading
 
-### Datadog tracing defaults changed
+Each note names the Batman release that introduced it. Read every note newer than the version you're upgrading from. A note is removed once every known Batman project is on that release or later.
+
+### Datadog tracing defaults changed (v1.32.0)
 
 `BaseApplicationStack` now defaults `datadog.nodeLayerVersion` to 143 (dd-trace 6.x) instead of 132, and passes `enableMergeXrayTraces: false` to `DatadogLambda`. These reach every project on its next `npx projen`. With merging off, the `aws.apigateway` span Datadog infers starts the API trace; API Gateway stage X-Ray tracing stays on. A stack that set its own `nodeLayerVersion` keeps it. To merge X-Ray traces again, override `createDatadogExtension()` in your `ApplicationStack`:
 
@@ -137,7 +139,7 @@ bundling: {
 
 CDK installs each package at the version spec in your root `package.json`, so `express` and `pg` must have plain version ranges there. A `catalog:` spec fails synth.
 
-### The base stack no longer creates a VPC
+### The base stack no longer creates a VPC (v1.30.0)
 
 `BaseApplicationStack` used to create a VPC with a NAT gateway and attach the API Lambda to it.
 It now creates neither unless the stack props set `enableVpc: true`. A stack that upgrades
@@ -155,7 +157,7 @@ Otherwise, make `vpc` optional in `src/constructs/Api.ts` (`readonly vpc?: IVpc;
 
 With `enableVpc: true`, the Lambda is attached only if your `Api.ts` still accepts a `vpc` prop and your stack doesn't override `createApi()` without passing it.
 
-### n8n support is removed
+### n8n support is removed (v1.30.0)
 
 `BatmanProject` and `BootcampProject` no longer generate any n8n wiring. The base stacks have no `n8nEndpoint` prop, `src/constructs/WorkflowProvider.ts` and a construct per `src/workflows/*.json` are no longer generated, and new projects get an `Api.ts`, `main.ts` and `LocalDevApp.ts` without n8n. The `n8nWorkflows` option, the `n8nEndpoint` environment config field and the exported `WorkflowAutoDiscover` class are gone, so every project removes `n8nWorkflows` and `n8nEndpoint` from its `.projenrc.ts`.
 
@@ -181,6 +183,16 @@ A project that uses n8n takes ownership of it:
    this.api.lambdaFunction.addEnvironment('N8N_ENDPOINT', props.n8nEndpoint);
    ```
 
+### `BaseService.ts` is no longer generated (v1.28.0)
+
+`ViteReactProject` no longer writes `web/src/services/BaseService.ts` or `web/src/services/RootService.ts`. `BaseService.ts` was managed, so upgrading makes projen delete it; `RootService.ts` was yours and stays. New projects get `web/src/services/ApiService.ts` and `web/src/helpers/` instead, and existing projects get them too wherever those files don't already exist.
+
+Anything that imports `BaseService.ts`, such as the old sample `App.tsx` or `RootService.ts`, stops compiling. Switch it to `useApiQuery` / `useApiMutation` from `ApiService.ts`, or keep your own copy of `BaseService.ts` by restoring it from the last commit that had it:
+
+```bash
+git checkout "$(git log -n1 --format=%H --diff-filter=AM -- web/src/services/BaseService.ts)" -- web/src/services/BaseService.ts
+```
+
 ## SoftwareFactoryFiles (standalone, non-Batman projects)
 
 `SoftwareFactoryFiles` is independently exported and can be attached to any

package/lib/BatmanProject.js

@@ -12,7 +12,7 @@ const SoftwareFactoryFiles_1 = require("./SoftwareFactoryFiles");
 const utils_1 = require("./utils");
 const ViteReactProject_1 = require("./ViteReactProject");
 class BatmanProject extends awscdk_1.AwsCdkTypeScriptApp {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.BatmanProject", version: "1.32.0" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.BatmanProject", version: "1.32.1" };
     constructor(options) {
         super({
             ...options,

package/lib/BootcampProject.js

@@ -12,7 +12,7 @@ const SoftwareFactoryFiles_1 = require("./SoftwareFactoryFiles");
 const utils_1 = require("./utils");
 const ViteReactProject_1 = require("./ViteReactProject");
 class BootcampProject extends awscdk_1.AwsCdkTypeScriptApp {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.BootcampProject", version: "1.32.0" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.BootcampProject", version: "1.32.1" };
     constructor(options) {
         super({
             ...options,

package/lib/CodeOwnersFile.js

@@ -4,7 +4,7 @@ exports.CodeOwnersFile = void 0;
 const JSII_RTTI_SYMBOL_1 = Symbol.for("jsii.rtti");
 const projen_1 = require("projen");
 class CodeOwnersFile extends projen_1.TextFile {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.CodeOwnersFile", version: "1.32.0" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.CodeOwnersFile", version: "1.32.1" };
     constructor(project, options = {}) {
         const defaultOwners = ['* @macedon-technologies/platform', '* @macedon-technologies/ai-development-team'];
         const allOwners = [...defaultOwners, ...(options.additionalOwners || [])];

package/lib/PrAutoMergeWorkflow.js

@@ -14,7 +14,7 @@ const PR_AUTO_MERGE_README_URL = 'https://github.com/macedon-technologies/platfo
  * workflows from pull request branches can't read the key. The job never checks out pull request code.
  */
 class PrAutoMergeWorkflow extends projen_1.YamlFile {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.PrAutoMergeWorkflow", version: "1.32.0" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.PrAutoMergeWorkflow", version: "1.32.1" };
     constructor(project, options = {}) {
         const actionVersions = (0, WorkflowActionVersions_1.resolveActionVersions)(options.actionVersions);
         super(project, '.github/workflows/pr-auto-merge.yml', {

package/lib/ProductionDeployWorkflow.js

@@ -7,7 +7,7 @@ const javascript_1 = require("projen/lib/javascript");
 const utils_1 = require("./utils");
 const WorkflowActionVersions_1 = require("./WorkflowActionVersions");
 class ProductionDeployWorkflow extends projen_1.YamlFile {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.ProductionDeployWorkflow", version: "1.32.0" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.ProductionDeployWorkflow", version: "1.32.1" };
     constructor(project, options) {
         const packageManager = project.package.packageManager;
         const actionVersions = (0, WorkflowActionVersions_1.resolveActionVersions)(options.actionVersions);

package/lib/SoftwareFactoryFiles.js

@@ -35,7 +35,7 @@ const DEFAULT_GITHUB_OWNER = 'macedon-technologies';
  * workflows that wire them together) is templated.
  */
 class SoftwareFactoryFiles {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.SoftwareFactoryFiles", version: "1.32.0" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.SoftwareFactoryFiles", version: "1.32.1" };
     constructor(project, options) {
         const { repoName, actionVersions, attestationFiles } = options;
         const githubOwner = options.githubOwner || DEFAULT_GITHUB_OWNER;

package/lib/StagingDeployWorkflow.js

@@ -7,7 +7,7 @@ const javascript_1 = require("projen/lib/javascript");
 const utils_1 = require("./utils");
 const WorkflowActionVersions_1 = require("./WorkflowActionVersions");
 class StagingDeployWorkflow extends projen_1.YamlFile {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.StagingDeployWorkflow", version: "1.32.0" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.StagingDeployWorkflow", version: "1.32.1" };
     constructor(project, options) {
         const packageManager = project.package.packageManager;
         const actionVersions = (0, WorkflowActionVersions_1.resolveActionVersions)(options.actionVersions);

package/package.json

@@ -49,7 +49,7 @@
   "main": "lib/index.js",
   "license": "Apache-2.0",
   "stability": "stable",
-  "version": "1.32.0",
+  "version": "1.32.1",
   "jest": {
     "coverageProvider": "v8",
     "testMatch": [

package/openspec/changes/pr-workflow-concurrency-group/.openspec.yaml

@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-09-09

package/openspec/changes/pr-workflow-concurrency-group/design.md

@@ -1,47 +0,0 @@
-## Context
-
-`PrDeployWorkflow` (`.github/workflows/pr-deploy.yml`) and `PrCleanupWorkflow` (`.github/workflows/pr-cleanup.yml`) are two independent `YamlFile` constructs, each hand-authored as a literal `obj:` in `projen/src/PrDeployWorkflow.ts` and `projen/src/PrCleanupWorkflow.ts`. Both are instantiated together in every Batman app via `Application.ts`. `pr-deploy` runs on `pull_request: [opened, synchronize, reopened]` and deploys the PR's stack (`cdk deploy`); `pr-cleanup` runs on `pull_request: [closed]` and tears the same stack down (`aws cloudformation delete-stack` + wait). Neither declares a `concurrency` block, so GitHub Actions runs them in parallel with no ordering guarantee. Issue #87 documents a concrete incident: a PR was closed while its 59-resource stack was still creating, `pr-cleanup`'s delete raced the in-flight create, and the stack ended up `DELETE_FAILED` with an orphaned bucket.
-
-`ProjenWorkflowHardening.ts` establishes the precedent for this class of fix: workflows projen generates on its own get patched externally via `JsonPatch`, but hand-authored workflows like these two are edited directly in their source `obj:` literal. This change follows that same convention.
-
-## Goals / Non-Goals
-
-**Goals:**
-- Guarantee `pr-deploy` and `pr-cleanup` never execute concurrently against the same PR's stack.
-- Prefer queuing over cancellation: a run that has to wait should wait, not get killed mid-`cdk deploy`/mid-delete, since a cancelled deploy can leave CloudFormation in `UPDATE_IN_PROGRESS` and break the next run.
-- Keep the group key identical between the two workflows so they queue against each other, not just against themselves.
-
-**Non-Goals:**
-- Recovering a stack already stuck in `DELETE_FAILED`/`ROLLBACK_COMPLETE` (issue #87's "Fix 2"). That requires a separate spike to pick between reaper-style detection-and-repair and `--no-rollback` on PR-stack deploys, and is tracked as follow-up work, not this change.
-- Changing what `pr-deploy`/`pr-cleanup` each do once it's their turn to run — this change only affects *when* they're allowed to start.
-- Deduplicating/redesigning the two workflows' trigger conditions or stack-naming logic (companion issue #88).
-
-## Decisions
-
-**Concurrency group key: `pr-stack-${{ github.event.pull_request.number }}`, identical in both workflows.**
-The PR number is the natural join key — it's the one thing both workflows compute their stack identity from (via the PR's branch name), and it's available on the `pull_request` event both workflows already trigger on. A key scoped to the workflow name (GitHub's default when `concurrency.group` is omitted) would only serialize `pr-deploy` runs against each other and `pr-cleanup` runs against each other — it would *not* prevent the race between the two workflows, which is the actual bug. The group must be textually identical in both files for GitHub to treat them as the same queue.
-
-**`cancel-in-progress: false` in both workflows.**
-Alternative considered: `cancel-in-progress: true`, which is the more common concurrency-group pattern (e.g. superseding stale CI runs on new pushes). Rejected here because cancelling a `pr-deploy` run mid-`cdk deploy` leaves CloudFormation in `UPDATE_IN_PROGRESS`/`CREATE_IN_PROGRESS`, which fails the *next* deploy attempt against that stack — trading one class of race for another. Queuing (`false`) means a `pr-cleanup` triggered while `pr-deploy` is running simply waits for it to finish, then deletes the now-complete stack; a `pr-deploy` triggered while a prior `pr-deploy` is still running (e.g. rapid pushes) waits its turn instead of double-deploying.
-
-**Edit the two `YamlFile` `obj:` literals directly, not a shared external patch.**
-Alternative considered: a `ProjenWorkflowHardening`-style helper that patches `concurrency` onto both workflows post-construction. Rejected because both workflows are already hand-authored in this package (unlike the projen-builtin workflows `ProjenWorkflowHardening` targets), so there's no `JsonPatch`-vs-source-edit tension to resolve — adding a two-line `concurrency` key next to each `obj:`'s existing `name`/`on`/`permissions` keys is simpler and keeps the workflow's full shape in one place.
-
-## Risks / Trade-offs
-
-- [A PR merge/close event and a fast-follow `pr-deploy` push (e.g. re-opening) could still queue for a while if a prior run is slow] → Acceptable: queuing bounds this to "wait", never "corrupt state"; GitHub Actions queue depth for a single PR is small in practice.
-- [Non-`pull_request`-number contexts, if a workflow is ever re-triggered via `workflow_dispatch` or similar, would evaluate `github.event.pull_request.number` as empty and could collide group keys across PRs] → Out of scope: both workflows currently only trigger on `pull_request` events, so this doesn't apply today; flag it if either workflow's `on:` trigger ever expands.
-- [This change doesn't fix `DELETE_FAILED` stacks that already exist from prior races] → Those are cleaned up manually per issue #87; this change only prevents new occurrences.
-
-## Migration Plan
-
-1. Add `concurrency` to `PrDeployWorkflow`'s and `PrCleanupWorkflow`'s generated `obj:`.
-2. Add/update unit tests asserting both workflows render the same `concurrency.group` string.
-3. Run `npx projen` in this package to confirm no other synthesized output changes unexpectedly.
-4. Downstream consumers (e.g. `exman`) pick up the fix the next time they bump this package version and re-run projen synth, regenerating `.github/workflows/pr-deploy.yml` / `pr-cleanup.yml` with the new `concurrency` block. No manual migration step needed beyond the normal dependency bump.
-
-No rollback concerns: removing the `concurrency` block is a pure revert with no state to unwind.
-
-## Open Questions
-
-None — issue #87's own investigation already resolved the "queue vs. cancel" question (`cancel-in-progress: false`) and identified the exact group key needed.

package/openspec/changes/pr-workflow-concurrency-group/proposal.md

@@ -1,27 +0,0 @@
-## Why
-
-`PrDeployWorkflow` and `PrCleanupWorkflow` generate independent GitHub Actions workflows that both operate on the same CloudFormation stack (`pr-deploy` creates/updates it, `pr-cleanup` deletes it) but declare no `concurrency` block. When a PR is closed while its deploy is still in flight, `pr-cleanup` issues `aws cloudformation delete-stack` against a stack that is mid-`CREATE_IN_PROGRESS`. On 2026-09-03 this raced a 59-resource stack, cancelled the create, failed the rollback, and left the stack `DELETE_FAILED` with an orphaned S3 bucket requiring manual cleanup (see issue #87). This affects every generated Batman app, and 2 of 12 `pr-cleanup` runs failed that same day, consistent with this being a recurring class of failure rather than a one-off.
-
-## What Changes
-
-- Add a `concurrency` block to `PrDeployWorkflow`'s generated `pr-deploy.yml`, keyed on the PR number.
-- Add the identical `concurrency` block to `PrCleanupWorkflow`'s generated `pr-cleanup.yml`, keyed on the same PR-number-derived group name.
-- Use `cancel-in-progress: false` on both so a queued run waits for the in-flight run to finish rather than being cancelled mid-`cdk deploy` (which would abandon CloudFormation in `UPDATE_IN_PROGRESS` and break the next deploy).
-- Regenerate/synth downstream projects (e.g. `exman`) so the emitted workflow YAML picks up the new `concurrency` block.
-
-Out of scope: the `DELETE_FAILED`/orphaned-bucket recovery path described as "Fix 2" in issue #87 (detecting and repairing `DELETE_FAILED`/`ROLLBACK_COMPLETE` stacks, or `--no-rollback` for PR-stack deploys). The issue itself notes neither option is settled yet and calls for a separate spike; queuing via `concurrency` prevents the race that causes `DELETE_FAILED` in the first place, so it is not required to close this change.
-
-## Capabilities
-
-### New Capabilities
-- `pr-workflow-concurrency`: Generated `pr-deploy.yml` and `pr-cleanup.yml` workflows share a concurrency group so that a stack delete triggered by closing a PR is queued behind, rather than raced against, an in-flight deploy of the same stack.
-
-### Modified Capabilities
-(none — no existing specs cover PR deploy/cleanup workflow generation)
-
-## Impact
-
-- `projen/src/PrDeployWorkflow.ts` — add `concurrency` to the generated workflow object.
-- `projen/src/PrCleanupWorkflow.ts` — add matching `concurrency` to the generated workflow object.
-- `projen/src/BatmanProject.test.ts` (or equivalent) — add coverage asserting both workflows emit the same concurrency group.
-- Any downstream project generated from these projen constructs (e.g. `exman`) needs to re-run projen synth to regenerate `.github/workflows/pr-deploy.yml` and `.github/workflows/pr-cleanup.yml` with the fix.

package/openspec/changes/pr-workflow-concurrency-group/specs/pr-workflow-concurrency/spec.md

@@ -1,23 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Shared concurrency group across PR deploy and cleanup workflows
-The generated `pr-deploy.yml` and `pr-cleanup.yml` workflows SHALL each declare a top-level `concurrency.group` keyed on the pull request number (`pr-stack-${{ github.event.pull_request.number }}`), and the group value SHALL be identical text in both files, so that GitHub Actions serializes runs of the two workflows against the same PR into a single queue.
-
-#### Scenario: pr-cleanup triggered while pr-deploy is still running
-- **WHEN** a PR is closed while its `pr-deploy` run for that same PR is still in progress
-- **THEN** the `pr-cleanup` run for that PR does not start until the in-progress `pr-deploy` run for that PR finishes
-
-#### Scenario: Concurrent pr-deploy runs on the same PR
-- **WHEN** two `pr-deploy` runs are triggered for the same PR in close succession (e.g. rapid pushes)
-- **THEN** the second run queues behind the first rather than executing `cdk deploy` concurrently against the same stack
-
-#### Scenario: Group keys match between workflows
-- **WHEN** the generated `pr-deploy.yml` and `pr-cleanup.yml` are compared for a given PR event
-- **THEN** their `concurrency.group` values evaluate to the same string, so GitHub Actions treats them as the same queue
-
-### Requirement: Queue instead of cancel in-flight runs
-Both `pr-deploy.yml` and `pr-cleanup.yml` SHALL set `concurrency.cancel-in-progress: false`, so that a queued run waits for the currently running workflow to finish instead of being cancelled mid-execution.
-
-#### Scenario: Queued run does not cancel an in-flight deploy
-- **WHEN** `pr-cleanup` is queued behind a running `pr-deploy` for the same PR
-- **THEN** the running `pr-deploy` job is allowed to run to completion (success or failure) rather than being cancelled by GitHub Actions

package/openspec/changes/pr-workflow-concurrency-group/tasks.md

@@ -1,15 +0,0 @@
-## 1. Add concurrency block to generated workflows
-
-- [x] 1.1 In `src/PrDeployWorkflow.ts`, add `concurrency: { group: 'pr-stack-${{ github.event.pull_request.number }}', 'cancel-in-progress': false }` to the generated `obj:` (alongside `name`, `on`, `permissions`).
-- [x] 1.2 In `src/PrCleanupWorkflow.ts`, add the identical `concurrency` block to its generated `obj:`.
-
-## 2. Test coverage
-
-- [x] 2.1 In `test/DeployWorkflows.test.ts`, add a test (or extend an existing one) asserting `pr-deploy.yml` and `pr-cleanup.yml` both render `concurrency.group: pr-stack-${{ github.event.pull_request.number }}` and `concurrency.cancel-in-progress: false`.
-- [x] 2.2 Add an assertion that the two workflows' `concurrency.group` values are textually identical, so the test fails if they ever drift apart.
-- [x] 2.3 Update `test/__snapshots__/DeployWorkflows.test.ts.snap` (and any other snapshots covering `pr-deploy.yml`/`pr-cleanup.yml`, e.g. `BatmanProject.test.ts.snap`, `BootcampProject.test.ts.snap`) by running the test suite with snapshot update, then review the diff for correctness before committing.
-
-## 3. Verify
-
-- [x] 3.1 Run the full `projen`/build test suite and confirm it passes with the updated snapshots.
-- [x] 3.2 Run `npx projen` in this package to confirm no unrelated synthesized output changes.