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/app/site.ts; `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": "angular-boilerplate",
"pascal": "AngularBoilerplate",
"productName": "angular-test",
"domain": "angular-boilerplate.example.com",
"subdomain": "your-workers-subdomain",
"githubOwner": "sourceplane"
}
115 changes: 115 additions & 0 deletions .baseline/product/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
# angular-boilerplate

An Angular app — the Angular CLI's welcome page, with its resources, its
Next Steps terminal and its router — built with
[Angular](https://angular.dev) 22, fully static, and served as **Cloudflare
Workers + Static Assets** behind one small Worker, as a single-page app.

## Live deployment

<!-- 03-docs:begin -->
Not recorded yet. The bootstrap's last phase writes the live URLs, the
workspace and the secrets the app uses into
[ai/context/deployment.md](ai/context/deployment.md); how the app 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 app's name, which the welcome banner reads | `apps/web/src/app/site.ts` |
| The welcome page, its component and its styles | `apps/web/src/app/app.component.{html,css,ts}`, `apps/web/src/styles.css` |
| The app's routes (none yet), its configuration and its bootstrap | `apps/web/src/app/app.routes.ts`, `apps/web/src/app/app.config.ts`, `apps/web/src/main.ts` |
| The page shell and the favicon | `apps/web/src/index.html`, `apps/web/src/favicon.ico` |
| Images and other files served as they are | `apps/web/src/assets` |
| The Angular workspace: build, serve and test | `apps/web/angular.json` |
| The app's specs | `apps/web/src/app/*.spec.ts` |
| The Worker in front of the static files, and the deploy contract | `apps/web/worker/index.ts`, `apps/web/wrangler.jsonc`, `apps/web/component.yaml` |
| Tests of the build, the Worker and the page | `tests/web` (vitest) |

## Getting started

```bash
pnpm install
pnpm typecheck
pnpm lint
pnpm test # ng test (the app's specs) and the vitest suite
pnpm build # ng build → apps/web/dist/browser
```

```bash
pnpm --filter @app/web dev # ng serve on http://localhost:3000, reloading as you edit
pnpm --filter @app/web preview # wrangler dev over the built app, as the Worker serves it
```

Generate a component with `pnpm --filter @app/web ng generate component
<name>` and add a page by giving it a route in `apps/web/src/app/app.routes.ts`:
every page address is answered with the app, so a route you add works on a
deep link and a reload without any server change. A path that names a file
the build did not write (`/missing.js`) is a 404. Make the app yours in
`apps/web/src/app/` (the welcome page is the Angular CLI's placeholder: delete
it to start) and `apps/web/src/app/site.ts` (its name).

## 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 app deploys to `stage`, then to
`prod` once stage has converged on the same commit; `dev` only verifies. The
Worker is `angular-boilerplate-web-<env>` on your account's workers.dev
subdomain, and every deploy is smoke-tested over HTTP: the home page must be
the app's shell, the main bundle it loads must be served with the welcome
page in it, a deep link must answer with the app, and a missing file must be
a 404. A pull request runs the same pipeline's verify lanes: the app 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 app answers on workers.dev from its first deploy. To serve it on your
own domain:

1. Add the domain to the Cloudflare account the app deploys into, and attach
it to the Worker (dashboard → Workers & Pages →
`angular-boilerplate-web-prod` → Settings → Domains & Routes → Add →
Custom domain). Do the same for stage with a subdomain if you want one.
2. Record the environment's public origin in `intent.yaml`. The app writes
no absolute URL, so the build does not change; the deployment record
probes the domain beside the workers.dev URL:

```yaml
environments:
prod:
env:
SITE_URL: https://angular-boilerplate.example.com
```

The app was born with the reserved placeholder
`angular-boilerplate.example.com` where its domain goes: that example,
and `BASE_DOMAIN` under each environment (dev, stage and prod) in
`intent.yaml`. Replace it with your domain in the same change.

## Credits

The app is Vercel's Angular example
([vercel/examples](https://github.com/vercel/examples),
`framework-boilerplates/angular`, © 2023 Vercel, MIT-licensed —
`apps/web/LICENSE.md`), itself the Angular CLI's generated welcome app,
moved to Angular 22. Its welcome page links Angular's documentation; replace
it with your own app as you make it yours.
24 changes: 24 additions & 0 deletions .baseline/tasks/01-product.TaskContract.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# 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.
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 Angular and deploys it to stage and prod
affects:
- web
- web-tests
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-docs \
--set "productname=Acme Docs" \
--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-v1."
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