breakaway 2.0.0-main.98 → 2.0.0

package/src/infra-provider.js

@@ -15,8 +15,12 @@ export const CHANGE_KINDS = ['create', 'update', 'delete', 'scale', 'restart'];
 export const BASE_CHANGES = ['create', 'update', 'delete'];
 /** The change kinds a provider may add per resource kind, for envelopes. */
 export const ENVELOPE_CHANGES = ['scale', 'restart'];
-/** A resource's health, from `observe`. */
-export const HEALTH_STATES = ['healthy', 'degraded', 'down', 'unknown'];
+/**
+ * A resource's health, from `observe`. `idle` is deployed and reachable with no traffic and no errors seen (BRK-266):
+ * it counts as healthy, never as unknown. `unknown` is only for what the provider couldn't read, and its text says
+ * which call and what to do.
+ */
+export const HEALTH_STATES = ['healthy', 'idle', 'degraded', 'down', 'unknown'];
 /** What a signal is about: health, the platform's alerts, and cost (BRK-172: no metrics, logs, or traces yet). */
 export const SIGNAL_KINDS = ['health', 'alert', 'cost'];
 /** How loud a signal is. */
@@ -61,6 +65,7 @@ export const COST_NOTE_MAX = 500;
  * What should exist in one environment, from its desired-state file (BRK-180).
  * @typedef {object} DesiredState
  * @property {Resource[]} resources
+ * @property {{ url: string }} [health] the owner's health URL, checked on each refresh (BRK-266); providers ignore it
  */
 
 /**
@@ -162,6 +167,8 @@ export const COST_NOTE_MAX = 500;
  *   Without it, every attr is a setting.
  * @property {string} [scales] the whole-number setting a `scale` changes (like `instances`): required when the kind
  *   declares `scale`, so an envelope (BRK-186) knows what its bounds are bounds of
+ * @property {boolean} [target] one of the kind can be an environment's target, what discovery starts from (a Worker):
+ *   a change that adds one to an environment with no target gives it that target (BRK-291)
  */
 
 /**
@@ -191,6 +198,23 @@ export const COST_NOTE_MAX = 500;
  * @property {string} url where the owner makes one, on the platform
  * @property {(ctx: { token: string, fetch?: typeof fetch }) => Promise<TokenCheck>} [check] asks the platform about
  *   a pasted token before the board keeps it
+ * @property {(permissions: TokenPermission[], name: string) => TokenTemplate} [template] the link that opens the
+ *   platform's create-token page with what it can prefill (BRK-304)
+ */
+
+/**
+ * A link to the platform's create-token page with some permissions filled in, and the ones to add by hand.
+ * @typedef {{ url: string, prefilled: string[], byHand: string[] }} TokenTemplate
+ */
+
+/**
+ * Each environment's write token (BRK-304), which the board never holds: guided setup says what to make and where to
+ * put it, and checks the GitHub environment has a secret by that name. Never a token's value.
+ * @typedef {object} WriteToken
+ * @property {string} secret the secret the apply workflow reads it from, in the GitHub environment
+ * @property {(desired: DesiredState | null, options: { running: string[] }) => Array<TokenPermission & { scope: string, workers?: string[], once?: boolean }>} permissions
+ *   what one environment's token needs, from its desired state and the targets that already run there
+ * @property {(permissions: TokenPermission[], name: string) => TokenTemplate} [template] the prefilled link
  */
 
 /**
@@ -207,6 +231,7 @@ export const COST_NOTE_MAX = 500;
  *   Worker, `scope.board`, or another environment's target, `scope.others`), in words, or null when it is; an act asks
  *   it before it plans (BRK-251)
  * @property {ReadToken} [readToken] the read-only token it needs, if any
+ * @property {WriteToken} [writeToken] what each environment's write token needs, for guided setup (BRK-304)
  * @property {(ctx: ProviderContext) => Promise<Discovery>} discover
  * @property {(ctx: ProviderContext, desired: DesiredState) => Promise<PlanDiff>} plan
  * @property {(ctx: ProviderContext, plan: PlanDiff) => Promise<ApplyResult>} apply
@@ -217,6 +242,8 @@ export const COST_NOTE_MAX = 500;
  *   month once `change` is applied, or null when the provider can't say; a plan's cost change uses it (BRK-178)
  * @property {(kind: string) => Editable | null} [editable] the settings the console may change on resources of `kind`,
  *   or null for a kind it changes nothing on; checked by `checkEditable` (BRK-262)
+ * @property {(kind: string) => Creatable | null} [creatable] whether the console may add a resource of `kind`, its
+ *   name's rule, and what a new one is given, or null for a kind it can't add; checked by `checkCreatable` (BRK-270)
  * @property {(ctx: ProviderContext, options: { board: string[] }) => Promise<AlertSetup>} [alerts] reads which of the
  *   platform's alerts are set up and which reach the board (`board` is its https origins), for a provider whose
  *   platform sends alerts to the board
@@ -251,13 +278,17 @@ const PATH = /^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)*$/u;
  * @property {string[]} [kinds] the kinds a `resource` may name
  * @property {BindingTarget[]} [targets] the binding types a `bindings` field changes: a binding of any other type (a
  *   variable, a secret) is shown by its name and type, and kept as it is
+ * @property {Record<string, string>} [typeLabels] a `bindings` field's words for binding types its `targets` don't
+ *   list (a Durable Object, static assets), so a change reads '+ CHAT (Durable Object)' (WEB-110)
  * @property {EditableField[]} [fields] a `rules` field's fields, inside one rule
  * @property {Record<string, unknown>} [template] what a new rule starts from
  */
 
 /**
  * One type of binding a `bindings` field changes, and how it names its resource: a binding is `{ name, type, [field]: … }`,
- * with the resource's ID in the desired state (`by: 'id'`) or its name (`by: 'name'`).
+ * the field the provider's plan compares with what runs (BRK-285), holding the resource's ID on the platform (`by:
+ * 'id'`, its inventory ID after `<kind>:`) or its name (`by: 'name'`). One the plan still makes has no platform ID yet,
+ * so a `by: 'id'` binding names it by its ID in the desired state, as `{ name, type, resource }`.
  * @typedef {object} BindingTarget
  * @property {string} type the binding's type, as the platform calls it
  * @property {string} label what people call it
@@ -283,6 +314,39 @@ const PATH = /^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)*$/u;
  * @property {ShownSetting[]} [shown] settings shown by name, read only
  */
 
