breakaway 2.0.0-main.60 → 2.0.0-main.62

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "breakaway",
-  "version": "2.0.0-main.60",
+  "version": "2.0.0-main.62",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "breakaway",
-      "version": "2.0.0-main.60",
+      "version": "2.0.0-main.62",
       "license": "FSL-1.1-Apache-2.0",
       "bin": {
         "breakaway": "scripts/tasks.mjs"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakaway",
-  "version": "2.0.0-main.60",
+  "version": "2.0.0-main.62",
   "description": "The task board for you and your coding agents: a Cloudflare Worker, its web app, Taskwarrior sync, and the CLI (npx breakaway).",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",
@@ -24,6 +24,7 @@
     "src/infra-check.js",
     "src/infra-currency.js",
     "src/infra-desired.js",
+    "src/infra-environments.js",
     "src/infra-inventory.js",
     "src/infra-cloudflare.js",
     "src/infra-cloudflare-analytics.js",

package/scripts/tasks/cli.js

@@ -29,7 +29,7 @@ export const SUBCOMMANDS = {
     'listen',
   ],
   specs: ['list', 'show'],
-  infra: ['init', 'runner', 'check', 'act', ...INFRA_READS],
+  infra: ['init', 'runner', 'check', 'adopt', 'act', ...INFRA_READS],
 };
 
 /** Commands that take nothing after their name, so a word there is a mistake (an old copy's missing subcommand, say). */

package/scripts/tasks/infra-adopt.js

@@ -0,0 +1,115 @@
+/**
+ * `npx breakaway infra adopt <environment>` (CLI-23, docs/specs/IDEA-19-architect.md, "Desired state"): writes the
+ * board's draft of an environment's desired state into the checkout, so nobody hand-writes
+ * `.github/breakaway-infra/<environment>.json`. The board drafts it from what runs there (BRK-240,
+ * GET /api/infra/environments/<environment>/draft, read only, so an agent's token may ask); this writes it where it
+ * goes, then checks it the way `infra check` does and says what to commit.
+ *
+ * Files only: it never makes a plan and never applies anything. It never overwrites a file without --force, and it
+ * writes nothing for an observe-only environment, which takes no desired state. The path is worked out here from the
+ * environment's name, never taken from the board's answer, so the file can't land anywhere else.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { checkDesiredFile, desiredPath, environmentOfFile } from '../../src/infra-desired.js';
+import { infraCheck, readInfraFolder } from './infra-check.js';
+
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+/**
+ * Runs `infra adopt`. `code` is what the CLI exits with: 1 when nothing was written, or the written file doesn't check.
+ * @param {string[]} args what follows `infra adopt`: the environment's name (or ID)
+ * @param {{ root: string, repo: string | null, force?: boolean, dryRun?: boolean,
+ *   get: (path: string) => Promise<{ ok: boolean, status: number, data: any }>,
+ *   post: (path: string, body: any) => Promise<{ ok: boolean, status: number, data: any }> }} ctx
+ * @returns {Promise<{ code: number, data: any, text: string }>}
+ */
+export async function infraAdopt(args, { root, repo, get, post, force = false, dryRun = false }) {
+  const refused = (error, text = `${error}.`) => ({ code: 1, data: { ok: false, written: false, error }, text });
+  const ref = args[0];
+  if (!ref)
+    return refused(
+      'name the environment',
+      'Name the environment: infra adopt <environment>. npx breakaway infra lists this repository’s.',
+    );
+
+  const res = await get(
+    `infra/environments/${encodeURIComponent(ref)}/draft${repo ? `?repo=${encodeURIComponent(repo)}` : ''}`,
+  );
+  if (!res.ok) {
+    if (res.status === 404 && /^no route for/u.test(String(res.data?.error ?? '')))
+      return refused(
+        'this board has no draft yet',
+        'This board can’t draft a desired state yet: its owner updates it to a release that can, then try again.',
+      );
+    const error = res.status === 0 ? `can’t reach the board (${res.data?.error ?? 'no answer'})` : res.data?.error;
+    return refused(error ?? `HTTP ${res.status}`, `Nothing was written: ${error ?? `HTTP ${res.status}`}.`);
+  }
+
+  const draft = res.data?.draft;
+  const named = environmentOfFile(`${draft?.environment ?? ''}.json`);
+  if (!draft || typeof draft.json !== 'string' || !named || !('environment' in named))
+    return refused('the board’s draft isn’t one this CLI can read: update npx breakaway, then try again');
+  const environment = named.environment;
+  const path = desiredPath(environment);
+  const notes = Array.isArray(draft.notes) ? draft.notes.map(String) : [];
+  const data = { environment, path, resources: draft.resources ?? 0, observeOnly: Boolean(draft.observeOnly), notes };
+  const withNotes = (lines) => [...lines, ...(notes.length ? ['', ...notes.map((n) => `- ${n}`)] : [])];
+
+  if (draft.observeOnly)
+    return {
+      code: 1,
+      data: { ...data, ok: false, written: false, error: `${environment} is observe only` },
+      text: withNotes([
+        `Nothing was written: ${environment} is observe only, so it takes no desired state and the board never changes it.`,
+      ]).join('\n'),
+    };
+  // The board checks its draft before it answers, so this only fails when the two disagree: write nothing bad.
+  const checked = checkDesiredFile(draft.json, {});
+  if ('error' in checked)
+    return refused(
+      `the draft doesn’t check at ${checked.error.field ?? 'the top'}: ${checked.error.message}`,
+      `Nothing was written: the board’s draft for ${environment} doesn’t check here (${checked.error.field ?? 'the top'}: ${checked.error.message}). Update npx breakaway, then try again.`,
+    );
+
+  const file = join(root, path);
+  const exists = existsSync(file);
+  if (exists && !force)
+    return {
+      code: 1,
+      data: { ...data, ok: false, written: false, error: `${path} is already there` },
+      text: `Nothing was written: ${path} is already there. See the draft with --dry-run, or replace the file with --force.`,
+    };
+
+  if (dryRun)
+    return {
+      code: 0,
+      data: { ...data, ok: true, written: false, json: draft.json },
+      text: withNotes([
+        `Would ${exists ? 'replace' : 'write'} ${path}, ${plural(data.resources, 'resource')}:`,
+        '',
+        draft.json.trimEnd(),
+      ]).join('\n'),
+    };
+
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, draft.json);
+  const check = await infraCheck([environment], { files: readInfraFolder(root), repo, post });
+  const next =
+    check.code === 0
+      ? [
+          '',
+          `Next: commit ${path} and open a pull request. Nothing changes until it merges: then the board plans from it, and the plan waits for you.`,
+        ]
+      : ['', `Fix what’s above, then npx breakaway infra check ${environment} before you commit ${path}.`];
+  return {
+    code: check.code,
+    data: { ...data, ok: check.code === 0, written: true, replaced: exists, check: check.data },
+    text: [
+      ...withNotes([`${exists ? 'Replaced' : 'Wrote'} ${path}, ${plural(data.resources, 'resource')}.`]),
+      '',
+      check.text,
+      ...next,
+    ].join('\n'),
+  };
+}

