breakaway 2.0.0-main.99 → 2.0.0

package/scripts/tasks/infra.js

@@ -14,7 +14,7 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { DESIRED_DIR, environmentOfFile } from '../../src/infra-desired.js';
+import { DESIRED_DIR } from '../../src/infra-desired.js';
 import { SHORT_LIVED_FILE } from '../../src/infra-short-lived.js';
 import { checkApplyResult } from '../../src/infra-provider.js';
 import { providers as registry } from '../../src/infra-providers.js';
@@ -29,15 +29,21 @@ import {
   runPath,
   runReport,
 } from '../../src/infra-runner.js';
-import { fill, lintWorkflow } from './pipeline.js';
+import {
+  RUNNER_RENDER_HEADER,
+  RUNNER_TEMPLATE,
+  RunnerRenderError,
+  environmentsIn,
+  renderRunner,
+  runnerStep,
+} from '../../src/infra-runner-render.js';
 
 /** The first line of the rendered workflow: how `--update` knows the file is its own to replace. */
-export const HEADER = `Rendered by npx breakaway infra init from the environments in ${DESIRED_DIR}/: add one there and run npx breakaway infra init --update, not this file.`;
+export const HEADER = RUNNER_RENDER_HEADER;
 /** Where the runner keeps the checked plan between its steps, in the job's temporary folder. */
 export const STATE_FILE = 'breakaway-infra-run.json';
-const BRANCH = /^(?!.*\.\.)[A-Za-z0-9._/-]{1,100}$/u;
 const HERE = dirname(fileURLToPath(import.meta.url));
-const TEMPLATE = join(HERE, '..', '..', 'template', 'infra', 'apply.yml');
+const TEMPLATE = join(HERE, '..', '..', RUNNER_TEMPLATE);
 const USER_AGENT = 'breakaway-infra-runner';
 
 /** A mistake `infra init` can name. */
