From e56f06a55bd746161713ea3006680d85ca284523 Mon Sep 17 00:00:00 2001 From: Rahul Varghese Date: Wed, 28 Oct 2026 11:45:39 +0530 Subject: [PATCH] WP2: cms-wordpress becomes an Orun baseline cms-sanity's machinery on this tree, in the turso v8 shape: blueprint.yaml (the console card: one Cloudflare provider, the subdomain read from the connection, no domain asked, WordPress connected by its owner afterwards) and repo-blueprint.yaml (one landing, 01-product, then the record, 02-docs; task set-up in the background, landings checked in the box, a 5 s watch, one secrets reconcile). .baseline/ (identity, the product's README with Connecting WordPress and Deploy by hand, task contracts), the rename engine, the bootstrap helpers, the deployment-record renderer probing /, /posts (sample or connected) and the webhook, the phase pages with minutes, the context pack, and the baseline's tests: manifest, phases, coverage, rebrand, retouch, bootstrap-defer, generated component docs, the leak gate, the offline bootstrap with the site's own plan, and the end-to-end tier that builds the site in the stage lane's staged tree and reads every route it promises, unconnected. Every tier passes locally on orun v2.89.0. Co-Authored-By: Claude Orun-Task: WP-3 --- .baseline/identity.json | 9 + .baseline/product/README.md | 177 +++++ .baseline/tasks/01-product.TaskContract.yaml | 23 + .baseline/tasks/02-docs.TaskContract.yaml | 13 + .github/workflows/baseline.yml | 151 ++++ .github/workflows/tag.yml | 97 +++ BOOTSTRAP.md | 241 +++++++ README.md | 55 +- ai/context/current.md | 45 ++ ai/context/decisions.md | 26 + ai/context/deployment.md | 7 + ai/context/open-risks.md | 17 + ai/context/operations.md | 166 +++++ blueprint.yaml | 157 +++++ docs/phases/01-product.md | 115 +++ docs/phases/02-docs.md | 39 + docs/phases/README.md | 143 ++++ hooks/render-deployment-docs.sh | 159 +++++ repo-blueprint.yaml | 666 ++++++++++++++++++ specs/epics/README.md | 2 +- .../cms-wordpress/IMPLEMENTATION-STATUS.md | 2 +- specs/epics/cms-wordpress/README.md | 2 +- specs/epics/cms-wordpress/epic.yaml | 2 +- testing/bootstrap-defer.test.sh | 67 ++ testing/coverage.test.sh | 263 +++++++ testing/e2e.test.sh | 438 ++++++++++++ testing/fixtures/acme.json | 25 + .../baseline-identity.cms-wordpress.json | 9 + testing/leak.test.sh | 174 +++++ testing/lib/bootstrap.sh | 69 ++ testing/lib/run-hooks.py | 72 ++ testing/lib/stage-job.py | 86 +++ testing/manifest.test.sh | 446 ++++++++++++ testing/phases.test.sh | 429 +++++++++++ testing/placement.test.sh | 325 +++++++++ testing/rebrand.test.sh | 202 ++++++ testing/retouch.test.sh | 199 ++++++ tooling/bootstrap/dev-lanes.mjs | 114 +++ tooling/bootstrap/promotion.mjs | 123 ++++ tooling/bootstrap/retouch.mjs | 254 +++++++ tooling/bootstrap/work-tree.mjs | 73 ++ tooling/rebrand/rebrand.mjs | 465 ++++++++++++ tooling/rebrand/values.example.json | 8 + 43 files changed, 6147 insertions(+), 8 deletions(-) create mode 100644 .baseline/identity.json create mode 100644 .baseline/product/README.md create mode 100644 .baseline/tasks/01-product.TaskContract.yaml create mode 100644 .baseline/tasks/02-docs.TaskContract.yaml create mode 100644 .github/workflows/baseline.yml create mode 100644 .github/workflows/tag.yml create mode 100644 BOOTSTRAP.md create mode 100644 ai/context/current.md create mode 100644 ai/context/decisions.md create mode 100644 ai/context/deployment.md create mode 100644 ai/context/open-risks.md create mode 100644 ai/context/operations.md create mode 100644 blueprint.yaml create mode 100644 docs/phases/01-product.md create mode 100644 docs/phases/02-docs.md create mode 100644 docs/phases/README.md create mode 100755 hooks/render-deployment-docs.sh create mode 100644 repo-blueprint.yaml create mode 100755 testing/bootstrap-defer.test.sh create mode 100755 testing/coverage.test.sh create mode 100755 testing/e2e.test.sh create mode 100644 testing/fixtures/acme.json create mode 100644 testing/fixtures/baseline-identity.cms-wordpress.json create mode 100755 testing/leak.test.sh create mode 100755 testing/lib/bootstrap.sh create mode 100755 testing/lib/run-hooks.py create mode 100755 testing/lib/stage-job.py create mode 100755 testing/manifest.test.sh create mode 100755 testing/phases.test.sh create mode 100755 testing/placement.test.sh create mode 100755 testing/rebrand.test.sh create mode 100755 testing/retouch.test.sh create mode 100755 tooling/bootstrap/dev-lanes.mjs create mode 100755 tooling/bootstrap/promotion.mjs create mode 100755 tooling/bootstrap/retouch.mjs create mode 100755 tooling/bootstrap/work-tree.mjs create mode 100755 tooling/rebrand/rebrand.mjs create mode 100644 tooling/rebrand/values.example.json diff --git a/.baseline/identity.json b/.baseline/identity.json new file mode 100644 index 0000000..99d8437 --- /dev/null +++ b/.baseline/identity.json @@ -0,0 +1,9 @@ +{ + "_comment": "THIS TREE'S OWN IDENTITY — the FROM side of every rebrand. tooling/rebrand/rebrand.mjs reads it to know what to rename AWAY from; a product's identity is the --values file, which is the TO side. Change a value here only together with the tree: these strings must be what the tree actually contains, or the rename silently misses and the product ships carrying this baseline's name. `productName` is the SITE_NAME seam in apps/web/site.config.ts (the upstream template's own name, `next-wp`); `domain` and `subdomain` are placeholders, because this baseline has never deployed under a name of its own; `githubOwner` is the owner in the source links the docs carry.", + "slug": "cms-wordpress", + "pascal": "CmsWordpress", + "productName": "next-wp", + "domain": "cms-wordpress.example.com", + "subdomain": "your-workers-subdomain", + "githubOwner": "sourceplane" +} diff --git a/.baseline/product/README.md b/.baseline/product/README.md new file mode 100644 index 0000000..c26c6e7 --- /dev/null +++ b/.baseline/product/README.md @@ -0,0 +1,177 @@ +# cms-wordpress + +A Next.js front end for a [WordPress](https://wordpress.org) site, used as a +headless CMS: posts, pages, categories, tags and authors are read from the +site's REST API (`/wp-json/wp/v2`), with search, filters, pagination, a +sitemap, Open Graph images and a revalidation webhook for WordPress — running +on **Cloudflare Workers + Static Assets** through +[`@opennextjs/cloudflare`](https://opennext.js.org/cloudflare). It is +Vercel's [Next.js Starter for WordPress Headless CMS](https://github.com/9d8dev/next-wp) +(9d8's `next-wp`), ported to Workers. + +## Live deployment + + +Not recorded yet. The bootstrap's last phase writes the live URLs, the +workspace and the secrets the site uses into +[ai/context/deployment.md](ai/context/deployment.md); how the site deploys +and how to operate it is in +[ai/context/operations.md](ai/context/operations.md). + + +## Connecting WordPress + +The site deploys and serves before it has a WordPress behind it: until its +build is given a WordPress URL it shows a few **sample posts**, a sample page +and their categories, tags and author, bundled with it, under a notice that +says so. To make it read your content: + +1. **Have a WordPress site whose REST API answers**: `https:///wp-json/wp/v2/posts` + returns JSON. Any self-hosted or managed WordPress does by default; the + site reads only published content, so it needs no credentials. +2. **Give the build its URL**, once per deployed environment. `next build` + bakes it in, so it is stored as this repository's Orun secret + `WORDPRESS_URL`, and stage and prod can each name their own (a staging + WordPress for stage, say): + + ```bash + orun secrets set WORDPRESS_URL --env stage # prompts for the value: https:// + orun secrets set WORDPRESS_URL --env prod + ``` + + Then **redeploy the site**: a secret is read when the site builds, and + setting one builds nothing. Press **Deploy** on the `web` component in + Orunbase (or see "Deploy by hand" below); the sample content and the + notice are gone from that deploy on, and `/admin` redirects to your + site's `wp-admin`. +3. **Images** need nothing: featured images are served as uploaded, from + wherever your WordPress's media URLs point (`images.unoptimized` — the + Worker has no image optimiser, so next/image passes them through). +4. **The revalidation webhook** (optional). Every page renders on every + request, so a change you publish shows on the next visit with nothing + else set up. The template's `next-revalidate` plugin + ([download](https://github.com/9d8dev/next-wp/releases/latest/download/next-revalidate.zip)) + calls `/api/revalidate` when content changes; to accept it, give the + plugin (WordPress → Settings → Next.js Revalidation: this site's URL and + the secret) and each Worker one shared secret, a Cloudflare Worker secret + that deploys leave alone: + + ```bash + pnpm --filter @app/web exec wrangler secret put WORDPRESS_WEBHOOK_SECRET --name cms-wordpress-web-stage + pnpm --filter @app/web exec wrangler secret put WORDPRESS_WEBHOOK_SECRET --name cms-wordpress-web-prod + ``` + + Without it every webhook is refused with 401, and nothing else changes. + +## What is here + +| Surface | Where | +|---|---| +| Home, `/posts` (search, filters, pagination), `/posts/[slug]`, `/pages`, `/pages/[slug]`, the category, tag and author lists | `apps/web/app` | +| The WordPress REST client, its types | `apps/web/lib/wordpress.ts`, `apps/web/lib/wordpress.d.ts` | +| The sample content an unconnected site shows, and its notice | `apps/web/lib/sample.ts`, `apps/web/components/unconnected-notice.tsx` | +| The revalidation webhook, the Open Graph image, the sitemap | `apps/web/app/api/revalidate`, `apps/web/app/api/og`, `apps/web/app/sitemap.ts` | +| The site's name, description and origin; the menus | `apps/web/site.config.ts`, `apps/web/menu.config.ts` | +| Components (craft, shadcn/ui), the theme toggle | `apps/web/components` | +| Workers build and deploy contract | `apps/web/next.config.ts`, `open-next.config.ts`, `wrangler.jsonc`, `component.yaml` | +| Tests | `tests/web` (vitest) | + +## Getting started + +```bash +pnpm install +pnpm typecheck +pnpm lint +pnpm test +pnpm build # next build + opennextjs-cloudflare build → apps/web/.open-next +``` + +That needs no WordPress, and is what to run before you push: a pull request +builds the site but does not lint or run its tests. With a WordPress: + +```bash +cd apps/web +cp .env.example .env.local # WORDPRESS_URL=https:// +cd ../.. +pnpm --filter @app/web dev # http://localhost:3000 +``` + +For the Worker locally, the URL is read at build time and the webhook secret +is a Worker secret: + +```bash +cd apps/web +cp .dev.vars.example .dev.vars # WORDPRESS_WEBHOOK_SECRET= +WORDPRESS_URL=https:// pnpm build +pnpm preview # wrangler dev over the built Worker +``` + +| Variable | Read | What it does | +|---|---|---| +| `WORDPRESS_URL` | build time | The WordPress site. Deployed builds take it from the `WORDPRESS_URL` secret of their environment. Unset, the site is unconnected: sample content and a notice. | +| `WORDPRESS_HOSTNAME` | build time | The template's next/image allow-list for media; the URL's own when unset. Inert while images are unoptimised. | +| `NEXT_PUBLIC_SITE_URL` | build time | The site's origin for absolute links (the sitemap, canonical and Open Graph links). The deploy sets it per environment. | +| `WORDPRESS_WEBHOOK_SECRET` | request time, in the Worker | The secret `/api/revalidate` checks. Optional. | +| `NEXT_PUBLIC_CF_BEACON_TOKEN` | build time | Optional Cloudflare Web Analytics token. Unset, no script is rendered. | + +## How it deploys + +Merges to `main` converge through [Orun](https://github.com/sourceplane/orun): +`.github/workflows/ci.yml` plans the changed components and runs each lane +against the workspace in `intent.yaml`. The site builds once per +environment, with that environment's WordPress URL and origin, and deploys — +to `stage`, then to `prod` once stage has converged on the same commit; +`dev` only verifies. The Worker is `cms-wordpress-web-` on your account's +workers.dev subdomain, and every deploy is smoke-tested over HTTP: the posts +page must render its count and the revalidation webhook must refuse a +request without the secret. A pull request runs the same pipeline's verify +lanes: the site built and dry-deployed for each environment, with nothing +deployed. They do not lint or run the tests, so run `pnpm typecheck`, +`pnpm lint` and `pnpm test` before you push. (A push to `main` builds, +deploys and smoke-tests.) + +The pipeline holds one credential, GitHub's own `GITHUB_TOKEN`. The +Cloudflare token and account id are brokered per run from the workspace's +Cloudflare connection; nothing provider-shaped is stored in the repository +or in GitHub. + +**Deploy by hand.** Orunbase's **Deploy** button on a component, or **Run +workflow** on the CI workflow in GitHub's Actions tab (on `main`), runs +`ci.yml` for the environment and components you pick, and each one deploys +exactly as a merge would deploy it. Leave the component blank to redeploy +every component in that environment, with nothing changed: after setting +`WORDPRESS_URL`, say. A component with nothing to run in that environment (a +test suite in `prod`) is left out with a notice. + +## Custom domain + +The site answers on workers.dev from its first deploy. To serve it on your +own domain: + +1. Add the domain to the Cloudflare account the site deploys into, and attach + it to the Worker (dashboard → Workers & Pages → + `cms-wordpress-web-prod` → Settings → Domains & Routes → Add → + Custom domain). +2. Set the environment's public origin in `intent.yaml`, so the next deploy + builds the site's absolute links for it — the sitemap, canonical and Open + Graph links (until then they use the workers.dev URL): + + ```yaml + environments: + prod: + env: + SITE_URL: https://cms-wordpress.example.com + ``` + + The site was born with the reserved placeholder + `cms-wordpress.example.com` where its domain goes: that example, and + `BASE_DOMAIN` under each environment in `intent.yaml`. Replace it with + your domain in the same change, and land it with a change under + `apps/web` so the merge rebuilds the site. Then point the + `next-revalidate` plugin at the new origin, if you use it. + +## Credits + +The site is 9d8's [next-wp](https://github.com/9d8dev/next-wp) (MIT — +`apps/web/LICENSE`), the template Vercel lists as its Next.js Starter for +WordPress Headless CMS. diff --git a/.baseline/tasks/01-product.TaskContract.yaml b/.baseline/tasks/01-product.TaskContract.yaml new file mode 100644 index 0000000..b04286a --- /dev/null +++ b/.baseline/tasks/01-product.TaskContract.yaml @@ -0,0 +1,23 @@ +# Task contract template for the 01-product landing — the whole site in one +# pull request. Unbound to a key on purpose: `orun.task/ensure@v1` seals and +# attaches it to the key the allocator issues. It lives under `.baseline/`, +# not `tasks/`, because `tasks/` is this repository's own work tree +# (`intent.yaml` `work:`), where an unkeyed contract is an error. gates: [] is +# a DECLARATION — merge alone finishes this task; the main convergence is the +# gate the bootstrap watches, not one the plane observes as a PR check. +# +# `affects` names COMPONENTS, by metadata.name: the phase's retouch hook reads +# this list to decide which component.yaml files get the redeploy marker, so +# the deploy set and the task plane's statement of the work are one list. +apiVersion: orun.io/v1 +kind: TaskContract +spec: + goal: The site's repository is born and linked, the whole site lands in one pull request, and one convergence deploys it to stage and prod — serving its sample posts until a WordPress site is connected + affects: + - web + - web-tests + doneWhen: + - repo pushed, main pinned as default, workspace linked + - main convergence green (build, deploy and smoke on stage and prod) + - the site answers on both workers.dev URLs + gates: [] diff --git a/.baseline/tasks/02-docs.TaskContract.yaml b/.baseline/tasks/02-docs.TaskContract.yaml new file mode 100644 index 0000000..45aedc8 --- /dev/null +++ b/.baseline/tasks/02-docs.TaskContract.yaml @@ -0,0 +1,13 @@ +# Task contract template for the 02-docs landing. See 01-product's header. +apiVersion: orun.io/v1 +kind: TaskContract +spec: + goal: The live deployment is recorded from verified facts as agent-readable state in the site's repo + affects: + - ai/context/deployment.md + - ai/context/operations.md + - README.md + doneWhen: + - committed deployment manifest matches probed reality + - prod waits on stage again, and dev verifies every merge to main again + gates: [] diff --git a/.github/workflows/baseline.yml b/.github/workflows/baseline.yml new file mode 100644 index 0000000..1afa03e --- /dev/null +++ b/.github/workflows/baseline.yml @@ -0,0 +1,151 @@ +name: Baseline CI + +# THE FACTORY'S OWN LANES — this repository tested as a BASELINE: that its +# build document parses with the orun a bootstrap actually runs, that its card +# agrees with it, that every component is placed by the one product phase, +# that a placed tree comes up branded and carrying nothing of the factory — +# and plans the site onto stage and prod on a merge — and that the site it +# produces installs, builds, deploys (dry) and serves with no WordPress +# behind it. +# +# ─── WHY THIS IS NOT IN ci.yml ──────────────────────────────────────────── +# +# `repo-blueprint.yaml`'s `github-workflows` module copies the WHOLE `.github` +# directory into every site built from this repository. These jobs run +# `testing/*.sh`, and `testing/` is deliberately not placed — so in a site they +# would be steps that cannot pass, red on its very first pull request. This +# file is in the blueprint's `ignore` list, and `testing/coverage.test.sh` +# fails on any workflow that reads `testing/` and is not. + +on: + push: + branches: [main] + pull_request: + +concurrency: + group: baseline-ci-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +permissions: + contents: read + +jobs: + # Tier 0. bash, python3 and git; node for the tools. No workspace install, + # no network, no credential — the job that most certainly fails a PR. + baseline-contract: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + - uses: actions/setup-node@v5 + with: + node-version: 22 + # setup-node v5 turns on the pnpm cache by itself when package.json + # names a packageManager, and then fails on a runner with no pnpm. + # This job installs nothing. + package-manager-cache: false + - name: Contract tests (manifest, phases, coverage, rebrand, retouch, bootstrap-defer) + run: | + set -euo pipefail + python3 -c 'import yaml' 2>/dev/null || pip install --quiet pyyaml + for t in manifest phases coverage rebrand retouch bootstrap-defer; do + echo "── $t" + bash "testing/$t.test.sh" + done + # Every component's docs/{overview,architecture,runbook}.md is generated + # from what the component declares (its manifest, Worker config, + # Terraform, migrations, package scripts). A pull request that changes + # one of those facts without regenerating the pages fails here. + - name: Component docs match their manifests + run: python3 tooling/catalog/gen-component-docs.py --check + + # Tier 1. THE BLUEPRINT, READ AND PLACED BY THE BINARY A BOOTSTRAP RUNS. + # + # Pinned at the bootstrap floor (BOOTSTRAP.md), not the site's lane pin: + # every test here reads YAML with PyYAML, which parses anything well-formed; + # only the pinned orun can say whether the document is one a bootstrap can + # run. `--status` parses it, validates every hook against the action + # registry, compiles every `when` and narration template, and writes + # nothing. Then the leak gate (what a product would carry, derived by the + # floor too), and the placement tier (the offline bootstrap: both phases + # placed and finished by the blueprint's own hooks, then the product's own + # `orun plan` for the 01-product merge, below). + blueprint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + - uses: sourceplane/orun-action@v1.2.0 + with: + version: v2.88.0 + - uses: pnpm/action-setup@v4 + with: + version: 10.12.1 + - uses: actions/setup-node@v5 + with: + node-version: 22 + # This job installs nothing either: with no lockfile hook the offline + # bootstrap never runs pnpm, so there is no store, and the pnpm cache + # setup-node v5 turns on by itself (package.json names a packageManager) + # fails the job saving a path that does not exist whenever no earlier + # cache exists for the lockfile. + package-manager-cache: false + - name: repo-blueprint.yaml, read by the pinned CLI + run: | + set -euo pipefail + orun --version + python3 -c 'import yaml' 2>/dev/null || pip install --quiet pyyaml + # Required inputs must be supplied for the document to resolve; the + # values are arbitrary and nothing is written. + orun new --blueprint repo-blueprint.yaml --status \ + --out "$(mktemp -d)" \ + --set reponame=acme-site \ + --set "productname=Acme Site" \ + --set githuborg=acme-inc + - name: the leak gate — what a product carries + run: bash testing/leak.test.sh + # The placement tier ENDS with the product's own `orun plan` — what the + # product's ci.yml runs — so it needs an orun at the product's lane pin + # (v2.78.4) or newer: the plan a convergence waits on is the lane pin's + # (its optional secret refs included), and the test refuses an orun + # older than the pin rather than assert the wrong CLI's plan. The + # offline bootstrap before it reads the blueprint, which takes the + # bootstrap floor (v2.88.0: the one `secrets` reconcile, the task set-up + # in the background, the landings checked in the box), so this tier + # runs the floor, which is newer than the lane pin. + - uses: sourceplane/orun-action@v1.2.0 + with: + version: v2.88.0 + - name: placement — the offline bootstrap, and the product's own plan + run: | + git config --global user.email ci@example.invalid + git config --global user.name "baseline ci" + bash testing/placement.test.sh + + # Tier 2. THE SITE IT PRODUCES WORKS, WITH NO WORDPRESS: each landing + # installed, its fixture rendered, type-checked, linted, tested and built, + # the stage lane's own structure check, build, output check and dry deploy + # in the tree orun stages, and the built Worker served and smoke-tested with + # the component's own smoke command — the sample posts and pages under the + # "no WordPress site is connected" notice, the filters, the sitemap, the + # Open Graph image and the webhook's refusal. Pinned at the bootstrap floor (v2.88.0): the offline bootstrap + # reads the blueprint, and the floor is newer than the product's lane pin + # (v2.78.4), which is all the lane steps need. + site: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + - uses: sourceplane/orun-action@v1.2.0 + with: + version: v2.88.0 + - uses: pnpm/action-setup@v4 + with: + version: 10.12.1 + - uses: actions/setup-node@v5 + with: + node-version: 22 + cache: pnpm + - name: e2e — the bootstrapped site builds, deploys (dry) and serves + run: | + python3 -c 'import yaml' 2>/dev/null || pip install --quiet pyyaml + git config --global user.email ci@example.invalid + git config --global user.name "baseline ci" + bash testing/e2e.test.sh diff --git a/.github/workflows/tag.yml b/.github/workflows/tag.yml new file mode 100644 index 0000000..c0383e3 --- /dev/null +++ b/.github/workflows/tag.yml @@ -0,0 +1,97 @@ +name: Baseline tag + +# CUTS A `baseline-vN` TAG FOR THIS REPOSITORY. +# +# A baseline tag is what the platform's registry resolves and what every +# product bootstrapped from this repository is built out of, so it is cut by a +# workflow rather than by hand: the version must look like a baseline tag, an +# existing tag is never moved, and the commit is resolved here, once. +# +# Whether a commit is fit to release is decided outside this repository, by +# whoever cuts the tag; nothing here asks for proof beyond a green `main`. + +on: + workflow_dispatch: + inputs: + version: + description: "The tag to cut, e.g. baseline-v2." + required: true + type: string + ref: + description: "Branch, tag or sha to cut it from. Defaults to main." + required: false + default: main + type: string + +concurrency: + group: baseline-tag + cancel-in-progress: false + +permissions: + contents: read + +jobs: + cut: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/checkout@v6 + with: + # Full history: the ref being cut from may be any commit, and a + # shallow clone cannot resolve one it did not fetch. + fetch-depth: 0 + ref: ${{ inputs.ref }} + + - name: the version must look like a baseline tag + run: | + set -euo pipefail + # Refused here rather than by the API, because the API's error for a + # malformed ref says nothing about the convention it broke. + case "${{ inputs.version }}" in + baseline-v[0-9]*) ;; + *) echo "✕ '${{ inputs.version }}' is not a baseline-vN tag" >&2; exit 1 ;; + esac + + - name: resolve the commit + id: commit + run: | + set -euo pipefail + sha="$(git rev-parse HEAD)" + echo "sha=$sha" >> "$GITHUB_OUTPUT" + echo "Cutting ${{ inputs.version }} from ${{ inputs.ref }} = $sha" + + - name: the tag must not already exist + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + set -euo pipefail + code="$(curl -sS -o /dev/null -w '%{http_code}' \ + -H "Authorization: Bearer $GH_TOKEN" \ + -H "Accept: application/vnd.github+json" \ + "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/git/ref/tags/${{ inputs.version }}")" + if [ "$code" = "200" ]; then + echo "✕ ${{ inputs.version }} already exists. A baseline tag is never moved:" >&2 + echo " products resolve it, and repointing one changes what a build that" >&2 + echo " already shipped was made of. Cut the next number." >&2 + exit 1 + fi + # Anything other than 200 or 404 means the question was not answered, + # and "it probably does not exist" is not a thing to guess about a + # tag that is about to be created. + [ "$code" = "404" ] || { echo "✕ could not check for the tag (HTTP $code)" >&2; exit 1; } + + - name: cut the tag + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + set -euo pipefail + curl -sS -X POST --fail-with-body \ + -H "Authorization: Bearer $GH_TOKEN" \ + -H "Accept: application/vnd.github+json" \ + "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/git/refs" \ + -d "$(printf '{"ref":"refs/tags/%s","sha":"%s"}' \ + "${{ inputs.version }}" "${{ steps.commit.outputs.sha }}")" + echo "" + echo "✓ ${{ inputs.version }} → ${{ steps.commit.outputs.sha }}" + echo " Next: move the registry row in orun-cloud's infra/baselines-registry/baselines.yaml." diff --git a/BOOTSTRAP.md b/BOOTSTRAP.md new file mode 100644 index 0000000..391f169 --- /dev/null +++ b/BOOTSTRAP.md @@ -0,0 +1,241 @@ +# BOOTSTRAP — a new site from this baseline, in one landing + +How to go from **nothing** to **a headless WordPress site live on stage +and prod, documented**, with ONE provider consent — and how its owner then +connects it to a WordPress site. + +There is one artifact: **`repo-blueprint.yaml`**. It declares what to place, +in what order, what each phase needs first, and what to say while it runs. +`orun new` is the whole runtime — the phases below are its `--phase` names, +not separate workflows. The console card the platform renders is +**`blueprint.yaml`**; it names the build document and states the inputs, the +brokered secrets and the programme, and `testing/manifest.test.sh` holds it +to what the build document does. + +Target wall-clock: **about twelve minutes** — an estimate summed from the +phases (11 + 1) until a bootstrap on this shape measures it. The shape: the +task set-up in the background while ONE landing places the whole site, +brands it and checks it in the box (`orun validate` and `orun plan`, no +runner waited for — its pull request no longer waits on a full Next.js build +in Checks), then one convergence that builds and deploys it to stage and +prod side by side, then a short docs landing that records it. It is +cirrus-baseline's one-landing shape (baseline-v22): no scaffold landing of +its own, no second landing for the app. + +## 0. What you need + +- GitHub org access (repository creation) and a machine with `git`, `node` + (≥ 22), `pnpm` (10.12.1), `python3` with PyYAML, `curl`, and the `orun` + CLI **≥ v2.88.0** — the floor for RUNNING the bootstrap (the phase overlay, + landings that commit per phase, `githubOwner` on the doctor probe, a probe + deferred for a project not yet created, `from: workspace`, the deploy + credentials minted in one `secrets` reconcile, the task set-up run in the + background (`background: true`), and landings checked in the box before + they merge (`checks: local`)). The site's own `ci.yml` pins its lanes + separately (v2.78.4). +- A Cloudflare account (the free plan is enough for one Worker with Static + Assets) and its **Account API token** with Workers Scripts Write (the + console's Connect recipe lists the exact permission groups). It is the ONLY + provider credential the bootstrap needs. +- **No WordPress.** WordPress is the owner's own site, which the platform + does not broker, so the bootstrap neither asks for nor creates one: the + site is built, deployed and verified unconnected — it serves bundled + sample posts under a "no WordPress site is connected" notice. Its owner + connects a WordPress afterwards (§3). +- An Orun Cloud workspace for the site — `orunWorkspace`, or the workspace + the build runs in (ORUN_WORKSPACE) when that is unset — with an + **admin-role API key** for headless runs (secret writes below admin are + masked as `not_found`). +- **The repository allow-listed in the workspace** (console → Settings → Git + repos), unless the credential can write links. `01-product`'s `link` step + stops and names the fix if it is not. + +## 1. One command: `--resume` + +The whole bootstrap, unattended. `--resume` places every phase not already +derived as done, in order, honouring each phase's barrier: + +```bash +git clone --depth 1 --branch https://github.com/sourceplane/cms-wordpress +cd cms-wordpress + +orun new --blueprint repo-blueprint.yaml \ + --out ~/sites/acme-notes --run-hooks --resume \ + --set reponame=acme-notes --set productname="Acme Notes" \ + --set githuborg=acme-inc \ + --set orunWorkspace=ws_XXXXXXXX \ + --set subdomain= +``` + +`subdomain` is the workers.dev subdomain of the Cloudflare account you deploy +into (Workers & Pages → your subdomain). A build started from the console, or +with `orun baseline new --from bst_…`, never asks for it: the platform reads +it from the workspace's Cloudflare connection, the same one the deploy token +is minted from. Only a hand-run build like this one passes it. + +**`--run-hooks` is the difference between placing files and bootstrapping a +site.** Without it `orun new` writes the tree and stops: no repository, no +landing, no convergence watch, no probe. That is deliberate — it is what +makes the offline bootstrap in `testing/` possible with no workspace and no +provider. + +`--resume` is safe to re-run from anywhere, a fresh container with a fresh +`--out` included: **phase state is derived from the tree, never stored.** A +phase whose files are present but branded derives as `drifted`, and +`--resume` leaves it placed rather than reverting the site's identity. + +## 1b. Or phase by phase + +| phase | what it lands | verified by | +|---|---|---| +| `01-product` | the repository, created and linked; the WHOLE site in one PR — intent, CI, tooling, identity, `apps/web` + `tests/web`; the brokered Cloudflare secrets | its commit validated and planned in the box (as the PR and as the merge), then merged; the convergence green (build, deploy, smoke) and the site answering on both workers.dev URLs | +| `02-docs` | `ai/context/deployment.md` from probed facts; prod's promotion gate and dev's push lanes restored | the render's own probes, recorded; the commit checked in the box and merged | + +```bash +orun new --blueprint repo-blueprint.yaml --out ~/sites/acme-notes --run-hooks \ + --phase 01-product --values ~/acme-notes.values.yaml +# … then 02-docs +``` + +`02-docs` reads the identity back from `.rebrand/values.json` in the placed +tree, but the blueprint's **required** inputs — `reponame`, `productname`, +`githuborg` — are validated before anything runs, so pass them every time (a +`--values` file is easier). The domain is not one of them: the site goes live +on workers.dev, and `productdomain` defaults to empty, which brands the +reserved placeholder `.example.com` into `BASE_DOMAIN` for an owner +to replace when they attach a domain (README, "Custom domain"). Pass +`--set productdomain=` only for a site that already has its domain. +The full guide, one page per phase: [docs/phases/README.md](docs/phases/README.md). + +| flag | what it does | +|---|---| +| `--status` | derives and prints every phase's state and writes nothing. It parses the document, validates each hook against the action registry and compiles every template; it needs no credential and no network | +| `--phase ` | places exactly that phase; its `requires.phases` still gates | +| `--until ` | places every phase through that one and stops | + +What lands in the site is PRODUCT-ONLY: the app, its tests, its CI, its +tooling, its README and its two context pages. None of this repository's +machinery (`.baseline/`, the blueprints, `tooling/rebrand`, +`tooling/bootstrap`, `hooks/`, `testing/`, `docs/phases/`, `specs/`, +`tasks/`, this file) ships, and no file that does ship names any of them. +That promise is a test: `testing/leak.test.sh` derives what every phase would +place and gates the set and its contents, and `testing/placement.test.sh` +gates the same rules over a placed, branded tree. + +## 2. Headless / container mode + +The blueprint's source is this repository (`sources: [{kind: dir, path: .}]`), +so the container contract is a shallow clone at a pinned tag plus two +tokens: + +```bash +export ORUN_TOKEN=… # orun auth, headless +export GITHUB_TOKEN=… # fine-grained PAT (below) + +git clone --depth 1 --branch https://github.com/sourceplane/cms-wordpress +cd cms-wordpress +orun new --blueprint repo-blueprint.yaml \ + --out /work/acme-notes --run-hooks --resume --progress json \ + --values /work/acme-notes.values.yaml +``` + +| requirement | detail | +|---|---| +| `GITHUB_TOKEN` | fine-grained PAT: **read** on this repository; on the site's repository **contents write**, **pull-requests write**, **actions read+write** (`orun.run/watch@v1` resumes runs with `gh run rerun`), **checks read**; **repository create** on the owner if `01-product` creates it (or pre-create it — supported) | +| classic token caveat | a classic PAT or gh OAuth token also needs the `workflow` scope to push `.github/workflows/` | +| pinning | the clone's `--branch ` pins everything: the blueprint, its modules and its hooks' scripts all come from that one commit | + +## 3. After the site is live: connect WordPress + +The bootstrap ends with an UNCONNECTED site: live, smoke-tested, showing its +sample posts. Connecting it is the owner's, because no platform connection +knows their WordPress. The site's README, "Connecting WordPress", has the +steps; in short, per environment: + +```bash +orun secrets set WORDPRESS_URL --env stage # prompts: https:// +# then redeploy apps/web: Orunbase's Deploy button on `web`, or +# `gh workflow run ci.yml --ref main -f environment=stage -f component=web` +pnpm --filter @app/web exec wrangler secret put WORDPRESS_WEBHOOK_SECRET --name -web-stage # the revalidation webhook only +``` + +The URL is an optional reference in `apps/web/component.yaml` +(`optionalSecretEnv`): until it exists, the build skips it; once it does, +the next build reads it. The site reads only published content, so +WordPress needs no credential. + +- **Build on it**: the app is `apps/web`; the REST client and its types are + `apps/web/lib/wordpress.ts` and `wordpress.d.ts`. Published content needs + no deploy: every page reads WordPress on request. +- **Custom domain**: attach it to the Worker in Cloudflare, set the + environment's `SITE_URL` in `intent.yaml` and replace the placeholder + `.example.com` in `BASE_DOMAIN` with it (the site's README, + "Custom domain"). There is no domain phase: attaching a domain needs zone + permissions the brokered `workers-deploy` token does not carry. +- **Refresh the record**: re-run `--phase 02-docs`; it is idempotent, and + records whether each environment reads a WordPress yet. + +## 4. Testing this baseline + +`.github/workflows/baseline.yml` runs three tiers on every pull request, and +each runs locally the same way: + +```bash +for t in manifest phases coverage rebrand retouch bootstrap-defer; do bash testing/$t.test.sh; done +bash testing/leak.test.sh # needs orun +bash testing/placement.test.sh # needs orun ≥ the floor (and so ≥ ci.yml's pin), node, pnpm: the offline bootstrap +bash testing/e2e.test.sh # + network for pnpm: each landing type-checked, linted, tested and built; the site dry-deployed and served, no WordPress +``` + +The offline bootstrap (`testing/lib/bootstrap.sh`) places both phases in +order and finishes each with the blueprint's OWN `run:` hooks — read out of +`repo-blueprint.yaml`, not transcribed — so the retouch marker, the rebrand, +the re-tenant, the work-tree strip, the deferrals and their restore and the +deployment record all run exactly as a real bootstrap runs them. Only the +platform's typed actions (task, repo, link, reconcile, land, watch, probe) +are stood in for, a landing becoming a commit on top of orun's `Initial +commit`. + +The bootstrap's landings check their commit in the box (`orun validate` and +`orun plan`) and the site's pull requests build and dry-deploy it; neither +lints or runs the tests. The e2e tier is where those run, on each landing, +before a tag is cut. + +## 5. Cutting a baseline tag (maintainers) + +Every site built from this repository resolves a `baseline-vN` tag, so the +tag is cut by a workflow rather than by hand: + +```bash +gh workflow run tag.yml -f version=baseline-v1 # from main +gh workflow run tag.yml -f version=baseline-v1 -f ref= +``` + +It refuses a version that is not `baseline-v` and a tag that already +exists: a baseline tag is never moved. Then add (or move) the registry row in +orun-cloud's `infra/baselines-registry/baselines.yaml` by pull request — +after the tag exists, because the registry's sync fetches `blueprint.yaml` +at the tag and refuses the whole catalogue if it 404s. + +## Troubleshooting + +| Symptom | Cause → fix | +|---|---| +| `01-product` parks: `waiting for github for ` | the workspace's GitHub connection is to another account. Connect the App installation on `` (console → Integrations → GitHub), then `--resume` | +| `01-product` waits on the `providers` probe for cloudflare, then stops | Cloudflare is not connected. Connect it (console → Integrations), then re-run the phase — the probe is a wait, not a failure | +| `01-product` stops at `link` | the repository is not linked to the workspace and the credential cannot link it. Allow-list it (console → Settings → Git repos) and re-run the phase | +| Secret WRITE fails `not_found` while listings work | the API key's role is below admin; re-mint it with the admin role | +| Deploy lane: Authentication error (10000) | the connection's token lacks Workers Scripts Write; re-issue it, re-connect, re-run `01-product` | +| Deploy lane's build: `Symlink … points out of the filesystem root` | the composition links one lane-wide install into the job's tree (stack-tectonic ≥ 0.20.0), which Turbopack refuses. The site pins 0.19.0 for this; keep the pin | +| The live site says "Showing sample content" | expected until a WordPress is connected (§3). Not a failure | +| Connected, but `/posts` says "0 posts found" | the WordPress URL does not answer its REST API (`/wp-json/wp/v2/posts`), or it has no published posts; the site renders empty lists rather than fail. Check `orun secrets list --env ` and the URL; fix the secret and redeploy | +| Connected, but a post's page is a 404 | the slug is not a published post in that WordPress (drafts and private posts are not in the REST API's public answer), or WordPress did not answer; the client logs `WordPress fetch failed for …` in the Worker's logs | +| `land` stops: `the landing's own check failed — orun plan for …` | the site's tree does not plan — the line after it is orun's own error (an unknown component type, a composition that does not resolve). Nothing was pushed. Fix the tree (or the baseline) and re-run the phase | +| `land` waits on CI after all | the site's repository requires a status check on `main` (branch protection or a ruleset), so GitHub refused the early merge; the landing waits for the check as a `checks: ci` landing would, then merges | +| Convergence failed AFTER the PR merged; re-running lands nothing | expected on its own — the files are on main. Re-run the phase (`--phase 01-product`, `--redo 01-product`, or the console's Retry): its `retouch` hook gives the landing a diff and the site redeploys | +| The site's `intent.yaml` says `workspace: ws_SET_ME` | `orunWorkspace` was empty and the build ran outside a workspace; set it and re-run `01-product` | +| A bootstrap stopped before `02-docs`; prod no longer waits on stage | the gate is deferred, not dropped: run `02-docs`, or `node tooling/bootstrap/promotion.mjs --restore --file /intent.yaml` | +| `✕ input "productname" is required` | all three required inputs (`reponame`, `productname`, `githuborg`) must be set on every invocation, single-phase ones included | +| `unknown flag: --phase`, `has no parameter "checks"`, `has no parameter "secrets"` or another parse error in the blueprint | the CLI is below the v2.88.0 floor | +| the convergence reported green, then `verify` got 404 from both URLs | a second workflow ran on the push to main and the watch took its run. Only `ci.yml` runs on a push to main (`testing/coverage.test.sh` holds it); read the CI run on main for the real result | +| the convergence planned no lanes at all | the merge's push had no `before` to diff against (a first push straight onto an unborn `main`). The landing merges a pull request into orun's `Initial commit`, so its push has one; re-run the phase and its retouch marker re-plans the site | diff --git a/README.md b/README.md index a16b70d..cb32650 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,10 @@ WordPress site's REST API through one typed client, with search, filters and pagination, a sitemap, Open Graph images, shadcn/ui and light and dark themes, and a revalidation webhook for WordPress's next-revalidate plugin — running on **Cloudflare Workers + Static Assets** through -[`@opennextjs/cloudflare`](https://opennext.js.org/cloudflare), deployed by -[Orun](https://github.com/sourceplane/orun) to stage and prod on every merge. -Packaging it as an Orun baseline is the next milestone (WP2). +[`@opennextjs/cloudflare`](https://opennext.js.org/cloudflare), and +packaged as an **Orun baseline**: one command takes a new site from nothing +to live on stage and prod, in its own repository, under its own name — in +ONE landing. The template's code is the code and WordPress stays the owner's own site. What the port adds is the Workers build, the monorepo wrapper, a test @@ -18,10 +19,54 @@ read-only cache, the Open Graph image runs on the Node.js runtime instead of the edge, images are served unoptimised, and Vercel Analytics becomes the Cloudflare Web Analytics beacon — and what makes it deployable before its owner has connected a WordPress: an unconnected build renders bundled sample -posts under a visible notice instead of empty lists. See +posts under a visible notice instead of empty lists. What the baseline adds +is everything needed to make a copy of it somebody else's — built the way +[cirrus-baseline](https://github.com/sourceplane/cirrus-baseline) is. See [`specs/epics/cms-wordpress`](specs/epics/cms-wordpress/README.md) for the design, the milestones and the as-built status. +## Instantiating a site + +```bash +git clone --depth 1 --branch https://github.com/sourceplane/cms-wordpress +cd cms-wordpress +orun new --blueprint repo-blueprint.yaml --out ~/sites/acme-notes --run-hooks --resume \ + --set reponame=acme-notes --set productname="Acme Notes" \ + --set githuborg=acme-inc --set subdomain= +``` + +Or, once the platform's registry lists it, from the Orun console (Baselines → +`cms-wordpress` → Build). Two phases — `01-product` (the repository, its CI +and the whole site in one pull request, deployed to stage and prod by one +convergence, smoke-tested) and `02-docs` (the live deployment recorded) — +each landing one pull request in the new repository. +**[BOOTSTRAP.md](BOOTSTRAP.md)** is the operator guide; +[docs/phases/](docs/phases/README.md) has a page per phase. + +The new repository receives the **site only** — the app, its tests, its CI, +its tooling, a README of its own and its operating contract — renamed +throughout to the site's name, repository and Cloudflare Worker. None of +this repository's machinery ships, and nothing that ships names it. + +The only provider the bootstrap asks for is Cloudflare. **WordPress is not a +provider the platform brokers**, so the site is built without it and its +owner connects one afterwards: one optional Orun secret (`WORDPRESS_URL`) +and a redeploy, and — for the revalidation webhook only — a Worker secret +`WORDPRESS_WEBHOOK_SECRET`. The site's README, "Connecting WordPress" +(`.baseline/product/README.md` here), has the steps. + +| What makes it a baseline | Where | +|---|---| +| The console card (inputs, secrets, programme) | `blueprint.yaml` | +| The build document (modules, phases, hooks) | `repo-blueprint.yaml` | +| This tree's identity, and the bootstrap's task contracts | `.baseline/` | +| The rename engine | `tooling/rebrand/rebrand.mjs` | +| The bootstrap's helpers (deferrals, redeploy marker, work-tree strip) | `tooling/bootstrap/` | +| The deployment-record renderer | `hooks/render-deployment-docs.sh` | +| The site's README and context pack | `.baseline/product/README.md`, `ai/context/` | +| The baseline's tests: contract, leak, offline bootstrap, end to end | `testing/`, `.github/workflows/baseline.yml` | +| Cutting a `baseline-vN` tag | `.github/workflows/tag.yml` | + ## What is here (the site) | Surface | Where | @@ -85,3 +130,5 @@ pnpm --filter @app/web dev # http://localhost:3000 | Workflow | What it runs | Ships to a site | |---|---|---| | `ci.yml` | the Orun pipeline, and the only workflow a site carries: `orun plan --changed`, then one job per lane. A pull request runs the verify lanes (the site built and dry-deployed per environment; they do not lint or run the tests), except the bootstrap's own landings (`orun/BASE-*`), where `plan` alone is the check; a merge deploys stage → prod. It plans nothing while `intent.yaml` names the placeholder workspace `ws_CHANGE_ME`, as this repository does. A manual run (Orunbase's Deploy button, or Run workflow on `main`) plans the environment and components it names under the push-to-main trigger, so they deploy as a merge deploys them | yes | +| `baseline.yml` | the baseline's own tiers: contract tests and the component docs' drift check, the blueprint read by the pinned orun, the leak gate, the offline bootstrap, each landing installed, its fixture rendered, type-checked, linted, tested and built, then the site built in a staged job tree, dry-deployed and served with no WordPress behind it | no | +| `tag.yml` | cuts a `baseline-vN` tag (manual) | no | diff --git a/ai/context/current.md b/ai/context/current.md new file mode 100644 index 0000000..ccb8ee1 --- /dev/null +++ b/ai/context/current.md @@ -0,0 +1,45 @@ +# cms-wordpress — where this repository stands + +The entry page for anyone (or any agent) picking this repository up. It is +this repository's own state and does not ship to a site built from it; the +two pages that do are [operations.md](operations.md) and +[deployment.md](deployment.md). + +## What it is + +Vercel's Next.js Starter for WordPress Headless CMS (9d8dev/next-wp) — a +Next.js front end that reads a WordPress site's REST API: posts, pages, +categories, tags and authors, with search, filters, pagination, a sitemap, +Open Graph images and a revalidation webhook — built by OpenNext into one +Cloudflare Worker with Static Assets, packaged as an Orun baseline: +`orun new --blueprint repo-blueprint.yaml` builds a new site in its own +repository and takes it to live on stage and prod in one landing +(`01-product`), then records what went live (`02-docs`). It deploys before +its owner has connected a WordPress: unconnected, the site serves bundled +sample content under a "no WordPress site is connected" notice. There is no +infra component; WordPress stays the owner's. + +## Release + +| | | +|---|---| +| Latest tag | `baseline-v1` — WP0 to WP2: the repository, the site on Workers with its sample mode, and the baseline (blueprint, phases, tests) | +| Proven live | Not yet: proven offline in Baseline CI only, unconnected (risk WP-A); no build has read a live WordPress yet (risk WP-C) | + +## Where to read + +| Question | Page | +|---|---| +| What shipped, and every departure from upstream | `specs/epics/cms-wordpress/IMPLEMENTATION-STATUS.md` | +| Why it is built this way | [decisions.md](decisions.md), then `specs/epics/cms-wordpress/design.md` | +| What could still go wrong | [open-risks.md](open-risks.md), then `specs/epics/cms-wordpress/risks-and-open-questions.md` | +| How to instantiate it | `BOOTSTRAP.md`, `docs/phases/` | +| What the components are | `apps/web/docs/`, `tests/web/docs/` (generated; `python3 tooling/catalog/gen-component-docs.py`) | + +## Next + +1. Bootstrap one site from `baseline-v1` from the console and record its + timings against the 12-minute estimate (closes WP-A); then the registry + row goes public with the measured minutes. +2. Connect a WordPress to it, see the samples give way, and post through + the next-revalidate plugin once (closes WP-C). diff --git a/ai/context/decisions.md b/ai/context/decisions.md new file mode 100644 index 0000000..5a77f52 --- /dev/null +++ b/ai/context/decisions.md @@ -0,0 +1,26 @@ +# cms-wordpress — decisions + +The choices that shape this repository, one line each, with where the full +reasoning lives. Superseded decisions stay listed, marked, so the history +reads in order. + +| # | Decision | Why | Source | +|---|---|---|---| +| 1 | Next.js on Workers + Static Assets through `@opennextjs/cloudflare`, with the static-assets incremental cache | The OpenNext path every Next.js baseline here shares; the cache serves the pre-rendered home page and 404 with no binding | `specs/epics/cms-wordpress/design.md` | +| 2 | Next 16.3.8, the template's 16.3 line | OpenNext 1.20.13 builds it; 16.4 is avoided | IMPLEMENTATION-STATUS (departures) | +| 3 | Every page that reads WordPress is `force-dynamic`, its fetches `no-store`; no ISR, no tag cache | The static-assets cache is read-only; the R2 cache plus a tag cache is provisioning for pages that render in milliseconds | design, "The alternative rejected"; risk WP-D | +| 4 | `/api/revalidate` is kept, secret-checked, with nothing to clear | The plugin keeps calling it, and an ISR upgrade would need it as is | risk WP-E | +| 5 | Unconnected, the client answers from `lib/sample.ts` in the REST API's shapes, under a notice | A bootstrap knows no WordPress; the site must deploy, pass its smoke and show what it is | design, "Unconnected: the sample site" | +| 6 | `WORDPRESS_URL` is an optional Orun secret per environment, inlined at build | The client reads it at module load; a key nobody stored is skipped, never a failed lane | `apps/web/component.yaml` | +| 7 | The webhook secret is a Worker secret set by hand; nothing for WordPress is brokered | Read at request time; no platform connection knows the owner's WordPress | operations.md | +| 8 | `/api/og` on the Node.js runtime | OpenNext runs no edge functions | risk WP-G | +| 9 | Images unoptimised (`images.unoptimized`) | The Worker has no image optimiser | risk WP-F | +| 10 | The site's name is one seam, `SITE_NAME` in `apps/web/site.config.ts`, which the root title reads too | The rename rewrites one literal | IMPLEMENTATION-STATUS (departures) | +| 11 | `site_domain` is `NEXT_PUBLIC_SITE_URL`, set per environment by the deploy (its `SITE_URL`, else its workers.dev URL) | The sitemap, canonical and Open Graph links are absolute | `apps/web/component.yaml` | +| 12 | The Railway template and the plugin's source are not carried | WordPress runs wherever its owner runs it; the plugin is upstream's download | IMPLEMENTATION-STATUS (departures) | +| 13 | No custom-domain phase: a domain is the owner's step, and `SITE_URL` points the build at it | The brokered `workers-deploy` token has no zone scope | README, "Custom domain" | +| 14 | One landing (`01-product`) then the record (`02-docs`), each checked in the build box | A landing has a fixed cost; the convergence on main builds, deploys and smoke-tests the site for real | `docs/phases/README.md` | +| 15 | `ci.yml` plans nothing while `intent.yaml` names `ws_CHANGE_ME`; no Checks workflow | A bootstrap cannot set a repository variable; a push to main must start `ci.yml` alone | `.github/workflows/ci.yml` | +| 16 | stack-tectonic 0.19.0, not 0.20.0 | 0.20.0's lane-shared install links `node_modules` out of the job's tree | risk WP-I | +| 17 | Component docs are generated from the manifests and checked in CI | A hand-written copy drifts silently | `tooling/catalog/gen-component-docs.py` | +| 18 | `subdomain` is read from the Cloudflare connection, never asked; the console asks for no domain | Both belong to the account or the owner, not to the build | `blueprint.yaml` | diff --git a/ai/context/deployment.md b/ai/context/deployment.md new file mode 100644 index 0000000..b221135 --- /dev/null +++ b/ai/context/deployment.md @@ -0,0 +1,7 @@ +# cms-wordpress — live deployment manifest + +> Not rendered yet. The bootstrap's `02-docs` phase probes every live URL and +> regenerates this file from what answered — the workspace, the URLs and +> their status, whether each site reads a WordPress yet, and the +> secrets the site uses, by name. Until then, nothing here claims the site +> is live. The operating contract is [operations.md](operations.md). diff --git a/ai/context/open-risks.md b/ai/context/open-risks.md new file mode 100644 index 0000000..dd3f1cf --- /dev/null +++ b/ai/context/open-risks.md @@ -0,0 +1,17 @@ +# cms-wordpress — open risks + +What is not yet proven or not yet decided. The full write-up of every risk, +including the accepted and resolved ones, is +`specs/epics/cms-wordpress/risks-and-open-questions.md`; this page lists +only what is still live, so it should be short. + +| ID | Risk | State | What closes it | +|---|---|---|---| +| WP-A | `baseline-v1` is not yet proven live; it is proven offline in Baseline CI (the offline bootstrap, the stage lane's own steps, the site served and smoke-tested, unconnected) | OPEN | One console bootstrap from `baseline-v1` | +| WP-B | The Worker is about 2.8 MiB gzipped (most of it next/og's WebAssembly), against Workers Free's 3 MiB | WATCH | Holds while dependencies stay as they are; every pull request's dry run prints the size | +| WP-C | No build has read a live WordPress; the client is tested against a stubbed REST API | OPEN | Connect a WordPress to a bootstrapped site | + +Accepted, and worth knowing before you change them: WP-D (every page reads +WordPress on every request), WP-E (the webhook clears nothing), WP-F +(images are not optimised), WP-G (`/api/og` on the Node.js runtime), WP-H +(a wrong URL is not caught at build), WP-I (stack-tectonic 0.19.0). diff --git a/ai/context/operations.md b/ai/context/operations.md new file mode 100644 index 0000000..2f456f1 --- /dev/null +++ b/ai/context/operations.md @@ -0,0 +1,166 @@ +# cms-wordpress — operating contract (for humans and agents) + +This is the standing guide to how this site is deployed and operated. +Instance facts (live URLs, workspace, the secrets it uses) live in +[deployment.md](deployment.md), rendered from probed reality by the +bootstrap's `02-docs` phase; this file is the contract that stays true +between deployments. It is written to give an agent with repository read +access enough context to reason about and operate the site without any +other source. + +## What this system is + +A Next.js front end for a WordPress site used as a headless CMS, served from +Cloudflare, expressed as an Orun component-native desired-state repo. + +- **`apps/web`** — Next.js built by `@opennextjs/cloudflare` into one Worker + plus Static Assets. Every page that shows WordPress content — `/posts` + (search, filters, pagination), `/posts/`, `/pages`, `/pages/`, + the category, tag and author lists, `/sitemap.xml` — renders per request + and reads the WordPress REST API afresh (`no-store`); the home page and the + 404 are pre-rendered static assets. `/api/og` renders Open Graph images; + `/api/revalidate` is the webhook WordPress's next-revalidate plugin calls. +- **`tests/web`** — vitest over the WordPress client (a stubbed REST API and + the sample site), the revalidation webhook, metadata, utilities and the + site's name. No lane lints or runs the tests: a pull request builds and + dry-deploys the site, so run `pnpm typecheck && pnpm lint && pnpm test` + before you push. +- **`tooling/*`** — shared TypeScript and ESLint configuration, and the + wrangler renderer for a deployable that comes to take wiring. + +There is no infrastructure component: WordPress is the owner's site, read +over HTTPS, not something this repository provisions. + +Environments: **`stage`** and **`prod`** are deployed; **`dev` is +verify-only by design** — lanes build and dry-deploy, nothing deploys. + +## WordPress: connected, or sample content + +The site reads ONE WordPress, fixed at build time (`next build` inlines +`WORDPRESS_URL`). Until a build has a URL it is **unconnected**: every page +renders the sample posts, page, categories, tags and author bundled in +`apps/web/lib/sample.ts`, answered in the REST API's own shapes, under a "no +WordPress site is connected" notice. Nothing fails: an unconnected site +deploys, passes its smoke test and serves. + +To connect it, per deployed environment: + +```bash +# 1. the WordPress URL (the next build reads it) +orun secrets set WORDPRESS_URL --env stage # prompts for the value: https:// +# …and the same with --env prod + +# 2. redeploy apps/web: the URL is read when it BUILDS, and setting a secret +# builds nothing. Orunbase's Deploy button on `web`, or +gh workflow run ci.yml --ref main -f environment=stage -f component=web + +# 3. the revalidation webhook (optional): one shared secret, in the +# next-revalidate plugin's settings and as a Worker secret (Cloudflare's, +# not Orun's — the deploy never touches it, so it survives deploys) +pnpm --filter @app/web exec wrangler secret put WORDPRESS_WEBHOOK_SECRET --name cms-wordpress-web-stage +``` + +The URL is read best-effort (`optionalSecretEnv` in +`apps/web/component.yaml`): a key nobody has stored is skipped, never a +failed lane. A wrong URL is not caught at build: the lists then render empty +("0 posts found") and a post's page 404s, so probe `/posts` after +connecting. Once connected, `/admin` redirects to the WordPress's +`wp-admin`. + +## Identity and tenancy + +Every remote operation runs against ONE Orun workspace, declared in +`intent.yaml` under `execution.state.workspace` — committed, enforced, and +what CI uses. Do not remove it; headless credentials depend on it. If it +reads `ws_SET_ME`, the bootstrap had no workspace to write: set the real one +before anything else. + +## How deployment works + +1. Merge (or push) to `main`. +2. CI (`.github/workflows/ci.yml`) runs `orun plan --changed` — only + components whose files changed are planned — then runs each planned lane + with `orun run --remote-state`, authenticated by GitHub OIDC (the + exchange resolves this repository's linked workspace server-side). +3. `apps/web` checks its committed `wrangler.jsonc` is there, builds once per + environment with that environment's WordPress URL (if any) and origin + (`NEXT_PUBLIC_SITE_URL`: the environment's `SITE_URL`, else its + workers.dev URL), `wrangler deploy` ships `cms-wordpress-web-`, and a + smoke test fetches `/posts` and requires its count ("N posts found"), + then requires `/api/revalidate` to refuse a webhook without the secret + (401) — proof the Worker's server code answers. +4. `prod` deploys after `stage` has converged on the same commit + (`environments.prod.promotion` in intent.yaml). +5. **The convergence run is the deployment.** A green run means every + planned lane passed. Failed lanes are retried with + `gh run rerun --failed`, which resumes the same execution. + +On a pull request nothing deploys: the site builds and dry-deploys. + +Caveats that matter: + +- A push that touches no component files plans zero lanes — that run is + green and deployed nothing. Never treat "latest run green" as "site + converged"; probe the URLs instead. +- Published content needs no deploy: the site reads WordPress on every + request, so a published post shows on the next visit. Nothing is cached in + the Worker, so `/api/revalidate` has nothing to clear; it is kept for the + plugin and answers 200 once its secret matches. +- A change to `intent.yaml`'s `environments`, or to an Orun secret, maps to + no component and redeploys nothing on its own. Land it with a change under + `apps/web`. + +## Secrets model + +- **Brokered provider secrets**: `CLOUDFLARE_API_TOKEN` (the + `workers-deploy` scope) and `CLOUDFLARE_ACCOUNT_ID` — pointers minted per + run from the workspace's Cloudflare connection. No long-lived values at + rest; nothing to rotate by hand. +- **The WordPress URL**: `WORDPRESS_URL` on `stage` and `prod`, stored by + the owner, read by the build. Not a credential (the site reads published + content only), kept as a secret so each environment can name its own. +- **The webhook secret**: `WORDPRESS_WEBHOOK_SECRET`, a Worker secret per + environment, read at request time by `/api/revalidate` only. +- Inspect by NAME only: `orun secrets list --org --env stage|prod`. No + tooling in this repository prints a secret value, and no document in + `ai/context/` may contain one. + +## Verifying the system + +```bash +# the site on each environment (also recorded, probed, in deployment.md); +# an unconnected site carries data-wordpress="unconnected" +curl -s https://cms-wordpress-web-stage.your-workers-subdomain.workers.dev/posts | grep -Eo 'data-wordpress="[a-z]*"|[0-9]+()? ()?posts?()? found' +curl -s -o /dev/null -w '%{http_code}\n' -X POST -d '{}' https://cms-wordpress-web-prod.your-workers-subdomain.workers.dev/api/revalidate # 401 + +# workspace readiness +orun secrets list --org --env stage && orun secrets list --org --env prod +orun integrations list --org --json && orun cloud check --org +``` + +## Common operations + +| task | how | +|---|---| +| connect a WordPress | "WordPress: connected, or sample content" above | +| write, edit, publish | in WordPress (`/admin` redirects there once connected); no deploy needed | +| change the site's code | edit `apps/web` (its name: `SITE_NAME` in `apps/web/site.config.ts`; its menus: `apps/web/menu.config.ts`), merge | +| read more of WordPress (a custom post type, a field) | a function in `apps/web/lib/wordpress.ts` and its type in `wordpress.d.ts`, and an answer for it in `apps/web/lib/sample.ts` so an unconnected build still renders | +| deploy a change | merge to `main`; watch the run; failed lanes → `gh run rerun --failed` | +| deploy by hand | Orunbase's Deploy button, or `gh workflow run ci.yml --ref main -f environment= [-f component=]` — the named components (blank: every one) run in that environment as a merge runs them; started off `main` it is refused | +| redeploy without a change | edit the last line of `apps/web/component.yaml` (`# orun: redeploy `) and merge — it is a deploy trigger, nothing reads it | +| serve a custom domain | attach it to the Worker in Cloudflare and set `SITE_URL` for the environment in `intent.yaml` — the next deploy builds the site's links for it (README, "Custom domain") — then replace the placeholder `cms-wordpress.example.com` in `intent.yaml`'s `BASE_DOMAIN` with it | +| headless credentials | `ORUN_TOKEN` (workspace-scoped) + `GITHUB_TOKEN` | + +The deployment record is the bootstrap's `02-docs` phase. Re-running it (the +Orun console's Retry on that phase, or `orun new … --phase 02-docs`) +re-probes the URLs and re-renders [deployment.md](deployment.md); it is +idempotent. + +## Evolution + +Structural changes follow the same contract that deployed the site: add a +component under `apps/`, `infra/` or `packages/` with a `component.yaml`, +land it as a pull request, and the convergence run deploys it. A component +under `infra/` whose wiring the Worker reads is declared in `apps/web`'s +`dependsOn` (enforced on `main`), so it is applied first. diff --git a/blueprint.yaml b/blueprint.yaml new file mode 100644 index 0000000..a710f7c --- /dev/null +++ b/blueprint.yaml @@ -0,0 +1,157 @@ +# The cms-wordpress card: what the console's Blueprints page renders and the +# platform's bootstrap door consumes. +# +# THIS FILE IS NOT THE BUILD. `spec.bootstrap.blueprint` names the build +# document — `repo-blueprint.yaml`, whose phases a runner places. This card is +# what an operator reads and fills in before pressing Build, and +# `testing/manifest.test.sh` compares every list below to the document that +# actually does the thing, not to a copy of itself. +# +# The division of labour with the registry is strict: the registry (orun-cloud +# `infra/baselines-registry/baselines.yaml`) owns identity and commerce — id, +# visibility, tier, the pinned tag. This file owns the build contract. Neither +# restates the other, which is why there is no `tag` here: this file is +# fetched AT the tag the registry pins. +apiVersion: orun.io/v1 +kind: Blueprint +metadata: + name: cms-wordpress + displayName: WordPress Headless CMS — a Next.js front end for WordPress on Cloudflare Workers + description: > + Vercel's Next.js Starter for WordPress Headless CMS as a product of its + own: posts, pages, categories, tags and authors read from a WordPress + site's REST API, with search, filters, pagination, a sitemap, Open Graph + images and a revalidation webhook for the next-revalidate plugin — built + by OpenNext into one Cloudflare Worker with Static Assets, with CI that + deploys it to stage and prod on merge, smoke-tested. It goes live before + any WordPress is connected, on bundled sample posts, and reads yours once + you give it its URL. One provider, one consent, one landing. + tags: [cms, wordpress, headless, nextjs, cloudflare] +spec: + source: + repo: sourceplane/cms-wordpress + # No `tag`. The registry pins it; this file is fetched at it. + + # ── What the operator reads first ──────────────────────────────────────── + overview: + lede: > + A headless WordPress front end on Cloudflare alone. It deploys with + sample posts and a "no WordPress site is connected" notice; give it + your WordPress URL and it renders your posts, pages and terms. + architecture: + - layer: Edge + items: [web] + - layer: Content + items: [WordPress (your site's REST API, connected after the build)] + - layer: Delivery + items: [GitHub Actions, OpenNext, wrangler] + outcome: + - Live on stage and prod, in one landing + - Sample posts until a WordPress site is connected — never a 500 + - Every merge redeploys, smoke-tested + - Its own CI from the first commit + + requires: + # Cloudflare is the only provider connection a bootstrap needs. GitHub + # arrives as the App installation plus the repo link, not as a + # connection row. WordPress is NOT a provider the platform brokers: the + # site is built without it, and its owner connects one afterwards (the + # product's README, "Connecting WordPress"). + integrations: [github, cloudflare] + apiKeyRole: admin # secret writes need the admin floor + + # Every input is collected by the console: keys are lowercase (the + # platform's reader refuses anything else), every one carries the `pattern` + # its value is checked against before Continue, and a value the console + # already holds says so with `from`. repo-blueprint.yaml declares the same + # names; `repoPrivate`, `orunWorkspace` and `epicSlug` are build inputs with + # defaults (or filled from the build's workspace) and are not asked. + # + # NOR IS THE DOMAIN. The site goes live on workers.dev, and a domain is an + # owner's step after the bootstrap: `productdomain` defaults to empty, the + # rebrand writes the reserved placeholder `.example.com` where + # the domain goes, and the site's README ("Custom domain") says how to set + # it. Nothing that needs a domain is removed — it waits for one. + inputs: + - key: reponame + label: Repo name + pattern: "^[a-z][a-z0-9-]{1,38}$" + # The operator picked the repository; its name IS this value. + from: repo.name + - key: productname + label: Site name + pattern: "^[A-Za-z0-9][A-Za-z0-9 .,'&-]{1,48}$" + help: The name visitors see — in the nav, the footer and the page titles. + example: Acme Notes + - key: githuborg + label: GitHub organisation + pattern: "^[A-Za-z0-9][A-Za-z0-9-]*$" + help: The GitHub org or user the site's repository is created under. + # DERIVED FROM THE CHOSEN REPOSITORY: its owner IS this value. Declared + # because repo-blueprint.yaml requires it — a build may declare more + # inputs than this card, but not require one nobody supplies. + from: repo.owner + - key: subdomain + label: workers.dev subdomain + pattern: "^[a-z0-9][a-z0-9-]{0,62}$" + help: The workers.dev subdomain of the Cloudflare account the site deploys into. + example: acme + # READ FROM THE CLOUDFLARE CONNECTION, not asked. The subdomain belongs + # to the account the same way its id does, and there is exactly one + # right answer — a typed one could only be wrong, and wrong showed up + # after deploy, in the deploy's smoke, 01-product's probes and the + # verify URL below. The integration reads it from Cloudflare at connect + # and on its hourly health check; the bootstrap door fills this input + # from the connection the build is BOUND to, the same one + # CLOUDFLARE_ACCOUNT_ID and the deploy token mint from, so all three + # name one account. The console renders no field for it, and an account + # with no workers.dev subdomain refuses the build at the door, naming + # the fix, before anything is created. + from: connection.cloudflare.workersSubdomain + + # ── PREVIEW ONLY. repo-blueprint.yaml's one `orun.integrations/reconcile@v1` + # hook (`secrets`) mints these, brokered, during 01-product. ────────────── + # Transcribed from that hook's own `secrets:` list (each key and its + # template), so testing/manifest.test.sh compares this list to the document + # that mints them. The console renders them read-only: no credential is ever typed, + # shown or stored. Keys that already exist are kept. The WordPress URL and + # the webhook secret are not here: no platform connection can mint them, + # the site is built and deployed without them, and its owner adds them + # afterwards. + secrets: + - key: CLOUDFLARE_API_TOKEN + provider: cloudflare + template: workers-deploy + why: Deploys the site's Worker and its static assets + - key: CLOUDFLARE_ACCOUNT_ID + provider: cloudflare + template: account-id + why: Connection fact, not a secret + fact: true + + # ── PREVIEW ONLY. repo-blueprint.yaml's run-level `hooks.preInstantiate` + # opens these — the epic, every milestone in this order, every task — before + # the first phase places. Idempotent by identity, so a re-run finds what it + # made before. + programme: + epicSlug: cms-wordpress-baselining # = repo-blueprint.yaml's `epicSlug` default + epicName: "WordPress site baselining — {productname}" + milestones: + # The whole product is one landing (01-product): the repository, its + # CI, the site and its tests are one pull request and one convergence. + - name: 01-product + - name: 02-docs + + bootstrap: + # THE BUILD DOCUMENT. There is no umbrella workflow and no agent brief: + # every phase is declared in it and orun runs it. + blueprint: repo-blueprint.yaml + # Summed from the phases' expectedMinutes (01-product 11, 02-docs 1). An + # estimate until a bootstrap on this shape measures it. + expectedMinutes: 12 + tokenChannel: ORUN_TOKEN_FILE # how a runner hands over its refreshed token + # The site's URL per environment, as the console links it. + verify: + urls: + - "https://{reponame}-web-{env}.{subdomain}.workers.dev" + envs: [stage, prod] diff --git a/docs/phases/01-product.md b/docs/phases/01-product.md new file mode 100644 index 0000000..bc6118c --- /dev/null +++ b/docs/phases/01-product.md @@ -0,0 +1,115 @@ +# 01-product — the site, built in one landing + +**Places** everything a site built from this baseline is made of, as ONE +pull request: the root manifests (`intent.yaml`, `package.json`, the pnpm +workspace and lockfile, `turbo.json`), `.github/workflows` +(`ci.yml` — the baseline's own `baseline.yml` and `tag.yml` are +ignored), the shared TypeScript/ESLint config and the wrangler +renderer, the site's README and its two context pages, the identity file +`.rebrand/values.json`, `.gitkeep` files for the four discovery roots, and +`apps/web` (the Next.js app, its sample content and its deploy contract) with +`tests/web` (vitest). + +**Requires** the GitHub App installation on `githuborg` and the Cloudflare +connection — both probed, each waited for up to ten minutes. The platform +sees a pull request only through the installation on the account that owns +the repository, and every deploy credential is minted from the Cloudflare +connection. It does **not** require WordPress: the site it lands builds, +deploys and serves with no WordPress behind it. + +## What runs + +The run's task set-up — the epic, both milestones, both tasks — runs in the +background from the start (`background: true`), so every hook up to `task` +runs beside it; `task` is the first that waits for it. + +| hook | what it does | +|---|---| +| `retouch` | the redeploy marker on `apps/web/component.yaml` and `tests/web/component.yaml` (`.baseline/tasks/01-product.TaskContract.yaml`'s `affects`) | +| `git-init`, `git-stage` | the rebrand enumerates with `git ls-files`, so the tree is a staged repo first | +| `rebrand` | renames the baseline's identity to the site's (`tooling/rebrand/rebrand.mjs`): the repo slug, the Worker name, the secret project, the `SITE_NAME` seam, the domain, the subdomain — and leaves the upstream template's `next-wp` credit alone | +| `orun-workspace` | writes the site's workspace into `intent.yaml` (`ws_SET_ME` if there is none — loud, not silent) | +| `work-tree` | removes the baseline's own `work:` block from `intent.yaml` — `specs/` and `tasks/` do not ship | +| `promotion` | defers prod's wait on stage until `02-docs` (both environments deploy side by side) | +| `dev-lanes` | keeps dev's verify lanes off main's convergences until `02-docs` | +| `git-restage`, `rebrand-verify` | refuses the landing if any baseline identity is left | +| `repo` | `orun.repo/ensure@v1` — creates `githuborg/reponame` (private unless `repoPrivate=false`) | +| `link` | `orun cloud link` (best effort) then `orun cloud check` — an unlinked repo stops here | +| `secrets` | `orun.integrations/reconcile@v1`, both keys in one hook, created side by side: `CLOUDFLARE_API_TOKEN`, brokered from the Cloudflare connection with the `workers-deploy` scope; `CLOUDFLARE_ACCOUNT_ID`, the connection fact | +| `task` | finds the phase's task (opened by the run-level list) and yields its key — waiting, if it must, for the background set-up | +| `land` | one PR bound to the task, its commit checked in the box first (`checks: local`: `orun validate`, then `orun plan` as the PR and as the merge would plan it, under a second); merged without waiting for the PR's CI | +| `converge` (await) | `orun.run/watch@v1` on the merge commit's run, read every 5 s; resumes it up to three times | +| `verify` (await) | `orun.http/probe@v1` on both workers.dev URLs | + +There is no `orun.secrets/exists@v1` await: the site has no infra component, +so nothing lease-publishes a `WIRING_*` secret. Nothing is minted for +WordPress: its URL is an optional secret reference the build skips while +nobody has stored it, and the webhook secret is a Worker secret the owner +adds. + +## What the convergence does + +`orun plan --changed` plans `web` on stage and prod (the `deploy` profile) +and — dev's push activation being deferred — nothing on dev (`web-tests` +verifies on dev only). Each lane: + +1. installs the workspace (`pnpm install --frozen-lockfile`) inside the + job's own tree (stack-tectonic 0.19.0: Turbopack refuses a + `node_modules` linked from outside it); +2. `verify-app-structure` — `test -f package.json` and + `test -f wrangler.jsonc`, BEFORE any build: the config is committed, never + generated; +3. `build-app` — `next build` on Turbopack with the environment's origin + (`NEXT_PUBLIC_SITE_URL`), then the OpenNext bundle. The environment's + `WORDPRESS_URL` secret is resolved best-effort: on a fresh product it + does not exist, and the build is the unconnected site (sample posts, a + page and their terms, under a notice); +4. `verify-build-output` — the Worker entrypoint and the assets directory; +5. deploys `-web-` with `wrangler deploy` (retried on + Cloudflare's first-deploy race); +6. smoke-tests it: `/posts` must render its count ("N posts found") and + `/api/revalidate` must answer 401 to a webhook without the secret — the + Worker's own code (retried while the route propagates). + +Stage and prod deploy side by side (the promotion gate is deferred). + +`web-tests` has a lane on dev alone, so the merge plans nothing for it. The +landing's own pull request runs `plan` alone, and nothing waits for it — the +same plan ran in +the box before the push: the baseline's own CI installed, type-checked, +linted, tested and built this exact tree before the tag was cut. A site's +later pull requests build and dry-deploy it and do not lint or run the +tests; its developers run them before a push. + +## Verified + +The convergence run for the merge commit is green, and +`https://-web-{stage,prod}..workers.dev` answer. + +## Troubleshooting + +| symptom | cause → fix | +|---|---| +| parks on `waiting for github for ` | the workspace's GitHub connection is to another account. Connect the App installation on `` (console → Integrations → GitHub), then `--resume` | +| parks on the `providers` probe for cloudflare | Cloudflare is not connected to the workspace. Connect it (console → Integrations → Cloudflare, paste the Account API token) | +| `link` fails: `… is not linked to workspace` | the credential cannot write links and the platform has not linked the repo. Allow-list it (console → Settings → Git repos) and re-run the phase | +| `land`: `the landing's own check failed — orun plan for …` | the placed tree does not plan; the next line is orun's error. Nothing was pushed. Fix it and re-run the phase | +| `rebrand-verify` lists leftovers | a file carries an identity form no rule renames. Add a rule to `tooling/rebrand/rebrand.mjs` (and a case to `testing/rebrand.test.sh`) | +| `intent.yaml` says `workspace: ws_SET_ME` | `orunWorkspace` was empty and the build ran outside a workspace. Set it and re-run | +| deploy lane: `secret resolution failed … CLOUDFLARE_API_TOKEN` | the reconcile did not run or minted against a revoked connection. Re-connect and re-run the phase; the reconcile re-mints only what is missing | +| deploy lane: Authentication error (10000) | the connection's token lacks Workers Scripts Write. Re-issue it with the permission groups the console's Connect recipe lists | +| build: `Symlink … points out of the filesystem root` | the composition installs once per lane and links it in (stack-tectonic ≥ 0.20.0). The product pins 0.19.0 for this; keep the pin | +| smoke fails right after the FIRST deploy | workers.dev route propagation; the composition retries the smoke with backoff (~4.5 min). A convergence resume clears what is left | +| the site shows "Showing sample content" | expected: no WordPress is connected yet. The site's README, "Connecting WordPress" | +| the watch says green, the probe says 404 | another workflow ran on the push and the watch took its run. Only `ci.yml` may run on a push to main | +| re-run lands nothing | the hooks did not run (`--run-hooks`), or the contract names no component — `node tooling/bootstrap/retouch.mjs --check --affects .baseline/tasks/01-product.TaskContract.yaml` in the site's tree says which | + +## Re-running + +Idempotent: placement is additive, rebrand is a no-op on branded files, +`git init` and the repo step are guarded, and the reconcile keeps keys that +exist. A re-run of a phase whose PR already merged lands the retouch markers +alone, which re-plans exactly the components it names. Once the tree is +branded the phase derives as `drifted`, so `--resume` leaves it alone; re-run +it deliberately with `--phase 01-product` (or `--redo 01-product` under +`--resume`). diff --git a/docs/phases/02-docs.md b/docs/phases/02-docs.md new file mode 100644 index 0000000..d3be15d --- /dev/null +++ b/docs/phases/02-docs.md @@ -0,0 +1,39 @@ +# 02-docs — the deployment, recorded + +**Places** nothing. Its work is hooks: it records what `01-product` built, +from probed facts rather than from what the blueprint intended, and it puts +back the two things `01-product` deferred for the bootstrap's sake. + +**Requires** `01-product` placed. (A hook-only phase derives as `unknown`, so +no phase may require this one.) + +## What runs + +| hook | what it does | +|---|---| +| `promotion` | restores `environments.prod.promotion` — from now on prod deploys only after stage | +| `dev-lanes` | restores dev's activation on pushes to main | +| `render` | `hooks/render-deployment-docs.sh`: probes `/`, `/posts` and the revalidation webhook on both environments (and records whether each site reads a WordPress yet or still shows its sample posts) and regenerates `ai/context/deployment.md` — the identity, the probed URLs, the secrets the site uses by name and where each lives — and the README's live-deployment section. It asks the platform nothing: what the workspace holds right now is on the console's Secrets and Integrations pages, which the record points to | +| `task` | finds the phase's task and yields its key | +| `land` | one PR, its commit checked in the box (`checks: local`) and merged. It touches no component, so it deploys nothing — and there is nothing after it to wait for: the render's probes are the phase's check | + +## Re-running it + +Idempotent, and the way to refresh the record after a redeploy or a custom +domain: every generated section is re-rendered from scratch. + +```bash +orun new --blueprint repo-blueprint.yaml --out \ + --run-hooks --phase 02-docs --values +``` + +## If a bootstrap stops before this phase + +The promotion gate and dev's push activation stay deferred: `intent.yaml` +carries a `# @promotion-deferred:…` and a `# @dev-lanes-deferred:…` marker. +Running this phase restores both, or by hand from the baseline checkout: + +```bash +node tooling/bootstrap/promotion.mjs --restore --file /intent.yaml +node tooling/bootstrap/dev-lanes.mjs --restore --file /intent.yaml +``` diff --git a/docs/phases/README.md b/docs/phases/README.md new file mode 100644 index 0000000..fa4e408 --- /dev/null +++ b/docs/phases/README.md @@ -0,0 +1,143 @@ +# The phases — one blueprint, two selections + +`repo-blueprint.yaml` declares two phases that take a site from **nothing** +to **live on stage and prod, documented**. Run them one at a time with +`--phase `, or the whole sequence unattended with `--resume`. There is +no umbrella workflow and no per-phase document: a phase is a selection on one +artifact, which is what makes running one alone, months later, from a fresh +container the same operation as running them all. + +Each phase follows the same contract: + +> **place its modules → brand them → check them in the box and land them as +> one pull request → watch the convergence that merge triggers +> (auto-resumed) → verify the outcome over HTTP.** + +The run's task set-up — the epic, a milestone per phase, a task per landing +— runs in the background from the start; the first hook that needs it, the +phase's `task`, waits for it. + +Run from the baseline checkout (the blueprint's source is `path: .`); the +site's repository is wherever `--out` points. + +## One landing builds the product + +Since cirrus-baseline's baseline-v22 the whole product lands as ONE pull +request and ONE convergence on main deploys it. Before that a bootstrap paid +a landing's fixed cost per layer — place, open a PR, wait for its checks, +merge, wait for the convergence to start — for order the plan can carry by +itself. This baseline is built that way from the start: `01-product` places +every module, and `02-docs` records what went live. + +| what has to come first | how the plan holds it | +|---|---| +| infrastructure before anything that reads its wiring | a component reading an infra component's `WIRING_*` declares `dependsOn` on it, `mode: enforced` on `github-push-main` (advisory on pull requests). **This site has no infra** — WordPress is the owner's site it reads, not infrastructure it applies — so nothing waits: `web` deploys to stage and prod side by side | +| stage before prod | deferred for the bootstrap (`promotion.mjs --defer`), restored by `02-docs` | +| dev's verify lanes on main | deferred for the bootstrap (`dev-lanes.mjs --defer`), restored by `02-docs`; pull requests keep them throughout | + +## Execution order + +The phase number is the EXECUTION order, and each phase's `requires.phases` +states it in the document: the engine refuses a phase whose predecessor is not +placed, and names it. + +Every landing is a pull request on a branch named for its task +(`orun/BASE--`), checked before it is pushed: `orun validate`, then +`orun plan` as the pull request and as the merge would plan it, in the box, +in under a second (`checks: local`). Then it merges; nothing waits for the +PR's CI. On those branches `ci.yml` runs `plan` only — the intent, every +component and every composition resolve — and skips the lanes, because the +merge runs them on main a minute later, for real, and that convergence is +what the phase watches. The site carries no other workflow: the baseline's +own CI (Tier 2) installs, renders the fixture, type-checks, lints, tests and +builds each landing before a tag is cut. A site's later pull requests run +`ci.yml`'s verify lanes, which build and dry-deploy it and do not lint or +run the tests. + +| phase | lands | verified by | +|---|---|---| +| [`01-product`](01-product.md) | **the GitHub repo created**, then the WHOLE site in one PR: intent, CI, tooling, identity, `apps/web` + `tests/web` — one convergence deploys it to stage and prod | convergence green (build, deploy, smoke) + the site answers on both URLs | +| [`02-docs`](02-docs.md) | the live-deployment record; the promotion gate and dev lanes put back | committed manifest matches probed reality | + +There is no custom-domain phase. Attaching a domain to a Worker needs zone +permissions the platform's brokered `workers-deploy` token does not carry, so +it is an owner's step after the bootstrap — the site's README, "Custom +domain", says how. + +There is no WordPress phase either. WordPress is not a provider the +platform brokers, so no phase can create or connect one: the site is +built, deployed and verified WITHOUT one — it serves bundled sample posts +under a "no WordPress site is connected" notice — and its owner connects a +WordPress afterwards (the site's README, "Connecting WordPress": one +optional secret, a redeploy, and a Worker secret for the revalidation +webhook). + +## Inputs + +`01-product` takes the site's identity once and writes it into the repo +(`.rebrand/values.json`); `02-docs` reads it back from the placed tree. But +the blueprint's **required** inputs — `reponame`, `productname`, +`githuborg` — are validated before any phase runs, so they must be supplied +on every invocation, single-phase ones included. A `--values` file is easier +than repeating `--set`. + +- `productdomain` — NOT ASKED, default empty. The site goes live on + workers.dev; empty brands the reserved placeholder `.example.com` + into `BASE_DOMAIN`, for an owner to replace when they attach a domain (the + site's README, "Custom domain"). Pass it only for a site that already has + its domain. + +- `subdomain` — the workers.dev subdomain of the Cloudflare account you + deploy into. It is in every URL the phases probe and in the URL the + deploy's smoke reads. A console or `--from bst_…` build reads it from the + Cloudflare connection; pass it only for a hand-run build. +- `orunWorkspace` — workspace id (`ws_…`). Unset, it is the workspace the + build runs in (`from: workspace`); with none anywhere, a placeholder that + fails loudly rather than silently claiming another tenant's workspace. +- `epicSlug` (default `cms-wordpress-baselining`) — the epic every phase clubs + its task under. Found by slug, so a fresh run and a resumed run find the + same work. +- `repoPrivate` (default `true`) — the repository's visibility at creation. + +```bash +orun new --blueprint repo-blueprint.yaml \ + --out $HOME/sites/acme-notes --run-hooks --phase 01-product \ + --values ~/acme-notes.values.yaml +``` + +Drop `--run-hooks` (or add `--status`) to preview. Without it a phase places +files and stops: no repo, no landing, no convergence watch, and no probe — +which is exactly what makes a dry instantiation of this baseline possible in +CI with no workspace and no provider (`testing/placement.test.sh`, +`testing/e2e.test.sh`). + +## What 01-product does after it places + +Placement writes the baseline's files as they are here. Before the phase +lands, its `post` hooks make them the site's: + +1. `retouch` — one `# orun: redeploy 01-product ` line at the end of + each component.yaml its task contract names, so a re-run after a failed + convergence still has a diff to land and redeploys exactly those + components. +2. `git init`, `git add` — the rebrand enumerates with `git ls-files`. +3. `rebrand` → the intent's `workspace:` → `work-tree --strip` → the two + deferrals → `git add` → `rebrand --verify` — the identity rename over the + whole tree, the re-tenant, and a sweep that fails on any of this + baseline's identity left behind. +4. `repo`, `link`, the brokered credentials in one `secrets` reconcile, + `task` (the first hook that waits for the background task set-up), and + `land`, its commit checked in the box (`checks: local`). + +There is no lockfile step: the baseline's complete lockfile is placed as it +is, and the lanes install it with `--frozen-lockfile`. + +## When a phase fails + +- **Before it lands** (a probe that timed out, a rebrand residue, a refused + link): nothing was merged. Fix what the message names and re-run the phase. +- **After it lands** (the convergence went red): the files are on main. + `orun.run/watch@v1` has already resumed the run up to three times. Re-run + the phase (`--phase 01-product`, `--redo 01-product` under `--resume`, or + the console's Retry): its `retouch` hook gives the landing a diff and the + site redeploys. diff --git a/hooks/render-deployment-docs.sh b/hooks/render-deployment-docs.sh new file mode 100755 index 0000000..740d78d --- /dev/null +++ b/hooks/render-deployment-docs.sh @@ -0,0 +1,159 @@ +#!/usr/bin/env bash +# Render the site's LIVE-DEPLOYMENT documentation from verified state. +# Called by phase 02-docs as a `run:` hook (and safe to run by hand, from the +# site's checkout). Idempotent: the generated file and the README section are +# fully re-rendered on every run, so re-running after a redeploy or a custom +# domain refreshes them. +# +# hooks/render-deployment-docs.sh +# +# What it writes (in ): +# ai/context/deployment.md — REGENERATED: URLs with live probe results +# (and whether each site reads a WordPress +# yet or still shows its sample posts), +# identity, and the secrets the site uses BY +# NAME +# ai/context/operations.md — healed from the baseline's copy if absent +# (the static operating contract; never rewritten) +# README.md — the section between +# is replaced (appended after the title if the +# README predates the markers) +# +# No secret VALUE is ever read or written here — secrets are named, not read. +# +# IT ASKS THE PLATFORM NOTHING. The record used to carry the workspace's slug, +# its secrets listed per rung and its integrations — five CLI calls, one after +# another, from the build box — and all of it is what the console shows live +# and this file could only show as it was the day it was written. The record +# keeps what the repository is the right place for: the identity the code +# names, what answered at the URLs, and where to look for the rest. +set -euo pipefail + +out="${1:?usage: render-deployment-docs.sh }" +ws="${2:-}" +L="${3:?usage: render-deployment-docs.sh }" + +cd "$out" +vals=".rebrand/values.json" +[ -f "$vals" ] || { echo "render-docs: $vals missing — is this a bootstrapped site?" >&2; exit 1; } +val() { python3 -c "import json,sys;print(json.load(open('$vals')).get(sys.argv[1],'') or '')" "$1"; } + +repo="$(val reponame)" +brand="$(val brandSlug)"; [ -n "$brand" ] || brand="$repo" +sub="$(val subdomain)"; [ -n "$sub" ] || sub="your-workers-subdomain" +[ -n "$ws" ] || ws="$(sed -n 's/^[[:space:]]*workspace:[[:space:]]*\([^[:space:]#]*\).*/\1/p' intent.yaml | head -1)" +[ -n "$ws" ] || ws="?" + +# CI lane pin (what version the deploy lanes run). +lanepin="$(sed -n 's/^ *version: *\(v[0-9.]*\) *$/\1/p' .github/workflows/ci.yml 2>/dev/null | head -1)" +[ -n "$lanepin" ] || lanepin="?" + +# curl emits the -w format even on connection failure (000) — capture, don't +# append, or a failed probe reads "000000". +probe() { local c; c="$(curl -s -o /dev/null -w '%{http_code}' --max-time 20 "$@" 2>/dev/null)" || true; printf '%s' "${c:-000}"; } +badge() { case "$1" in 2*|3*) echo "LIVE ($1)" ;; 000) echo "unreachable" ;; *) echo "answering $1" ;; esac; } +# Whether a site reads its owner's WordPress yet: until the build has a +# WORDPRESS_URL, every page carries the "no WordPress site is connected" +# notice over the bundled sample posts. The posts page renders its count +# either way ("N posts found"), so a page without it (a workers.dev 404, an +# error page) is not the site's and says nothing either way. +content() { + local body + body="$( { curl -sf --max-time 20 "$1/posts" 2>/dev/null || true; } )" + if ! printf '%s' "$body" | grep -Eq 'posts?()? found'; then echo "not the site's page" + elif printf '%s' "$body" | grep -q 'data-wordpress="unconnected"'; then echo "showing sample posts — no WordPress site connected yet" + else echo "showing the WordPress site's posts" + fi +} + +stage_url="https://${brand}-web-stage.${sub}.workers.dev" +prod_url="https://${brand}-web-prod.${sub}.workers.dev" + +rows="" +for pair in "stage|$stage_url" "prod|$prod_url"; do + env="${pair%%|*}"; url="${pair#*|}" + rows+="| site (${env}) | ${url}/ | $(badge "$(probe "$url/")") |"$'\n' + rows+="| posts (${env}) | ${url}/posts | $(badge "$(probe "$url/posts")"), $(content "$url") |"$'\n' + rows+="| revalidate webhook (${env}) | ${url}/api/revalidate | answers $(probe -X POST -H 'content-type: application/json' -d '{}' "$url/api/revalidate") to a POST without the webhook secret (401 expected) |"$'\n' +done + +now="$(date -u +%Y-%m-%dT%H:%M:%SZ)" + +# Heal the static operating contract when the site predates it. +mkdir -p ai/context +if [ ! -f ai/context/operations.md ] && [ -f "$L/ai/context/operations.md" ]; then + cp "$L/ai/context/operations.md" ai/context/operations.md + git add ai/context/operations.md 2>/dev/null || true + node "$L/tooling/rebrand/rebrand.mjs" --values "$vals" --allow-dirty >/dev/null 2>&1 || true + echo "render-docs: healed ai/context/operations.md" +fi + +cat > ai/context/deployment.md < GENERATED by the \`02-docs\` phase on ${now}; re-run it to refresh +> (idempotent; see [operations.md](operations.md)). Hand-edits here are +> overwritten. No secret values appear in this file — secrets are named only. + +## Identity + +| | | +|---|---| +| repository / project slug | \`${repo}\` | +| Orun workspace | \`${ws}\` | +| declared in | \`intent.yaml\` → \`execution.state.workspace\` | +| Workers | \`${brand}-web-stage\`, \`${brand}-web-prod\` on \`${sub}.workers.dev\` | +| CI lane CLI pin | orun \`${lanepin}\` (\`.github/workflows/ci.yml\`) | + +## Public URLs (probed ${now}) + +| surface | URL | status | +|---|---|---| +${rows} +The \`dev\` environment is verify-only by design — no deployed URL. + +## Secrets (names only) + +| secret | where | what it is | +|---|---|---| +| \`CLOUDFLARE_API_TOKEN\` | the workspace | BROKERED from its Cloudflare connection (\`workers-deploy\`): deploys the Worker and its static assets | +| \`CLOUDFLARE_ACCOUNT_ID\` | the workspace | the connection's account id — a fact, not a credential | +| \`WORDPRESS_URL\` | \`${repo}\` on stage and on prod, once the owner stores it | the WordPress site the next build reads (its REST API at \`/wp-json/wp/v2\`); optional — unset, the site shows its sample posts | +| \`WORDPRESS_WEBHOOK_SECRET\` | each Worker, as a Cloudflare Worker secret — not Orun's | the shared secret \`/api/revalidate\` checks on the next-revalidate plugin's webhook; optional — unset, every webhook is refused | + +Brokered secrets are minted per run, so no long-lived value is at rest. What +the workspace holds right now (every secret by name, and its integrations +and their health) is on the console's Secrets and Integrations pages for +\`${ws}\`. How to connect WordPress: [operations.md](operations.md). + +## How this deployment changes + +Merges to \`main\` converge automatically: CI plans the changed components and +runs each lane with \`orun run --remote-state\` against the workspace above. +See [operations.md](operations.md) for the full operating contract. +EOF +echo "render-docs: wrote ai/context/deployment.md" + +python3 - <<'PY' +import re +begin, end = "", "" +body = f"""{begin} +This site is **live**. Verified URLs, identity and the secrets it uses are +recorded in [ai/context/deployment.md](ai/context/deployment.md) (re-rendered +by the `02-docs` phase); how it deploys and how to operate it: +[ai/context/operations.md](ai/context/operations.md). +{end}""" +s = open("README.md").read() +if begin in s and end in s: + s = re.sub(re.escape(begin) + r".*?" + re.escape(end), lambda _m: body, s, count=1, flags=re.S) +else: + lines = s.splitlines(keepends=True) + at = 1 + while at < len(lines) and lines[at].strip() == "": + at += 1 + lines.insert(at, f"\n## Live deployment\n\n{body}\n") + s = "".join(lines) +open("README.md", "w").write(s) +print("render-docs: README live-deployment section rendered") +PY +echo "render-docs: done" diff --git a/repo-blueprint.yaml b/repo-blueprint.yaml new file mode 100644 index 0000000..ce5c305 --- /dev/null +++ b/repo-blueprint.yaml @@ -0,0 +1,666 @@ +apiVersion: orun.dev/v1 +kind: Blueprint +metadata: + name: cms-wordpress + description: >- + The cms-wordpress baseline as a Blueprint of itself — instantiate a new + repository holding a headless-WordPress Next.js site on Cloudflare Workers + + Static Assets (posts, pages, categories, tags and authors read from a + WordPress REST API, with its tests and CI) and take it from nothing to + live on stage and prod in ONE landing — serving bundled sample posts until + its owner connects a WordPress site — then record what went live. Run one phase at a time with `--phase ` or the whole + sequence with `--resume`; see docs/phases/README.md for the contract every + phase follows, and BOOTSTRAP.md for the operator checklist no script can + perform. + +# ── INPUTS ──────────────────────────────────────────────────────────────── +# The instance-identity contract, consumed by tooling/rebrand/rebrand.mjs via +# the `.rebrand/values.json` the `rebrand-values` module templates. Every +# input a later phase needs is in that file, because it is committed and so +# survives a fresh container; `.orun/provenance.lock` does not. +# +# The card (blueprint.yaml) declares a subset of these with the patterns the +# console validates; testing/manifest.test.sh fails if a card input is not +# one of these, or if one of these is required and nothing supplies it. +inputs: + reponame: + type: string + pattern: "^[a-z][a-z0-9-]*$" + required: true + description: Repo slug (e.g. acme-notes) — intent metadata.name, the Worker name prefix, the secret project. + productname: + type: string + required: true + description: The site's display name (e.g. "Acme Notes") — the nav, the footer and the page titles. + productdomain: + type: string + default: "" + description: >- + The site's own domain, once it has one (e.g. acme.dev). NOT ASKED: the + site answers on workers.dev from its first deploy, and a domain is an + owner's step after it. Empty, the rebrand writes the reserved + placeholder `.example.com` where the domain goes (BASE_DOMAIN + in intent.yaml, for dev, stage and prod), so setting it later is + replacing that one string — the site's README, "Custom domain", says + how. Pass it with --set only to brand a hand-run build with a domain it + already has. + githuborg: + type: string + pattern: "^[A-Za-z0-9][A-Za-z0-9-]*$" + required: true + description: >- + GitHub owner the site's repository is created under. 01-product waits for + the App installation on THIS owner before it creates anything: the + platform learns of a pull request only through the installation on the + account that owns the repository. + subdomain: + type: string + default: "your-workers-subdomain" + description: >- + The workers.dev subdomain of the Cloudflare account the site deploys + into — its URLs, the deploy's smoke, the probes. A console or + `--from bst_…` build gets it from the workspace's Cloudflare connection + (blueprint.yaml declares `from: connection.cloudflare.workersSubdomain`); + pass it with --set only for a hand-run build. + repoPrivate: + type: boolean + default: true + description: >- + Whether the repository is created private. Private is the safe default; + `orun.repo/ensure@v1` only sets it at creation — an existing repository + keeps the visibility it has. + orunWorkspace: + type: string + default: "" + # Unset, it is the workspace the build runs in (ORUN_WORKSPACE — which a + # console build's sandbox always sets, and which the console form cannot + # send). A value set on the command line or recorded by the tree wins. + from: workspace + description: >- + Orun Cloud workspace (ws_…) for the site's remote state. Unset, it is the + workspace the build runs in; with none anywhere, 01-product writes a + placeholder that fails loudly rather than silently claiming another + tenant's workspace. + epicSlug: + type: string + pattern: "^[a-z][a-z0-9-]*$" + default: cms-wordpress-baselining + description: >- + The epic this bootstrap tracks itself under. Found by slug, so a run + that starts fresh and a run that resumes find the same work. + +# ── SOURCES ─────────────────────────────────────────────────────────────── +# The baseline is this repository itself. Run `orun new` from its root so +# `path: .` resolves to it; orun pins it by digest into its object store +# before any module reads it, so an instance is reproducible and provenanced. +sources: + - name: baseline + kind: dir + path: . + +# Derived build output, local secrets, and the factory's own lanes — never +# carried into an instance. +# +# WHAT `ignore` ACTUALLY EXCLUDES: orun matches an entry two ways, and which +# one depends on the entry. A pattern with no glob metacharacter is compared +# against each path SEGMENT; only a pattern containing one is compared against +# the whole relative path. So `apps/web/.dev.vars` on its own would match +# nothing — it needs the `**/`. testing/coverage.test.sh refuses an entry that +# names a path without a glob. +ignore: + - dist + - coverage + - .turbo + - .next + - .open-next + - .wrangler + - node_modules + - .orun + - plan.json + - "**/*.tsbuildinfo" + - "**/next-env.d.ts" + # `orun new` snapshots the WORKING TREE, not the git index: an operator's + # local environment files would otherwise be copied into somebody else's + # repository — a WordPress URL or webhook secret among them. `.env.example` and + # `.dev.vars.example` are not, and ship. + - "**/.env" + - "**/.env.local" + - "**/.env.*.local" + - "**/.dev.vars" + # wrangler's per-environment `.dev.vars.` — but not `.dev.vars.example`, + # which ships (an entry is a Go path.Match glob, so `[^e]` is a negated + # class): `**/.dev.vars.*` silently dropped the example a site's owner + # copies to hold the webhook secret for `wrangler dev`. + - "**/.dev.vars.[^e]*" + # THE FACTORY'S OWN LANES. `github-workflows` copies the whole of `.github`, + # so without these two entries every site built from this baseline would + # carry them — `baseline.yml` runs `testing/*.sh`, which no module places, + # and `tag.yml` cuts baseline tags a product does not have. + # testing/coverage.test.sh fails if a lane reading `testing/` is not here. + - "**/.github/workflows/baseline.yml" + - "**/.github/workflows/tag.yml" + +# ── MODULES ─────────────────────────────────────────────────────────────── +# One module per component or root file. Root files are single-file modules +# rather than one module with an include list: a file shipping to a product +# is a line in a diff, and nothing of the factory (specs/, tasks/, testing/, +# hooks/, docs/phases/, tooling/rebrand/, tooling/bootstrap/, the blueprints, +# BOOTSTRAP.md) can ship by accident. testing/leak.test.sh holds that line. +modules: + # ── the identity file every later phase reads back ─────────────────────── + # The only place blueprint inputs touch the tree; everything else is a + # verbatim copy the `rebrand` hook rewrites. Committed, so a phase run months + # later from a fresh container recovers what the operator answered. + - name: rebrand-values + mode: template + files: + ".rebrand/values.json": | + { + "reponame": "{{ .reponame }}", + "productname": "{{ .productname }}", + "productdomain": "{{ .productdomain }}", + "subdomain": "{{ .subdomain }}", + "orunWorkspace": "{{ .orunWorkspace }}", + "githuborg": "{{ .githuborg }}", + "epicSlug": "{{ .epicSlug }}" + } + + # ── root files ─────────────────────────────────────────────────────────── + - name: root-intent + mode: copy + source: baseline + from: intent.yaml + to: intent.yaml + - name: root-package-json + mode: copy + source: baseline + from: package.json + to: package.json + - name: root-pnpm-workspace + mode: copy + source: baseline + from: pnpm-workspace.yaml + to: pnpm-workspace.yaml + # The baseline's complete lockfile, as it is: the whole tree lands at once + # and the lockfile carries no identity, so there is nothing to re-resolve — + # the lanes install it with --frozen-lockfile, and the baseline's own CI + # (testing/e2e.test.sh) does the same on this exact tree before a tag. + - name: root-pnpm-lock + mode: copy + source: baseline + from: pnpm-lock.yaml + to: pnpm-lock.yaml + - name: root-turbo + mode: copy + source: baseline + from: turbo.json + to: turbo.json + - name: root-gitignore + mode: copy + source: baseline + from: .gitignore + to: .gitignore + # The SITE's README, not this repository's: this one is about the baseline + # (how to instantiate it, how it is tested), and a site's owner has no use + # for any of that. It carries the steps that connect a WordPress site. + - name: root-readme + mode: copy + source: baseline + from: .baseline/product/README.md + to: README.md + - name: github-workflows + mode: copy + source: baseline + from: .github + to: .github + - name: vscode + mode: copy + source: baseline + from: .vscode + to: .vscode + + # The two context pages a site genuinely owns: its operating contract, and + # the deployment manifest 02-docs renders. One module per file, so a new + # file in ai/context/ cannot ship without somebody writing a module for it. + - name: ai-operations + mode: copy + source: baseline + from: ai/context/operations.md + to: ai/context/operations.md + - name: ai-deployment + mode: copy + source: baseline + from: ai/context/deployment.md + to: ai/context/deployment.md + + # ── the empty discovery roots, declared ────────────────────────────────── + # orun's repo-scale gate — and later `orun plan` in the site's own CI — + # discovers apps/, infra/, packages/ and tests/, and a missing root is a + # hard failure. infra/ and packages/ stay empty: the site reads no wiring + # (WordPress is the owner's own site, not infrastructure this repository applies) + # and shares no package. A file the tree needs in order to be valid is what a + # module is for. + - name: discovery-roots + mode: template + files: + "apps/.gitkeep": "" + "infra/.gitkeep": "" + "packages/.gitkeep": "" + "tests/.gitkeep": "" + + # ── shared tooling ─────────────────────────────────────────────────────── + # Only what a site runs: the TypeScript and ESLint configuration and the + # deploy-time wrangler renderer (for a Worker that comes to take wiring). + # The factory's tooling (rebrand, bootstrap) stays here. + - name: tooling-tsconfig + mode: copy + source: baseline + from: tooling/tsconfig + to: tooling/tsconfig + - name: tooling-eslint + mode: copy + source: baseline + from: tooling/eslint + to: tooling/eslint + - name: tooling-wire + mode: copy + source: baseline + from: tooling/wire + to: tooling/wire + + # ── the site ───────────────────────────────────────────────────────────── + - name: web + mode: copy + source: baseline + from: apps/web + to: apps/web + dependsOn: [tooling-eslint, tooling-tsconfig] + - name: web-tests + mode: copy + source: baseline + from: tests/web + to: tests/web + dependsOn: [web, tooling-eslint, tooling-tsconfig] + +# ── THE WORK, UP FRONT ──────────────────────────────────────────────────── +# The bootstrap is work, so it lives where work lives — and all of it is on +# the plane before the first phase places a file: one epic, one milestone per +# phase in the order the phases run, one task per landing. +# +# `hooks.preInstantiate` (orun >= v2.60) runs under no phase, once per run, on +# a resume too. Everything here is find-or-create BY IDENTITY — the epic by +# slug, a milestone by name within its epic, a task by title within its epic — +# so a second run, a resume and a redo all find what the first run made. The +# milestones are created IN ORDER and BEFORE the tasks: the plane appends each +# new milestone after the last, and a task naming a milestone the epic does +# not have yet would create it out of order. +# +# IN THE BACKGROUND (orun >= v2.88.0, `background: true` on every hook here). +# Nothing a phase does before its landing reads the task plane — the provider +# check, the placement, the rebrand, the repository, the secrets — so the +# whole list runs beside 01-product instead of before it, in order. A hook +# that works on the plane (`orun.task/ensure@v1`, `orun.pr/land@v1`) waits +# for it to finish; a failure here stops the build at the next hook. +# +# Each phase's own `task` hook runs `orun.task/ensure@v1` on its task again, +# just before its landing. Same identity, so it finds rather than creates, +# and it is how the phase gets the task's KEY for its landing; it sits in +# `post` rather than `pre` so that everything before it overlaps with this +# list. The MILESTONE keeps the phase's name: it is the identity the engine's +# phase events, the plane's evidence and the console's rows all meet on, and +# the card's `programme.milestones` names the same list. +hooks: + preInstantiate: + - id: epic + uses: orun.task/ensure@v1 + background: true + with: + kind: epic + slug: "{{ .inputs.epicSlug }}" + name: "WordPress site baselining — {{ .inputs.productname }}" + description: >- + Everything the cms-wordpress baseline builds for + {{ .inputs.productname }} in {{ .inputs.githuborg }}/{{ .inputs.reponame }}: + the repository, its CI and the site live on stage and prod in one + landing, and the record of what went live. One milestone per phase, + in the order the phases run; one task per landing, each bound to the + pull request that lands it. + owner: me + - id: m01 + uses: orun.task/ensure@v1 + background: true + with: + kind: milestone + epic: "{{ .inputs.epicSlug }}" + name: 01-product + exitCriteria: + - repository created under {{ .inputs.githuborg }} and linked to the workspace + - the site merged, deployed on stage and prod, its smoke green + - the site answers on both workers.dev URLs + - id: m02 + uses: orun.task/ensure@v1 + background: true + with: + kind: milestone + epic: "{{ .inputs.epicSlug }}" + name: 02-docs + exitCriteria: + - ai/context/deployment.md on main matches the probed live URLs + - prod waits on stage again + - id: t01 + uses: orun.task/ensure@v1 + background: true + with: + kind: task + epic: "{{ .inputs.epicSlug }}" + milestone: 01-product + name: "Build the site in one landing" + brief: >- + Create {{ .inputs.githuborg }}/{{ .inputs.reponame }}, land the whole + site as its first pull request — the intent, CI, tooling, the identity + every later phase reads back, the Next.js app and its tests, branded + as {{ .inputs.productname }} — and see the convergence deploy it to + stage and prod, smoke-tested over HTTP. It serves bundled sample + posts until a WordPress site is connected. + prefix: BASE + contract: .baseline/tasks/01-product.TaskContract.yaml + - id: t02 + uses: orun.task/ensure@v1 + background: true + with: + kind: task + epic: "{{ .inputs.epicSlug }}" + milestone: 02-docs + name: "Record the live deployment" + brief: >- + Probe every live URL one last time and write the deployment record + into the repository from what actually answered, not from what the + blueprint intended. + prefix: BASE + contract: .baseline/tasks/02-docs.TaskContract.yaml + +# ── PHASES ──────────────────────────────────────────────────────────────── +# A phase is orun's own barrier over the module DAG and the whole of what a +# phase DOES: what it is for a person (`title`), what to budget +# (`expectedMinutes`), what must already be true (`requires`), and the hooks +# that do its work around placement — `pre` before, `post` after, `await` for +# what is still converging when the hooks are done. +# +# THE ORDER HERE IS THE EXECUTION ORDER, and the numbered names are the names +# the task plane's milestones carry. A dependency may never point forward +# across a phase boundary; orun refuses the blueprint if one does. +# +# TWO PHASES. The whole site is ONE landing (01-product), as cirrus-baseline +# builds its product since baseline-v22: a landing has a fixed cost, and +# nothing in this tree needs one landing to finish before another starts — +# the order a deploy needs is the plan's to carry. The record (02-docs) places +# NO modules: it is a phase because it is a separately landable unit with its +# own task and its own PR. +phases: + - name: 01-product + title: The site, built in one landing + description: The whole tree — manifests, CI, tooling, identity, the Next.js app and its tests — branded, landed as one pull request, and deployed by one convergence. + # An estimate, not a measurement: the landing no longer waits on a full + # Next.js build in Checks — its commit is checked here (`checks: local`) + # and merged — the task set-up runs in the background, and the watch + # reads every 5 s. What is left is the merge's convergence: the site's + # build, deploy and smoke on stage and prod side by side. Lowered by a + # minute from the old 12 until a bootstrap on this shape measures it. + expectedMinutes: 11 + narrate: + start: "Creating the repository and landing the whole site in one pull request — intent, CI, tooling, the Next.js app and its tests. Then one convergence deploys it to stage and prod side by side. Usually about {{ .meta.expectedMinutes }} minutes." + await: "One convergence is deploying the site to stage and prod: install, the Next.js build, deploy and a smoke in each. The build is the long pole; nothing is stuck." + done: "{{ .inputs.reponame }} is live on stage and prod — {{ .meta.files }} files on main, branded as {{ .inputs.productname }}, serving its sample posts until a WordPress site is connected. That took {{ .meta.elapsed }}." + failed: "The site did not come up. The failing lane above names the step — the build, the deploy or the smoke — and a provider error is in its log; whatever deployed is still there." + modules: [ai-deployment, ai-operations, discovery-roots, github-workflows, rebrand-values, root-gitignore, root-intent, root-package-json, root-pnpm-lock, root-pnpm-workspace, root-readme, root-turbo, tooling-eslint, tooling-tsconfig, tooling-wire, vscode, web, web-tests] + # THE PLATFORM MUST BE ABLE TO SEE THE REPOSITORY BEFORE IT EXISTS. Every + # phase lands a pull request that files under its task, and the platform + # learns of a PR only through the GitHub App installation on the account + # that OWNS the repository. So the owner's connection is asked for here, + # before a repository is created, and waited for like any other consent — + # and the Cloudflare connection, which every deploy credential below is + # minted from, since this phase is the one that deploys. + requires: + probe: + - id: providers + uses: orun.doctor/check@v1 + with: + providers: [github, cloudflare] + githubOwner: "{{ .inputs.githuborg }}" + waitSeconds: 600 + pollSeconds: 20 + hooks: + # The identity chain, then the repository, its link, its credentials, + # the task and the landing — cirrus-baseline's 01-product, hook for hook. + # No `pre` hook: the task is found in `post`, just before the landing, + # so everything before it runs beside the background task set-up. + # + # rebrand.mjs enumerates the tree with `git ls-files`, so the output has + # to be a git repository with a populated index BEFORE it runs. `git add + # -A` only stages; the landing commits. + post: + # A RE-RUN MUST HAVE SOMETHING TO LAND: a convergence can fail after + # its PR merged, and the merge has already put every file this phase + # places on main; orun derives phase state from the tree, so a forced + # re-run lands an EMPTY diff while the site's CI plans `--changed`. So + # the phase rewrites ONE trailing marker line in each component.yaml + # its contract names — `# orun: redeploy ` — and the + # landing has a diff that redeploys exactly those components. The + # marker is a deploy trigger, not state: nothing reads it back. + - id: retouch + run: ["node", "{{ .baseline.dir }}/tooling/bootstrap/retouch.mjs", "--phase", "{{ .phase.name }}", "--affects", "{{ .baseline.dir }}/.baseline/tasks/01-product.TaskContract.yaml"] + - id: git-init + run: ["git", "init", "-q"] + - id: git-stage + run: ["git", "add", "-A"] + - id: rebrand + run: ["node", "{{ .baseline.dir }}/tooling/rebrand/rebrand.mjs", "--values", ".rebrand/values.json", "--allow-dirty"] + # Re-tenant the site. rebrand.mjs treats the orun state backend as + # org-owned and leaves it alone, so intent.yaml would keep THIS + # repository's `workspace:` — the site's CI would then claim another + # tenant's workspace on every remote op. Hook argv is not templated, + # so the value travels through .rebrand/values.json, which IS. + - id: orun-workspace + run: + - node + - -e + - | + const fs = require("fs"); + const values = JSON.parse(fs.readFileSync(".rebrand/values.json", "utf8")); + const ws = String(values.orunWorkspace || "").trim() || "ws_SET_ME"; + const before = fs.readFileSync("intent.yaml", "utf8"); + // Look for the line rather than for a change: a site built into + // a workspace already named there rewrites the line to the value + // it already has, and "unchanged" is not "missing". + const line = /^(\s*workspace:\s*).*$/m; + if (!line.test(before)) { + console.error("orun-workspace: no `workspace:` line in intent.yaml — refusing to guess"); + process.exit(1); + } + fs.writeFileSync("intent.yaml", before.replace(line, "$1" + ws)); + console.log( + ws === "ws_SET_ME" + ? "orun-workspace: wrote placeholder ws_SET_ME — set your Orun Cloud workspace before enabling remote state" + : "orun-workspace: intent.yaml workspace -> " + ws, + ); + # The site carries no work tree of this repository's: `specs/` and + # `tasks/` never ship, so intent.yaml's `work:` block would point its + # every plan at two directories that do not exist. + - id: work-tree + run: ["node", "{{ .baseline.dir }}/tooling/bootstrap/work-tree.mjs", "--strip"] + # STAGE AND PROD DEPLOY SIDE BY SIDE UNTIL THE BOOTSTRAP IS DONE. The + # promotion gate makes prod wait out stage's deploy; during a + # bootstrap both are empty and the landing is watched to green, so it + # protects nothing and doubles the convergence. Deferred here, + # restored by 02-docs. tooling/bootstrap/promotion.mjs. + - id: promotion + run: ["node", "{{ .baseline.dir }}/tooling/bootstrap/promotion.mjs", "--defer"] + # DEV'S VERIFY LANES STAY OFF MAIN UNTIL THE BOOTSTRAP IS DONE, by the + # same mechanism: a third Next.js build on the merge proves nothing + # the baseline's own CI did not. Pull requests keep their dev lanes. + # tooling/bootstrap/dev-lanes.mjs. + - id: dev-lanes + run: ["node", "{{ .baseline.dir }}/tooling/bootstrap/dev-lanes.mjs", "--defer"] + # Re-stage so `git ls-files` and `rebrand --verify` see the rewritten tree. + - id: git-restage + run: ["git", "add", "-A"] + - id: rebrand-verify + run: ["node", "{{ .baseline.dir }}/tooling/rebrand/rebrand.mjs", "--verify", "--values", ".rebrand/values.json"] + # The repo has to exist before there is anywhere to land. + - id: repo + uses: orun.repo/ensure@v1 + narrate: "The repository exists at {{ .inputs.githuborg }}/{{ .inputs.reponame }}." + with: + owner: "{{ .inputs.githuborg }}" + name: "{{ .inputs.reponame }}" + private: "{{ .inputs.repoPrivate }}" + # THE REPOSITORY MUST BE THE WORKSPACE'S before anything lands in it, + # or the site's own CI cannot reach the platform: every convergence + # lane authenticates over GitHub OIDC, resolved through the repo link. + # `link` may be refused where the credential cannot write links (a + # workspace key) and the platform has linked the repository already, + # so it is best effort and `check` is the gate — an unlinked + # repository stops here, naming the fix, instead of in every lane. + - id: link + run: + - bash + - -c + - | + orun cloud link --org "$1" || true + orun cloud check --org "$1" || { + echo "$2 is not linked to workspace $1 — its CI cannot authenticate. Link it (orun cloud link --org $1, or the console's Git Repos) and re-run this phase." >&2 + exit 1 + } + - link + - "{{ .inputs.orunWorkspace }}" + - "{{ .inputs.githuborg }}/{{ .inputs.reponame }}" + # The deploy credentials, brokered, in ONE hook (orun >= v2.87.0): + # `secrets` mints each key under its own scope template from the one + # connection the build is bound to, reading the connections and the + # existing secrets once and creating the missing keys side by side. + # The deploy lane binds both keys (the workers-assets composition's + # `secretBindings`); the site reads no D1, R2, Hyperdrive or DNS, so + # no other scope is asked for. Keys that already exist are kept. + # After the link, before the landing whose convergence uses them. + # Nothing is minted for WordPress: no platform connection can, and + # the site builds and serves without it (its optional secret ref + # skips a key nobody has stored). + - id: secrets + uses: orun.integrations/reconcile@v1 + with: + provider: cloudflare + secrets: + - { key: CLOUDFLARE_API_TOKEN, template: workers-deploy } + - { key: CLOUDFLARE_ACCOUNT_ID, template: account-id } + # The task this landing closes, and its key. The run-level list above + # opens it in the background; this is the first hook that needs it, + # so it is the one that waits for that list (orun >= v2.88.0) — every + # hook before it ran while the task plane was still being set up. + - id: task + uses: orun.task/ensure@v1 + with: + kind: task + epic: "{{ .inputs.epicSlug }}" + milestone: "{{ .phase.name }}" + name: "Build the site in one landing" + prefix: BASE + contract: .baseline/tasks/01-product.TaskContract.yaml + # THE SITE IS A PULL REQUEST THAT IS CHECKED, THEN MERGED — checked + # HERE (`checks: local`, orun >= v2.88.0): `orun validate`, then + # `orun plan` as the pull request and as the merge to main plan it, + # on the commit, before it is pushed. That is what the PR's `plan` + # job checks (the intent, every component and every composition + # resolve), plus the merge's own plan, in under a second instead of + # waiting for a runner. Before, this landing waited on the PR's whole + # CI run — Checks' full Next.js build among it — for a tree the + # baseline's own e2e tier already built, tested and linted before + # the tag. A tree that fails is never pushed. The PR's CI still runs + # (`plan` alone on a bootstrap branch, `orun/BASE-…`, ci.yml); nothing + # waits for it. The merge runs every lane on main a minute later, for + # real, and the convergence after the merge is what this phase + # watches to green. + - id: land + uses: orun.pr/land@v1 + narrate: "The site is merged into main." + with: + task: "{{ .phase.hooks.task.outputs.key }}" + epic: "{{ .inputs.epicSlug }}" + branchSlug: "{{ .phase.name }}" + title: "feat: {{ .inputs.productname }}, a headless WordPress site on Workers, live on stage and prod" + checks: local + # No wiring await: the site has no infra component, so nothing + # lease-publishes a WIRING_* secret for `orun.secrets/exists@v1` to find. + await: + - id: converge + uses: orun.run/watch@v1 + narrate: "The site built, deployed and passed its smoke on stage and prod, and the convergence run came back green." + with: + # The run for the commit THIS landing merged (an unpinned watch + # reads the previous push's run); the budget is a few times + # expectedMinutes plus room for the resumes. + sha: "{{ .phase.hooks.land.outputs.mergeSha }}" + repo: "{{ .inputs.githuborg }}/{{ .inputs.reponame }}" + resumeBudget: 3 + waitSeconds: 1800 + # Read every 5 s, not the action's 40: the build goes on the + # moment the run is green instead of up to 40 s after it. + pollSeconds: 5 + - id: verify + uses: orun.http/probe@v1 + narrate: "The site answered on stage and prod." + with: + urls: + - "https://{{ .inputs.reponame }}-web-stage.{{ .inputs.subdomain }}.workers.dev" + - "https://{{ .inputs.reponame }}-web-prod.{{ .inputs.subdomain }}.workers.dev" + + # Places nothing. It records what 01-product built, from PROBED facts rather + # than from what the blueprint intended — which is why it runs last. Its + # render probes every URL as it writes the record, and this landing + # redeploys nothing, so there is no probe after it to wait for. + - name: 02-docs + title: The deployment, recorded + description: The live-deployment manifest, rendered from probed reality, and the promotion gate and dev's lanes put back. + # An estimate: the render's probes, then a landing checked here and + # merged, with nothing after it to wait for. + expectedMinutes: 1 + narrate: + start: "Now recording what was actually built — probing every URL and writing the deployment manifest into the repository." + done: "ai/context/deployment.md now records the live deployment, written from probed facts, and prod waits on stage again. {{ .meta.elapsed }}." + failed: "The deployment record did not land. The site is still live; only the write-up is missing." + modules: [] + requires: + phases: [01-product] + hooks: + post: + # THE SITE GOES LIVE WITH ITS PROMOTION GATE. 01-product deferred + # `prod.promotion.dependsOn: [stage]`; this, the last landing, puts it + # back, and from here on a change reaches prod only after stage. + # Restoring touches only intent.yaml's `environments` section, which + # `orun plan --changed` maps to no component, so this landing + # redeploys nothing. + - id: promotion + run: ["node", "{{ .baseline.dir }}/tooling/bootstrap/promotion.mjs", "--restore"] + # And dev verifies every merge to main again (01-product deferred it). + - id: dev-lanes + run: ["node", "{{ .baseline.dir }}/tooling/bootstrap/dev-lanes.mjs", "--restore"] + - id: render + run: ["bash", "{{ .baseline.dir }}/hooks/render-deployment-docs.sh", ".", "{{ .inputs.orunWorkspace }}", "{{ .baseline.dir }}"] + - id: task + uses: orun.task/ensure@v1 + with: + kind: task + epic: "{{ .inputs.epicSlug }}" + milestone: "{{ .phase.name }}" + name: "Record the live deployment" + prefix: BASE + contract: .baseline/tasks/02-docs.TaskContract.yaml + # Checked here and merged, as 01-product's landing is. + - id: land + uses: orun.pr/land@v1 + narrate: "The deployment record is merged into main." + with: + task: "{{ .phase.hooks.task.outputs.key }}" + epic: "{{ .inputs.epicSlug }}" + branchSlug: "{{ .phase.name }}" + title: "docs(deployment): record the live deployment state" + checks: local diff --git a/specs/epics/README.md b/specs/epics/README.md index 9622037..522f843 100644 --- a/specs/epics/README.md +++ b/specs/epics/README.md @@ -7,6 +7,6 @@ folder is the adoption; the merge creates the epic in the workspace. | Epic | Cluster | Status | What it is | |------|---------|--------|------------| -| [`cms-wordpress/`](./cms-wordpress/) | **WP** | In progress (WP1: the site on Workers) | Vercel's Next.js Starter for WordPress Headless CMS — 9d8's next-wp, posts, pages and terms from a WordPress REST API — on Cloudflare Workers + Static Assets through OpenNext, serving sample content until a WordPress is connected, and an Orun baseline that instantiates it (WP2) | +| [`cms-wordpress/`](./cms-wordpress/) | **WP** | ✅ Shipped (`baseline-v1`); not yet live | Vercel's Next.js Starter for WordPress Headless CMS — 9d8's next-wp, posts, pages and terms from a WordPress REST API — on Cloudflare Workers + Static Assets through OpenNext, serving sample content until a WordPress is connected, and an Orun baseline that instantiates it (WP2) | As-built ≠ intent: what shipped lives in each epic's `IMPLEMENTATION-STATUS.md`. diff --git a/specs/epics/cms-wordpress/IMPLEMENTATION-STATUS.md b/specs/epics/cms-wordpress/IMPLEMENTATION-STATUS.md index 738dbf2..41d6ab0 100644 --- a/specs/epics/cms-wordpress/IMPLEMENTATION-STATUS.md +++ b/specs/epics/cms-wordpress/IMPLEMENTATION-STATUS.md @@ -4,7 +4,7 @@ |---|---|---| | WP0 — the spec | ✅ | the repository's first commit | | WP1 — the site on Workers | ✅ | WP-2 | -| WP2 — a baseline | planned | WP-3 | +| WP2 — a baseline | ✅ | WP-3, tagged `baseline-v1` | ## Departures from the upstream template diff --git a/specs/epics/cms-wordpress/README.md b/specs/epics/cms-wordpress/README.md index 938e722..7748975 100644 --- a/specs/epics/cms-wordpress/README.md +++ b/specs/epics/cms-wordpress/README.md @@ -9,7 +9,7 @@ landing.** | | | |---|---| -| Status | In progress — WP1 on main: the site runs on Workers | +| Status | ✅ Shipped (`baseline-v1`) — proven offline in Baseline CI; not yet live (risk WP-A) | | Upstream | [9d8dev/next-wp](https://github.com/9d8dev/next-wp) (MIT), at `4a2caeb` (2026-08-06) — Vercel's Next.js Starter for WordPress Headless CMS | | Reference | [cms-sanity](https://github.com/sourceplane/cms-sanity) — the same scaffolding, tests and bootstrap, and the unconnected sample mode; [portfolio-starter-kit](https://github.com/sourceplane/portfolio-starter-kit) — the origin per environment | | Key | `WP` | diff --git a/specs/epics/cms-wordpress/epic.yaml b/specs/epics/cms-wordpress/epic.yaml index 12018c6..d1621f2 100644 --- a/specs/epics/cms-wordpress/epic.yaml +++ b/specs/epics/cms-wordpress/epic.yaml @@ -9,7 +9,7 @@ metadata: spec: title: "Vercel's Next.js Starter for WordPress Headless CMS on Cloudflare Workers" summary: "9d8's next-wp — a Next.js front end for a WordPress site used as a headless CMS: posts, pages, categories, tags and authors from its REST API, with search, filters, pagination, a sitemap, Open Graph images and a revalidation webhook — runs on Cloudflare Workers + Static Assets through @opennextjs/cloudflare, serves bundled sample content until a WordPress is connected, and becomes an Orun baseline that takes a new site from nothing to live on stage and prod in one landing." - state: started + state: completed milestones: - name: "WP0 — the spec" exitCriteria: diff --git a/testing/bootstrap-defer.test.sh b/testing/bootstrap-defer.test.sh new file mode 100755 index 0000000..526e2b4 --- /dev/null +++ b/testing/bootstrap-defer.test.sh @@ -0,0 +1,67 @@ +#!/usr/bin/env bash +# The two things a bootstrap turns off in intent.yaml and puts back — +# `prod.promotion` (tooling/bootstrap/promotion.mjs) and dev's push-to-main +# activation (tooling/bootstrap/dev-lanes.mjs) — must each defer, be +# idempotent both ways, leave a parseable intent while deferred, and restore +# the file BYTE-FOR-BYTE: a restore that reproduced the block by hand would +# be a second place the intent is authored. +set -euo pipefail +here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +root="$(cd "$here/.." && pwd)" +fail=0 +ok() { echo " ok $1"; } +bad() { echo " ✕ $1" >&2; fail=1; } + +tmp="$(mktemp -d)"; trap 'rm -rf "$tmp"' EXIT +cp "$root/intent.yaml" "$tmp/intent.yaml" + +for tool in promotion dev-lanes; do + f="$tmp/intent.yaml"; cp "$root/intent.yaml" "$f" + echo "── $tool.mjs" + node "$root/tooling/bootstrap/$tool.mjs" --check --file "$f" | grep -q -E 'enforced|active' && ok "starts enforced/active" || bad "starts enforced/active" + node "$root/tooling/bootstrap/$tool.mjs" --defer --file "$f" >/dev/null + node "$root/tooling/bootstrap/$tool.mjs" --check --file "$f" | grep -q deferred && ok "--defer defers" || bad "--defer defers" + python3 -c "import yaml,sys; yaml.safe_load(open(sys.argv[1]))" "$f" && ok "deferred intent still parses" || bad "deferred intent still parses" + cp "$f" "$tmp/once.yaml"; node "$root/tooling/bootstrap/$tool.mjs" --defer --file "$f" >/dev/null + cmp -s "$f" "$tmp/once.yaml" && ok "a second --defer changes nothing" || bad "a second --defer changes nothing" + node "$root/tooling/bootstrap/$tool.mjs" --restore --file "$f" >/dev/null + cmp -s "$f" "$root/intent.yaml" && ok "--restore is byte-exact" || bad "--restore is byte-exact" + node "$root/tooling/bootstrap/$tool.mjs" --restore --file "$f" >/dev/null + cmp -s "$f" "$root/intent.yaml" && ok "a second --restore changes nothing" || bad "a second --restore changes nothing" +done + +echo "── what each deferral means to a push-to-main plan" +f="$tmp/intent.yaml"; cp "$root/intent.yaml" "$f" +node "$root/tooling/bootstrap/dev-lanes.mjs" --defer --file "$f" >/dev/null +python3 - "$f" <<'PY' && ok "dev is no longer activated by github-push-main while deferred" || bad "dev is no longer activated by github-push-main while deferred" +import sys, yaml +d = yaml.safe_load(open(sys.argv[1])) +refs = d["environments"]["dev"]["activation"]["triggerRefs"] +assert "github-push-main" not in refs and "github-pull-request" in refs, refs +PY +f="$tmp/intent.yaml"; cp "$root/intent.yaml" "$f" +node "$root/tooling/bootstrap/promotion.mjs" --defer --file "$f" >/dev/null +python3 - "$f" <<'PY' && ok "prod has no promotion gate while deferred" || bad "prod has no promotion gate while deferred" +import sys, yaml +d = yaml.safe_load(open(sys.argv[1])) +assert "promotion" not in d["environments"]["prod"], d["environments"]["prod"].keys() +PY + +echo "── work-tree.mjs — the baseline's work tree does not ship" +f="$tmp/intent.yaml"; cp "$root/intent.yaml" "$f" +node "$root/tooling/bootstrap/work-tree.mjs" --check --file "$f" | grep -q declared && ok "this repository declares a work tree" || bad "this repository declares a work tree" +node "$root/tooling/bootstrap/work-tree.mjs" --strip --file "$f" >/dev/null +node "$root/tooling/bootstrap/work-tree.mjs" --check --file "$f" | grep -q absent && ok "--strip removes it" || bad "--strip removes it" +python3 - "$f" "$root/intent.yaml" <<'PY' && ok "everything else in the intent is untouched" || bad "everything else in the intent is untouched" +import sys, yaml +after, before = (yaml.safe_load(open(p)) for p in sys.argv[1:3]) +assert "work" not in after, list(after) +before.pop("work") +assert after == before, "a key other than work: changed" +PY +grep -q 'Where the work lives' "$f" && bad "the block's own comment is left behind" || ok "the block's own comment goes with it" +cp "$f" "$tmp/once.yaml"; node "$root/tooling/bootstrap/work-tree.mjs" --strip --file "$f" >/dev/null +cmp -s "$f" "$tmp/once.yaml" && ok "a second --strip changes nothing" || bad "a second --strip changes nothing" + +if [ "$fail" -ne 0 ]; then echo "bootstrap-defer.test.sh: failure(s)" >&2; exit 1; fi +echo "bootstrap-defer.test.sh: ok" diff --git a/testing/coverage.test.sh b/testing/coverage.test.sh new file mode 100755 index 0000000..f8a4b4c --- /dev/null +++ b/testing/coverage.test.sh @@ -0,0 +1,263 @@ +#!/usr/bin/env bash +# EVERY COMPONENT THIS REPO SHIPS IS PLACED BY EXACTLY ONE PHASE +# (saas-bootstrap-engine BE5, Tier 0). +# +# `repo-blueprint.yaml` decides what a product is made of. A component that no +# module names is not a component a product gets — and nothing would say so. +# The failure is quiet and late: the fork builds, its CI goes green, and the +# missing piece surfaces when somebody looks for a worker that was never +# copied. +# +# orun already enforces the other half — every MODULE belongs to exactly one +# phase, and a module naming an unknown module is a parse error. What it cannot +# know is what this repository contains, because a blueprint declares what to +# place and not what exists. That is this file's job. +# +# bash + python3 + PyYAML. No network, no orun, no credential. +set -euo pipefail +here="$(cd "$(dirname "$0")" && pwd)" +root="$(cd "$here/.." && pwd)" + +echo "── every component against the blueprint that places it" +python3 - "$root" <<'PY' +import pathlib, sys + +try: + import yaml +except ImportError: + sys.exit("PyYAML is required for the coverage gate (pip install pyyaml)") + +root = pathlib.Path(sys.argv[1]) +problems = [] +def bad(m): problems.append(m) + +# A component directory this repository deliberately keeps to itself. Declared +# with its reason rather than skipped by a pattern: "tests/*" would also hide +# the test suite a product genuinely needs, and the next +# baseline-only directory should have to be argued for in a diff. +# EMPTY: every component here is a product's. The baseline's own suites live in +# `testing/`, which is not a component at all and so is not one this gate can +# miss. The map stays so that the next baseline-only directory has to be +# argued for in a diff; the check below refuses an exemption whose directory is +# absent, so a stale entry cannot linger. +BASELINE_ONLY: dict[str, str] = {} + +bp = yaml.safe_load((root / "repo-blueprint.yaml").read_text()) + +# Where each module takes its content from, and which phase places it. +placed_by = {} +for m in bp.get("modules") or []: + src = (m.get("from") or "").rstrip("/") + if src: + placed_by.setdefault(src, []).append(m["name"]) +phase_of = {n: ph["name"] for ph in (bp.get("phases") or []) for n in ph["modules"]} + +components = sorted( + p.parent.relative_to(root).as_posix() + for p in root.rglob("component.yaml") + if "node_modules" not in p.parts and ".git" not in p.parts +) +if not components: + sys.exit("no component.yaml anywhere — this check has gone blind") + +for comp in components: + modules = placed_by.get(comp, []) + reason = BASELINE_ONLY.get(comp) + + if reason and modules: + bad(f"{comp} is declared baseline-only ({reason}) and yet {modules[0]} " + f"places it — one of the two is wrong") + continue + if reason: + continue + if not modules: + bad(f"{comp} is a component and no module places it. Either add one, or " + f"declare it baseline-only in this file with the reason.") + continue + if len(modules) > 1: + bad(f"{comp} is placed by {len(modules)} modules ({', '.join(modules)}) " + f"— a component comes from one place") + continue + if modules[0] not in phase_of: + bad(f"{comp} is placed by {modules[0]}, which is in no phase") + +# The other direction: a module naming a path this repo does not have places +# nothing, silently. orun resolves `from` against the source tree and an absent +# path is an empty module, not an error. +for src, modules in sorted(placed_by.items()): + if not (root / src).exists(): + bad(f"module {modules[0]} takes its content from {src}, which does not " + f"exist — it would place nothing, and say nothing") + +# A directory named baseline-only must actually BE one, or the exemption is +# protecting nothing and will outlive the thing it was written for. +for comp in BASELINE_ONLY: + if not (root / comp).exists(): + bad(f"{comp} is declared baseline-only and does not exist — drop the entry") + +# ── WHAT THE CATALOG SEES OF EACH COMPONENT ─────────────────────────────── +# +# Every component ships its generated pages (overview, architecture, runbook) +# and must ATTACH them in `spec.docs`: a `docs/` folder no manifest declares is +# never attached, so a fresh product's Docs library showed nothing for any +# component and the catalog failed every one of them on docs and on runbook. +# A component also needs a description: it is the catalog's one-line answer to +# "what is this", and the test suite had none. +# +# And a domain may not share a component's name. The catalog keys entities by +# name, so the `web` domain (`spec.domain: web`) took the `web` component's +# place, and the product's one deployable was missing from its own catalog. +WANT_DOCS = {"overview": "docs/overview.md", "architecture": "docs/architecture.md", "runbook": "docs/runbook.md"} +names, domains = {}, {} +for comp in components: + if comp in BASELINE_ONLY: + continue + doc = yaml.safe_load((root / comp / "component.yaml").read_text()) or {} + meta, spec = doc.get("metadata") or {}, doc.get("spec") or {} + names[meta.get("name")] = comp + if spec.get("domain"): + domains.setdefault(spec["domain"], comp) + if not (meta.get("description") or "").strip(): + bad(f"{comp}/component.yaml has no metadata.description — the catalog shows the component with nothing to say") + docs = spec.get("docs") or {} + got = {"overview": docs.get("overview")} + for page in docs.get("pages") or []: + got[page.get("role")] = page.get("path") + for role, path in WANT_DOCS.items(): + if got.get(role) != path: + bad(f"{comp}/component.yaml does not attach {path} as its {role} " + f"(spec.docs) — the page ships and the catalog never sees it") + elif not (root / comp / path).is_file(): + bad(f"{comp}/component.yaml attaches {path}, which does not exist") +for domain, comp in sorted(domains.items()): + if domain in names: + bad(f"{comp} declares domain `{domain}`, which is also the name of the " + f"component in {names[domain]} — the catalog keeps one of the two") + +# ── WHAT `ignore` ACTUALLY EXCLUDES (BE6) ────────────────────────────────── +# +# orun matches an ignore entry two ways, and WHICH ONE depends on the entry: +# a pattern containing no glob metacharacter is compared against each path +# SEGMENT, and only a pattern containing one is compared against the whole +# relative path. So `apps/admin-worker/wrangler.jsonc` matches nothing at all — +# no segment is ever equal to it — and the entry is INERT while reading exactly +# like a rule. +# +# That was not hypothetical. Twelve such entries were inert in this file's own +# blueprint, and a canary written to `apps/admin-worker/wrangler.jsonc` was +# placed straight into a product — which is the leak their comment says they +# exist to prevent. An `ignore` list that silently does nothing is worse than +# no list, because the comment above it reads as a defence. +for entry in bp.get("ignore") or []: + if "/" in entry and not any(c in entry for c in "*?["): + bad(f'ignore entry "{entry}" names a path and has no glob character, so orun ' + f'matches it against path SEGMENTS and it excludes nothing. Write it as ' + f'"**/{entry}".') + +# A workflow that runs the FACTORY must not ship to the factory's products. +# `github-workflows` copies the whole `.github` directory, so a lane added for +# this repository travels to every product built from it — and one that reads a +# path under `testing/` cannot work there, because `testing/` is not placed. +# A nightly lane did exactly this once: shipped, on a cron, reading an intent +# file no product has. +ignored = set(bp.get("ignore") or []) +workflows = sorted((root / ".github" / "workflows").glob("*.y*ml")) +for wf in workflows: + text = wf.read_text(encoding="utf-8") + if "testing/" not in text: + continue + rel = f".github/workflows/{wf.name}" + if f"**/{rel}" not in ignored and rel not in ignored: + bad(f"{rel} reads a path under testing/, which no product is placed with, " + f"and is not in the blueprint's ignore list — so it ships into every " + f'product and fails there. Add "**/{rel}" to ignore.') + +# ONE WORKFLOW ON A PUSH TO MAIN, in what a product carries. The bootstrap +# watches each phase's convergence with `orun.run/watch@v1` and `sha:`, which +# takes the newest workflow run for the merge commit — from any workflow. A +# second one on push (checks.yml did this) can be the run it finds: the first +# live bootstrap watched Checks go green while ci.yml's deploy lanes had +# failed. So every shipped workflow but ci.yml stays off pushes to main. +import yaml as _yaml +on_push = [] +for wf in workflows: + rel = f".github/workflows/{wf.name}" + if f"**/{rel}" in ignored or rel in ignored: + continue # the factory's own; never in a product + doc = _yaml.safe_load(wf.read_text(encoding="utf-8")) or {} + on = doc.get("on", doc.get(True)) # PyYAML reads a bare `on:` key as True + if isinstance(on, str): + on = {on: None} + elif isinstance(on, list): + on = {k: None for k in on} + push = (on or {}).get("push", "absent") + if push == "absent": + continue + branches = (push or {}).get("branches") if isinstance(push, dict) else None + if branches is None or "main" in branches: + on_push.append(wf.name) +if on_push != ["ci.yml"]: + bad(f"the workflows a product runs on a push to main are {on_push or 'none'}; " + f"it must be exactly ci.yml — orun.run/watch@v1 watches the newest run " + f"for a commit from ANY workflow, so a second one hides the convergence") + +# A MANUAL RUN (the deploys contract, packages/contracts DEPLOY_WORKFLOW in +# orun-cloud). Orunbase's Run and Deploy buttons dispatch ci.yml on main with +# inputs component, environment and deploy_id, then find the run by the deploy +# id in its name; GitHub refuses a dispatch whose inputs the workflow does not +# declare (422), so a product without them has dead buttons. The plan step +# must plan a dispatch under the push-to-main binding (what a merge deploys), +# on main only, and read the inputs from env, never interpolate them. +import yaml as _ydisp +_ci_path = root / ".github" / "workflows" / "ci.yml" +_ci = _ydisp.safe_load(_ci_path.read_text(encoding="utf-8")) or {} +_on = _ci.get("on", _ci.get(True)) or {} +_wd = _on.get("workflow_dispatch") if isinstance(_on, dict) else None +_inputs = (_wd or {}).get("inputs") or {} +if set(_inputs) != {"component", "environment", "deploy_id"}: + bad(f"ci.yml's workflow_dispatch declares inputs {sorted(_inputs) or 'none'}; Orunbase " + f"dispatches component, environment and deploy_id, and GitHub refuses unknown inputs") +else: + _intent = _ydisp.safe_load((root / "intent.yaml").read_text(encoding="utf-8")) or {} + _envs = set((_intent.get("environments") or {}).keys()) + _opts = set(_inputs["environment"].get("options") or []) + if _inputs["environment"].get("type") != "choice" or _opts != _envs: + bad(f"ci.yml's environment input offers {sorted(_opts)}; intent.yaml declares {sorted(_envs)}") + if "github-push-main" not in ((_intent.get("automation") or {}).get("triggerBindings") or {}): + bad("a manual run plans under intent.yaml's github-push-main binding, which is missing") +if "inputs.deploy_id" not in str(_ci.get("run-name", "")): + bad("ci.yml's run-name must carry inputs.deploy_id: Orunbase finds a deploy's run by that id") +_steps = (_ci.get("jobs") or {}).get("plan", {}).get("steps") or [] +_plan_step = next((s for s in _steps if "plan_args" in str(s.get("run", ""))), None) +if _plan_step is None: + bad("ci.yml's plan job has no step that builds plan_args") +else: + _run = _plan_step["run"] + for _needle, _why in ( + ('"$GITHUB_EVENT_NAME" = "workflow_dispatch"', "plans a dispatch on its own branch"), + ("--trigger github-push-main", "plans a dispatch as a merge to main"), + ('"$GITHUB_REF" != "refs/heads/main"', "refuses a dispatch started off main"), + ('--env "$DISPATCH_ENVIRONMENT"', "filters a dispatch to its environment"), + ): + if _needle not in _run: + bad(f"ci.yml's plan step no longer {_why} ({_needle!r} is gone)") + if "${{" in _run and "inputs." in _run: + bad("ci.yml's plan step interpolates inputs.* into its script; read them from env") + _env = _plan_step.get("env") or {} + if "inputs.component" not in str(_env.get("DISPATCH_COMPONENT", "")) \ + or "inputs.environment" not in str(_env.get("DISPATCH_ENVIRONMENT", "")): + bad("ci.yml's plan step must take DISPATCH_COMPONENT / DISPATCH_ENVIRONMENT from inputs in env") + +if problems: + print("FAIL: the blueprint and this repository disagree about what a product is:", + file=sys.stderr) + for p in problems: + print(f" - {p}", file=sys.stderr) + sys.exit(1) + +shipped = len(components) - len(BASELINE_ONLY) +print(f" {shipped} of {len(components)} components placed, " + f"{len(BASELINE_ONLY)} baseline-only by declaration") +PY + +echo "coverage.test.sh: ok" diff --git a/testing/e2e.test.sh b/testing/e2e.test.sh new file mode 100755 index 0000000..b2abfb3 --- /dev/null +++ b/testing/e2e.test.sh @@ -0,0 +1,438 @@ +#!/usr/bin/env bash +# TIER 2 — the site a bootstrap produces builds, deploys (dry) and serves, +# with NO WordPress behind it. +# +# placement.test.sh proves the tree a bootstrap ends with is the right tree. +# This proves it WORKS, by doing to it what its own pipelines will — on the +# day it is built, when its owner has not connected a WordPress site yet: +# +# 1. at the 01-product landing (the commit its one pull request merges), the +# landing's own checks — install with the lockfile the product ships, +# render fixtures and check the committed config is the render, +# typecheck, lint, test, build. The bootstrap's landings are checked in +# the box with `orun validate` and `orun plan` alone (`checks: local`; +# their PR's CI on an `orun/BASE-…` branch is `plan` alone), and a +# product's later pull requests build and dry-deploy it through ci.yml's +# lanes, so THIS is where a product those steps refuse is caught: before +# the tag, not after a build has merged it. Then the same at the 02-docs +# landing, the finished site; +# 2. the stage lane's own steps, read out of `orun plan` in the product for +# a pull request (the verify profile: the deploy profile has no dry run) +# — EVERY `run:` step of the job, in order, exactly as planned: the +# install, `verify-app-structure` (the committed `package.json` and +# `wrangler.jsonc`, checked BEFORE any build), `build-app` (TypeGen, +# `next build` on Turbopack, the OpenNext bundle), `verify-build-output` +# and `deploy-dry-run` (`wrangler deploy --dry-run --name +# -web-stage`). They run IN THE TREE THE RUNNER STAGES for the +# job (testing/lib/stage-job.py), with no build output in it and the +# dependency layout the pinned composition produces: if its install step +# is `scope: lane`, the top-level node_modules is a symlink to the source +# checkout's (which Turbopack refuses); if not, the job's own install +# step runs inside the staged tree. The job's WordPress ref is +# optional, and a fresh product has stored none, so the lane runs with +# no WORDPRESS_URL — as here; +# 3. serve the built Worker with `wrangler dev` and run the component's OWN +# `smokeCommand` against it, verbatim and then inside the deploy +# profile's planned `smoke` step (its retry loop and all — only its +# workers.dev URL swapped for the local one) — the check the real deploy +# ends with; then read every route the site promises: the home page, +# the posts page with its count, filters and search, the three sample +# posts under the "no WordPress site is connected" notice, the sample +# page, the category, tag and author lists, carrying the site's name and +# its stage origin in every absolute link, 404s for an unknown post, page +# and path, the sitemap, the Open Graph image, the static assets — and +# the webhook only the Worker's server code answers: /api/revalidate, +# refusing a request without the secret with 401. +# +# What it cannot do is the platform's half: create the repository, mint the +# brokered Cloudflare token, deploy for real and probe workers.dev — nor +# WordPress's: a connected site reading real posts needs a WordPress. That is +# a bootstrap against a workspace (BOOTSTRAP.md); everything short of it is +# here. +# +# Needs: orun, node, pnpm, python3 (+PyYAML), git, curl, setsid, and the +# network for `pnpm install` and the build's Google Font (or a warm store). +# Several minutes: three installs and three Next.js builds. +set -euo pipefail +here="$(cd "$(dirname "$0")" && pwd)" +root="$(cd "$here/.." && pwd)" +# shellcheck source=lib/bootstrap.sh +source "$here/lib/bootstrap.sh" + +for bin in orun node pnpm python3 git curl setsid; do + command -v "$bin" >/dev/null || { echo "e2e.test.sh needs $bin on PATH" >&2; exit 1; } +done + +scratch="$(mktemp -d)" +dev_pid="" +# wrangler dev runs under pnpm, node and two workerd processes; a TERM to the +# first does not reach the rest, and waiting on it then never returns. So it is +# started as its own process group (setsid) and the whole group is stopped. +cleanup() { + if [ -n "$dev_pid" ]; then + kill -TERM -- "-$dev_pid" 2>/dev/null || true + for _ in 1 2 3 4 5 6 7 8 9 10; do kill -0 -- "-$dev_pid" 2>/dev/null || break; sleep 0.5; done + kill -KILL -- "-$dev_pid" 2>/dev/null || true + fi + rm -rf "$scratch" +} +trap cleanup EXIT +values="$here/fixtures/acme.json" +repo="$(python3 -c "import json,sys;print(json.load(open(sys.argv[1]))['reponame'])" "$values")" +sub="$(python3 -c "import json,sys;print(json.load(open(sys.argv[1]))['subdomain'])" "$values")" +export CI=1 WRANGLER_SEND_METRICS=false NEXT_TELEMETRY_DISABLED=1 TURBO_TELEMETRY_DISABLED=1 +# NO WORDPRESS, whatever the caller's shell holds: this is the site its owner +# gets before connecting one. +unset WORDPRESS_URL WORDPRESS_HOSTNAME WORDPRESS_WEBHOOK_SECRET SITE_URL NEXT_PUBLIC_SITE_URL +free_port() { python3 -c "import socket;s=socket.socket();s.bind(('127.0.0.1',0));print(s.getsockname()[1]);s.close()"; } + +# The landing's own checks, step for step, run here at once on the whole +# tree. A pull request in the product builds and dry-deploys the site +# through ci.yml's lanes; the lint and the tests run here, and by hand before +# a push. +LANDING_CHECKS=( + "pnpm install --frozen-lockfile" + "pnpm run wire:fixture" + "git diff --exit-code" + "pnpm typecheck" + "pnpm lint" + "pnpm test" + "pnpm build" +) +checks() { # DIR LOG + local dir="$1" log="$2" cmd + for cmd in "${LANDING_CHECKS[@]}"; do + echo " \$ $cmd" | tee -a "$log" + if ! (cd "$dir" && bash -c "$cmd") >> "$log" 2>&1; then + echo "FAIL: \`$cmd\` failed in $dir" >&2; tail -40 "$log" >&2; return 1 + fi + done +} + +echo "── the offline bootstrap (testing/lib/bootstrap.sh)" +tree="$scratch/$repo" +bootstrap_offline "$root" "$tree" "$values" "$scratch/logs" > "$scratch/bootstrap.log" 2>&1 || { + echo "FAIL: the offline bootstrap stopped" >&2; tail -40 "$scratch/bootstrap.log" >&2; exit 1; } +s00="$(git -C "$tree" rev-parse HEAD~2)"; s01="$(git -C "$tree" rev-parse HEAD~1)" +echo " 2 phases placed and landed on orun's Initial commit" + +# ── 1. each landing's own checks ─────────────────────────────────────────── +echo "── 01-product's landing: install, the fixture render, typecheck, lint, test, build" +git -C "$tree" worktree add -q "$scratch/at-01" "$s01" +checks "$scratch/at-01" "$scratch/checks-01.log" +# Its tree is not needed again, and the disk is shared. +git -C "$tree" worktree remove --force "$scratch/at-01" + +echo "── 02-docs's landing (the finished site): the same checks" +checks "$tree" "$scratch/checks-site.log" +grep -q '(Turbopack)' "$scratch/checks-site.log" \ + || { echo "FAIL: the landing's build did not run on Turbopack" >&2; exit 1; } + +# ── 2. the stage lane, as a pull request plans it ────────────────────────── +echo "── the stage lane: every run step the PR plan gives web@stage, in a staged job tree" +(cd "$tree" && orun plan --intent intent.yaml --trigger github-pull-request --changed \ + --base "$s00" --head "$s01" --env stage --output "$scratch/plan-pr.json") > "$scratch/plan-pr.log" 2>&1 \ + || { echo "FAIL: orun plan (pull request)" >&2; tail -15 "$scratch/plan-pr.log" >&2; exit 1; } +python3 - "$scratch/plan-pr.json" "$scratch/steps" "$tree" "$values" <<'PY' +import json, pathlib, sys +import yaml +plan = json.load(open(sys.argv[1])) +out = pathlib.Path(sys.argv[2]); out.mkdir() +tree, values = pathlib.Path(sys.argv[3]), json.load(open(sys.argv[4])) +repo, ws = values["reponame"], values["orunWorkspace"] +job = next(j for j in plan["jobs"] if j["component"] == "web" and j["environment"] == "stage") +params = yaml.safe_load((tree / "apps/web/component.yaml").read_text())["spec"]["parameters"] +order, uses = [], [] +for s in job["steps"]: + if "use" in s: + uses.append(f"{s['id']}\t{s['use']}\t{json.dumps(s.get('with') or {})}") + continue + order.append(s["id"]) + (out / f"{s['id']}.sh").write_text(s.get("run") or "") + (out / f"{s['id']}.wd").write_text(s.get("working-directory") or ".") + if s.get("scope"): + (out / f"{s['id']}.scope").write_text(s["scope"]) +(out / "order").write_text("\n".join(order) + "\n") +(out / "uses").write_text("\n".join(uses) + "\n") +(out / "path").write_text(job.get("path") or "apps/web") +(out / "profile").write_text(job["profile"]) +(out / "node").write_text(params["nodeVersion"]) +(out / "pnpm").write_text(params["pnpmVersion"]) +for k, v in (job.get("env") or {}).items(): + (out / "env").open("a").write(f"export {k}={json.dumps(v)}\n") +# What the platform resolves into the job before its first step. The +# WordPress URL's ref is OPTIONAL: on a product nobody has connected, nothing +# is stored under it, so nothing is exported — which is what this lane replays. +refs = {r["asEnv"]: r for r in job.get("secretRefs") or []} +for key in ("WORDPRESS_URL",): + r = refs.get(key) + if not r or r.get("optional") is not True or f"/{repo}/stage/" not in r.get("ref", ""): + sys.exit(f"FAIL: the stage lane resolves {key} as {r} — want an optional ref to the product's stage secret") +required = sorted(k for k, r in refs.items() if not r.get("optional")) +if required: + sys.exit(f"FAIL: the verify lane requires secrets {required}; a pull request's lane needs none") +PY +order="$(tr '\n' ' ' < "$scratch/steps/order")" +echo " $(cat "$scratch/steps/profile"): $order" +for need in install-workspace-dependencies verify-app-structure build-app verify-build-output deploy-dry-run; do + grep -qx "$need" "$scratch/steps/order" || { echo "FAIL: the stage lane plans no $need step" >&2; exit 1; } +done +[ "$(grep -n -x verify-app-structure "$scratch/steps/order" | cut -d: -f1)" -lt "$(grep -n -x build-app "$scratch/steps/order" | cut -d: -f1)" ] \ + || { echo "FAIL: the structure check is planned after the build" >&2; exit 1; } +# The `use:` steps set up the runner's toolchain; here it is this machine's, +# so it must be the one the component asks for. +node_major="$(node -p 'process.versions.node.split(".")[0]')" +[ "$node_major" = "$(cat "$scratch/steps/node")" ] || { echo "FAIL: node $node_major here, the lane sets up $(cat "$scratch/steps/node")" >&2; exit 1; } +[ "$(pnpm --version)" = "$(cat "$scratch/steps/pnpm")" ] || { echo "FAIL: pnpm $(pnpm --version) here, the lane sets up $(cat "$scratch/steps/pnpm")" >&2; exit 1; } +echo " setup-node $node_major and setup-pnpm $(pnpm --version) stand in for the lane's \`use:\` steps" +echo " the WordPress URL's ref is optional and unstored: the lane builds with none" + +# The job's private tree, staged as orun stages it, from a source checkout +# with no build output (a CI checkout has none, so step 1's is removed rather +# than copied in) and the dependencies the pinned composition says: a +# lane-scoped install ran once in the source tree (step 1 ran the same +# command) and is linked in, or the job installs its own. +rm -rf "$tree/apps/web/.next" "$tree/apps/web/.open-next" "$tree/apps/web/.wrangler" "$tree/tests/web/coverage" +work="$tree/.orun/runs/e2e/web.stage.verify-deploy/work" +install_scope="$(cat "$scratch/steps/install-workspace-dependencies.scope" 2>/dev/null || echo job)" +if [ "$install_scope" = lane ]; then + python3 "$here/lib/stage-job.py" "$tree" "$work" --shared-deps + [ -L "$work/node_modules" ] || { echo "FAIL: the staged tree's node_modules is not the lane's symlink" >&2; exit 1; } +else + python3 "$here/lib/stage-job.py" "$tree" "$work" + [ ! -e "$work/node_modules" ] || { echo "FAIL: the staged tree carries node_modules it should install" >&2; exit 1; } +fi +for built in apps/web/.next apps/web/.open-next apps/web/.wrangler; do + [ ! -e "$work/$built" ] || { echo "FAIL: the staged tree carries build output ($built)" >&2; exit 1; } +done +echo " staged: $(realpath --relative-to="$tree" "$work"); install scope: $install_scope; no build output" + +while IFS= read -r step; do + [ -n "$step" ] || continue + if [ "$step" = install-workspace-dependencies ] && [ "$install_scope" = lane ]; then + echo " · $step (lane-scoped: ran once in the source tree)"; continue + fi + echo " ▸ $step" + # The runner's per-job environment: the job's env (intent environment + # `env:`) and ORUN_ENVIRONMENT; the step runs in the component's directory. + if ! (cd "$work/$(cat "$scratch/steps/path")/$(cat "$scratch/steps/$step.wd")" && \ + { [ -f "$scratch/steps/env" ] && source "$scratch/steps/env"; true; } && \ + export ORUN_ENVIRONMENT=stage && bash -e "$scratch/steps/$step.sh") > "$scratch/$step.log" 2>&1; then + echo "FAIL: the stage lane's $step step" >&2; tail -40 "$scratch/$step.log" >&2; exit 1 + fi +done < "$scratch/steps/order" +[ "$install_scope" = lane ] || { [ -d "$work/node_modules" ] && [ ! -L "$work/node_modules" ]; } \ + || { echo "FAIL: the job's install did not land inside its own tree" >&2; exit 1; } +# The build this site is verified with: Turbopack (a webpack build would get +# past an out-of-tree symlink and is not the build that deploys). +grep -q '(Turbopack)' "$scratch/build-app.log" \ + || { echo "FAIL: the staged build did not run on Turbopack" >&2; grep -m3 'Next.js' "$scratch/build-app.log" >&2; exit 1; } +grep -q -- "--name \"\${EFFECTIVE_WORKER_NAME}\"" "$scratch/steps/deploy-dry-run.sh" && grep -q "$repo-web-stage" "$scratch/steps/deploy-dry-run.sh" \ + || { echo "FAIL: the dry run does not name the Worker $repo-web-stage" >&2; exit 1; } +grep -q 'Total Upload' "$scratch/deploy-dry-run.log" \ + || { echo "FAIL: the dry run bundled nothing" >&2; tail -20 "$scratch/deploy-dry-run.log" >&2; exit 1; } +echo " the staged build ran on Turbopack; the dry run bundled $repo-web-stage ($(grep -m1 -o 'Total Upload: .*' "$scratch/deploy-dry-run.log"))" + +# ── 3. serve it, and smoke it as the deploy does ─────────────────────────── +echo "── wrangler dev over the staged Worker, no WordPress, no webhook secret" +port="$(free_port)"; iport="$(free_port)" +# setsid without its own fork: the subshell is not a group leader, so the +# pid recorded IS the new process group's. +(cd "$work/apps/web" && exec setsid pnpm exec wrangler dev --config wrangler.jsonc --name "$repo-web-stage" \ + --ip 127.0.0.1 --port "$port" --inspector-port "$iport" --show-interactive-dev-session=false) \ + > "$scratch/dev.log" 2>&1 < /dev/null & +dev_pid=$! +url="http://127.0.0.1:$port" +for _ in $(seq 1 120); do + curl -s -o /dev/null "$url/favicon.ico" && break + kill -0 "$dev_pid" 2>/dev/null || { echo "FAIL: wrangler dev exited" >&2; tail -30 "$scratch/dev.log" >&2; exit 1; } + sleep 1 +done +curl -s -o /dev/null "$url/favicon.ico" || { echo "FAIL: wrangler dev never answered" >&2; tail -30 "$scratch/dev.log" >&2; exit 1; } + +smoke="$(python3 -c "import yaml,sys;print(yaml.safe_load(open(sys.argv[1]))['spec']['parameters']['smokeCommand'])" "$tree/apps/web/component.yaml")" +echo " ▸ the component's own smokeCommand, verbatim, DEPLOYED_URL=$url" +DEPLOYED_URL="$url" bash -c "$smoke" || { echo "FAIL: the deploy's smoke refused the site" >&2; exit 1; } +if DEPLOYED_URL="$url/no-such-site" bash -c "$smoke" 2>/dev/null; then + echo "FAIL: the smoke passed against a path that is not the site — it checks nothing" >&2; exit 1 +fi +echo " ▸ …and it refuses what is not the site" + +(cd "$tree" && orun plan --intent intent.yaml --trigger github-push-main --changed \ + --base "$s00" --head "$s01" --env stage --output "$scratch/plan-push.json") > "$scratch/plan-push.log" 2>&1 \ + || { echo "FAIL: orun plan (push to main)" >&2; tail -15 "$scratch/plan-push.log" >&2; exit 1; } +python3 - "$scratch/plan-push.json" "$scratch/smoke-step.sh" "https://$repo-web-stage.$sub.workers.dev" <<'PY' +import json, sys +plan, out, origin = json.load(open(sys.argv[1])), sys.argv[2], sys.argv[3] +job = next(j for j in plan["jobs"] if j["component"] == "web" and j["environment"] == "stage") +assert job["profile"].endswith(".deploy"), job["profile"] +run = next(s for s in job["steps"] if s["id"] == "smoke")["run"] +# The one thing offline cannot reach is workers.dev: the step derives its URL +# from the Worker's name and the account's subdomain, so that line — and only +# that line — is pointed at the local Worker, after checking it is this site's. +line = 'export DEPLOYED_URL="https://${EFFECTIVE_WORKER_NAME}.${WORKERS_DEV_SUBDOMAIN}.workers.dev"' +if line not in run or 'EFFECTIVE_WORKER_NAME="' + origin.split("//")[1].split(".")[0] + '"' not in run: + sys.exit(f"FAIL: the planned smoke step does not derive {origin}:\n{run}") +open(out, "w").write(run.replace(line, 'export DEPLOYED_URL="${E2E_LOCAL_URL}"')) +PY +echo " ▸ the deploy profile's planned smoke step (its retry loop around the same command), on the local Worker" +(E2E_LOCAL_URL="$url" bash "$scratch/smoke-step.sh") > "$scratch/smoke-step.log" 2>&1 \ + || { echo "FAIL: the planned smoke step refused the site" >&2; tail -20 "$scratch/smoke-step.log" >&2; exit 1; } + +echo " ▸ every route the site promises" +python3 - "$url" "$values" <<'PY' +import html, json, re, sys, urllib.error, urllib.request +base, values = sys.argv[1], json.load(open(sys.argv[2])) +name = values["productname"] +# The staged lane built for stage: every absolute link is the stage Worker's. +origin = f"https://{values['reponame']}-web-stage.{values['subdomain']}.workers.dev" +problems = [] +def bad(m): problems.append(m) +class NoRedirect(urllib.request.HTTPRedirectHandler): + def redirect_request(self, *a, **k): + return None +opener = urllib.request.build_opener(NoRedirect) +def get(path, method="GET", data=None, headers=None): + req = urllib.request.Request(base + path, data=data, method=method, headers=headers or {}) + try: + with opener.open(req, timeout=60) as r: + return r.status, r.headers.get("content-type", ""), r.read() + except urllib.error.HTTPError as e: + return e.code, e.headers.get("content-type", ""), e.read() +def text(fragment): + return " ".join(html.unescape(re.sub(r"|<[^>]+>", "", fragment)).split()) +def title(page): + m = re.search(r"(.*?)", page, re.S) + return html.unescape(m.group(1)) if m else None +def page_of(path): + s, ctype, body = get(path) + if s != 200 or not ctype.startswith("text/html"): + bad(f"{path} answered {s} {ctype}") + return body.decode() +def body_of(page): + # The page without the notice, which links the first sample post from + # every page: what remains is what the page itself lists. + return re.sub(r']*data-wordpress="unconnected".*?', "", page, flags=re.S) +def count(page): + m = re.search(r"(\d+)(?:)?\s*(?:)?posts?(?:)? found", page) + return int(m.group(1)) if m else None +NOTICE = 'data-wordpress="unconnected"' +POSTS = {"connect-your-wordpress-site": "Connect your WordPress site", + "how-the-site-reads-wordpress": "How the site reads WordPress", + "hello-world": "Hello world!"} + +# The home page: the site's own name, the notice, and the template's credit. +page = page_of("/") +if title(page) != name: + bad(f"the home page's is {title(page)!r}, not {name!r}") +nav = re.search(r'<h2 class="text-sm">(.*?)</h2>', page, re.S) +if not nav or text(nav.group(1)) != name: + bad(f"the nav names the site {nav and text(nav.group(1))!r}, not {name!r}") +if NOTICE not in page or 'href="/posts/connect-your-wordpress-site"' not in page: + bad("the home page does not say the site is unconnected, or where to connect it") +if 'href="https://github.com/9d8dev/next-wp"' not in page: + bad("the home page's credit to the upstream template is gone or rewritten") + +# The posts page: the count, every sample post, the filters and the search, +# answered as the REST API would answer them. +page = page_of("/posts") +if count(page) != 3: + bad(f"/posts counts {count(page)} posts, not the 3 samples") +links = set(re.findall(r'href="/posts/([^"/?]+)"', body_of(page))) +if not set(POSTS) <= links: + bad(f"/posts links {sorted(links)}, missing samples {sorted(set(POSTS) - links)}") +if NOTICE not in page: + bad("/posts does not carry the unconnected notice") +for query, want, slugs in (("?category=2", 1, {"how-the-site-reads-wordpress"}), + ("?tag=3", 2, {"connect-your-wordpress-site", "hello-world"}), + ("?author=1", 3, set(POSTS)), + ("?search=hello", 1, {"hello-world"})): + p = page_of("/posts" + query) + shown = set(re.findall(r'href="/posts/([^"/?]+)"', body_of(p))) & set(POSTS) + if count(p) != want or shown != slugs: + bad(f"/posts{query} shows {count(p)} post(s) {sorted(shown)}, want {want} {sorted(slugs)}") +if "matching your search" not in text(page_of("/posts?search=hello")): + bad("/posts?search= does not say it is a search") + +# Each sample post, with the notice and absolute links for the stage origin. +for slug, post_title in POSTS.items(): + p = page_of(f"/posts/{slug}") + h1 = re.search(r"<h1[^>]*>(.*?)</h1>", p, re.S) + if not h1 or text(h1.group(1)) != post_title: + bad(f"/posts/{slug}'s heading is {h1 and text(h1.group(1))!r}, not {post_title!r}") + if title(p) != post_title: + bad(f"/posts/{slug}'s <title> is {title(p)!r}, not {post_title!r}") + if NOTICE not in p: + bad(f"/posts/{slug} does not carry the unconnected notice") + if f'content="{origin}/api/og?title=' not in p or f'content="{origin}/posts/{slug}"' not in p: + bad(f"/posts/{slug}'s Open Graph links are not the stage origin's ({origin})") +p = page_of("/posts/connect-your-wordpress-site") +for words in ("WORDPRESS_URL", "WORDPRESS_WEBHOOK_SECRET", "/api/revalidate", "orun secrets set"): + if words not in p: + bad(f"the connect post does not mention {words}") + +# The sample page, and the archive lists. +if 'href="/pages/about"' not in page_of("/pages"): + bad("/pages does not list the sample page") +p = page_of("/pages/about") +if not re.search(r"<h2[^>]*>About</h2>", p): + bad("/pages/about does not render the sample page") +for path, words in (("/posts/categories", ("Getting started", "Guides", 'href="/posts?category=1"')), + ("/posts/tags", ("WordPress", "Next.js", "Cloudflare")), + ("/posts/authors", ("The editor",))): + p = page_of(path) + for w in words: + if w not in p: + bad(f"{path} does not list {w}") + +# Not there: an unknown post, page and path — and /admin, which redirects to +# wp-admin only once a WordPress is connected. +for path in ("/posts/no-such-post", "/pages/no-such-page", "/no-such-page", "/admin"): + s, _, _ = get(path) + if s != 404: + bad(f"{path} answered {s}, want 404") + +# The sitemap and robots, per request; the Open Graph image, rendered by the Worker. +s, ctype, body = get("/sitemap.xml") +if s != 200 or "xml" not in ctype or f"<loc>{origin}/posts/hello-world</loc>" not in body.decode(): + bad(f"/sitemap.xml answered {s} {ctype} without the sample posts under {origin}") +s, ctype, _ = get("/robots.txt") +if s != 200 or not ctype.startswith("text/plain"): + bad(f"/robots.txt answered {s} {ctype}") +s, ctype, body = get("/api/og?title=Hello&description=World") +if s != 200 or ctype != "image/png" or not body.startswith(b"\x89PNG"): + bad(f"/api/og answered {s} {ctype} — not a PNG") + +# Static assets, served by the Worker's ASSETS binding. +s, ctype, _ = get("/favicon.ico") +if s != 200 or not ctype.startswith("image/"): + bad(f"/favicon.ico answered {s} {ctype}") +chunk = re.search(r'src="(/_next/static/[^"]+\.js)"', page_of("/")) +if not chunk: + bad("the home page loads no script from /_next/static") +else: + s, ctype, _ = get(chunk.group(1)) + if s != 200 or "javascript" not in ctype: + bad(f"{chunk.group(1)} answered {s} {ctype}") + +# THE ROUTE ONLY THE WORKER ANSWERS: the revalidation webhook. With no +# secret set, every request is refused — never a 500, never a revalidation. +for hdrs in ({}, {"x-webhook-secret": "guess"}): + s, _, body = get("/api/revalidate", "POST", json.dumps({"contentType": "post"}).encode(), + {"content-type": "application/json", **hdrs}) + if s != 401 or b"Invalid webhook secret" not in body: + bad(f"/api/revalidate with {hdrs or 'no secret'} answered {s} {body[:80]!r}, want 401") +s, _, _ = get("/api/revalidate") +if s != 405: + bad(f"GET /api/revalidate answered {s}, want 405") + +if problems: + for p in problems: + print(f" ✕ {p}", file=sys.stderr) + sys.exit(1) +print(f" /, /posts (its count, filters and search), the three sample posts, /pages and the sample page,") +print(f" the category, tag and author lists, four 404s, the sitemap, the OG image, the static assets") +print(f" and the webhook's 401 — the site's own, named {name!r}, on {origin}, unconnected and saying so") +PY + +echo "e2e.test.sh: ok" diff --git a/testing/fixtures/acme.json b/testing/fixtures/acme.json new file mode 100644 index 0000000..621229d --- /dev/null +++ b/testing/fixtures/acme.json @@ -0,0 +1,25 @@ +{ + "_comment": [ + "The inputs the placement, leak and end-to-end gates render with. Acme is", + "not a real site and never becomes one: this tree is placed into a temp", + "directory, asserted against, and deleted. The values are chosen to be", + "AWKWARD rather than tidy — a site name with an apostrophe and an", + "ampersand (both legal in the card's pattern, both special in HTML,", + "TypeScript strings, shell words and JSON), a hyphenated repo slug that", + "ENDS in the baseline's own slug (so its Worker is `<…>-cms-wordpress-web`),", + "an owner other than the baseline's, and NO domain — a console build asks", + "for none, so the placeholder <reponame>.example.com is what a site is", + "born with, and this slug's placeholder CONTAINS the baseline's own", + "placeholder domain — because a fixture that only uses values the", + "templates were written against proves the templates work on the values", + "they were written against.", + "Every key here is an input repo-blueprint.yaml declares. A key it does not", + "declare is a fixture that has drifted, and orun refuses it." + ], + "reponame": "acme-cms-wordpress", + "productname": "Sam's Notes & Links", + "githuborg": "acme-inc", + "subdomain": "acme", + "orunWorkspace": "ws_0000000000000000000000000000000f", + "epicSlug": "cms-wordpress-baselining" +} diff --git a/testing/fixtures/baseline-identity.cms-wordpress.json b/testing/fixtures/baseline-identity.cms-wordpress.json new file mode 100644 index 0000000..673baa9 --- /dev/null +++ b/testing/fixtures/baseline-identity.cms-wordpress.json @@ -0,0 +1,9 @@ +{ + "_comment": "THE IDENTITY testing/rebrand.test.sh PINS ITS FIXTURES TO. That suite tests the rename ENGINE, and its fixtures spell this baseline's identity out literally; passed as --baseline-identity, a later change to .baseline/identity.json (a baseline promoted under a new name) cannot silently turn every case into a comparison against the wrong FROM side.", + "slug": "cms-wordpress", + "pascal": "CmsWordpress", + "productName": "next-wp", + "domain": "cms-wordpress.example.com", + "subdomain": "your-workers-subdomain", + "githubOwner": "sourceplane" +} diff --git a/testing/leak.test.sh b/testing/leak.test.sh new file mode 100755 index 0000000..79c66f7 --- /dev/null +++ b/testing/leak.test.sh @@ -0,0 +1,174 @@ +#!/usr/bin/env bash +# THE LEAK GATE — what a site carries, and what stays in the factory. +# +# A site built from this baseline is somebody's site, not a copy of this +# repository. It gets the product: the app, its tests, its CI, its tooling, +# its README and its two context pages. It does NOT get the factory: +# the blueprints, the bootstrap and rebrand tooling, the test gates, the task +# contracts and identity under `.baseline/`, this repository's own epic and +# task tree, or BOOTSTRAP.md. +# +# This asks orun to DERIVE the placement — every file every phase would write +# — and gates that set: which paths ship, and what the shipped files SAY. A +# product-facing file never names a factory path (`repo-blueprint`, +# `testing/`, `specs/`, `tasks/`, `.baseline/`, …): the product has none of +# them, so a comment or a doc pointing there points at nothing. intent.yaml is +# read as 01-product lands it, after `work-tree.mjs --strip` removed the +# baseline's own `work:` block. Derivation runs no hooks, contacts nothing and +# writes nothing. testing/placement.test.sh gates the same rules over a tree +# that is actually placed and branded. +# +# Needs: orun + node + python3. No network, no credential. +set -euo pipefail +here="$(cd "$(dirname "$0")" && pwd)" +root="$(cd "$here/.." && pwd)" + +command -v orun >/dev/null || { echo "leak.test.sh needs orun on PATH" >&2; exit 1; } + +scratch="$(mktemp -d)" +trap 'rm -rf "$scratch"' EXIT + +echo "── deriving what every phase would place" +sets=() +while IFS=$'\t' read -r k v; do sets+=( --set "$k=$v" ); done < <( + python3 - "$here/fixtures/acme.json" <<'PY' +import json, sys +for k, v in json.load(open(sys.argv[1])).items(): + if not k.startswith("_"): + print(f"{k}\t{'true' if v is True else 'false' if v is False else v}") +PY +) +orun new --blueprint "$root/repo-blueprint.yaml" --status --json \ + --out "$scratch/empty" "${sets[@]}" > "$scratch/status.json" + +# intent.yaml as the product lands it: the work-tree strip is a 01-product +# hook, so the block it removes never reaches a product. +cp "$root/intent.yaml" "$scratch/intent.yaml" +node "$root/tooling/bootstrap/work-tree.mjs" --strip --file "$scratch/intent.yaml" >/dev/null + +python3 - "$scratch/status.json" "$root" "$scratch/intent.yaml" <<'PY' +import json, pathlib, re, sys +import yaml + +status = json.load(open(sys.argv[1])) +root = pathlib.Path(sys.argv[2]) +landed_intent = pathlib.Path(sys.argv[3]) +problems = [] +def bad(m): problems.append(m) + +# Against an empty output directory every file a phase places is "missing", so +# the union of those lists IS the site's file set. +placed = sorted({f for ph in status["phases"] for f in (ph.get("missing") or [])}) +if len(placed) < 50: + sys.exit(f"only {len(placed)} files derived — the tree is not a site") + +# ── the context pack, exactly ───────────────────────────────────────────── +ALLOWED_AI = {"ai/context/deployment.md", "ai/context/operations.md"} +shipped_ai = {p for p in placed if p.startswith("ai/")} +for extra in sorted(shipped_ai - ALLOWED_AI): + bad(f"{extra} ships to the site and is this repository's own state") +for missing in sorted(ALLOWED_AI - shipped_ai): + bad(f"{missing} is declared a product file and would not ship") + +# ── the factory never ships ─────────────────────────────────────────────── +NEVER = (".baseline/", "specs/", "tasks/", "testing/", "hooks/", "docs/phases/", + "tooling/rebrand/", "tooling/bootstrap/", ".github/workflows/baseline.yml", + ".github/workflows/tag.yml", "BOOTSTRAP.md", "repo-blueprint.yaml", + "blueprint.yaml", "flows/", "agents/") +for p in placed: + for never in NEVER: + if p == never or p.startswith(never): + bad(f"{p} would ship — it is the factory, not the site") + +# ── nothing local and nothing built ─────────────────────────────────────── +# `.dev.vars.example` is the one `.dev.vars.*` that ships: the template an +# owner copies for `wrangler dev`, holding no value. +LOCAL = re.compile(r"(^|/)(\.env(\.[^/]*\.local|\.local)?|\.dev\.vars(\.(?!example$)[^/]*)?|node_modules|\.next|" + r"\.open-next|\.wrangler|\.turbo|\.orun|dist|next-env\.d\.ts|[^/]*\.tsbuildinfo)(/|$)") +for p in placed: + if LOCAL.search(p): + bad(f"{p} would ship — a local or built file of whoever ran the bootstrap") + +# ── the site's README, not this repository's ────────────────────────────── +if "README.md" not in placed: + bad("README.md would not ship") +for must in (".github/workflows/ci.yml", + "apps/web/component.yaml", "apps/web/wrangler.jsonc", "apps/web/site.config.ts", + "apps/web/lib/wordpress.ts", "apps/web/lib/wordpress.d.ts", "apps/web/lib/sample.ts", + "apps/web/components/unconnected-notice.tsx", "apps/web/app/api/revalidate/route.ts", + "apps/web/open-next.config.ts", "apps/web/types/images.d.ts", "apps/web/LICENSE", + "apps/web/.env.example", "apps/web/.dev.vars.example", + "tests/web/component.yaml", "tests/web/src/unconnected.test.ts", + "tooling/wire/render.mjs", "tooling/wire/live.mjs", ".rebrand/values.json", + "pnpm-lock.yaml", "packages/.gitkeep", "infra/.gitkeep"): + if must not in placed: + bad(f"{must} would not ship, and a site needs it") + +# ── WHAT EVERY SHIPPED FILE SAYS ────────────────────────────────────────── +# Each placed path, read from the source the module copies it from (or the +# template that writes it), and searched for the factory's paths. +bp = yaml.safe_load((root / "repo-blueprint.yaml").read_text()) +def source_of(path): + if path == "intent.yaml": + return landed_intent.read_text() + for m in bp.get("modules") or []: + if m.get("mode") == "template": + files = m.get("files") or {} + if path in files: + return files[path] + continue + frm, to = (m.get("from") or "").rstrip("/"), (m.get("to") or "").rstrip("/") + if path == to: + return (root / frm).read_text(errors="replace") + if path.startswith(to + "/"): + return (root / frm / path[len(to) + 1:]).read_text(errors="replace") + return None + +FACTORY = re.compile( + r"repo-blueprint|BOOTSTRAP\.md|(?<![\w.-])(testing|specs|tasks|docs/phases|hooks)/" + r"|\.baseline/|tooling/(rebrand|bootstrap)/") +read = 0 +for p in placed: + text = source_of(p) + if text is None: + bad(f"{p} is derived but no module of repo-blueprint.yaml says where it comes from") + continue + read += 1 + if p == "pnpm-lock.yaml": + continue # resolver output: package paths, not prose + for n, line in enumerate(text.splitlines(), 1): + m = FACTORY.search(line) + if m: + bad(f"{p}:{n} names the factory path {m.group(0)!r}, which no product has: {line.strip()[:90]}") + +# ── PROVENANCE, which rebrand has no rule for ───────────────────────────── +# Not a search for this baseline's name: the rebrand rewrites that, and this +# gate reads the sources before it runs. What the rebrand cannot rewrite is a +# sentence about where the site CAME FROM, or one about being a baseline. +PROVENANCE = re.compile( + r"\bfork(ed)? (of|from)\b|\bbaseline (repo|repository|commit|tag)\b|\bthis baseline\b", + re.I, +) +for p in placed: + if not re.search(r"\.(md|ts|tsx|js|mjs|json|jsonc|ya?ml)$", p) or p == "pnpm-lock.yaml": + continue + text = source_of(p) or "" + if p == "intent.yaml": + text = landed_intent.read_text() + for n, line in enumerate(text.splitlines(), 1): + if PROVENANCE.search(line): + bad(f"{p}:{n} tells the site about the factory: {line.strip()[:80]}") + +if problems: + print("FAIL: the site would carry the baseline:", file=sys.stderr) + for p in problems: + print(f" - {p}", file=sys.stderr) + sys.exit(1) + +print(f" {len(placed)} files derived across every phase, {read} read") +print(f" ai/context is exactly {len(ALLOWED_AI)} declared file(s); none of the " + f"{len(NEVER)} factory paths ship, and no shipped file names one; nothing " + f"local or built; no provenance prose") +PY + +echo "leak.test.sh: ok" diff --git a/testing/lib/bootstrap.sh b/testing/lib/bootstrap.sh new file mode 100755 index 0000000..e0b123a --- /dev/null +++ b/testing/lib/bootstrap.sh @@ -0,0 +1,69 @@ +#!/usr/bin/env bash +# The offline bootstrap: every phase of repo-blueprint.yaml, placed by orun and +# finished by the blueprint's own `run:` hooks, in order, the way a real +# `orun new --run-hooks --resume` takes a site from nothing to its last +# landing — minus the platform. Sourced by placement.test.sh and e2e.test.sh. +# +# bootstrap_offline <root> <tree> <values.json> <log-dir> [until-phase] +# +# What stands in for the platform: +# - the typed actions (`uses:` — task, repo, reconcile, land, watch, probe) +# are skipped; a landing becomes a commit on `main`, which is what the +# next phase's placement sees on the real thing too; +# - the repository's first commit is orun's empty `Initial commit`, which +# seeds an empty repository so the first landing's pull request has a +# base — and so the push that merges 01-product has a `before` its +# convergence plans `--changed` against; +# - `link` (a `run:` hook that calls `orun cloud`) is skipped — it needs a +# workspace; +# - `{{ .inputs.* }}` render from the fixture. +# Everything else — the rebrand, the re-tenant, the work-tree strip, the +# deferrals and their restore, the retouch marker, the deployment-docs +# render — runs exactly as declared. +# +# Needs: orun, node, pnpm, python3 (+PyYAML), git. + +bootstrap_offline() { + local root="$1" tree="$2" values="$3" logs="$4" until="${5:-}" + local sets=() k v phase + while IFS=$'\t' read -r k v; do sets+=( --set "$k=$v" ); done < <( + python3 - "$values" <<'PY' +import json, sys +for k, v in json.load(open(sys.argv[1])).items(): + if not k.startswith("_"): + print(f"{k}\t{'true' if v is True else 'false' if v is False else v}") +PY + ) + mkdir -p "$tree"/{apps,infra,packages,tests} "$logs" + for d in apps infra packages tests; do touch "$tree/$d/.gitkeep"; done + + for phase in $(python3 -c "import yaml,sys;print(' '.join(p['name'] for p in yaml.safe_load(open(sys.argv[1]))['phases']))" "$root/repo-blueprint.yaml"); do + echo "── $phase: place" + if ! orun new --blueprint "$root/repo-blueprint.yaml" --out "$tree" --phase "$phase" \ + "${sets[@]}" > "$logs/place-$phase.log" 2>&1; then + echo "FAIL: $phase did not place" >&2; tail -20 "$logs/place-$phase.log" >&2; return 1 + fi + echo "── $phase: post hooks" + if ! python3 "$root/testing/lib/run-hooks.py" "$root/repo-blueprint.yaml" "$phase" post \ + "$tree" "$root" "$values" --skip link > "$logs/hooks-$phase.log" 2>&1; then + echo "FAIL: $phase's post hooks" >&2; tail -30 "$logs/hooks-$phase.log" >&2; return 1 + fi + sed 's/^/ /' "$logs/hooks-$phase.log" + # The landing: what the PR merges is what the next phase is placed onto. + ( + cd "$tree" + git config user.email bootstrap@example.invalid + git config user.name "offline bootstrap" + if ! git rev-parse -q --verify HEAD >/dev/null; then + init="$(git commit-tree "$(git hash-object -w -t tree /dev/null)" -m "Initial commit")" + git update-ref refs/heads/main "$init" + git symbolic-ref HEAD refs/heads/main + fi + git checkout -q -B main 2>/dev/null || true + git add -A + git commit -q -m "land $phase" --allow-empty + ) || { echo "FAIL: $phase did not commit" >&2; return 1; } + [ "$phase" = "$until" ] && break + done + return 0 +} diff --git a/testing/lib/run-hooks.py b/testing/lib/run-hooks.py new file mode 100755 index 0000000..31a1ea3 --- /dev/null +++ b/testing/lib/run-hooks.py @@ -0,0 +1,72 @@ +#!/usr/bin/env python3 +"""Run one phase's `run:` hooks EXACTLY as repo-blueprint.yaml declares them. + + run-hooks.py <blueprint> <phase> <slot> <tree> <baseline-dir> <values.json> [--skip id,id] + +The offline bootstrap (testing/lib/bootstrap.sh) uses this so that what it +exercises is the blueprint's own hook list, not a transcription of it: a hook +added, removed or reordered in the blueprint is added, removed or reordered +here with no edit. Argv templates are rendered the way orun renders them for +the hooks this baseline uses — `{{ .baseline.dir }}`, `{{ .phase.name }}`, +`{{ .inputs.<key> }}` — and anything else left between braces is an error, so +a hook that starts using a template this cannot render fails loudly rather +than running with a literal `{{ … }}` in its argv. + +`uses:` hooks are the platform's typed actions (task, repo, land, watch, +probe, reconcile). They need a workspace and the network, and are reported as +skipped; the caller stands in for the ones whose effect the tree needs (a +landing is a commit). +""" +import json +import pathlib +import re +import subprocess +import sys + +import yaml + + +def main() -> int: + args = sys.argv[1:] + skip = set() + if "--skip" in args: + i = args.index("--skip") + skip = {s for s in args[i + 1].split(",") if s} + args = args[:i] + args[i + 2:] + blueprint, phase_name, slot, tree, baseline_dir, values_path = args + bp = yaml.safe_load(pathlib.Path(blueprint).read_text()) + phase = next((p for p in bp.get("phases") or [] if p.get("name") == phase_name), None) + if phase is None: + print(f"run-hooks: no phase {phase_name!r}", file=sys.stderr) + return 2 + inputs = {k: v for k, v in json.loads(pathlib.Path(values_path).read_text()).items() if not k.startswith("_")} + + def render(arg: str) -> str: + out = arg.replace("{{ .baseline.dir }}", baseline_dir).replace("{{ .phase.name }}", phase_name) + out = re.sub(r"\{\{ \.inputs\.([A-Za-z0-9_]+) \}\}", lambda m: str(inputs.get(m.group(1), "")), out) + if "{{" in out: + raise SystemExit(f"run-hooks: cannot render {arg!r} — a template this harness does not know") + return out + + for hook in ((phase.get("hooks") or {}).get(slot) or []): + hid = hook.get("id") + if "uses" in hook: + print(f" · {phase_name}/{slot}/{hid}: {hook['uses']} (platform action — skipped offline)") + continue + if hid in skip: + print(f" · {phase_name}/{slot}/{hid}: skipped by the caller") + continue + argv = [render(a) for a in hook.get("run") or []] + print(f" ▸ {phase_name}/{slot}/{hid}") + r = subprocess.run(argv, cwd=tree, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True) + for line in (r.stdout or "").splitlines()[-6:]: + print(f" {line}") + if r.returncode != 0: + print(f"run-hooks: {phase_name}/{slot}/{hid} exited {r.returncode}", file=sys.stderr) + print(r.stdout, file=sys.stderr) + return 1 + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/testing/lib/stage-job.py b/testing/lib/stage-job.py new file mode 100755 index 0000000..d2f9c9a --- /dev/null +++ b/testing/lib/stage-job.py @@ -0,0 +1,86 @@ +#!/usr/bin/env python3 +"""Stage a job's private tree the way orun's runner does. + + stage-job.py <source-tree> <work-dir> [--shared-deps] + +orun runs every job of a run in an isolated copy of the source checkout, +`.orun/runs/<exec>/<job>/work` (orun internal/runner/workspace.go, +`materializeTree`). What it does with installed dependencies depends on the +composition the component's lane runs: + + default the job installs them itself, so `node_modules` is left out + at every level and the job's install step recreates it + INSIDE the work tree (stack-tectonic < 0.20.0, or a + composition with no lane-scoped install); + --shared-deps a `scope: lane` install ran once in the source checkout + (stack-tectonic >= 0.20.0, orun >= 2.78.2): the TOP-LEVEL + `node_modules` is a SYMLINK to the source tree's, and every + nested one is COPIED with its pnpm symlinks intact — so they + resolve up through that link, OUT of the work tree. + +Either way `.git` and `.orun` are left out, and so are build outputs and +caches (.next, .nuxt, .turbo, .svelte-kit, dist, build, target, .venv, venv, +__pycache__, .terraform, .pytest_cache, .mypy_cache). + +Why a test builds here rather than in a plain checkout: the first live +bootstrap of portfolio-starter-kit (where this file comes from) died in the +--shared-deps layout — Next.js 16's Turbopack refuses a dependency that +resolves outside its project root ("Symlink … points out of the filesystem +root") — in a lane its e2e tier had run green over a plain checkout. This +site is the same Next.js 16 on Turbopack, so its lane is replayed the same +way: in the tree the runner stages, BEFORE any build output exists, which is +also where the composition's `verify-app-structure` step looks for the +committed wrangler.jsonc. +""" +import os +import shutil +import sys + +OUTPUT_DIRS = {".next", ".nuxt", ".turbo", ".svelte-kit", "dist", "build", "target", + ".venv", "venv", "__pycache__", ".terraform", ".pytest_cache", ".mypy_cache"} +SKIP = {".git", ".orun"} + + +def stage(src: str, dst: str, top: bool, shared_deps: bool) -> None: + os.makedirs(dst, exist_ok=True) + for entry in os.scandir(src): + name = entry.name + s, d = entry.path, os.path.join(dst, name) + if name in SKIP: + continue + if entry.is_symlink(): + os.symlink(os.readlink(s), d) + continue + if entry.is_dir(): + if name in OUTPUT_DIRS: + continue + if name == "node_modules": + if not shared_deps: + continue # the job installs its own + if top: + os.symlink(os.path.abspath(s), d) # the lane's one install + else: + shutil.copytree(s, d, symlinks=True) # copied, links intact + continue + stage(s, d, False, shared_deps) + continue + shutil.copy2(s, d) + + +def main() -> int: + args = sys.argv[1:] + shared = "--shared-deps" in args + paths = [a for a in args if a != "--shared-deps"] + if len(paths) != 2: + print("usage: stage-job.py <source-tree> <work-dir> [--shared-deps]", file=sys.stderr) + return 2 + src, dst = (os.path.abspath(p) for p in paths) + if os.path.exists(dst): + print(f"stage-job: {dst} exists", file=sys.stderr) + return 2 + stage(src, dst, True, shared) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/testing/manifest.test.sh b/testing/manifest.test.sh new file mode 100755 index 0000000..64f04c8 --- /dev/null +++ b/testing/manifest.test.sh @@ -0,0 +1,446 @@ +#!/usr/bin/env bash +# The manifest must state what THE BLUEPRINT does (saas-bootstrap-console +# BC2/BC3; repointed from the flows by saas-bootstrap-engine BE4). +# +# `blueprint.yaml` is the contract the platform's bootstrap door reads and the +# console renders screen for screen. A manifest that drifts is a console that +# lies — showing an operator secrets that will not be created, or a programme +# that will not be laid out, with nothing failing until a customer's build is +# already running. +# +# Every check compares the manifest to THE THING THAT DOES THE WORK, never to +# another copy of the same claim. `spec.source.tag` sat at `baseline-v1` against +# a live `baseline-v4` for three releases (and `baseline-v17` against +# `baseline-v27` in lumen — ten) because nothing compared it to anything that +# moved. A drift test between two files catches nothing. +# +# ## What the thing that does the work IS, now +# +# It used to be shell: `flows/common/create-secrets.sh`'s `create` calls, and +# the umbrella's `ensure-milestone` lines, grepped out of scripts. BE4 deleted +# those, and the work moved into `repo-blueprint.yaml` — so this file now reads +# the blueprint's own hooks. +# +# That is a STRONGER comparison, not a weaker one. Grepping a shell script for +# `create FOO cloudflare … workers-deploy` matched a line's shape; reading +# `orun.integrations/reconcile@v1`'s `with:` reads the declaration orun actually +# executes. The action's own documentation says as much — "a script walks that +# table calling create for each … it is a reconcile written out longhand, and +# this is the verb it was reaching for". +# +# TWO SHAPES OF REPO, one test. A repo may carry more than one baseline: stratus +# serves both the `stratus` and `stratus-coolify` registry rows from one tree. +# So every `blueprint*.yaml` at the root is checked. +# +# And a baseline need not have every mechanism. Stratus mints no secrets and +# lays out no milestones, so it declares neither block. That is allowed — but +# only BOTH-OR-NEITHER, checked in both directions: if the mechanism exists the +# block must match it, and if the block exists the mechanism must be there to +# realize it. "Absent" is never permission to skip a check silently; it is a +# fact that must agree with the other side. +# +# bash + python3 + PyYAML. No network, no fakes, no credential. +set -euo pipefail +here="$(cd "$(dirname "$0")" && pwd)" +root="$(cd "$here/.." && pwd)" + +echo "── blueprint manifests against the blueprint that realizes them" +python3 - "$root" <<'PY' +import pathlib, re, sys + +try: + import yaml +except ImportError: + sys.exit("PyYAML is required for the manifest contract test (pip install pyyaml)") + +root = pathlib.Path(sys.argv[1]) +problems = [] +def bad(m): problems.append(m) + +manifests = sorted(root.glob("blueprint*.yaml")) +if not manifests: + sys.exit("no blueprint*.yaml at the repo root — this check has gone blind") + +# ── what the blueprint actually mints, and what it actually lays out ────── +# +# One read of `repo-blueprint.yaml`, shared across a repo's baselines. A repo +# with no blueprint at the root has no mechanism to compare against, and that +# is a fact the both-or-neither rule below handles rather than a reason to skip. +bp_path = root / "repo-blueprint.yaml" +bp = yaml.safe_load(bp_path.read_text()) if bp_path.exists() else None +bp_phases = (bp or {}).get("phases") or [] + +def hooks_of(phase): + """Every hook a phase declares, in the order orun runs them.""" + h = phase.get("hooks") or {} + if isinstance(h, list): + return list(h) + return [x for slot in ("pre", "post", "await") for x in (h.get(slot) or [])] + +def uses(phase, action): + for hook in hooks_of(phase): + if (hook.get("uses") or "").startswith(action): + yield hook + +# THE SECRETS THE BOOTSTRAP MINTS. `orun.integrations/reconcile@v1` is what +# `create-secrets.sh` was written out longhand as: one connection, and per key +# the scope template it is minted under — `secrets: [{key, template}]`, or +# `keys` sharing one `template`. Read per key so a hook minting three keys is +# three facts rather than one. +blueprint_secrets = {} +for phase in bp_phases: + for hook in uses(phase, "orun.integrations/reconcile@v1"): + w = hook.get("with") or {} + for item in (w.get("secrets") or []): + blueprint_secrets[item.get("key")] = (w.get("provider"), item.get("template")) + for key in (w.get("keys") or []): + blueprint_secrets[key] = (w.get("provider"), w.get("template")) + +if bp is not None and not bp_phases: + bad("repo-blueprint.yaml declares no phases — this check has gone blind") + +checked = [] +for path in manifests: + name = path.name + spec = (yaml.safe_load(path.read_text()) or {}).get("spec") or {} + def B(m): bad(f"{name}: {m}") + + # ── the field that cannot be true ───────────────────────────────────── + if "tag" in (spec.get("source") or {}): + B("spec.source.tag is back. The registry pins the tag; this file is fetched at it.") + + # ── blocks every baseline must carry ────────────────────────────────── + for key in ("source", "overview", "requires", "inputs", "bootstrap"): + if key not in spec: + B(f"spec.{key} is missing — the console renders it") + + # ── inputs v3: every input is collected by the console (BE3) ────────── + # + # `askedBy` is gone with the agent. It split inputs into ones a form + # collects and ones asked for in a session, and the second half no longer + # exists — so the field could only ever hold one value. + # + # The exemption it carried is what these checks replace: an `askedBy: + # agent` input needed no `pattern`, because prose asked for it and prose + # does not validate. + input_keys = {f.get("key") for f in (spec.get("inputs") or [])} + ACTION_ID = re.compile(r"^[a-z][a-z0-9.]*/[a-z][a-z0-9-]*@v[0-9]+$") + REBRAND = "tooling/rebrand/rebrand.mjs" + # THE KEY CHARSET THE PLATFORM'S PARSER ENFORCES, mirrored here. + # + # `INPUT_KEY_RE = /^[a-z][a-z0-9_]{0,38}$/` in orun-cloud's + # `blueprint-manifest.ts`. Nothing in this repository ran that parser: the + # `blueprint-parses` job reads `repo-blueprint.yaml` with ORUN, which + # accepts camelCase happily, and this file is a hand-rolled reader of the + # card. So a card key orun likes and the platform refuses passed every + # check here and failed at the pin: + # + # line 98: input key "githubOrg" must be lowercase letters, digits + # and underscores + # + # It cost a baseline tag — v6 was already cut and a baseline tag is never + # moved — which is the whole argument for mirroring the rule rather than + # trusting that the two readers agree. + # + # It also constrains `repo-blueprint.yaml`: a card key must be an input the + # blueprint accepts (checked below), so any input the CARD declares must be + # named in this charset on BOTH sides. The blueprint's own camelCase + # inputs — `epicSlug`, `orunWorkspace`, `pascalName` — are untouched, + # because the card does not declare them. + INPUT_KEY = re.compile(r"^[a-z][a-z0-9_]{0,38}$") + for i, field in enumerate(spec.get("inputs") or []): + key = field.get("key", f"#{i}") + if not INPUT_KEY.match(str(key)): + B(f"inputs[{key}] is not a key the platform's parser accepts — it " + f"must match ^[a-z][a-z0-9_]{{0,38}}$ (lowercase letters, digits " + f"and underscores). The console would refuse the whole manifest.") + if "askedBy" in field: + B(f"inputs[{key}] declares askedBy — there is no agent to ask, so " + f"every input is collected by the console") + if not field.get("pattern"): + B(f"inputs[{key}] declares no pattern — it is collected in a form " + f"and validated before Continue, so it must say what a valid " + f"value looks like") + + # from / derive / probe each answer "where does this value come from + # when nobody types it". Two of them is two answers. + sources = [k for k in ("from", "derive", "probe") if k in field] + if len(sources) > 1: + B(f"inputs[{key}] declares {' and '.join(sources)} — an input has " + f"one source") + + # A derivation must name inputs this manifest actually declares. + derive = field.get("derive") + if derive is not None: + refs = re.findall(r"\{([a-z][a-z0-9_]*)\}", derive) + if not refs: + B(f"inputs[{key}].derive has no {{key}} reference — a constant " + f"is a default, not a derivation") + for ref in refs: + if ref == key: + B(f"inputs[{key}].derive references itself") + elif ref not in input_keys: + B(f"inputs[{key}].derive references {{{ref}}}, which is not " + f"a declared input") + + # A DERIVATION HAS A SECOND IMPLEMENTATION, and they must agree. + # + # `rebrand.mjs` has computed this value since long before the manifest + # could say so: + # + # const apibaseurl = values.apibaseurl ?? `https://api.${productdomain}`; + # + # Both paths are live. The console resolves `derive` and the flow hands + # it down, so on a console bootstrap the manifest's rule wins; a phase + # run by hand passes nothing and rebrand's fallback wins. One rule, two + # implementations — which is the thing this file's header warns about, + # unless something holds them equal. This does. + if derive is not None and (root / REBRAND).exists(): + js = (root / REBRAND).read_text(errors="replace") + for m in re.finditer(r"const (\w+) = values\.\w+ \?\? `([^`]+)`", js): + # `${productdomain}` there is `{productdomain}` here. + want = re.sub(r"\$\{([A-Za-z]+)\}", lambda g: "{" + g.group(1).lower() + "}", m.group(2)) + if m.group(1).lower() == key and want != derive: + B(f"inputs[{key}].derive is {derive!r} and {REBRAND} falls back " + f"to {want!r} — one value, two rules, and which one a " + f"product gets depends on whether the console resolved it") + + # A probe names an orun action. Shape only — this repository does not + # own the registry and cannot know which ids a runner has. The id being + # WELL-FORMED is what it can check; whether it is REGISTERED is the + # runner's answer, at parse time, where the real list lives. + probe = field.get("probe") + if probe is not None: + uses = (probe or {}).get("uses") + if not uses or not ACTION_ID.match(uses): + B(f"inputs[{key}].probe.uses is {uses!r} — not an action id " + f"(<namespace>/<verb>@v<major>)") + + # `from` says the CONSOLE already holds this value, so it renders no + # field for it (saas-bootstrap-console BC-K5). Two ways to get it + # wrong, and the platform refuses both — check them here too, so the + # mistake is caught in this repo rather than at a live bootstrap. + # + # A `connection.<provider>.<fact>` source is read from the connection + # the build is bound to, so the provider must be one the manifest + # requires — the platform's parser refuses it otherwise. + sources_known = ("repo.name", "repo.owner", "repo.fullName", + "connection.cloudflare.workersSubdomain") + src = field.get("from") + if src is not None and src not in sources_known: + B(f"inputs[{key}].from is {src!r} — must be one of {', '.join(sources_known)}") + if isinstance(src, str) and src.startswith("connection."): + provider = src.split(".")[1] + if provider not in ((spec.get("requires") or {}).get("integrations") or []): + B(f"inputs[{key}].from is {src!r} but spec.requires.integrations " + f"does not list {provider} — there is no connection to read it from") + + # ── secrets: BOTH or NEITHER, checked both ways ─────────────────────── + declared = {s.get("key"): (s.get("provider"), s.get("template")) for s in (spec.get("secrets") or [])} + if bp is None: + if declared: + B(f"declares {len(declared)} secret(s) but the repo has no " + f"repo-blueprint.yaml to mint them") + elif not blueprint_secrets: + if declared: + B(f"declares {len(declared)} secret(s) and repo-blueprint.yaml has no " + f"orun.integrations/reconcile@v1 hook to mint any") + else: + if "secrets" not in spec: + B("repo-blueprint.yaml mints keys and the manifest declares no secrets") + for k in sorted(set(blueprint_secrets) - set(declared)): + B(f"repo-blueprint.yaml mints {k} and the manifest does not declare it") + for k in sorted(set(declared) - set(blueprint_secrets)): + B(f"declares secret {k} and repo-blueprint.yaml never mints it") + for k in sorted(set(blueprint_secrets) & set(declared)): + if blueprint_secrets[k] != declared[k]: + B(f"{k}: manifest says provider/template {declared[k]}, " + f"repo-blueprint.yaml mints it as {blueprint_secrets[k]}") + + # ── bootstrap: what is left of it, and what BE4 removed ─────────────── + # + # `umbrella` and `agentBrief` named two files BE4 deleted. orun-cloud + # BE-K1c made both OPTIONAL in the manifest contract for exactly this, so + # this file no longer declares them — and must not, because a path that + # does not exist is the drift this whole test is about. + boot = spec.get("bootstrap") or {} + for field in ("umbrella", "agentBrief"): + rel = boot.get(field) + if rel is None: + continue + B(f"bootstrap.{field} is back, naming {rel}. The shell layer is gone " + f"(BE4): every phase is declared in repo-blueprint.yaml and orun runs " + f"it, so there is no umbrella to name and no session to brief.") + if not boot.get("expectedMinutes"): + B("bootstrap.expectedMinutes is missing — the console renders it") + + # ── …and what BE-K1e added in their place ───────────────────────────── + # + # With no umbrella and no brief, `blueprint` is the ONLY entry point: it + # names the document whose phases a runner places after fetching this repo + # at its pinned tag. The registry row's `manifestPath` names the console + # CARD — this file — so without this key a runner has nothing to run. + # + # Checked the way everything else here is checked: against the thing that + # does the work, not against another copy of the claim. The file must + # exist, and it must be the one that actually declares the phases — a path + # to some other YAML would satisfy a mere existence check and fail a real + # bootstrap at the only moment that matters. + build = boot.get("blueprint") + if not build: + B("bootstrap.blueprint is missing. This baseline has no umbrella and " + "no agentBrief (BE4), so nothing else names the document a runner " + "places — a fetch at the pinned tag would find no entry point.") + else: + target = root / build + if not target.is_file(): + B(f"bootstrap.blueprint names {build}, which does not exist") + else: + try: + doc = yaml.safe_load(target.read_text()) or {} + except yaml.YAMLError as exc: + doc = {} + B(f"bootstrap.blueprint names {build}, which does not parse: {exc}") + if doc and not (doc.get("phases") or (doc.get("spec") or {}).get("phases")): + B(f"bootstrap.blueprint names {build}, which declares no phases. " + f"A runner would fetch it and place nothing.") + if doc and doc.get("kind") != "Blueprint": + B(f"bootstrap.blueprint names {build}, whose kind is " + f"{doc.get('kind')!r} rather than Blueprint") + + # ── every declared input is one the BLUEPRINT accepts ───────────────── + # + # This used to check the manifest's keys against the UMBRELLA's inputs, + # because a flow was what consumed them and orun's flow engine fails closed + # on an undeclared `--set`. The blueprint is what consumes them now, and it + # fails closed the same way: + # + # ✕ unknown input "reponame" (not declared in blueprint inputs) + # + # That equivalence is why open question 10 had to be settled in the same + # commit that deleted the flows: the umbrella's lowercase input names were + # the ONLY thing translating this file's keys into the blueprint's + # camelCase ones, so deleting it without renaming would have left every key + # refused. + # + # ONE DIRECTION ONLY. The blueprint declares more than this file does — + # `githuborg`, `epicSlug`, `domain`, `orunWorkspace` and the identity + # defaults are how a BUILD is driven, not what a product is configured + # with. What must hold is that nothing this file declares arrives at an + # engine that cannot take it. + if bp is not None: + bp_inputs = set((bp.get("inputs") or {}).keys()) + if not bp_inputs: + B("repo-blueprint.yaml declares no inputs — this check has gone blind") + for key in [f.get("key") for f in (spec.get("inputs") or [])]: + if key and key not in bp_inputs: + B(f"inputs[{key}] is not an input of repo-blueprint.yaml — the " + f"console would resolve it and the engine would refuse it " + f"(orun fails closed on an undeclared --set)") + + # ── …AND THE OTHER DIRECTION, for REQUIRED inputs only ─────────────── + # + # The check above is one-directional on purpose: the blueprint declares + # more than this card does, because `epicSlug`, `domain` and the identity + # defaults are how a BUILD is driven rather than what a product is + # configured with. That tolerance had no floor, and `githuborg` fell + # through it — `required: true` in the blueprint, absent from this card, + # so a platform build resolved the card's inputs, handed them to the + # runner and died on its first step: + # + # ✕ input "githuborg" is required + # + # An input the blueprint REQUIRES and gives no default to is one somebody + # must supply, and the only things that supply inputs to a hosted build + # are this card's fields and its `from`/`derive` sources. So "more" may + # not include one of those. + # + # Defaulted inputs stay out of it: a default IS the supply. + if bp is not None: + for key, spec_in in (bp.get("inputs") or {}).items(): + if not isinstance(spec_in, dict): + continue + if not spec_in.get("required"): + continue + if "default" in spec_in: + continue + if key not in input_keys: + B(f"repo-blueprint.yaml requires input {key!r} and gives it no " + f"default, and this card does not declare it — a hosted build " + f"would collect every field it shows and still die with " + f'\'input "{key}" is required\'') + + # ── programme: BOTH or NEITHER, against the blueprint's own hooks ───── + # + # A milestone is what a phase CLUBS ITS TASK UNDER, which the phase states + # as `orun.task/ensure@v1`'s `milestone:`, which is why a phase that is + # the second landing of one unit of work would name its predecessor's + # milestone rather than one of its own (`04-workers-restore` did, before + # the bootstrap folded it into `05-edge`). + # + # Distinct, in phase order. The old check grepped the umbrella's + # `ensure-milestone` lines for the same list. + ensured, seen = [], set() + for phase in bp_phases: + for hook in uses(phase, "orun.task/ensure@v1"): + # Not `name`: that is the manifest's file name, which the summary + # line below prints (it printed the last milestone instead). + ms_name = ((hook.get("with") or {}).get("milestone") or "") + ms_name = ms_name.replace("{{ .phase.name }}", phase.get("name", "")).strip() + if ms_name and ms_name not in seen: + seen.add(ms_name) + ensured.append(ms_name) + + # A phase's `when:` is what made a milestone conditional; the umbrella + # carried the same fact as a shell `[ != "true" ] ||` guard. + conditional = { + p_["name"] for p_ in bp_phases + if p_.get("when") and p_.get("name") in seen + } + + prog = spec.get("programme") + if not ensured: + if prog: + B("declares a programme but repo-blueprint.yaml opens no milestones") + else: + if not prog: + B(f"repo-blueprint.yaml opens {len(ensured)} milestone(s) and the " + f"manifest declares no programme") + else: + ms = prog.get("milestones") or [] + if any(not isinstance(m, dict) or "name" not in m for m in ms): + B("every programme.milestones entry must be a mapping with a `name` " + "(so a conditional one can carry its `when`)") + else: + names = [m["name"] for m in ms] + dcond = {m["name"] for m in ms if m.get("when")} + if names != ensured: + B(f"programme.milestones {names} != repo-blueprint.yaml's {ensured}") + if dcond != conditional: + B(f"conditional milestones disagree: manifest says {sorted(dcond) or '[]'}, " + f"the blueprint guards {sorted(conditional) or '[]'}") + slug = ((bp.get("inputs") or {}).get("epicSlug") or {}).get("default") + if slug and prog.get("epicSlug") != slug: + B(f"programme.epicSlug {prog.get('epicSlug')!r} != the blueprint's " + f"default {slug!r}") + + # ── verify is optional, but must not name an input that is not there ── + input_keys = {f.get("key") for f in (spec.get("inputs") or [])} | {"env"} + for url in ((spec.get("verify") or {}).get("urls") or []): + for ph in re.findall(r"\{([a-zA-Z0-9_]+)\}", url): + if ph not in input_keys: + B(f"verify url interpolates {{{ph}}}, which is not an input") + + checked.append((name, len(declared), len((prog or {}).get("milestones") or []))) + +if problems: + print("FAIL: a manifest and the blueprint disagree:", file=sys.stderr) + for p in problems: + print(f" - {p}", file=sys.stderr) + sys.exit(1) + +for name, ns, nm in checked: + print(f" {name}: {ns} secret(s), {nm} milestone(s) agree with repo-blueprint.yaml") +PY + +echo "manifest.test.sh: ok" diff --git a/testing/phases.test.sh b/testing/phases.test.sh new file mode 100755 index 0000000..bbe6bd3 --- /dev/null +++ b/testing/phases.test.sh @@ -0,0 +1,429 @@ +#!/usr/bin/env bash +# The phases in `repo-blueprint.yaml` must be the phases the bootstrap runs, +# placing what they are meant to place, saying what they are, and naming only +# what the engine can resolve. +# +# The partition below is the bootstrap's order, written down a second time on +# purpose: the order is load-bearing (the deployment record cannot be written +# before the site is live), and a module that drifts into another phase fails +# at landing time, live, with nothing in this repository having looked wrong. +# Moving one is a deliberate change, argued in the diff that edits both places. +# +# ONE LANDING BUILDS THE PRODUCT (cirrus-baseline baseline-v22): `01-product` +# places every module — root files, workflows, tooling, the site and its tests +# — brands it, and lands it as one pull request; it is the only phase that +# deploys. `02-docs` places nothing: it records what went live and puts back +# what `01-product` deferred. The hook chain of `01-product` is cirrus's, +# hook for hook, and is pinned below. +# +# And the shape that keeps a bootstrap fast (orun >= v2.88.0, ported from +# sourceplane/turso-starter baseline-v8): the run-level task set-up runs in +# the background, each phase finds its task just before its landing, each +# landing checks its commit here (`checks: local`), and the convergence +# watch reads every few seconds. +# +# Adapted from sourceplane/cirrus-baseline's testing/phases.test.sh: the +# narration rules and the hook-only rule are Cirrus's, unchanged. +# +# bash + python3 + PyYAML. No network, no fakes, no credential. +set -euo pipefail +here="$(cd "$(dirname "$0")" && pwd)" +root="$(cd "$here/.." && pwd)" + +echo "── repo-blueprint.yaml phases against what the bootstrap runs" +python3 - "$root" <<'PY' +import pathlib, re, sys + +try: + import yaml +except ImportError: + sys.exit("PyYAML is required for the phase contract test (pip install pyyaml)") + +root = pathlib.Path(sys.argv[1]) +problems = [] +def bad(m): problems.append(m) + +bp = yaml.safe_load((root / "repo-blueprint.yaml").read_text()) +phases = bp.get("phases") or [] +if not phases: + sys.exit("repo-blueprint.yaml declares no phases — this check has gone blind") + +PARTITION = { + "01-product": ["ai-deployment", "ai-operations", "discovery-roots", + "github-workflows", "rebrand-values", "root-gitignore", "root-intent", + "root-package-json", "root-pnpm-lock", + "root-pnpm-workspace", "root-readme", "root-turbo", "tooling-eslint", + "tooling-tsconfig", "tooling-wire", "vscode", "web", "web-tests"], + "02-docs": [], +} +HOOK_ONLY = {"02-docs"} +# The phases that DEPLOY, and so must give a re-run something to land. +DEPLOYS = {"01-product"} + +by_name = {p["name"]: p for p in phases} +names = [p["name"] for p in phases] + +# ── the order IS the execution order ────────────────────────────────────── +if names != sorted(names): + bad(f"phases are not in execution order: {names}. The numbered name IS the " + f"order; a phase out of sequence is a barrier in the wrong place.") +if names != list(PARTITION): + bad(f"phases are {names}; the bootstrap runs {list(PARTITION)}") + +# ── the partition has not drifted ───────────────────────────────────────── +for name, want in PARTITION.items(): + if name not in by_name: + continue + now = sorted(by_name[name].get("modules") or []) + if now != sorted(want): + bad(f"phase {name} no longer places what it placed: gained " + f"{sorted(set(now) - set(want)) or '[]'}, lost {sorted(set(want) - set(now)) or '[]'}") +declared = {m["name"] for m in bp.get("modules") or []} +placed = {m for p in phases for m in (p.get("modules") or [])} +for m in sorted(declared - placed): + bad(f"module {m} is declared and no phase places it") +for name in HOOK_ONLY: + if by_name.get(name, {}).get("modules"): + bad(f"phase {name} places modules — it is declared as hooks only") + +# ── nothing may GATE on a phase the tree cannot answer for ──────────────── +# A hook-only phase places no files, so orun derives it as `unknown`, and +# `requires.phases` fails closed on `unknown`: a requirement naming one can +# never be satisfied. +for p in phases: + for need in ((p.get("requires") or {}).get("phases") or []): + if need in HOOK_ONLY: + bad(f"phase {p['name']} requires {need}, which places no files — require " + f"its predecessor instead") + if need not in by_name or names.index(need) >= names.index(p["name"]): + bad(f"phase {p['name']} requires {need}, which does not run before it") + +# ── every phase says what it is and what to budget ──────────────────────── +for p in phases: + for field in ("title", "expectedMinutes"): + if not p.get(field): + bad(f"phase {p['name']} declares no {field} — an operator reads both") + if not (p.get("hooks") or {}): + bad(f"phase {p['name']} declares no hooks — a phase that only places files " + f"still has to land them") + +def hooks_of(p): + h = p.get("hooks") or {} + if isinstance(h, list): + return list(h) + return [x for slot in ("pre", "post", "await") for x in (h.get(slot) or [])] + +run_hooks = list((bp.get("hooks") or {}).get("preInstantiate") or []) + +# ── every phase lands, and every landing is bound to its task ───────────── +for p in phases: + ids = [h.get("id") for h in hooks_of(p)] + lands = [h for h in hooks_of(p) if (h.get("uses") or "").startswith("orun.pr/land@")] + if len(lands) != 1: + bad(f"phase {p['name']} has {len(lands)} landing(s); a phase is ONE pull request") + continue + w = lands[0].get("with") or {} + if w.get("task") != "{{ .phase.hooks.task.outputs.key }}": + bad(f"phase {p['name']} lands without binding the PR to its task key") + if "task" not in ids or ids.index("task") > ids.index(lands[0].get("id")): + bad(f"phase {p['name']} must ensure its task before it lands") + if p["name"] in DEPLOYS: + if not any("retouch.mjs" in " ".join(h.get("run") or []) for h in hooks_of(p)): + bad(f"phase {p['name']} deploys and has no retouch hook — a re-run after a " + f"failed convergence would land an empty diff and redeploy nothing") + awaits = (p.get("hooks") or {}).get("await") or [] + watch = [h for h in awaits if (h.get("uses") or "").startswith("orun.run/watch@")] + if not watch or (watch[0].get("with") or {}).get("sha") != "{{ .phase.hooks.land.outputs.mergeSha }}": + bad(f"phase {p['name']} deploys and does not watch the convergence of the " + f"commit it merged (orun.run/watch@v1 with sha: mergeSha)") + +# ── every phase's task is one the run-level list opens, in the same order ─ +def task_names(hooks): + return [(h.get("with") or {}).get("name") for h in hooks + if (h.get("uses") or "").startswith("orun.task/ensure@") + and (h.get("with") or {}).get("kind") == "task"] +opened = task_names(run_hooks) +per_phase = [n for p in phases for n in task_names(hooks_of(p))] +if opened != per_phase: + bad(f"the run-level list opens tasks {opened}; the phases ensure {per_phase} — " + f"a task is found by its title, so the two must be the same words") +milestones = [(h.get("with") or {}).get("name") for h in run_hooks + if (h.get("with") or {}).get("kind") == "milestone"] +if milestones != names: + bad(f"the run-level list opens milestones {milestones}; the phases are {names}") + +# ── every contract a hook names exists, beside the blueprint ────────────── +for h in run_hooks + [x for p in phases for x in hooks_of(p)]: + rel = (h.get("with") or {}).get("contract") + if rel and not (root / rel).exists(): + bad(f"hook {h.get('id')} names contract {rel}, which does not exist") + if rel and not rel.startswith(".baseline/tasks/"): + bad(f"hook {h.get('id')} names contract {rel} outside .baseline/tasks/ — " + f"`tasks/` is this repository's own work tree, where an unkeyed " + f"contract is an error") +for p in phases: + for h in hooks_of(p): + argv = " ".join(h.get("run") or []) + for ref in re.findall(r"\{\{ \.baseline\.dir \}\}/(\S+?)(?:\"|'|\s|$)", argv + " "): + if not (root / ref).exists(): + bad(f"phase {p['name']} hook {h.get('id')} runs {ref}, which this " + f"repository does not have") + +# ── every phase has a documentation page, and every page a phase ────────── +docs_dir = root / "docs" / "phases" +pages = {f.stem for f in docs_dir.glob("*.md")} - {"README"} +for n in names: + if n not in pages: + bad(f"phase {n} has no page at docs/phases/{n}.md") +for page in sorted(pages - set(names)): + bad(f"docs/phases/{page}.md documents a phase repo-blueprint.yaml does not declare") + +# ── narration: authored here, printed from state (Cirrus's rules) ───────── +META_AT = { + "start": {"files", "expectedMinutes"}, + "await": {"files", "expectedMinutes"}, + "failed": {"files", "expectedMinutes"}, + "done": {"files", "expectedMinutes", "elapsed", "next"}, +} +STATE_WORDS = {"done", "failed", "complete", "completed", "succeeded", "skipped"} +PHASE_KEYS = {"name", "title"} +input_keys = set((bp.get("inputs") or {}).keys()) + +ws_input = (bp.get("inputs") or {}).get("orunWorkspace") or {} +if ws_input.get("from") != "workspace": + bad("inputs.orunWorkspace must declare `from: workspace` — a console build has no other way to say it") + +def strip_expressions(line): + return re.sub(r"\{\{.*?\}\}", "", line, flags=re.S) + +def refs(line): + found = [] + for expr in re.findall(r"\{\{(.*?)\}\}", line, re.S): + found += re.findall(r"\.([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*)", expr) + return found + +def check_line(where, line, slot, hook_ids): + prose = strip_expressions(line).lower() + for w in STATE_WORDS: + if re.search(rf"\b{w}\b", prose): + bad(f"{where} asserts {w!r} — `state` is the truth and narration is the " + f"caption. Describe the world, not the run.") + for ref in refs(line): + parts = ref.split(".") + head = parts[0] + if head == "phase": + if len(parts) != 2 or parts[1] not in PHASE_KEYS: + bad(f"{where} names .{ref}; a phase carries {sorted(PHASE_KEYS)}") + elif head == "inputs": + if len(parts) != 2 or parts[1] not in input_keys: + bad(f"{where} names .{ref}, which is not a declared input") + elif head == "meta": + allowed = META_AT.get(slot, META_AT["start"]) + if len(parts) != 2 or parts[1] not in allowed: + bad(f"{where} names .{ref}; the {slot} event carries {sorted(allowed)}") + elif head == "hooks": + if len(parts) < 2 or parts[1] not in hook_ids: + bad(f"{where} names .{ref}; this phase has no such hook") + else: + bad(f"{where} names .{ref}; narration may reference phase, inputs, meta and hooks") + +for p in phases: + n = p.get("narrate") or {} + ids = {h.get("id") for h in hooks_of(p)} + awaits = bool((p.get("hooks") or {}).get("await")) + for slot in ("start", "await", "done", "failed"): + line = n.get(slot) + if slot == "await" and not awaits: + # A phase that waits on nothing never says its await line. + if line: + bad(f"phase {p['name']} declares narrate.await and has no await hooks — " + f"nobody would ever read it") + continue + if not line: + bad(f"phase {p['name']} declares no narrate.{slot}") + continue + check_line(f"phase {p['name']} narrate.{slot}", line, slot, ids) + for h in ((p.get("hooks") or {}).get("await") or []): + line = h.get("narrate") + if not line: + bad(f"phase {p['name']} await hook {h.get('id')} declares no narrate — a " + f"wait with no words reads as a stalled build") + continue + check_line(f"phase {p['name']} hook {h.get('id')} narrate", line, "done", ids) + for slot in ("pre", "post"): + for h in ((p.get("hooks") or {}).get(slot) or []): + if h.get("narrate"): + check_line(f"phase {p['name']} hook {h.get('id')} narrate", h["narrate"], "start", ids) + +# ── ONE LANDING: every component is placed by the deploying phase ───────── +# A component placed by any other phase would deploy in a convergence of its +# own, after a landing of its own — the fixed cost the one-landing bootstrap +# exists to pay once. +module_from = {m["name"]: (m.get("from") or "").rstrip("/") for m in bp.get("modules") or []} +phase_of = {m: p["name"] for p in phases for m in (p.get("modules") or [])} +components = {c.parent.relative_to(root).as_posix() + for c in root.rglob("component.yaml") + if "node_modules" not in c.parts and ".git" not in c.parts and ".orun" not in c.parts} +for name, src in sorted(module_from.items()): + if src in components and phase_of.get(name) not in DEPLOYS: + bad(f"module {name} places the component {src} from phase {phase_of.get(name)}; " + f"every component lands in {sorted(DEPLOYS)}") +watching = {p["name"] for p in phases + if any((h.get("uses") or "").startswith("orun.run/watch@") for h in hooks_of(p))} +if watching != DEPLOYS: + bad(f"the phases that watch a convergence are {sorted(watching)}; only {sorted(DEPLOYS)} deploys") + +# ── 01-product's hook chain is cirrus-baseline's ───────────────────────────── +# The identity chain (retouch before git exists, then git, rebrand, re-tenant, +# the work-tree strip, the two deferrals, restage, verify), the repository and +# its link, the brokered credentials — ONE `secrets` reconcile per provider +# (orun >= v2.87.0), after the link and before the landing whose convergence +# uses them — then the task, found just before the landing so that everything +# before it runs beside the background task set-up, and the landing. No +# lockfile hook: the shipped lockfile is installed frozen by the lanes and by +# testing/e2e.test.sh. No phase has a `pre` hook. +PRE = {"01-product": [], "02-docs": []} +CHAIN = ["retouch", "git-init", "git-stage", "rebrand", "orun-workspace", + "work-tree", "promotion", "dev-lanes", "git-restage", "rebrand-verify", + "repo", "link", "secrets", "task", "land"] +TYPED = {"repo": "orun.repo/ensure@v1", "secrets": "orun.integrations/reconcile@v1", + "task": "orun.task/ensure@v1", "land": "orun.pr/land@v1"} +RUN_HAS = {"retouch": "retouch.mjs", "work-tree": "work-tree.mjs --strip", + "promotion": "promotion.mjs --defer", "dev-lanes": "dev-lanes.mjs --defer", + "rebrand": "rebrand.mjs --values", "rebrand-verify": "rebrand.mjs --verify"} +for name, want in PRE.items(): + got = [h.get("id") for h in ((by_name.get(name, {}).get("hooks") or {}).get("pre") or [])] + if got != want: + bad(f"phase {name}'s pre hooks are {got}; want {want} — a task found in `pre` waits " + f"for the background task set-up before the phase has done anything") +product = by_name.get("01-product") or {} +post = (product.get("hooks") or {}).get("post") or [] +chain = [h.get("id") for h in post] +if chain != CHAIN: + bad(f"01-product's post hooks are {chain}; cirrus-baseline's are {CHAIN}") +# One reconcile per provider, every key it mints listed in `secrets:` with its +# own template: one connections read and one secrets read for all of them, +# the missing keys created side by side — not one hook (and two round trips) +# per key. This site mints from Cloudflare alone: WordPress is not a provider the +# platform brokers. +reconciles = [h for h in post if (h.get("uses") or "") == "orun.integrations/reconcile@v1"] +if not reconciles: + bad("01-product mints no credential — its convergence deploys, and binds CLOUDFLARE_API_TOKEN") +providers = [(h.get("with") or {}).get("provider") for h in reconciles] +if len(set(providers)) != len(providers): + bad(f"01-product reconciles {providers} — one hook per provider, its keys in `secrets:`") +for h in reconciles: + w = h.get("with") or {} + items = w.get("secrets") or [] + if w.get("keys") or w.get("template") or not items or \ + any(not (i or {}).get("key") or not (i or {}).get("template") for i in items): + bad(f"reconcile hook {h.get('id')} does not mint its keys as `secrets: [{{key, template}}]` — " + f"one hook per provider, each key under its own scope template") +for h in post: + want = TYPED.get(h.get("id")) + if want and h.get("uses") != want: + bad(f"01-product hook {h.get('id')} uses {h.get('uses')!r}, not {want}") + need = RUN_HAS.get(h.get("id")) + if need and need not in " ".join(h.get("run") or []): + bad(f"01-product hook {h.get('id')} does not run `{need}`") + +# The await: the convergence of the merge commit, then the URLs. There is no +# wiring await (orun.secrets/exists@v1): this site has no infra component, so +# nothing lease-publishes a WIRING_* document. Were one added, its readers +# would prove it instead — each resolving the document in the same +# convergence from its component.yaml secret refs, where every later run +# reads it, fail-closed, after waiting for its publisher on main +# (placement.test.sh's INFRA BEFORE APP) — which is the rule +# sourceplane/turso-starter's copy of this file holds. There is nothing here +# for that rule to read, so an infra component stops this test until it is +# ported (or until the wiring is awaited again). +infra = sorted(c for c in components if c.startswith("infra/")) +if infra: + bad(f"{infra} would publish wiring this file does not check — port turso-starter's reader " + f"rule (each WIRING_* resolved in the convergence on stage and prod, the reader waiting " + f"for its publisher on main), or await it with orun.secrets/exists@v1") +awaits = (product.get("hooks") or {}).get("await") or [] +if [h.get("id") for h in awaits] != ["converge", "verify"]: + bad(f"01-product's await hooks are {[h.get('id') for h in awaits]}; want ['converge', 'verify']") +kinds = [(h.get("uses") or "").split("@")[0] for h in awaits] +want_kinds = ["orun.run/watch", "orun.http/probe"] +if kinds != want_kinds: + bad(f"01-product awaits {kinds}; it must await {want_kinds}") +probe_urls = [] +for h in awaits: + if (h.get("uses") or "").startswith("orun.http/probe@"): + probe_urls = (h.get("with") or {}).get("urls") or [] +for env in ("stage", "prod"): + if not any(f"-{env}." in u for u in probe_urls): + bad(f"01-product's probe names no {env} URL: {probe_urls}") + +# 02-docs: puts back what 01-product deferred, renders the record, finds its +# task, lands — and awaits nothing: its render probes every URL as it writes +# the record, and its landing redeploys nothing, so there is no probe after +# it to wait for. +docs = by_name.get("02-docs") or {} +dpost = (docs.get("hooks") or {}).get("post") or [] +if [h.get("id") for h in dpost] != ["promotion", "dev-lanes", "render", "task", "land"]: + bad(f"02-docs's post hooks are {[h.get('id') for h in dpost]}; want promotion, dev-lanes, render, task, land") +for h in dpost: + argv = " ".join(h.get("run") or []) + if h.get("id") in ("promotion", "dev-lanes") and "--restore" not in argv: + bad(f"02-docs hook {h.get('id')} does not --restore") +dawait = (docs.get("hooks") or {}).get("await") or [] +if dawait: + bad(f"02-docs awaits {[h.get('id') for h in dawait]} — its render probes as it writes and its " + f"landing redeploys nothing, so there is nothing after it to wait for") + +# ── THE FAST SHAPE (orun >= v2.88.0) ────────────────────────────────────── +# The run-level list is the task set-up, all of it in the background: the +# first phase's provider check, placement, rebrand, repository, link and +# secrets run while it opens the epic, the milestones and the tasks. +for h in run_hooks: + if not h.get("background"): + bad(f"hooks.preInstantiate {h.get('id')} is not `background: true` — the first phase " + f"waits for it before doing anything, though nothing before its landing reads it") +# No phase keeps a `pre` hook on the task plane: it would wait for the whole +# background before the phase has placed a file — the old order, whatever +# its id. +TASK_PLANE = ("orun.task/", "orun.pr/") +for p in phases: + for h in ((p.get("hooks") or {}).get("pre") or []): + if (h.get("uses") or "").startswith(TASK_PLANE): + bad(f"phase {p['name']} pre hook {h.get('id')} uses {h['uses']} — it waits for " + f"the background task set-up; find the task in `post`, just before the landing") +# Every landing checks its commit here and merges, instead of waiting for a +# runner to plan (and, before, for Checks to build) the tree this box just +# wrote. +for p in phases: + for h in hooks_of(p): + if (h.get("uses") or "").startswith("orun.pr/land@") and (h.get("with") or {}).get("checks") != "local": + bad(f"phase {p['name']} lands with checks {(h.get('with') or {}).get('checks', 'ci')!r}, " + f"not 'local' — it waits for a runner to plan a tree that is here") +# The convergence watch reads every few seconds, not the action's default 40. +for p in phases: + for h in ((p.get("hooks") or {}).get("await") or []): + if (h.get("uses") or "").startswith("orun.run/watch@"): + every = (h.get("with") or {}).get("pollSeconds") + if not isinstance(every, int) or every > 10: + bad(f"phase {p['name']} watches its convergence every {every or 40} s; at most 10 — " + f"the build goes on that much after the run is green") + +# ── what a baseline of this shape never grows back ──────────────────────── +if (root / "flows").exists(): + bad("flows/ exists — the bootstrap is the blueprint; every mechanism is a typed orun action") + +if problems: + print("FAIL: the blueprint's phases and the bootstrap disagree:", file=sys.stderr) + for p in problems: + print(f" - {p}", file=sys.stderr) + sys.exit(1) + +placed_n = sum(len(p.get("modules") or []) for p in phases) +narrated = sum(len(p.get("narrate") or {}) for p in phases) +narrated += sum(1 for p in phases for h in hooks_of(p) if h.get("narrate")) +print(f" {len(phases)} phases, {placed_n} modules, {len(HOOK_ONLY)} hook-only — in execution order") +print(f" hooks in the one-landing order; task set-up in the background, every landing checked here") +print(f" {narrated} authored narration lines, every reference resolving") +PY + +echo "phases.test.sh: ok" diff --git a/testing/placement.test.sh b/testing/placement.test.sh new file mode 100755 index 0000000..73457d5 --- /dev/null +++ b/testing/placement.test.sh @@ -0,0 +1,325 @@ +#!/usr/bin/env bash +# TIER 1 — the tree is placed, branded, and made to answer. +# +# A real bootstrap is `orun new --run-hooks --resume` against a workspace: it +# places each phase, runs that phase's hooks, lands a pull request and watches +# the convergence. Everything in that sentence except the platform can run +# here, offline, and this file runs it: +# +# 1. the whole blueprint placed in one go — orun runs `validate` and +# `plan --dry-run` inside the produced tree and says so; asserted, because +# a future orun that stopped running them would weaken this tier in silence; +# 2. THE OFFLINE BOOTSTRAP (testing/lib/bootstrap.sh) — both phases placed in +# order, finished by the blueprint's OWN `run:` hooks (retouch, rebrand, +# re-tenant, work-tree strip, the deferrals and their restore, the +# deployment record), each landing a commit on top of orun's `Initial +# commit`; +# 3. the product it ends with: branded with no residue, carrying nothing of +# the factory and naming none of its paths, re-tenanted, its gates +# restored, its record rendered; +# 4. what the product's own CI does with the 01-product merge: `orun plan` +# exactly as ci.yml runs it (`--from-ci github --event-file … --changed`) +# for the push that merged it — infrastructure before anything reading +# its wiring (this site has none, so nothing waits), the site deployed to +# stage and prod side by side, nothing on dev, the structure check before +# the build, the Worker, the smoke and the secret refs the product's own +# — the WordPress URL's ref best-effort, so a product nobody has +# connected to a WordPress yet still resolves every lane; +# 5. a `--resume` over the finished site places nothing and un-brands nothing. +# +# testing/e2e.test.sh goes on from here: it installs, builds and serves the +# product and runs its smoke against it. +# +# Needs: orun, node, pnpm, python3 (+PyYAML), git. No credential. The +# deployment-record probes reach the network if they can, and pass without it. +set -euo pipefail +here="$(cd "$(dirname "$0")" && pwd)" +root="$(cd "$here/.." && pwd)" +# shellcheck source=lib/bootstrap.sh +source "$here/lib/bootstrap.sh" + +for bin in orun node pnpm python3 git; do + command -v "$bin" >/dev/null || { echo "placement.test.sh needs $bin on PATH" >&2; exit 1; } +done +# Step 4 is the PRODUCT's own plan, so it must be planned by the orun the +# product's CI runs (ci.yml's pin) or newer. The bootstrap's floor (v2.88.0) +# is newer than the pin, and is what baseline.yml runs this under: steps 1 +# and 2 read the blueprint, which an orun below the floor refuses. +pin="$(sed -n 's/^ *version: *v\([0-9.]*\) *$/\1/p' "$root/.github/workflows/ci.yml" | head -1)" +have="$(orun --version | sed -n 's/.*version \([0-9.]*\).*/\1/p')" +python3 -c "import sys; v=lambda s: tuple(map(int, s.split('.'))); sys.exit(0 if v(sys.argv[1]) >= v(sys.argv[2]) else 1)" "$have" "$pin" \ + || { echo "placement.test.sh plans as the product's CI does: run it with orun >= v$pin (ci.yml's pin), not v$have" >&2; exit 1; } + +scratch="$(mktemp -d)" +trap 'rm -rf "$scratch"' EXIT +fails=0 +fail() { echo " ✕ $*" >&2; fails=$((fails + 1)); } +values="$here/fixtures/acme.json" +repo="$(python3 -c "import json,sys;print(json.load(open(sys.argv[1]))['reponame'])" "$values")" +org="$(python3 -c "import json,sys;print(json.load(open(sys.argv[1]))['githuborg'])" "$values")" + +sets=() +while IFS=$'\t' read -r k v; do sets+=( --set "$k=$v" ); done < <( + python3 - "$values" <<'PY' +import json, sys +for k, v in json.load(open(sys.argv[1])).items(): + if not k.startswith("_"): + print(f"{k}\t{'true' if v is True else 'false' if v is False else v}") +PY +) + +# ── 1. the whole blueprint, one placement ────────────────────────────────── +echo "── placing the whole blueprint at once (offline, no credential)" +whole="$scratch/whole" +mkdir -p "$whole"/{apps,infra,packages,tests} +for d in apps infra packages tests; do touch "$whole/$d/.gitkeep"; done +if ! orun new --blueprint "$root/repo-blueprint.yaml" --out "$whole" "${sets[@]}" > "$scratch/whole.log" 2>&1; then + echo "FAIL: the placement did not run" >&2; tail -20 "$scratch/whole.log" >&2; exit 1 +fi +# The line's wording moved between orun releases (v2.58: `repo gate: validate + +# plan --dry-run passed`; v2.79: `Verified intent valid · N components …`). +grep -Eq "repo gate: validate \+ plan --dry-run passed|Verified +intent valid" "$scratch/whole.log" \ + || fail "the placement did not report the repo-scale gate (orun validate + plan --dry-run inside the tree)" +n="$(find "$whole" -type f -not -path '*/.orun/*' | wc -l | tr -d ' ')" +[ "$n" -ge 50 ] || fail "only $n files placed — that is not a site" +[ "$fails" -eq 0 ] && echo " $n files placed; the repo-scale gate ran" + +# ── 2. the offline bootstrap ─────────────────────────────────────────────── +echo "── the offline bootstrap: both phases, their own hooks, a landing each" +tree="$scratch/$repo" # named as the repository is: orun names the project after it +bootstrap_offline "$root" "$tree" "$values" "$scratch/logs" > "$scratch/bootstrap.log" 2>&1 || { + echo "FAIL: the offline bootstrap stopped" >&2; tail -40 "$scratch/bootstrap.log" >&2; exit 1; } +grep -E '^── ' "$scratch/bootstrap.log" | sed 's/^/ /' +commits="$(git -C "$tree" rev-list --count HEAD)" +[ "$commits" = 3 ] || fail "the bootstrap made $commits commits, not orun's initial one and one per phase (3)" +[ -z "$(git -C "$tree" ls-tree -r --name-only HEAD~2)" ] || fail "the first commit is not orun's empty Initial commit" + +# ── 3. the product it ends with ──────────────────────────────────────────── +echo "── the site it produced" +(cd "$tree" && node "$root/tooling/rebrand/rebrand.mjs" --verify --values .rebrand/values.json) > "$scratch/verify.log" 2>&1 \ + || { fail "rebrand --verify found the baseline's identity in the site:"; sed 's/^/ /' "$scratch/verify.log" >&2; } + +python3 - "$tree" "$values" "$root" <<'PY' || fails=$((fails + 1)) +import json, pathlib, re, subprocess, sys +import yaml +tree, values, root = pathlib.Path(sys.argv[1]), json.load(open(sys.argv[2])), pathlib.Path(sys.argv[3]) +problems = [] +def bad(m): problems.append(m) +repo, org, name, sub = values["reponame"], values["githuborg"], values["productname"], values["subdomain"] +ws = values["orunWorkspace"] + +tracked = subprocess.run(["git", "ls-files"], cwd=tree, capture_output=True, text=True, check=True).stdout.split() + +# Nothing of the factory, nothing local, exactly the two context pages. +NEVER = (".baseline/", "specs/", "tasks/", "testing/", "hooks/", "docs/phases/", + "tooling/rebrand/", "tooling/bootstrap/", ".github/workflows/baseline.yml", + ".github/workflows/tag.yml", "BOOTSTRAP.md", "repo-blueprint.yaml", "blueprint.yaml") +for p in tracked: + if any(p == n or p.startswith(n) for n in NEVER): + bad(f"{p} is in the site — it is the factory") + if re.search(r"(^|/)(\.env(\.local)?|\.dev\.vars|node_modules|\.orun|\.wrangler|\.next|\.open-next|dist)(/|$)", p): + bad(f"{p} is in the site — a local or built file") +ai = {p for p in tracked if p.startswith("ai/")} +if ai != {"ai/context/deployment.md", "ai/context/operations.md"}: + bad(f"ai/ in the site is {sorted(ai)}") + +# No tracked file names a factory path: the product has none of them. +FACTORY = re.compile( + r"repo-blueprint|BOOTSTRAP\.md|(?<![\w.-])(testing|specs|tasks|docs/phases|hooks)/" + r"|\.baseline/|tooling/(rebrand|bootstrap)/") +for p in tracked: + if p == "pnpm-lock.yaml": + continue + try: + text = (tree / p).read_text() + except UnicodeDecodeError: + continue + for n, line in enumerate(text.splitlines(), 1): + m = FACTORY.search(line) + if m: + bad(f"{p}:{n} names the factory path {m.group(0)!r}: {line.strip()[:80]}") + +# The identity, where the site carries it. +site = (tree / "apps/web/site.config.ts").read_text() +if f"SITE_NAME = {json.dumps(name)};" not in site: + bad(f"apps/web/site.config.ts does not name the site {name!r}") +wrangler = (tree / "apps/web/wrangler.jsonc").read_text() +wname = re.search(r'^\s*"name":\s*"([^"]+)"', wrangler, re.M) +if not wname or wname.group(1) != f"{repo}-web": + bad(f"wrangler.jsonc names the Worker {wname and wname.group(1)!r}, not {repo}-web") +spec = yaml.safe_load((tree / "apps/web/component.yaml").read_text())["spec"] +comp = spec["parameters"] +if comp["workerName"] != f"{repo}-web" or comp["workersDevSubdomain"] != sub: + bad(f"the component deploys {comp['workerName']} on {comp['workersDevSubdomain']}, not {repo}-web on {sub}") +if comp["wranglerConfig"] != "wrangler.jsonc" or comp.get("wranglerTemplate"): + bad("the Worker's config is no longer the committed wrangler.jsonc") +# WordPress is the owner's to connect: nothing the deploy needs may be a hard +# reference to a key no bootstrap stores. +if spec.get("secretEnv"): + bad(f"apps/web declares required secrets {sorted(spec['secretEnv'])} — a fresh product has none of them") +want_refs = {"WORDPRESS_URL": f"secret://{ws}/{repo}/{{{{ .environment }}}}/WORDPRESS_URL"} +if spec.get("optionalSecretEnv") != want_refs: + bad(f"apps/web's optional WordPress ref is {spec.get('optionalSecretEnv')}, not the product's {want_refs}") +if json.loads((tree / "package.json").read_text())["name"] != repo: + bad("package.json is not named for the site") +# The home page's credit to the upstream template is content, not identity. +home = (tree / "apps/web/app/page.tsx").read_text() +if 'This is <a href="https://github.com/9d8dev/next-wp">next-wp</a>,' not in home: + bad("the home page's credit to the upstream template was rewritten") + +# The intent: re-tenanted, no work tree, both gates back. +intent_text = (tree / "intent.yaml").read_text() +intent = yaml.safe_load(intent_text) +if intent["metadata"]["name"] != repo: + bad(f"intent metadata.name is {intent['metadata']['name']}") +if intent["execution"]["state"]["workspace"] != values["orunWorkspace"]: + bad(f"intent workspace is {intent['execution']['state']['workspace']}, not the site's") +if "work" in intent: + bad("intent.yaml still declares the baseline's work tree") +if "promotion" not in intent["environments"]["prod"] or "@promotion-deferred" in intent_text: + bad("prod's promotion gate was not restored by 02-docs") +if "github-push-main" not in intent["environments"]["dev"]["activation"]["triggerRefs"] or "@dev-lanes-deferred" in intent_text: + bad("dev's push activation was not restored by 02-docs") +for env in ("stage", "prod"): + want = f"https://{repo}-web-{env}.{sub}.workers.dev" + if intent["environments"][env].get("url") != want: + bad(f"environments.{env}.url is {intent['environments'][env].get('url')}, not {want}") +if any("SITE_URL" in ((e or {}).get("env") or {}) for e in intent["environments"].values()): + bad("intent.yaml sets a SITE_URL — a fresh site builds its links for its workers.dev URL") +for page in (intent.get("repo") or {}).get("docs", {}).get("pages", []): + if not (tree / page["path"]).exists(): + bad(f"intent repo.docs names {page['path']}, which the site does not have") + +# The landing, as 01-product made it. +for rel in ("apps/web/component.yaml", "tests/web/component.yaml"): + if not re.search(r"^# orun: redeploy 01-product \S+$", (tree / rel).read_text(), re.M): + bad(f"{rel} carries no 01-product redeploy marker") +dep = (tree / "ai/context/deployment.md").read_text() +if "GENERATED by the `02-docs` phase" not in dep or f"https://{repo}-web-prod.{sub}.workers.dev/api/revalidate" not in dep: + bad("ai/context/deployment.md was not rendered for the site") +readme = (tree / "README.md").read_text() +if not readme.startswith(f"# {repo}\n") or "This site is **live**" not in readme: + bad("README.md is not the site's, or its live-deployment section was not rendered") +if "## Connecting WordPress" not in readme or f"--name {repo}-web-stage" not in readme: + bad("README.md does not tell the owner how to connect a WordPress to THIS site's Workers") + +# Provenance prose, over the BRANDED files. +PROV = re.compile(r"\bfork(ed)? (of|from)\b|\bbaseline (repo|repository|commit|tag)\b|\bthis baseline\b", re.I) +for rel in tracked: + if not re.search(r"\.(md|ts|json|jsonc|ya?ml|js|mjs)$", rel) or rel == "pnpm-lock.yaml": + continue + for n, line in enumerate((tree / rel).read_text().splitlines(), 1): + if PROV.search(line): + bad(f"{rel}:{n} speaks of the factory: {line.strip()[:70]}") + +if problems: + for p in problems: + print(f" ✕ {p}", file=sys.stderr) + sys.exit(1) +print(f" {len(tracked)} tracked files; branded, re-tenanted, gates restored, record rendered; no factory path named") +PY + +# ── 4. the product's own CI, over the 01-product merge ───────────────────── +# Exactly ci.yml's plan step: a GitHub push event for the commit 01-product +# merged, whose `before` is the repository's Initial commit. The deferrals +# are in force at that commit (02-docs restores them later), so this is the +# plan the bootstrap's convergence watch waits on. +echo "── orun plan in the site, for the push that merged 01-product (as ci.yml plans it)" +s00="$(git -C "$tree" rev-parse HEAD~2)"; s01="$(git -C "$tree" rev-parse HEAD~1)" +git -C "$tree" checkout -q "$s01" +cat > "$scratch/push.json" <<EOF +{"ref": "refs/heads/main", "before": "$s00", "after": "$s01", "created": false, "forced": false, + "repository": {"name": "$repo", "full_name": "$org/$repo", "default_branch": "main", "owner": {"login": "$org"}}, + "head_commit": {"id": "$s01"}} +EOF +(cd "$tree" && orun validate --intent intent.yaml) > "$scratch/validate.log" 2>&1 \ + || { fail "orun validate refused the site's intent at 01-product"; tail -10 "$scratch/validate.log" >&2; } +(cd "$tree" && env GITHUB_ACTIONS=true GITHUB_EVENT_NAME=push GITHUB_EVENT_PATH="$scratch/push.json" \ + GITHUB_REF=refs/heads/main GITHUB_SHA="$s01" GITHUB_REPOSITORY="$org/$repo" \ + orun plan --from-ci github --event-file "$scratch/push.json" --intent intent.yaml \ + --output "$scratch/plan.json" --changed) > "$scratch/plan.log" 2>&1 \ + || { fail "orun plan failed in the site at 01-product"; tail -15 "$scratch/plan.log" >&2; } +git -C "$tree" checkout -q main +python3 - "$scratch/plan.json" "$values" "$tree" <<'PY' || fails=$((fails + 1)) +import json, pathlib, sys +import yaml +plan, values, tree = json.load(open(sys.argv[1])), json.load(open(sys.argv[2])), pathlib.Path(sys.argv[3]) +repo, sub, ws = values["reponame"], values["subdomain"], values["orunWorkspace"] +problems = [] +def bad(m): problems.append(m) +trig = (plan.get("metadata") or {}).get("trigger") or {} +if trig.get("name") != "github-push-main" or trig.get("mode") != "event-file": + bad(f"the plan did not come from the push event: {trig}") +jobs = {(j["component"], j["environment"]): j for j in plan["jobs"]} +by_id = {j["id"]: j for j in plan["jobs"]} + +# INFRA BEFORE APP. Every component under infra/ that a deploy reads wiring +# from must be a job the deploy waits on. This site has no infra component, so +# the rule holds vacuously — and the site deploys with nothing to wait for. +infra = {c.parent.name for c in tree.glob("infra/*/component.yaml")} +infra_names = {yaml.safe_load((tree / "infra" / d / "component.yaml").read_text())["metadata"]["name"] for d in infra} +for (comp, env), j in jobs.items(): + if comp in infra_names: + continue + waits = {by_id[d]["component"] for d in (j.get("dependsOn") or []) if d in by_id} + for need in infra_names: + if (need, env) in jobs and need not in waits: + bad(f"{comp}@{env} does not wait on {need}@{env} — infrastructure must apply first") +order = "no infra component — nothing to order before the site" if not infra_names else f"{sorted(infra_names)} before the site" + +if set(jobs) != {("web", "stage"), ("web", "prod")}: + bad(f"the 01-product merge plans {sorted(jobs)}; it must deploy web to stage and prod and nothing else " + f"(dev's push lanes are deferred during the bootstrap)") +for (comp, env), j in jobs.items(): + if not j["profile"].endswith(".deploy"): + bad(f"{comp}@{env} plans profile {j['profile']}, not a deploy") + if j.get("dependsOn"): + bad(f"{comp}@{env} waits on {j['dependsOn']} — during the bootstrap stage and prod deploy side by side") + steps = {s["id"]: s.get("run") or "" for s in j["steps"]} + ids = [s["id"] for s in j["steps"]] + for need in ("verify-app-structure", "build-app", "verify-build-output", "deploy", "smoke"): + if need not in steps: + bad(f"{comp}@{env} has no {need} step") + if "verify-app-structure" in ids and "build-app" in ids and ids.index("verify-app-structure") > ids.index("build-app"): + bad(f"{comp}@{env} checks the app's structure after the build") + if 'test -f "wrangler.jsonc"' not in steps.get("verify-app-structure", ""): + bad(f"{comp}@{env}'s structure check does not look for the committed wrangler.jsonc") + if f'EFFECTIVE_WORKER_NAME="{repo}-web-{env}"' not in steps.get("deploy", ""): + bad(f"{comp}@{env} deploys a Worker not named {repo}-web-{env}") + if f'WORKERS_DEV_SUBDOMAIN="{sub}"' not in steps.get("smoke", "") or "/api/revalidate" not in steps.get("smoke", ""): + bad(f"{comp}@{env}'s smoke is not the site's own: {steps.get('smoke','')[:200]}") + refs = {r["asEnv"]: r for r in j.get("secretRefs") or []} + for key in ("CLOUDFLARE_API_TOKEN", "CLOUDFLARE_ACCOUNT_ID"): + ref = (refs.get(key) or {}).get("ref", "") + if not ref.startswith(f"secret://{ws}/") or f"project:{repo}" not in ref or refs[key].get("optional"): + bad(f"{comp}@{env} resolves {key} from {ref or 'nowhere'} — not the site's workspace and project, required") + # The WordPress URL: this environment's, the product's, and BEST-EFFORT — + # a key nobody has stored is skipped, so the unconnected site still deploys. + for key, secret in (("WORDPRESS_URL", "WORDPRESS_URL"),): + r = refs.get(key) or {} + if r.get("ref") != f"secret://{ws}/{repo}/{env}/{secret}" or r.get("optional") is not True: + bad(f"{comp}@{env} resolves {key} as {r or 'nothing'} — want the optional secret://{ws}/{repo}/{env}/{secret}") + hard = sorted(k for k, r in refs.items() if not r.get("optional") and "WORDPRESS" in k) + if hard: + bad(f"{comp}@{env} requires {hard}, which no bootstrap stores") +if problems: + for p in problems: + print(f" ✕ {p}", file=sys.stderr) + sys.exit(1) +print(f" {order}; web → stage + prod, deploy, side by side; structure check before the build;") +print(f" Worker, smoke and Cloudflare secrets the site's own; the WordPress URL's ref optional") +PY + +# ── 5. a resume over the finished site ───────────────────────────────────── +echo "── --resume over the finished site" +before="$(git -C "$tree" status --porcelain; git -C "$tree" rev-parse HEAD)" +orun new --blueprint "$root/repo-blueprint.yaml" --out "$tree" --resume "${sets[@]}" > "$scratch/resume.log" 2>&1 \ + || { fail "--resume did not run"; tail -10 "$scratch/resume.log" >&2; } +after="$(git -C "$tree" status --porcelain; git -C "$tree" rev-parse HEAD)" +[ "$before" = "$after" ] || { fail "--resume changed the finished site:"; git -C "$tree" status --short | head -10 >&2; } +grep -q "SITE_NAME = \"Sam's Notes & Links\";" "$tree/apps/web/site.config.ts" \ + || fail "--resume reverted the site's identity" +[ "$fails" -eq 0 ] && echo " nothing placed again, nothing un-branded" + +[ "$fails" -eq 0 ] || { echo "placement.test.sh: $fails failure(s)" >&2; exit 1; } +echo "placement.test.sh: ok" diff --git a/testing/rebrand.test.sh b/testing/rebrand.test.sh new file mode 100755 index 0000000..1658f3e --- /dev/null +++ b/testing/rebrand.test.sh @@ -0,0 +1,202 @@ +#!/usr/bin/env bash +# THE REBRAND WRITES EACH VALUE ONCE, AND WHAT IT WROTE STAYS WRITTEN. +# +# Drives the real tooling/rebrand/rebrand.mjs over one-file trees and compares +# the file. Each case is a shape this baseline's identity actually takes in the +# tree — a source link, the site-name seam, the Worker name in wrangler.jsonc +# and the component, the intent's environment URLs, the placeholder domain, the +# WordPress secret ref, and the upstream template's own name, which is its +# credit and must NOT be renamed — and each can run through several passes (a re-run of a phase +# re-runs the rebrand over everything already placed, and 02-docs's heal runs +# it again), so a value written by one pass must survive every later one. +# +# The identity is PINNED (fixtures/baseline-identity.cms-wordpress.json) rather than +# read from .baseline/identity.json: what this tests is the engine, and its +# fixtures spell the identity out literally. +# +# Needs: node, git. No network. +set -euo pipefail +here="$(cd "$(dirname "$0")" && pwd)" +rebrand="$here/../tooling/rebrand/rebrand.mjs" +identity="$here/fixtures/baseline-identity.cms-wordpress.json" + +fail=0 +# check NAME VALUES-JSON FILE CONTENT WANT [PASSES] +check() { + local name="$1" values="$2" file="$3" content="$4" want="$5" passes="${6:-1}" + local tmp got out i + tmp="$(mktemp -d)" + git -C "$tmp" init -q + mkdir -p "$tmp/$(dirname "$file")" "$tmp/.rebrand" + printf '%s\n' "$content" > "$tmp/$file" + printf '%s\n' "$values" > "$tmp/.rebrand/values.json" + for ((i = 1; i <= passes; i++)); do + git -C "$tmp" add -A + if ! out="$(cd "$tmp" && node "$rebrand" --baseline-identity "$identity" --values .rebrand/values.json --allow-dirty 2>&1)"; then + echo " ✕ $name: rebrand pass $i failed:" >&2 + printf '%s\n' "$out" | sed 's/^/ /' >&2 + fail=1 + rm -rf "$tmp" + return + fi + done + got="$(cat "$tmp/$file")" + rm -rf "$tmp" + if [ "$got" = "$want" ]; then + echo " ok $name" + else + echo " ✕ $name:" >&2 + echo " got: $got" >&2 + echo " want: $want" >&2 + fail=1 + fi +} + +acme='{"reponame":"acme-notes","productname":"Acme Notes","productdomain":"acme.dev","githuborg":"acme-inc","subdomain":"acme","orunWorkspace":"ws_79BDXAZQ"}' + +echo "── rebrand: the site's own identity" +check "a source link names the product's owner and repository" \ + "$acme" README.md \ + 'See https://github.com/sourceplane/cms-wordpress for the source.' \ + 'See https://github.com/acme-inc/acme-notes for the source.' +check "the site-name seam takes the product's name" \ + "$acme" apps/web/site.config.ts 'export const SITE_NAME = "next-wp";' \ + 'export const SITE_NAME = "Acme Notes";' +check "…and stays a valid string for a name with an apostrophe and an ampersand" \ + '{"reponame":"sams-notes","productname":"Sam'"'"'s Notes & Links","productdomain":"sam.dev"}' \ + apps/web/site.config.ts 'export const SITE_NAME = "next-wp";' \ + 'export const SITE_NAME = "Sam'"'"'s Notes & Links";' +check "the template's name elsewhere is its credit, and is left alone" \ + "$acme" apps/web/app/page.tsx 'This is <a href="https://github.com/9d8dev/next-wp">next-wp</a>,' \ + 'This is <a href="https://github.com/9d8dev/next-wp">next-wp</a>,' +check "the Worker name in wrangler.jsonc is re-prefixed" \ + "$acme" apps/web/wrangler.jsonc ' "name": "cms-wordpress-web",' \ + ' "name": "acme-notes-web",' +check "the component's worker name is re-prefixed, the environment suffix kept" \ + "$acme" apps/web/component.yaml ' workerName: cms-wordpress-web' \ + ' workerName: acme-notes-web' +check "the workers.dev subdomain in the component" \ + "$acme" apps/web/component.yaml ' workersDevSubdomain: your-workers-subdomain' \ + ' workersDevSubdomain: acme' +check "an environment URL in the intent" \ + "$acme" intent.yaml ' url: https://cms-wordpress-web-prod.your-workers-subdomain.workers.dev' \ + ' url: https://acme-notes-web-prod.acme.workers.dev' +check "the placeholder domain is the product's domain, not a renamed slug" \ + "$acme" intent.yaml ' BASE_DOMAIN: cms-wordpress.example.com' \ + ' BASE_DOMAIN: acme.dev' +check "no domain given: the reserved placeholder, for an owner to replace later" \ + '{"reponame":"acme-notes","productname":"Acme Notes","githuborg":"acme-inc","subdomain":"acme"}' \ + intent.yaml ' BASE_DOMAIN: cms-wordpress.example.com' \ + ' BASE_DOMAIN: acme-notes.example.com' +check "an empty domain is no domain" \ + '{"reponame":"acme-notes","productname":"Acme Notes","productdomain":""}' \ + intent.yaml ' BASE_DOMAIN: cms-wordpress.example.com' \ + ' BASE_DOMAIN: acme-notes.example.com' +check "the repo slug" \ + "$acme" package.json ' "name": "cms-wordpress",' \ + ' "name": "acme-notes",' +check "the WordPress secret ref names the product's workspace and project, the environment kept" \ + "$acme" apps/web/component.yaml \ + ' WORDPRESS_URL: "secret://cms-wordpress/cms-wordpress/{{ .environment }}/WORDPRESS_URL"' \ + ' WORDPRESS_URL: "secret://ws_79BDXAZQ/acme-notes/{{ .environment }}/WORDPRESS_URL"' +check "the WordPress variable names are the template's, and are left alone" \ + "$acme" apps/web/.env.example 'WORDPRESS_URL=' \ + 'WORDPRESS_URL=' +check "org-owned identity is not renamed" \ + "$acme" intent.yaml 'apiVersion: sourceplane.io/v1 # mail ops@sourceplane.ai' \ + 'apiVersion: sourceplane.io/v1 # mail ops@sourceplane.ai' +check "without githuborg a source link keeps the baseline's owner" \ + '{"reponame":"acme-notes","productname":"Acme Notes","productdomain":"acme.dev"}' \ + README.md 'https://github.com/sourceplane/cms-wordpress' \ + 'https://github.com/sourceplane/acme-notes' + +echo "── rebrand: a written value is not rewritten, in any later pass" +contains='{"reponame":"cms-wordpress-2","productname":"next-wp 2","productdomain":"cms-wordpress.example.com.au","githuborg":"sourceplane","subdomain":"your-workers-subdomain-2"}' +check "a repo slug containing the baseline's slug survives three passes" \ + "$contains" package.json ' "name": "cms-wordpress",' \ + ' "name": "cms-wordpress-2",' 3 +check "a Worker name built on it survives three passes" \ + "$contains" apps/web/wrangler.jsonc ' "name": "cms-wordpress-web",' \ + ' "name": "cms-wordpress-2-web",' 3 +check "a domain containing the baseline's domain survives three passes" \ + "$contains" intent.yaml 'BASE_DOMAIN: cms-wordpress.example.com' \ + 'BASE_DOMAIN: cms-wordpress.example.com.au' 3 +check "a subdomain containing the placeholder survives three passes" \ + "$contains" intent.yaml ' url: https://cms-wordpress-web-stage.your-workers-subdomain.workers.dev' \ + ' url: https://cms-wordpress-2-web-stage.your-workers-subdomain-2.workers.dev' 3 +check "a site name containing the baseline's name survives three passes" \ + "$contains" apps/web/site.config.ts 'export const SITE_NAME = "next-wp";' \ + 'export const SITE_NAME = "next-wp 2";' 3 +check "the template's credit survives three passes of a slug and a name that contain the baseline's" \ + "$contains" apps/web/app/page.tsx 'This is <a href="https://github.com/9d8dev/next-wp">next-wp</a>,' \ + 'This is <a href="https://github.com/9d8dev/next-wp">next-wp</a>,' 3 +# The fixture the placement and end-to-end gates build with: a slug that ENDS +# in the baseline's, so its Worker is `<…>-cms-wordpress-web`. +suffixed='{"reponame":"acme-cms-wordpress","productname":"Acme","productdomain":"www.acme.dev","githuborg":"acme-inc","subdomain":"acme","orunWorkspace":"ws_79BDXAZQ"}' +check "a repo slug ending in the baseline's slug survives three passes" \ + "$suffixed" package.json ' "name": "cms-wordpress",' \ + ' "name": "acme-cms-wordpress",' 3 +check "…and its Worker name" \ + "$suffixed" apps/web/wrangler.jsonc ' "name": "cms-wordpress-web",' \ + ' "name": "acme-cms-wordpress-web",' 3 +check "…and its secret ref" \ + "$suffixed" apps/web/component.yaml ' WORDPRESS_URL: "secret://cms-wordpress/cms-wordpress/{{ .environment }}/WORDPRESS_URL"' \ + ' WORDPRESS_URL: "secret://ws_79BDXAZQ/acme-cms-wordpress/{{ .environment }}/WORDPRESS_URL"' 3 +# The placement fixture carries no domain (a console build asks for none), and +# its slug's placeholder CONTAINS the baseline's: acme-cms-wordpress.example.com. +nodomain='{"reponame":"acme-cms-wordpress","productname":"Acme","productdomain":"","githuborg":"acme-inc","subdomain":"acme","orunWorkspace":"ws_79BDXAZQ"}' +check "…and, with no domain, its placeholder survives three passes" \ + "$nodomain" intent.yaml ' BASE_DOMAIN: cms-wordpress.example.com' \ + ' BASE_DOMAIN: acme-cms-wordpress.example.com' 3 + +# --verify runs in every phase. Without the product's values it cannot tell +# the product's own identity from a leftover; with them it can. A real +# leftover must fail it either way. +verify() { # NAME VALUES FILE CONTENT WANT(pass|fail) [--values] + local name="$1" values="$2" file="$3" content="$4" want="$5" withvalues="${6:-}" tmp got + tmp="$(mktemp -d)" + git -C "$tmp" init -q + mkdir -p "$tmp/$(dirname "$file")" "$tmp/.rebrand" + printf '%s\n' "$content" > "$tmp/$file" + printf '%s\n' "$values" > "$tmp/.rebrand/values.json" + git -C "$tmp" add -A + if (cd "$tmp" && node "$rebrand" --baseline-identity "$identity" --verify ${withvalues:+--values .rebrand/values.json} >/dev/null 2>&1); then got=pass; else got=fail; fi + rm -rf "$tmp" + if [ "$got" = "$want" ]; then echo " ok $name"; else echo " ✕ $name: --verify ${got}ed, want $want" >&2; fail=1; fi +} +echo "── rebrand --verify: the product's own identity is not residue" +verify "given the values, a slug containing the baseline's passes" \ + "$contains" package.json '"name": "cms-wordpress-2"' pass --values +verify "without them it cannot know, and fails" \ + "$contains" package.json '"name": "cms-wordpress-2"' fail +verify "given the values, a slug ending in the baseline's passes" \ + "$suffixed" apps/web/wrangler.jsonc '"name": "acme-cms-wordpress-web"' pass --values +verify "given the values, a placeholder domain containing the baseline's passes" \ + "$nodomain" intent.yaml 'BASE_DOMAIN: acme-cms-wordpress.example.com' pass --values +verify "the upstream template's link is not residue" \ + "$acme" apps/web/app/page.tsx 'href="https://github.com/9d8dev/next-wp/blob/main/README.md"' pass --values +verify "given the values, a real leftover still fails" \ + "$acme" package.json '"name": "cms-wordpress"' fail --values +verify "a leftover Worker name fails" \ + "$acme" apps/web/wrangler.jsonc '"name": "cms-wordpress-web"' fail --values +verify "a leftover link to another repository named like it fails" \ + "$acme" README.md 'https://github.com/acme-inc/cms-wordpress' fail --values +verify "a leftover code identifier fails (no rule renames it — so nothing may spell it)" \ + "$acme" apps/web/x.ts 'export class CmsWordpress {}' fail --values +verify "a clean product passes" \ + "$acme" package.json '"name": "acme-notes"' pass --values + +echo "── rebrand: a residue it cannot rename fails the rebrand itself" +tmp="$(mktemp -d)"; git -C "$tmp" init -q; mkdir -p "$tmp/.rebrand" "$tmp/apps/web" +printf '%s\n' "$acme" > "$tmp/.rebrand/values.json" +printf 'const x = "CMS_WORDPRESS_TOKEN"\n' > "$tmp/apps/web/x.ts" +git -C "$tmp" add -A +if (cd "$tmp" && node "$rebrand" --baseline-identity "$identity" --values .rebrand/values.json --allow-dirty >/dev/null 2>&1); then + echo " ✕ an unrenamable env-var prefix passed the rebrand" >&2; fail=1 +else + echo " ok an unrenamable env-var prefix fails the rebrand, naming the file" +fi +rm -rf "$tmp" + +[ "$fail" -eq 0 ] || exit 1 +echo "rebrand.test.sh: ok" diff --git a/testing/retouch.test.sh b/testing/retouch.test.sh new file mode 100755 index 0000000..1ef5d69 --- /dev/null +++ b/testing/retouch.test.sh @@ -0,0 +1,199 @@ +#!/usr/bin/env bash +# A RE-RUN PHASE HAS SOMETHING TO LAND. +# +# A phase's convergence can fail AFTER its PR merged, and the merge has already +# put every file the phase places on main. orun derives phase state from the +# files, so a retried build sees the phase placed and a forced re-run of it +# lands an EMPTY diff — and the product's CI plans `--changed`, so a component +# whose files did not change in the push does not deploy. The phase's `retouch` +# hook (tooling/bootstrap/retouch.mjs) is what breaks that: one marker line at +# the end of each affected component.yaml, +# +# # orun: redeploy <phase> <stamp> +# +# replaced rather than accumulated, so the landing has a diff and exactly the +# phase's components are in the changed set. The marker is a deploy trigger and +# nothing reads it back; phase state stays derived, never stored. +# +# This drives the real retouch.mjs over a two-component tree, then checks that +# every component the blueprint's retouch hooks name resolves in THIS tree — +# the layout a product is placed with. +# Needs: node. No network. +set -euo pipefail +here="$(cd "$(dirname "$0")" && pwd)" +root="$(cd "$here/.." && pwd)" +retouch="$root/tooling/bootstrap/retouch.mjs" + +command -v node >/dev/null || { echo "retouch.test.sh needs node" >&2; exit 1; } + +fail=0 +ok() { echo " ok $*"; } +bad() { echo " ✕ $*" >&2; fail=1; } + +tmp="$(mktemp -d)" +trap 'rm -rf "$tmp"' EXIT + +# A product tree with two components in two of the lanes the blueprint places +# into, a test package that shares a directory name with the first (as +# tests/<worker> does with apps/<worker>) and must NOT be touched, and the +# hand-written re-trigger line the fleet carried before this tool existed. +mkdir -p "$tmp/apps/alpha" "$tmp/infra/beta" "$tmp/tests/alpha" "$tmp/node_modules/x" +cat > "$tmp/apps/alpha/component.yaml" <<'Y' +apiVersion: sourceplane.io/v1 +kind: Component +metadata: + name: alpha +spec: + type: cloudflare-worker-turbo + labels: + team: platform +# ci: re-trigger deploy (batch A — runner-starvation recovery 20260622T115650Z) +Y +# No trailing newline on purpose: the tool must add one, and only one. +printf 'apiVersion: sourceplane.io/v1\nkind: Component\nmetadata:\n name: beta\nspec:\n type: terraform' > "$tmp/infra/beta/component.yaml" +printf 'kind: Component\nmetadata:\n name: alpha-tests\n' > "$tmp/tests/alpha/component.yaml" +printf 'kind: Component\nmetadata:\n name: alpha\n' > "$tmp/node_modules/x/component.yaml" +cp "$tmp/apps/alpha/component.yaml" "$tmp/alpha.orig" +cp "$tmp/infra/beta/component.yaml" "$tmp/beta.orig" + +markers() { grep -c '^# orun: redeploy ' "$1" || true; } + +echo "── retouch: one marker, last, replaced not appended" +(cd "$tmp" && ORUN_RUN_ID=run-one node "$retouch" --phase 04-workers --components alpha,beta) > "$tmp/one.log" 2>&1 \ + || { bad "first run failed:"; sed 's/^/ /' "$tmp/one.log" >&2; } +for f in apps/alpha infra/beta; do + [ "$(markers "$tmp/$f/component.yaml")" = 1 ] || bad "$f: $(markers "$tmp/$f/component.yaml") marker lines after one run, want 1" + [ "$(tail -n1 "$tmp/$f/component.yaml")" = "# orun: redeploy 04-workers run-one" ] \ + || bad "$f: last line is '$(tail -n1 "$tmp/$f/component.yaml")'" +done +[ "$(tail -c1 "$tmp/infra/beta/component.yaml" | od -An -c | tr -d ' ')" = '\n' ] \ + || bad "infra/beta: no trailing newline after retouch" +ok "both components carry the marker as their last line" + +(cd "$tmp" && ORUN_RUN_ID=run-two node "$retouch" --phase 04-workers-restore --components alpha,beta) > "$tmp/two.log" 2>&1 \ + || { bad "second run failed:"; sed 's/^/ /' "$tmp/two.log" >&2; } +for f in apps/alpha infra/beta; do + [ "$(markers "$tmp/$f/component.yaml")" = 1 ] || bad "$f: $(markers "$tmp/$f/component.yaml") marker lines after two runs — the marker accumulated" + [ "$(tail -n1 "$tmp/$f/component.yaml")" = "# orun: redeploy 04-workers-restore run-two" ] \ + || bad "$f: second run did not replace the marker: '$(tail -n1 "$tmp/$f/component.yaml")'" +done +grep -q 'replace marker' "$tmp/two.log" || bad "second run did not report a replacement" +ok "a second run replaces the marker (a different phase's too) rather than appending" + +echo "── retouch: every other byte is as it was" +if [ "$(head -n -1 "$tmp/apps/alpha/component.yaml" | cksum)" = "$(cksum < "$tmp/alpha.orig")" ]; then + ok "apps/alpha: the file above the marker is byte-for-byte the original" +else + bad "apps/alpha: bytes above the marker changed" + diff <(head -n -1 "$tmp/apps/alpha/component.yaml") "$tmp/alpha.orig" >&2 || true +fi +if [ "$(head -n -1 "$tmp/infra/beta/component.yaml" | cksum)" = "$(printf '%s\n' "$(cat "$tmp/beta.orig")" | cksum)" ]; then + ok "infra/beta: only a newline was added before the marker" +else + bad "infra/beta: bytes above the marker changed" +fi +grep -q '^# ci: re-trigger deploy' "$tmp/apps/alpha/component.yaml" \ + && ok "the hand-written re-trigger line is left alone" \ + || bad "the hand-written re-trigger line was removed" +[ "$(cat "$tmp/tests/alpha/component.yaml")" = "$(printf 'kind: Component\nmetadata:\n name: alpha-tests\n')" ] \ + && ok "tests/alpha (alpha-tests) was not touched — components resolve by metadata.name" \ + || bad "tests/alpha was touched: a component is its metadata.name, not its directory name" + +echo "── retouch: the same stamp twice is a no-op" +(cd "$tmp" && ORUN_RUN_ID=run-two node "$retouch" --phase 04-workers-restore --components alpha,beta) > "$tmp/again.log" 2>&1 \ + || bad "idempotent re-run failed" +grep -q 'nothing to do' "$tmp/again.log" && ok "re-running with the same stamp reports nothing to do" \ + || bad "re-running with the same stamp did not report a no-op: $(tail -1 "$tmp/again.log")" + +echo "── retouch: the stamp" +(cd "$tmp" && env -u ORUN_RUN_ID ORUN_SESSION_ID=sess-9 node "$retouch" --phase p --components beta) >/dev/null 2>&1 +[ "$(tail -n1 "$tmp/infra/beta/component.yaml")" = "# orun: redeploy p sess-9" ] \ + && ok "ORUN_SESSION_ID stamps when ORUN_RUN_ID is unset" \ + || bad "ORUN_SESSION_ID was not used: '$(tail -n1 "$tmp/infra/beta/component.yaml")'" +(cd "$tmp" && env -u ORUN_RUN_ID -u ORUN_SESSION_ID node "$retouch" --phase p --components beta) >/dev/null 2>&1 +tail -n1 "$tmp/infra/beta/component.yaml" | grep -Eq '^# orun: redeploy p [0-9]{8}T[0-9]{6}Z$' \ + && ok "with neither, a UTC timestamp" \ + || bad "no timestamp stamp: '$(tail -n1 "$tmp/infra/beta/component.yaml")'" + +echo "── retouch: --dry-run writes nothing, --check names what is missing" +before="$(cksum < "$tmp/apps/alpha/component.yaml")" +(cd "$tmp" && ORUN_RUN_ID=dry node "$retouch" --phase p --components alpha --dry-run) > "$tmp/dry.log" 2>&1 \ + || bad "--dry-run failed" +[ "$before" = "$(cksum < "$tmp/apps/alpha/component.yaml")" ] && grep -q 'would replace marker' "$tmp/dry.log" \ + && ok "--dry-run reports the change and leaves the file alone" \ + || bad "--dry-run wrote, or did not say what it would do" + +if (cd "$tmp" && node "$retouch" --phase p --components alpha,gamma --check) > "$tmp/check.log" 2>&1; then + bad "--check passed with gamma absent" +else + grep -q 'gamma' "$tmp/check.log" && ok "--check fails and names gamma" \ + || bad "--check failed without naming the missing component: $(cat "$tmp/check.log")" +fi +if (cd "$tmp" && ORUN_RUN_ID=x node "$retouch" --phase p --components alpha,gamma) > "$tmp/miss.log" 2>&1; then + bad "a run with a missing component succeeded" +else + [ "$(tail -n1 "$tmp/apps/alpha/component.yaml")" != "# orun: redeploy p x" ] \ + && ok "a missing component refuses the whole run before any file is written" \ + || bad "a missing component still wrote the components that exist" +fi +(cd "$tmp" && node "$retouch" --phase p --components alpha,beta --check) >/dev/null 2>&1 \ + && ok "--check passes when every component resolves" || bad "--check failed on a complete set" + +echo "── retouch: --affects reads a task contract" +cat > "$tmp/contract.yaml" <<'Y' +# A contract, as .baseline/tasks/*.TaskContract.yaml are written. +apiVersion: orun.io/v1 +kind: TaskContract +spec: + goal: Two components converge + affects: + - alpha + # a comment between items + - beta + doneWhen: + - convergence green + gates: [] +Y +(cd "$tmp" && ORUN_RUN_ID=via-contract node "$retouch" --phase 05-edge --affects contract.yaml) > "$tmp/aff.log" 2>&1 \ + || { bad "--affects run failed:"; sed 's/^/ /' "$tmp/aff.log" >&2; } +for f in apps/alpha infra/beta; do + [ "$(tail -n1 "$tmp/$f/component.yaml")" = "# orun: redeploy 05-edge via-contract" ] \ + || bad "$f: --affects did not touch it" +done +grep -q '2 of 2' "$tmp/aff.log" && ok "spec.affects named both, and both were touched" \ + || bad "--affects touched the wrong number: $(tail -1 "$tmp/aff.log")" +printf 'spec:\n affects: [alpha, beta]\n' > "$tmp/flow.yaml" +(cd "$tmp" && ORUN_RUN_ID=flow node "$retouch" --phase p --affects flow.yaml --check) >/dev/null 2>&1 \ + && ok 'the flow form `affects: [a, b]` reads too' || bad "the flow form of affects did not read" +printf 'spec:\n goal: nothing\n' > "$tmp/none.yaml" +(cd "$tmp" && node "$retouch" --phase p --affects none.yaml --check) >/dev/null 2>&1 \ + && bad "a contract with no affects passed --check" || ok "a contract with no affects refuses" + +# ── THE BLUEPRINT'S OWN HOOKS RESOLVE IN THIS TREE ───────────────────────── +# Every `retouch` hook in repo-blueprint.yaml names the components a phase +# redeploys, through a contract (.baseline/tasks/) or a list. A product is placed with this +# repository's layout, so each must resolve here — a contract that names a +# component nobody ships, or a component that moved, fails a real bootstrap at +# the landing, an hour in. `{{ .baseline.dir }}` is this checkout. +echo "── the blueprint's retouch hooks, against this tree" +hooks=0 +while IFS= read -r line; do + hooks=$((hooks + 1)) + argv="$(printf '%s' "$line" | sed -e 's/^[[:space:]]*run:[[:space:]]*//' \ + -e "s#{{ \.baseline\.dir }}#$root#g" -e 's#{{ \.phase\.name }}#probe#g')" + if (cd "$root" && node -e ' + const argv = JSON.parse(process.argv[1]); + const { spawnSync } = require("node:child_process"); + const r = spawnSync(argv[0], [...argv.slice(1), "--check"], { stdio: ["ignore", "pipe", "pipe"] }); + process.stdout.write(r.stdout); process.stderr.write(r.stderr); + process.exit(r.status ?? 1); + ' "$argv") > "$tmp/hook.log" 2>&1; then + ok "$(grep -c -- '->' "$tmp/hook.log") component(s): ${argv#*retouch.mjs\", }" + else + bad "a retouch hook does not resolve: $argv"; sed 's/^/ /' "$tmp/hook.log" >&2 + fi +done < <(grep -E '^\s*run: \[.*retouch\.mjs' "$root/repo-blueprint.yaml") +[ "$hooks" -ge 1 ] || bad "only $hooks retouch hook(s) in repo-blueprint.yaml — 01-product lands the deployable product and needs one" + +[ "$fail" -eq 0 ] || exit 1 +echo "retouch.test.sh: ok" diff --git a/tooling/bootstrap/dev-lanes.mjs b/tooling/bootstrap/dev-lanes.mjs new file mode 100755 index 0000000..27e4f84 --- /dev/null +++ b/tooling/bootstrap/dev-lanes.mjs @@ -0,0 +1,114 @@ +#!/usr/bin/env node +// The dev verify lanes stay off main's convergences while a product is being +// bootstrapped (zero-dependency). +// +// intent.yaml activates `dev` on `github-push-main` as well as on pull +// requests: every merge to main re-verifies every component (builds, tests) +// on the dev rung beside the stage and prod deploys. That is the right rule +// for a product that is live. During a bootstrap it proves nothing — the +// content comes from a pinned baseline whose own CI already ran it, and +// every phase's pull request is checked by `plan` alone — and it costs the +// one thing a bootstrap's wall-clock is made of: runner slots. The product's +// landing is a Next.js build per deployed environment; a third, on the dev +// rung (and its tests beside it), re-proves what the baseline's own CI +// already proved and competes with stage and prod for the runner pool. +// (Measured on the Cirrus baseline, where this tool comes from: dev took +// eight of eighteen lanes and stage and prod got five each.) +// +// So 01-product defers the trigger and 02-docs, the last landing, puts it +// back, exactly as tooling/bootstrap/promotion.mjs does for prod's gate: +// +// node tooling/bootstrap/dev-lanes.mjs --defer # 01-product, before the first landing +// node tooling/bootstrap/dev-lanes.mjs --restore # 02-docs, the last landing +// node tooling/bootstrap/dev-lanes.mjs --check # prints deferred | active +// +// --defer replaces dev's `- github-push-main` trigger line with one marker +// comment that base64-encodes the exact text removed, so --restore +// reproduces intent.yaml byte-for-byte. Both are idempotent. Pull requests +// keep their dev lanes throughout: only the push-to-main activation moves. +// +// The trigger is deferred, never dropped: a bootstrap that stops before +// 02-docs leaves the marker in intent.yaml, and `--restore` (or a re-run of +// 02-docs) is the whole fix. +import * as fs from "node:fs"; + +const FILE = process.argv.includes("--file") + ? process.argv[process.argv.indexOf("--file") + 1] + : "intent.yaml"; +const MARKER = "@dev-lanes-deferred"; +const TRIGGER = "github-push-main"; + +function usage() { + console.error("usage: dev-lanes.mjs --defer | --restore | --check [--file intent.yaml]"); + process.exit(2); +} + +// The `- github-push-main` line under environments.dev.activation.triggerRefs. +function findDevPushTrigger(text) { + const lines = text.split("\n"); + let inEnvs = false; + let devIndent = -1; + let inDev = false; + for (let i = 0; i < lines.length; i++) { + const line = lines[i]; + if (/^environments:\s*$/.test(line)) { + inEnvs = true; + continue; + } + if (!inEnvs) continue; + if (/^\S/.test(line) && line.trim() !== "") break; // left the section + const env = /^(\s+)([A-Za-z0-9_-]+):\s*$/.exec(line); + if (env && (devIndent < 0 || env[1].length <= devIndent)) { + inDev = env[2] === "dev"; + if (inDev) devIndent = env[1].length; + continue; + } + if (!inDev) continue; + if (new RegExp(`^\\s+-\\s+${TRIGGER}\\s*$`).test(line)) return { lines, index: i }; + } + return { lines, index: -1 }; +} + +function defer() { + const text = fs.readFileSync(FILE, "utf8"); + if (text.includes(`# ${MARKER}:`)) { + console.log(`dev-lanes --defer: already deferred in ${FILE}`); + return; + } + const { lines, index } = findDevPushTrigger(text); + if (index < 0) { + console.log(`dev-lanes --defer: dev is not activated on ${TRIGGER} in ${FILE} — nothing to defer`); + return; + } + const original = lines[index]; + const indent = /^(\s*)/.exec(original)[1]; + const b64 = Buffer.from(original, "utf8").toString("base64"); + const marker = `${indent}# ${MARKER}:${b64} (tooling/bootstrap/dev-lanes.mjs --restore puts it back)`; + const out = [...lines.slice(0, index), marker, ...lines.slice(index + 1)].join("\n"); + fs.writeFileSync(FILE, out); + console.log(`dev-lanes --defer: dev's verify lanes stay off main's convergences until --restore (${FILE})`); +} + +function restore() { + const text = fs.readFileSync(FILE, "utf8"); + const re = new RegExp(`^[ \\t]*# ${MARKER}:([A-Za-z0-9+/=]+) \\(tooling/bootstrap/dev-lanes\\.mjs --restore puts it back\\)$`, "m"); + const m = re.exec(text); + if (!m) { + console.log(`dev-lanes --restore: nothing deferred in ${FILE}`); + return; + } + const original = Buffer.from(m[1], "base64").toString("utf8"); + fs.writeFileSync(FILE, text.slice(0, m.index) + original + text.slice(m.index + m[0].length)); + console.log(`dev-lanes --restore: dev verifies every merge to main again (${FILE})`); +} + +function check() { + const text = fs.readFileSync(FILE, "utf8"); + console.log(text.includes(`# ${MARKER}:`) ? "deferred" : "active"); +} + +const mode = process.argv[2]; +if (mode === "--defer") defer(); +else if (mode === "--restore") restore(); +else if (mode === "--check") check(); +else usage(); diff --git a/tooling/bootstrap/promotion.mjs b/tooling/bootstrap/promotion.mjs new file mode 100755 index 0000000..ec8f4f5 --- /dev/null +++ b/tooling/bootstrap/promotion.mjs @@ -0,0 +1,123 @@ +#!/usr/bin/env node +// Stage and prod deploy side by side while a product is being bootstrapped +// (zero-dependency). +// +// intent.yaml gates prod behind stage: `environments.prod.promotion.dependsOn: +// [stage]`, which orun plans as an in-run edge from every prod job to the +// same component's stage job. That is the right rule for a product that is +// live — a change reaches prod only after it deployed to stage. During a +// bootstrap it protects nothing (both environments are empty, and every phase +// is watched to green before the next one starts) and it doubles the length +// of every convergence: each worker's prod deploy waits out its stage deploy. +// +// So 01-product defers the gate and 02-docs, the last landing, puts it back: +// +// node tooling/bootstrap/promotion.mjs --defer # 01-product, before the first landing +// node tooling/bootstrap/promotion.mjs --restore # 02-docs, the last landing +// node tooling/bootstrap/promotion.mjs --check # prints deferred | enforced +// +// --defer replaces the prod `promotion:` block with one marker comment that +// base64-encodes the exact text removed, so --restore reproduces intent.yaml +// byte-for-byte. Both are idempotent. Restoring is a change to intent.yaml's +// `environments` section only, which `orun plan --changed` (intent impact +// `watch`, the default) maps to no component: the landing that restores it +// deploys nothing. +// +// The gate is deferred, never dropped: a bootstrap that stops before 02-docs +// leaves the marker in intent.yaml, and `--restore` (or a re-run of 02-docs) +// is the whole fix. docs/phases/02-docs.md says so. + +import * as fs from "node:fs"; + +const FILE = process.argv.includes("--file") + ? process.argv[process.argv.indexOf("--file") + 1] + : "intent.yaml"; +const MARKER = "@promotion-deferred"; + +function usage() { + console.error("usage: promotion.mjs --defer | --restore | --check [--file intent.yaml]"); + process.exit(2); +} + +// The `promotion:` block of the `prod:` environment: from its `promotion:` +// line up to (not including) the next line indented at or above it. +function findProdPromotion(text) { + const lines = text.split("\n"); + let inEnvs = false; + let prodIndent = -1; + for (let i = 0; i < lines.length; i++) { + const line = lines[i]; + if (/^environments:\s*$/.test(line)) { + inEnvs = true; + continue; + } + if (!inEnvs) continue; + if (/^\S/.test(line) && line.trim() !== "") break; // left the section + const prod = /^(\s+)prod:\s*$/.exec(line); + if (prod) { + prodIndent = prod[1].length; + continue; + } + if (prodIndent < 0) continue; + const indent = line.length - line.trimStart().length; + if (line.trim() !== "" && indent <= prodIndent) { + prodIndent = -1; // left prod without finding one + continue; + } + const m = /^(\s+)promotion:\s*$/.exec(line); + if (!m) continue; + const own = m[1].length; + let end = i + 1; + while (end < lines.length) { + const l = lines[end]; + if (l.trim() !== "" && l.length - l.trimStart().length <= own) break; + end++; + } + return { lines, start: i, end, indent: m[1] }; + } + return null; +} + +function defer() { + const text = fs.readFileSync(FILE, "utf8"); + if (text.includes(MARKER)) { + console.log(`promotion --defer: already deferred in ${FILE}`); + return; + } + const found = findProdPromotion(text); + if (!found) { + console.log(`promotion --defer: prod has no promotion block in ${FILE} — nothing to defer`); + return; + } + const { lines, start, end, indent } = found; + const removed = lines.slice(start, end).join("\n"); + const b64 = Buffer.from(removed, "utf8").toString("base64"); + const marker = `${indent}# ${MARKER}:${b64} (tooling/bootstrap/promotion.mjs --restore puts it back)`; + const out = [...lines.slice(0, start), marker, ...lines.slice(end)].join("\n"); + fs.writeFileSync(FILE, out); + console.log(`promotion --defer: prod no longer waits on stage until --restore (${FILE})`); +} + +function restore() { + const text = fs.readFileSync(FILE, "utf8"); + const re = new RegExp(`^[ \\t]*# ${MARKER}:([A-Za-z0-9+/=]+).*$`, "m"); + const m = re.exec(text); + if (!m) { + console.log(`promotion --restore: nothing deferred in ${FILE}`); + return; + } + const original = Buffer.from(m[1], "base64").toString("utf8"); + fs.writeFileSync(FILE, text.slice(0, m.index) + original + text.slice(m.index + m[0].length)); + console.log(`promotion --restore: prod waits on stage again (${FILE})`); +} + +function check() { + const text = fs.readFileSync(FILE, "utf8"); + console.log(text.includes(MARKER) ? "deferred" : "enforced"); +} + +const mode = process.argv[2]; +if (mode === "--defer") defer(); +else if (mode === "--restore") restore(); +else if (mode === "--check") check(); +else usage(); diff --git a/tooling/bootstrap/retouch.mjs b/tooling/bootstrap/retouch.mjs new file mode 100755 index 0000000..26c31b2 --- /dev/null +++ b/tooling/bootstrap/retouch.mjs @@ -0,0 +1,254 @@ +#!/usr/bin/env node +// Give a re-run phase something to land (zero-dependency). +// +// A phase lands as a pull request and is verified by the convergence run that +// follows the merge. When that convergence FAILS — a provider error, a runner +// starved out, a smoke that raced route propagation past its retries — the +// merge has already happened, so every file the phase places is on main. orun +// derives phase state from the files on disk (never from a stored record), so +// a retried build finds the phase placed, and even a forced re-run of it +// produces an EMPTY diff: `orun.pr/land@v1` has nothing to commit, and the +// product's CI (`orun plan --changed`) deploys a component only when one of +// its files changed in the push. Nothing lands, nothing redeploys, and the +// operator is told the phase is fine. +// +// This tool is what the phase's `retouch` hook runs before it stages and +// lands: for each component the phase deploys, it rewrites ONE trailing line +// in that component's `component.yaml`, +// +// # orun: redeploy <phase> <stamp> +// +// replacing the previous marker if there is one (never accumulating), so the +// landing has a diff and exactly those components are in the changed set. The +// same convention was hand-edited before this existed (`# ci: re-trigger +// deploy …` lines, duplicated by hand); this is that edit with a name, a +// stamp, and a phase to answer for it. +// +// THE MARKER IS A DEPLOY TRIGGER, NOT STATE. Nothing reads it back: orun does +// not learn from it whether a phase ran, and this repository's invariant — +// phase state is DERIVED from the tree, never stored in it — holds. Delete the +// line and nothing is lost but the next redeploy's reason to happen. +// +// node retouch.mjs --phase 01-product --affects .baseline/tasks/01-product.TaskContract.yaml +// node retouch.mjs --phase 01-product --components web,web-tests +// +// Options: +// --phase <name> the phase the marker names (required) +// --components a,b,c the components to touch, by `metadata.name` … +// --affects <contract> … or read them from a TaskContract's `spec.affects` +// --check resolve every component and exit non-zero naming +// any without a component.yaml; write nothing +// --dry-run print what would change; write nothing +// +// The stamp is ORUN_RUN_ID if set, else ORUN_SESSION_ID, else a UTC timestamp +// (YYYYMMDDTHHMMSSZ) — whichever identifies the run that asked for the deploy. +// +// Runs in the product checkout (the phase hooks' working directory). A +// component is found by the `metadata.name` its component.yaml declares, not +// by directory: `apps/web` and `tests/web` both carry one, and only the +// first is named `web`. + +import * as fs from "node:fs"; +import * as path from "node:path"; + +const MARKER_RE = /^# orun: redeploy \S+ \S+\r?$/; +const SKIP_DIRS = new Set(["node_modules", ".git", ".orun", "dist", ".next", ".open-next", ".turbo"]); +const MAX_DEPTH = 4; + +function usage(msg) { + if (msg) console.error(`retouch: ${msg}`); + console.error( + "usage: retouch.mjs --phase <name> (--components a,b,c | --affects <TaskContract.yaml>) [--check] [--dry-run]", + ); + process.exit(2); +} + +function parseArgs(argv) { + const opts = { phase: null, components: null, affects: null, check: false, dryRun: false }; + for (let i = 0; i < argv.length; i++) { + const a = argv[i]; + const next = () => { + if (i + 1 >= argv.length) usage(`${a} needs a value`); + return argv[++i]; + }; + if (a === "--phase") opts.phase = next(); + else if (a === "--components") opts.components = next(); + else if (a === "--affects") opts.affects = next(); + else if (a === "--check") opts.check = true; + else if (a === "--dry-run") opts.dryRun = true; + else if (a === "-h" || a === "--help") usage(); + else usage(`unknown argument ${a}`); + } + if (!opts.phase) usage("--phase is required"); + if (/\s/.test(opts.phase)) usage("--phase must be a single token"); + if (!opts.components && !opts.affects) usage("one of --components or --affects is required"); + if (opts.components && opts.affects) usage("--components and --affects are exclusive"); + return opts; +} + +// `spec.affects` from a TaskContract, with a reader small enough to need no +// YAML dependency: the contracts are a flat mapping with one block sequence. +// Accepts the block form (`affects:` then `- name` lines indented under it) +// and the flow form (`affects: [a, b]`). +function readAffects(file) { + let text; + try { + text = fs.readFileSync(file, "utf8"); + } catch (e) { + console.error(`retouch: cannot read ${file}: ${e.message}`); + process.exit(1); + } + const lines = text.split(/\r?\n/); + const names = []; + for (let i = 0; i < lines.length; i++) { + const m = /^(\s*)affects:\s*(.*?)\s*$/.exec(lines[i]); + if (!m) continue; + const indent = m[1].length; + const inline = m[2].replace(/\s+#.*$/, ""); + if (inline.startsWith("[")) { + const body = inline.replace(/^\[/, "").replace(/\]\s*$/, ""); + for (const part of body.split(",")) { + const v = part.trim().replace(/^["']|["']$/g, ""); + if (v) names.push(v); + } + break; + } + for (let j = i + 1; j < lines.length; j++) { + const line = lines[j]; + if (/^\s*(#.*)?$/.test(line)) continue; + const lead = /^(\s*)/.exec(line)[1].length; + if (lead <= indent) break; + const item = /^\s*-\s*(.+?)\s*$/.exec(line); + if (!item) break; + names.push(item[1].replace(/\s+#.*$/, "").replace(/^["']|["']$/g, "")); + } + break; + } + if (names.length === 0) { + console.error(`retouch: ${file} declares no spec.affects — nothing to touch`); + process.exit(1); + } + return names; +} + +// `metadata.name` from a component.yaml, read the same minimal way. +function componentName(file) { + const lines = fs.readFileSync(file, "utf8").split(/\r?\n/); + for (let i = 0; i < lines.length; i++) { + const m = /^(\s*)metadata:\s*$/.exec(lines[i]); + if (!m) continue; + const indent = m[1].length; + for (let j = i + 1; j < lines.length; j++) { + const line = lines[j]; + if (/^\s*(#.*)?$/.test(line)) continue; + const lead = /^(\s*)/.exec(line)[1].length; + if (lead <= indent) break; + const nm = /^\s*name:\s*(.+?)\s*$/.exec(line); + if (nm && lead === indent + 2) return nm[1].replace(/^["']|["']$/g, ""); + } + } + return null; +} + +// Every component.yaml in the tree, by the name it declares. +function indexComponents(root) { + const byName = new Map(); + const walk = (dir, depth) => { + let entries; + try { + entries = fs.readdirSync(dir, { withFileTypes: true }); + } catch { + return; + } + for (const ent of entries) { + const full = path.join(dir, ent.name); + if (ent.isDirectory()) { + if (SKIP_DIRS.has(ent.name) || depth >= MAX_DEPTH) continue; + walk(full, depth + 1); + } else if (ent.name === "component.yaml") { + const name = componentName(full); + if (!name) continue; + const rel = path.relative(root, full); + if (byName.has(name)) { + console.error( + `retouch: two component.yaml files declare metadata.name ${name}: ${byName.get(name)} and ${rel}`, + ); + process.exit(1); + } + byName.set(name, rel); + } + } + }; + walk(root, 0); + return byName; +} + +function stamp() { + for (const key of ["ORUN_RUN_ID", "ORUN_SESSION_ID"]) { + const v = (process.env[key] || "").trim(); + if (v) return v.replace(/\s+/g, "-"); + } + return new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z"); +} + +// The file with exactly one marker line, last, and a trailing newline. Every +// other byte is kept as it was. +function retouched(text, marker) { + const hadTrailingNewline = text.endsWith("\n"); + const lines = text.split("\n"); + if (hadTrailingNewline) lines.pop(); + const kept = lines.filter((l) => !MARKER_RE.test(l)); + // A file that was only a marker, or empty, still ends up valid. + const body = kept.length ? kept.join("\n") + "\n" : ""; + return body + marker + "\n"; +} + +function main() { + const opts = parseArgs(process.argv.slice(2)); + const root = process.cwd(); + const wanted = opts.components + ? opts.components.split(",").map((s) => s.trim()).filter(Boolean) + : readAffects(opts.affects); + if (wanted.length === 0) usage("no components named"); + + const index = indexComponents(root); + const missing = wanted.filter((n) => !index.has(n)); + if (missing.length) { + console.error( + `retouch: no component.yaml declares metadata.name for: ${missing.join(", ")} (looked under ${root})`, + ); + process.exit(1); + } + if (opts.check) { + for (const n of wanted) console.log(`retouch --check: ${n} -> ${index.get(n)}`); + console.log(`retouch --check: ${wanted.length} component(s) resolve.`); + return; + } + + const marker = `# orun: redeploy ${opts.phase} ${stamp()}`; + const verb = opts.dryRun ? "would" : ""; + let changed = 0; + for (const n of wanted) { + const rel = index.get(n); + const file = path.join(root, rel); + const before = fs.readFileSync(file, "utf8"); + const after = retouched(before, marker); + const had = before.split("\n").some((l) => MARKER_RE.test(l)); + if (after === before) { + console.log(`retouch: ${rel}: unchanged (marker already ${marker.slice(2)})`); + continue; + } + if (!opts.dryRun) fs.writeFileSync(file, after); + changed++; + console.log(`retouch: ${rel}: ${verb ? "would " : ""}${had ? "replace" : "add"} marker`); + } + console.log( + opts.dryRun + ? `retouch --dry-run: ${changed} of ${wanted.length} file(s) would change; nothing written.` + : changed > 0 + ? `retouch: ${changed} of ${wanted.length} component.yaml file(s) marked "${marker.slice(2)}" — the landing has a diff.` + : `retouch: nothing to do (every marker already current).`, + ); +} + +main(); diff --git a/tooling/bootstrap/work-tree.mjs b/tooling/bootstrap/work-tree.mjs new file mode 100755 index 0000000..ad48ba6 --- /dev/null +++ b/tooling/bootstrap/work-tree.mjs @@ -0,0 +1,73 @@ +#!/usr/bin/env node +// A product carries no work tree of the baseline's (zero-dependency). +// +// This repository's intent.yaml declares where ITS work lives: +// +// work: +// epics: specs/epics +// tasks: tasks +// sync: on-merge +// +// and `orun plan` on main reconciles that tree into the workspace's work +// plane. A product built from this baseline has neither directory — `specs/` and +// `tasks/` are the factory's, and the leak gate keeps them out — and its +// bootstrap work is opened on the platform by the build itself. Left in, the +// block would point the product's every plan at two directories that do not +// exist. +// +// So 01-product removes it from the product's copy, before the first landing: +// +// node tooling/bootstrap/work-tree.mjs --strip # 01-product +// node tooling/bootstrap/work-tree.mjs --check # prints declared | absent +// +// The block removed is the top-level `work:` key with everything indented +// under it, and the comment lines directly above it that belong to it. It is +// not put back: a product that wants a work tree declares its own. Idempotent. +import * as fs from "node:fs"; + +const FILE = process.argv.includes("--file") + ? process.argv[process.argv.indexOf("--file") + 1] + : "intent.yaml"; + +function usage() { + console.error("usage: work-tree.mjs --strip | --check [--file intent.yaml]"); + process.exit(2); +} + +function findWork(lines) { + const start = lines.findIndex((l) => /^work:\s*(#.*)?$/.test(l)); + if (start < 0) return null; + let end = start + 1; + while (end < lines.length && (lines[end].trim() === "" || /^\s/.test(lines[end]))) end++; + // Trailing blank lines belong to the gap before the next key, not the block. + while (end > start + 1 && lines[end - 1].trim() === "") end--; + // Its own comment: the contiguous `#` lines directly above it. + let from = start; + while (from > 0 && /^#/.test(lines[from - 1])) from--; + return { from, end }; +} + +function strip() { + const text = fs.readFileSync(FILE, "utf8"); + const lines = text.split("\n"); + const found = findWork(lines); + if (!found) { + console.log(`work-tree --strip: ${FILE} declares no work tree — nothing to do`); + return; + } + let { from, end } = found; + // Drop one of the blank lines that separated it from its neighbours. + if (end < lines.length && lines[end].trim() === "" && from > 0 && lines[from - 1].trim() === "") end++; + fs.writeFileSync(FILE, [...lines.slice(0, from), ...lines.slice(end)].join("\n")); + console.log(`work-tree --strip: removed the baseline's work tree from ${FILE}`); +} + +function check() { + const lines = fs.readFileSync(FILE, "utf8").split("\n"); + console.log(findWork(lines) ? "declared" : "absent"); +} + +const mode = process.argv[2]; +if (mode === "--strip") strip(); +else if (mode === "--check") check(); +else usage(); diff --git a/tooling/rebrand/rebrand.mjs b/tooling/rebrand/rebrand.mjs new file mode 100755 index 0000000..290d33a --- /dev/null +++ b/tooling/rebrand/rebrand.mjs @@ -0,0 +1,465 @@ +#!/usr/bin/env node +// Rebrand renamer for the cms-wordpress baseline (zero-dependency). +// +// This repository is a baseline: a product is instantiated from it, branded, +// and deployed as somebody's own site. This script rewrites every *instance +// identity* literal in the product tree — repo slug (which also names the +// secret project), the site's display name, a source-repository link, the +// product domain, Cloudflare worker resource names (so an instance is +// account-safe even when it shares an account with another), the workers.dev +// subdomain placeholder — to the values in a values file, and leaves +// *org-owned* identity alone (the orun state backend, the `sourceplane.io` +// manifest apiVersion, company mailboxes). +// +// The engine is generic; the identity is not. Everything specific to this +// tree is `.baseline/identity.json` (and the defaults below, which must equal +// it) plus the SITE_NAME seam in apps/web/site.config.ts. +// +// The engine is Cirrus's (sourceplane/cirrus-baseline tooling/rebrand): the +// FROM side declared in `.baseline/identity.json`, every written value held +// opaque until the last rule has run, and a leftover sweep that fails on any +// identity a rule did not rename. The rules are this tree's. +// +// Usage (from the product root, on a git tree with the files staged): +// node tooling/rebrand/rebrand.mjs --values .rebrand/values.json [--dry-run] [--allow-dirty] +// node tooling/rebrand/rebrand.mjs --verify [--values .rebrand/values.json] +// +// Values file (see tooling/rebrand/values.example.json): +// { +// "reponame": "acme-notes", // required — repo slug +// "productname": "Acme Notes", // required — the site's display name +// "productdomain": "acme.dev", // optional — default <reponame>.example.com (set later) +// "githuborg": "acme-inc", // owner of the product repo (source link) +// "brandSlug": "acme", // default: reponame — worker name prefix +// "subdomain": "acme", // default: your-workers-subdomain +// "orunWorkspace": "ws_XXXXXXXX", // the segment secret refs name +// "orunWorkspaceSlug": "acme-space" // optional: wins over orunWorkspace there +// } +// +// Modes: +// (default) apply the rename map in place, then run the leftover sweep +// --dry-run report per-rule match counts; change nothing +// --verify only run the leftover sweep (non-zero exit on residue) + +import { execFileSync } from "node:child_process"; +import * as fs from "node:fs"; +import * as path from "node:path"; +import { fileURLToPath } from "node:url"; + +// ── Inputs ───────────────────────────────────────────────────── + +function flag(name) { + return process.argv.includes(`--${name}`); +} +function arg(name) { + const i = process.argv.indexOf(`--${name}`); + return i >= 0 ? process.argv[i + 1] : undefined; +} + +const dryRun = flag("dry-run"); +const verifyOnly = flag("verify"); + +let values = {}; +// --verify takes --values too, optionally: without them it cannot tell the +// product's own identity from a leftover of the baseline's. +const valuesPath = arg("values"); +if (!verifyOnly && !valuesPath) { + console.error("usage: rebrand.mjs --values <file> [--dry-run] | --verify [--values <file>]"); + process.exit(2); +} +if (valuesPath) { + values = JSON.parse(fs.readFileSync(valuesPath, "utf8")); + for (const required of ["reponame", "productname"]) { + if (typeof values[required] !== "string" || values[required].length === 0) { + console.error(`rebrand: values file is missing required field "${required}"`); + process.exit(2); + } + } +} + +// ── THE BASELINE'S OWN IDENTITY — the FROM side, declared ────── +// +// Read from `.baseline/identity.json` beside THIS SCRIPT, not the working +// directory: the rebrand runs with its cwd set to the PRODUCT being branded, +// and a product does not carry `.baseline/` (no module places it). The phase +// hooks invoke this as `node {{ .baseline.dir }}/tooling/rebrand/rebrand.mjs`, +// so the script's own path is the one thing that always points at the +// baseline. `--baseline-identity <file>` overrides it (the test suite pins one). +// +// slug the repo slug: intent name, worker prefix, secret project +// pascal the code-identifier form (swept for, never expected) +// productName the display name, as the SITE_NAME seam spells it +// domain the product domain (BASE_DOMAIN) +// subdomain the workers.dev subdomain this tree carries +// githubOwner the owner in the site's source link +const BASELINE_IDENTITY_FILE = + arg("baseline-identity") ?? + path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", ".baseline", "identity.json"); +const BASELINE_DEFAULTS = { + slug: "cms-wordpress", + pascal: "CmsWordpress", + productName: "next-wp", + domain: "cms-wordpress.example.com", + subdomain: "your-workers-subdomain", + githubOwner: "sourceplane", +}; +const baseline = (() => { + let declared = {}; + try { + declared = JSON.parse(fs.readFileSync(BASELINE_IDENTITY_FILE, "utf8")); + } catch { + declared = {}; // absent is fine: the defaults ARE this baseline's identity + } + const id = { ...BASELINE_DEFAULTS }; + for (const k of Object.keys(BASELINE_DEFAULTS)) { + if (declared[k] !== undefined) id[k] = declared[k]; + } + for (const [k, v] of Object.entries(id)) { + if (typeof v !== "string" || v.length === 0) { + console.error(`rebrand: ${BASELINE_IDENTITY_FILE} field "${k}" must be a non-empty string`); + process.exit(2); + } + } + if (/[^a-z0-9-]/.test(id.slug)) { + console.error(`rebrand: ${BASELINE_IDENTITY_FILE} "slug" must be a lowercase slug ([a-z0-9-])`); + process.exit(2); + } + return { ...id, envPrefix: id.slug.toUpperCase().replace(/-/g, "_") }; +})(); +// Regex-escape, for the rules that build a pattern out of the identity. +const rx = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); + +// All fields are unused under --verify; the fallbacks keep derivation total. +const reponame = values.reponame ?? ""; +const productname = values.productname ?? ""; +// The domain is NOT ASKED at bootstrap: a site goes live on workers.dev and an +// owner sets a domain later. Until then the reserved placeholder +// `<reponame>.example.com` (RFC 2606 — it can never be someone else's) stands +// wherever the domain goes, so setting it is replacing one string. +const productdomain = (values.productdomain ?? "").trim() || (reponame ? `${reponame}.example.com` : ""); +const githuborg = (values.githuborg ?? "").trim() || baseline.githubOwner; +const brandSlug = (values.brandSlug ?? "").trim() || reponame; +const subdomain = (values.subdomain ?? "").trim() || "your-workers-subdomain"; +// A `secret://<workspace>/<project>/<env>/<KEY>` ref names the WORKSPACE first +// and the project (repo) second. The workspace segment is the product's +// workspace — an explicit slug if one was given, else the ws_… id itself +// (the platform's resolve accepts a slug, a public id or a ws_ ref) — and the +// repo name only as the last resort when no workspace was given at all. +const orunWorkspaceSlug = (() => { + const explicit = (values.orunWorkspaceSlug ?? "").trim(); + if (explicit) return explicit; + const ws = (values.orunWorkspace ?? "").trim(); + if (ws) return ws; + return reponame; +})(); + +if (!verifyOnly && /[^a-z0-9-]/.test(`${reponame}${brandSlug}`)) { + console.error("rebrand: reponame/brandSlug must be lowercase slugs ([a-z0-9-])"); + process.exit(2); +} +if (!verifyOnly && /[^A-Za-z0-9-]/.test(githuborg)) { + console.error("rebrand: githuborg must be a GitHub owner name ([A-Za-z0-9-])"); + process.exit(2); +} + +// In-place rewrite of the whole tree: insist on a clean checkout so the +// result is reviewable as one diff (and trivially revertible). +if (!verifyOnly && !dryRun && !flag("allow-dirty")) { + const status = execFileSync("git", ["status", "--porcelain"], { encoding: "utf8" }); + if (status.trim().length > 0) { + console.error("rebrand: working tree is not clean — commit/stash first (or pass --allow-dirty)"); + process.exit(2); + } +} + +// ── File set ─────────────────────────────────────────────────── + +// Tracked text files only. Exclusions are generated/locked artifacts, this +// tool and the identity it reads, and binary content. +const EXCLUDE_RE = new RegExp( + [ + "^tooling/rebrand/", + "^\\.rebrand/", + // The baseline's declared identity. Renaming its contents would make the + // product claim to be a baseline called by the product's own name. + "^\\.baseline/", + "^pnpm-lock\\.yaml$", + "\\.(png|jpg|jpeg|ico|gif|webp|woff2?|ttf|eot)$", + ].join("|"), +); + +function trackedFiles() { + return execFileSync("git", ["ls-files"], { encoding: "utf8" }) + .split("\n") + .filter((f) => f.length > 0 && !EXCLUDE_RE.test(f)) + .filter((f) => { + // `git ls-files` also lists gitlinks (a grounded sandbox checkout carries + // `baseline/` as one) and paths deleted from disk. Only regular files + // are sweepable. + try { + return fs.statSync(f).isFile(); + } catch { + return false; + } + }); +} + +// ── Protected literals (org-owned identity, never rewritten) ─── +// +// Masked before the rules run and restored after, so no rename can touch the +// org's shared infrastructure identity. +const PROTECTED = [ + /https:\/\/orun-api\.sourceplane\.ai/g, // orun state backend + /sourceplane\.io/g, // manifest apiVersion, owned by the orun tooling + /[A-Za-z0-9._%+-]+@sourceplane\.ai/g, // company mailboxes +]; +const MASK = (i, j) => `\u0000REBRAND_PROTECTED_${i}_${j}\u0000`; + +// ── Substituted values are opaque ────────────────────────────── +// +// The rules run in sequence over one buffer. If each wrote its VALUE into it, +// every later rule could match that value again — a product whose domain +// contains the baseline's slug would have it renamed a second time by the +// repo-slug rule, and every phase of a bootstrap re-runs this over the whole +// tree. So a rule writes a TOKEN standing for its value, and every token is +// expanded once, after the last rule. A token is NUL, `H<n>`, NUL; its outer +// characters take the word/non-word class of the value's own edges, so a +// later rule's `\b` sees the boundary the value would have given it. +const heldValues = []; +const heldIndex = new Map(); +function hold(value) { + if (value === "") return ""; + let i = heldIndex.get(value); + if (i === undefined) { + i = heldValues.push(value) - 1; + heldIndex.set(value, i); + } + const edge = (c) => (/\w/.test(c) ? "0" : "\u0001"); + return `${edge(value[0])}\u0000H${i}\u0000${edge(value[value.length - 1])}`; +} +const HELD_RE = /[0\u0001]\u0000H(\d+)\u0000[0\u0001]/g; +function release(text) { + return text.replace(HELD_RE, (_, i) => heldValues[Number(i)]); +} + +// ── Worker resource names ────────────────────────────────────── +// +// Every Cloudflare worker ships prefixed with the slug (`<slug>-<base>`, the +// base being its `apps/<base>/` directory): the component's `workerName`, the +// environment URLs, the deploy smoke. Re-prefix it so an instance's workers +// never collide with another's in a shared account. +function workerBases(files) { + const bases = new Set(); + for (const file of files) { + const m = /^apps\/([^/]+)\//.exec(file); + if (m) bases.add(m[1]); + } + return [...bases]; +} + +// ── Rename map (ordered, most specific first) ────────────────── + +function literalPairs() { + return [ + // The source-repository link the docs carry. + // Before the repo-slug rule, which would otherwise rename only its tail + // and leave the link pointing at the baseline's owner. + [`github.com/${baseline.githubOwner}/${baseline.slug}`, `github.com/${githuborg}/${reponame}`, "source repository link"], + // The product domain wherever it is the product's (BASE_DOMAIN, docs). + // Before the repo-slug rule: the placeholder domain starts with the slug. + [baseline.domain, productdomain, "product domain"], + // The workers.dev subdomain (component parameters, build origin, intent + // environment URLs, docs). + [baseline.subdomain, subdomain, "workers.dev subdomain"], + ]; +} + +function regexPairs(files) { + const list = [ + // The display-name seam. JSON.stringify writes a valid TS string for any + // name the card's pattern admits (apostrophes and ampersands included). + { + re: new RegExp(`SITE_NAME = "${rx(baseline.productName)}"`, "g"), + replacement: () => `SITE_NAME = ${JSON.stringify(productname)}`, + label: "site name seam", + }, + // Secret refs: `secret://<workspace>/<project>/…`. MUST precede the + // repo-slug pass, which would otherwise rewrite only the project half. The + // workspace segment is ANY segment — a ws_… id or a slug. + { + re: new RegExp(`\\bsecret://[A-Za-z0-9_-]+/${rx(baseline.slug)}/`, "g"), + replacement: () => `secret://${orunWorkspaceSlug}/${reponame}/`, + label: "secret ref workspace/project", + }, + ]; + + const bases = workerBases(files); + if (bases.length > 0) { + // Longest-first so an alternation never matches a shorter prefix of a base. + const wb = bases.slice().sort((a, b) => b.length - a.length).map(rx).join("|"); + list.push({ + re: new RegExp(`\\b${rx(baseline.slug)}-(${wb})\\b`, "g"), + replacement: (_m, base) => `${brandSlug}-${base}`, + label: "worker CF name", + }); + } + + // Repo slug: intent metadata.name and per-env `repo:` params, the root + // package name, docs. Runs AFTER the worker pass so `<slug>-<base>` has + // already been consumed. + list.push({ + re: new RegExp(`\\b${rx(baseline.slug)}\\b`, "g"), + replacement: () => reponame, + label: "repo slug", + }); + return list; +} + +// ── Leftover sweep ───────────────────────────────────────────── +// +// After a rebrand (or under --verify) every remaining baseline-identity +// literal is residue: either org-owned (allowed, masked above) or a missed +// rename (reported, non-zero exit). The pascal form and the env-var prefix +// have no rule because nothing in this tree spells them; they are swept so +// that the first file that does fails here, naming itself, rather than +// shipping the baseline's name. +// +// The placeholder subdomain is residue only when the product changed it — a +// product that kept the placeholder has not deployed yet, and that is not a +// missed rename. Under --verify without values it is skipped for the same +// reason. +const subdomainChanged = !verifyOnly && subdomain !== baseline.subdomain; +const RESIDUE_RE = new RegExp( + (subdomainChanged ? `${rx(baseline.subdomain)}|` : "") + + [ + `\\b${rx(baseline.slug)}\\b`, + `${rx(baseline.slug)}-`, + rx(baseline.pascal), + `${rx(baseline.envPrefix)}_`, + rx(baseline.domain), + ].join("|"), + "g", +); +const ALLOWED_RESIDUE = [ + /https:\/\/orun-api\.sourceplane\.ai/, // orun state backend + /[A-Za-z0-9._%+-]+@sourceplane\.ai/, // company mailboxes +]; + +function sweep(files, allowedLiterals = []) { + const residue = []; + for (const file of files) { + let text; + try { + text = fs.readFileSync(file, "utf8"); + } catch { + continue; + } + for (const line of text.split("\n")) { + let cleaned = ALLOWED_RESIDUE.reduce((l, re) => l.replace(new RegExp(re.source, "g"), ""), line); + // The rename's own TARGET values: a product legitimately named with the + // baseline's slug inside it is not residue. + for (const lit of allowedLiterals) { + if (lit) cleaned = cleaned.split(lit).join(""); + } + if (new RegExp(RESIDUE_RE.source).test(cleaned)) { + residue.push(`${file}: ${line.trim().slice(0, 120)}`); + } + } + } + return residue; +} + +// ── Main ─────────────────────────────────────────────────────── + +const files = trackedFiles(); +const literals = literalPairs(); +const regexes = regexPairs(files); + +// Every value a rule can write. A value some rule would match again is HELD +// wherever it already stands: every phase of a bootstrap re-runs this over the +// whole tree, so what an earlier phase wrote is input to the next pass and +// must come out of it unchanged. +const produced = [ + ...literals.map(([, to]) => to), + `SITE_NAME = ${JSON.stringify(productname)}`, + `secret://${orunWorkspaceSlug}/${reponame}/`, + reponame, + ...workerBases(files).map((base) => `${brandSlug}-${base}`), +].filter((v, i, all) => v && all.indexOf(v) === i); +const rematchable = (v) => + literals.some(([from]) => v.includes(from)) || regexes.some(({ re }) => new RegExp(re.source).test(v)); +// Longest first, so a held value is never split by a shorter one inside it. +const guarded = produced.filter(rematchable).sort((a, b) => b.length - a.length); +const allowedTargets = produced.filter((to) => new RegExp(RESIDUE_RE.source).test(to)); + +if (verifyOnly) { + const residue = sweep(files, valuesPath ? allowedTargets : []); + if (residue.length > 0) { + console.error(`rebrand --verify: ${residue.length} baseline-identity leftover(s):`); + for (const r of residue) console.error(` ${r}`); + process.exit(1); + } + console.log("rebrand --verify: no baseline-identity leftovers."); + process.exit(0); +} + +const counts = new Map(); +const touched = new Set(); +const count = (label, n = 1) => counts.set(label, (counts.get(label) ?? 0) + n); + +for (const file of files) { + let text; + try { + text = fs.readFileSync(file, "utf8"); + } catch { + continue; + } + if (text.includes("\0")) continue; // binary safety net + const original = text; + + const masks = []; + PROTECTED.forEach((re, i) => { + text = text.replace(re, (m) => { + const token = MASK(i, masks.length); + masks.push([token, m]); + return token; + }); + }); + + // What a previous pass already wrote stays as written. + for (const value of guarded) text = text.split(value).join(hold(value)); + + for (const [from, to, label] of literals) { + const n = text.split(from).length - 1; + if (n === 0) continue; + text = text.split(from).join(hold(to)); + count(label, n); + } + for (const { re, replacement, label } of regexes) { + text = text.replace(re, (...m) => { + count(label); + return hold(replacement(...m)); + }); + } + + // Every rule has run; only now do the values it wrote appear. + text = release(text); + for (const [token, value] of masks) text = text.split(token).join(value); + + if (text !== original) { + touched.add(file); + if (!dryRun) fs.writeFileSync(file, text); + } +} + +console.log(`rebrand${dryRun ? " (dry-run)" : ""}: ${touched.size} file(s) affected`); +for (const [label, n] of counts) console.log(` ${String(n).padStart(5)} ${label}`); +if (dryRun) process.exit(0); + +const residue = sweep(trackedFiles(), allowedTargets); +if (residue.length > 0) { + console.error(`rebrand: ${residue.length} baseline-identity leftover(s) after rename:`); + for (const r of residue) console.error(` ${r}`); + process.exit(1); +} +console.log("rebrand: leftover sweep clean."); diff --git a/tooling/rebrand/values.example.json b/tooling/rebrand/values.example.json new file mode 100644 index 0000000..d02c419 --- /dev/null +++ b/tooling/rebrand/values.example.json @@ -0,0 +1,8 @@ +{ + "reponame": "acme-notes", + "productname": "Acme Notes", + "productdomain": "acme.dev", + "githuborg": "acme-inc", + "subdomain": "acme", + "orunWorkspace": "ws_XXXXXXXX" +}