@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.9
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/LICENSE +21 -0
- package/README.md +310 -3
- package/README.vi.md +280 -0
- package/audit/audit.mjs +3035 -0
- package/package.json +26 -5
- package/templates/README.md +257 -0
- package/templates/adr-README.md +57 -0
- package/templates/branch-name.yml +51 -0
- package/templates/ci-laravel.yml +540 -0
- package/templates/ci-node.yml +291 -0
- package/templates/ci-python.yml +281 -0
- package/templates/deploy-xserver.yml +531 -0
- package/templates/dist-refs.yml +177 -0
- package/templates/docs-lint.mjs +993 -0
- package/templates/docs-lint.yml +55 -0
- package/templates/gotchas-d-README.md +41 -0
- package/templates/identity-vocabulary.example +58 -0
- package/templates/npx-launcher.mjs +213 -0
- package/templates/pre-commit-dispatch +88 -0
- package/templates/pre-commit-identity +267 -0
- package/templates/pre-push-guard +137 -0
- package/templates/release-auto.yml +475 -0
- package/templates/release-tag.yml +245 -0
- package/templates/repo-CLAUDE-block.md +21 -0
- package/tools/colab +13785 -0
- package/tools/lib/adopt.js +882 -0
- package/tools/lib/axis-authority.js +96 -0
- package/tools/lib/base-ci-verdict.js +93 -0
- package/tools/lib/blocked-by.js +262 -0
- package/tools/lib/branch-name.js +137 -0
- package/tools/lib/checklist.js +143 -0
- package/tools/lib/ci-cure.js +512 -0
- package/tools/lib/ci-grant.js +307 -0
- package/tools/lib/ci-verdict.js +113 -0
- package/tools/lib/claim-comments.js +212 -0
- package/tools/lib/claim-identity.js +195 -0
- package/tools/lib/codeowners.js +208 -0
- package/tools/lib/consumer-evidence.js +74 -0
- package/tools/lib/container-close.js +141 -0
- package/tools/lib/cure-diff.js +267 -0
- package/tools/lib/decision-record.js +335 -0
- package/tools/lib/dirty-owner.js +150 -0
- package/tools/lib/disposition.js +378 -0
- package/tools/lib/docs-only.js +156 -0
- package/tools/lib/exposure-shape.js +207 -0
- package/tools/lib/gate.js +80 -0
- package/tools/lib/git.js +1059 -0
- package/tools/lib/group-labels.js +120 -0
- package/tools/lib/hermetic.js +193 -0
- package/tools/lib/identity.js +187 -0
- package/tools/lib/install-check.js +259 -0
- package/tools/lib/instruction-file.js +302 -0
- package/tools/lib/journal.js +430 -0
- package/tools/lib/labels.js +653 -0
- package/tools/lib/landed.js +230 -0
- package/tools/lib/local-adopt.js +133 -0
- package/tools/lib/lockfile-drift.js +119 -0
- package/tools/lib/machine-trailer.js +83 -0
- package/tools/lib/machine.js +238 -0
- package/tools/lib/migration-grant.js +641 -0
- package/tools/lib/migration-paths.js +135 -0
- package/tools/lib/notify.js +188 -0
- package/tools/lib/npm-publish-guard.js +242 -0
- package/tools/lib/orphan-worktree.js +127 -0
- package/tools/lib/owner-branch.js +182 -0
- package/tools/lib/place.js +782 -0
- package/tools/lib/ports.js +167 -0
- package/tools/lib/procs.js +185 -0
- package/tools/lib/readiness.js +240 -0
- package/tools/lib/records.js +185 -0
- package/tools/lib/refs-brake.js +95 -0
- package/tools/lib/release-channel.js +99 -0
- package/tools/lib/release-cut.js +822 -0
- package/tools/lib/release-finalize.js +481 -0
- package/tools/lib/release-policy.js +358 -0
- package/tools/lib/release-tag.js +225 -0
- package/tools/lib/ship-batch.js +277 -0
- package/tools/lib/ship-roles.js +71 -0
- package/tools/lib/ship-target-sync.js +181 -0
- package/tools/lib/shipguard.js +317 -0
- package/tools/lib/shipped-branch.js +56 -0
- package/tools/lib/solo.js +213 -0
- package/tools/lib/squash.js +515 -0
- package/tools/lib/stale-base.js +70 -0
- package/tools/lib/stamp.js +740 -0
- package/tools/lib/state.js +262 -0
- package/tools/lib/teardown.js +83 -0
- package/tools/lib/trust-humans.js +104 -0
- package/tools/lib/util.js +98 -0
- package/tools/lib/wake.js +188 -0
- package/tools/lib/workflow-triggers.js +273 -0
- package/tools/lib/writes-authority.js +237 -0
- package/tools/lib/yaml.js +101 -0
- package/bin/cli.js +0 -3
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
# Dist refs — TEMPLATE. Copy me into your repo at .github/workflows/dist-refs.yml.
|
|
2
|
+
#
|
|
3
|
+
# This is a starting point, not a dependency. Once you copy it, YOU OWN THIS FILE.
|
|
4
|
+
# Edit it freely; nothing calls it remotely and nothing will update it for you.
|
|
5
|
+
#
|
|
6
|
+
# It is a `workflow_call` workflow, but only ever called from INSIDE your own repo
|
|
7
|
+
# (`uses: ./.github/workflows/dist-refs.yml`) — never from the handbook. Copy-and-own still
|
|
8
|
+
# holds: the file lives, in full, in the repo that runs it (templates/README.md).
|
|
9
|
+
#
|
|
10
|
+
# WHAT IT IS FOR. CONVENTIONS.md §6, *Distribution* (#442): every distributed tool installs with
|
|
11
|
+
# `npx`. A PRIVATE repo shipping a COMPILED tool cannot use npm platform packages (`@<org>` on
|
|
12
|
+
# public npm is always public, #432), and GitHub Release assets are not an install path. So the
|
|
13
|
+
# binaries live in the same repo, as DIST REFS:
|
|
14
|
+
#
|
|
15
|
+
# refs/tags/dist/vX.Y.Z/<os>-<arch> one orphan commit per platform, holding exactly the
|
|
16
|
+
# files of that platform's build artifact plus a
|
|
17
|
+
# SHA256SUMS over them. No parent: it never touches
|
|
18
|
+
# trunk history, and nothing on trunk ever points at it.
|
|
19
|
+
#
|
|
20
|
+
# `npx github:<org>/<repo>#vX.Y.Z` then installs the repo's root package.json, whose `bin` is
|
|
21
|
+
# templates/npx-launcher.mjs: it fetches exactly one of these refs with the git credentials npx
|
|
22
|
+
# just used, verifies SHA256SUMS, installs the binary to a stable per-user path, and execs it.
|
|
23
|
+
# Repository read access is the only lock — the same lock as the source.
|
|
24
|
+
#
|
|
25
|
+
# <os>-<arch> is Node's own `${process.platform}-${process.arch}` (darwin-arm64, linux-x64,
|
|
26
|
+
# win32-x64, …) — the same names npm's `os`/`cpu` fields use, and what the launcher computes.
|
|
27
|
+
#
|
|
28
|
+
# HOW TO CALL IT — from the SAME run that cut the release tag. A tag pushed with GITHUB_TOKEN
|
|
29
|
+
# triggers no other workflow, so "build on the tag push" silently never runs for a tag your
|
|
30
|
+
# release workflow made (CONVENTIONS.md §6). Build every platform in that run, upload one
|
|
31
|
+
# artifact per platform named `<artifact-prefix><os>-<arch>`, then:
|
|
32
|
+
#
|
|
33
|
+
# dist:
|
|
34
|
+
# needs: [build] # your matrix build, one upload-artifact per platform
|
|
35
|
+
# uses: ./.github/workflows/dist-refs.yml
|
|
36
|
+
# permissions:
|
|
37
|
+
# contents: write
|
|
38
|
+
# with:
|
|
39
|
+
# version: ${{ needs.release.outputs.tag }} # vX.Y.Z or vX.Y.Z-rc.N
|
|
40
|
+
# platforms: darwin-arm64 darwin-x64 linux-x64 linux-arm64 win32-x64
|
|
41
|
+
# bin: mytool # EDIT: the launcher's binary name
|
|
42
|
+
#
|
|
43
|
+
# Each artifact must hold the binary at its top level, named `<bin>` (`<bin>.exe` on win32-*).
|
|
44
|
+
# Anything else in the artifact rides along in the same ref and is covered by SHA256SUMS.
|
|
45
|
+
#
|
|
46
|
+
# REFUSALS — each is a red run with the reason, never a silent partial:
|
|
47
|
+
# - the repository is public, or its visibility cannot be read. A public compiled tool ships
|
|
48
|
+
# per-platform npm packages instead (CONVENTIONS.md §6, *Distribution*); a binary pushed
|
|
49
|
+
# into a public repo's refs is a download anyone can take.
|
|
50
|
+
# - `version` is not vX.Y.Z / vX.Y.Z-rc.N, or that tag does not exist on origin. A dist ref
|
|
51
|
+
# names a release; it never invents one.
|
|
52
|
+
# - a listed platform has no artifact, or its artifact lacks the binary.
|
|
53
|
+
#
|
|
54
|
+
# IT NEVER MOVES A REF. A dist ref that already exists is left alone and reported — like a
|
|
55
|
+
# release tag, it is immutable once published (re-running a failed job pushes only the missing
|
|
56
|
+
# ones). It never writes a commit to any branch.
|
|
57
|
+
#
|
|
58
|
+
# COST TO KNOW. Dist refs are tags, so a plain `git clone` of the repo (which fetches every
|
|
59
|
+
# tag) downloads every platform of every release; later plain fetches do not (a tag is followed
|
|
60
|
+
# only into fetched history, and an orphan is never in it). The launcher's own fetch is
|
|
61
|
+
# `--depth 1 --no-tags` of one ref and pays for one binary. Contributors who mind clone with
|
|
62
|
+
# `--no-tags`.
|
|
63
|
+
#
|
|
64
|
+
# The push step below is plain bash over git plumbing, with every input in `env:` — that is
|
|
65
|
+
# what lets tools/lib/dist-refs-template.test.js run this exact script against a local origin.
|
|
66
|
+
|
|
67
|
+
name: Dist refs
|
|
68
|
+
|
|
69
|
+
on:
|
|
70
|
+
workflow_call:
|
|
71
|
+
inputs:
|
|
72
|
+
version:
|
|
73
|
+
description: 'Release tag the binaries belong to: vX.Y.Z or vX.Y.Z-rc.N. Must already exist on origin.'
|
|
74
|
+
required: true
|
|
75
|
+
type: string
|
|
76
|
+
platforms:
|
|
77
|
+
description: 'Space-separated <os>-<arch> list (Node process.platform-process.arch), one artifact each.'
|
|
78
|
+
required: true
|
|
79
|
+
type: string
|
|
80
|
+
bin:
|
|
81
|
+
description: 'Binary name inside each artifact (win32-* adds .exe).'
|
|
82
|
+
required: true
|
|
83
|
+
type: string
|
|
84
|
+
artifact-prefix:
|
|
85
|
+
description: 'Artifact name = <artifact-prefix><os>-<arch>.'
|
|
86
|
+
required: false
|
|
87
|
+
type: string
|
|
88
|
+
default: 'dist-'
|
|
89
|
+
|
|
90
|
+
permissions:
|
|
91
|
+
contents: write
|
|
92
|
+
|
|
93
|
+
jobs:
|
|
94
|
+
push:
|
|
95
|
+
name: Push dist refs
|
|
96
|
+
runs-on: ubuntu-latest
|
|
97
|
+
steps:
|
|
98
|
+
# Visibility from the API, never guessed: `github.event.repository.private` is absent on
|
|
99
|
+
# some caller events (schedule), and an absent value must refuse, not pass.
|
|
100
|
+
- name: Refuse a public (or unreadable) repository
|
|
101
|
+
env:
|
|
102
|
+
GH_TOKEN: ${{ github.token }}
|
|
103
|
+
REPO: ${{ github.repository }}
|
|
104
|
+
run: |
|
|
105
|
+
set -euo pipefail
|
|
106
|
+
vis="$(gh api "repos/${REPO}" --jq '.visibility' 2>/dev/null || true)"
|
|
107
|
+
case "$vis" in
|
|
108
|
+
private|internal) echo "repository visibility: $vis — dist refs allowed" ;;
|
|
109
|
+
public) echo "::error::${REPO} is public. Dist refs are for PRIVATE compiled tools; a public one ships per-platform npm packages (CONVENTIONS.md §6, Distribution)."; exit 1 ;;
|
|
110
|
+
*) echo "::error::could not read ${REPO}'s visibility (got '${vis}') — refusing rather than guessing (CONVENTIONS.md §6, Distribution)."; exit 1 ;;
|
|
111
|
+
esac
|
|
112
|
+
|
|
113
|
+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
114
|
+
with:
|
|
115
|
+
fetch-depth: 1
|
|
116
|
+
|
|
117
|
+
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
|
|
118
|
+
with:
|
|
119
|
+
pattern: ${{ inputs.artifact-prefix }}*
|
|
120
|
+
path: dist-in
|
|
121
|
+
|
|
122
|
+
- name: Push one orphan ref per platform
|
|
123
|
+
env:
|
|
124
|
+
VERSION: ${{ inputs.version }}
|
|
125
|
+
PLATFORMS: ${{ inputs.platforms }}
|
|
126
|
+
BIN: ${{ inputs.bin }}
|
|
127
|
+
PREFIX: ${{ inputs.artifact-prefix }}
|
|
128
|
+
ARTIFACTS: dist-in
|
|
129
|
+
REMOTE: origin
|
|
130
|
+
GIT_AUTHOR_NAME: github-actions[bot]
|
|
131
|
+
GIT_AUTHOR_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com
|
|
132
|
+
GIT_COMMITTER_NAME: github-actions[bot]
|
|
133
|
+
GIT_COMMITTER_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com
|
|
134
|
+
run: |
|
|
135
|
+
set -euo pipefail
|
|
136
|
+
# --- dist-refs push script (begin) ---
|
|
137
|
+
if ! printf '%s' "$VERSION" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+(-rc\.[0-9]+)?$'; then
|
|
138
|
+
echo "::error::version '$VERSION' is not vX.Y.Z or vX.Y.Z-rc.N"; exit 1
|
|
139
|
+
fi
|
|
140
|
+
if [ -z "$(git ls-remote --tags "$REMOTE" "refs/tags/$VERSION")" ]; then
|
|
141
|
+
echo "::error::tag $VERSION does not exist on $REMOTE — dist refs name a release, they never invent one"; exit 1
|
|
142
|
+
fi
|
|
143
|
+
[ -n "$PLATFORMS" ] || { echo "::error::no platforms given"; exit 1; }
|
|
144
|
+
|
|
145
|
+
# Check every platform before pushing any, so a missing artifact never leaves a partial set.
|
|
146
|
+
for plat in $PLATFORMS; do
|
|
147
|
+
dir="$ARTIFACTS/$PREFIX$plat"
|
|
148
|
+
exe="$BIN"; case "$plat" in win32-*) exe="$BIN.exe" ;; esac
|
|
149
|
+
[ -f "$dir/$exe" ] || { echo "::error::$plat: no $exe in artifact $PREFIX$plat ($dir)"; exit 1; }
|
|
150
|
+
done
|
|
151
|
+
|
|
152
|
+
pushed=0; kept=0
|
|
153
|
+
for plat in $PLATFORMS; do
|
|
154
|
+
ref="refs/tags/dist/$VERSION/$plat"
|
|
155
|
+
if [ -n "$(git ls-remote "$REMOTE" "$ref")" ]; then
|
|
156
|
+
echo "::notice::$ref already exists — left alone (dist refs never move)"
|
|
157
|
+
kept=$((kept + 1)); continue
|
|
158
|
+
fi
|
|
159
|
+
dir="$ARTIFACTS/$PREFIX$plat"
|
|
160
|
+
sums="$(mktemp)"; tree_in="$(mktemp)"
|
|
161
|
+
# Top-level files only, sorted, so the tree and SHA256SUMS are deterministic.
|
|
162
|
+
for f in $(cd "$dir" && find . -maxdepth 1 -type f ! -name SHA256SUMS | sed 's|^\./||' | LC_ALL=C sort); do
|
|
163
|
+
sha="$(sha256sum "$dir/$f" | cut -d' ' -f1)"
|
|
164
|
+
printf '%s %s\n' "$sha" "$f" >> "$sums"
|
|
165
|
+
blob="$(git hash-object -w "$dir/$f")"
|
|
166
|
+
printf '100755 blob %s\t%s\n' "$blob" "$f" >> "$tree_in"
|
|
167
|
+
done
|
|
168
|
+
printf '100644 blob %s\tSHA256SUMS\n' "$(git hash-object -w "$sums")" >> "$tree_in"
|
|
169
|
+
tree="$(LC_ALL=C sort -k4 "$tree_in" | git mktree)"
|
|
170
|
+
commit="$(git commit-tree "$tree" -m "dist $VERSION $plat")" # no -p: an orphan
|
|
171
|
+
git push "$REMOTE" "$commit:$ref"
|
|
172
|
+
echo "pushed $ref -> $commit"
|
|
173
|
+
pushed=$((pushed + 1))
|
|
174
|
+
rm -f "$sums" "$tree_in"
|
|
175
|
+
done
|
|
176
|
+
echo "dist refs for $VERSION: $pushed pushed, $kept already present"
|
|
177
|
+
# --- dist-refs push script (end) ---
|