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/src/lib/site.ts (the upstream template's own name for the app, from its <title>); `domain` and `subdomain` are placeholders, because this baseline has never deployed under a name of its own; `githubOwner` is the owner in the repository's source links.",
"slug": "tanstack-start",
"pascal": "TanStackStart",
"productName": "TanStack Start Starter",
"domain": "tanstack-start.example.com",
"subdomain": "your-workers-subdomain",
"githubOwner": "sourceplane"
}
98 changes: 98 additions & 0 deletions .baseline/product/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
# tanstack-start

A TanStack Start site — the welcome page, a todo list kept by server
functions in the visitor's own cookie, an API route, and the three SSR modes
(full, data-only and SPA) — on **Cloudflare Workers + Static Assets**, built
by [Cloudflare's Vite plugin](https://developers.cloudflare.com/workers/vite-plugin/),
TanStack Start's own Cloudflare target.

## Live deployment

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

## What is here

| Surface | Where |
|---|---|
| The site's name (every page's `<title>`) | `apps/web/src/lib/site.ts` |
| `/` (the welcome page), `/demo/start/server-funcs` (todos through a GET and a POST server function), `/demo/start/api-request` (a page that fetches the API route), `/demo/start/ssr/*` (full SSR, data-only, SPA mode) | `apps/web/src/routes` |
| The API route: `GET /demo/api/names` | `apps/web/src/routes/demo/api.names.ts` |
| The todo store: the visitor's list in one httpOnly cookie | `apps/web/src/data/todos.ts` |
| The header and its navigation | `apps/web/src/components/Header.tsx` |
| Workers build and deploy contract | `apps/web/vite.config.ts`, `apps/web/wrangler.jsonc`, `apps/web/component.yaml` |
| Tests (the site's name, the todo store) | `apps/web/src/**/*.test.ts` (vitest) |

## Getting started

```bash
pnpm install
pnpm typecheck # tsc
pnpm lint # biome lint
pnpm test # vitest
pnpm build # vite build → apps/web/dist/server (the Worker) + dist/client (the browser's files)
```

```bash
pnpm --filter @app/web dev # http://localhost:3000, the server in workerd
pnpm --filter @app/web preview # wrangler dev over the built Worker
```

Make the site yours in `apps/web/src/routes` (the pages; TanStack Router
writes `src/routeTree.gen.ts` from them) and `apps/web/src/lib/site.ts` (its
name). The site needs no environment variable and no secret.

The server-functions demo keeps each visitor's list in their own browser:
one httpOnly cookie holding the list as JSON — no database and no third
party. A cookie holds about 4 KB, so the list is capped (50 todos of up to
100 characters, and a todo that would not fit is refused with a message). To
share a list across devices, swap `readTodos` and the `setCookie` call in
`apps/web/src/routes/demo/start.server-funcs.tsx` for a KV namespace bound in
`apps/web/wrangler.jsonc`.

## How it deploys

Merges to `main` converge through Orun: `.github/workflows/ci.yml` plans the
changed components and runs each lane against the workspace in
`intent.yaml`. The site deploys to `stage`, then to `prod` once stage has
converged on the same commit; `dev` only verifies. The Worker is
`tanstack-start-web-<env>` on your account's workers.dev subdomain, and
every deploy is smoke-tested over HTTP. 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 rotating a
secret, 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, add the domain to the Cloudflare account the site deploys into
and attach it to the Worker (dashboard → Workers & Pages →
`tanstack-start-web-prod` → Settings → Domains & Routes → Add → Custom
domain). Do the same for stage with a subdomain if you want one.

Nothing else has to change: the site builds no absolute links, so it answers
on whatever origin serves it, and TanStack Start's server functions check a
request's `Origin` against the host it arrived on. The repository names the domain in
one place, `BASE_DOMAIN` in `intent.yaml` (dev, stage and prod), which the
site was born with as the reserved placeholder
`tanstack-start.example.com`. Replace it with your domain in the same
change that records it.
25 changes: 25 additions & 0 deletions .baseline/tasks/01-product.TaskContract.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Task contract template for the 01-product landing.
# 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.
#
# The whole site in one landing. `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. The site is one component — its
# test runs inside it (vitest in apps/web), so there is no separate test
# package to redeploy.
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 builds it with Cloudflare's Vite plugin and deploys it to stage and prod, its tests green
affects:
- web
doneWhen:
- repo pushed, main pinned as default, workspace linked (orun cloud link)
- main convergence green (build, deploy and smoke on stage and prod)
- the home page answers on both workers.dev URLs
gates: []
13 changes: 13 additions & 0 deletions .baseline/tasks/03-docs.TaskContract.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Task contract template for the 03-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: []
136 changes: 136 additions & 0 deletions .github/workflows/baseline.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
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 exactly one phase, that a
# placed tree comes up branded and carrying nothing of the factory, and that
# the site it produces installs, builds, deploys (dry) and serves.
#
# ─── 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 site would carry) and the placement
# tier (the offline bootstrap: every phase placed and finished by the
# blueprint's own hooks, then the site's own `orun plan` for the 01-product
# merge).
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-notes \
--set "productname=Acme Notes" \
--set githuborg=acme-inc
- name: the leak gate — what a site carries
run: bash testing/leak.test.sh
- name: placement — the offline bootstrap, and the site'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: the finished site installed, its
# fixtures rendered, type-checked, linted, tested and built, the stage
# lane's own build, output check and dry deploy, and the built Worker served
# and smoke-tested with the component's own smoke command. Pinned at the
# bootstrap floor (v2.88.0): the offline bootstrap reads the blueprint (its
# one `secrets` reconcile, its background task set-up, its landings checked
# in the box), and the floor is newer than the site'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
97 changes: 97 additions & 0 deletions .github/workflows/tag.yml
Original file line number Diff line number Diff line change
@@ -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."
Loading
Loading