create-agent-rig 0.4.0 → 0.6.0

package/templates/skeleton/aws-serverless/README.md

@@ -45,13 +45,27 @@ do not edit the workflow:
 
 1. In AWS, create an IAM role your repo can assume via GitHub's OIDC provider
    (`token.actions.githubusercontent.com`) — a short-lived federated role, no
-   long-lived access keys anywhere.
-2. Add its ARN as the repository secret **`AWS_DEPLOY_ROLE_ARN`** (and,
-   optionally, repo variables `AWS_REGION` and `API_URL`).
-
-The workflow then assumes the role, builds the web bundle, and runs
-`cdk deploy AppStack WebStack`. The web bundle is served from S3 + CloudFront
-(the `WebUrl` output).
+   long-lived access keys anywhere. Beyond what `cdk deploy` needs, the
+   workflow uploads the bundle itself, so the role also needs
+   **`s3:ListBucket`, `s3:PutObject`, `s3:DeleteObject`** on the web bucket and
+   **`cloudfront:CreateInvalidation`** on the distribution. A role scoped only
+   to CDK's bootstrap roles gets through the deploy and fails on the upload —
+   after both stacks are already up.
+2. Add its ARN as the repository secret **`AWS_DEPLOY_ROLE_ARN`**, and set the
+   repo variable **`API_URL`** to the deployed API's URL (the `ApiUrl` output
+   of a first deploy). It becomes `NEXT_PUBLIC_API_URL`, which Next **inlines
+   into the bundle at build time** — unset, the site calls `/notes` on its own
+   CloudFront domain, where nothing answers. `AWS_REGION` is genuinely
+   optional. The first deploy is therefore two passes: deploy, read `ApiUrl`
+   from the job's `cdk deploy` Outputs, set the variable, then re-run the
+   workflow (push, or **Run workflow** — it is `workflow_dispatch`-enabled).
+
+The workflow then assumes the role, builds the web bundle, runs
+`cdk deploy AppStack WebStack --outputs-file`, then **uploads `apps/web/out` to
+the web bucket (`aws s3 sync --delete`) and invalidates the CloudFront cache**,
+reading both destinations from the stack outputs. You do not sync anything by
+hand on this path. The site is served from S3 + CloudFront (the `WebUrl`
+output).
 
 ### Local / manual
 
@@ -59,8 +73,26 @@ The workflow then assumes the role, builds the web bundle, and runs
 # needs AWS credentials; region comes from your profile (generator default: __REGION__)
 cd infra
 npx cdk bootstrap   # first time per account/region
-npx cdk deploy AppStack WebStack
-aws s3 sync ../apps/web/out "s3://<WebBucketName output>"
+npx cdk deploy AppStack WebStack --outputs-file cdk-outputs.json
+# --delete makes the bucket the bundle's territory alone, so a stale or missing
+# `out/` would empty the live site — or restore last month's. The workflow
+# builds two steps before its sync; by hand, build here.
+# Read the outputs into variables FIRST. `jq -er` exits non-zero on a missing
+# key, but a command substitution inside an assignment or an argument throws
+# that status away — which is how a stale outputs file becomes a bundle built
+# against `null` and an `aws s3 sync … s3://null --delete`.
+API=$(jq -er '.AppStack.ApiUrl' cdk-outputs.json) || { echo "no ApiUrl"; exit 1; }
+BUCKET=$(jq -er '.WebStack.WebBucketName' cdk-outputs.json) || { echo "no WebBucketName"; exit 1; }
+DIST=$(jq -er '.WebStack.WebDistributionId' cdk-outputs.json) || { echo "no WebDistributionId"; exit 1; }
+
+# NEXT_PUBLIC_API_URL is inlined at build time: without it the bundle calls its
+# own CloudFront domain instead of the API, and the sync below makes that live.
+(cd .. && NEXT_PUBLIC_API_URL="$API" pnpm build:web)
+[ -f ../apps/web/out/index.html ] || { echo "no web bundle — build failed"; exit 1; }
+aws s3 sync ../apps/web/out "s3://$BUCKET" --delete
+# a synced bucket whose distribution still serves the old objects has not
+# deployed — invalidate, or you are looking at the previous build
+aws cloudfront create-invalidation --paths '/*' --distribution-id "$DIST"
 ```
 
 ### Production — a human step, on purpose
@@ -76,12 +108,41 @@ your own approval — reusing the dev workflow's OIDC pattern.
 After every deploy:
 
 ```sh
