breakaway 1.4.0-main.22 → 1.4.0-main.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakaway",
-  "version": "1.4.0-main.22",
+  "version": "1.4.0-main.24",
   "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/pipeline.js

@@ -615,6 +615,167 @@ export function runScripts(text) {
   );
 }
 
+// ---- repos init --pipeline -----------------------------------------------------------------
+
+/** Where the minimal CI goes in a repository that has no workflow yet, and the line it starts with. */
+export const CI_PATH = '.github/workflows/ci.yml';
+export const CI_HEADER =
+  'Added by npx breakaway repos init --pipeline, because this repository had no workflow: the checks Deploy and Release wait for.';
+/**
+ * The starter deploy paths: every file but the docs and the board's own, so the first deploys don't miss a change.
+ * The owner narrows it to the Worker's code.
+ */
+export const STARTER_PATHS = '^(?!docs/|tools/tasks/|\\.agents/|\\.claude/|\\.github/|[^/]+\\.md$)';
+/** The workflow names the rendered files take, never a check of their own. */
+const RENDERED_NAMES = new Set(['Deploy', 'Promote', 'Roll back', 'Release']);
+/** npm's placeholder test script, which fails: a package.json with it has no tests yet. */
+const NO_TEST = /no test specified/u;
+
+/** How the repository installs and runs a script, from its lockfile. */
+function managerOf(readTarget) {
+  if (readTarget('pnpm-lock.yaml') !== null)
+    return { install: 'corepack pnpm install --frozen-lockfile', run: 'corepack pnpm run' };
+  if (readTarget('yarn.lock') !== null) return { install: 'yarn install --frozen-lockfile', run: 'yarn run' };
+  if (readTarget('package-lock.json') !== null) return { install: 'npm ci', run: 'npm run' };
+  return { install: 'npm install', run: 'npm run' };
+}
+
+/** A workflow's `name:` when it runs on a push, which is what a check has to do to gate a deploy; else null. */
+function pushCheckName(text) {
+  let doc;
+  try {
+    doc = parseYaml(text);
+  } catch {
+    return null;
+  }
+  const on = doc?.on;
+  const push =
+    typeof on === 'string' ? on === 'push' : Array.isArray(on) ? on.includes('push') : isObject(on) && 'push' in on;
+  return push && typeof doc.name === 'string' && doc.name.trim() ? doc.name.trim() : null;
+}
+
+/**
+ * What `repos init <slug> --pipeline` and `--package` add (BRK-91, docs/specs/IDEA-27-move-ci-cd-to-the-deploy-flow.md,
+ * section 4): a starter `.github/breakaway-pipeline.json`, the files it renders, and, when the repository has no
+ * workflow at all, a minimal CI for them to wait for. All of it is new files: a repository that already has the
+ * config or a file it would render gets nothing from here, and is told to use `pipeline init`.
+ *
+ * `workers` is the staging and production Worker for the deploy flow (null for none); `withPackage` asks for the
+ * release flow of the package that package.json names, which it gets only when package.json is there and isn't
+ * private. `readTarget(path)` reads the repository (null when the file isn't there), `workflows` are its workflow
+ * files, and `readTemplate(name)` gives template/pipeline/<name>.
+ * @param {{
+ *   branch?: string,
+ *   workers?: { staging: string, production: string } | null,
+ *   withPackage?: boolean,
+ *   readTarget: (path: string) => string | null,
+ *   workflows?: Array<{ path: string, text: string }>,
+ *   readTemplate: (name: string) => string,
+ * }} input
+ * @returns {{ files: Array<{ path: string, content: string }>, notes: string[], todo: string[] }}
+ */
+export function starterPlan({
+  branch = 'main',
+  workers = null,
+  withPackage = false,
+  readTarget,
+  workflows = [],
+  readTemplate,
+}) {
+  const notes = [];
+  const todo = [];
+  const none = (note) => ({ files: [], notes: [...notes, note], todo: [] });
+  if (readTarget(CONFIG_PATH) !== null)
+    return none(
+      `${CONFIG_PATH} is already there, so --pipeline added nothing: run npx breakaway pipeline init in its checkout to render it.`,
+    );
+
+  let json = null;
+  try {
+    json = JSON.parse(readTarget('package.json') ?? 'null');
+  } catch {
+    /* said below, when it matters */
+  }
+  const scripts = isObject(json?.scripts) ? json.scripts : {};
+  let pkg = null;
+  if (withPackage) {
+    if (!isObject(json)) notes.push('There is no package.json to release, so there is no release flow.');
+    else if (json.private === true)
+      notes.push('package.json says "private": true, so npm won\'t take it: there is no release flow.');
+    else {
+      const name = typeof json.name === 'string' ? json.name : '';
+      const access = json.publishConfig?.access ?? (name.startsWith('@') ? 'restricted' : 'public');
+      pkg = { name, directory: '.', access };
+      try {
+        checkConfig({ checks: ['CI'], package: pkg }, { packageJson: () => json });
+      } catch (error) {
+        if (!(error instanceof PipelineError)) throw error;
+        notes.push(`No release flow: ${error.message}`);
+        pkg = null;
+      }
+    }
+  }
+  if (!workers && !pkg) return { files: [], notes, todo };
+
+  const checks = workflows.length
+    ? [...new Set(workflows.map((w) => pushCheckName(w.text)).filter((n) => n && !RENDERED_NAMES.has(n)))]
+    : ['CI'];
+  if (!checks.length)
+    return none(
+      `None of ${workflows.map((w) => w.path).join(', ')} runs on a push, so nothing would gate a deploy: add a check workflow that does, then run npx breakaway pipeline init in its checkout.`,
+    );
+
+  const manager = managerOf(readTarget);
+  const raw = {
+    ...(workers ? { workers } : {}),
+    ...(branch === 'main' ? {} : { branch }),
+    checks,
+    install: manager.install,
+    ...(typeof scripts.build === 'string' ? { build: `${manager.run} build` } : {}),
+    ...(workers ? { deployPaths: { [workers.production]: STARTER_PATHS } } : {}),
+    ...(pkg ? { package: pkg } : {}),
+  };
+  const config = checkConfig(raw, { packageJson: () => json });
+  const rendered = renderPipeline(config, readTemplate);
+  const there = rendered.filter((f) => readTarget(f.path) !== null).map((f) => f.path);
+  if (there.length)
+    return none(
+      `${there.join(', ')} ${there.length > 1 ? 'are' : 'is'} already there, so --pipeline added nothing: move ${there.length > 1 ? 'them' : 'it'} into ${CONFIG_PATH} and run npx breakaway pipeline init in its checkout.`,
+    );
+
+  const files = [
+    { path: CONFIG_PATH, content: `${JSON.stringify(raw, null, 2)}\n` },
+    ...rendered.map((f) => ({ path: f.path, content: f.text })),
+  ];
+  if (!workflows.length) {
+    const test = typeof scripts.test === 'string' && !NO_TEST.test(scripts.test) ? [`${manager.run} test`] : [];
+    const values = { ...valuesOf(config), ciHeader: CI_HEADER, test };
+    files.push({ path: CI_PATH, content: fill(readTemplate('ci.yml'), values) });
+  } else
+    todo.push(
+      `${CONFIG_PATH}: check that checks (${checks.join(', ')}) names only the workflows that must pass before a deploy or a release, and that none of the existing workflows deploys or publishes too`,
+    );
+  for (const file of files.filter((f) => f.path.endsWith('.yml'))) {
+    const problems = lintWorkflow(file.content);
+    if (problems.length) throw new Error(`${file.path} renders with problems: ${problems.join('; ')}`);
+  }
+
+  if (workers) {
+    todo.push(
+      `${CONFIG_PATH}: narrow deployPaths to the files the Worker is built from, and add a healthCheck address and any beforeDeploy commands (migrations)`,
+      `Before merging (the merge itself runs Deploy once CI passes): create the Workers ${workers.staging} and ${workers.production} and a Cloudflare API token for each; make the GitHub environments staging and production, restricted to ${branch}, each with its token as CLOUDFLARE_API_TOKEN, and the repository variable CLOUDFLARE_ACCOUNT_ID; give the board's GitHub App Actions: read and write here`,
+    );
+  }
+  if (pkg)
+    todo.push(
+      `Before merging (the merge itself stages the first pre-release of ${pkg.name}): make the GitHub environment npm, restricted to ${branch}; on npmjs.com add a trusted publisher for release.yml and that environment (or put a granular NPM_TOKEN that can't bypass 2FA in it); after it, approve each staged version on npm with 2FA`,
+    );
+  todo.push(
+    `After merging: turn deploys on from the repository's GitHub page on the board (Turn on deploys), once the workflows are on ${branch}`,
+  );
+  return { files, notes, todo };
+}
+
 // ---- the command ---------------------------------------------------------------------------
 
 const TEMPLATES = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'template', 'pipeline');

