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
8 changes: 4 additions & 4 deletions .dz/briefs/health.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ or PR announces. No verdict is always re-run, never filed: a null `conclusion` (
| `dependabot-not-stuck` | `gh pr list --app dependabot --limit 5 --state open --json number,createdAt,updatedAt,statusCheckRollup` | green checks at any age; failed checks until >7 days since `updatedAt` (7 exactly is not over). Green: completed CheckRuns `SUCCESS`, `NEUTRAL`, `SKIPPED`, StatusContexts `SUCCESS`; terminal failures red. Pending, missing, malformed, unknown, mixed evidence = no verdict; so is a missing or invalid `updatedAt`, never replaced by `createdAt`. A page of `--limit` (5) is truncated: raise it, file nothing until short. A confirmed stuck PR files even beside a PR with unread evidence. `--state open` excludes merged and closed; `createdAt` is context, never inactivity |
| `demo-shipped` | `gh run list --workflow deploy-social-demo.yml --limit 1 --json databaseId,event,status,conclusion,headBranch,displayTitle,url,createdAt` | `success` on a `workflow_run`. Null `conclusion` = still building: read `status`. `skipped` = the `ci.yml` completion was no green push (the deploy job's `if:`): red `main-green` files it; with it green, look for a non-push `ci.yml` run. `workflow_dispatch` = an operator's run, not a push publish; `headBranch` names the ref. Other non-success: name the guard its log's `::error::` line names. The ask carries `url`, `createdAt`, `databaseId`, `displayTitle`, `headBranch` |
| `release-exists` | `t=$(git describe --tags --abbrev=0 --match 'v[0-9]*' origin/main)`, then `gh release view "$t" --json tagName,isDraft,publishedAt` | `isDraft` false AND `publishedAt` set; a draft, or none, is unhealthy. Missing = unhealthy: gh prints `release not found` and no JSON — the message is the signal, not the exit code. Any other unreadable answer = `cannot tell` (`X_HEALTH_ROW_UNREADABLE`) |
| `tutorials-run` | `gh run list --workflow tutorial-run.yml --limit 1 --json databaseId,event,status,conclusion,headBranch,displayTitle,url,createdAt` | `success`, or no run yet (paths-filtered: nothing diverged). `cancelled` (superseded by a newer push) = re-run. Else a tutorial no longer runs as written: the ask names `url` and `bun run scripts/tutorial-run.ts --json`, whose `X_DOC_TUTORIAL_DIVERGED` names page and line |
| `tutorials-run` | `gh run list --workflow tutorial-run.yml --branch main --event push --limit 1 --json databaseId,event,status,conclusion,headBranch,displayTitle,url,createdAt` | `success`, or no run yet (paths-filtered). `cancelled` (superseded) = re-run. Else a tutorial diverged: the ask names `url` and `bun run scripts/tutorial-run.ts --json` (`X_DOC_TUTORIAL_DIVERGED`: page, line) |
| `flake-hunt` | `gh run list --workflow flake-hunt.yml --limit 1 --json databaseId,event,status,conclusion,headBranch,headSha,displayTitle,url,createdAt` | `success` under 48 h; older = unhealthy, the schedule stopped. No run or `cancelled` = re-run. Else a test failed in a shuffled order: open `flake-hunt` issues name test, seed, rerun |
| `bench` | `gh run list --workflow bench.yml --limit 1 --json databaseId,event,status,conclusion,headBranch,headSha,displayTitle,url,createdAt` | `success` under 8 days; older = the weekly schedule stopped. No run or `cancelled` = re-run. Else a figure failed to measure |
| `compat` | `gh run list --workflow compat.yml --limit 1 --json databaseId,event,status,conclusion,headBranch,headSha,displayTitle,url,createdAt` | `success` under 8 days; older = the schedule stopped. No run or `cancelled` = re-run. Else a cell is red: open `compat` issues name each and its replay |
Expand All @@ -34,9 +34,9 @@ One ask per unhealthy row unless an open issue names it, titled by the signal (`
`publish failed: <v>`, `Dependabot #<n> failed checks, inactive since <updatedAt>`), its body the
command, its output and the failing run's URL. A red `main` first: nothing releases from it.

A `Dependabot` npm-bump ask carries cause and repair: Dependabot cannot write `bun.lock`, so its
lock is stale by construction; a pin left behind fails `X_RELEASE_VERSION_SKEW`; the repair is
`bun run lockfile:fix`; a conflicted lock is never merged over — the local regeneration lands first.
A `Dependabot` npm-bump ask says why and the repair: it cannot write `bun.lock`, so its lock is
stale; a pin left behind fails `X_RELEASE_VERSION_SKEW`; repair: `bun run lockfile:fix`; a
conflicted lock is never merged over — regenerate it locally first.

Never re-run a publish, delete a tag, a Release or a branch, or `npm publish` from here.
`PUBLISHING.md` owns every recovery; a fix ships as the next patch, never a moved tag.
Expand Down
22 changes: 14 additions & 8 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ name: ci
# parts, and `verify`, their one verdict), does each tracked app still gate
# (`reference-app-verify`), can a stranger scaffold an app that gates (`scaffold-smoke`), do the
# deployable artifacts BUILD and RENDER (`container`), does a rolling upgrade on the scaffolded
# chart drop a request (`deploy-proof`, main only), is each package green and above its
# chart drop a request (`deploy-proof`: main, and a pull request touching its paths), is each package green and above its
# coverage bar in isolation (`packages`), and does any of it work on native Windows (`windows`,
# the one runner that is not `ubuntu-latest`). The last four each carry their own argument, above
# the job. One more asks first, on a push: did a green pull-request run already test this tree
Expand Down Expand Up @@ -1332,12 +1332,15 @@ jobs:
# Service, and fails on a single non-2xx. Every step is `docker/deploy-proof/run.sh`, which a
# developer runs unchanged on a laptop.
#
# Main only, and only when a file that decides the answer moved since a proof that PASSED: kind
# plus two image builds is minutes, not seconds, and a push that touches none of those paths
# cannot change the verdict. Budget: <= 8 minutes; the timeout below is the ceiling, not the
# target.
# On main, only when a file that decides the answer moved since a proof that PASSED: kind plus
# two image builds is minutes, not seconds, and a push that touches none of those paths cannot
# change the verdict. On a pull request, only when its diff touches one of those paths: main-only,
# it went red on the merge of a green pull request (#1272's `held-job.sh` edited a registry
# shape `x new` no longer wrote). Beside the gate, never in `verify`'s needs: a red proof is a red
# check on the pull request, and `verify` stays the one verdict. Budget: <= 8 minutes; the
# timeout below is the ceiling, not the target.
deploy-proof:
if: (github.event_name == 'push' && github.ref == 'refs/heads/main') || github.event_name == 'workflow_dispatch'
if: (github.event_name == 'push' && github.ref == 'refs/heads/main') || github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch'
runs-on: ubuntu-latest
timeout-minutes: 15
# `actions: read` is the previous run's job list, which the decision below reads.
Expand All @@ -1348,6 +1351,8 @@ jobs:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
# Depth 2: a pull request's decision diffs its merge commit against the base tip.
fetch-depth: 2
# Before the decision, because the decision is a Bun script: ~10 s on a push that then skips.
- uses: ./.github/actions/setup
# A `paths:` filter belongs to a whole workflow, never to one job, so the filter is a step —
Expand All @@ -1356,8 +1361,9 @@ jobs:
# path, and release.yml then published from B. Now a skip inherits the PREVIOUS main run's
# verdict, so it is legal only when that run's deploy-proof concluded `success` and no
# deciding file moved since its commit; a red, cancelled, unfinished or unreadable
# predecessor runs the proof, and so does every `release:` commit and every manual run. The
# rule and the path list: scripts/deploy-proof-due.ts, unit-tested beside it.
# predecessor runs the proof, and so does every `release:` commit and every manual run. A pull
# request inherits nothing: it runs when its own diff touches a deciding path. The rule and
# the path list: scripts/deploy-proof-due.ts, unit-tested beside it.
- name: did a file that decides the verdict move since a proof that passed?
id: paths
env:
Expand Down
34 changes: 30 additions & 4 deletions .github/workflows/tutorial-run.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,13 @@ name: tutorial-run
# Does a stranger following tutorials 1–4 on this commit see what the pages show? Every ```bash
# fence, in order, on a scaffold built from this checkout (`scripts/tutorial-run.ts`). Its own
# workflow, never a `ci` job: it installs and gates a scaffold several times, and `ci`'s clock and
# push count must not pay for that. On a push to `main` only, filtered to the files that can move a
# tutorial's output — a push touching none of them starts nothing. Not on a PR: a tutorial left
# wrong breaks `main` for one push at most, and the red run is read by the daily health brief.
# push count must not pay for that. On a push to `main` AND a pull request, filtered to the files
# that can move a tutorial's output — the generators, `x new`, `x db` and the CLI's message
# catalog — so a change touching none of them starts nothing. Main-only, it went red on the merge
# of a green pull request (#1272: `x db gen`'s success line gained its tables); on a pull request
# the red lands before the merge. Not a required check: `verify` is the one
# (docs/history/ci-split.md), and a path-filtered workflow never leaves a check pending.
# `scripts/ci-workflow-main-only.test.ts` holds the two path lists equal.
# The same job RUNS `wiki/Building-Your-Own-Base.md`'s recipes: each `## Recipe:` fence written to
# the path it names in a scratch app and driven by `scripts/base-recipes/` — seconds, no scaffold.

Expand All @@ -16,6 +20,26 @@ on:
- 'wiki/Tutorial-0[1-4]*'
- 'packages/cli/src/templates/**'
- 'packages/cli/src/cmd-generate*'
- 'packages/cli/src/cmd-new*'
- 'packages/cli/src/cmd-db*'
- 'packages/cli/src/db-*'
- 'packages/cli/src/messages*'
- 'packages/cli/src/verify-*'
- 'scripts/tutorial-run.ts'
- 'scripts/lib/tutorial-steps.ts'
- 'wiki/Building-Your-Own-Base.md'
- 'scripts/base-recipes/**'
- 'scripts/lib/base-recipes.ts'
- '.github/workflows/tutorial-run.yml'
pull_request:
paths:
- 'wiki/Tutorial-0[1-4]*'
- 'packages/cli/src/templates/**'
- 'packages/cli/src/cmd-generate*'
- 'packages/cli/src/cmd-new*'
- 'packages/cli/src/cmd-db*'
- 'packages/cli/src/db-*'
- 'packages/cli/src/messages*'
- 'packages/cli/src/verify-*'
- 'scripts/tutorial-run.ts'
- 'scripts/lib/tutorial-steps.ts'
Expand All @@ -25,8 +49,10 @@ on:
- '.github/workflows/tutorial-run.yml'
workflow_dispatch:

# One group per ref: a newer push to main supersedes the run before it, as it always did, and a pull
# request's run is superseded only by its own next push — never by main's, nor main's by it.
concurrency:
group: tutorial-run
group: tutorial-run-${{ github.ref }}
cancel-in-progress: true

permissions:
Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ Semver applies from 1.0.0. A breaking change to a documented API needs a major
- `x heavy run --max-wait <seconds>` gives up with `X_HEAVY_WAIT_EXPIRED` (exit 75); `x heavy status` names each run's wrapper and command pids (`wrapperAlive`, `childPids` in `--json`), and a heavy run also waits while the CPU is saturated and another run is admitted.
- `x clean --services` stops this app's test service stack, and the gate prints one line saying whether it started, reused or shared one.
- `x dev`'s port refusal names the directory of the process holding the port.
- `x upgrade --only <step>[,<step>…]` runs the hop's `x verify` on those steps alone, so `unit`, `live` and `e2e` can be left to CI on a loaded machine. The report never reads as a full gate: `proof: "verify-only"`, `verify.notRun[]`, a `NOT THE FULL GATE` summary and a `then` naming `x verify --only <the rest>`. A bare `x upgrade` still runs the full gate ([Upgrading](wiki/Upgrading.md)).

### Changed

Expand Down
26 changes: 24 additions & 2 deletions docs/history/ci-split.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ servers a `services:` block cannot start.
| `scaffold-smoke` | 5 | one scaffold per runner: default, `--no-example`, and one per `x new --shape` (`api`, `blog`, `dashboard` since 2026-11-06), held to `NEW_SHAPES` by `scripts/ci-workflow-shape.test.ts` |
| `packages` | 4 + 1 | each unit tested and covered alone; `cli` cut into two weight-band parts on two shards, the other 31 units on two more; `packages (merge)` folds the parts and judges `cli` (2026-11-17, below) |
| `container` | 1 | unchanged |
| `deploy-proof` | 1 | unchanged, `main` only |
| `deploy-proof` | 1 | `main`, and a pull request whose diff touches a deciding path (2026-11-19, below) |
| `fault-drills` | 1 | `x drill` on `examples/dummy` against one Postgres: `pg-blackhole`, `worker-sigkill`, `web-sigterm` — added 2026-11-06, below |
| `release-rehearsal` | 1 | pull requests only: on a diff touching `scripts/`, the CLI's templates, codemods or upgrade, or any `package.json`, `release.ts --bump minor --rehearse` stamps the next minor in the runner's checkout (never committed) and the version-sensitive suites run against it — a test that bakes the current version breaks here, not on the release PR (added 2026-11-15) |
| `windows` | 1 | native Windows in PowerShell: lint, typecheck, a path-heavy unit subset, a scaffold smoke — added 2026-10-05, below |
Expand Down Expand Up @@ -103,6 +103,7 @@ services where it starts any (22 s + 8 s before this change, for two servers by
| a part starts only the services it exports URLs for | `scripts/test-services-shape.test.ts` |
| a suite that needs a service URL is run by a part that exports it | `scripts/test-services-shape.test.ts` |
| `windows` is the one non-Ubuntu runner, pwsh on every step, ≤ 25 min | `scripts/ci-workflow-shape.test.ts` |
| no check runs on `main` alone: a workflow a push to `main` starts runs on a pull request over the same paths, unless it publishes; no `ci.yml` job a push runs is skipped on a pull request | `scripts/ci-workflow-main-only.test.ts` |

## Trade

Expand Down Expand Up @@ -344,6 +345,27 @@ more under coverage than its weights say, ~0.4 s of isolation per file. Expected
install and a fold of two ~150 KB documents. The first run's `packages` logs are the proof; the
next lever is a per-file overhead in `planParts`' cost, so the bands balance at ~210 s each.

## Nothing checks `main` alone, 2026-11-19

Two jobs ran only on a push to `main`, and both went red on the merge of a green pull request
(#1272): `deploy-proof` (`docker/deploy-proof/held-job.sh` edited a registry shape `x new` no
longer wrote) and `tutorial-run` (Tutorial 2's `x db gen` line gained its tables). Each now runs on
a pull request too, over the paths it already depended on:

| Job | On a pull request | Cost |
|---|---|---|
| `deploy-proof` | when `scripts/deploy-proof-due.ts` finds a `VERDICT_PATHS` file in the diff (merge commit against its first parent, depth 2); none: the job runs its decision step and skips the rest. It inherits nothing — `main` still decides by the predecessor rule | ≤ 8 min, beside the gate, off the critical path |
| `tutorial-run.yml` | `pull_request.paths` equal to `push.paths`; the list gained `cmd-new*`, `cmd-db*`, `db-*` and `messages*`, where the tutorial output it diverged on lives | ~2.5 min, its own workflow |

`verify` is still the one verdict: neither job is in its `needs`, neither is required, and a
path-filtered workflow never leaves a check pending — a red one is a red check on the pull request.
`scripts/lib/health-tutorials.ts` reads `--branch main` alone, so a pull request's red is never
main's health. `scripts/ci-workflow-main-only.test.ts` holds the rule: a workflow pushed on `main`
with no `pull_request` trigger, or with different paths, fails unless it is a named publisher
(`wiki.yml`, `scorecard.yml`); a `ci.yml` job whose `if` runs on a push to `main` and not on a pull
request fails — each `if` evaluated for both events (`scripts/lib/workflow-if.ts`), never matched
as a substring.

## Fault drills, 2026-11-06

`fault-drills` asks one question no other job can: does the reference app keep the framework's
Expand Down Expand Up @@ -387,7 +409,7 @@ when it became a symlink to `CLAUDE.md`. `ci.yml` runs on pushes to `main`, `nex
| `deploy-social-demo.yml` | green `ci` on `main` → the demo image |
| `deploy-docs-site.yml` | green `ci` on `main` → `dummy/docs-site`'s static build on GitHub Pages; **inert** — every job skipped — until the owner sets the `DOCS_SITE_ORIGIN` repository variable (`scripts/ci-workflow-shape-docs.test.ts`) |
| `wiki.yml` | push to `main` → the wiki |
| `tutorial-run.yml` | push to `main` touching a tutorial or a generator → tutorials 1–4 fence by fence, `X_DOC_TUTORIAL_DIVERGED`; never on a PR, never in `ci` |
| `tutorial-run.yml` | push to `main` or a PR touching a tutorial, a generator, `x new`, `x db` or the CLI's messages → tutorials 1–4 fence by fence, `X_DOC_TUTORIAL_DIVERGED`; never in `ci`, never required; one concurrency group per ref (on PRs since 2026-11-19, below) |
| `bench.yml` | weekly + dispatch → re-measured first-hour/http-hello JSON as one PR on `bench/re-measured`, replaced by the next run; never in `ci`. No `release` trigger: a Release `release-tag.yml` creates with `GITHUB_TOKEN` starts no run, so it never fired. Needs Actions allowed to create pull requests (repository and organisation Actions settings); the cost is that required reviews must come from CODEOWNERS, which the bot cannot satisfy. Both 2026-11 runs were refused the PR; a refusal now says so and prints the `gh pr create` that opens it by hand, never the approve switch as the remedy |
| `workflow-lint.yml` | push or PR touching `.github/**` → zizmor 1.32.0 at `medium` and above, online audits (impostor commits, advisories) included; a deliberate finding is suppressed in place with its reason. Its own workflow so a path filter can gate it; not a required check, so the filter never leaves one pending (added 2026-11-09) |
| `scorecard.yml` | push to `main`, weekly, a change to `main`'s rules → the OpenSSF Scorecard run, published to the Scorecard API the README badge reads (`publish_results: true`); never gates a merge (added 2026-11-10) |
Expand Down
Loading
Loading