breakaway 1.4.0-main.53 → 1.4.0-main.55

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakaway",
-  "version": "1.4.0-main.53",
+  "version": "1.4.0-main.55",
   "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",
@@ -30,6 +30,7 @@
     "src/prompt.js",
     "src/redact.js",
     "src/repos.js",
+    "src/session-report.js",
     "src/specs.js",
     "src/versions.js",
     "prompts/*.md",

package/scripts/tasks/platform.js

@@ -0,0 +1,55 @@
+/**
+ * The systems the install supports (CLI-3, decided in BRK-140): macOS, Linux, and Windows through WSL. The commands
+ * that write a secret run `npx wrangler` without a shell, and `setup` runs a `#!/bin/sh` script, so on Windows
+ * itself (PowerShell or cmd) they stop before doing anything. Where wrangler can't run, the reason it gives is what's
+ * reported, not a guess. Pure, so it's tested without Windows or wrangler.
+ */
+
+export const WSL_URL = 'https://learn.microsoft.com/windows/wsl/install';
+
+/**
+ * Null on a supported system; on Windows itself, the message that stops `command`.
+ *
+ * @param {string} command
+ * @param {string} platform `process.platform`
+ * @returns {string | null}
+ */
+export function unsupportedSystem(command, platform) {
+  if (platform !== 'win32') return null;
+  return `npx breakaway ${command} doesn't run on Windows itself, so nothing was changed. Install WSL (${WSL_URL}), then run it in WSL's terminal: the board supports macOS, Linux, and Windows through WSL.`;
+}
+
+/** Colours and wrangler's box-drawing around its messages. */
+const NOISE = /\u001b\[[0-9;]*m|[│┌┐└┘─╭╮╰╯]/gu;
+
+/** Lines that say nothing about the failure: wrangler's banner and npm's warnings. */
+const CHATTER = /^(\S+\s+)?wrangler \d+\.\d+|^npm (warn|notice)|^Update available/iu;
+
+/** @param {string | null | undefined} text */
+const meaningful = (text) =>
+  (text ?? '')
+    .replace(NOISE, '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line && !CHATTER.test(line));
+
+/**
+ * Why a `spawnSync('npx', ['wrangler', …])` failed, in one line: npx missing or not runnable, else wrangler's own
+ * error (its `✘ [ERROR]` line, or its last line of output), else its exit code.
+ *
+ * @param {{ error?: (Error & { code?: string }) | undefined, status: number | null, signal?: string | null, stdout?: string | null, stderr?: string | null }} res
+ * @returns {string}
+ */
+export function wranglerFailure(res) {
+  if (res.error?.code === 'ENOENT')
+    return "npx isn't on this machine's PATH; install Node.js 20 or newer, then run this again";
+  if (res.error) return `npx couldn't run (${res.error.message})`;
+  const stderr = meaningful(res.stderr);
+  const stdout = meaningful(res.stdout);
+  const error = [...stderr, ...stdout].find((line) => /^✘\s*\[ERROR\]/u.test(line));
+  if (error) return `wrangler said: ${error.replace(/^✘\s*\[ERROR\]\s*/u, '')}`;
+  const last = (stderr.length ? stderr : stdout).at(-1);
+  if (last) return `wrangler said: ${last}`;
+  if (res.signal) return `wrangler stopped (${res.signal})`;
+  return `wrangler stopped with exit code ${res.status}`;
+}

package/scripts/tasks.mjs

@@ -39,10 +39,12 @@ import {
   textFields,
 } from './tasks/structure.js';
 import { looksLikeSecret } from '../src/ping.js';
+import { sessionReport, shortHash, stubText } from '../src/session-report.js';
 import { promptPathOf } from '../src/repos.js';
 import { hookFailure, sessionProxy, routeThroughSessionProxy } from './tasks/proxy.js';
 import { githubFromRemote, inRepo, pickRepo } from './tasks/repo.js';
 import { appInPlace } from './tasks/github-connect.js';
+import { unsupportedSystem, wranglerFailure } from './tasks/platform.js';
 import { checkInstall } from './tasks/install-check.js';
 import { NO_TERMINAL, ask as askIn } from './tasks/ask.js';
 import {
@@ -142,6 +144,12 @@ async function ensureBoardInstall(command, health = null) {
   if (result.warning) console.error(`tasks: ${result.warning}`);
 }
 
+/** Stops `command` before it does anything on a system the install doesn't support: Windows outside WSL (CLI-3). */
+function ensureSupportedSystem(command) {
+  const message = unsupportedSystem(command, process.platform);
+  if (message) fail(message);
+}
+
 /** A file in this checkout, or null when it isn't there. */
 function readOptional(path) {
   try {
@@ -623,6 +631,18 @@ async function startSessionLog(t) {
     );
 }
 
+/**
+ * In a cloud session, what its claim tells the board about its environment, so the routine that started it reads
+ * Verified on Connections (BRK-142): whether a name was set, where the token came from, and the hash of this
+ * checkout's copy of the stub. Never a value. Null outside a cloud session.
+ */
+async function environmentReport() {
+  if (process.env.CLAUDE_CODE_REMOTE !== 'true') return null;
+  const path = ['tools/tasks/prompts/stub.md', 'prompts/stub.md'].map((p) => join(REPO, p)).find((p) => existsSync(p));
+  const stub = path ? await shortHash(stubText(readFileSync(path, 'utf8'))) : null;
+  return sessionReport({ env: process.env, file: fileEnv, named: Boolean(opts.as), stub });
+}
+
 /** The session hook couldn't post this checkout's live output: say so where the agent and the owner see it (BRK-86). */
 function warnHookFailure() {
   try {
@@ -1250,10 +1270,12 @@ const commands = {
   async claim() {
     // The board refuses a task of another repository than the one sent (--all doesn't widen a claim).
     const { slug: repo } = await checkoutRepo();
+    const session = await environmentReport();
     const { task } = await call('POST', `tasks/${enc(need(args[0], 'task'))}/claim`, {
       agent: agent(),
       force: Boolean(opts.force),
       ...(repo ? { repo } : {}),
+      ...(session ? { session } : {}),
     });
     markSession(task);
     await startSessionLog(task);
@@ -1539,6 +1561,8 @@ const commands = {
   /** Every connection with its state and, for each that isn't working, the fix (IDEA-14). Read only. */
   async connections() {
     const STATE = { working: 'Working', attention: 'Needs attention', off: 'Not connected' };
+    // A routine's row says whether a session it started has reported back (BRK-142).
+    const READING = { verified: 'Verified', unverified: 'Not verified yet' };
     const GROUP = {
       repos: 'Repositories',
       cloudflare: 'Cloudflare',
@@ -1568,7 +1592,7 @@ const commands = {
           out.push('', GROUP[group] ?? group);
         }
         const when = c.at ? ` (${c.at.slice(0, 16).replace('T', ' ')})` : '';
-        out.push(`  ${STATE[c.state].padEnd(16)} ${c.name}: ${c.detail}${when}`);
+        out.push(`  ${(READING[c.reading] ?? STATE[c.state] ?? c.state).padEnd(16)} ${c.name}: ${c.detail}${when}`);
         if (c.fix) out.push(`  ${''.padEnd(16)} Fix: ${c.fix}`);
         if (c.fix && c.link) out.push(`  ${''.padEnd(16)} ${c.link}`);
       }
@@ -1578,6 +1602,7 @@ const commands = {
     });
   },
   async setup() {
+    ensureSupportedSystem('setup');
     const clientId = setting('CLIENT_ID');
     const secret = setting('SECRET');
     if (!clientId || !secret)
@@ -1620,6 +1645,7 @@ const commands = {
    * values. The new values are saved before the server switches, so they can't be lost.
    */
   async 'rotate-sync'() {
+    ensureSupportedSystem('rotate-sync');
     const env = readEnvFile();
     if (!readSetting('SECRET', { file: env })) fail(`${ENV_FILE} has no sync secret; this is for the owner's machine.`);
     const health = await call('GET', 'health');
@@ -1654,6 +1680,7 @@ const commands = {
   },
   /** Owner: a new API token. Every browser is signed out; cloud environments need the new one. */
   async 'rotate-token'() {
+    ensureSupportedSystem('rotate-token');
     await ensureBoardInstall('rotate-token');
     const env = readEnvFile();
     const token = randomBytes(32).toString('base64url');
@@ -1686,6 +1713,7 @@ const commands = {
    * the install's ROUTINES secret (BREAKAWAY_ROUTINES with breakaway's prefix), JSON keyed by slug, merged with this machine's copy of the others.
    */
   async 'agents-connect'() {
+    ensureSupportedSystem('agents-connect');
     const { repos, default: fallback } = await call('GET', 'repos');
     const slug = opts.repo ? String(opts.repo).toLowerCase() : fallback;
     if (!repos.some((r) => r.slug === slug)) fail(unknownRepo(slug, repos));
@@ -1706,13 +1734,11 @@ const commands = {
       fail("that isn't a routine token; generate one in the routine's API trigger.");
     if (!others) {
       if (!updateSecretsStore({ ROUTINE_URL: url, ROUTINE_TOKEN: token }))
-        fail("couldn't update the Secrets Store (is wrangler logged in?).");
+        fail("couldn't update the Secrets Store (the reason is above), so the routine isn't connected.");
     } else {
       const next = { ...others, [slug]: { url, token } };
       if (!updateSecretsStore({ ROUTINES: JSON.stringify(next) }))
-        fail(
-          `couldn't update the Secrets Store (is wrangler logged in, and does ${secretName(installConfig(), 'ROUTINES')} exist?).`,
-        );
+        fail("couldn't update the Secrets Store (the reason is above), so the routine isn't connected.");
       writePrivate(ROUTINES_FILE, `${JSON.stringify(next, null, 2)}\n`);
     }
     console.log(
@@ -1726,6 +1752,7 @@ const commands = {
    * the App's ID, key, and webhook secret, and pipe them into the Secrets Store.
    */
   async 'github-connect'() {
+    ensureSupportedSystem('github-connect');
     const code = need(args[0], 'code');
     // Before the code is traded: it works once, and the keys it gives have to go into the board's own secrets.
     await ensureBoardInstall('github-connect');
@@ -2162,8 +2189,10 @@ async function promptAnswers() {
 async function removeRepo(slug, signer) {
   const { default: fallback } = await call('GET', 'repos');
   // Dropping a routine this machine connected rewrites the ROUTINES secret: check before anything changes.
-  if (existsSync(ROUTINES_FILE) && JSON.parse(readFileSync(ROUTINES_FILE, 'utf8'))[slug])
+  if (existsSync(ROUTINES_FILE) && JSON.parse(readFileSync(ROUTINES_FILE, 'utf8'))[slug]) {
+    ensureSupportedSystem('repos remove');
     await ensureBoardInstall('repos remove');
+  }
   const res = await call('DELETE', `repos/${enc(slug)}`, { by: signer, ...(opts.force ? { force: true } : {}) });
   const lines = [
     `Took ${res.removed.slug} (${res.removed.github}) off the board. Its tasks stay, readable, and its slug and prefixes (${res.removed.areas.map((a) => a.prefix).join(', ')}) stay its own.`,
@@ -2184,7 +2213,7 @@ async function removeRepo(slug, signer) {
       delete next[res.removed.slug];
       if (!updateSecretsStore({ ROUTINES: JSON.stringify(next) }))
         lines.push(
-          `Couldn't drop its routine from the Secrets Store (is wrangler logged in?); the board doesn't use it any more.`,
+          `Couldn't drop its routine from the Secrets Store (the reason is above); the board doesn't use it any more.`,
         );
       else {
         writePrivate(ROUTINES_FILE, `${JSON.stringify(next, null, 2)}\n`);
@@ -2266,7 +2295,7 @@ function updateSecretsStore(values) {
     { cwd: REPO, encoding: 'utf8' },
   );
   if (list.status !== 0) {
-    console.error(`tasks: couldn't list the Secrets Store (is wrangler logged in?)`);
+    console.error(`tasks: couldn't list the Secrets Store: ${wranglerFailure(list)}`);
     return false;
   }
   const ids = Object.fromEntries(
@@ -2286,7 +2315,7 @@ function updateSecretsStore(values) {
       { cwd: REPO, encoding: 'utf8', input: value },
     );
     if (res.status !== 0) {
-      console.error(`tasks: couldn't update ${name} in the Secrets Store`);
+      console.error(`tasks: couldn't update ${name} in the Secrets Store: ${wranglerFailure(res)}`);
       ok = false;
     }
   }
@@ -2307,7 +2336,7 @@ function updateWorkerSecrets(install, values) {
       input: value,
     });
     if (res.status !== 0) {
-      console.error(`tasks: couldn't set ${binding} on the Worker ${install.worker} (is wrangler logged in?)`);
+      console.error(`tasks: couldn't set ${binding} on the Worker ${install.worker}: ${wranglerFailure(res)}`);
       ok = false;
     }
   }

package/src/session-report.js

@@ -0,0 +1,92 @@
+/**
+ * A cloud session's report on its own environment (BRK-142, docs/specs/IDEA-33-onboarding-hardening.md): the CLI
+ * sends it with a board-started agent's claim, and the routine that started the session reads Verified on
+ * Connections. Only yes/no facts and a hash of a public file are sent, never a value: whether a name was set,
+ * where the token came from, and the sha-256 of the checkout's copy of the stub. Pure, so it's tested without a
+ * Worker; the CLI builds a report with `sessionReport`, the board checks it with `checkReport`
+ * and `judgeStub` when it arrives, and reads it back with `reportProblems`.
+ */
+
+/** Where the session's token came from: the cloud environment's API credential, a variable, or a tasks.env file. */
+export const TOKEN_SOURCES = Object.freeze(['credential', 'variable', 'file']);
+
+/** The stub's text the way it's hashed on both sides: line endings and trailing space don't count. */
+export const stubText = (text) => String(text).replace(/\r\n/gu, '\n').trim();
+
+/**
+ * The report a cloud session's CLI sends with its claim, or null outside a cloud session. `env` is the environment,
+ * `file` the tasks.env settings, `named` whether --as named the agent, and `stub` the hash of the checkout's
+ * stub (null when the checkout has none).
+ * @param {{ env: Record<string, string | undefined>, file?: Record<string, string>, named?: boolean, stub?: string | null }} input
+ */
+export function sessionReport({ env, file = {}, named = false, stub = null }) {
+  if (env.CLAUDE_CODE_REMOTE !== 'true') return null;
+  const token = env.BREAKAWAY_TOKEN ? 'variable' : file.BREAKAWAY_TOKEN ? 'file' : 'credential';
+  return { token, agent: Boolean(named || env.BREAKAWAY_AGENT || file.BREAKAWAY_AGENT), stub: stub ?? null };
+}
+
+/**
+ * The report as the board keeps it, or null when it isn't one: only the known facts, so nothing else a client
+ * sends is ever stored.
+ * @returns {{ token: string, agent: boolean, stub: string | null } | null}
+ */
+export function checkReport(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  if (!TOKEN_SOURCES.includes(input.token) || typeof input.agent !== 'boolean') return null;
+  const stub = typeof input.stub === 'string' && /^[0-9a-f]{16}$/u.test(input.stub) ? input.stub : null;
+  return { token: input.token, agent: input.agent, stub };
+}
+
+/**
+ * The checkout's stub against the board's, both hashes: `same`, `different`, or `missing` (the checkout has none),
+ * and null when the board has no copy to compare with, so the stub isn't judged.
+ * @returns {'same' | 'different' | 'missing' | null}
+ */
+export function judgeStub(stub, boardStub) {
+  if (!boardStub) return null;
+  if (!stub) return 'missing';
+  return stub === boardStub ? 'same' : 'different';
+}
+
+/**
+ * What's wrong in a kept report, each with its fix: no agent name, the token in a variable or a file instead of
+ * the API credential, and a stub that's missing from the checkout or differs from the board's (`stub`, judgeStub's
+ * verdict). `slug` names the repository and `host` the board in the fixes.
+ * @param {{ token: string, agent: boolean, stub: string | null }} report
+ * @param {{ slug: string, host: string }} board
+ * @returns {{ what: string, fix: string }[]}
+ */
+export function reportProblems(report, { slug, host }) {
+  const out = [];
+  if (!report.agent)
+    out.push({
+      what: 'it had no agent name (BREAKAWAY_AGENT)',
+      fix: 'Make the routine’s instructions the stub from the Agents view (Copy stub): it sends each agent to the prompt that sets BREAKAWAY_AGENT to the name the board gave it.',
+    });
+  if (report.token !== 'credential')
+    out.push({
+      what:
+        report.token === 'variable'
+          ? 'it read the board’s token from BREAKAWAY_TOKEN, a variable anyone using the environment can see'
+          : 'it read the board’s token from a tasks.env file',
+      fix: `In the routine’s cloud environment on claude.ai, add the token as an API credential for ${host} and remove BREAKAWAY_TOKEN: the proxy then adds it, and the token never enters the session.`,
+    });
+  if (report.stub === 'different' || report.stub === 'missing')
+    out.push({
+      what:
+        report.stub === 'different'
+          ? 'its checkout’s copy of the stub differs from the board’s'
+          : 'its checkout has no copy of the stub',
+      fix: `Bring ${slug}’s copy of the board’s files up to date (npx breakaway repos init ${slug} --update opens a pull request; in the board’s own repository, update the board to the same release), then paste the stub from the Agents view (Copy stub) as the routine’s instructions.`,
+    });
+  return out;
+}
+
+/** The first 16 hex digits of the sha-256 of `text`, with Web Crypto (the Worker and Node alike). */
+export async function shortHash(text) {
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+  return [...new Uint8Array(digest)]
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('')
+    .slice(0, 16);
+}