package/scripts/tasks.mjs

@@ -21,6 +21,7 @@ import {
   lstatSync,
   mkdirSync,
   readFileSync,
+  readdirSync,
   renameSync,
   rmSync,
   symlinkSync,
@@ -245,6 +246,11 @@ Working
                          --never-share <text>; --defaults takes the default for the rest without asking
     --update             refresh the copied files (the CLI, core, skill, Taskwarrior files) in a pull request when they're
                          older than this checkout's; the repository's own (its prompt, AGENTS.md) are never touched
+    --pipeline           also add the deploy flow: .github/breakaway-pipeline.json for the Workers --staging <name> and
+                         --production <name> (asked in a terminal; default <slug>-staging and <slug>), what it renders,
+                         and a minimal CI when the repository has no workflow. Only new files: never one it already has
+    --package            also add the release flow for the npm package package.json names, with its publishConfig.access
+                         (none for a private package.json); with --pipeline, both flows
   repos setup <slug|owner/name>   the Add a repository wizard's steps for it: which are done, the one to do now, and
                          any fix; read only, so an agent helping the owner may run it (the board's /#/add-repo)
   repos remove <slug>    take one off the board (owner): its sync, webhooks, agents, and routines stop; its tasks
@@ -360,7 +366,10 @@ const FLAGS = new Set([
   'replace',
   'update',
   'defaults',
+  'package',
 ]);
+/** Flags only in repos init (BRK-91): --pipeline takes a file in repos modify, and is a flag there. */
+const INIT_FLAGS = new Set(['pipeline']);
 
 function parse(argv) {
   const positional = [];
@@ -373,7 +382,7 @@ function parse(argv) {
       continue;
     }
     const [name, inline] = arg.slice(2).split(/=(.*)/su);
-    if (FLAGS.has(name)) {
+    if (FLAGS.has(name) || (INIT_FLAGS.has(name) && positional[0] === 'repos' && positional[1] === 'init')) {
       opts[name] = true;
       continue;
     }
@@ -1810,6 +1819,11 @@ async function initRepo(slug) {
   const registry = await call('GET', 'repos');
   const repo = registry.repos.find((r) => r.slug === String(slug).toLowerCase());
   if (!repo) fail(unknownRepo(slug, registry.repos));
+  const flows = Boolean(opts.pipeline || opts.package);
+  if (flows && opts.update)
+    fail(
+      '--pipeline and --package add the deploy and release flows to a repository that has none. To refresh rendered ones, run npx breakaway pipeline init --update in its checkout.',
+    );
   const dir = resolve(opts.dir ?? join(dirname(REPO), repo.slug));
   const git = (...a) =>
     execFileSync('git', ['-C', dir, ...a], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
@@ -1881,6 +1895,36 @@ async function initRepo(slug) {
     update,
     ...promptSections(answers),
   });
+  // The deploy flow, the package's release flow, and a minimal CI (BRK-91): new files in the same commit.
+  let starter = { files: [] };
+  if (flows) {
+    const { PipelineError, starterPlan } = await import('./tasks/pipeline.js');
+    const workers = opts.pipeline ? await workerNames(repo.slug) : null;
+    const at = join(dir, '.github', 'workflows');
+    const workflows = existsSync(at)
+      ? readdirSync(at)
+          .filter((name) => /\.ya?ml$/u.test(name))
+          .map((name) => ({ path: `.github/workflows/${name}`, text: readFileSync(join(at, name), 'utf8') }))
+      : [];
+    // package.json as the commit leaves it: repos init adds one when the repository has none.
+    const planned = (path) => plan.files.find((f) => f.path === path && !f.link)?.content ?? readTarget(path);
+    try {
+      starter = starterPlan({
+        branch,
+        workers,
+        withPackage: Boolean(opts.package),
+        readTarget: planned,
+        workflows,
+        readTemplate: (name) => readFileSync(join(PKG, 'template', 'pipeline', name), 'utf8'),
+      });
+    } catch (e) {
+      if (!(e instanceof PipelineError)) throw e;
+      fail(e.message);
+    }
+    plan.files.push(...starter.files);
+    plan.notes.push(...starter.notes);
+    plan.todo.push(...starter.todo);
+  }
   const report = [
     `${repo.github} ${empty ? 'has no commits yet' : `has commits on ${branch}`}.`,
     ...(plan.files.length
@@ -1955,7 +1999,9 @@ async function initRepo(slug) {
       `git add failed in ${dir}: ${String(e.stderr || e.message).trim()}. Nothing was committed. Fix that, then run repos init again (it leaves what's there alone), or use git checkout ${repo.defaultBranch || 'main'} && git branch -D ${work} to start over.`,
     );
   }
-  const first = initCommitMessage(repo.slug);
+  const first = initCommitMessage(repo.slug, {
+    by: `npx breakaway repos init ${repo.slug}${opts.pipeline ? ' --pipeline' : ''}${opts.package ? ' --package' : ''}`,
+  });
   const title = update ? "Update the task board's agent files" : first.title;
   git(
     'commit',
@@ -1964,7 +2010,7 @@ async function initRepo(slug) {
     '-m',
     update
       ? `The board's core, skill, release helpers, and Taskwarrior files as they are in ${board ?? 'breakaway'} now, and the session hooks run through npx, so an old copy of the CLI is removed: run it as npx ${CLI_PACKAGE} (CLI version ${CLI_VERSION}). This repository's own files are unchanged. Updated by npx ${CLI_PACKAGE} repos init ${repo.slug} --update.`
-      : first.body,
+      : `${first.body}${starter.files.length ? ` It also adds the deploy and release flows, rendered from ${starter.files[0].path}.` : ''}`,
   );
   const pushed = spawnSync('git', ['-C', dir, 'push', '-u', 'origin', empty ? `HEAD:refs/heads/${branch}` : work], {
     stdio: 'inherit',
@@ -2009,6 +2055,28 @@ async function initRepo(slug) {
   console.log(['', ...next].join('\n'));
 }
 
+/**
+ * The staging and production Workers for repos init --pipeline (BRK-91): --staging and --production, else asked in a
+ * terminal, else `<slug>-staging` and `<slug>`.
+ */
+async function workerNames(slug) {
+  const names = { staging: opts.staging, production: opts.production };
+  const defaults = { staging: `${slug}-staging`, production: slug };
+  const ask = !opts.defaults && !opts['dry-run'] && !opts.json && process.stdin.isTTY;
+  const { createInterface } = ask ? await import('node:readline') : {};
+  for (const env of /** @type {const} */ (['staging', 'production'])) {
+    if (names[env] !== undefined) continue;
+    if (ask) {
+      console.log(`\nThe ${env} Worker's name (Enter for ${defaults[env]}):`);
+      names[env] = await askIn('> ', { input: process.stdin, output: process.stdout, createInterface }).catch((error) =>
+        fail(error.message),
+      );
+    }
+    names[env] = String(names[env] ?? '').trim() || defaults[env];
+  }
+  return { staging: String(names.staging), production: String(names.production) };
+}
+
 /**
  * The agent prompt's sections for repos init (CLD-196), flag → text: each from its flag (--checks, --never-share, …),
  * and in a terminal, the rest asked one by one, with Enter taking the default. Without a terminal, with --defaults,

package/src/cli-version.js

@@ -4,5 +4,5 @@
  * and how to update it. scripts/tasks/version.test.js fails when the copied files change and this doesn't:
  * so it lives in the board's package (CLD-135) and the CLI imports it from here.
  */
-export const CLI_VERSION = 69;
-export const CLI_FINGERPRINT = 'd7528500bc5e5a4c';
+export const CLI_VERSION = 70;
+export const CLI_FINGERPRINT = 'f3abfe0e5927ffed';

package/template/pipeline/ci.yml

@@ -0,0 +1,40 @@
+# {{ciHeader}}
+#
+# CI: install, build, and test every pull request and every push to {{branchName}}. Deploy and Release run only after
+# it passes on {{branchName}}, so a change that breaks it never ships. This file is the repository's own: change its
+# steps to taste, and if you rename it, change checks in .github/breakaway-pipeline.json to match.
+name: CI
+
+on:
+  push:
+    branches: [{{branch}}]
+  pull_request:
+
+permissions: {}
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    name: check
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 22
+
+      - name: Install, build, and test
+        run: |
+          set -euo pipefail
+          if grep -q '"packageManager"' package.json 2>/dev/null; then corepack enable; fi
+          {{@install}}
+          {{@build}}
+          {{@test}}