breakaway 2.0.0-main.60 → 2.0.0-main.61

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "breakaway",
-  "version": "2.0.0-main.60",
+  "version": "2.0.0-main.61",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "breakaway",
-      "version": "2.0.0-main.60",
+      "version": "2.0.0-main.61",
       "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.61",
   "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/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)),