@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 CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.13.0-rc.32"
36
+ "version": "1.13.0-rc.34"
37
37
  }
@@ -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. |
@@ -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.
@@ -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.
@@ -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.