Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .baseline/identity.json
Original file line number Diff line number Diff line change
@@ -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"
}
177 changes: 177 additions & 0 deletions .baseline/product/README.md
Original file line number Diff line number Diff line change
@@ -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

<!-- 02-docs:begin -->
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).
<!-- 02-docs:end -->

## 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://<your-site>/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://<your-site>
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://<your-site>
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=<a shared secret>
WORDPRESS_URL=https://<your-site> 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-<env>` 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.
23 changes: 23 additions & 0 deletions .baseline/tasks/01-product.TaskContract.yaml
Original file line number Diff line number Diff line change
@@ -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: []
13 changes: 13 additions & 0 deletions .baseline/tasks/02-docs.TaskContract.yaml
Original file line number Diff line number Diff line change
@@ -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: []
151 changes: 151 additions & 0 deletions .github/workflows/baseline.yml
Original file line number Diff line number Diff line change
@@ -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
Loading
Loading