@futurelastic/colab-handbook 1.12.0-rc.34 → 1.12.0-rc.36
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 +2 -1
- package/templates/npx-launcher.mjs +98 -12
- package/templates/npx-service.mjs +598 -0
- package/templates/release-auto.yml +34 -3
- package/tools/colab +29 -12
- package/tools/lib/release-cut.js +54 -19
- package/tools/lib/release-finalize.js +92 -6
- package/tools/lib/release-policy.js +1 -1
package/package.json
CHANGED
package/templates/README.md
CHANGED
|
@@ -22,7 +22,8 @@ Starting points you **copy into your own repo**. That is the entire model.
|
|
|
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
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. |
|
|
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
|
-
| `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
|
|
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
|
+
| `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`, then `<tool> update [--check] [--version vX.Y.Z] [--channel next\|stable]`, `<tool> rollback`, `<tool> status`; 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. Node ≥ 18, zero dependencies; needs `git`, and `npm` for `update`. **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), `LABEL`, `SERVICE_ARGS`, `ENTRY`, `HEALTH_URL`, `KEEP`, `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. |
|
|
26
27
|
| `deploy-xserver.yml` | `.github/workflows/deploy-xserver.yml` | PHP-framework + Vite apps shipped to **shared hosting over SSH** (no root, no Docker): build on a runner, rsync, migrate on the server | Derived from three independently-written copies. Resolves Node the same way the CI templates do — all three hardcoded it, and one shipped on a different major than its CI built on. Migrates **production**; keeps a **mandatory** smoke test. Does **not** change your tier. |
|
|
27
28
|
| `deploy-container.yml` | `.github/workflows/deploy-container.yml` | A **container** app on a host whose platform has an API (Portainer today), `deploy: tag` ([CONVENTIONS §6, *A container deploy*](../CONVENTIONS.md#6-releases), #452) | One contract on every host: build each listed image **once** per final tag (`vX.Y.Z` + commit sha), run the pre-deploy hook, have the platform run exactly that tag (all images, one call), green only on a **verified running version** (stack settled, commit and container images checked, then `release.health-url` reporting `X.Y.Z`), roll back to the previous final on a failure after the platform accepted. **Two jobs (#460):** `publish` builds and pushes on **every** final, ungated — so a repo not yet cut over still gets each final's image in the registry; `deploy` `needs:` it, never builds (a missing image fails before the platform is touched), and is the one job you gate on "is the platform switched on". Images and build args sit in the workflow-level `env`, written once for both jobs. Triggers: a final tag push (route `deploy-tag`), `workflow_dispatch` with a tag (a manual deploy or rollback), and `workflow_call` — route `deploy-tag-fast` reaches it from `release-auto.yml`'s commented `deploy` job, like `dist-refs.yml` from its release run. Needs its two scripts below. One required secret: `PORTAINER_API_KEY`, a non-admin key owning only this app's stack; optional `HEALTH_AUTH_HEADER` (`Name: value`) or `HEALTH_BASIC_AUTH` (`user:password`) when the version URL sits behind auth — masked, never printed. **Every redeploy recreates the containers.** Does **not** change your exposure. |
|
|
28
29
|
| `deploy-container-run.mjs` | `.github/deploy/deploy-container-run.mjs` | Pairs with `deploy-container.yml` | The driver: builds, runs the hook, calls the adapter, verifies, rolls back, records. `--publish-only` = build and push only (no platform config, no version URL needed); `--deploy-only` = everything after, refusing a tag whose image is not in the registry. **Build args:** `DEPLOY_BUILD_ARGS`, one per line — `KEY=VALUE` for every image or `<image-ref> KEY=VALUE` for one; `${TAG}` (`vX.Y.Z`), `${VERSION}` (`X.Y.Z`) and `${SHA}` are filled in by the driver, so a static site can bake public config and its version into a served file. They end up in the image — public values only, never a secret. Node ≥ 18, zero dependencies; shells out to `git`, `docker`, `gh`. `colab template deploy-container-run.mjs --dest <path>`, `--dest` required, stamped on line 2. |
|
|
@@ -26,6 +26,14 @@
|
|
|
26
26
|
// 3. this package's own package.json: `version` → `v<version>`, `repository.url` → origin.
|
|
27
27
|
// Nothing found → it refuses and says which variable to set. It never guesses a version.
|
|
28
28
|
//
|
|
29
|
+
// A RELEASE CHANNEL instead of a version (#465): `npx github:<org>/<repo>#stable` (or `#next`,
|
|
30
|
+
// the channel branches of CONVENTIONS.md §6, #445). A channel is never an install key — dist
|
|
31
|
+
// refs are keyed by version. The launcher asks the same origin, with the same git, which release
|
|
32
|
+
// tag sits on the commit npx installed (the sha in the lockfile's `resolved`; the channel's live
|
|
33
|
+
// tip only when no sha is recorded) and installs exactly that version: `stable` → the highest
|
|
34
|
+
// final there, `next` → the highest release tag there. No release tag on that commit → it
|
|
35
|
+
// refuses. Any other branch committish (`#main`) still refuses, as before.
|
|
36
|
+
//
|
|
29
37
|
// The checksum lives in the same ref as the binary, so it proves the bytes arrived whole and are
|
|
30
38
|
// the bytes the release run pushed — not that the release run was honest. The trust anchor is
|
|
31
39
|
// write access to the repository, as it is for the source npx just ran.
|
|
@@ -33,7 +41,8 @@
|
|
|
33
41
|
// A long-running tool must not run from npx's cache (npm may prune it under a live process).
|
|
34
42
|
// This launcher never does: the binary always runs from the stable install path below, and
|
|
35
43
|
// `--print-path` (consumed by the launcher, never passed on) prints that path so an `init` /
|
|
36
|
-
// `install` step can wire a service to it.
|
|
44
|
+
// `install` step can wire a service to it. A per-machine SERVICE uses templates/npx-service.mjs,
|
|
45
|
+
// which imports this file as a library for its `init` / `update` / `rollback` verbs (#465).
|
|
37
46
|
|
|
38
47
|
import { spawnSync } from 'node:child_process';
|
|
39
48
|
import { createHash } from 'node:crypto';
|
|
@@ -48,7 +57,8 @@ import { fileURLToPath } from 'node:url';
|
|
|
48
57
|
// package's name without its scope.
|
|
49
58
|
const BIN = null;
|
|
50
59
|
|
|
51
|
-
const VERSION_RE = /^v\d+\.\d+\.\d+(-rc\.\d+)?$/;
|
|
60
|
+
export const VERSION_RE = /^v\d+\.\d+\.\d+(-rc\.\d+)?$/;
|
|
61
|
+
export const CHANNELS = ['next', 'stable'];
|
|
52
62
|
const here = dirname(fileURLToPath(import.meta.url));
|
|
53
63
|
|
|
54
64
|
function die(msg) {
|
|
@@ -96,6 +106,8 @@ export function resolveTarget({ env, pkgDir, pkg, read = readJson }) {
|
|
|
96
106
|
const envKey = tool.toUpperCase().replace(/[^A-Z0-9]/g, '_') + '_DIST';
|
|
97
107
|
let version = env[`${envKey}_VERSION`] || null;
|
|
98
108
|
let origin = env[`${envKey}_ORIGIN`] || null;
|
|
109
|
+
let channel = null;
|
|
110
|
+
let sha = null;
|
|
99
111
|
|
|
100
112
|
const inst = pkg.name ? installerRoot(pkgDir, pkg.name) : null;
|
|
101
113
|
if (inst) {
|
|
@@ -103,11 +115,22 @@ export function resolveTarget({ env, pkgDir, pkg, read = readJson }) {
|
|
|
103
115
|
const spec = (ipkg.dependencies || {})[pkg.name] || (ipkg.devDependencies || {})[pkg.name];
|
|
104
116
|
const committish = typeof spec === 'string' && spec.includes('#') ? spec.slice(spec.lastIndexOf('#') + 1) : null;
|
|
105
117
|
if (!version && committish && VERSION_RE.test(committish)) version = committish;
|
|
118
|
+
if (!version && committish && CHANNELS.includes(committish)) channel = committish;
|
|
106
119
|
const lock = read(join(inst, 'package-lock.json')) || {};
|
|
107
120
|
const entry = (lock.packages || {})[`node_modules/${pkg.name}`];
|
|
121
|
+
if (entry && typeof entry.resolved === 'string') {
|
|
122
|
+
const m = entry.resolved.match(/#([0-9a-f]{40})$/);
|
|
123
|
+
if (m) sha = m[1];
|
|
124
|
+
}
|
|
108
125
|
if (!origin && entry && entry.resolved) origin = gitUrl(entry.resolved);
|
|
109
126
|
if (!origin && spec) origin = gitUrl(spec);
|
|
110
127
|
}
|
|
128
|
+
// A channel is resolved to a version later, against the origin (resolveChannel) — never from
|
|
129
|
+
// the manifest, whose version names the final even at `#next`.
|
|
130
|
+
if (!version && channel) {
|
|
131
|
+
if (!origin) return { error: `cannot tell which repository to fetch from — set ${envKey}_ORIGIN to its git URL` };
|
|
132
|
+
return { tool, channel, sha, origin, envKey };
|
|
133
|
+
}
|
|
111
134
|
if (!version && pkg.version) version = `v${pkg.version}`;
|
|
112
135
|
if (!origin && pkg.repository) origin = gitUrl(typeof pkg.repository === 'string' ? pkg.repository : pkg.repository.url);
|
|
113
136
|
|
|
@@ -138,30 +161,85 @@ export function expectedSum(sumsText, file) {
|
|
|
138
161
|
return null;
|
|
139
162
|
}
|
|
140
163
|
|
|
164
|
+
/** `git ls-remote` output → { heads: {name: sha}, tags: {name: sha} }, annotated tags peeled. */
|
|
165
|
+
export function parseLsRemote(text) {
|
|
166
|
+
const heads = {};
|
|
167
|
+
const tags = {};
|
|
168
|
+
for (const line of String(text || '').split('\n')) {
|
|
169
|
+
const m = line.match(/^([0-9a-f]{40})\s+refs\/(heads|tags)\/(.+)$/);
|
|
170
|
+
if (!m) continue;
|
|
171
|
+
const [, sha, kind, name] = m;
|
|
172
|
+
if (kind === 'heads') { heads[name] = sha; continue; }
|
|
173
|
+
if (name.endsWith('^{}')) tags[name.slice(0, -3)] = sha; // the peeled line wins
|
|
174
|
+
else if (!(name in tags)) tags[name] = sha;
|
|
175
|
+
}
|
|
176
|
+
return { heads, tags };
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/** SemVer order over release tags: a final outranks its own candidates. */
|
|
180
|
+
export function compareVersions(a, b) {
|
|
181
|
+
const p = (v) => {
|
|
182
|
+
const m = String(v).match(/^v(\d+)\.(\d+)\.(\d+)(?:-rc\.(\d+))?$/);
|
|
183
|
+
return m ? [+m[1], +m[2], +m[3], m[4] === undefined ? Infinity : +m[4]] : [-1, -1, -1, -1];
|
|
184
|
+
};
|
|
185
|
+
const x = p(a); const y = p(b);
|
|
186
|
+
for (let i = 0; i < 4; i++) if (x[i] !== y[i]) return x[i] < y[i] ? -1 : 1;
|
|
187
|
+
return 0;
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/**
|
|
191
|
+
* Which release a channel names. `at` = the commit to read (the sha npx installed); absent, the
|
|
192
|
+
* channel branch's tip. `stable` → highest final tagged there; `next` → highest release tag there.
|
|
193
|
+
* Returns { version, sha } or { error } — never a guess.
|
|
194
|
+
*/
|
|
195
|
+
export function channelVersion(lsText, channel, at = null) {
|
|
196
|
+
if (!CHANNELS.includes(channel)) return { error: `${channel} is not a release channel (${CHANNELS.join(', ')})` };
|
|
197
|
+
const { heads, tags } = parseLsRemote(lsText);
|
|
198
|
+
const sha = at || heads[channel];
|
|
199
|
+
if (!sha) return { error: `the origin has no \`${channel}\` channel branch — install a version (#vX.Y.Z) instead` };
|
|
200
|
+
const here = Object.keys(tags)
|
|
201
|
+
.filter((t) => tags[t] === sha && VERSION_RE.test(t))
|
|
202
|
+
.filter((t) => channel === 'next' || !t.includes('-rc.'))
|
|
203
|
+
.sort(compareVersions);
|
|
204
|
+
if (!here.length) return { error: `\`${channel}\` is at ${sha.slice(0, 12)}, which carries no ${channel === 'stable' ? 'final ' : ''}release tag — refusing to guess a version` };
|
|
205
|
+
return { version: here[here.length - 1], sha };
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/** Ask the origin (same git, same URL, so the same credentials) which version a channel names. */
|
|
209
|
+
export function resolveChannel({ origin, channel, at = null, run = git }) {
|
|
210
|
+
const r = run(['ls-remote', origin, `refs/heads/${channel}`, 'refs/tags/v*']);
|
|
211
|
+
if (r.status !== 0) return { error: `could not read ${origin}: ${(r.stderr || '').trim()}` };
|
|
212
|
+
return channelVersion(r.stdout, channel, at);
|
|
213
|
+
}
|
|
214
|
+
|
|
141
215
|
function sha256(path) {
|
|
142
216
|
return createHash('sha256').update(readFileSync(path)).digest('hex');
|
|
143
217
|
}
|
|
144
218
|
|
|
145
219
|
function git(args, opts = {}) {
|
|
146
220
|
const r = spawnSync('git', args, { encoding: 'utf8', ...opts });
|
|
147
|
-
if (r.error)
|
|
221
|
+
if (r.error) throw new Error(`git could not run: ${r.error.message}`);
|
|
148
222
|
return r;
|
|
149
223
|
}
|
|
150
224
|
|
|
151
|
-
/**
|
|
225
|
+
/**
|
|
226
|
+
* Fetch the dist ref into a throwaway repo, verify, install atomically. Returns the binary path.
|
|
227
|
+
* Throws on any refusal (main() turns that into a message + exit 1; the service template reports it).
|
|
228
|
+
*/
|
|
152
229
|
export function install({ origin, version, plat, exe, dir }) {
|
|
153
230
|
const ref = `refs/tags/dist/${version}/${plat}`;
|
|
231
|
+
const fail = (msg) => { throw new Error(msg); };
|
|
154
232
|
const tmp = mkdtempSync(join(tmpdir(), 'npx-launcher-'));
|
|
155
233
|
try {
|
|
156
234
|
git(['init', '-q', '--bare', tmp]);
|
|
157
235
|
const f = git(['-C', tmp, 'fetch', '-q', '--depth', '1', '--no-tags', origin, ref]);
|
|
158
236
|
if (f.status !== 0) {
|
|
159
|
-
|
|
237
|
+
fail(`could not fetch ${ref} from ${origin} — is ${version} released for ${plat}?\n${(f.stderr || '').trim()}`);
|
|
160
238
|
}
|
|
161
239
|
const sums = git(['-C', tmp, 'cat-file', 'blob', `FETCH_HEAD:SHA256SUMS`]);
|
|
162
|
-
if (sums.status !== 0)
|
|
240
|
+
if (sums.status !== 0) fail(`${ref} carries no SHA256SUMS — refusing an unverifiable binary`);
|
|
163
241
|
const want = expectedSum(sums.stdout, exe);
|
|
164
|
-
if (!want)
|
|
242
|
+
if (!want) fail(`${ref}'s SHA256SUMS has no line for ${exe}`);
|
|
165
243
|
|
|
166
244
|
mkdirSync(dir, { recursive: true });
|
|
167
245
|
const part = join(dir, `.${exe}.part-${process.pid}`);
|
|
@@ -170,9 +248,9 @@ export function install({ origin, version, plat, exe, dir }) {
|
|
|
170
248
|
try {
|
|
171
249
|
r = spawnSync('git', ['-C', tmp, 'cat-file', 'blob', `FETCH_HEAD:${exe}`], { stdio: ['ignore', fd, 'pipe'] });
|
|
172
250
|
} finally { closeSync(fd); }
|
|
173
|
-
if (r.error || r.status !== 0) { rmSync(part, { force: true });
|
|
251
|
+
if (r.error || r.status !== 0) { rmSync(part, { force: true }); fail(`${ref} has no ${exe}`); }
|
|
174
252
|
const got = sha256(part);
|
|
175
|
-
if (got !== want) { rmSync(part, { force: true });
|
|
253
|
+
if (got !== want) { rmSync(part, { force: true }); fail(`checksum mismatch for ${exe} in ${ref}: expected ${want}, got ${got}`); }
|
|
176
254
|
chmodSync(part, 0o755);
|
|
177
255
|
renameSync(part, join(dir, exe));
|
|
178
256
|
return join(dir, exe);
|
|
@@ -181,11 +259,17 @@ export function install({ origin, version, plat, exe, dir }) {
|
|
|
181
259
|
}
|
|
182
260
|
}
|
|
183
261
|
|
|
184
|
-
function main(argv) {
|
|
185
|
-
const pkgDir = packageRoot(
|
|
262
|
+
export function main(argv, start = here) {
|
|
263
|
+
const pkgDir = packageRoot(start);
|
|
186
264
|
const pkg = (pkgDir && readJson(join(pkgDir, 'package.json'))) || die('cannot find this package\'s package.json');
|
|
187
265
|
const t = resolveTarget({ env: process.env, pkgDir, pkg });
|
|
188
266
|
if (t.error) die(t.error);
|
|
267
|
+
if (!t.version) {
|
|
268
|
+
let c;
|
|
269
|
+
try { c = resolveChannel({ origin: t.origin, channel: t.channel, at: t.sha }); } catch (e) { die(e.message); }
|
|
270
|
+
if (c.error) die(c.error);
|
|
271
|
+
t.version = c.version;
|
|
272
|
+
}
|
|
189
273
|
const plat = platformKey();
|
|
190
274
|
const exe = process.platform === 'win32' ? `${t.tool}.exe` : t.tool;
|
|
191
275
|
const dir = installDir({ env: process.env, tool: t.tool, version: t.version, plat });
|
|
@@ -193,7 +277,9 @@ function main(argv) {
|
|
|
193
277
|
|
|
194
278
|
// Installed already? A release's dist ref never moves, so an existing binary is that release's
|
|
195
279
|
// — re-fetching on every run would make every invocation a network round-trip.
|
|
196
|
-
if (!existsSync(bin))
|
|
280
|
+
if (!existsSync(bin)) {
|
|
281
|
+
try { install({ origin: t.origin, version: t.version, plat, exe, dir }); } catch (e) { die(e.message); }
|
|
282
|
+
}
|
|
197
283
|
|
|
198
284
|
const args = argv.filter((a) => a !== '--print-path');
|
|
199
285
|
if (args.length !== argv.length) { process.stdout.write(`${bin}\n`); return 0; }
|