+/**
+ * A resource kind the console may add (BRK-270), from the provider's `creatable(kind)`. A new one is the kind's
+ * editable fields (BRK-262) and `fields`, with `defaults` filled in and `required` given; a `create` edit
+ * (src/infra-changes.js) checks them, and the plan says what it makes.
+ * @typedef {object} Creatable
+ * @property {string} label what one is called, like `Queue`
+ * @property {string} help one line on what it's for, in plain words
+ * @property {{ label: string, help: string, pattern?: string, max?: number }} name its name's rule: a regular
+ *   expression and a length, and help saying them. A name is unique among the kind in the environment's file and what
+ *   runs there; the plan checks the rest of the platform's account.
+ * @property {EditableField[]} [fields] what only a new one is given (like a route's zone), beyond its editable fields:
+ *   the plan reads them when it makes it, and never compares them
+ * @property {string[]} [required] the paths, of `fields` or the editable fields, a new one must be given
+ * @property {Record<string, unknown>} [defaults] what a new one starts with, by path
+ * @property {{ kind: string, list: string, target: BindingTarget, required?: boolean }} [bind] how a resource of another
+ *   kind (`kind`, like a Worker) binds a new one: a binding in its `list` setting, as `target` says; `required` when the
+ *   plan makes one only if something binds it, so a `create` edit must bind it. None for a kind nothing binds.
+ * @property {string} [needsCode] what code must exist before the plan can make one (a class, an image), in words: the
+ *   console adds it to the file, and the plan waits until the code's deploy has made it
+ */
+
+/**
+ * A kind the console may add, as the board answers it (BRK-270): one list of fields, the kind's editable ones after
+ * its own, each marked `required` or carrying its `default`.
+ * @typedef {object} CreatableKind
+ * @property {string} label
+ * @property {string} help
+ * @property {{ label: string, help: string, pattern?: string, max?: number }} name
+ * @property {Array<EditableField & { required?: boolean, default?: unknown }>} fields
+ * @property {{ kind: string, list: string, target: BindingTarget, required?: boolean }} [bind]
+ * @property {string} [needsCode]
+ */
+
 /**
  * Which of a platform's alerts are set up, and which reach the board: each alert type with how many policies use it
  * and whether one sends to the board, each policy (on or off, the routines on the board it fires), and how many
@@ -330,8 +394,11 @@ export function checkProvider(provider) {
       fail(what, `${kind}'s settings is not a list of settings' names`);
     if (spec.changes.includes('scale') ? !text(spec.scales) : spec.scales !== undefined)
       fail(what, `${kind}'s scales names the setting a scale changes, and only a kind that scales has one`);
+    if (spec.target !== undefined && typeof spec.target !== 'boolean')
+      fail(what, `${kind}'s target is not true or false`);
   }
   if (provider.readToken !== undefined) checkReadToken(what, provider.readToken);
+  if (provider.writeToken !== undefined) checkWriteToken(what, provider.writeToken);
   if (provider.refuses !== undefined && typeof provider.refuses !== 'function') fail(what, 'refuses is not a function');
   if (provider.outside !== undefined && typeof provider.outside !== 'function') fail(what, 'outside is not a function');
   if (provider.estimate !== undefined && typeof provider.estimate !== 'function')
@@ -340,6 +407,10 @@ export function checkProvider(provider) {
     if (typeof provider.editable !== 'function') fail(what, 'editable is not a function');
     for (const kind of Object.keys(provider.kinds)) checkEditable(provider, kind, provider.editable(kind));
   }
+  if (provider.creatable !== undefined) {
+    if (typeof provider.creatable !== 'function') fail(what, 'creatable is not a function');
+    for (const kind of Object.keys(provider.kinds)) checkCreatable(provider, kind, provider.creatable(kind));
+  }
   return provider;
 }
 
@@ -467,6 +538,137 @@ export function editableKinds(provider) {
   return out;
 }
 
+/**
+ * What's wrong with a value for one of the console's fields (BRK-262's types), in words, or null when it fits. A
+ * `resource` field's value is a name: whether the environment has it is the caller's to check.
+ * @param {EditableField} field
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+export function fieldProblem(field, value) {
+  const label = field.label;
+  const fits = (pattern, v) => !pattern || new RegExp(pattern, 'u').test(v);
+  switch (field.type) {
+    case 'number': {
+      if (typeof value !== 'number' || !Number.isFinite(value)) return `${label} is a number`;
+      if (field.integer && !Number.isInteger(value)) return `${label} is a whole number`;
+      const unit = field.unit ? ` ${field.unit}` : '';
+      if (field.min !== undefined && value < field.min) return `${label} is at least ${field.min}${unit}`;
+      if (field.max !== undefined && value > field.max) return `${label} is at most ${field.max}${unit}`;
+      return null;
+    }
+    case 'yesno':
+      return typeof value === 'boolean' ? null : `${label} is yes or no (true or false)`;
+    case 'choice':
+      return field.options?.some((o) => o.value === value)
+        ? null
+        : `${label} is one of ${(field.options ?? []).map((o) => o.value).join(', ')}`;
+    case 'text':
+    case 'resource':
+      if (typeof value !== 'string' || !value.trim()) return `${label} is text`;
+      return fits(field.pattern, value) ? null : `${value} doesn’t fit ${label}: ${field.help}`;
+    case 'names':
+      if (!Array.isArray(value) || !value.every((v) => typeof v === 'string')) return `${label} is a list of names`;
+      for (const v of value) if (!fits(field.pattern, v)) return `${v} doesn’t fit ${label}: ${field.help}`;
+      return null;
+    default:
+      return Array.isArray(value) ? null : `${label} is a list`;
+  }
+}
+
+/**
+ * Checks what a provider's `creatable(kind)` returned, or throws saying what's wrong: a label, help, and a name's rule;
+ * its own fields are well formed and none is also editable; what's required or defaulted is one of the fields; each
+ * default fits its field; and a binding names a kind the provider declares, binding this one.
+ * @param {Provider} provider
+ * @param {string} kind
+ * @param {Creatable | null} creatable
+ * @returns {Creatable | null}
+ */
+export function checkCreatable(provider, kind, creatable) {
+  const what = `${provider.id} creatable ${kind}`;
+  if (creatable === null) return null;
+  if (!provider.kinds[kind]) fail(what, `${provider.id} doesn't declare ${kind}`);
+  if (!isObject(creatable) || !text(creatable.label) || !text(creatable.help)) fail(what, 'has no label or no help');
+  const name = creatable.name;
+  if (!isObject(name) || !text(name.label) || !text(name.help)) fail(what, 'name has no label or no help');
+  if (name.pattern !== undefined) checkPattern(what, 'name', name.pattern);
+  if (name.max !== undefined && (!Number.isInteger(name.max) || name.max < 1))
+    fail(what, 'name’s max is not a whole number of characters');
+  const own = creatable.fields ?? [];
+  checkFields(provider, what, own, undefined);
+  const editable = typeof provider.editable === 'function' ? (provider.editable(kind)?.fields ?? []) : [];
+  for (const f of own) if (editable.some((e) => e.path === f.path)) fail(`${what} ${f.path}`, 'is editable already');
+  const byPath = new Map([...own, ...editable].map((f) => [f.path, f]));
+  if (creatable.required !== undefined) {
+    if (!Array.isArray(creatable.required)) fail(what, 'required is not a list');
+    for (const p of creatable.required) if (!byPath.has(p)) fail(what, `requires ${p}, which isn't one of its fields`);
+  }
+  if (creatable.defaults !== undefined) {
+    if (!isObject(creatable.defaults)) fail(what, 'defaults is not an object');
+    for (const [p, v] of Object.entries(creatable.defaults)) {
+      const f = byPath.get(p);
+      if (!f) fail(what, `has a default for ${p}, which isn't one of its fields`);
+      const problem = fieldProblem(/** @type {EditableField} */ (f), v);
+      if (problem) fail(`${what} default ${p}`, problem);
+    }
+  }
+  if (creatable.bind !== undefined) {
+    const b = creatable.bind;
+    if (!isObject(b) || !provider.kinds[b.kind]) fail(what, 'bind names no kind the provider declares');
+    if (!text(b.list) || !PATH.test(b.list)) fail(what, 'bind names no list');
+    const t = b.target;
+    if (!isObject(t) || !text(t.type) || !text(t.label) || !text(t.field))
+      fail(what, 'bind’s target has no type, label, or field');
+    if (t.kind !== kind) fail(what, `bind’s target binds ${t.kind}, not ${kind}`);
+    if (t.by !== 'id' && t.by !== 'name') fail(what, 'bind’s target names its resource by neither id nor name');
+    if (b.required !== undefined && typeof b.required !== 'boolean') fail(what, 'bind’s required is not true or false');
+  }
+  if (creatable.needsCode !== undefined && !text(creatable.needsCode)) fail(what, 'needsCode is empty');
+  return creatable;
+}
+
+/**
+ * The kinds one of which can be an environment's target (BRK-291): the provider's kinds marked `target`.
+ * @param {Provider} provider
+ * @returns {string[]}
+ */
+export const targetKinds = (provider) =>
+  Object.entries(provider.kinds)
+    .filter(([, spec]) => spec.target === true)
+    .map(([kind]) => kind);
+
+/**
+ * The kinds the console may add (BRK-270), checked, each with one list of fields: its own, then its editable ones,
+ * marked `required` or carrying their `default`. A provider without `creatable` adds nothing from the console.
+ * @param {Provider} provider
+ * @returns {Record<string, CreatableKind>}
+ */
+export function creatableKinds(provider) {
+  if (typeof provider.creatable !== 'function') return {};
+  /** @type {Record<string, CreatableKind>} */
+  const out = {};
+  for (const kind of Object.keys(provider.kinds)) {
+    const c = checkCreatable(provider, kind, provider.creatable(kind));
+    if (!c) continue;
+    const editable = typeof provider.editable === 'function' ? (provider.editable(kind)?.fields ?? []) : [];
+    const fields = [...(c.fields ?? []), ...editable].map((f) => ({
+      ...f,
+      ...(c.required?.includes(f.path) ? { required: true } : {}),
+      ...(c.defaults && Object.hasOwn(c.defaults, f.path) ? { default: structuredClone(c.defaults[f.path]) } : {}),
+    }));
+    out[kind] = {
+      label: c.label,
+      help: c.help,
+      name: { ...c.name },
+      fields,
+      ...(c.bind ? { bind: structuredClone(c.bind) } : {}),
+      ...(c.needsCode ? { needsCode: c.needsCode } : {}),
+    };
+  }
+  return out;
+}
+
 /** @param {string} what @param {ReadToken} token */
 function checkReadToken(what, token) {
   if (!isObject(token)) fail(what, 'readToken is not an object');
@@ -478,6 +680,18 @@ function checkReadToken(what, token) {
   }
   if (typeof token.url !== 'string' || !token.url.startsWith('https://')) fail(what, 'readToken has no https url');
   if (token.check !== undefined && typeof token.check !== 'function') fail(what, 'readToken check is not a function');
+  if (token.template !== undefined && typeof token.template !== 'function')
+    fail(what, 'readToken template is not a function');
+}
+
+/** What guided setup needs of a provider's write token (BRK-304): a secret's name and the permissions, from a function. */
+function checkWriteToken(what, token) {
+  if (!isObject(token)) fail(what, 'writeToken is not an object');
+  if (!text(token.secret) || !/^[A-Z][A-Z0-9_]{0,63}$/u.test(token.secret))
+    fail(what, 'writeToken secret is not a GitHub secret’s name');
+  if (typeof token.permissions !== 'function') fail(what, 'writeToken permissions is not a function');
+  if (token.template !== undefined && typeof token.template !== 'function')
+    fail(what, 'writeToken template is not a function');
 }
 
 /**

package/src/infra-runner-render.js

@@ -0,0 +1,172 @@
+/**
+ * The apply workflow, rendered (CLI-12, BRK-307; docs/specs/IDEA-19-architect.md, "Executor"):
+ * `.github/workflows/breakaway-infra.yml` from template/infra/apply.yml, for every environment with a desired-state
+ * file. `npx breakaway infra init` writes it in a checkout, and the board's change brings it in the same commit as the
+ * desired state (store-infra-changes.js), so both render byte-identical files from the same template: the CLI reads
+ * it from disk, the Worker from src/infra-runner-template.json, which scripts/board-files.mjs generates from it.
+ *
+ * Pure and Node-safe: no store, no network, no disk.
+ */
+import { DESIRED_DIR, environmentOfFile } from './infra-desired.js';
+import { RUNNER_WORKFLOW } from './infra-runner.js';
+import { SHORT_LIVED_FILE } from './infra-short-lived.js';
+import { fill, lintWorkflow } from './workflow-render.js';
+
+/** Where the template is, in breakaway's own files. */
+export const RUNNER_TEMPLATE = 'template/infra/apply.yml';
+
+/** The first line of the rendered workflow: how `--update`, and the board, know the file is theirs to replace. */
+export const RUNNER_RENDER_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.`;
+
+/** What the change card and the plan check say when the board couldn't bring the workflow itself. */
+export const RUNNER_NEEDS_WORKFLOWS = `Applying needs ${RUNNER_WORKFLOW}: give the board’s GitHub App Workflows: write and propose again, or run npx breakaway infra init in the repository and merge it.`;
+
+/** The same, for a pull request the board didn't write, where proposing again isn't the way. */
+export const RUNNER_NEEDS_INIT = `Applying needs ${RUNNER_WORKFLOW}: run npx breakaway infra init in the repository and merge it.`;
+
+const BRANCH = /^(?!.*\.\.)[A-Za-z0-9._/-]{1,100}$/u;
+const VERSION = /^\d+\.\d+\.\d+(?:-[\w.]+)?$/u;
+
+/** A reason the workflow can't be rendered, in words for the owner or the agent. */
+export class RunnerRenderError extends Error {}
+const bad = (message) => {
+  throw new RunnerRenderError(message);
+};
+
+/**
+ * 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 = new Set();
+  for (const name of names) {
+    const found = environmentOfFile(name);
+    if (!found) continue;
+    if ('problem' in found) throw new RunnerRenderError(`${DESIRED_DIR}/${found.problem}.`);
+    environments.add(found.environment);
+  }
+  if (!environments.size)
+    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 (!VERSION.test(version)) bad(`${version} isn't a breakaway release.`);
+  const text = fill(template, {
+    header: RUNNER_RENDER_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 };
+}
+
+/** Whether a workflow's text is the board's own render, which `--update` and the board may replace. */
+export const isRenderedRunner = (text) => String(text ?? '').startsWith(`# ${RUNNER_RENDER_HEADER}`);
+
+/**
+ * What to do 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 runnerStep(file, there, { update = false } = {}) {
+  if (there === null) return { write: true };
+  if (there === file.text) return { write: false, same: true };
+  if (!isRenderedRunner(there))
+    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 };
+}
+
+/**
+ * What a change does with the apply workflow (BRK-307): the environments come from the desired-state folder's file
+ * names on the default branch plus the environment the change writes, and the workflow is rendered for them.
+ * - `add`: there's none; `update`: it's the board's own render and differs (an environment, the branch, or the
+ *   release); the change commits `file` either way.
+ * - `current`: it's already what the board renders.
+ * - `own`: it's the repository's own, which the board never overwrites; `missing` names the environments it doesn't
+ *   offer, as far as the board can tell.
+ * @param {{ names: string[], environment: string, there: string | null, branch: string, version: string,
+ *   template: string }} input
+ * @returns {{ action: 'add' | 'update' | 'current' | 'own', file: { path: string, text: string },
+ *   environments: string[], missing: string[] }}
+ */
+export function runnerChange({ names, environment, there, branch, version, template }) {
+  const environments = environmentsIn([...names, `${environment}.json`]);
+  const shortLived = names.includes(SHORT_LIVED_FILE);
+  const file = renderRunner({ environments, branch, version, shortLived }, template);
+  const out = { file, environments, missing: [] };
+  if (there === null) return { ...out, action: 'add' };
+  if (there === file.text) return { ...out, action: 'current' };
+  if (isRenderedRunner(there)) return { ...out, action: 'update' };
+  return { ...out, action: 'own', missing: runnerMissing(there, environments) };
+}
+
+/**
+ * The environments a workflow doesn't offer: none when it takes any environment's name (an input of type string, as
+ * the render does with short-lived environments, or a repository's own that the board can't read), else the ones not
+ * among its environment input's choices.
+ * @param {string} text
+ * @param {string[]} environments
+ * @returns {string[]}
+ */
+export function runnerMissing(text, environments) {
+  const options = /\n {6}environment:\n(?: {8}.*\n)*? {8}options:\n((?: {10}- .*\n?)+)/u.exec(String(text ?? ''));
+  if (!options) return [];
+  const offered = new Set(
+    options[1]
+      .split('\n')
+      .map((line) => line.replace(/^\s*-\s*/u, '').trim())
+      .filter(Boolean)
+      .map((value) => {
+        try {
+          return String(JSON.parse(value));
+        } catch {
+          return value.replace(/^['"]|['"]$/gu, '');
+        }
+      }),
+  );
+  return environments.filter((name) => !offered.has(name));
+}
+
+/** The words for an apply workflow the board left alone because it's the repository's own. */
+export function runnerOwnWords(missing) {
+  if (!missing.length) return null;
+  return `${RUNNER_WORKFLOW} is the repository’s own, and it doesn’t offer ${missing.join(', ')}: add ${missing.length === 1 ? 'it' : 'them'} to its environment choices, or rename it and run npx breakaway infra init, then merge it.`;
+}
+
+/**
+ * What a pull request's plan check says about the apply workflow (BRK-307), given the workflow at its head (null when
+ * there's none) and the environments it plans: null when the workflow offers them all, else what to do before
+ * Approve. A waiting note, never a failure.
+ * @param {string | null} there
+ * @param {string[]} environments
+ * @returns {string | null}
+ */
+export function runnerNote(there, environments) {
+  if (!environments.length) return null;
+  if (there === null) return RUNNER_NEEDS_INIT;
+  const missing = runnerMissing(there, environments);
+  if (!missing.length) return null;
+  if (!isRenderedRunner(there)) return runnerOwnWords(missing);
+  return `${RUNNER_WORKFLOW} doesn’t offer ${missing.join(', ')} yet: run npx breakaway infra init --update in the repository and merge it.`;
+}

package/src/init.js

@@ -19,7 +19,7 @@ export { routinePrompt };
  * The CLI on npm (BRK-7), as a repository runs it: `npx breakaway`, pinned to the major (BRK-47), so a breaking change
  * never reaches a repository by itself. It was the `next` channel until the first stable release.
  */
-export const CLI_PACKAGE = 'breakaway@1';
+export const CLI_PACKAGE = 'breakaway@2';
 /**
  * Where the CLI starts: the command, and the two session hooks. repos init no longer copies them (BRK-7): an old copy
  * is replaced by npx, and these still version the CLI and say which files an old copy holds.