breakaway 1.4.0-main.55 → 1.4.0-main.56

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakaway",
-  "version": "1.4.0-main.55",
+  "version": "1.4.0-main.56",
   "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/prompts/install.md

@@ -82,7 +82,7 @@ gh run list --repo <owner>/<name> --workflow deploy.yml --limit 1   # it takes a
 gh run watch <run ID> --repo <owner>/<name> --exit-status
 ```
 
-When the dry run passes, run it again without `-f dry-run=true` and watch it the same way. It stops with a message when something needs their hands: read the run's log (`gh run view <run ID> --repo <owner>/<name> --log-failed`) and say what it asks for.
+When the dry run passes, run it again without `-f dry-run=true` and watch it the same way. On an address on their own domain, this first deploy can wait up to five minutes for its certificate, and can end with a notice that the board is waiting for its secrets: that's expected, they go on next. It stops with a message when something needs their hands: read the run's log (`gh run view <run ID> --repo <owner>/<name> --log-failed`) and say what it asks for.
 
 Then put the three secrets on the Worker. Each command reads its value from `tasks.env` and pipes it to Wrangler, so it never shows:
 

package/scripts/install/cli.js

@@ -13,9 +13,10 @@ import {
   bumpBody,
   deployPlan,
   deployTarget,
-  isHealthy,
   latestReleases,
+  newWorkerStop,
   parseState,
+  pingHealth,
   previousVersionId,
   shapeOf,
   updatePlan,
@@ -152,6 +153,15 @@ export async function runStep(step, opts, io) {
         `Couldn't list the Worker's deployments, so the deploy stopped before changing anything. Check that CLOUDFLARE_ACCOUNT_ID is your account's ID and that CLOUDFLARE_API_TOKEN can read Workers on it. Wrangler said:\n${output.trim()}`,
       );
     }
+    // A Worker that doesn't exist on an install that already has a board is a changed or mistyped name, not a first
+    // deploy (BRK-141): a dispatch has no earlier config for `check` to compare with.
+    const stop = newWorkerStop({
+      worker: configIn(join(dir, 'breakaway.config.json')).worker,
+      variable: opts.variable || null,
+      running: opts.running || null,
+      at: opts.at || null,
+    });
+    if (stop) throw new Stop(stop, 2);
     io.out('first=true');
     return 0;
   }
@@ -163,7 +173,12 @@ export async function runStep(step, opts, io) {
     } catch {
       ping = null;
     }
