breakaway 2.0.0-main.52 → 2.0.0-main.53

package/npm-shrinkwrap.json

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

package/scripts/tasks/cli.js

@@ -29,7 +29,7 @@ export const SUBCOMMANDS = {
     'listen',
   ],
   specs: ['list', 'show'],
-  infra: ['init', 'runner', 'check', ...INFRA_READS],
+  infra: ['init', 'runner', 'check', '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-act.js

@@ -0,0 +1,108 @@
+/**
+ * `npx breakaway infra act <environment> <resource> scale <n>|restart` (CLI-24, docs/specs/IDEA-19-architect.md,
+ * "Envelopes"): a runbook's agent asks for one scale or restart, for the run it holds. It's the one change a run may
+ * ask for, and it's the CLI's only: Architect's MCP tools stay read only.
+ *
+ * The request is POST /api/infra/envelopes/<environment>/act (BRK-186) with { resource, change, value, task, by }: the
+ * board checks the agent holds the runbook's run, builds the plan itself, and answers whether the envelope the owner
+ * approved covers it (the executor applies it) or it waits for the owner. The board's words go through unchanged when
+ * it refuses. The requests go through `get` and `post`, which the CLI gives (and the tests mock), and which answer
+ * `{ ok, status, data }` for any answer.
+ */
+import { PLAN_STATE_LABELS } from './infra-read.js';
+
+/** An act the CLI won't send, with what to do instead. */
+export class InfraActError extends Error {}
+const bad = (message) => {
+  throw new InfraActError(message);
+};
+
+const enc = encodeURIComponent;
+const USAGE = 'infra act <environment> <resource> scale <n>|restart';
+
+/**
+ * What follows `infra act`, as the act route's body.
+ * @param {string[]} args
+ * @returns {{ environment: string, resource: string, change: 'scale' | 'restart', value: number | null }}
+ */
+export function parseAct(args) {
+  const [environment, resource, change, value, ...rest] = args;
+  if (!environment || !resource || !change)
+    bad(`${USAGE}: name the environment, the resource, and the change, like infra act production widgets-api scale 4.`);
+  if (change === 'restart') {
+    if (value !== undefined) bad(`${USAGE}: a restart takes no number.`);
+    return { environment, resource, change: 'restart', value: null };
+  }
+  if (change !== 'scale') bad(`${USAGE}: the change is scale or restart, not ${change}.`);
+  if (value === undefined || !/^\d{1,5}$/u.test(value)) bad(`${USAGE}: scale needs a whole number, like scale 4.`);
+  if (rest.length) bad(`${USAGE}: one change at a time.`);
+  return { environment, resource, change: 'scale', value: Number(value) };
+}
+
+/**
+ * The run this agent holds: `--task` when it names one, else the only routine run in this repository it has claimed.
+ * The board checks it's a runbook's either way.
+ * @param {{ task?: string, get: (path: string) => Promise<{ ok: boolean, status: number, data: any }>,
+ *   agent: string, inRepo: (task: any) => boolean }} ctx
+ */
+export async function heldRun({ task, get, agent, inRepo }) {
+  if (task) return String(task);
+  const res = await get('tasks?status=pending');
+  if (!res.ok) bad(res.data?.error ?? `HTTP ${res.status}`);
+  const runs = (res.data.tasks ?? []).filter((t) => t.claim === agent && t.project === 'routines' && inRepo(t));
+  if (runs.length === 1) return runs[0].wid ?? runs[0].uuid;
+  if (!runs.length)
+    bad(
+      `${agent} holds no routine run here: only a runbook’s agent acts in an envelope, for the run it holds. Name it with --task <ID>.`,
+    );
+  return bad(`${agent} holds ${runs.length} runs (${runs.map((t) => t.wid).join(', ')}): name one with --task <ID>.`);
+}
+
+/**
+ * What the board answered, in words: inside the envelope it applies without a press; outside it waits for the owner.
+ * @param {{ act: { inside: boolean, why: string, plan: any } }} data
+ * @param {{ environment: string, resource: string, change: string, value: number | null }} asked
+ */
+export function actText({ act }, asked) {
+  const what = asked.change === 'scale' ? `Scale ${asked.resource} to ${asked.value}` : `Restart ${asked.resource}`;
+  const plan = act.plan ?? {};
+  const state = PLAN_STATE_LABELS[plan.state] ?? plan.state;
+  const out = act.inside
+    ? [
+        `${what} in ${asked.environment}: inside its envelope (${act.why}).`,
+        `${plan.id} · ${state}: it applies without a press.`,
+      ]
+    : [
+        `${what} in ${asked.environment}: waits for the owner (${act.why}).`,
+        `${plan.id} · ${state}: the owner approves or rejects it on the board.`,
+      ];
+  out.push('', `The plan: npx breakaway infra plan ${plan.id}`);
+  return out.join('\n');
+}
+
+/**
+ * Runs `infra act`. `code` is what the CLI exits with: 1 when the board refuses the act.
+ * @param {string[]} args what follows `infra act`
+ * @param {{ get: (path: string) => Promise<{ ok: boolean, status: number, data: any }>,
+ *   post: (path: string, body: any) => Promise<{ ok: boolean, status: number, data: any }>,
+ *   repo: string | null, agent: string, opts?: Record<string, any>, inRepo?: (task: any) => boolean }} ctx
+ * @returns {Promise<{ data: any, text: string, code: number }>}
+ */
+export async function infraAct(args, { get, post, repo, agent, opts = {}, inRepo = () => true }) {
+  const asked = parseAct(args);
+  const task = await heldRun({ task: opts.task, get, agent, inRepo });
+  const res = await post(`infra/envelopes/${enc(asked.environment)}/act`, {
+    resource: asked.resource,
+    change: asked.change,
+    value: asked.value,
+    task,
+    by: agent,
+    ...(repo ? { repo } : {}),
+  });
+  if (res.ok) return { data: res.data, text: actText(res.data, asked), code: 0 };
+  if (res.status === 0) bad(`can’t reach the board (${res.data?.error ?? 'no answer'}).`);
+  if (res.status === 404 && /^no route for/u.test(String(res.data?.error ?? '')))
+    bad('this board doesn’t have envelopes yet: its owner updates it to a release that does, then try again.');
+  const error = res.data?.error ?? `HTTP ${res.status}`;
+  return { data: { status: res.status, error }, text: `The board refused it: ${error}`, code: 1 };
+}

package/scripts/tasks.mjs

@@ -429,6 +429,10 @@ Infrastructure   (init and add need no board: run them in the checkout of the re
                          and policy.json, naming the file, line, and field that's wrong), then show the plan each valid
                          file would make from what runs now and the policy's answer; the board keeps none of it
                          (exits 1 if a file doesn't check or the board refuses one)
+  infra act <environment> <resource> scale <n>|restart   a runbook's agent asks for one scale or restart, for the
+                         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 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
@@ -1436,6 +1440,28 @@ const commands = {
       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');
+      let result;
+      try {
+        result = await infraAct(args.slice(1), {
+          get: (path) => call('GET', path, undefined, { raw: true }),
+          post: (path, body) => call('POST', path, body, { raw: true }),
+          repo: slug,
+          agent: agent(),
+          opts,
+          inRepo: (t) => !slug || inRepo(t, slug, repoContext.registry),
+        });
+      } catch (error) {
+        if (!(error instanceof InfraActError)) throw error;
+        if (opts.json) console.log(JSON.stringify({ error: error.message }, null, 2));
+        fail(error.message);
+      }
+      print(result.data, () => result.text);
+      process.exitCode = result.code;
+      return;
+    }
     // Architect's reads (CLI-13): every request is a GET, so an agent's token reads and never writes.
     let result;
     try {