@futurelastic/colab-handbook 1.16.0-rc.17 → 1.16.0-rc.18
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
package/templates/README.md
CHANGED
|
@@ -110,7 +110,7 @@ check that reads one of these files is that tool's behaviour, documented with th
|
|
|
110
110
|
| `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
111
|
| `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
112
|
| `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. |
|
|
113
|
-
| `publish-downloads.yml` | `.github/workflows/publish-downloads.yml` | A repo whose **finals** carry files people install on their own machines, published to a **self-hosted downloads site** ([CONVENTIONS §6, *Downloads*](../CONVENTIONS.md#downloads--finals-to-a-self-hosted-site-648); contract in [`docs/downloads.md`](../docs/downloads.md)) | `workflow_call` from your release workflow's last job (a tag or Release made with `GITHUB_TOKEN` triggers nothing else), and `workflow_dispatch` with a tag to retry, finish a partial run, or `dry_run`. Finals only. Downloads the Release's files the `downloads:` block in `project.yml` names and runs the script below. Inputs: `runs-on` — a runner that can **reach the site** (a private-network site is unreachable from a GitHub-hosted runner; an unresolvable name fails the run before anything is sent) — and `reserved`, names the site keeps for itself. Secrets `DOWNLOADS_SSH_KEY` / `_SSH_HOST` / `_SSH_PORT` / `_SSH_USER` / `DOWNLOADS_KNOWN_HOSTS
|
|
113
|
+
| `publish-downloads.yml` | `.github/workflows/publish-downloads.yml` | A repo whose **finals** carry files people install on their own machines, published to a **self-hosted downloads site** ([CONVENTIONS §6, *Downloads*](../CONVENTIONS.md#downloads--finals-to-a-self-hosted-site-648); contract in [`docs/downloads.md`](../docs/downloads.md)) | `workflow_call` from your release workflow's last job (a tag or Release made with `GITHUB_TOKEN` triggers nothing else), and `workflow_dispatch` with a tag to retry, finish a partial run, or `dry_run`. Finals only. Downloads the Release's files the `downloads:` block in `project.yml` names and runs the script below. Inputs: `runs-on` — a runner that can **reach the site** (a private-network site is unreachable from a GitHub-hosted runner; an unresolvable name fails the run before anything is sent) — and `reserved`, names the site keeps for itself. Secrets `DOWNLOADS_SSH_KEY` / `_SSH_HOST` / `_SSH_PORT` / `_SSH_USER` / `_SSH_KNOWN_HOSTS` (the older `DOWNLOADS_KNOWN_HOSTS` is still read as a fallback), variable `DOWNLOADS_URL` (the site root). Edit point: `PUBLISH_SCRIPT`. |
|
|
114
114
|
| `publish-downloads.mjs` | `.github/downloads/publish-downloads.mjs` (the workflow's `PUBLISH_SCRIPT`) | Pairs with `publish-downloads.yml` | `check` · `names vX.Y.Z` · `publish vX.Y.Z <dir> [--dry-run]`. rsync over SSH in a fixed order — the version folder, each file read back over HTTPS against its checksum, `SHA256SUMS`, installers (`@DOWNLOADS_URL@` stamped), `manifest.json`, `latest.json` **last** (never moved back to an older final) — then reads it all back. Never replaces a published file; a different `SHA256SUMS` for a published version refuses; a re-run sends nothing. Validates the manifest the portal lists. Node ≥ 18, zero dependencies. `colab template publish-downloads.mjs --dest <path>`, `--dest` required. |
|
|
115
115
|
| `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. |
|
|
116
116
|
| `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. |
|
|
@@ -30,7 +30,7 @@
|
|
|
30
30
|
// DOWNLOADS_SSH_HOST/PORT/USER where rsync goes (repo secrets). The account is restricted to the app's
|
|
31
31
|
// folder server-side and cannot delete: its root IS /<app>/
|
|
32
32
|
// DOWNLOADS_KEY_FILE the private key file the workflow wrote from DOWNLOADS_SSH_KEY
|
|
33
|
-
// DOWNLOADS_KNOWN_HOSTS_FILE the known-hosts file the workflow wrote from
|
|
33
|
+
// DOWNLOADS_KNOWN_HOSTS_FILE the known-hosts file the workflow wrote from DOWNLOADS_SSH_KNOWN_HOSTS
|
|
34
34
|
// DOWNLOADS_RESERVED names the site keeps for itself, refused as an app slug (space/comma list)
|
|
35
35
|
//
|
|
36
36
|
// THE ORDER ON THE SITE, which is what makes a half-finished run harmless:
|
|
@@ -45,7 +45,9 @@
|
|
|
45
45
|
#
|
|
46
46
|
# CONFIGURATION — per repo, never shared between repos:
|
|
47
47
|
# secrets DOWNLOADS_SSH_KEY · DOWNLOADS_SSH_HOST · DOWNLOADS_SSH_PORT · DOWNLOADS_SSH_USER ·
|
|
48
|
-
#
|
|
48
|
+
# DOWNLOADS_SSH_KNOWN_HOSTS — an upload account restricted to this app's folder, that cannot delete.
|
|
49
|
+
# The older name DOWNLOADS_KNOWN_HOSTS is still read when DOWNLOADS_SSH_KNOWN_HOSTS is unset, so a
|
|
50
|
+
# repo set up before the rename keeps publishing; rename the secret when convenient.
|
|
49
51
|
# variable DOWNLOADS_URL — the site's root address (https). The script appends /<app>; no host is ever
|
|
50
52
|
# written in the repository.
|
|
51
53
|
#
|
|
@@ -151,7 +153,7 @@ jobs:
|
|
|
151
153
|
if: inputs.dry_run != true
|
|
152
154
|
env:
|
|
153
155
|
KEY: ${{ secrets.DOWNLOADS_SSH_KEY }}
|
|
154
|
-
KNOWN_HOSTS: ${{ secrets.DOWNLOADS_KNOWN_HOSTS }}
|
|
156
|
+
KNOWN_HOSTS: ${{ secrets.DOWNLOADS_SSH_KNOWN_HOSTS || secrets.DOWNLOADS_KNOWN_HOSTS }}
|
|
155
157
|
run: |
|
|
156
158
|
set -euo pipefail
|
|
157
159
|
umask 077
|