@@ -48,66 +54,14 @@ const bad = (message) => {
 
 // ---- infra init ----------------------------------------------------------------------------
 
-/**
- * The environments the runner offers, from the file names in the desired-state folder: each `<environment>.json`,
- * sorted, skipping policy.json, scaling.json, and anything that isn't JSON.
- * @param {string[]} names
- */
-export function environmentsIn(names) {
-  const environments = [];
-  for (const name of names) {
-    const found = environmentOfFile(name);
-    if (!found) continue;
-    if ('problem' in found) throw new InfraError(`${DESIRED_DIR}/${found.problem}.`);
-    environments.push(found.environment);
-  }
-  if (!environments.length)
-    bad(
-      `${DESIRED_DIR}/ has no environment's file, so there's nothing to apply to: write <environment>.json for each (like staging.json), then run this again.`,
-    );
-  return environments.sort();
-}
-
-/**
- * The runner's workflow for these environments, applied from `branch`, running breakaway `version`. With `shortLived`
- * (the folder has short-lived.json), the environment is any name, since each short-lived one is new, and the run may
- * name the GitHub environment that holds the write token: `short-lived` for all of them (BRK-242).
- * @param {{ environments: string[], branch: string, version: string, shortLived?: boolean }} input
- * @param {string} template template/infra/apply.yml
- * @returns {{ path: string, text: string }}
- */
-export function renderRunner({ environments, branch, version, shortLived = false }, template) {
-  if (!BRANCH.test(branch)) bad(`${branch.slice(0, 80)} isn't a branch's name.`);
-  if (!/^\d+\.\d+\.\d+(?:-[\w.]+)?$/u.test(version)) bad(`${version} isn't a breakaway release.`);
-  const text = fill(template, {
-    header: HEADER,
-    branchName: branch,
-    version,
-    shortLived,
-    fixedOnly: !shortLived,
-    environments: environments.map((name) => `- ${JSON.stringify(name)}`),
-  });
-  const problems = lintWorkflow(text);
-  if (problems.length) throw new Error(`${RUNNER_WORKFLOW} renders with problems: ${problems.join('; ')}`);
-  return { path: RUNNER_WORKFLOW, text };
-}
+// The render is shared with the board (src/infra-runner-render.js, BRK-307), so both write the same file.
+export { environmentsIn, renderRunner };
 
 /**
  * What `infra init` does with the rendered file, given what's there (null when nothing): write it, leave it (the
  * same), or refuse it (the repository's own, or rendered before when `update` isn't set).
- * @param {{ path: string, text: string }} file
- * @param {string | null} there
- * @param {{ update?: boolean }} [options]
- * @returns {{ write: boolean, same?: boolean, refused?: string }}
  */
-export function initStep(file, there, { update = false } = {}) {
-  if (there === null) return { write: true };
-  if (there === file.text) return { write: false, same: true };
-  if (!there.startsWith(`# ${HEADER}`))
-    return { write: false, refused: "it's the repository's own, not rendered: rename it, then run infra init again" };
-  if (!update) return { write: false, refused: 'it differs from what infra init renders: run infra init --update' };
-  return { write: true };
-}
+export const initStep = runnerStep;
 
 /** The checkout's top folder, or the folder the command runs in. */
 function topOf(cwd) {
@@ -341,7 +295,7 @@ export async function run(args, opts, io = {}) {
     if (command !== 'init') bad('infra has init. npx breakaway help says what it does.');
     return init(opts, { cwd, log, error, version: io.version });
   } catch (e) {
-    if (!(e instanceof InfraError)) throw e;
+    if (!(e instanceof InfraError) && !(e instanceof RunnerRenderError)) throw e;
     error(`infra: ${e.message}`);
     return 1;
   }

package/scripts/tasks/pipeline.js

@@ -13,6 +13,9 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { YamlError, parseYaml as readYaml } from '../../src/yaml.js';
+import { fill, lintWorkflow } from '../../src/workflow-render.js';
+
+export { fill, lintWorkflow };
 
 export const CONFIG_PATH = '.github/breakaway-pipeline.json';
 export const DEPLOY_PATHS = '.github/deploy-paths.json';
@@ -43,8 +46,6 @@ export const HELPERS = {
   rollback: ['scripts/deploy-plan.mjs', 'scripts/record-deployment.mjs'],
   release: ['scripts/deploy-plan.mjs', 'scripts/package-release.mjs'],
 };
-/** The secrets a rendered workflow may read: each lives in a GitHub environment only the default branch can use. */
-const SECRETS = new Set(['CLOUDFLARE_API_TOKEN', 'NPM_TOKEN']);
 
 /** A config's or a workflow's mistake, in words the owner or the agent can act on. */
 export class PipelineError extends Error {}
@@ -233,46 +234,6 @@ export function checkConfig(raw, { packageJson = () => null } = {}) {
   return { workers, wranglerEnv, branch, checks, install, build, beforeDeploy, deployPaths, healthCheck, package: pkg };
 }
 
-/**
- * A template with its values: `{{key}}` is replaced inline, a line that is only `{{@key}}` becomes the list's lines at
- * that indentation (none for an empty list), and lines between `{{#if key}}` and `{{/if}}` stay only when the value is
- * truthy.
- * @param {string} template
- * @param {Record<string, any>} values
- */
-export function fill(template, values) {
-  const out = [];
-  const keep = [true];
-  for (const line of template.split('\n')) {
-    const cond = /^\s*\{\{#if (\w+)\}\}\s*$/u.exec(line);
-    if (cond) {
-      keep.push(keep.at(-1) && Boolean(values[cond[1]]));
-      continue;
-    }
-    if (/^\s*\{\{\/if\}\}\s*$/u.test(line)) {
-      if (keep.length === 1) throw new Error('{{/if}} without {{#if}}');
-      keep.pop();
-      continue;
-    }
-    if (!keep.at(-1)) continue;
-    const list = /^(\s*)\{\{@(\w+)\}\}\s*$/u.exec(line);
-    if (list) {
-      const items = values[list[2]];
-      if (!Array.isArray(items)) throw new Error(`{{@${list[2]}}} needs a list`);
-      for (const item of items) out.push(`${list[1]}${item}`);
-      continue;
-    }
-    out.push(
-      line.replace(/(?<!\$)\{\{(\w+)\}\}/gu, (_, key) => {
-        if (!(key in values)) throw new Error(`the template's {{${key}}} has no value`);
-        return String(values[key]);
-      }),
-    );
-  }
-  if (keep.length !== 1) throw new Error('{{#if}} without {{/if}}');
-  return out.join('\n');
-}
-
 const quote = (value) => JSON.stringify(value ?? '');
 
 /** The values the templates take, from a checked config. */
@@ -344,134 +305,6 @@ export function parseYaml(text) {
   }
 }
 
-const CONTEXTS = new Set([
-  'github',
-  'inputs',
-  'secrets',
-  'vars',
-  'steps',
-  'env',
-  'job',
-  'needs',
-  'runner',
-  'matrix',
-  'strategy',
-]);
-
-/** The `${{ }}` expressions in a value, and the value itself when it's an `if:` (an expression without the braces). */
-function expressionsIn(text, isIf) {
-  const found = [...String(text).matchAll(/\$\{\{([\s\S]*?)\}\}/gu)].map((m) => m[1]);
-  if (isIf && !found.length) found.push(String(text));
-  return found;
-}
-
-/** Every string under a value, with whether it's an `if:`. */
-function stringsIn(value, key = '') {
-  if (typeof value === 'string') return [{ text: value, isIf: key === 'if' }];
-  if (Array.isArray(value)) return value.flatMap((item) => stringsIn(item));
-  if (isObject(value)) return Object.entries(value).flatMap(([k, v]) => stringsIn(v, k));
-  return [];
-}
-
-/**
- * The problems GitHub (or actionlint) would find in a rendered workflow, as messages; none when it's sound. It parses
- * the YAML, then checks the shape (on, permissions, jobs with runs-on, a timeout, and steps), that every action is
- * pinned to a commit, that every expression names a context Actions has, a step that ran before, an input the workflow
- * takes, or a secret the pipeline uses, that secrets are read only in a job with an environment, that run scripts take
- * no `${{ }}` (they read env instead), and that nothing of the template is left over.
- * @param {string} text
- * @returns {string[]}
- */
-export function lintWorkflow(text) {
-  const problems = [];
-  const leftover = text.replace(/\$\{\{[\s\S]*?\}\}/gu, '').match(/\{\{[#/@]?\w+\}\}/u);
-  if (leftover) problems.push(`the template's ${leftover[0]} is left over`);
-  let doc;
-  try {
-    doc = parseYaml(text);
-  } catch (error) {
-    return [...problems, error.message];
-  }
-  if (typeof doc.name !== 'string' || !doc.name) problems.push('it has no name');
-  if (!isObject(doc.on)) problems.push('it has no on: triggers');
-  else if ('pull_request_target' in doc.on) problems.push('pull_request_target runs untrusted code with secrets');
-  if (!isObject(doc.permissions) || Object.keys(doc.permissions).length)
-    problems.push('the workflow sets permissions: {}, and each job asks for what it needs');
-  if (!isObject(doc.jobs) || !Object.keys(doc.jobs).length) return [...problems, 'it has no jobs'];
-  const inputs = Object.keys(doc.on?.workflow_dispatch?.inputs ?? {});
-  for (const [name, input] of Object.entries(doc.on?.workflow_dispatch?.inputs ?? {}))
-    if (!['string', 'boolean', 'choice', 'number', 'environment'].includes(input?.type))
-      problems.push(`input ${name} has no type`);
-
-  const checkExpressions = (strings, where, steps, jobLevel) => {
-    for (const { text: value, isIf } of strings)
-      for (const expression of expressionsIn(value, isIf)) {
-        const code = expression.replace(/'(?:[^']|'')*'/gu, "''");
-        for (const m of code.matchAll(/(?<![\w.-])([A-Za-z_][\w-]*)((?:\.[\w-]+)*)/gu)) {
-          const [, context, path] = m;
-          if (!path) {
-            if (!/^\s*\(/u.test(code.slice(m.index + context.length)) && !['true', 'false', 'null'].includes(context))
-              problems.push(`${where}: "${context}" isn't a context or a function`);
-            continue;
-          }
-          const [first] = path.slice(1).split('.');
-          if (!CONTEXTS.has(context)) problems.push(`${where}: no context "${context}"`);
-          else if (context === 'secrets' && !SECRETS.has(first))
-            problems.push(`${where}: the pipeline uses no secret ${first}`);
-          else if (context === 'inputs' && !inputs.includes(first)) problems.push(`${where}: no input ${first}`);
-          else if (context === 'steps' && !steps.includes(first))
-            problems.push(`${where}: no step ${first} before this one`);
-          else if (context === 'env' && jobLevel) problems.push(`${where}: env isn't available here`);
-        }
-      }
-  };
-  checkExpressions(stringsIn({ on: doc.on, env: doc.env, concurrency: doc.concurrency }), 'the workflow', [], false);
-
-  for (const [jobName, job] of Object.entries(doc.jobs)) {
-    const where = `job ${jobName}`;
-    if (!isObject(job)) {
-      problems.push(`${where} isn't a mapping`);
-      continue;
-    }
-    if (!job['runs-on']) problems.push(`${where} has no runs-on`);
-    if (typeof job['timeout-minutes'] !== 'number') problems.push(`${where} has no timeout-minutes`);
-    if (!isObject(job.permissions)) problems.push(`${where} doesn't say its permissions`);
-    for (const need of [job.needs ?? []].flat())
-      if (!(need in doc.jobs)) problems.push(`${where} needs ${need}, which isn't a job`);
-    const { steps = [], ...rest } = job;
-    checkExpressions(stringsIn({ if: rest.if }), where, [], true);
-    checkExpressions(stringsIn({ ...rest, if: undefined, outputs: undefined }), where, [], false);
-    // A job's outputs read its steps once they've all run.
-    const stepIds = Array.isArray(steps) ? steps.map((s) => s?.id).filter(Boolean) : [];
-    checkExpressions(stringsIn({ outputs: rest.outputs }), `${where}'s outputs`, stepIds, false);
-    if (stringsIn(job).some(({ text: value }) => /\bsecrets\./u.test(value)) && !job.environment)
-      problems.push(`${where} reads a secret outside an environment`);
-    if (!Array.isArray(steps) || !steps.length) {
-      problems.push(`${where} has no steps`);
-      continue;
-    }
-    const ids = [];
-    steps.forEach((step, i) => {
-      const at = `${where}, step ${i + 1}${step?.name ? ` (${step.name})` : ''}`;
-      if (!isObject(step)) {
-        problems.push(`${at} isn't a mapping`);
-        return;
-      }
-      if ('uses' in step === 'run' in step) problems.push(`${at} has one of uses or run`);
-      if ('uses' in step && !/^[\w.-]+\/[\w./-]+@[0-9a-f]{40}$/u.test(String(step.uses)))
-        problems.push(`${at} uses ${step.uses}, which isn't pinned to a commit`);
-      if (typeof step.run === 'string' && step.run.includes('${{'))
-        problems.push(`${at} puts \${{ }} in its script: pass it through env`);
-      checkExpressions(stringsIn(step), at, ids, false);
-      if (step.id !== undefined) {
-        if (ids.includes(step.id)) problems.push(`${at} repeats the id ${step.id}`);
-        ids.push(String(step.id));
-      }
-    });
-  }
-  return problems;
-}
-
 /** The run scripts of a parsed workflow, `[{ where, script }]`, for a shell's syntax check. */
 export function runScripts(text) {
   const doc = parseYaml(text);

package/scripts/tasks.mjs

@@ -371,13 +371,16 @@ Working
                          --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)
+                         [--brief <text> | --brief-file <path>] [--release <x.y.z>]
                          --from <ref> (owner): made from the group <ref> is in on the Dependencies view: its open tasks
                          join, and tasks already in another feature stay there
-  features modify <slug> change one (owner): --title, --brief, --brief-file, --release <x.y.z|none>, --state open|shipped
+  features modify <slug> change one: --title, --brief, --brief-file, --release <x.y.z|none>; --state open|shipped is the
+                         owner's. An agent's change shows in Activity and on the feature, and the owner can undo it
+  features pull <x.y.z>  pull a release's open tasks, and what they wait for, into now  [--into next] [--dry-run];
+                         the next release goes in first. An agent's pull shows on the feature, and the owner can undo it
   routines add <slug>    new routine (owner, or the agent of a routine maker's task)  --name <text> --prompt <text> | --prompt-file <path>  [--done-when <text>] [--horizon now|next|later] [--gap <minutes>] [--daily <n>]
                          [--repo <slug>] the repository it runs in (default: the checkout's)
-  routines modify <slug> change one (owner, or the agent of the routine maker's task that made it): the same options (--repo <slug> moves it), and --enabled yes|no; --schedule "0 9 * * 1" runs it on a cron schedule (UTC), --schedule "" clears it; --trigger-start auto|wait sets whether a webhook or GitHub event starts the agent or waits for your Start; --github-events pr_merged,release_published,workflow_failed,issue_opened,issue_reopened (or "") starts it on those GitHub events
+  routines modify <slug> change one (owner, or the agent of the routine maker's task that made it): the same options (--repo <slug> moves it), and --enabled yes|no; --schedule "0 9 * * 1" runs it on a cron schedule (UTC), --schedule "" clears it; --trigger-start auto|wait sets whether a webhook or GitHub event starts the agent or waits for your Start; --github-events pr_merged,release_published,workflow_failed,issue_opened,issue_reopened (or "") starts it on those GitHub events; --infra-events plan.failed,drift.found:environment=staging,budget.crossed:percent=80 (or "", the owner's) starts it on those infrastructure events, each with filters environment=, kind=, resource= (several joined by +)
   routines trigger <slug> new webhook/API trigger (owner): prints its secret once  [--label <text>]
   routines revoke <slug> <id>  revoke a trigger
   routines pause|resume  stop or allow every routine  [--daily-all <n>] sets the cap for all routines a day
@@ -1320,6 +1323,7 @@ const commands = {
         enabled: yes(opts.enabled),
         triggerStart: opts['trigger-start'],
         githubEvents: opts['github-events'],
+        infraEvents: opts['infra-events'],
         gapMinutes: opts.gap === undefined ? undefined : Number(opts.gap),
         dailyCap: opts.daily === undefined ? undefined : Number(opts.daily),
       };
@@ -1426,7 +1430,7 @@ const commands = {
         ...(d.routines.length ? [''] : ['', 'No routines yet: routines add <slug> --name … --prompt …']),
         ...d.routines.map(
           (x) =>
-            `  ${x.slug.padEnd(16)} ${several ? `${x.repo}: ` : ''}${x.enabled ? 'on ' : 'off'} ${x.openRun ? `running ${x.openRun.wid}` : x.lastRun ? `last ${x.lastRun.wid ?? ''} ${ago(x.lastRun.at)}` : 'never run'}, ${x.runsToday} of ${x.dailyCap} today${x.schedule ? `, schedule ${x.schedule}${x.nextRun ? ` (next ${x.nextRun.slice(0, 16).replace('T', ' ')} UTC)` : ''}` : ''}${x.triggers?.length ? `, ${x.triggers.length} trigger${x.triggers.length === 1 ? '' : 's'} (${x.triggerStart === 'auto' ? 'start by themselves' : 'wait for Start'}; ids ${x.triggers.map((t) => t.id).join(', ')})` : ''}${x.disabledReason ? `, off: ${x.disabledReason}` : ''}`,
+            `  ${x.slug.padEnd(16)} ${several ? `${x.repo}: ` : ''}${x.enabled ? 'on ' : 'off'} ${x.openRun ? `running ${x.openRun.wid}` : x.lastRun ? `last ${x.lastRun.wid ?? ''} ${ago(x.lastRun.at)}` : 'never run'}, ${x.runsToday} of ${x.dailyCap} today${x.schedule ? `, schedule ${x.schedule}${x.nextRun ? ` (next ${x.nextRun.slice(0, 16).replace('T', ' ')} UTC)` : ''}` : ''}${x.triggers?.length ? `, ${x.triggers.length} trigger${x.triggers.length === 1 ? '' : 's'} (${x.triggerStart === 'auto' ? 'start by themselves' : 'wait for Start'}; ids ${x.triggers.map((t) => t.id).join(', ')})` : ''}${x.infraEvents?.length ? `, on ${x.infraEvents.map((e) => e.event).join(', ')}` : ''}${x.disabledReason ? `, off: ${x.disabledReason}` : ''}`,
         ),
       ].join('\n'),
     );
@@ -1550,6 +1554,21 @@ const commands = {
       print({ feature }, (d) => `Saved ${d.feature.slug}.`);
       return;
     }
+    if (sub === 'pull') {
+      const release = need(args[1], 'release').replace(/^v(?=\d)/u, '');
+      const into = opts.into ?? 'now';
+      const dryRun = Boolean(opts['dry-run']);
+      const pulled = await call('POST', `releases/${enc(release)}/pull`, { into, dryRun, ...(by ? { by } : {}) });
+      print(pulled, (d) =>
+        [
+          `${d.dryRun ? 'Would move' : 'Moved'} ${d.tasks.length} ${d.tasks.length === 1 ? 'task' : 'tasks'} of ${d.release} into ${d.into}:`,
+          ...d.tasks.map(
+            (t) => `  ${t.wid ?? t.uuid.slice(0, 8)}  ${t.description}${t.chain ? ' (it waits for this)' : ''}`,
+          ),
+        ].join('\n'),
+      );
+      return;
+    }
     if (sub === 'show') {
       const { feature } = await call('GET', `features/${enc(need(args[1], 'feature').toLowerCase())}`);
       print({ feature }, (d) => featureLines(d.feature).join('\n'));

package/src/infra-cloudflare-analytics.js

@@ -249,14 +249,28 @@ export const COST_DATASETS = {
   },
 };
 
-/** How far back health looks: errors and slowness in the last this many minutes (BRK-188's "Observe" rows). */
+/** How far back health looks first: errors and slowness in the last this many minutes (BRK-188's "Observe" rows). */
 export const HEALTH_WINDOW_MINUTES = 15;
 
 /**
- * The datasets health reads (BRK-188's "Observe" rows), one query each for the whole environment, over the last
- * HEALTH_WINDOW_MINUTES. Which fields each dataset serves at minute resolution is checked against a real account when
- * the owner first tries Architect (BRK-205); a dataset Cloudflare won't answer leaves its resources' health unknown.
- * @type {Record<string, Dataset>}
+ * How far behind now the health window ends (BRK-266): Cloudflare's analytics arrive a few minutes late, so the newest
+ * minutes are always empty and a window ending at now would see a busy resource fall quiet.
+ */
+export const HEALTH_LAG_MINUTES = 5;
+
+/**
+ * The windows health reads, shortest first (BRK-266): a resource with no traffic in one is read again over the next
+ * before it's called idle, and its verdict says which window it came from.
+ */
+export const HEALTH_WINDOWS = [HEALTH_WINDOW_MINUTES, 60, 24 * 60];
+
+/**
+ * The datasets health reads (BRK-188's "Observe" rows), one query each for the whole environment, over the first of
+ * HEALTH_WINDOWS, and again over the longer ones only for the resources it found quiet. `busy` says whether a
+ * resource's usage counts as traffic; a dataset without one (the queues' backlog) is read once. Which fields each
+ * dataset serves at minute resolution is checked against a real account when the owner first tries Architect
+ * (BRK-205); a dataset Cloudflare won't answer leaves its resources' health unread, saying which.
+ * @type {Record<string, Dataset & { busy?: (u: Record<string, number>) => boolean }>}
  */
 export const HEALTH_DATASETS = {
   workers: {
@@ -266,6 +280,7 @@ export const HEALTH_DATASETS = {
     time: 'datetime',
     sum: ['requests', 'errors'],
     label: 'requests and errors',
+    busy: (u) => (u.requests ?? 0) > 0,
   },
   durableObjects: {
     dataset: 'durableObjectsInvocationsAdaptiveGroups',
@@ -274,6 +289,7 @@ export const HEALTH_DATASETS = {
     time: 'datetime',
     sum: ['requests', 'errors'],
     label: 'requests and errors',
+    busy: (u) => (u.requests ?? 0) > 0,
   },
   d1: {
     dataset: 'd1AnalyticsAdaptiveGroups',
@@ -283,6 +299,7 @@ export const HEALTH_DATASETS = {
     sum: ['readQueries', 'writeQueries'],
     avg: ['queryBatchTimeMs'],
     label: 'queries and their time',
+    busy: (u) => (u.readQueries ?? 0) + (u.writeQueries ?? 0) > 0,
   },
   kv: {
     dataset: 'kvOperationsAdaptiveGroups',
@@ -291,6 +308,7 @@ export const HEALTH_DATASETS = {
     time: 'datetime',
     sum: ['requests'],
     label: 'operations',
+    busy: (u) => (u.requests ?? 0) > 0,
   },
   r2: {
     dataset: 'r2OperationsAdaptiveGroups',
@@ -300,6 +318,7 @@ export const HEALTH_DATASETS = {
     sum: ['requests'],
     by: 'responseStatusCode',
     label: 'operations by response status',
+    busy: (u) => Object.entries(u).some(([k, v]) => k.startsWith('requests:') && v > 0),
   },
   queues: {
     dataset: 'queuesBacklogAdaptiveGroups',

package/src/infra-cloudflare-plan.js

@@ -266,8 +266,13 @@ function bindingChange(worker, live, wanted, resolve) {
 export async function plan(ctx, desired) {
   const found = await discover(ctx, { live: true });
   const live = /** @type {LiveAccount} */ (found.live);
-  if (!live.account || !live.scripts.includes(String(ctx.scope?.target ?? '')))
-    refuse(`${ctx.scope?.target ?? 'the target'} isn’t a Worker on the account yet: deploy it first, then plan`);
+  const target = String(ctx.scope?.target ?? '');
+  // A target the desired state makes (a new environment built from the console, BRK-291) is planned like any Worker.
+  const makes = desired.resources.some((r) => r.kind === 'worker' && r.name === target);
+  if (!live.account || !(live.scripts.includes(target) || (target && makes)))
+    refuse(
+      `${ctx.scope?.target ?? 'the target'} isn’t a Worker on the account yet: deploy it first, or add it to the desired state, then plan`,
+    );
   if (ctx.scope?.board && ctx.scope.board === ctx.scope.target)
     refuse(
       `${ctx.scope.target} is the Worker this board runs on: Architect only observes it, so it never plans for it`,
@@ -600,6 +605,35 @@ function writer(ctx) {
   };
 }
 
+/** The module a new Worker starts with (BRK-270): it answers /health until the repository's deploy puts its code on it. */
+export const STARTER_MODULE = 'starter.js';
+export const STARTER_SCRIPT = `// Made by breakaway's Architect. The repository's deploy replaces it.
+export default {
+  fetch(request) {
+    if (new URL(request.url).pathname === '/health') return Response.json({ ok: true, starter: true });
+    return new Response('This Worker has no code yet: its deploy puts it here.', { status: 503 });
+  },
+};
+`;
+
+/**
+ * A new Worker's first upload: the starter module, with the change's settings and bindings. A Durable Object binding
+ * waits for the deploy, since its class is in the Worker's own code.
+ */
+function starterUpload(after, resolve) {
+  const { keep_bindings: _, ...settings } = workerSettings(after, [], resolve);
+  const metadata = {
+    ...settings,
+    main_module: STARTER_MODULE,
+    bindings: settings.bindings.filter((b) => b.type !== 'durable_object_namespace'),
+    compatibility_date: settings.compatibility_date ?? new Date().toISOString().slice(0, 10),
+  };
+  const form = new FormData();
+  form.append('metadata', new Blob([JSON.stringify(metadata)], { type: 'application/json' }));
+  form.append(STARTER_MODULE, new Blob([STARTER_SCRIPT], { type: 'application/javascript+module' }), STARTER_MODULE);
+  return form;
+}
+
 /** A Worker's settings, as `PATCH …/settings` takes them, from a change's `after` and its live bindings. */
 function workerSettings(after, live, resolve) {
   const byName = new Map(live.map((b) => [b.name, b]));
@@ -689,8 +723,9 @@ async function applyChange(c, { call, a, live, have, made, resolve }) {
       const perm = { permission: WORKERS_WRITE.edit };
       if (c.op === 'delete') return call('DELETE', p, { permission: WORKERS_WRITE.delete });
       if (c.op === 'create') {
-        // The Worker alone: its first version, with its code, comes from its deploy.
+        // The Worker, then a starter version that answers /health, with its settings: its deploy replaces the code.
         await call('POST', `${a}/workers/workers`, { permission: WORKERS_WRITE.create, json: { name: c.name } });
+        await call('PUT', p, { permission: WORKERS_WRITE.create, form: starterUpload(after, resolve) });
         if (Array.isArray(after.crons) && after.crons.length)
           await call('PUT', `${p}/schedules`, { ...perm, json: after.crons.map((cron) => ({ cron })) });
         return;

package/src/infra-cloudflare-tokens.js

@@ -0,0 +1,133 @@
+/**
+ * Cloudflare's tokens for guided setup (BRK-304; docs/specs/IDEA-19-architect.md, "Tokens"): which permissions each
+ * environment's write token needs, from the kinds its desired state declares, and the link that opens Cloudflare's
+ * create-token page with as many of them filled in as Cloudflare allows. Pure: no store, no network, and it runs in
+ * Node as well as the Worker. The board never makes, sees, or keeps a write token: it only says what to make.
+ *
+ * Cloudflare's template URLs ("API token template URLs", developers.cloudflare.com/fundamentals/api/how-to/
+ * account-owned-token-template/, read 8 Oct 2026) prefill an account API token's permissions by key, but only the
+ * keys that page lists. Workers roles (Metadata Read-Only, Editor, Admin; BRK-243), Containers, and Notifications have
+ * no listed key, and the legacy `workers_scripts` key would give Content Read-Only (code) or Editor on every Worker, so
+ * those are never prefilled: the setup names them to add by hand.
+ */
+import { READ_PERMISSIONS, WORKERS_READ } from './infra-cloudflare.js';
+
+/** The secret the apply workflow reads the write token from, in each environment's GitHub environment. */
+export const WRITE_SECRET = 'CLOUDFLARE_API_TOKEN';
+
+/** Where an account API token is made, with `permissionGroupKeys` and `name` added (the account is picked there). */
+export const TEMPLATE_BASE = 'https://dash.cloudflare.com/?to=/:account/api-tokens';
+
+/** The permissions a template URL can prefill, by the name the token page gives them. */
+export const TEMPLATE_KEYS = {
+  'Workers KV Storage Read': { key: 'workers_kv_storage', type: 'read' },
+  'Workers KV Storage Write': { key: 'workers_kv_storage', type: 'edit' },
+  'Workers R2 Storage Read': { key: 'workers_r2', type: 'read' },
+  'Workers R2 Storage Write': { key: 'workers_r2', type: 'edit' },
+  'D1 Read': { key: 'd1', type: 'read' },
+  'D1 Write': { key: 'd1', type: 'edit' },
+  'Queues Read': { key: 'queues', type: 'read' },
+  'Queues Write': { key: 'queues', type: 'edit' },
+  'Account Analytics Read': { key: 'account_analytics', type: 'read' },
+  'Zone Read': { key: 'zone', type: 'read' },
+  'Workers Routes Read': { key: 'workers_routes', type: 'read' },
+  'Workers Routes Write': { key: 'workers_routes', type: 'edit' },
+};
+
+/** The permissions that are given on zones, not the account: only the zones the environments use. */
+const ZONE = new Set(['Zone Read', 'Workers Routes Read', 'Workers Routes Write']);
+
+/**
+ * One permission a token needs, where it's given, and why.
+ * @typedef {object} SetupPermission
+ * @property {string} name as Cloudflare's token page names it
+ * @property {string} scope where it's given: `account`, `zones`, `workers` (only the Workers named in `workers`), or
+ *   `workers-product` (every Worker on the account)
+ * @property {string} for what it's for, in a few words
+ * @property {string[]} [legacy] older names for the same access
+ * @property {string[]} [workers] with scope `workers`, the Workers to choose
+ * @property {boolean} [once] only for the first apply that makes a Worker: give it, then take it away
+ */
+
+/** The board's read token, with where each permission is given. */
+export const readPermissions = () =>
+  READ_PERMISSIONS.map(
+    (p) =>
+      /** @type {SetupPermission} */ ({
+        ...p,
+        scope: p.name === WORKERS_READ ? 'workers-product' : ZONE.has(p.name) ? 'zones' : 'account',
+      }),
+  );
+
+/** The Write permission each kind needs beyond Workers Editor, and what it's for. */
+const KIND_WRITES = [
+  { kinds: ['route', 'custom-domain'], name: 'Workers Routes Write', for: 'routes and custom domains, on their zones' },
+  { kinds: ['d1'], name: 'D1 Write', for: 'D1 databases' },
+  { kinds: ['kv'], name: 'Workers KV Storage Write', for: 'KV namespaces' },
+  { kinds: ['r2'], name: 'Workers R2 Storage Write', for: 'R2 buckets' },
+  { kinds: ['queue'], name: 'Queues Write', for: 'queues' },
+  { kinds: ['container'], name: 'Containers Write', for: 'container applications' },
+];
+
+/**
+ * What one environment's write token needs: the read token's permissions (apply discovers again with it), Workers
+ * Editor on its Workers (on the Workers product when it declares custom domains, which have no per-Worker role yet),
+ * and only the Write permissions for the kinds it declares. A Worker the desired state names that doesn't run yet
+ * needs Workers Admin for the apply that makes it, never as part of the standing token.
+ * @param {{ resources?: Array<{ kind: string, name: string }> } | null} desired the environment's desired state, null
+ *   when it has none yet
+ * @param {{ running?: string[] }} [options] the Workers that already run in the environment, by name
+ * @returns {SetupPermission[]}
+ */
+export function writePermissions(desired, { running = [] } = {}) {
+  const resources = desired?.resources ?? [];
+  const kinds = new Set(resources.map((r) => r.kind));
+  const workers = [...new Set(resources.filter((r) => r.kind === 'worker').map((r) => r.name))].sort();
+  const domains = kinds.has('custom-domain');
+  /** @type {SetupPermission[]} */
+  const out = readPermissions();
+  out.push({
+    name: 'Workers Editor',
+    legacy: ['Workers Scripts Write'],
+    scope: domains || !workers.length ? 'workers-product' : 'workers',
+    ...(domains || !workers.length ? {} : { workers }),
+    for: domains
+      ? 'changing its Workers and their custom domains (custom domains have no per-Worker role yet)'
+      : 'changing its Workers and their Durable Objects',
+  });
+  for (const w of KIND_WRITES)
+    if (w.kinds.some((k) => kinds.has(k)))
+      out.push({ name: w.name, scope: ZONE.has(w.name) ? 'zones' : 'account', for: w.for });
+  const have = new Set(running);
+  const missing = workers.filter((w) => !have.has(w));
+  if (missing.length)
+    out.push({
+      name: 'Workers Admin',
+      scope: 'workers-product',
+      once: true,
+      for: `making ${missing.join(', ')}, which ${missing.length === 1 ? 'doesn’t' : 'don’t'} run yet: give it for the first apply, then take it away`,
+    });
+  return out;
+}
+
+/**
+ * The link that opens Cloudflare's create-token page for an account API token with every permission it can prefill,
+ * and the ones to add by hand. Workers Editor scoped to chosen Workers, and Workers Admin, are always by hand.
+ * @param {Array<{ name: string }>} permissions
+ * @param {string} name the token's name, prefilled
+ * @returns {{ url: string, prefilled: string[], byHand: string[] }}
+ */
+export function tokenTemplate(permissions, name) {
+  const keys = [];
+  const prefilled = [];
+  const byHand = [];
+  for (const p of permissions) {
+    const key = TEMPLATE_KEYS[/** @type {keyof typeof TEMPLATE_KEYS} */ (p.name)];
+    if (key) {
+      keys.push(key);
+      prefilled.push(p.name);
+    } else byHand.push(p.name);
+  }
+  const query = `permissionGroupKeys=${encodeURIComponent(JSON.stringify(keys))}&name=${encodeURIComponent(name)}`;
+  return { url: `${TEMPLATE_BASE}&${query}`, prefilled, byHand };
+}