Add examples/setup-aws.sh: one-command AWS provisioning

README.md

@@ -81,19 +81,19 @@ The default `GITHUB_TOKEN` in Actions is scoped to the workflow's own repo. To a
 
 A commented S3 variant in the example workflow stores both `dora.db` and `dora-report.json` in S3 instead of using the cache + git-commit pattern. Useful if you'd rather not have JSON history in your git log, or if you want guaranteed persistence beyond the 7-day cache eviction window.
 
-**Recommended auth: GitHub OIDC.** Short-lived credentials assumed at workflow runtime; no long-lived AWS keys to rotate, no secrets stored in the repo. Setup is two AWS resources:
+**Recommended auth: GitHub OIDC.** Short-lived credentials assumed at workflow runtime; no long-lived AWS keys to rotate, no secrets stored in the repo. Run [`examples/setup-aws.sh`](examples/setup-aws.sh) to provision the bucket, OIDC provider, and IAM role in one command:
 
-1. An IAM OIDC identity provider for `token.actions.githubusercontent.com`.
-2. An IAM role with a trust policy restricted to your repo (and optionally branch), and a policy granting `s3:GetObject` + `s3:PutObject` on the bucket prefix.
+    ./examples/setup-aws.sh \
+      --repo OWNER/REPO --bucket BUCKET --region REGION [--branch main]
 
-The workflow then uses [`aws-actions/configure-aws-credentials@v4`](https://github.com/aws-actions/configure-aws-credentials) with `role-to-assume: …`. See the example workflow comments for the exact policy/role shape.
+The script prints the role ARN and bucket details to paste into your workflow. See `examples/setup-aws.sh --help` for full options, or the workflow file's S3-variant section for the underlying resources if you'd rather provision by hand.
 
 **Fallback: long-lived access keys.** If you don't have AWS-side access to set up OIDC, store `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` as repo secrets and pass them via env vars on the relevant steps.
 
 Either way, you'll also need:
 
 - Bucket CORS config allowing `GET` from `*` (so the dashboard can fetch the JSON)
-- The DB is stored privately; only the JSON is `--public-read`
+- The DB is stored privately; only the JSON is publicly readable (via a bucket policy scoped to `dora-report.json`)
 
 ## Metric definitions
 

docs/superpowers/plans/2026-04-27-aws-setup-script-smoke-test.md

@@ -0,0 +1,89 @@
+# `setup-aws.sh` Manual Smoke Test
+
+Run this against a real AWS test account before merging changes to the
+script. Unit tests stub `aws`; this exercises the actual API contract.
+
+## Setup
+
+- An AWS account where you have IAM + S3 admin permissions.
+- A test repo (yours, doesn't need to be a fork of dora — the trust policy
+  references it but no real workflow needs to run).
+- `aws configure sso` (or env vars) targeting the test account.
+
+## 1. Fresh setup, no `--branch`
+
+    ./examples/setup-aws.sh \
+      --repo your-handle/test-repo \
+      --bucket dora-smoketest-$(date +%s) \
+      --region us-east-1
+
+Expected:
+- Script exits 0.
+- Stderr shows: OIDC creating (or reusing), bucket creating, BPA, CORS,
+  bucket policy, role creating, inline policy.
+- Stderr contains "no --branch given … Recommend --branch main".
+- Stdout shows summary block with role ARN, bucket name, dashboard URL.
+
+Verify in the AWS console:
+- IAM → Identity providers → token.actions.githubusercontent.com exists.
+- IAM → Roles → dora-report-uploader exists with the expected trust policy
+  (`StringLike` sub = `repo:your-handle/test-repo:*`) and inline policy
+  scoped to two S3 keys.
+- S3 → bucket → Permissions → Bucket policy contains the public-read
+  statement on dora-report.json.
+- S3 → bucket → Permissions → CORS contains the GET-from-* rule.
+
+## 2. Re-run idempotency
+
+Run the same command again. Expected:
+- Script exits 0.
+- Stderr: "OIDC provider already exists, reusing", "bucket already exists,
+  reusing", "updating existing role's trust policy".
+
+## 3. Branch restriction update
+
+Re-run with `--branch main`:
+
+    ./examples/setup-aws.sh \
+      --repo your-handle/test-repo \
+      --bucket <same-bucket-as-step-1> \
+      --region us-east-1 \
+      --branch main
+
+Expected:
+- Stderr: "role exists; updating".
+- Verify in console: trust policy `StringLike` sub now =
+  `repo:your-handle/test-repo:ref:refs/heads/main`.
+
+## 4. `--existing-bucket` mode
+
+    ./examples/setup-aws.sh \
+      --repo your-handle/test-repo \
+      --existing-bucket <bucket-from-step-1> \
+      --region us-east-1
+
+Expected:
+- Stderr does NOT include "creating bucket", "applying CORS", "applying
+  bucket policy". It DOES include OIDC and IAM steps.
+- Stdout summary includes the "--existing-bucket was used … your responsibility"
+  caveat.
+
+## 5. Bucket name taken by another owner (403)
+
+Pick a bucket name you know is taken (e.g. `aws`, `s3`):
+
+    ./examples/setup-aws.sh \
+      --repo your-handle/test-repo \
+      --bucket aws \
+      --region us-east-1
+
+Expected:
+- Script exits non-zero.
+- Stderr surfaces the AWS error verbatim ("BucketAlreadyExists" or similar).
+
+## 6. Cleanup
+
+    aws s3 rb s3://<your-bucket> --force
+    aws iam delete-role-policy --role-name dora-report-uploader --policy-name dora-s3-access
+    aws iam delete-role --role-name dora-report-uploader
+    # Leave the OIDC provider in place — it's account-wide and may be reused.