@macedon-technologies/batman 1.29.0 → 1.31.0

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## 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."
+    "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### 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."
   },
   "repository": {
     "type": "git",
@@ -123,7 +123,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/Application.ts",
-        "line": 24
+        "line": 23
       },
       "name": "ApplicationEnvironmentConfig",
       "properties": [
@@ -135,7 +135,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/Application.ts",
-            "line": 25
+            "line": 24
           },
           "name": "githubActionRoleArn",
           "type": {
@@ -158,7 +158,7 @@
         },
         "locationInModule": {
           "filename": "src/BatmanProject.ts",
-          "line": 82
+          "line": 87
         },
         "parameters": [
           {
@@ -172,7 +172,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/BatmanProject.ts",
-        "line": 81
+        "line": 86
       },
       "name": "BatmanProject",
       "symbolId": "src/BatmanProject:BatmanProject"
@@ -251,7 +251,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/BatmanProject.ts",
-            "line": 52
+            "line": 47
           },
           "name": "actionVersions",
           "optional": true,
@@ -268,7 +268,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/BatmanProject.ts",
-            "line": 42
+            "line": 37
           },
           "name": "additionalCodeOwners",
           "optional": true,
@@ -314,7 +314,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/BatmanProject.ts",
-            "line": 77
+            "line": 72
           },
           "name": "attestationFiles",
           "optional": true,
@@ -337,7 +337,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/BatmanProject.ts",
-            "line": 59
+            "line": 54
           },
           "name": "authorizerObjectVersion",
           "optional": true,
@@ -355,7 +355,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/BatmanProject.ts",
-            "line": 66
+            "line": 61
           },
           "name": "e2eTesting",
           "optional": true,
@@ -366,15 +366,17 @@
         {
           "abstract": true,
           "docs": {
+            "default": "false",
+            "remarks": "Requires the\n`AUTO_MERGE_APP_CLIENT_ID` variable and the\n`AUTO_MERGE_APP_PRIVATE_KEY` secret in an `auto-merge` environment; see the README section\n\"Auto-merging pull requests with a GitHub App\".",
             "stability": "stable",
-            "summary": "Enable n8n workflow auto-discovery and WorkflowProvider generation."
+            "summary": "Generates the pr-auto-merge workflow, which arms squash auto-merge on ready pull requests into the default branch with a GitHub App token."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/BatmanProject.ts",
-            "line": 37
+            "line": 82
           },
-          "name": "n8nWorkflows",
+          "name": "prAutoMerge",
           "optional": true,
           "type": {
             "primitive": "boolean"
@@ -389,7 +391,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/BatmanProject.ts",
-            "line": 47
+            "line": 42
           },
           "name": "websiteDeps",
           "optional": true,
@@ -554,7 +556,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/MainFile.ts",
-            "line": 11
+            "line": 10
           },
           "name": "account",
           "type": {
@@ -584,7 +586,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/MainFile.ts",
-            "line": 13
+            "line": 12
           },
           "name": "clerkPublishableKey",
           "type": {
@@ -644,9 +646,9 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/MainFile.ts",
-            "line": 10
+            "line": 11
           },
-          "name": "n8nEndpoint",
+          "name": "region",
           "type": {
             "primitive": "string"
           }
@@ -659,36 +661,124 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/MainFile.ts",
-            "line": 12
+            "line": 13
           },
-          "name": "region",
+          "name": "additionalStackProps",
+          "optional": true,
           "type": {
-            "primitive": "string"
+            "collection": {
+              "elementtype": {
+                "primitive": "any"
+              },
+              "kind": "map"
+            }
           }
