@futurelastic/colab-handbook 1.18.0-rc.1 → 1.18.0-rc.10
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/README.md +16 -0
- package/README.vi.md +15 -0
- package/package.json +1 -1
- package/templates/publish-downloads.yml +5 -0
- package/templates/release-auto.yml +119 -7
- package/tools/colab +171 -21
- package/tools/lib/engines.js +53 -1
- package/tools/lib/install-check.js +63 -4
- package/tools/lib/migration-paths.js +44 -14
- package/tools/lib/procs.js +44 -6
- package/tools/lib/release-cut.js +154 -13
- package/tools/lib/release-finalize.js +21 -5
package/README.md
CHANGED
|
@@ -317,11 +317,27 @@ linked, so an existing machine changes nothing. Finding none, it installs for
|
|
|
317
317
|
Claude Code and says so. The per-runtime facts live in [`engines/`](engines/),
|
|
318
318
|
one file each — that folder is the source for the table above.
|
|
319
319
|
|
|
320
|
+
**Sessions that run in a private home** never see a user-level folder. For
|
|
321
|
+
those, copy the skills into the repo itself:
|
|
322
|
+
|
|
323
|
+
```sh
|
|
324
|
+
./install.sh --repo ~/code/app --engine opencode # → ~/code/app/.opencode/skills
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
Every skill is copied as plain files (a linked folder or file is
|
|
328
|
+
dereferenced, never linked), with a manifest of what was copied. The command
|
|
329
|
+
prints each file it wrote, so you can commit them. A re-run refreshes the
|
|
330
|
+
copies the repo has not edited and leaves edited ones alone. `--check` reports
|
|
331
|
+
the copy and its version, and marks it ✗ behind once a skill changes in the
|
|
332
|
+
clone. Only agent runtimes whose `engines/` file names a `project_skills_dir`
|
|
333
|
+
have this route; today that is opencode.
|
|
334
|
+
|
|
320
335
|
| Flag | What it does |
|
|
321
336
|
|---|---|
|
|
322
337
|
| *(none)* | Symlink `skills/` into each chosen agent runtime's user-level folder, so they are available in every repo you open. Asks at a terminal; otherwise keeps what is linked (see [*Choose your agent runtime*](#choose-your-agent-runtime)). |
|
|
323
338
|
| `--engine <id>[,<id>]` | Install for these agent runtimes (`claude`, `codex`, `opencode` — the files in `engines/`), no question asked. |
|
|
324
339
|
| `--skills-dir <path>` | Also install into this folder, for an agent `engines/` does not know. |
|
|
340
|
+
| `--repo <path> --engine <id>` | Instead of a user-level install, **copy** the skills into that repo's project skills folder, for sessions that run in a private home. Prints the files to commit. |
|
|
325
341
|
| `--tools` | The `colab` CLI twice: a **symlink** at `~/.local/bin/colab` for your sessions (it prints the `PATH` line if needed), and a stamped **frozen copy** at `~/.colab/bin/colab` for always-on services. Also creates an empty `~/.colab/state.json` if there is none. |
|
|
326
342
|
| `--hooks` | Point this clone's git at `.githooks/`: a gitleaks secret scan and an identity scan whose vocabulary you keep outside every repo (see [`templates/README.md`](templates/README.md)). |
|
|
327
343
|
| `--fleet` | Seed `~/.colab/repos.txt` with format notes only, if absent. It stays machine-local because it names your private repos; `colab register` fills it. |
|
package/README.vi.md
CHANGED
|
@@ -316,11 +316,26 @@ sẵn, nên máy đã cài không thay đổi gì. Không thấy agent runtime n
|
|
|
316
316
|
Code và nói rõ điều đó. Thông tin từng agent runtime nằm trong [`engines/`](engines/),
|
|
317
317
|
mỗi agent runtime một file — thư mục đó là nguồn của bảng trên.
|
|
318
318
|
|
|
319
|
+
**Phiên chạy trong một home riêng** không bao giờ thấy thư mục cấp user. Với
|
|
320
|
+
những phiên đó, hãy chép skill vào chính repo:
|
|
321
|
+
|
|
322
|
+
```sh
|
|
323
|
+
./install.sh --repo ~/code/app --engine opencode # → ~/code/app/.opencode/skills
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
Mỗi skill được chép thành file thường (thư mục hay file là link thì được chép
|
|
327
|
+
nội dung, không bao giờ để link), kèm một manifest ghi những gì đã chép. Lệnh in
|
|
328
|
+
ra từng file nó đã ghi để bạn commit. Chạy lại thì làm mới các bản chép mà repo
|
|
329
|
+
chưa sửa, và để nguyên bản đã sửa. `--check` báo bản chép cùng phiên bản của nó,
|
|
330
|
+
và đánh ✗ (đã cũ) khi một skill trong clone thay đổi. Chỉ agent runtime nào có
|
|
331
|
+
file `engines/` khai `project_skills_dir` mới có đường này; hiện nay là opencode.
|
|
332
|
+
|
|
319
333
|
| Flag | Làm gì |
|
|
320
334
|
|---|---|
|
|
321
335
|
| *(không có)* | Symlink `skills/` vào thư mục cấp user của từng agent runtime đã chọn, để mở repo nào cũng có. Ở terminal thì hỏi; không thì giữ những gì đã link (xem [*Chọn agent runtime*](#chọn-agent-runtime)). |
|
|
322
336
|
| `--engine <id>[,<id>]` | Cài cho các agent runtime này (`claude`, `codex`, `opencode` — các file trong `engines/`), không hỏi. |
|
|
323
337
|
| `--skills-dir <path>` | Cài thêm vào thư mục này, cho agent mà `engines/` chưa biết. |
|
|
338
|
+
| `--repo <path> --engine <id>` | Thay cho cài cấp user: **chép** skill vào thư mục skill của project trong repo đó, cho phiên chạy trong một home riêng. In ra các file cần commit. |
|
|
324
339
|
| `--tools` | CLI `colab` cài hai lần: một **symlink** ở `~/.local/bin/colab` cho các phiên làm việc của bạn (in sẵn dòng `PATH` nếu cần), và một **bản đóng băng** có đóng dấu ở `~/.colab/bin/colab` cho các service luôn-bật. Đồng thời tạo `~/.colab/state.json` rỗng nếu chưa có. |
|
|
325
340
|
| `--hooks` | Trỏ git của clone này vào `.githooks/`: quét secret bằng gitleaks, và quét danh tính với danh sách từ khoá do bạn giữ NGOÀI mọi repo (xem [`templates/README.md`](templates/README.md)). |
|
|
326
341
|
| `--fleet` | Tạo `~/.colab/repos.txt` chỉ chứa ghi chú định dạng, nếu chưa có. Nó cố tình nằm trên máy vì nó ghi tên các repo private của bạn; `colab register` mới là thứ điền vào. |
|
package/package.json
CHANGED
|
@@ -34,6 +34,11 @@
|
|
|
34
34
|
# (A tag pushed or a Release published with GITHUB_TOKEN starts no other workflow, so a chained call is
|
|
35
35
|
# the reliable trigger — not `on: release`.) Nothing is published from an incomplete Release: the script
|
|
36
36
|
# names what is missing and uploads nothing.
|
|
37
|
+
# Chained from release-auto.yml, gate the build jobs and this one on its `downloads-tag` output, not on
|
|
38
|
+
# the run's own finalize tag (#669): `downloads-tag` also carries a final a PERSON tagged — early
|
|
39
|
+
# (`colab release finalize --early`, #627) or on `final: human` — which no run tags, and which the daily
|
|
40
|
+
# run hands on once the site's latest.json is behind it (creating its Release, so the build jobs have one
|
|
41
|
+
# to attach files to). release-auto.yml's "DOWNLOADS" header block shows the wiring.
|
|
37
42
|
# - By hand (Actions → Run workflow) with a tag: retries a failed publish, finishes a partial one (only the
|
|
38
43
|
# missing files are sent), re-checks a complete one. `dry_run` stages and lists — it uploads nothing.
|
|
39
44
|
# The project.yml, manifest, installers and script are read from THIS run's checkout: the tag's commit when
|
|
@@ -31,6 +31,11 @@
|
|
|
31
31
|
# comment above that job
|
|
32
32
|
# the daily schedule or a dispatch, and the same npm publish of the newest final on main
|
|
33
33
|
# npm `latest` is older than that final — a final tagged by hand (`final: human`, #612)
|
|
34
|
+
# project.yml declares `downloads:`, and the final this run tagged — or, on the daily
|
|
35
|
+
# this run tagged a final, or the daily schedule / a dispatch, the newest final on main
|
|
36
|
+
# schedule / a dispatch finds the site's (an early or `final: human` final a person
|
|
37
|
+
# latest.json older than the newest final tagged, #669) — handed to YOUR build + downloads
|
|
38
|
+
# jobs as `downloads-tag`; see "DOWNLOADS" below
|
|
34
39
|
# the cut tagged a FINAL — route deploy + health check (job `deploy`, #446) — see
|
|
35
40
|
# deploy-tag-fast only "DEPLOYING IN THIS RUN" below
|
|
36
41
|
# the cut tagged a FINAL — route published like any tag (Release marked latest, npm
|
|
@@ -126,6 +131,38 @@
|
|
|
126
131
|
# ends in `[publish]`. So a red INSIDE a `[publish]` step, or in the npm or deploy jobs (which never
|
|
127
132
|
# run without a tag), cannot be cured by a dry run — that stays a human ci-grant.
|
|
128
133
|
#
|
|
134
|
+
# DOWNLOADS — EVERY FINAL, NOT ONLY THE ONES THIS RUN TAGGED (#669). A repo whose finals carry files
|
|
135
|
+
# people install (docs/downloads.md, templates/publish-downloads.yml) builds them in jobs YOU add below
|
|
136
|
+
# `release`, and chains publish-downloads.yml after them. Gate both on the release job's
|
|
137
|
+
# `downloads-tag` output, never on the finalize step's own tag: a final a person tagged — early
|
|
138
|
+
# (`colab release finalize --early`, #627) or on `final: human` — is tagged by the CLI, not by this
|
|
139
|
+
# run, so a job gated on this run's tag never builds it, and a later run reads `already-final` and
|
|
140
|
+
# skips it again. `downloads-tag` is the final this run tagged, or — on the daily run and a dispatch —
|
|
141
|
+
# the newest final on main whose version the site's latest.json does not name yet (absent, or older);
|
|
142
|
+
# that swept final also gets its GitHub Release here, so your build jobs have one to attach files to.
|
|
143
|
+
# Empty when project.yml declares no `downloads:`, when the site already names that version or a newer
|
|
144
|
+
# one (a complete version sends nothing), and when the site cannot be read from this job's runner —
|
|
145
|
+
# a warning then, never a red run; the next daily run retries. The site is read at
|
|
146
|
+
# vars.DOWNLOADS_URL/<downloads.app>/latest.json FROM THE RELEASE JOB'S RUNNER: a site only a private
|
|
147
|
+
# network reaches needs the release job on a runner inside it (RUNNERS, below). The wiring:
|
|
148
|
+
#
|
|
149
|
+
# build-macos: # EDIT: one job per platform you build
|
|
150
|
+
# needs: release
|
|
151
|
+
# if: needs.release.outputs.downloads-tag != ''
|
|
152
|
+
# runs-on: macos-latest
|
|
153
|
+
# permissions: { contents: write }
|
|
154
|
+
# steps:
|
|
155
|
+
# - uses: actions/checkout@<sha>
|
|
156
|
+
# with: { ref: '${{ needs.release.outputs.downloads-tag }}' }
|
|
157
|
+
# - run: …build, then attach the files to the tag's Release (gh release upload … --clobber)
|
|
158
|
+
# env: { GH_TOKEN: '${{ github.token }}', TAG: '${{ needs.release.outputs.downloads-tag }}' }
|
|
159
|
+
# downloads:
|
|
160
|
+
# needs: [release, build-macos]
|
|
161
|
+
# if: needs.release.outputs.downloads-tag != ''
|
|
162
|
+
# uses: ./.github/workflows/publish-downloads.yml
|
|
163
|
+
# with: { tag: '${{ needs.release.outputs.downloads-tag }}' }
|
|
164
|
+
# secrets: inherit
|
|
165
|
+
#
|
|
129
166
|
# IT READS TAGS AND CREATES TAGS. IT NEVER WRITES A COMMIT. No step here commits; the refs
|
|
130
167
|
# pushed are the tags `colab release cut` / `colab release finalize` create (annotated, their
|
|
131
168
|
# checks recorded in the tag message) and — only on a repo granting unattended promotion — the
|
|
@@ -335,6 +372,10 @@ jobs:
|
|
|
335
372
|
# What the deploy job below needs (#446) — empty unless this run tagged a deploy-tag-fast final.
|
|
336
373
|
deploy-tag: ${{ steps.cut.outputs.final }}
|
|
337
374
|
health-url: ${{ steps.cut.outputs.health-url }}
|
|
375
|
+
# What YOUR build and downloads jobs gate on (#669) — empty unless project.yml declares `downloads:`
|
|
376
|
+
# and this run tagged a final, or the daily sweep found a final the site's latest.json lacks.
|
|
377
|
+
# See "DOWNLOADS" in the header.
|
|
378
|
+
downloads-tag: ${{ steps.downloads-target.outputs.tag }}
|
|
338
379
|
env:
|
|
339
380
|
GH_TOKEN: ${{ github.token }}
|
|
340
381
|
# #474: 'true' on a dry run — a dispatch on any ref other than main, or one with dry_run set.
|
|
@@ -475,7 +516,7 @@ jobs:
|
|
|
475
516
|
{
|
|
476
517
|
echo "### colab promote --auto"
|
|
477
518
|
echo
|
|
478
|
-
jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
|
|
519
|
+
jq -r '.checks[]? | "- \(if .checked == false then "·" elif .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
|
|
479
520
|
echo
|
|
480
521
|
} >> "$GITHUB_STEP_SUMMARY"
|
|
481
522
|
if [ "${DRY_RUN:-false}" = "true" ]; then
|
|
@@ -544,7 +585,7 @@ jobs:
|
|
|
544
585
|
{
|
|
545
586
|
echo "### colab release cut --auto"
|
|
546
587
|
echo
|
|
547
|
-
jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
|
|
588
|
+
jq -r '.checks[]? | "- \(if .checked == false then "·" elif .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
|
|
548
589
|
echo
|
|
549
590
|
} >> "$GITHUB_STEP_SUMMARY"
|
|
550
591
|
if [ "${DRY_RUN:-false}" = "true" ]; then
|
|
@@ -680,7 +721,7 @@ jobs:
|
|
|
680
721
|
{
|
|
681
722
|
echo "### colab release finalize --auto — $STATE"
|
|
682
723
|
echo
|
|
683
|
-
jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
|
|
724
|
+
jq -r '.checks[]? | "- \(if .checked == false then "·" elif .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
|
|
684
725
|
echo
|
|
685
726
|
if [ -n "$WHY" ]; then echo "**Why no final:** $WHY"; echo; fi
|
|
686
727
|
if [ "$(jq -r '(.skipped // []) | length' "$OUT")" != "0" ]; then
|
|
@@ -776,12 +817,83 @@ jobs:
|
|
|
776
817
|
echo "package=$PACKAGE"
|
|
777
818
|
} >> "$GITHUB_OUTPUT"
|
|
778
819
|
|
|
779
|
-
#
|
|
780
|
-
#
|
|
781
|
-
|
|
782
|
-
|
|
820
|
+
# #669: which final YOUR build + downloads jobs get (`downloads-tag`, header "DOWNLOADS"). The final
|
|
821
|
+
# this run tagged, if any; else, on the daily run and a dispatch, the newest FINAL reachable from main
|
|
822
|
+
# when the site's latest.json does not name it yet (absent → never published, older → behind) — a
|
|
823
|
+
# final a person tagged (early, #627, or `final: human`) is never tagged by a run, so without this
|
|
824
|
+
# sweep it never reached the site. The site at that version or newer, no `downloads:` block, no
|
|
825
|
+
# DOWNLOADS_URL, or an unreadable site: nothing is handed on, and the step stays green.
|
|
826
|
+
- name: Read the downloads target [publish]
|
|
827
|
+
id: downloads-target
|
|
828
|
+
if: env.DRY_RUN != 'true' && (steps.cut.outputs.tag != '' || steps.finalize.outputs.tag != '' || (github.event_name == 'schedule' && env.RETRY_RUN != 'true') || github.event_name == 'workflow_dispatch')
|
|
783
829
|
env:
|
|
784
830
|
TAGS: ${{ steps.cut.outputs.tag }} ${{ steps.finalize.outputs.tag }}
|
|
831
|
+
SWEEP: ${{ (github.event_name == 'schedule' && env.RETRY_RUN != 'true') || github.event_name == 'workflow_dispatch' }}
|
|
832
|
+
DOWNLOADS_URL: ${{ vars.DOWNLOADS_URL }}
|
|
833
|
+
run: |
|
|
834
|
+
set -uo pipefail
|
|
835
|
+
# The `downloads:` block's `app:` — the same key publish-downloads.mjs reads. No block, no target.
|
|
836
|
+
APP="$(awk '
|
|
837
|
+
/^downloads:[ \t]*(#.*)?$/ { inb = 1; next }
|
|
838
|
+
inb && /^[^ \t#]/ { exit }
|
|
839
|
+
inb && /^[ \t]+app:/ { v = $0; sub(/^[ \t]+app:[ \t]*/, "", v); sub(/[ \t]+#.*$/, "", v); gsub(/["\047]/, "", v); sub(/[ \t]+$/, "", v); print v; exit }
|
|
840
|
+
' .github/project.yml 2> /dev/null)"
|
|
841
|
+
if [ -z "$APP" ]; then
|
|
842
|
+
echo "No downloads: block in .github/project.yml — no downloads target."
|
|
843
|
+
exit 0
|
|
844
|
+
fi
|
|
845
|
+
if ! [[ "$APP" =~ ^[a-z0-9][a-z0-9-]*$ ]]; then
|
|
846
|
+
echo "::warning::downloads.app '$APP' is not a valid app slug — nothing is handed to the downloads jobs"
|
|
847
|
+
exit 0
|
|
848
|
+
fi
|
|
849
|
+
OWN="$(tr ' ' '\n' <<< "$TAGS" | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -n 1 || true)"
|
|
850
|
+
if [ -n "$OWN" ]; then
|
|
851
|
+
echo "tag=$OWN" >> "$GITHUB_OUTPUT"
|
|
852
|
+
echo "downloads: $OWN was tagged by this run — handing it to the build and downloads jobs" | tee -a "$GITHUB_STEP_SUMMARY"
|
|
853
|
+
exit 0
|
|
854
|
+
fi
|
|
855
|
+
[ "${SWEEP:-false}" = "true" ] || exit 0
|
|
856
|
+
FINAL="$(git tag --merged HEAD --list 'v*' | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -n 1 || true)"
|
|
857
|
+
if [ -z "$FINAL" ]; then
|
|
858
|
+
echo "downloads sweep: no final on main yet — nothing to publish"
|
|
859
|
+
exit 0
|
|
860
|
+
fi
|
|
861
|
+
if [ -z "${DOWNLOADS_URL:-}" ]; then
|
|
862
|
+
echo "::warning::downloads sweep: the DOWNLOADS_URL variable is not set on this repo — cannot read the site, so $FINAL is not handed on"
|
|
863
|
+
exit 0
|
|
864
|
+
fi
|
|
865
|
+
eval "$RETRY_TRANSIENT"
|
|
866
|
+
VERSION="${FINAL#v}"
|
|
867
|
+
URL="${DOWNLOADS_URL%/}/$APP/latest.json"
|
|
868
|
+
ERR="$RUNNER_TEMP/downloads-latest.err"
|
|
869
|
+
hand_on() {
|
|
870
|
+
{ echo "tag=$FINAL"; echo "swept=$FINAL"; } >> "$GITHUB_OUTPUT"
|
|
871
|
+
echo "downloads sweep: $1 — handing $FINAL to the build and downloads jobs (#669)" | tee -a "$GITHUB_STEP_SUMMARY"
|
|
872
|
+
}
|
|
873
|
+
if BODY="$(retry_transient curl -fsSL "$URL" 2> "$ERR")"; then
|
|
874
|
+
SITE="$(jq -r '.version // empty' <<< "$BODY" 2> /dev/null || true)"
|
|
875
|
+
if [ -z "$SITE" ]; then
|
|
876
|
+
echo "::warning::downloads sweep: $URL names no version — $FINAL is not handed on in this run"
|
|
877
|
+
elif [ "$SITE" = "$VERSION" ]; then
|
|
878
|
+
echo "downloads sweep: the site already names $VERSION — nothing to publish"
|
|
879
|
+
elif [ "$(printf '%s\n' "$SITE" "$VERSION" | sort -V | tail -n 1)" = "$SITE" ]; then
|
|
880
|
+
echo "downloads sweep: the site names $SITE, newer than $FINAL — nothing to publish" | tee -a "$GITHUB_STEP_SUMMARY"
|
|
881
|
+
else
|
|
882
|
+
hand_on "$FINAL is final on main but the site names $SITE"
|
|
883
|
+
fi
|
|
884
|
+
elif grep -q 'error: 404' "$ERR"; then
|
|
885
|
+
hand_on "$FINAL is final on main and the site has no latest.json for $APP"
|
|
886
|
+
else
|
|
887
|
+
echo "::warning::downloads sweep: could not read $URL from this runner ($(tail -n 1 "$ERR" 2> /dev/null)) — $FINAL is not handed on in this run; the next daily run retries"
|
|
888
|
+
fi
|
|
889
|
+
|
|
890
|
+
# Publishes every tag THIS run created — and a final the downloads sweep handed on (#669), which a
|
|
891
|
+
# person tagged and nothing published. In this run, never via a tag-push workflow: see "PUBLISHING
|
|
892
|
+
# HAPPENS IN THIS RUN" in the header.
|
|
893
|
+
- name: Publish GitHub Release (same run) [publish]
|
|
894
|
+
if: env.DRY_RUN != 'true' && (steps.cut.outputs.tag != '' || steps.finalize.outputs.tag != '' || steps.downloads-target.outputs.swept != '')
|
|
895
|
+
env:
|
|
896
|
+
TAGS: ${{ steps.cut.outputs.tag }} ${{ steps.finalize.outputs.tag }} ${{ steps.downloads-target.outputs.swept }}
|
|
785
897
|
run: |
|
|
786
898
|
set -euo pipefail
|
|
787
899
|
eval "$RETRY_TRANSIENT"
|