+# From the deploy's outputs file — run this from `infra/`, where the manual
+# section leaves you. Deployed through CI instead? That file is written on the
+# runner and never lands here: take both values from the job's `cdk deploy`
+# Outputs, or re-run `cdk deploy … --outputs-file cdk-outputs.json` locally.
+API_URL=$(jq -er '.AppStack.ApiUrl' cdk-outputs.json)
+WEB_URL=$(jq -er '.WebStack.WebUrl' cdk-outputs.json)
+
 curl -s -X POST "$API_URL/notes" \
   -H 'content-type: application/json' \
   -d '{"title":"smoke test","tags":["deploy"]}'
 # expect: HTTP 201 with { "note": { … } }
 ```
 
+**That checks the API, not the site.** The two fail independently: a bundle
+built without `NEXT_PUBLIC_API_URL` calls its own CloudFront domain, and a
+misnamed origin is refused by the browser — neither is visible to a `curl` that
+sends no `Origin` header. So also open the `WebUrl` output, create a note in
+the form, and reload:
+
+```sh
+curl -s -I "$WEB_URL" | head -1                      # the bundle is served
+
+# API Gateway answers a preflight 204 whether or not the origin matched, so the
+# status code proves nothing here. The browser gates on the echoed header —
+# that is what to look for. `content-type` is sent because the real call uses
+# it, and a non-safelisted header is what makes `allowHeaders` matter.
+curl -s -X OPTIONS "$API_URL/notes" -D - -o /dev/null \
+  -H "Origin: $WEB_URL" \
+  -H 'access-control-request-method: POST' \
+  -H 'access-control-request-headers: content-type' \
+  | grep -i '^access-control-allow-origin:'
+# expect: a line echoing $WEB_URL. No line = the browser will refuse the call,
+# whatever the status code said.
+```
+
 Then confirm the pipeline: the worker logs `note.created processed`, and the
 **DLQ alarm stays quiet**. If the smoke test regresses: `npx cdk deploy` the
 previous revision (or `git revert` and redeploy) **first**, diagnose second.
@@ -95,5 +156,26 @@ previous revision (or `git revert` and redeploy) **first**, diagnose second.
 - `packages/db` is the only module that touches the storage SDK.
 - A failing queue message is poison: it throws, SQS retries ×3, the DLQ alarm
   fires. Never wrap the worker in a broad catch.
+- **Creating a note is a dual write, and it is not atomic.** `create-note`
+  puts to DynamoDB and then publishes to SQS. If the publish fails, the note
+  is stored and its event never happened — the worker never runs, and nothing
+  compensates; the caller gets a 500 for a note that exists. That is a
+  deliberate simplification for a starter. When it starts to matter, the two
+  ways out are an **outbox** (write the event alongside the note, relay it
+  afterwards) or DynamoDB Streams feeding the worker, which deletes the second
+  write instead of coordinating it.
+- **CORS names who may call the API, and that half is wired for you.**
+  `bin/app.ts` builds `WebStack` first and passes its CloudFront origin to
+  `AppStack`, so the API allows the deployed site without you configuring it.
+  The other half is not automatic: the bundle has to know where the API *is*,
+  and that is `NEXT_PUBLIC_API_URL` above. For a custom domain or a second
+  origin, deploy with `-c allowedOrigins=https://app.example.com` (comma-
+  separated for several) — the entrypoint prefers the flag over the wired
+  default, and the cross-stack export disappears with it. An `allowedOrigins`
+  that parses to nothing, or an entry no browser could send, is refused at
+  synth rather than deployed as an API nobody can call. `*` is not the default
+  and never will be, but the flag does take it: you get a warning naming the
+  consequence, not a refusal, because the alternative is people editing the
+  stack.
 
 See `.claude/rules/architecture.md` for the full rules.