+        }
+      ],
+      "symbolId": "src/MainFile:EnvironmentConfig"
+    },
+    "@macedon-technologies/batman.PrAutoMergeWorkflow": {
+      "assembly": "@macedon-technologies/batman",
+      "base": "projen.YamlFile",
+      "docs": {
+        "stability": "stable",
+        "summary": "Generates `.github/workflows/pr-auto-merge.yml`, which arms GitHub's native squash auto-merge on every ready pull request into the default branch using a GitHub App installation token. It runs on `pull_request_target` in the `auto-merge` environment, which holds the `AUTO_MERGE_APP_CLIENT_ID` variable and the `AUTO_MERGE_APP_PRIVATE_KEY` secret, so workflows from pull request branches can't read the key. The job never checks out pull request code."
+      },
+      "fqn": "@macedon-technologies/batman.PrAutoMergeWorkflow",
+      "initializer": {
+        "docs": {
+          "stability": "stable"
+        },
+        "locationInModule": {
+          "filename": "src/PrAutoMergeWorkflow.ts",
+          "line": 22
         },
+        "parameters": [
+          {
+            "name": "project",
+            "type": {
+              "fqn": "projen.Project"
+            }
+          },
+          {
+            "name": "options",
+            "optional": true,
+            "type": {
+              "fqn": "@macedon-technologies/batman.PrAutoMergeWorkflowOptions"
+            }
+          }
+        ]
+      },
+      "kind": "class",
+      "locationInModule": {
+        "filename": "src/PrAutoMergeWorkflow.ts",
+        "line": 21
+      },
+      "methods": [
+        {
+          "docs": {
+            "stability": "stable",
+            "summary": "Implemented by derived classes and returns the contents of the file to emit."
+          },
+          "locationInModule": {
+            "filename": "src/PrAutoMergeWorkflow.ts",
+            "line": 84
+          },
+          "name": "synthesizeContent",
+          "overrides": "projen.YamlFile",
+          "parameters": [
+            {
+              "name": "resolver",
+              "type": {
+                "fqn": "projen.IResolver"
+              }
+            }
+          ],
+          "protected": true,
+          "returns": {
+            "optional": true,
+            "type": {
+              "primitive": "string"
+            }
+          }
+        }
+      ],
+      "name": "PrAutoMergeWorkflow",
+      "symbolId": "src/PrAutoMergeWorkflow:PrAutoMergeWorkflow"
+    },
+    "@macedon-technologies/batman.PrAutoMergeWorkflowOptions": {
+      "assembly": "@macedon-technologies/batman",
+      "datatype": true,
+      "docs": {
+        "stability": "stable"
+      },
+      "fqn": "@macedon-technologies/batman.PrAutoMergeWorkflowOptions",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/PrAutoMergeWorkflow.ts",
+        "line": 7
+      },
+      "name": "PrAutoMergeWorkflowOptions",
+      "properties": [
         {
           "abstract": true,
           "docs": {
-            "stability": "stable"
+            "stability": "stable",
+            "summary": "Overrides for the pinned action versions used by this workflow."
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/MainFile.ts",
-            "line": 14
+            "filename": "src/PrAutoMergeWorkflow.ts",
+            "line": 11
           },
-          "name": "additionalStackProps",
+          "name": "actionVersions",
           "optional": true,
           "type": {
-            "collection": {
-              "elementtype": {
-                "primitive": "any"
-              },
-              "kind": "map"
-            }
+            "fqn": "@macedon-technologies/batman.WorkflowActionVersions"
           }
         }
       ],
-      "symbolId": "src/MainFile:EnvironmentConfig"
+      "symbolId": "src/PrAutoMergeWorkflow:PrAutoMergeWorkflowOptions"
     },
     "@macedon-technologies/batman.ProductionDeployWorkflow": {
       "assembly": "@macedon-technologies/batman",
@@ -1155,6 +1245,24 @@
             "primitive": "string"
           }
         },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "'actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1' // v3.2.0",
+            "stability": "stable",
+            "summary": "The `actions/create-github-app-token` action reference, used by the opt-in pr-auto-merge workflow to mint a GitHub App installation token."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/WorkflowActionVersions.ts",
+            "line": 86
+          },
+          "name": "createGithubAppToken",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
+        },
         {
           "abstract": true,
           "docs": {
@@ -1283,54 +1391,8 @@
         }
       ],
       "symbolId": "src/WorkflowActionVersions:WorkflowActionVersions"
-    },
-    "@macedon-technologies/batman.WorkflowAutoDiscover": {
-      "assembly": "@macedon-technologies/batman",
-      "base": "projen.Component",
-      "docs": {
-        "stability": "stable"
-      },
-      "fqn": "@macedon-technologies/batman.WorkflowAutoDiscover",
-      "initializer": {
-        "docs": {
-          "stability": "stable"
-        },
-        "locationInModule": {
-          "filename": "src/WorkflowAutoDiscover.ts",
-          "line": 7
-        },
-        "parameters": [
-          {
-            "name": "project",
-            "type": {
-              "fqn": "projen.awscdk.AwsCdkTypeScriptApp"
-            }
-          }
-        ]
-      },
-      "kind": "class",
-      "locationInModule": {
-        "filename": "src/WorkflowAutoDiscover.ts",
-        "line": 6
-      },
-      "methods": [
-        {
-          "docs": {
-            "stability": "stable",
-            "summary": "Synthesizes files to the project output directory."
-          },
-          "locationInModule": {
-            "filename": "src/WorkflowAutoDiscover.ts",
-            "line": 11
-          },
-          "name": "synthesize",
-          "overrides": "projen.Component"
-        }
-      ],
-      "name": "WorkflowAutoDiscover",
-      "symbolId": "src/WorkflowAutoDiscover:WorkflowAutoDiscover"
     }
   },
-  "version": "1.29.0",
-  "fingerprint": "dt1wlH22V+EIj+x/9WefgyfYIFcWaGRY6I39LcVxZNI="
+  "version": "1.31.0",
+  "fingerprint": "v3LtzRASfWDpM+pq51kAi0OCLSH+2WXyh+/YEMCFxFg="
 }