breakaway 1.3.2 → 1.4.0-main.18

package/scripts/tasks.mjs

@@ -54,7 +54,12 @@ import {
   generalAgentRequest,
   generalAgentSummary,
   githubRequest,
+  specLines,
+  specListLines,
+  specRequest,
+  specsRequest,
   ideaTask,
+  packageReleaseRequest,
   pullAgentRequest,
   pullAgentSummary,
   reviewRequest,
@@ -147,6 +152,8 @@ Reading                (list, next, claim, and add work in this checkout's repos
   agents new "<prompt>"  start an agent from a prompt: it makes its own task  [--image <file>]… [--repo <slug>] [--force] (owner)
   agents new --decision <ref> ["<note>"]   start an agent that brings the work waiting for an answered decision in line with its answers; the board writes its prompt  [--force] (owner)
   agents new --next minor|major ["<note>"]   start an agent that sets package.json to the next minor or major release; the board writes its prompt  [--repo <slug>] [--force] (owner)
+  agents new --spec <path> "<what should change>"   start an agent that changes a spec as you ask and brings the tasks that
+                         link it in line; the board writes its prompt  [--repo <slug>] [--force] (owner)
   agents start <ref>     start a Claude cloud agent on a task  [--note <text>] [--force]
   agents refine <ref>    start an agent that improves a task, not builds it  --note <what to look at or change> [--force]
   agents plan [<plan>]   your Claude plan and what it allows; pro, max5, or max20 picks one (owner) and sets the limits to its defaults
@@ -165,6 +172,10 @@ Reading                (list, next, claim, and add work in this checkout's repos
   github review <n>      start an agent that reviews a pull request that can merge as it stands, on the task it closes, as
                          Review with an agent does; on a Dependabot one it tests the update, as Safe to merge? does
                          (owner)  [--note <text>] [--repo <slug>] [--force]
+  github release <pre-release>   release a package's pre-release (1.4.0-main.5) as its stable on latest, as Release on the
+                         GitHub page does: the board starts release.yml's stable job, and npm waits for your 2FA (owner)  [--repo <slug>]
+  specs                  the repository's specs, newest first: each one's status and its tasks  [--repo <slug>]
+  specs show <path>      one spec: its status, last change, Markdown, and the tasks that link it  [--repo <slug>]
   github                 the checkout's repository on GitHub: open pull requests, checks, reviews, CI, deploys, alerts  [--sync] [--repo <slug>]
   hook session|wait      the Claude Code session hooks a repository's .claude/settings.json runs (npx breakaway hook session)
   health                 the server's state
@@ -236,7 +247,9 @@ Working
   repos modify <slug>    change one (owner): --area <project:PREFIX> adds an area, --remove-area <project> drops one with no tasks, --name, --branch, --github,
                          --agents-max <n|none> and --agents-hourly <n|none> cap its agents under the board's shared limits,
                          --prompt <path|none> says where its agent prompt is in its checkout (default tools/tasks/routine-prompt.md)
-                         --pipeline <file.json|none> sets its deploy pipeline ({"workers": {"staging", "production"}, "workflows": {...}, "deployPaths"}) or clears it
+                         --specs <dir|none> says where its specs are (default docs/specs)
+                         --pipeline <file.json|none> sets its deploy pipeline ({"workers": {"staging", "production"}, "package": "<npm name>", "workflows": {...}, "deployPaths"},
+                         with workers, package, or both) or clears it
   features add <slug>    new feature: its tasks join by carrying <slug> as a tag  [--title <text>]
                          [--brief <text> | --brief-file <path>] [--release <x.y.z>] (agents add one without a release)
                          --from <ref> (owner): made from the group <ref> is in on the Dependencies view: its open tasks
@@ -268,6 +281,12 @@ Install repository     (no board needed: the files and steps that deploy a board
                          [--channel stable|main] [--version <release>]
   install resolve|check|config|previous|healthy|update   the steps those workflows run (docs in the install's README)
 
+Deploy and release flows   (no board needed: run in the checkout of the repository that deploys or publishes)
+  pipeline init          render .github/breakaway-pipeline.json into Deploy, Promote, and Roll back (for its workers),
+                         .github/deploy-paths.json, and Release (for its npm package); without the config it prints an
+                         example. Never overwrites a file  [--update] replaces what it rendered before  [--dry-run]
+  pipeline check         say whether the config is sound and the workflows are what it renders now (exits 1 if not)
+
 Repositories
   The checkout's repository is the one its origin remote names (git remote get-url origin), matched
   against repos. --repo <slug> or BREAKAWAY_REPO=<slug> picks another, --all shows every repository
@@ -792,11 +811,13 @@ const commands = {
     if (sub === 'new') {
       const decision = typeof opts.decision === 'string' ? opts.decision : null;
       const next = typeof opts.next === 'string' ? opts.next : null;
+      const spec = typeof opts.spec === 'string' ? opts.spec : null;
       const built = generalAgentRequest(args.slice(1).join(' '), {
         // From a decision, the board runs it in the decision's repository unless --repo says otherwise.
         repo: opts.repo ?? (decision ? null : (await checkoutRepo()).slug),
         decision,
         next,
+        spec,
         force: Boolean(opts.force),
         by: opts.as ?? setting('AGENT'),
       });
@@ -809,7 +830,7 @@ const commands = {
         const image = await upload(ref(answer.task), file);
         if (!opts.json) console.log(`Attached ${image.name} (${Math.ceil(image.size / 1024)} KB).`);
       }
-      print(answer, (d) => generalAgentSummary(d, { next }));
+      print(answer, (d) => generalAgentSummary(d, { next, spec }));
       return;
     }
     if (sub === 'start') {
@@ -935,9 +956,14 @@ const commands = {
     if (sub === 'modify') {
       const slug = need(args[1], 'repository');
       const change = fields();
+      const routineFlags =
+        opts['agents-max'] !== undefined || opts['agents-hourly'] !== undefined || opts.prompt !== undefined;
+      const current =
+        routineFlags || opts.specs !== undefined
+          ? (await call('GET', 'repos')).repos.find((r) => r.slug === slug.toLowerCase())
+          : null;
       // Its caps on agents, under the board's shared limits, and where its agent prompt is (CLD-127): kept with the rest of its routine settings.
-      if (opts['agents-max'] !== undefined || opts['agents-hourly'] !== undefined || opts.prompt !== undefined) {
-        const current = (await call('GET', 'repos')).repos.find((r) => r.slug === slug.toLowerCase());
+      if (routineFlags) {
         const routine = { ...current?.routine };
         for (const [flag, key] of [
           ['agents-max', 'max'],
@@ -948,6 +974,9 @@ const commands = {
         if (opts.prompt !== undefined) routine.prompt = opts.prompt === 'none' ? null : String(opts.prompt);
         change.routine = routine;
       }
+      // Where its specs are (IDEA-31), kept with the rest of its settings; none goes back to docs/specs.
+      if (opts.specs !== undefined)
+        change.settings = { ...current?.settings, specs: opts.specs === 'none' ? null : String(opts.specs) };
       // Its deploy pipeline (BRK-44): a JSON file, or none to clear it; the board refuses one it couldn't use, with the reason.
       if (opts.pipeline !== undefined) {
         if (opts.pipeline === 'none') change.pipeline = null;
@@ -1080,6 +1109,17 @@ const commands = {
       ].join('\n'),
     );
   },
+  async specs() {
+    // A repository's specs (IDEA-31), read from its default branch on GitHub: the checkout's unless --repo names another.
+    const { slug } = await checkoutRepo();
+    if (args[0] === 'show') {
+      const built = specRequest(args.slice(1).join(' ') || undefined, slug);
+      if (built.error || !built.request) fail(built.error ?? 'bad request');
+      print(await call(...built.request), (d) => specLines(d).join('\n'));
+      return;
+    }
+    print(await call(...specsRequest(slug)), (d) => specListLines(d).join('\n'));
+  },
   async features() {
     const sub = args[0];
     const body = () =>
@@ -1381,6 +1421,20 @@ const commands = {
       print(answer, (a) => pullAgentSummary(action, args[1].replace(/^#/u, ''), a));
       return;
     }
+    if (action === 'release') {
+      const built = packageReleaseRequest(args[1], {
+        repo: (await checkoutRepo()).slug,
+        by: opts.as ?? setting('AGENT'),
+      });
+      if (built.error || !built.request) fail(built.error ?? 'bad request');
+      const answer = await call(...built.request);
+      print(
+        answer,
+        () =>
+          `Started ${answer.workflow}'s stable job for ${args[1]}. It stages the stable on npm's latest, where it waits for your approval with 2FA.`,
+      );
+      return;
+    }
     const g = await call(...githubRequest((await checkoutRepo()).slug, { sync: Boolean(opts.sync) }));
     print(g, (d) => {
       if (!d.connected) return "GitHub isn't connected yet: open the GitHub view on the board (docs/tasks.md#github).";
@@ -2122,6 +2176,9 @@ if (opts.help || command === 'help') {
 } else if (command === 'install') {
   // An install repository's own steps (BRK-9): they need no board, so they run before the board's address is checked.
   await (await import('./install/cli.js')).run(args, opts);
+} else if (command === 'pipeline') {
+  // A repository's deploy and release workflows (BRK-90): rendered from its own config, so they need no board either.
+  process.exitCode = (await import('./tasks/pipeline.js')).run(args, opts);
 } else if (!commands[command]) {
   fail(`no command "${command}". npx breakaway help lists them.`);
 } else if (!BASE && command !== 'init-secrets') {

package/src/cli-version.js

@@ -4,5 +4,5 @@
  * and how to update it. scripts/tasks/version.test.js fails when the copied files change and this doesn't:
  * so it lives in the board's package (CLD-135) and the CLI imports it from here.
  */
-export const CLI_VERSION = 63;
-export const CLI_FINGERPRINT = '4e27258ce14d0ac7';
+export const CLI_VERSION = 68;
+export const CLI_FINGERPRINT = 'd62907097b579845';

package/src/packages.js

@@ -0,0 +1,56 @@
+/**
+ * The Packages feed's pure half (BRK-101, docs/specs/IDEA-27-move-ci-cd-to-the-deploy-flow.md, section 2b): what a
+ * workflow run's annotations say it staged on npm, and what npm's public registry answers about it. Read-only: the
+ * board never publishes or approves a package; approving a staged version needs the owner's 2FA on npm.
+ */
+
+/** npm's public registry. The npmjs.com pages answer 403 to anything but a browser, so the board reads this. */
+export const REGISTRY = 'https://registry.npmjs.org';
+
+/** How staging works and how a person approves a staged version (with 2FA): npm's own docs. */
+export const STAGING_DOCS = 'https://docs.npmjs.com/staged-publishing';
+
+/** The package's page on npm; its Staged Packages tab is where the owner approves a staged version. */
+export const packageUrl = (name, version = null) =>
+  `https://www.npmjs.com/package/${name}${version ? `/v/${version}` : ''}`;
+
+const NAME = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/u;
+/** Whether `name` is a name npm would take for a package, scoped or not. */
+export const isPackageName = (name) => typeof name === 'string' && name.length <= 214 && NAME.test(name);
+const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u;
+const TAG = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u;
+
+/**
+ * The line the release flow prints when it stages a version (`::notice title=Staged on npm::…`), word for word:
+ * `<package>@<version> goes live on <dist-tag> once the owner approves it with 2FA: …`. The package may be scoped.
+ */
+const STAGED = /(?<=^|\s)((?:@[^\s@/]+\/)?[^\s@/]+)@(\S+) goes live on (\S+) once the owner approves it\b/gu;
+
+/**
+ * The versions an annotation's message says were staged: `{ name, version, tag }` each, only names, versions, and
+ * dist-tags npm would accept, so nothing else from a run reaches a URL or the board.
+ */
+export function stagedIn(message) {
+  const out = [];
+  for (const m of String(message ?? '').matchAll(STAGED)) {
+    const [, name, version, tag] = m;
+    if (isPackageName(name) && VERSION.test(version) && TAG.test(tag)) out.push({ name, version, tag });
+  }
+  return out;
+}
+
+/** A package name as the registry's path has it: a scoped one's slash is escaped. */
+export const registryName = (name) => name.replace('/', '%2f');
+
+/** The registry's URL for a package's metadata, or for one version of it. */
+export const registryUrl = (name, version = null, base = REGISTRY) =>
+  `${base.replace(/\/$/u, '')}/${registryName(name)}${version ? `/${encodeURIComponent(version)}` : ''}`;
+
+/** A package's dist-tags from its metadata, only the ones that name a version. */
+export function distTags(metadata) {
+  const tags = metadata?.['dist-tags'];
+  if (!tags || typeof tags !== 'object') return {};
+  return Object.fromEntries(
+    Object.entries(tags).filter(([tag, version]) => TAG.test(tag) && VERSION.test(String(version))),
+  );
+}

package/src/repos.js

@@ -10,6 +10,8 @@
  * repository, and a prefix to exactly one area, so a work ID means one task across the install.
  */
 import { AREA_NAMES, InputError, PROJECTS } from './model.js';
+import { isPackageName } from './packages.js';
+import { checkSettings } from './specs.js';
 
 /** The slug a task without `repo` falls back to while the registry has no default: nothing is registered, so no task is. */
 export const NO_REPO = 'default';
@@ -114,26 +116,42 @@ function jsonField(value, what) {
 }
 
 const WORKER_NAME = /^[\w.-]{1,100}$/u;
+/** The fields a repository's pipeline has, as `repos modify --pipeline` and Turn on deploys (WEB-13) set it. */
+export const PIPELINE_KEYS = ['workers', 'workflows', 'deployPaths', 'package'];
 const DEPLOY_PATHS_PATH = /^(?!\/)(?!.*\.\.)[\w./-]{1,200}\.json$/u;
 
 /**
- * A repository's deploy pipeline as the owner sets it: the shape `pipelineOf` (release.js) reads, refused with
- * the reason when it would read none. `workers.staging` and `workers.production` are required; `workflows`
- * (deploy, promote, rollback, workflow file names) and `deployPaths` (a JSON file in the repository) are optional.
+ * A repository's deploy pipeline as the owner sets it: the shape `pipelineOf` and `packageOf` (release.js) read,
+ * refused with the reason when they would read none. It needs `workers` (`staging` and `production`, the Workers it
+ * deploys), `package` (the npm package it releases, BRK-103), or both. `workflows` (deploy, promote, rollback, and
+ * release, workflow file names) and `deployPaths` (a JSON file in the repository) are optional.
  */
-function checkPipeline(pipeline) {
+export function checkPipeline(pipeline) {
   if (!pipeline) return null;
-  const known = { workers: ['staging', 'production'], workflows: ['deploy', 'promote', 'rollback'] };
+  const known = { workers: ['staging', 'production'], workflows: ['deploy', 'promote', 'rollback', 'release'] };
   for (const key of Object.keys(pipeline)) {
-    if (!['workers', 'workflows', 'deployPaths'].includes(key))
-      throw new InputError(`pipeline has no "${key.slice(0, 40)}"; it has workers, workflows, and deployPaths`);
+    if (!PIPELINE_KEYS.includes(key))
+      throw new InputError(
+        `pipeline has no "${key.slice(0, 40)}"; it has workers, package, workflows, and deployPaths`,
+      );
   }
   const out = {};
+  const hasPackage = pipeline.package !== undefined && pipeline.package !== null && pipeline.package !== '';
+  if (hasPackage) {
+    const name = typeof pipeline.package === 'string' ? pipeline.package.trim() : null;
+    if (!isPackageName(name))
+      throw new InputError(
+        'pipeline.package is the npm package’s name, as its package.json says, like widgets or @acme/widgets',
+      );
+    out.package = name;
+  }
   for (const [group, keys] of Object.entries(known)) {
     const value = pipeline[group];
     if (value === undefined || value === null) {
-      if (group === 'workers')
-        throw new InputError('pipeline.workers needs staging and production, the names of the two Workers');
+      if (group === 'workers' && !hasPackage)
+        throw new InputError(
+          'pipeline needs workers (staging and production, the names of the two Workers it deploys), package (the npm package it releases), or both',
+        );
       continue;
     }
     if (typeof value !== 'object' || Array.isArray(value)) throw new InputError(`pipeline.${group} is an object`);
@@ -292,6 +310,7 @@ export function checkRepo(
   for (const key of JSON_FIELDS) if (key in input) row[key] = jsonField(input[key], key);
   if ('pipeline' in input) row.pipeline = checkPipeline(row.pipeline);
   if ('routine' in input) row.routine = checkRoutine(row.routine, caps);
+  if ('settings' in input) row.settings = checkSettings(row.settings);
 
   const adding = [...list(input.areas), ...list(input.addAreas)].map(parseArea);
   for (const project of list(input.removeAreas).map((p) => String(p).trim().toLowerCase())) {

package/src/specs.js

@@ -0,0 +1,96 @@
+/**
+ * A repository's specs (docs/specs/IDEA-31-specs-view.md, sections 1 and 2): where they are, and what the board
+ * reads from each file. Pure, so it's tested without the Durable Object; reading them through GitHub is in
+ * store-specs.js. The board never stores a spec: it reads the files on the default branch when asked.
+ */
+import { InputError } from './model.js';
+
+/** Where a repository keeps its specs when its settings don't say: where breakaway and the template put them. */
+export const DEFAULT_SPECS_DIR = 'docs/specs';
+/** The largest spec the board reads; a bigger one is a link to GitHub. */
+export const SPEC_MAX_BYTES = 1_048_576;
+const SPECS_DIR = /^(?!\/)(?!.*\.\.)[\w./-]{1,200}$/u;
+const SPEC_NAME = /^[\w.-]{1,200}\.md$/u;
+const WID = /^([A-Z]{2,8}-\d+)(?:[-.]|$)/u;
+
+/**
+ * A repository's specs directory as the owner sets it (`settings.specs`): a relative directory, with no `..`,
+ * of at most 200 characters, checked like `routine.prompt`. Empty or null means the default, so it's left out.
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+export function checkSpecsDir(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const dir = String(value).trim().replace(/^\.\//u, '').replace(/\/+$/u, '');
+  if (!SPECS_DIR.test(dir) || dir.split('/').some((part) => part === '' || part === '.'))
+    throw new InputError('settings.specs is a directory in the repository, like docs/specs');
+  return dir;
+}
+
+/**
+ * A repository's `settings`, checked: its specs directory (`specs`) when it has one; the rest is kept as it is.
+ * @param {Record<string, any> | null} settings
+ */
+export function checkSettings(settings) {
+  if (!settings) return null;
+  const out = { ...settings };
+  const specs = checkSpecsDir(out.specs);
+  if (specs) out.specs = specs;
+  else delete out.specs;
+  return Object.keys(out).length ? out : null;
+}
+
+/** The directory, in the repository, its specs are in. */
+export const specsDirOf = (repo) => repo?.settings?.specs || DEFAULT_SPECS_DIR;
+
+/** A path as a task's `spec` field or a request may give it: no leading `./` or `/`. */
+export const normalPath = (path) =>
+  String(path ?? '')
+    .trim()
+    .replace(/^(?:\.\/|\/)+/u, '');
+
+/**
+ * Whether `path` is a file the board reads as one of the repository's specs: a Markdown file directly in `dir`
+ * (its README.md too). Subdirectories, other files, and anything outside it are refused.
+ * @param {string} dir
+ * @param {string} path
+ */
+export function inSpecsDir(dir, path) {
+  const p = normalPath(path);
+  if (!p.startsWith(`${dir}/`)) return false;
+  const name = p.slice(dir.length + 1);
+  return SPEC_NAME.test(name) && !name.startsWith('.');
+}
+
+/** Whether a file in the directory is a spec, not its introduction. */
+export const isSpecFile = (name) => SPEC_NAME.test(name) && !name.startsWith('.') && name.toLowerCase() !== 'readme.md';
+
+/**
+ * What the list shows for one spec: its title (the first `# ` heading, else the file name), its status (the
+ * first word after `Status:` on the line under the heading, as the template has it, else null), and the work ID
+ * its file name starts with, if any. `text` is null for a file the board didn't read (too large).
+ * @param {string} name the file name
+ * @param {string | null} text
+ */
+export function specMeta(name, text) {
+  const wid = WID.exec(name)?.[1] ?? null;
+  const fallback = name.replace(/\.md$/u, '');
+  if (text === null || text === undefined) return { wid, title: fallback, status: null };
+  const lines = String(text).split(/\r?\n/u);
+  const at = lines.findIndex((l) => /^#\s+\S/u.test(l));
+  if (at < 0) return { wid, title: fallback, status: null };
+  const title =
+    lines[at]
+      .replace(/^#\s+/u, '')
+      .replace(/\s+#+\s*$/u, '')
+      .trim() || fallback;
+  const under = lines.slice(at + 1).find((l) => l.trim() !== '') ?? '';
+  const status = /\bStatus:\s*\**\s*([A-Za-z][\w-]*)/u.exec(under)?.[1]?.toLowerCase() ?? null;
+  return { wid, title, status };
+}
+
+/** Newest first by the work ID's number, then by path; specs without a work ID last. */
+export function bySpecOrder(a, b) {
+  const n = (s) => (s.wid ? Number(s.wid.split('-')[1]) : -1);
+  return n(b) - n(a) || a.path.localeCompare(b.path);
+}

package/template/pipeline/deploy.yml

@@ -0,0 +1,178 @@
+# {{header}}
+#
+# Deploy: a merge to {{branchName}} that passes its checks goes to staging, the Worker {{stagingName}}. Production
+# changes only when the owner promotes a staging build (promote.yml). The build is kept as the workflow artifact
+# release-<commit>, and Promote deploys those same files to production. Deploys record GitHub Deployments, which the
+# board reads. Agents never run this workflow.
+name: Deploy
+
+on:
+  # After every check workflow has passed on a push to {{branchName}}: each one's completion starts this, and only the
+  # run that finds them all passed deploys.
+  workflow_run:
+    workflows: {{checks}}
+    types: [completed]
+    branches: [{{branch}}]
+  # By hand: deploy {{branchName}}'s latest commit to staging, once its checks have passed.
+  workflow_dispatch:
+
+permissions: {}
+
+# One staging deploy at a time. One that waits finds staging already runs its commit, or a newer one, and stops.
+concurrency:
+  group: deploy-staging
+  cancel-in-progress: false
+
+env:
+  STAGING: {{staging}}
+  BRANCH: {{branch}}
+  CHECKS: {{checksEnv}}
+  HEALTH_URL: {{healthStaging}}
+
+jobs:
+  staging:
+    name: staging
+    if: github.event_name == 'workflow_dispatch' || (github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'push' && github.event.workflow_run.head_repository.full_name == github.repository)
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    # CLOUDFLARE_API_TOKEN is a secret of this environment, which only {{branchName}} may use: a token for the staging
+    # Worker only. CLOUDFLARE_ACCOUNT_ID is a repository variable.
+    environment: staging
+    permissions:
+      contents: read
+      deployments: write
+      actions: read
+    env:
+      GITHUB_TOKEN: ${{ github.token }}
+      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+      CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
+      SHA: ${{ github.event.workflow_run.head_sha || github.sha }}
+      RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+      # What the repository's own commands (beforeDeploy) read to know where they run.
+      BREAKAWAY_ENV: staging
+      WORKER: {{staging}}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.workflow_run.head_sha || github.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 22
+
+      - name: Check it should deploy
+        id: plan
+        run: node scripts/deploy-plan.mjs plan --staging "$STAGING" --sha "$SHA" --branch "$BRANCH" --checks "$CHECKS" --paths .github/deploy-paths.json >> "$GITHUB_OUTPUT"
+
+      - name: Record the start
+        id: record
+        if: steps.plan.outputs.deploy == 'true'
+        run: node scripts/record-deployment.mjs --environment "$STAGING" --sha "$SHA" --state in_progress --description "pre-release · building" --log-url "$RUN_URL"
+
+      - name: Install and build
+        if: steps.plan.outputs.deploy == 'true'
+        run: |
+          set -euo pipefail
+          if grep -q '"packageManager"' package.json 2>/dev/null; then corepack enable; fi
+          {{@install}}
+          {{@build}}
+
+      - name: Keep the build as the release artifact
+        id: artifact
+        if: steps.plan.outputs.deploy == 'true'
+        run: |
+          set -euo pipefail
+          # The commit as installed and built: Promote deploys these files to production, and builds nothing.
+          mkdir -p "$RUNNER_TEMP/release"
+          tar --exclude=./.git -czf "$RUNNER_TEMP/release/tree.tgz" .
+          echo "digest=$(node scripts/release-artifact.mjs digest "$RUNNER_TEMP/release")" >> "$GITHUB_OUTPUT"
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: steps.plan.outputs.deploy == 'true'
+        with:
+          name: release-${{ github.event.workflow_run.head_sha || github.sha }}
+          path: ${{ runner.temp }}/release
+          retention-days: 90
+          compression-level: 0
+          if-no-files-found: error
+
+      - name: Deploy to staging
+        id: deploy
+        if: steps.plan.outputs.deploy == 'true'
+        env:
+          FROM: ${{ steps.plan.outputs.from }}
+          DEPLOYMENT: ${{ steps.record.outputs.deployment }}
+        run: |
+          set -euo pipefail
+          wrangler() { npx --yes wrangler "$@" --name "$WORKER"{{stagingEnvFlag}}; }
+          step() { node scripts/record-deployment.mjs --deployment "$DEPLOYMENT" --state in_progress --description "pre-release · $1" > /dev/null; }
+          # The version running now, which a failed check goes back to. Only a Worker that doesn't exist yet has none:
+          # any other failure to list stops here, since deploying with nothing to go back to isn't safe.
+          previous=""
+          if wrangler deployments list --json > "$RUNNER_TEMP/deployments.json" 2> "$RUNNER_TEMP/list-error.txt"; then
+            previous=$(node scripts/deploy-plan.mjs current < "$RUNNER_TEMP/deployments.json" | sed 's/^version=//')
+          else
+            cat "$RUNNER_TEMP/deployments.json" "$RUNNER_TEMP/list-error.txt" | node scripts/deploy-plan.mjs missing > /dev/null
+          fi
+          # The migrations this deploy runs: the ones added since staging's last deploy.
+          migrations=""
+          if [ -d migrations ]; then
+            node scripts/check-migrations.mjs --dir migrations ${FROM:+--base "$FROM"}
+            if [ -n "$FROM" ]; then
+              migrations=$(git diff --name-only --diff-filter=A "$FROM" "$SHA" -- migrations | grep '\.sql$' | xargs -r -n1 basename | paste -sd, - || true)
+            fi
+          fi
+          echo "migrations=$migrations" >> "$GITHUB_OUTPUT"
+          step migrating
+          {{@beforeDeploy}}
+          step deploying
+          export WRANGLER_OUTPUT_FILE_PATH="$RUNNER_TEMP/wrangler-output.ndjson"
+          if [ -z "$previous" ]; then
+            # The first deploy makes the Worker.
+            wrangler deploy --message "${SHA:0:7}"
+            version=$(node scripts/deploy-plan.mjs uploaded < "$WRANGLER_OUTPUT_FILE_PATH" | sed 's/^version=//')
+          else
+            wrangler versions upload --message "${SHA:0:7}"
+            version=$(node scripts/deploy-plan.mjs uploaded < "$WRANGLER_OUTPUT_FILE_PATH" | sed 's/^version=//')
+            wrangler versions deploy "$version@100%" --message "${SHA:0:7}" --yes
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          step checking
+          if [ -z "$HEALTH_URL" ]; then
+            echo "::notice title=Not checked::Staging runs ${SHA:0:7} as version $version. Set healthCheck in .github/breakaway-pipeline.json and the next deploy checks it, and goes back if it doesn't answer."
+            exit 0
+          fi
+          for attempt in $(seq 1 18); do
+            if curl -fsS --max-time 10 -o /dev/null "$HEALTH_URL"; then
+              echo "Staging runs ${SHA:0:7} as version $version, and $HEALTH_URL answers."
+              exit 0
+            fi
+            sleep 5
+          done
+          if [ -n "$previous" ] && wrangler rollback "$previous" --message "${SHA:0:7} failed its check" --yes; then
+            echo "rolled_back=true" >> "$GITHUB_OUTPUT"
+            echo "::error title=Rolled back::${SHA:0:7} didn't answer $HEALTH_URL within 90 seconds, so staging went back to version $previous. Read the Worker's logs on Cloudflare."
+          else
+            echo "::error title=Failed its check::${SHA:0:7} didn't answer $HEALTH_URL within 90 seconds, and staging had no version to go back to. Read the Worker's logs on Cloudflare."
+          fi
+          exit 1
+
+      - name: Record the end
+        if: always() && steps.record.outputs.deployment
+        env:
+          DEPLOYMENT: ${{ steps.record.outputs.deployment }}
+          OUTCOME: ${{ job.status }}
+          VERSION: ${{ steps.deploy.outputs.version }}
+          DIGEST: ${{ steps.artifact.outputs.digest }}
+          MIGRATIONS: ${{ steps.deploy.outputs.migrations }}
+          ROLLED_BACK: ${{ steps.deploy.outputs.rolled_back }}
+        run: |
+          set -euo pipefail
+          record() { node scripts/record-deployment.mjs --deployment "$DEPLOYMENT" --log-url "$RUN_URL" "$@" > /dev/null; }
+          if [ "$OUTCOME" = success ]; then
+            record --state success --note pre-release --version "$VERSION" --artifact "$DIGEST" --migrations "$MIGRATIONS" ${HEALTH_URL:+--environment-url "$HEALTH_URL"}
+          elif [ "$ROLLED_BACK" = true ]; then
+            record --state failure --description "rolled back: version $VERSION failed its check"
+          else
+            record --state failure --description "failed: the run says why"
+          fi