-    return isHealthy(ping, opts.version) ? 0 : 1;
+    // A first deploy answers before its secrets are on (the install puts them on the Worker it made), so there it
+    // passes and says so; any later deploy needs them (BRK-141).
+    const health = pingHealth(ping, opts.version);
+    const first = opts.first === true || opts.first === 'true';
+    io.out(`health=${health}`);
+    return health === 'healthy' || (first && health === 'secrets') ? 0 : 1;
   }
   if (step === 'update') {
     const state = stateIn(dir);

package/scripts/install/lib.js

@@ -253,9 +253,34 @@ export function workerMissing(output) {
   return /\[code: 10007\]|worker does not exist on your account/iu.test(String(output ?? ''));
 }
 
+/**
+ * The message that stops a deploy about to make a new Worker on an install that already has a board (BRK-141), or null
+ * when making one is a first deploy. A board is there when the repository variable BREAKAWAY_URL is set (`variable`: the
+ * install sets it once the board answers) or the address the deploy checked (`at`) answered /api/ping with a release
+ * (`running`). A new Worker then means the name changed or is mistyped, and deploying it would open a second, empty board.
+ * @param {{ worker: string, variable?: string | null, running?: string | null, at?: string | null }} options
+ */
+export function newWorkerStop({ worker, variable = null, running = null, at = null }) {
+  if (!variable && !running) return null;
+  const seen = running
+    ? `${at || variable || 'its address'} answers as breakaway ${running}`
+    : `the repository variable BREAKAWAY_URL is set (${variable})`;
+  return `There is no Worker named ${worker} on this Cloudflare account, but this install already has a board: ${seen}. Deploying would make a new Worker with an empty board, so nothing was deployed. Put "worker" in breakaway.config.json back to the name the board runs as (Workers & Pages on Cloudflare lists it), then run Deploy again. If that board is gone and you mean to start an empty one, delete the repository variable BREAKAWAY_URL, then run Deploy again.`;
+}
+
+/**
+ * What `/api/ping`'s answer says about the new release: `healthy` when it runs and its secrets load (BRK-96), `secrets`
+ * when it runs but a bound secret can't be read yet, and `down` for anything else.
+ * @returns {'healthy' | 'secrets' | 'down'}
+ */
+export function pingHealth(ping, version) {
+  if (ping?.ok !== true || ping.release !== version) return 'down';
+  return ping.secrets?.ok === true ? 'healthy' : 'secrets';
+}
+
 /** Whether `/api/ping`'s answer says the new release is running and its secrets load (BRK-96). */
 export function isHealthy(ping, version) {
-  return Boolean(ping) && ping.ok === true && ping.release === version && ping.secrets?.ok === true;
+  return pingHealth(ping, version) === 'healthy';
 }
 
 /**

package/template/.github/workflows/deploy.yml

@@ -131,6 +131,10 @@ jobs:
           cat check.out
           if [ "$status" -ne 0 ]; then exit "$status"; fi
           cat check.out >> "$GITHUB_OUTPUT"
+          # Where the running board was asked, and what it said: a Worker that doesn't exist is only a first deploy when
+          # no board answered there (BRK-141).
+          echo "running=$running" >> "$GITHUB_OUTPUT"
+          echo "address=$address" >> "$GITHUB_OUTPUT"
 
       - name: Make the Worker config
         env:
@@ -149,15 +153,38 @@ jobs:
           fi
           node "$CLI" install config --bundle bundle --out wrangler.generated.json
 
+      - name: Find the Worker
+        id: worker
+        env:
+          CLI: ${{ steps.release.outputs.cli }}
+          VARIABLE: ${{ vars.BREAKAWAY_URL }}
+          RUNNING: ${{ steps.check.outputs.running }}
+          CHECKED: ${{ steps.check.outputs.address }}
+        run: |
+          set -euo pipefail
+          # The version the deploy replaces. Only a Worker that doesn't exist is a first deploy: any other failure to list
+          # (a wrong account ID, a token that can't read Workers) stops here, because deploying over a live Worker with
+          # nothing to roll back to is not safe. And a Worker that doesn't exist on an install that already has a board
+          # (BREAKAWAY_URL set, or the address answered) is a changed or mistyped name: that stops too, before the dry run,
+          # since deploying it would make a second, empty board (BRK-141).
+          if npx --yes wrangler@4 deployments list --json -c wrangler.generated.json > deployments.json 2> list-error.txt; then
+            node "$CLI" install previous < deployments.json >> "$GITHUB_OUTPUT"
+          else
+            cat deployments.json list-error.txt | node "$CLI" install missing --variable "$VARIABLE" --running "$RUNNING" --at "$CHECKED"
+            echo "previous=" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Dry run
         if: ${{ inputs.dry-run }}
         env:
           DEPLOY: ${{ steps.check.outputs.deploy }}
           CHANGES: ${{ steps.check.outputs.changes }}
+          PREVIOUS: ${{ steps.worker.outputs.previous }}
         run: |
           set -euo pipefail
           npx --yes wrangler@4 deploy --dry-run --outdir "$RUNNER_TEMP/dry" -c wrangler.generated.json
-          if [ "$DEPLOY" != wrangler ]; then echo "A deploy would upload a version."
+          if [ -z "$PREVIOUS" ]; then echo "This is the first deploy: it would make the Worker and its board."
+          elif [ "$DEPLOY" != wrangler ]; then echo "A deploy would upload a version."
           elif [ -n "$CHANGES" ]; then echo "A deploy would run wrangler deploy for $CHANGES."
           else echo "A deploy would run wrangler deploy, the release's manual step."; fi
 
@@ -170,19 +197,13 @@ jobs:
           DEPLOY: ${{ steps.check.outputs.deploy }}
           CHANGES: ${{ steps.check.outputs.changes }}
           ADDRESS_CHANGED: ${{ steps.check.outputs.address_changed }}
+          PREVIOUS: ${{ steps.worker.outputs.previous }}
         run: |
           set -euo pipefail
+          previous=$PREVIOUS
           wrangler() { npx --yes wrangler@4 "$@" -c wrangler.generated.json; }
-          # The Worker the new version replaces. A first run has none, and `wrangler deploy` makes the Worker and its
-          # Durable Object; every run after that uploads a version and deploys it, so it can be rolled back. Only a Worker
-          # that doesn't exist is a first run: any other failure to list (a wrong account ID, a token that can't read
-          # Workers) stops here, because deploying over a live Worker with nothing to roll back to is not safe.
-          if npx --yes wrangler@4 deployments list --json -c wrangler.generated.json > deployments.json 2> list-error.txt; then
-            previous=$(node "$CLI" install previous < deployments.json | sed 's/^previous=//')
-          else
-            cat deployments.json list-error.txt | node "$CLI" install missing > /dev/null
-            previous=""
-          fi
+          # The version the new one replaces (Find the Worker). A first run has none, and `wrangler deploy` makes the Worker
+          # and its Durable Object; every run after that uploads a version and deploys it, so it can be rolled back.
           if [ -z "$previous" ]; then
             wrangler deploy --var "BREAKAWAY_VERSION:$VERSION"
           elif [ "$DEPLOY" = wrangler ]; then
@@ -200,25 +221,36 @@ jobs:
           url=$(node -p "require('./breakaway.config.json').url || ''")
           address=${ADDRESS:-$url}
           tries=12
+          first=false
           if [ "$ADDRESS_CHANGED" = true ]; then
             # A new address: check it, not the old one, and give its custom domain five minutes for its certificate.
             address=${url:-$ADDRESS}
             tries=60
           fi
+          if [ -z "$previous" ]; then
+            # A first deploy: its custom domain is new too, and its secrets go on the Worker it just made, so a release that
+            # answers without them passes, saying so (BRK-141).
+            first=true
+            if [ -n "$url" ]; then address=$url; tries=60; fi
+          fi
           if [ -z "$address" ]; then
             echo "::warning title=Not checked::There is no address to check. Set the repository variable BREAKAWAY_URL to where the board answers (a workers.dev address, say) and the next deploy checks it."
             exit 0
           fi
           for attempt in $(seq 1 "$tries"); do
-            if curl -fsS --max-time 15 "$address/api/ping" | node "$CLI" install healthy --version "$VERSION"; then
-              echo "breakaway $VERSION is running at $address."
+            if health=$(curl -fsS --max-time 15 "$address/api/ping" | node "$CLI" install healthy --version "$VERSION" --first "$first"); then
+              if [ "$health" = health=secrets ]; then
+                echo "::notice title=Waiting for its secrets::breakaway $VERSION is running at $address, and is waiting for its secrets. Put them on the Worker (npx breakaway init-secrets, then .dev.vars.example says where each goes); the board works once they're on."
+              else
+                echo "breakaway $VERSION is running at $address."
+              fi
               exit 0
             fi
             sleep 5
           done
           waited=$([ "$tries" -gt 12 ] && echo "five minutes" || echo "a minute")
           if [ -z "$previous" ]; then
-            echo "::error title=Failed its check::breakaway $VERSION didn't answer $address/api/ping, with its secrets readable, within $waited, and this was the first deploy, so there is no version to go back to. Read the Worker's logs on Cloudflare."
+            echo "::error title=Failed its check::breakaway $VERSION didn't answer $address/api/ping within $waited, and this was the first deploy, so there is no version to go back to. A new custom domain can take longer for its certificate: once $address/api/ping answers, the board is up, and its secrets go on next. If it never answers, read the Worker's logs on Cloudflare."
           elif wrangler rollback "$previous" --message "breakaway $VERSION failed its check" --yes; then
             kept=""
             if [ "$DEPLOY" = wrangler ]; then kept=" Rolling back brings back the code only: what wrangler deploy changed${CHANGES:+ ($CHANGES)} stays as it left it."; fi

package/template/README.md

@@ -30,6 +30,8 @@ The board answers at {{address}}.
 
 Both workflows run breakaway's CLI from the release's own source on GitHub, with Node. Apart from `wrangler`, nothing comes from npm.
 
+If Deploy stops with "There is no Worker named …, but this install already has a board", it changed nothing: `worker` in `breakaway.config.json` isn't the name the board runs as, and deploying it would make a second, empty board. Put the name back. Only if that board is gone and you want an empty one, delete the repository variable `BREAKAWAY_URL`, then run Deploy again.
+
 If Deploy stops with "Couldn't list the Worker's deployments", it changed nothing: only a Worker that doesn't exist yet counts as a first deploy. Check that `CLOUDFLARE_ACCOUNT_ID` is your account's ID (32 hex characters) and that `CLOUDFLARE_API_TOKEN` can read and edit Workers on it, then run Deploy again.
 
 A release can need steps by hand (a Durable Object class deleted or renamed, say). The workflow stops with those steps in its message and deploys nothing; do them, then deploy with `wrangler`. A release whose only step is `wrangler deploy` says so in its notes, and Deploy runs it itself when it may ([below](#which-token-does-what)). The same goes for a new address in `breakaway.config.json`, which a version upload can't carry: without that, apply it yourself (`npx breakaway install config` makes the Worker config), then run Deploy again.