@futurelastic/colab-handbook 1.13.0-rc.32 → 1.13.0-rc.34
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 +1 -1
- package/templates/README.md +1 -1
- package/templates/ci-laravel.yml +14 -0
- package/templates/ci-node.yml +15 -1
- package/templates/ci-python.yml +15 -1
package/package.json
CHANGED
package/templates/README.md
CHANGED
|
@@ -20,7 +20,7 @@ Starting points you **copy into your own repo**. That is the entire model.
|
|
|
20
20
|
| `ci-laravel.yml` | `.github/workflows/ci.yml` | Laravel + Inertia + Vite fullstack (with route/type codegen) | Same resolution for **both** PHP and Node. Includes the sqlite bootstrap + explicit wayfinder step, and a `migrations` job that round-trips the schema (migrate → rollback → seed → migrate, schema compared) on the test engine **and** the deploy engine (a MariaDB/MySQL service container at production's version). Its data-dependent checks need `ROUNDTRIP_SEEDER` — see *Migration round-trip* below. |
|
|
21
21
|
| `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. |
|
|
22
22
|
| `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. |
|
|
23
|
-
| `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 and `colab release finalize --auto` daily, 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. |
|
|
23
|
+
| `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 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. |
|
|
24
24
|
| `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. |
|
|
25
25
|
| `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). |
|
|
26
26
|
| `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. |
|
package/templates/ci-laravel.yml
CHANGED
|
@@ -265,6 +265,7 @@ jobs:
|
|
|
265
265
|
# (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
|
|
266
266
|
# cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
|
|
267
267
|
# (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
|
|
268
|
+
# `ci-wait-factor` (#564) too (tools/lib/ci-profile.js parseFactor): absent, or a number >= 1.
|
|
268
269
|
# ---------------------------------------------------------------------------
|
|
269
270
|
- name: Descriptor check (.github/project.yml)
|
|
270
271
|
working-directory: ${{ github.workspace }}
|
|
@@ -296,6 +297,19 @@ jobs:
|
|
|
296
297
|
exit 1
|
|
297
298
|
fi ;;
|
|
298
299
|
esac
|
|
300
|
+
# ci-wait-factor (#559): a number >= 1 — a multiple of the repo's measured CI duration. No ceiling.
|
|
301
|
+
# Same reading as tools/lib/ci-profile.js parseFactor on the raw scalar the audit hands it.
|
|
302
|
+
f="$(field ci-wait-factor)"
|
|
303
|
+
case "$f" in
|
|
304
|
+
''|'~'|null) echo "ci-wait-factor: absent — ok (default 2)" ;;
|
|
305
|
+
*)
|
|
306
|
+
if printf '%s\n' "$f" | grep -Eq '^[0-9]+(\.[0-9]+)?$' && awk -v n="$f" 'BEGIN { exit !(n + 0 >= 1) }'; then
|
|
307
|
+
echo "ci-wait-factor: $f — ok"
|
|
308
|
+
else
|
|
309
|
+
echo "::error file=.github/project.yml::ci-wait-factor is '$f', expected a number >= 1 (a multiple of the measured CI duration; omit for 2). colab ship and colab ci-wait ignore any other value and use 2. See project.schema.md, ci-wait-factor."
|
|
310
|
+
exit 1
|
|
311
|
+
fi ;;
|
|
312
|
+
esac
|
|
299
313
|
# thresholds (#560): one level of `name: whole number`, each name known and at or above its
|
|
300
314
|
# floor (and, for a percent, at most 100) — the table in tools/lib/thresholds.js (SPEC),
|
|
301
315
|
# which a test holds this list to.
|
package/templates/ci-node.yml
CHANGED
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
#
|
|
15
15
|
# What it does:
|
|
16
16
|
# 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416;
|
|
17
|
-
# ship-batch-wait, #555).
|
|
17
|
+
# ship-batch-wait, #555; ci-wait-factor, #564).
|
|
18
18
|
# 1. Resolve the Node version from declared sources — never a hardcoded default.
|
|
19
19
|
# 2. Secret scan with gitleaks (pinned release binary, see note at the step).
|
|
20
20
|
# 3. Install dependencies with the package manager the lockfile implies.
|
|
@@ -260,6 +260,7 @@ jobs:
|
|
|
260
260
|
# (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
|
|
261
261
|
# cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
|
|
262
262
|
# (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
|
|
263
|
+
# `ci-wait-factor` (#564) too (tools/lib/ci-profile.js parseFactor): absent, or a number >= 1.
|
|
263
264
|
# ---------------------------------------------------------------------------
|
|
264
265
|
- name: Descriptor check (.github/project.yml)
|
|
265
266
|
working-directory: ${{ github.workspace }}
|
|
@@ -291,6 +292,19 @@ jobs:
|
|
|
291
292
|
exit 1
|
|
292
293
|
fi ;;
|
|
293
294
|
esac
|
|
295
|
+
# ci-wait-factor (#559): a number >= 1 — a multiple of the repo's measured CI duration. No ceiling.
|
|
296
|
+
# Same reading as tools/lib/ci-profile.js parseFactor on the raw scalar the audit hands it.
|
|
297
|
+
f="$(field ci-wait-factor)"
|
|
298
|
+
case "$f" in
|
|
299
|
+
''|'~'|null) echo "ci-wait-factor: absent — ok (default 2)" ;;
|
|
300
|
+
*)
|
|
301
|
+
if printf '%s\n' "$f" | grep -Eq '^[0-9]+(\.[0-9]+)?$' && awk -v n="$f" 'BEGIN { exit !(n + 0 >= 1) }'; then
|
|
302
|
+
echo "ci-wait-factor: $f — ok"
|
|
303
|
+
else
|
|
304
|
+
echo "::error file=.github/project.yml::ci-wait-factor is '$f', expected a number >= 1 (a multiple of the measured CI duration; omit for 2). colab ship and colab ci-wait ignore any other value and use 2. See project.schema.md, ci-wait-factor."
|
|
305
|
+
exit 1
|
|
306
|
+
fi ;;
|
|
307
|
+
esac
|
|
294
308
|
# thresholds (#560): one level of `name: whole number`, each name known and at or above its
|
|
295
309
|
# floor (and, for a percent, at most 100) — the table in tools/lib/thresholds.js (SPEC),
|
|
296
310
|
# which a test holds this list to.
|
package/templates/ci-python.yml
CHANGED
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
#
|
|
29
29
|
# What it does:
|
|
30
30
|
# 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416;
|
|
31
|
-
# ship-batch-wait, #555).
|
|
31
|
+
# ship-batch-wait, #555; ci-wait-factor, #564).
|
|
32
32
|
# 1. Resolve the Python version from declared sources — never a hardcoded default.
|
|
33
33
|
# 2. Secret scan with gitleaks (pinned release binary, see note at the step).
|
|
34
34
|
# 3. Install dependencies from whichever manifest the repo actually has.
|
|
@@ -251,6 +251,7 @@ jobs:
|
|
|
251
251
|
# (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
|
|
252
252
|
# cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
|
|
253
253
|
# (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
|
|
254
|
+
# `ci-wait-factor` (#564) too (tools/lib/ci-profile.js parseFactor): absent, or a number >= 1.
|
|
254
255
|
# ---------------------------------------------------------------------------
|
|
255
256
|
- name: Descriptor check (.github/project.yml)
|
|
256
257
|
working-directory: ${{ github.workspace }}
|
|
@@ -282,6 +283,19 @@ jobs:
|
|
|
282
283
|
exit 1
|
|
283
284
|
fi ;;
|
|
284
285
|
esac
|
|
286
|
+
# ci-wait-factor (#559): a number >= 1 — a multiple of the repo's measured CI duration. No ceiling.
|
|
287
|
+
# Same reading as tools/lib/ci-profile.js parseFactor on the raw scalar the audit hands it.
|
|
288
|
+
f="$(field ci-wait-factor)"
|
|
289
|
+
case "$f" in
|
|
290
|
+
''|'~'|null) echo "ci-wait-factor: absent — ok (default 2)" ;;
|
|
291
|
+
*)
|
|
292
|
+
if printf '%s\n' "$f" | grep -Eq '^[0-9]+(\.[0-9]+)?$' && awk -v n="$f" 'BEGIN { exit !(n + 0 >= 1) }'; then
|
|
293
|
+
echo "ci-wait-factor: $f — ok"
|
|
294
|
+
else
|
|
295
|
+
echo "::error file=.github/project.yml::ci-wait-factor is '$f', expected a number >= 1 (a multiple of the measured CI duration; omit for 2). colab ship and colab ci-wait ignore any other value and use 2. See project.schema.md, ci-wait-factor."
|
|
296
|
+
exit 1
|
|
297
|
+
fi ;;
|
|
298
|
+
esac
|
|
285
299
|
# thresholds (#560): one level of `name: whole number`, each name known and at or above its
|
|
286
300
|
# floor (and, for a percent, at most 100) — the table in tools/lib/thresholds.js (SPEC),
|
|
287
301
|
# which a test holds this list to.
|