@futurelastic/colab-handbook 1.19.1-rc.1 → 1.20.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.19.1-rc.1"
36
+ "version": "1.20.0-rc.1"
37
37
  }
@@ -85,6 +85,7 @@ header naming its new home ([`docs/compat-surfaces.md`](../docs/compat-surfaces.
85
85
  |---|---|---|
86
86
  | `ci-node.yml`, `ci-python.yml`, `ci-laravel.yml` (with the #625 `Migration round-trip` job), `ci-*-heavy.yml` | your forge's CI; `colab ship` / `promote` read or dispatch the runs; `colab template --roundtrip` writes the round-trip job | the adopter's CI layer; until it ships (#608), an optional starting file here |
87
87
  | `release-tag.yml`, `release-auto.yml` | your forge's CI; `release-auto.yml` runs `colab release cut` / `finalize --auto` | the release commands' new home (#608); an optional starting file here until then |
88
+ | `forgejo-release-auto.yml` | a Forgejo repo's CI; runs `colab release cut --auto` | the owner's #681 exception to #608 item 10 for Forgejo; an optional starting file here |
88
89
  | `dist-refs.yml`, `npx-launcher.mjs`, `npx-service.mjs` | your own release workflow and package `bin` | stays here, as an optional starting file |
89
90
  | `publish-downloads.yml`, `publish-downloads.mjs` | your own release workflow, as its last job | stays here, as an optional starting file |
90
91
  | `deploy-xserver.yml`, `deploy-container.yml`, `deploy-container-run.mjs`, `deploy-adapter-portainer.mjs` | your repo's deploy workflow | the adopter's deploy tooling; here as an optional starting file |
@@ -107,6 +108,7 @@ check that reads one of these files is that tool's behaviour, documented with th
107
108
  | `ci-python.yml` | `.github/workflows/ci.yml` | Python: FastAPI/Flask services, CLIs, libraries | Resolves Python from `project.yml` → `.python-version`/`requires-python` → **fails**. `requirements.txt` does not count. **Hybrid** Python+Node repo: copy this, then paste `ci-node.yml`'s `build:` job alongside — see the template header. Opt-in `Migration round-trip` job, as in `ci-node.yml`. |
108
109
  | `release-tag.yml` | `.github/workflows/release.yml` | Any repo cutting `v*.*.*` releases | Triggers on tag push. Publishes a grouped GitHub Release — a `-rc.N` tag as a pre-release, every summary since the previous *final* tag. No toolchain, no deploy; its header shows the `!v*.*.*-*` exclusion a deploy trigger needs. |
109
110
  | `release-auto.yml` | `.github/workflows/release-auto.yml` | A repo whose release tags land on `main` (`trunk: main`, `deploy: tag` or `none`) and whose §6 release route cuts candidates | Runs `colab release cut --auto` after CI goes green on main — at the sha that CI run tested (`--sha`, #622), even once main has moved on — and `colab release finalize --auto` daily — plus an hourly run that re-tries only a refused cut, once the fetched CLI has moved within `RETRY_WINDOW_MINUTES` or a run at main's head was cancelled (#547) — from a handbook ref (`HANDBOOK_REF` — the `stable` channel by default, `next` for the fast channel, or an exact tag to freeze; #445) — the handbook's own copy runs its checkout's CLI instead, since it ships the CLI it releases with (#428). **Publishes the Release in the same run** — a tag pushed with `GITHUB_TOKEN` triggers no other workflow, so `release-tag.yml` would never fire for it. A refusal is a warning, not a red run. Reads and creates tags, and fast-forwards the release channels `next` / `stable` (branches naming the newest candidate / final, #445); never pushes a commit. The audit recognises any workflow running `release cut/finalize --auto` and warns when the route leaves candidates off, when it tags without publishing while a tag-push workflow waits, or when it commits. |
111
+ | `forgejo-release-auto.yml` | `.forgejo/workflows/release-auto.yml` | A repo hosted on **Forgejo** (or Gitea) whose §6 release route cuts candidates, with the forge named in the machine config's `forges` (#678) | The Forgejo dialect of `release-auto.yml` (#681). It has no `workflow_run`: the job you append to your CI (in its header) dispatches it when CI ends green, with `source=ci-completed` and the sha it tested. It waits for CI at that sha (`colab ci-wait`), then runs `colab release cut --auto --sha`, which tags the candidate and publishes its pre-release through the forge's API. No `permissions:` blocks, full-URL `uses:`, the runner label from the `RELEASE_RUNNER` variable, verdicts printed to the log (Forgejo drops the step summary), no `jq`. A refusal stays green. No verdict is a red run. **No finalize step**: on a forge a final is a human's `release finalize` under the human bar, which also publishes the final's release, so no tag-push workflow is needed. Keep its `name:` equal to the file's base name, because the CLI drops its own statuses by that name. |
110
112
  | `dist-refs.yml` | `.github/workflows/dist-refs.yml` | A **private** repo shipping a **compiled** tool, installed as `npx github:<org>/<repo>#vX.Y.Z` ([CONVENTIONS §6, *Distribution*](../CONVENTIONS.md#distribution--one-install-surface-npx-442)) | `workflow_call`, called from the same run that cut the release tag (a tag pushed with `GITHUB_TOKEN` triggers nothing else). Takes one build artifact per `<os>-<arch>` and pushes each as an orphan commit at `refs/tags/dist/vX.Y.Z/<os>-<arch>` with a `SHA256SUMS`. Refuses a public or unreadable repository (a public compiled tool ships npm platform packages instead), a version that is not an existing tag, and a missing platform — before pushing any. Never moves a dist ref that exists. |
111
113
  | `npx-launcher.mjs` | anywhere in-repo (e.g. `bin/launch.mjs`), named by the root `package.json`'s `bin` | Pairs with `dist-refs.yml` | Node ≥ 18, zero dependencies, needs `git`. Reads the `#vX.Y.Z` npx installed, fetches that one dist ref with the same URL and credentials npx cloned with, verifies `SHA256SUMS`, installs to a stable per-user path (`$XDG_DATA_HOME`/`%LOCALAPPDATA%`), and execs it; `--print-path` prints that path. A **channel** committish (`#stable`, `#next`, #465) is resolved to the release tag on the commit npx installed, then installed as that version; any other branch is refused. Also the library `npx-service.mjs` imports. `*.mjs`, so `colab template npx-launcher.mjs --dest <path>` copies it stamped, `--dest` required. One edit point: `BIN` (defaults to the package name without its scope). |
112
114
  | `npx-service.mjs` | the same directory as your `npx-launcher.mjs` copy (e.g. `bin/service.mjs`), named by the root `package.json`'s `bin` | A tool that runs as a **per-machine service** (a dashboard, a daemon, a JS app a launch agent serves), installed with npx ([CONVENTIONS §6, *Services over npx*](../CONVENTIONS.md#services-over-npx--init-update-rollback-465)) | `npx github:<org>/<repo>#vX.Y.Z init [--auto-update 6h \| --no-auto-update]`, then `<tool> update [--check] [--version vX.Y.Z] [--channel next\|stable]`, `<tool> rollback`, `<tool> status`, `<tool> uninstall [--purge]` (#472: unit, timer, shim and every version go; config and state stay unless `--purge`); anything else runs the current version's payload. Versions side by side under `$XDG_DATA_HOME/<tool>/` with `current`/`previous` links the unit and the `~/.local/bin` shim go through; update installs beside, switches, restarts, health-checks, and **switches back** on failure. Config/secrets under `$XDG_CONFIG_HOME/<tool>/`, state and logs under `$XDG_STATE_HOME/<tool>/` — the unit carries their locations, never a value. launchd agent on macOS, systemd user unit on Linux, Windows refused; `<TOOL>_SERVICE_MANAGER=none` skips the manager. `--auto-update` (#471) adds a timer (launchd `StartInterval` agent / systemd user `.timer`) that runs the same `update`. Node ≥ 18, zero dependencies; needs `git`, `npm` for `update`, `tar` for `dist`. **Imports `./npx-launcher.mjs`** — copy both, or edit the import. Edit points: `KIND` (`binary` = a compiled tool from dist refs, `package` = a JS app run with node, `dist` = a prebuilt JS app unpacked from one verified tarball in the `dist/vX.Y.Z/any` ref, #470), `LABEL`, `SERVICE_ARGS`, `ENTRY`, `DIST_FILE`, `HEALTH_URL`, `KEEP`, `AUTO_UPDATE`, `VERBS`. The package's `files` must include both copies (and a `package` app's built output). `colab template npx-service.mjs --dest <path>`, `--dest` required. |
@@ -0,0 +1,220 @@
1
+ # Release (auto), Forgejo dialect — TEMPLATE (#681). Copy me into your repo at
2
+ # .forgejo/workflows/release-auto.yml.
3
+ #
4
+ # This is a starting point, not a dependency. Once you copy it, YOU OWN THIS FILE.
5
+ # Edit it freely; nothing calls it remotely and nothing will update it for you.
6
+ #
7
+ # EDIT POINTS are marked `# EDIT:` — walk them once after copying.
8
+ #
9
+ # WHAT IT DOES. The candidate half of CONVENTIONS.md §6's release rung, on a repo hosted on Forgejo
10
+ # (or Gitea): a green CI run on main cuts the next candidate `vX.Y.Z-rc.N`, pushes the tag and
11
+ # publishes its pre-release on the forge.
12
+ #
13
+ # trigger step
14
+ # ---------------------------------------------- ---------------------------------------------
15
+ # your CI workflow finished green on main and colab ci-wait --sha <sha>, then
16
+ # dispatched this one (source=ci-completed) colab release cut --auto --sha <sha>
17
+ # a daily schedule colab ci-wait, then colab release cut --auto
18
+ # at main's head (a head a missed dispatch
19
+ # left uncut)
20
+ #
21
+ # THE FINAL IS A HUMAN ACT ON A FORGE. There is no finalize step here: an automatic final leans on
22
+ # the release tracking issue, and the handbook writes no issue on a forge (#678). A human finalizes:
23
+ # COLAB_HUMAN=1 colab release finalize --tag vX.Y.Z-rc.N --answered-by <name>
24
+ # which tags the final and publishes its release object itself, so no separate tag-push workflow
25
+ # (the GitHub `release-tag.yml`) is needed here. A route that tags finals on its own
26
+ # (`release.route: deploy-tag-fast` / `library-fast`) is refused on a forge for the same reason.
27
+ #
28
+ # HOW IT DIFFERS FROM templates/release-auto.yml (the GitHub workflow), and why:
29
+ # - no `workflow_run` — Forgejo has none. Your CI dispatches this workflow when it ends green
30
+ # (the job to add is below, CI DISPATCH), with `source=ci-completed` and the sha it tested.
31
+ # - no `permissions:` blocks — Forgejo does not read them. The token is a secret you set
32
+ # (RELEASE_TOKEN), falling back to the job's own token.
33
+ # - full-URL `uses:` — a bare `actions/checkout` resolves against the instance's default action
34
+ # host, which differs between instances; the URL says which one.
35
+ # - the runner label comes from an Actions variable (RELEASE_RUNNER), not a literal.
36
+ # - verdicts are printed to the log — Forgejo drops `$GITHUB_STEP_SUMMARY`.
37
+ # - no `jq`: the verdict JSON is read with node, which the CLI needs anyway.
38
+ #
39
+ # THE CLI IGNORES THIS WORKFLOW'S OWN STATUSES when it reads CI at a commit (#425, #681): on a
40
+ # Forgejo runner a status context reads `<workflow> / <job> (<event>)`, and the CLI drops the ones
41
+ # whose `<workflow>` is this file's — by its path or its base name. So keep `name:` below equal to
42
+ # this file's base name (`release-auto` for release-auto.yml), and never fold these steps into the
43
+ # workflow that runs your test suite: that suite's statuses would be ignored with it.
44
+ #
45
+ # A REFUSAL IS NOT A FAILURE. `colab release cut --auto` refusing (nothing owed, a check failed) is
46
+ # the ordinary output of most runs: it is printed as a warning and the job stays green, because a
47
+ # red run at main's head reads as "main not green" to `colab ship`. A FAILED CLI STEP FAILS THE
48
+ # JOB: no verdict at all (a crash, bad flags, a CLI too old for Forgejo) is a red run, and a missing
49
+ # verdict is never read as "no candidate cut". CI that is red at the sha is not a candidate (exit 0,
50
+ # said so); CI still running when the wait's deadline passes is a warning — the next run cuts it.
51
+ #
52
+ # WHAT THE MACHINE CONFIG SAYS. The CLI knows a remote is Forgejo from `forges` in its machine
53
+ # config ($COLAB_HOME/config.json, never a tracked file). This workflow writes one for the run,
54
+ # naming this instance (github.server_url) — nothing to edit.
55
+ #
56
+ # CI DISPATCH — add this job to the END of your CI workflow (.forgejo/workflows/ci.yml):
57
+ #
58
+ # release-dispatch:
59
+ # needs: [test] # EDIT: every other job of your CI workflow
60
+ # if: github.event_name == 'push' && github.ref == 'refs/heads/main'
61
+ # runs-on: ${{ vars.RELEASE_RUNNER || 'docker' }}
62
+ # steps:
63
+ # - name: Dispatch the release workflow at this sha
64
+ # env:
65
+ # TOKEN: ${{ secrets.RELEASE_TOKEN || github.token }}
66
+ # URL: ${{ github.server_url }}/api/v1/repos/${{ github.repository }}/actions/workflows/release-auto.yml/dispatches
67
+ # SHA: ${{ github.sha }}
68
+ # run: |
69
+ # node -e '
70
+ # const body = { ref: "main", inputs: { source: "ci-completed", sha: process.env.SHA } };
71
+ # fetch(process.env.URL, { method: "POST", body: JSON.stringify(body),
72
+ # headers: { authorization: "token " + process.env.TOKEN, "content-type": "application/json" } })
73
+ # .then(async (r) => { if (r.status >= 300) { console.error(r.status, await r.text()); process.exit(1); } });'
74
+ #
75
+ # It runs only after every other CI job passed (`needs:`), so a red CI run dispatches nothing. Its
76
+ # own status (`CI / release-dispatch (push)`) is part of CI: the release run's `ci-wait` waits for
77
+ # it, and it finishes seconds after the dispatch.
78
+ #
79
+ # SECRETS AND VARIABLES (repository or organisation settings → Actions):
80
+ # RELEASE_TOKEN secret, recommended — a token that may push tags, create releases and dispatch
81
+ # workflows on this repo (write:repository). Without it the job's own token is
82
+ # used, which some instances do not let create releases or dispatch.
83
+ # RELEASE_RUNNER variable, optional — the runner label (default `docker`).
84
+ #
85
+ # The tag this run pushes starts no other workflow (a tag pushed with an Actions token never does),
86
+ # which is why the cut publishes the pre-release itself.
87
+
88
+ name: release-auto
89
+
90
+ on:
91
+ workflow_dispatch:
92
+ inputs:
93
+ source:
94
+ description: "Who dispatched this run: ci-completed (your CI, at the sha it tested) or manual"
95
+ required: false
96
+ default: "manual"
97
+ type: string
98
+ sha:
99
+ description: "The main commit CI tested (ci-completed sets it); empty = main's head"
100
+ required: false
101
+ default: ""
102
+ type: string
103
+ dry_run:
104
+ description: "Dry run: decide everything, write nothing (no tag, no release)"
105
+ required: false
106
+ default: false
107
+ type: boolean
108
+ schedule:
109
+ # EDIT: when the daily catch-up cut runs (UTC). Off the hour on purpose.
110
+ - cron: "17 3 * * *"
111
+
112
+ env:
113
+ # EDIT: the handbook ref whose colab CLI makes the release decisions — `stable` (the newest final),
114
+ # `next` (the newest candidate) or an exact vX.Y.Z. It must carry #681 (Forgejo support): the
115
+ # "Fetch the colab CLI" step refuses an older CLI rather than letting it refuse every cut.
116
+ HANDBOOK_REF: "stable"
117
+ HANDBOOK_REPO: "https://github.com/futurelastic/colab-handbook.git"
118
+ # EDIT: how long the run waits for CI at the sha to finish before giving up for this run.
119
+ CI_WAIT_TIMEOUT: "30m"
120
+
121
+ jobs:
122
+ release:
123
+ name: Cut a candidate
124
+ runs-on: ${{ vars.RELEASE_RUNNER || 'docker' }}
125
+ env:
126
+ FORGEJO_TOKEN: ${{ secrets.RELEASE_TOKEN || github.token }}
127
+ SOURCE: ${{ inputs.source || github.event_name }}
128
+ RUN_SHA: ${{ inputs.sha }}
129
+ # A dispatch on any ref other than main is dry whether or not dry_run is set.
130
+ DRY_RUN: ${{ github.event_name == 'workflow_dispatch' && (inputs.dry_run || github.ref_name != 'main') }}
131
+ steps:
132
+ - uses: https://code.forgejo.org/actions/checkout@v4
133
+ with:
134
+ ref: main # EDIT: your trunk, if it is not main
135
+ # Full history plus tags: versions, bumps and "previous final" are read from git, and the
136
+ # on-trunk check refuses a shallow checkout outright.
137
+ fetch-depth: 0
138
+ # `colab release cut` pushes its tag over the checkout's origin with this token.
139
+ token: ${{ secrets.RELEASE_TOKEN || github.token }}
140
+
141
+ - name: Fetch the colab CLI
142
+ run: |
143
+ set -eu
144
+ rm -rf "$RUNNER_TEMP/colab-handbook"
145
+ git clone --quiet --depth 1 --branch "$HANDBOOK_REF" "$HANDBOOK_REPO" "$RUNNER_TEMP/colab-handbook"
146
+ COLAB="$RUNNER_TEMP/colab-handbook/tools/colab"
147
+ # A CLI older than #681 reads every Forgejo cut as "gh not usable" and refuses it forever.
148
+ if ! node "$COLAB" release cut --help | grep -q 'On a Forgejo remote'; then
149
+ echo "::error::HANDBOOK_REF \"$HANDBOOK_REF\" carries a colab CLI without Forgejo release support (#681) — set HANDBOOK_REF to a ref that has it"
150
+ exit 1
151
+ fi
152
+ echo "COLAB=$COLAB" >> "$GITHUB_ENV"
153
+ # The machine config naming this instance as a Forgejo forge (tools/lib/tracker.js engineFor).
154
+ COLAB_HOME="$RUNNER_TEMP/colab-home"
155
+ mkdir -p "$COLAB_HOME"
156
+ SERVER="${{ github.server_url }}" node -e '
157
+ const u = new URL(process.env.SERVER);
158
+ const api = process.env.SERVER.replace(/\/+$/, "") + "/api/v1";
159
+ require("fs").writeFileSync(process.argv[1], JSON.stringify({ forges: { [u.hostname]: { engine: "forgejo", api, tokenEnv: "FORGEJO_TOKEN" } } }));
160
+ ' "$COLAB_HOME/config.json"
161
+ echo "COLAB_HOME=$COLAB_HOME" >> "$GITHUB_ENV"
162
+ # The tags are annotated; git needs an identity to write one.
163
+ git config user.name "forgejo-actions"
164
+ git config user.email "forgejo-actions@noreply.invalid"
165
+
166
+ - name: Wait for CI at the sha (colab ci-wait)
167
+ id: wait
168
+ run: |
169
+ set -u
170
+ SHA="${RUN_SHA:-}"
171
+ [ -n "$SHA" ] || SHA="$(git rev-parse origin/main)"
172
+ echo "sha=$SHA" >> "$GITHUB_OUTPUT"
173
+ echo "release-auto ($SOURCE): waiting for CI at $SHA"
174
+ rc=0
175
+ node "$COLAB" ci-wait --sha "$SHA" --timeout "$CI_WAIT_TIMEOUT" || rc=$?
176
+ case "$rc" in
177
+ 0) echo "cut=true" >> "$GITHUB_OUTPUT" ;;
178
+ 1) echo "cut=false" >> "$GITHUB_OUTPUT"; echo "CI is red at $SHA — not a candidate, nothing to cut." ;;
179
+ 3) echo "cut=false" >> "$GITHUB_OUTPUT"; echo "::warning::CI at $SHA did not finish within $CI_WAIT_TIMEOUT — nothing cut this run; the next dispatch or the daily run cuts it." ;;
180
+ *) echo "::error::colab ci-wait gave no verdict (exit $rc) — the reason is in this step's log"; exit 1 ;;
181
+ esac
182
+
183
+ - name: Cut a candidate (colab release cut --auto)
184
+ if: steps.wait.outputs.cut == 'true'
185
+ env:
186
+ SHA: ${{ steps.wait.outputs.sha }}
187
+ run: |
188
+ set -u
189
+ OUT="$RUNNER_TEMP/cut.json"
190
+ DRY=""; [ "${DRY_RUN:-false}" = "true" ] && DRY="--dry"
191
+ rc=0
192
+ # The checkout sits on main's head; a release.guard-run reads the working tree, so it is
193
+ # detached at the sha being cut and restored afterwards.
194
+ HEAD="$(git rev-parse HEAD)"
195
+ [ "$HEAD" = "$SHA" ] || git checkout --quiet --detach "$SHA"
196
+ node "$COLAB" release cut --auto --sha "$SHA" $DRY --json > "$OUT" || rc=$?
197
+ [ "$HEAD" = "$SHA" ] || git checkout --quiet main
198
+ # A verdict is JSON carrying `ok`; anything else is a run that never decided — red.
199
+ node -e '
200
+ const fs = require("fs");
201
+ let v;
202
+ try { v = JSON.parse(fs.readFileSync(process.argv[1], "utf8")); } catch (_) { v = null; }
203
+ if (!v || typeof v !== "object" || !("ok" in v)) {
204
+ console.log("::error::colab release cut produced no verdict (exit " + process.argv[2] + ")");
205
+ process.stdout.write(fs.existsSync(process.argv[1]) ? fs.readFileSync(process.argv[1], "utf8") : "");
206
+ process.exit(1);
207
+ }
208
+ console.log("colab release cut --auto at " + v.sha);
209
+ for (const c of v.checks || []) console.log(" " + (c.checked === false ? "·" : c.ok ? "✓" : "✗") + " " + c.condition + " — " + c.detail);
210
+ const fail = (v.checks || []).filter((c) => c.ok === false && c.checked !== false).map((c) => c.condition + " — " + c.detail).join("; ");
211
+ if (process.env.DRY_RUN === "true") console.log("Dry run — would cut: " + (v.tag || "nothing"));
212
+ else if (v.created) {
213
+ console.log("Cut " + v.tag + " and pushed it.");
214
+ if (v.published && !v.published.ok) console.log("::warning::" + v.published.detail);
215
+ else if (v.published) console.log(v.published.detail);
216
+ } else if (v.noop) console.log("No-op: nothing owed, or a later commit already carries a candidate.");
217
+ else if (v.ok) console.log("Verdict ok but nothing created.");
218
+ else if ((v.standing || []).length) console.log("::error title=Release stalled::colab release cut refused on a condition that does not clear by itself (" + v.standing.join(", ") + "): " + fail);
219
+ else console.log("::warning::colab release cut refused: " + fail);
220
+ ' "$OUT" "$rc"