package/templates/skeleton/aws-serverless/apps/web/src/lib/api.ts

@@ -2,8 +2,15 @@
 // (the guard-web-boundary hook refuses such imports at the tool layer).
 import type { Note } from '@app/core';
 
-// Same-origin by default (the API server serves this bundle); set
-// NEXT_PUBLIC_API_URL at build time when the API lives elsewhere.
+// In THIS target the API is never same-origin: the bundle is served from
+// CloudFront and the API is API Gateway, so `NEXT_PUBLIC_API_URL` has to be set
+// at build time — Next inlines it, and an unset one leaves the empty string
+// here, which sends every call to whatever is serving this page.
+//
+// The `?? ''` is a fallback to nothing, not to a working default: there is no
+// dev proxy in this project, so `pnpm --filter @app/web dev` needs the variable
+// too. It exists only so a missing value is a relative URL rather than the
+// string "undefined" in a request path.
 const base = process.env.NEXT_PUBLIC_API_URL ?? '';
 
 export async function createNote(input: { title: string; tags: string[] }): Promise<Note> {

package/templates/skeleton/aws-serverless/gitignore

@@ -2,16 +2,53 @@ node_modules/
 dist/
 coverage/
 cdk.out/
+# what `cdk deploy --outputs-file` writes: bucket names, distribution ids,
+# endpoints. Harmless today, and the file that accumulates the ones that are not.
+cdk-outputs.json
 *.tsbuildinfo
 .DS_Store
 .next/
 out/
 next-env.d.ts
 .claude/worktrees/
+# per-checkout queue state: the tier the last close recorded. The queue CONFIG
+# is composed and tracked; this is runtime state and must never be committed.
+.claude/queue.state.json
+# gate rounds, one count per branch
+.claude/gate-rounds.json
+# per-run machine trace (.claude/scripts/run-journal.mjs): forensics that churn
+# on every gate and collide across concurrent sessions. Unlike a committed
+# evidence directory, this one is per-run and stays out of the repository.
+.claude/runs/
 
 # secrets — never commit these
+*.env
 .env
 .env.*
 !.env.example
+.envrc
+.npmrc
+.netrc
+.pgpass
+id_rsa
+id_ed25519
 *.pem
 *.key
+*.p12
+*.pfx
+*.keystore
+*.jks
+*.secret
+*.secrets
+*.token
+*.tokens
+*.password
+*.passwords
+*.credential
+*.credentials
+*.apikey
+*.apikeys
+*.passwd
+*.creds
+*.jwt
+*.bearer

package/templates/skeleton/aws-serverless/infra/bin/app.ts

@@ -1,19 +1,79 @@
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { App } from 'aws-cdk-lib';
-import { AppStack } from '../lib/app-stack.js';
+import { AppStack, nothingGiven } from '../lib/app-stack.js';
 import { WebStack } from '../lib/web-stack.js';
 
-const app = new App();
+/**
+ * The composition, as a function so a test can synthesise the same wiring the
+ * CLI gets. A test that re-wires the stacks itself would pass while this file
+ * stayed broken, which is the one failure worth catching here.
+ */
+export function createApp(): App {
+  const app = new App();
 
-// Region-agnostic by default; `cdk deploy` uses your CLI profile. Pin it here
-// when the project settles (the generator's default region is __REGION__).
-const env = { region: process.env.CDK_DEFAULT_REGION };
+  // Region-agnostic by default; `cdk deploy` uses your CLI profile. Pin it here
+  // when the project settles (the generator's default region is __REGION__).
+  const env = { region: process.env.CDK_DEFAULT_REGION };
 
-new AppStack(app, 'AppStack', {
-  description: 'API + worker for __PROJECT_NAME__ (generated by create-agent-rig)',
-  env,
-});
+  // The web stack first: the API has to allow the origin the browser loads the
+  // app from, and that origin is a CloudFront domain this stack owns. Passing
+  // it makes CORS correct on the first deploy instead of after someone
+  // discovers the app is blocked and reaches for `*`.
+  //
+  // The price, so it is not discovered later: this is a cross-stack export, so
+  // WebStack is deploy-ordered before AppStack and cannot be torn down while
+  // AppStack still imports it — CDK warns about the reference strength on
+  // synth. Pass `allowedOrigins` explicitly (a custom domain, several origins)
+  // and the export disappears with it.
+  const web = new WebStack(app, 'WebStack', {
+    description: 'Static web serving for __PROJECT_NAME__ (generated by create-agent-rig)',
+    env,
+  });
 
-new WebStack(app, 'WebStack', {
-  description: 'Static web serving for __PROJECT_NAME__ (generated by create-agent-rig)',
-  env,
-});
+  // `-c allowedOrigins=…` wins over the wired default — a custom domain is a
+  // deliberate act, and props short-circuit the context inside AppStack, so
+  // passing them unconditionally would accept the flag and ignore it. Omitting
+  // the prop hands the flag to AppStack's own validation instead of dropping
+  // it: an unusable value is refused at synth rather than deployed.
+  // `nothingGiven` is imported rather than restated: this file and the stack
+  // both decide whether the operator supplied an origin, and two spellings of
+  // that question is how `"allowedOrigins": null` in cdk.json comes to mean
+  // "they chose one" here and "use the default" there — a green synth whose
+  // deployed API allows only localhost.
+  const override = app.node.tryGetContext('allowedOrigins');
+
+  new AppStack(app, 'AppStack', {
+    description: 'API + worker for __PROJECT_NAME__ (generated by create-agent-rig)',
+    env,
+    ...(nothingGiven(override) ? { allowedOrigins: [web.origin] } : {}),
+  });
+
+  return app;
+}
+
+/**
+ * Only when the CDK CLI runs this file. A test importing `createApp` would
+ * otherwise build a second composition — and re-bundle three Lambdas — for an
+ * App nobody looks at.
+ *
+ * Both sides go through realpath: ESM resolves `import.meta.url` through
+ * symlinks while `process.argv[1]` keeps the path as typed, so a checkout
+ * behind a link (a macOS temp dir, a symlinked home) would fail a plain
+ * comparison and synthesise an empty app.
+ */
+function invokedDirectly(): boolean {
+  if (!process.argv[1]) return false;
+  const real = (p: string) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return p;
+    }
+  };
+  return real(fileURLToPath(import.meta.url)) === real(process.argv[1]);
+}
+
+if (invokedDirectly()) {
+  createApp();
+}