package/scripts/tasks.mjs

@@ -434,6 +434,10 @@ Infrastructure   (init and add need no board: run them in the checkout of the re
                          run it holds (--task <ID>, else the one routine run it has claimed here); it says whether
                          the owner's envelope covers it or it waits for the owner, and names the plan. Only a
                          runbook's run may; it's the one change a run may ask for, and it never applies anything
+  infra adopt <environment>   write the board's draft of the environment's desired state, drafted from what runs
+                         there, to .github/breakaway-infra/<environment>.json, then check it like infra check and say
+                         what to commit; it never plans or applies, and writes nothing for an observe-only environment
+                         [--force] replaces a file that's there  [--dry-run] prints the draft instead
   infra add [<template>] [<environment>] [<input>=<value> …]   a golden path: write the change one of the owner's
                          templates makes (.github/breakaway-infra/templates/<name>/, else breakaway's example of that
                          name) into the environment's file and the code it needs, for a pull request; it never
@@ -1441,6 +1445,22 @@ const commands = {
       process.exitCode = result.code;
       return;
     }
+    if (args[0] === 'adopt') {
+      // infra adopt (CLI-23): the board's draft of an environment's desired state, written into the checkout and checked.
+      const { infraAdopt } = await import('./tasks/infra-adopt.js');
+      const { topOf } = await import('./tasks/pipeline.js');
+      const result = await infraAdopt(args.slice(1), {
+        root: topOf(process.cwd()),
+        repo: slug,
+        force: Boolean(opts.force),
+        dryRun: Boolean(opts['dry-run']),
+        get: (path) => call('GET', path, undefined, { raw: true }),
+        post: (path, body) => call('POST', path, body, { raw: true }),
+      });
+      print(result.data, () => result.text);
+      process.exitCode = result.code;
+      return;
+    }
     if (args[0] === 'act') {
       // infra act (CLI-24): a runbook's agent asks for one scale or restart, for the run it holds; the board decides.
       const { infraAct, InfraActError } = await import('./tasks/infra-act.js');

package/src/infra-desired.js

@@ -17,8 +17,11 @@ import { redact } from './redact.js';
 export const DESIRED_DIR = '.github/breakaway-infra';
 /** @param {string} environment */
 export const desiredPath = (environment) => `${DESIRED_DIR}/${environment}.json`;
-/** Files in the folder that aren't an environment's: policy (BRK-181) and scaling rules (BRK-186). */
-export const RESERVED_FILES = ['policy', 'scaling'];
+/**
+ * Files in the folder that aren't an environment's: policy (BRK-181), scaling rules (BRK-186), and the template
+ * short-lived environments are made from (BRK-200).
+ */
+export const RESERVED_FILES = ['policy', 'scaling', 'short-lived'];
 /** The only version there is. */
 export const DESIRED_VERSION = 1;
 /** Bigger than any one environment needs, and small enough to keep a copy of each in the store. */
@@ -204,10 +207,11 @@ function secretIn(value, path) {
  * resource's kind must be one it declares. With `expectProvider` (the environment's provider ID), a `provider` in the
  * file must be that one.
  * @param {string} source the file's text
- * @param {{ provider?: import('./infra-provider.js').Provider | null, expectProvider?: string | null }} [options]
+ * @param {{ provider?: import('./infra-provider.js').Provider | null, expectProvider?: string | null, extra?: string[] }} [options]
+ *   `extra` names more top-level keys a caller reads itself, like a short-lived template's `target` (BRK-200)
  * @returns {{ ok: true, desired: import('./infra-provider.js').DesiredState, provider: string | null } | { ok: false, error: DesiredError }}
  */
-export function checkDesiredFile(source, { provider = null, expectProvider = null } = {}) {
+export function checkDesiredFile(source, { provider = null, expectProvider = null, extra = [] } = {}) {
   /** @param {string | null} field @param {string} message @param {number | null} [at] */
   const wrong = (field, message, at) => ({
     ok: /** @type {const} */ (false),
@@ -228,8 +232,11 @@ export function checkDesiredFile(source, { provider = null, expectProvider = nul
   if (!isObject(file))
     return wrong(null, 'the file is one JSON object: { "version": 1, "resources": [ … ] }', lines.get('') ?? 1);
   for (const key of Object.keys(file))
-    if (!TOP.includes(key))
-      return wrong(key, `“${key}” isn’t part of a desired state: the file has version, provider, and resources`);
+    if (!TOP.includes(key) && !extra.includes(key))
+      return wrong(
+        key,
+        `“${key}” isn’t part of a desired state: the file has ${[...TOP, ...extra].join(', ').replace(/, (?=[^,]*$)/u, ', and ')}`,
+      );
   if (file.version !== DESIRED_VERSION)
     return wrong(
       file.version === undefined ? null : 'version',

package/src/infra-environments.js

@@ -0,0 +1,100 @@
+/**
+ * Architect's environments (docs/specs/IDEA-19-architect.md, "Environments"; BRK-174): a named target in one of the
+ * board's repositories that plans apply to. Pure, so the rules are tested without the Durable Object; the table and
+ * the API are in store-infra-environments.js.
+ */
+import { RESERVED_FILES } from './infra-desired.js';
+import { InputError } from './model.js';
+
+/** What an environment is for; production gates apply to `production` unless the owner says otherwise. */
+export const ENVIRONMENT_KINDS = ['production', 'staging', 'short-lived'];
+/** Per repository: enough for staging, production, and a handful of short-lived ones at once. */
+export const MAX_ENVIRONMENTS = 50;
+
+/** A name that's also a file name: `.github/breakaway-infra/<environment>.json` (BRK-180). */
+const NAME = /^[a-z0-9][a-z0-9-]{0,39}$/u;
+/** A provider's ID in the registry (BRK-173), like `cloudflare`. */
+const PROVIDER = /^[a-z][a-z0-9-]{0,31}$/u;
+/** What the environment points at on its provider, like a Worker's name. */
+const TARGET = /^[\w.:/-]{1,100}$/u;
+
+/** @param {unknown} value */
+export function checkEnvironmentName(value) {
+  const name = String(value ?? '').trim();
+  if (!NAME.test(name))
+    throw new InputError(
+      'name the environment with lowercase letters, digits, and - (up to 40), like staging or preview-12: it’s also its desired-state file’s name',
+    );
+  if (RESERVED_FILES.includes(name))
+    throw new InputError(
+      `${name} is the name of Architect’s ${name} file, so an environment can’t have it: pick another`,
+    );
+  return name;
+}
+
+/** @param {unknown} value */
+export function checkEnvironmentKind(value) {
+  const kind = String(value ?? '').trim();
+  if (!ENVIRONMENT_KINDS.includes(kind)) throw new InputError('kind is production, staging, or short-lived');
+  return kind;
+}
+
+/** @param {unknown} value */
+export function checkProvider(value) {
+  const provider = String(value ?? '').trim();
+  if (!PROVIDER.test(provider))
+    throw new InputError('provider is the ID of the provider the environment runs on, like cloudflare');
+  return provider;
+}
+
+/** @param {unknown} value @returns {string | null} */
+export function checkTarget(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const target = String(value).trim();
+  if (!TARGET.test(target))
+    throw new InputError(
+      'target is what the environment runs on at its provider, like a Worker’s name (up to 100 characters)',
+    );
+  return target;
+}
+
+/** @param {unknown} value @param {string} field */
+export function checkSwitch(value, field) {
+  if (typeof value !== 'boolean') throw new InputError(`${field} is true or false`);
+  return value;
+}
+
+/**
+ * Whether an environment runs the board's own install: it points at the install's Worker (src/install.js). That one
+ * is always observe only (BRK-169), whatever its row says, so Architect never applies to the board it runs on.
+ * @param {{ target: string | null }} row
+ * @param {string} worker the install's Worker
+ */
+export const runsTheBoard = (row, worker) => Boolean(row.target) && row.target === worker;
+
+/**
+ * The environment as the API shows it.
+ * @param {{ id: number, repo: string, name: string, kind: string, provider: string | null, target: string | null, task: string | null, frozen: number, frozen_at: number | null, gates: number | null, observe_only: number, pipeline?: string | null, created: number, edited: number }} row
+ * @param {{ worker: string, task?: { uuid: string, wid: string | null, description: string } | null }} context
+ */
+export function environmentView(row, { worker, task = null }) {
+  const own = runsTheBoard(row, worker);
+  return {
+    id: row.id,
+    repo: row.repo,
+    name: row.name,
+    kind: row.kind,
+    provider: row.provider ?? null,
+    target: row.target ?? null,
+    task,
+    frozen: Boolean(row.frozen),
+    frozenAt: row.frozen && row.frozen_at ? new Date(row.frozen_at).toISOString() : null,
+    gates: row.gates === null || row.gates === undefined ? row.kind === 'production' : Boolean(row.gates),
+    observeOnly: own || Boolean(row.observe_only),
+    runsTheBoard: own,
+    // `staging` or `production` when it's its repository's pipeline's (BRK-195), else null.
+    pipeline: row.pipeline ?? null,
+    created: new Date(row.created).toISOString(),
+    edited: new Date(row.edited).toISOString(),
+  };
+}

package/src/infra-plans.js

@@ -21,10 +21,10 @@ export const PLAN_STATES = ['draft', 'waiting', 'approved', 'rejected', 'applyin
 
 /**
  * Where a plan comes from: a pull request that changed a desired-state file (BRK-185), drift (BRK-184), an envelope
- * acting (BRK-186), an incident's runbook (BRK-197), the deploy flow's Promote and Roll back (BRK-195), or removing
- * what nobody owns once its grace period is over (BRK-201).
+ * acting (BRK-186), an incident's runbook (BRK-197), the deploy flow's Promote and Roll back (BRK-195), removing what
+ * nobody owns once its grace period is over (BRK-201), or a task's short-lived environment being made or removed (BRK-200).
  */
-export const PLAN_SOURCES = ['pull-request', 'drift', 'envelope', 'incident', 'deploy', 'cleanup'];
+export const PLAN_SOURCES = ['pull-request', 'drift', 'envelope', 'incident', 'deploy', 'cleanup', 'short-lived'];
 
 /**
  * Which states a plan may move to from each. A draft waits for the owner or is dropped; only an approved plan is

package/src/infra-policy.js

@@ -25,6 +25,7 @@
 import { CHANGE_KINDS } from './infra-provider.js';
 import { DESIRED_DIR, parseWithLines } from './infra-desired.js';
 import { rateWords } from './infra-currency.js';
+import { ENVIRONMENT_KINDS } from './infra-environments.js';
 
 /** @typedef {import('./infra-provider.js').PlanDiff} PlanDiff */
 /** @typedef {import('./infra-provider.js').Change} Change */
@@ -67,6 +68,8 @@ export const DEFAULT_POLICY = Object.freeze({
  * @typedef {object} AllowRule
  * @property {string} name what the plan and the audit trail call it
  * @property {string[]} [environments] the environments it covers, by name; every one when left out
+ * @property {string[]} [environmentKinds] the kinds of environment it covers (ENVIRONMENT_KINDS), like `short-lived`
+ *   for the environments tasks ask for (BRK-200), whose names aren't known ahead; every kind when left out
  * @property {string[]} [changes] the change kinds it covers (CHANGE_KINDS); every one when left out
  * @property {string[]} [kinds] the resource kinds it covers; every one when left out
  * @property {number} [maxChanges] the most changes a plan it lets through has
@@ -86,7 +89,7 @@ export const DEFAULT_POLICY = Object.freeze({
 const TOP = ['version', 'costLimit', 'budget', 'environments', 'access', 'allow'];
 const LIMITS = ['costLimit', 'budget'];
 const ACCESS = ['kinds', 'settings'];
-const RULE = ['name', 'environments', 'changes', 'kinds', 'maxChanges'];
+const RULE = ['name', 'environments', 'environmentKinds', 'changes', 'kinds', 'maxChanges'];
 const ENV_NAME = /^[a-z0-9][a-z0-9-]{0,39}$/u;
 const KIND = /^[a-z][a-z0-9-]{0,39}$/u;
 const SETTING = /^[A-Za-z_][\w.-]{0,79}$/u;
@@ -239,6 +242,22 @@ export function checkPolicyFile(source) {
         if (bad) return bad;
         rule.environments = [...r.environments];
       }
+      if (r.environmentKinds !== undefined) {
+        const bad = names(
+          r.environmentKinds,
+          `${at}.environmentKinds`,
+          KIND,
+          `a kind of environment: ${ENVIRONMENT_KINDS.join(', ')}`,
+        );
+        if (bad) return bad;
+        const unknown = r.environmentKinds.findIndex((k) => !ENVIRONMENT_KINDS.includes(k));
+        if (unknown >= 0)
+          return wrong(
+            `${at}.environmentKinds[${unknown}]`,
+            `${r.environmentKinds[unknown]} isn’t a kind of environment: ${ENVIRONMENT_KINDS.join(', ')}`,
+          );
+        rule.environmentKinds = [...r.environmentKinds];
+      }
       if (r.changes !== undefined) {
         const bad = names(r.changes, `${at}.changes`, KIND, `a change kind: ${CHANGE_KINDS.join(', ')}`);
         if (bad) return bad;
@@ -369,8 +388,9 @@ const upper = (s) => s.charAt(0).toUpperCase() + s.slice(1);
  * keeps and shows. Pure: the caller gives the environment as it is now, and the plan's diff and cost change.
  * @param {Policy} policy
  * @param {object} plan
- * @param {{ name: string, frozen: boolean, gates: boolean }} plan.environment `gates` is production's gates
- *   (environmentView's `gates`: on for a production environment unless the owner turned them off)
+ * @param {{ name: string, kind?: string, frozen: boolean, gates: boolean }} plan.environment `gates` is production's
+ *   gates (environmentView's `gates`: on for a production environment unless the owner turned them off); `kind` is
+ *   what an allow rule's `environmentKinds` matches
  * @param {PlanDiff} plan.diff
  * @param {CostChange} plan.cost
  * @param {import('./infra-provider.js').Provider | null} [plan.provider] for the kinds and settings it marks as access
@@ -471,7 +491,7 @@ export function evaluatePolicy(
     outcome = 'needs-owner';
     rule = asked[0].rule;
   } else {
-    const allowed = policy.allow.find((a) => allows(a, env, diff));
+    const allowed = policy.allow.find((a) => allows(a, env, diff, environment.kind));
     if (allowed) {
       outcome = 'allowed';
       rule = allowed.name;
@@ -511,9 +531,11 @@ export function evaluatePolicy(
  * @param {AllowRule} rule
  * @param {string} environment
  * @param {PlanDiff} diff
+ * @param {string} [kind] the environment's kind, for a rule with `environmentKinds`
  */
-export function allows(rule, environment, diff) {
+export function allows(rule, environment, diff, kind) {
   if (rule.environments && !rule.environments.includes(environment)) return false;
+  if (rule.environmentKinds && !rule.environmentKinds.includes(String(kind))) return false;
   if (rule.maxChanges !== undefined && diff.changes.length > rule.maxChanges) return false;
   return diff.changes.every(
     (c) => (!rule.changes || rule.changes.includes(c.op)) && (!rule.kinds || rule.kinds.includes(c.kind)),