package/templates/skeleton/aws-serverless/infra/lib/app-stack.ts

@@ -1,6 +1,14 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { CfnOutput, Duration, RemovalPolicy, Stack, type StackProps } from 'aws-cdk-lib';
+import {
+  Annotations,
+  CfnOutput,
+  Duration,
+  RemovalPolicy,
+  Stack,
+  Token,
+  type StackProps,
+} from 'aws-cdk-lib';
 import { CorsHttpMethod, HttpApi, HttpMethod } from 'aws-cdk-lib/aws-apigatewayv2';
 import { HttpLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';
 import { ComparisonOperator, TreatMissingData } from 'aws-cdk-lib/aws-cloudwatch';
@@ -14,10 +22,131 @@ import type { Construct } from 'constructs';
 const here = path.dirname(fileURLToPath(import.meta.url));
 const workspaceRoot = path.resolve(here, '..', '..');
 
+export interface AppStackProps extends StackProps {
+  /**
+   * Browser origins allowed to call the API.
+   *
+   * `bin/app.ts` passes the CloudFront origin from `WebStack`, so a deployed
+   * app works without configuring anything. Pass this (or
+   * `-c allowedOrigins=https://…`, comma-separated, which the entrypoint
+   * prefers when given) for a custom domain, a staging origin, or several.
+   */
+  allowedOrigins?: string[];
+}
+
+/**
+ * Local dev only: a real origin is a deliberate act, not a default.
+ *
+ * The port belongs to `apps/web`'s `dev` script — that is the source of truth,
+ * and a test reads it from there rather than restating it. A default naming a
+ * port nothing serves is worse than no default: it looks configured.
+ */
+const DEFAULT_ALLOWED_ORIGINS = ['http://localhost:3001'];
+
+/**
+ * Props win, then `-c allowedOrigins=a,b`, then the local default.
+ *
+ * Anything given but unusable — an empty list, a context value that trims away
+ * to nothing, a value that is not a string — throws rather than falling back.
+ * The failure this prevents is silent: an API synthesised with an empty
+ * allow-list blocks every browser call, and the symptom appears far from the
+ * flag that caused it.
+ *
+ * Exported for the tests, and only for them — nothing else imports it. The
+ * alternative was a case per branch built on its own `AppStack`, which cost a
+ * full synth and three Lambda bundles each and put the generated project's
+ * suite over its hook timeout.
+ */
+export function resolveAllowedOrigins(fromProps: string[] | undefined, fromContext: unknown): string[] {
+  if (fromProps !== undefined) {
+    if (fromProps.length === 0) {
+      throw new Error('allowedOrigins was given as an empty list — name an origin, or omit it');
+    }
+    return fromProps.map(checkedOrigin);
+  }
+  if (nothingGiven(fromContext)) return DEFAULT_ALLOWED_ORIGINS;
+  if (typeof fromContext !== 'string') {
+    throw new Error(
+      `allowedOrigins must be a comma-separated string, got ${typeof fromContext} — ` +
+        'use -c allowedOrigins=https://example.com',
+    );
+  }
+  const origins = fromContext
+    .split(',')
+    .map((origin) => origin.trim())
+    .filter(Boolean);
+  if (origins.length === 0) {
+    throw new Error(`allowedOrigins parsed to no origin at all from ${JSON.stringify(fromContext)}`);
+  }
+  return origins.map(checkedOrigin);
+}
+
+/**
+ * Whether the caller supplied nothing. Exported because `bin/app.ts` decides
+ * the same question about the same value, and two spellings of "nothing given"
+ * is how a `null` in `cdk.json` ends up meaning "the operator chose an origin"
+ * in one file and "use the default" in the other.
+ */
+export function nothingGiven(contextValue: unknown): boolean {
+  return contextValue === undefined || contextValue === null;
+}
+
+/**
+ * An origin a browser could actually send: `*`, or a scheme plus a host.
+ *
+ * The check exists because the near-misses synthesise green and fail in the
+ * browser, far from the flag that caused them — `app.example.com` with the
+ * scheme left off is the likeliest of them, since an `Origin` header always
+ * carries one.
+ */
+function checkedOrigin(origin: string): string {
+  if (origin === '*') return origin;
+  // A cross-stack origin is a token here and a domain only at deploy time —
+  // there is nothing to parse yet, and refusing it would refuse the wiring
+  // this stack ships with.
+  if (Token.isUnresolved(origin)) return origin;
+  let parsed: URL;
+  try {
+    parsed = new URL(origin);
+  } catch {
+    throw new Error(
+      `allowedOrigins entry ${JSON.stringify(origin)} is not an origin — ` +
+        'a browser sends scheme://host[:port], as in https://app.example.com',
+    );
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error(`allowedOrigins entry ${JSON.stringify(origin)} is not an http(s) origin`);
+  }
+  // The NORMALISED form, not what was typed: a trailing slash, an uppercase
+  // scheme, a path, a unicode host or a redundant :443 all synthesise green and
+  // then match no Origin header a browser sends.
+  return parsed.origin;
+}
+
 export class AppStack extends Stack {
-  constructor(scope: Construct, id: string, props?: StackProps) {
+  constructor(scope: Construct, id: string, props?: AppStackProps) {
     super(scope, id, props);
 
+    const allowedOrigins = resolveAllowedOrigins(
+      props?.allowedOrigins,
+      this.node.tryGetContext('allowedOrigins'),
+    );
+
+    // `*` is honoured — an operator who typed it into a flag has chosen it, and
+    // refusing would push them to edit this stack instead, which is worse. It
+    // does not get to be quiet about it: the whole point of not shipping the
+    // wildcard is that reaching for it should be a visible act.
+    if (allowedOrigins.includes('*')) {
+      // V2 because it can be acknowledged: `addWarning` hard-blocks
+      // `cdk synth --strict`, which would turn "loud" into "refused" for an
+      // operator who chose the wildcard deliberately.
+      Annotations.of(this).addWarningV2(
+        '@app/allowed-origins:wildcard',
+        'allowedOrigins includes "*": every site may call this API from a browser. ' +
+          'Name the origins instead unless this is a throwaway environment.',
+      );
+    }
+
     // --- storage: one single-table DynamoDB table --------------------------
     const table = new Table(this, 'NotesTable', {
       partitionKey: { name: 'pk', type: AttributeType.STRING },
@@ -91,10 +220,13 @@ export class AppStack extends Stack {
     table.grantReadData(listFunction); // the lister only reads
 
     // --- the HTTP routes ---------------------------------------------------
-    // CORS: the web bundle is served from another origin (CloudFront).
+    // CORS: the web bundle is served from another origin (CloudFront), so the
+    // API has to name who may call it. `*` is not that name — a starter
+    // multiplies whatever it ships, and a wildcard here becomes the default of
+    // every project generated from it.
     const httpApi = new HttpApi(this, 'NotesApi', {
       corsPreflight: {
-        allowOrigins: ['*'],
+        allowOrigins: allowedOrigins,
         allowMethods: [CorsHttpMethod.GET, CorsHttpMethod.POST],
         allowHeaders: ['content-type'],
       },

package/templates/skeleton/aws-serverless/infra/lib/web-stack.ts

@@ -9,6 +9,14 @@ import { BlockPublicAccess, Bucket } from 'aws-cdk-lib/aws-s3';
 import type { Construct } from 'constructs';
 
 export class WebStack extends Stack {
+  /**
+   * Where the browser loads the app from — and therefore the origin the API
+   * has to allow. A synth-time token: CDK resolves it across stacks as an
+   * `Fn::ImportValue`, so `AppStack` can name it without either stack having
+   * been deployed yet.
+   */
+  public readonly origin: string;
+
   constructor(scope: Construct, id: string, props?: StackProps) {
     super(scope, id, props);
 
@@ -26,7 +34,12 @@ export class WebStack extends Stack {
       defaultRootObject: 'index.html',
     });
 
+    this.origin = `https://${distribution.domainName}`;
+
     new CfnOutput(this, 'WebBucketName', { value: bucket.bucketName });
-    new CfnOutput(this, 'WebUrl', { value: `https://${distribution.domainName}` });
+    new CfnOutput(this, 'WebUrl', { value: this.origin });
+    // The upload step needs this to invalidate the edge cache: a synced bucket
+    // whose distribution still serves the old objects has not deployed.
+    new CfnOutput(this, 'WebDistributionId', { value: distribution.distributionId });
   }
 }