@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,267 @@
|
|
|
1
|
+
#!/bin/sh
|
|
2
|
+
# pre-commit-identity — refuse to commit content that names something the operator has
|
|
3
|
+
# decided must never be published: a machine hostname, an account handle, an absolute home
|
|
4
|
+
# path, an internal domain, a customer or partner name.
|
|
5
|
+
#
|
|
6
|
+
# WHY THIS EXISTS. Every automated gate in a normal repo guards SECRETS. A secret scanner
|
|
7
|
+
# finds credentials, and it finds them well — but a hostname is not a credential, an
|
|
8
|
+
# account handle is not a credential, and a customer's name is not a credential. Those pass
|
|
9
|
+
# every gate, land in a public repo, and stay there: git history cannot be recalled once
|
|
10
|
+
# anything is cloned or forked. This scans the one class the secret scanner structurally
|
|
11
|
+
# cannot see.
|
|
12
|
+
#
|
|
13
|
+
# WHY PRE-COMMIT AND NOT CI. CI is too late. By the time a workflow runs, the commit exists
|
|
14
|
+
# and may already be pushed, and the only remedy is rewriting published history. Pre-commit
|
|
15
|
+
# is the last point at which nothing has left the machine.
|
|
16
|
+
#
|
|
17
|
+
# ⚠ THE SCANNER SHIPS; THE VOCABULARY DOES NOT. A list of the exact strings an organisation
|
|
18
|
+
# considers sensitive is itself sensitive — it is a precise index of what to look for. This
|
|
19
|
+
# script therefore takes the vocabulary BY PATH, from a file the operator keeps OUTSIDE the
|
|
20
|
+
# repo. Never commit a real one. `templates/identity-vocabulary.example` is an invented
|
|
21
|
+
# list, safe to copy and then edit in place outside the working tree.
|
|
22
|
+
#
|
|
23
|
+
# WHERE THE VOCABULARY COMES FROM (first hit wins):
|
|
24
|
+
# 1. $COLAB_IDENTITY_VOCAB — explicit, per invocation
|
|
25
|
+
# 2. git config colab.identityVocabulary — explicit, per clone (lives in .git/config,
|
|
26
|
+
# so it is machine-local and never synced —
|
|
27
|
+
# the same property core.hooksPath relies on)
|
|
28
|
+
# 3. ${COLAB_HOME:-~/.colab}/identity-vocabulary — the machine-wide default
|
|
29
|
+
#
|
|
30
|
+
# If 1 or 2 names a file that cannot be read, this REFUSES the commit: you declared a
|
|
31
|
+
# vocabulary and it is not there, so the check cannot run, and a check that cannot run must
|
|
32
|
+
# never pass silently. If only 3 applies and the file is absent, the machine simply has no
|
|
33
|
+
# vocabulary configured — it warns on every commit and exits 0, exactly as the gitleaks
|
|
34
|
+
# hook does when gitleaks is not installed.
|
|
35
|
+
#
|
|
36
|
+
# INSTALL — three shapes, pick one:
|
|
37
|
+
# a. Alongside an existing pre-commit hook (the usual case), via the dispatcher:
|
|
38
|
+
# cp templates/pre-commit-dispatch <hooks>/pre-commit # see its own header
|
|
39
|
+
# cp templates/pre-commit-identity <hooks>/pre-commit.d/20-identity
|
|
40
|
+
# chmod +x <hooks>/pre-commit <hooks>/pre-commit.d/*
|
|
41
|
+
# b. As the whole hook, in a repo that has no pre-commit hook at all:
|
|
42
|
+
# cp templates/pre-commit-identity .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
|
|
43
|
+
# c. Additionally as a commit-msg hook — a commit MESSAGE is published too, and unlike a
|
|
44
|
+
# file it cannot be corrected afterwards without rewriting history:
|
|
45
|
+
# cp templates/pre-commit-identity .git/hooks/commit-msg && chmod +x .git/hooks/commit-msg
|
|
46
|
+
# (git passes the message file as $1; this script scans a file when given one.)
|
|
47
|
+
# <hooks> is `git config core.hooksPath` if you set one, else `.git/hooks`.
|
|
48
|
+
#
|
|
49
|
+
# WHAT IT SCANS. With no argument: the STAGED diff's added lines, plus the staged path
|
|
50
|
+
# names themselves (a directory named after a customer names them just as loudly as a line
|
|
51
|
+
# of prose). Deleted lines and unstaged work are not scanned — this is about what the commit
|
|
52
|
+
# publishes. With a file argument: that file, whole.
|
|
53
|
+
#
|
|
54
|
+
# ON A MATCH. The commit is refused, and the matched text is REDACTED in the output: the
|
|
55
|
+
# whole point is that the string should not be republished, and a terminal, a shell history
|
|
56
|
+
# and a CI log are all places it would then live. You get file:line and the vocabulary entry
|
|
57
|
+
# number — you own that file, so the entry number is all you need. COLAB_IDENTITY_SHOW=1
|
|
58
|
+
# prints the matched term when you genuinely cannot tell what fired.
|
|
59
|
+
#
|
|
60
|
+
# OVERRIDE — per invocation, never persistent:
|
|
61
|
+
# COLAB_IDENTITY_OK=1 git commit ...
|
|
62
|
+
# It is deliberately an environment variable and NOT an in-file marker (`# privacy-ok` and
|
|
63
|
+
# friends). Three reasons: a marker is persistent, so it silently allows every future commit
|
|
64
|
+
# touching that line; a marker is itself committed, which publishes an arrow pointing at the
|
|
65
|
+
# thing it excuses; and a marker can be added by the same diff that carries the leak, which
|
|
66
|
+
# means the scanner can be disabled by the content it is scanning. An environment variable
|
|
67
|
+
# is none of those — it is one act, by the person at the keyboard, for one commit.
|
|
68
|
+
# `git commit --no-verify` also works, but it disables EVERY hook including the secret scan;
|
|
69
|
+
# this override is narrower on purpose. Setting it is the operator's call — an agent that
|
|
70
|
+
# hits this block surfaces it and stops, it does not set the variable for itself.
|
|
71
|
+
#
|
|
72
|
+
# EXIT: 0 clean (or overridden, or no vocabulary configured), 1 blocked.
|
|
73
|
+
|
|
74
|
+
set -eu
|
|
75
|
+
|
|
76
|
+
MIN_TERM_LEN=3 # a 1-2 character term matches nearly everything; refuse it as a mistake
|
|
77
|
+
MAX_REPORTED=20 # a flood of hits is not more informative than the first twenty
|
|
78
|
+
|
|
79
|
+
say() { printf '%s\n' "$*" >&2; }
|
|
80
|
+
|
|
81
|
+
# --------------------------------------------------------------- resolve the vocabulary
|
|
82
|
+
vocab=""
|
|
83
|
+
vocab_src=""
|
|
84
|
+
vocab_explicit=0
|
|
85
|
+
|
|
86
|
+
if [ -n "${COLAB_IDENTITY_VOCAB:-}" ]; then
|
|
87
|
+
vocab=$COLAB_IDENTITY_VOCAB
|
|
88
|
+
vocab_src="COLAB_IDENTITY_VOCAB"
|
|
89
|
+
vocab_explicit=1
|
|
90
|
+
else
|
|
91
|
+
cfg=$(git config --get colab.identityVocabulary 2>/dev/null || true)
|
|
92
|
+
if [ -n "$cfg" ]; then
|
|
93
|
+
vocab=$cfg
|
|
94
|
+
vocab_src="git config colab.identityVocabulary"
|
|
95
|
+
vocab_explicit=1
|
|
96
|
+
else
|
|
97
|
+
vocab="${COLAB_HOME:-$HOME/.colab}/identity-vocabulary"
|
|
98
|
+
vocab_src="default"
|
|
99
|
+
fi
|
|
100
|
+
fi
|
|
101
|
+
|
|
102
|
+
# `~` is not expanded inside a git config value or an exported variable.
|
|
103
|
+
case $vocab in
|
|
104
|
+
"~/"*) vocab="$HOME/${vocab#\~/}" ;;
|
|
105
|
+
esac
|
|
106
|
+
|
|
107
|
+
if [ ! -r "$vocab" ]; then
|
|
108
|
+
if [ "$vocab_explicit" -eq 1 ]; then
|
|
109
|
+
say "❌ identity scan: the vocabulary named by $vocab_src cannot be read — commit BLOCKED."
|
|
110
|
+
say " path: $vocab"
|
|
111
|
+
say " A configured check that cannot run is not a pass. Fix the path, or unset it."
|
|
112
|
+
exit 1
|
|
113
|
+
fi
|
|
114
|
+
say "⚠ identity scan: no vocabulary at $vocab — nothing was scanned for identity."
|
|
115
|
+
say " Create one (start from templates/identity-vocabulary.example, keep it OUT of any repo)"
|
|
116
|
+
say " or point at yours: git config colab.identityVocabulary <path>"
|
|
117
|
+
exit 0
|
|
118
|
+
fi
|
|
119
|
+
|
|
120
|
+
# ------------------------------------------------------------------------ what to scan
|
|
121
|
+
tmp=$(mktemp -d "${TMPDIR:-/tmp}/identity-scan.XXXXXX")
|
|
122
|
+
trap 'rm -rf "$tmp"' EXIT
|
|
123
|
+
trap 'rm -rf "$tmp"; exit 130' INT
|
|
124
|
+
trap 'rm -rf "$tmp"; exit 143' TERM
|
|
125
|
+
|
|
126
|
+
subject="$tmp/subject" # one record per line: <location><TAB><text>
|
|
127
|
+
: > "$subject"
|
|
128
|
+
|
|
129
|
+
if [ "$#" -gt 0 ] && [ -n "${1:-}" ]; then
|
|
130
|
+
if [ ! -r "$1" ]; then
|
|
131
|
+
say "❌ identity scan: cannot read $1 — commit BLOCKED (the check could not run)."
|
|
132
|
+
exit 1
|
|
133
|
+
fi
|
|
134
|
+
awk '{ printf "%s:%d\t%s\n", FILENAME, FNR, $0 }' "$1" > "$subject"
|
|
135
|
+
else
|
|
136
|
+
# Staged PATHS. A path is content too, and it is the one kind a diff of added lines
|
|
137
|
+
# never shows: renaming a directory after a customer adds no line anywhere.
|
|
138
|
+
#
|
|
139
|
+
# Reported by ORDINAL, never by name — the path IS the offending string here, so printing
|
|
140
|
+
# it as the location would republish exactly what the redaction exists to withhold. The
|
|
141
|
+
# ordinal is the line number in the listing below, which the message tells you how to run.
|
|
142
|
+
git diff --cached --name-only --diff-filter=ACMR \
|
|
143
|
+
| awk 'NF { printf "(staged path %d)\t%s\n", FNR, $0 }' >> "$subject"
|
|
144
|
+
|
|
145
|
+
# Staged ADDED LINES, with real file:line locations reconstructed from the hunk headers.
|
|
146
|
+
# --unified=0 so there is no context: a neighbouring line somebody else wrote is not
|
|
147
|
+
# this commit's to answer for.
|
|
148
|
+
git diff --cached --unified=0 --diff-filter=ACMR \
|
|
149
|
+
| awk '
|
|
150
|
+
/^\+\+\+ \/dev\/null/ { path = ""; next }
|
|
151
|
+
/^\+\+\+ / { path = substr($0, 7); next } # strips the "+++ b/" prefix
|
|
152
|
+
/^@@ / { n = $3; sub(/^\+/, "", n); sub(/,.*$/, "", n); ln = n + 0; next }
|
|
153
|
+
/^\+/ { printf "%s:%d\t%s\n", (path == "" ? "(unknown)" : path), ln, substr($0, 2); ln++; next }
|
|
154
|
+
' >> "$subject"
|
|
155
|
+
fi
|
|
156
|
+
|
|
157
|
+
# ------------------------------------------------------------------- parse the vocabulary
|
|
158
|
+
# One term per line. Blank lines and lines whose first non-space character is `#` are
|
|
159
|
+
# comments. A leading `re:` marks an extended regular expression; everything else is a
|
|
160
|
+
# fixed string. Matching is case-insensitive and by SUBSTRING, deliberately: a hostname
|
|
161
|
+
# appears inside URLs, paths and identifiers with no word boundary anywhere near it.
|
|
162
|
+
# A term is kept verbatim apart from surrounding whitespace, so it may contain `#`.
|
|
163
|
+
terms="$tmp/terms"
|
|
164
|
+
awk '
|
|
165
|
+
{
|
|
166
|
+
line = $0
|
|
167
|
+
sub(/\r$/, "", line)
|
|
168
|
+
sub(/^[ \t]+/, "", line); sub(/[ \t]+$/, "", line)
|
|
169
|
+
if (line == "" || substr(line, 1, 1) == "#") next
|
|
170
|
+
kind = "fixed"
|
|
171
|
+
if (substr(line, 1, 3) == "re:") { kind = "regex"; line = substr(line, 4); sub(/^[ \t]+/, "", line) }
|
|
172
|
+
if (line == "") next
|
|
173
|
+
gsub(/\t/, " ", line) # tab separates the fields of the record below
|
|
174
|
+
printf "%d\t%s\t%s\n", FNR, kind, line
|
|
175
|
+
}' "$vocab" > "$terms"
|
|
176
|
+
|
|
177
|
+
# ------------------------------------------------------------------------------- scan
|
|
178
|
+
hits="$tmp/hits" # <entry><TAB><chars><TAB><location><TAB><term>
|
|
179
|
+
: > "$hits"
|
|
180
|
+
problems="$tmp/problems"
|
|
181
|
+
: > "$problems"
|
|
182
|
+
|
|
183
|
+
TAB=$(printf '\t')
|
|
184
|
+
while IFS="$TAB" read -r entry kind value; do
|
|
185
|
+
[ -n "${entry:-}" ] || continue
|
|
186
|
+
if [ "${#value}" -lt "$MIN_TERM_LEN" ]; then
|
|
187
|
+
printf 'entry %s is only %s character(s) — too short to be a term (minimum %s)\n' \
|
|
188
|
+
"$entry" "${#value}" "$MIN_TERM_LEN" >> "$problems"
|
|
189
|
+
continue
|
|
190
|
+
fi
|
|
191
|
+
if ! found=$(
|
|
192
|
+
TERM_VALUE="$value" TERM_KIND="$kind" awk '
|
|
193
|
+
BEGIN { t = tolower(ENVIRON["TERM_VALUE"]); k = ENVIRON["TERM_KIND"] }
|
|
194
|
+
{
|
|
195
|
+
i = index($0, "\t")
|
|
196
|
+
if (i == 0) next
|
|
197
|
+
loc = substr($0, 1, i - 1)
|
|
198
|
+
text = tolower(substr($0, i + 1))
|
|
199
|
+
if (k == "regex") { if (text ~ t) print loc }
|
|
200
|
+
else if (index(text, t) > 0) { print loc }
|
|
201
|
+
}' "$subject" 2>/dev/null
|
|
202
|
+
); then
|
|
203
|
+
printf 'entry %s is not a valid regular expression\n' "$entry" >> "$problems"
|
|
204
|
+
continue
|
|
205
|
+
fi
|
|
206
|
+
[ -n "$found" ] || continue
|
|
207
|
+
printf '%s\n' "$found" | while IFS= read -r loc; do
|
|
208
|
+
[ -n "$loc" ] || continue
|
|
209
|
+
printf '%s\t%s\t%s\t%s\n' "$entry" "${#value}" "$loc" "$value" >> "$hits"
|
|
210
|
+
done
|
|
211
|
+
done < "$terms"
|
|
212
|
+
|
|
213
|
+
# ---------------------------------------------------------------------------- verdict
|
|
214
|
+
if [ -s "$problems" ]; then
|
|
215
|
+
say "❌ identity scan: the vocabulary itself is unusable — commit BLOCKED."
|
|
216
|
+
while IFS= read -r p; do say " $p"; done < "$problems"
|
|
217
|
+
say " Vocabulary: $vocab ($vocab_src)"
|
|
218
|
+
say " Fix those entries. This is not what COLAB_IDENTITY_OK is for — a broken"
|
|
219
|
+
say " vocabulary is not a false positive, it is a check that did not run."
|
|
220
|
+
exit 1
|
|
221
|
+
fi
|
|
222
|
+
|
|
223
|
+
if [ ! -s "$hits" ]; then
|
|
224
|
+
exit 0
|
|
225
|
+
fi
|
|
226
|
+
|
|
227
|
+
total=$(wc -l < "$hits" | tr -d ' ')
|
|
228
|
+
if [ "${COLAB_IDENTITY_OK:-}" = "1" ]; then
|
|
229
|
+
say "⚠ identity scan: $total match(es) allowed through by COLAB_IDENTITY_OK=1."
|
|
230
|
+
else
|
|
231
|
+
say "❌ identity scan: staged content names something the vocabulary forbids — commit BLOCKED."
|
|
232
|
+
fi
|
|
233
|
+
|
|
234
|
+
shown=0
|
|
235
|
+
while IFS="$TAB" read -r entry chars loc value; do
|
|
236
|
+
shown=$((shown + 1))
|
|
237
|
+
if [ "$shown" -gt "$MAX_REPORTED" ]; then continue; fi
|
|
238
|
+
if [ "${COLAB_IDENTITY_SHOW:-}" = "1" ]; then
|
|
239
|
+
say " $loc — vocabulary entry $entry: $value"
|
|
240
|
+
else
|
|
241
|
+
say " $loc — vocabulary entry $entry ($chars chars, redacted)"
|
|
242
|
+
fi
|
|
243
|
+
done < "$hits"
|
|
244
|
+
if [ "$total" -gt "$MAX_REPORTED" ]; then
|
|
245
|
+
say " … and $((total - MAX_REPORTED)) more."
|
|
246
|
+
fi
|
|
247
|
+
|
|
248
|
+
if [ "${COLAB_IDENTITY_OK:-}" = "1" ]; then
|
|
249
|
+
exit 0
|
|
250
|
+
fi
|
|
251
|
+
|
|
252
|
+
if grep -q '(staged path ' "$hits" 2>/dev/null; then
|
|
253
|
+
say " Resolve a (staged path N) with:"
|
|
254
|
+
say " git diff --cached --name-only --diff-filter=ACMR | sed -n Np"
|
|
255
|
+
fi
|
|
256
|
+
|
|
257
|
+
say ""
|
|
258
|
+
say " The matched text is redacted on purpose — printing it here would republish it into"
|
|
259
|
+
say " your terminal, your shell history and any log that captures them. Vocabulary:"
|
|
260
|
+
say " $vocab ($vocab_src). COLAB_IDENTITY_SHOW=1 unredacts it locally."
|
|
261
|
+
say ""
|
|
262
|
+
say " • Rewrite it with an invented value — a fixture asserts shape, never provenance, so"
|
|
263
|
+
say " an invented value tests exactly as well (CONVENTIONS.md §9)."
|
|
264
|
+
say " • Genuinely a false positive? COLAB_IDENTITY_OK=1 git commit ..."
|
|
265
|
+
say " That override is the operator's call. An agent surfaces this block; it does not"
|
|
266
|
+
say " set the variable for itself."
|
|
267
|
+
exit 1
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
#!/bin/sh
|
|
2
|
+
# pre-push-guard — refuse raw `git push` to protected branches unless a sanctioned path set the env.
|
|
3
|
+
# TRUNK (from .github/project.yml): allowed by COLAB_SHIP=1 (colab ship) or COLAB_HUMAN=1.
|
|
4
|
+
# INTEGRATION lines (project.yml `integration:`): same rule as trunk. Work merges into a declared
|
|
5
|
+
# line exactly the way it merges into trunk — via `colab ship` — so it gets the same door. The
|
|
6
|
+
# line is a DEVELOPMENT integration point: guarding it protects the branch, and nothing here
|
|
7
|
+
# gives it any path to production.
|
|
8
|
+
# MAIN, on tier A and C (trunk != main): allowed by COLAB_PROMOTE=1 (colab promote) or COLAB_HUMAN=1.
|
|
9
|
+
# COLAB_SHIP does NOT open main — ship is trunk/line-only by design.
|
|
10
|
+
# The guard keys on `trunk != main`, never on the tier letter, so tier C is covered
|
|
11
|
+
# automatically — main there is what promotion deploys, so it needs the gate most.
|
|
12
|
+
# RELEASE CHANNELS `next` and `stable` (#445): allowed by COLAB_RELEASE=1 (`colab release cut` moves
|
|
13
|
+
# `next`, `colab release finalize` moves `stable`) or COLAB_HUMAN=1. Nothing else writes them —
|
|
14
|
+
# they name the newest candidate and the newest final, and a hand push makes them lie. A repo that
|
|
15
|
+
# uses a branch of either name for something else edits its copy of this hook (copy-and-own).
|
|
16
|
+
# On tier B (trunk == main) the trunk rule already covers main. Non-protected pushes always pass.
|
|
17
|
+
# Missing .github/project.yml → degrade to ALLOW (with a warning) rather than block work.
|
|
18
|
+
#
|
|
19
|
+
# The variables named above are set BY A TOOL (`colab ship`, `colab promote`, `colab release`) or BY A PERSON at
|
|
20
|
+
# the keyboard — never by an agent reading this file or one of the refusals below. COLAB_SHIP is a
|
|
21
|
+
# process-identity assertion, not a permission: typed by hand it claims preconditions nothing ran.
|
|
22
|
+
# The refusal messages below therefore name the remedy and not the variable (#322) — this header is
|
|
23
|
+
# the documentation lane, which a human consults deliberately and an error message is not.
|
|
24
|
+
#
|
|
25
|
+
# Install (copy-and-own, per repo):
|
|
26
|
+
# cp templates/pre-push-guard .git/hooks/pre-push && chmod +x .git/hooks/pre-push
|
|
27
|
+
# # or, if you use a shared hooks dir: cp templates/pre-push-guard "$(git config core.hooksPath)/pre-push"
|
|
28
|
+
set -eu
|
|
29
|
+
|
|
30
|
+
root=$(git rev-parse --show-toplevel 2>/dev/null || echo .)
|
|
31
|
+
pj="$root/.github/project.yml"
|
|
32
|
+
if [ ! -f "$pj" ]; then
|
|
33
|
+
echo "pre-push-guard: no .github/project.yml — allowing push (cannot determine trunk)." >&2
|
|
34
|
+
exit 0
|
|
35
|
+
fi
|
|
36
|
+
|
|
37
|
+
trunk=$(sed -n 's/^trunk:[[:space:]]*//p' "$pj" | head -1 | tr -d "\"'" | awk '{print $1}')
|
|
38
|
+
[ -z "$trunk" ] && exit 0
|
|
39
|
+
|
|
40
|
+
# Declared integration lines, in either YAML list form: `integration: [a, b]` or `integration:`
|
|
41
|
+
# followed by ` - a` lines. Same minimal subset the audit tool and the CLI read.
|
|
42
|
+
integration=$(awk '
|
|
43
|
+
/^integration:[[:space:]]*\[/ {
|
|
44
|
+
s = $0; sub(/^[^[]*\[/, "", s); sub(/\].*$/, "", s); gsub(/[,"'"'"']/, " ", s); print s; next
|
|
45
|
+
}
|
|
46
|
+
/^integration:[[:space:]]*$/ { inlist = 1; next }
|
|
47
|
+
inlist && /^[[:space:]]*-[[:space:]]*/ {
|
|
48
|
+
s = $0; sub(/^[[:space:]]*-[[:space:]]*/, "", s); sub(/[[:space:]]*#.*$/, "", s)
|
|
49
|
+
gsub(/["'"'"']/, "", s); print s; next
|
|
50
|
+
}
|
|
51
|
+
inlist && /^[^[:space:]#]/ { inlist = 0 }
|
|
52
|
+
' "$pj")
|
|
53
|
+
|
|
54
|
+
# Which protected refs are being pushed? (stdin: <localref> <localsha> <remoteref> <remotesha>)
|
|
55
|
+
pushing_trunk=0
|
|
56
|
+
pushing_main=0
|
|
57
|
+
pushing_line=""
|
|
58
|
+
pushing_channel=""
|
|
59
|
+
while read -r _localref _localsha remoteref _remotesha; do
|
|
60
|
+
case "${remoteref:-}" in
|
|
61
|
+
refs/heads/"$trunk") pushing_trunk=1 ;;
|
|
62
|
+
refs/heads/main) pushing_main=1 ;;
|
|
63
|
+
refs/heads/next) pushing_channel=next ;;
|
|
64
|
+
refs/heads/stable) pushing_channel=stable ;;
|
|
65
|
+
esac
|
|
66
|
+
for line in $integration; do
|
|
67
|
+
if [ "${remoteref:-}" = "refs/heads/$line" ]; then pushing_line="$line"; fi
|
|
68
|
+
done
|
|
69
|
+
done
|
|
70
|
+
|
|
71
|
+
# A REFUSAL NAMES THE REMEDY, NEVER THE DOOR (#322). Each message below used to end with the
|
|
72
|
+
# environment variable that defeats it. That is a bypass printed at the exact moment its reader has
|
|
73
|
+
# run out of ideas, and it was taken: two independent sessions in one day set COLAB_SHIP=1 by hand
|
|
74
|
+
# after this hook refused them, one of them reporting it as ordinary housekeeping. Neither had read
|
|
75
|
+
# it in a skill — they read it HERE. So these messages say what to run; the attended-human override
|
|
76
|
+
# is documented in this file's header and in tools/README.md, where a person looks it up and an
|
|
77
|
+
# agent scanning an error message does not find it.
|
|
78
|
+
#
|
|
79
|
+
# COLAB_SHIP is a PROCESS-IDENTITY assertion — "`colab ship` ran its preconditions" — not a human
|
|
80
|
+
# gate. Typed by hand it asserts that falsely and skips the grade, the branch-CI check, the claim
|
|
81
|
+
# release and the evidence comment. There is no case where typing it is the right next step.
|
|
82
|
+
|
|
83
|
+
# The remote the remedy text below names (#376). git hands a pre-push hook the remote it is pushing
|
|
84
|
+
# to as $1 — the name when the push went through a configured remote, the bare URL when it did not.
|
|
85
|
+
# A name is used as-is: it is the remote this push actually targets, and the one whose tracking ref
|
|
86
|
+
# the reader has. A URL push has no tracking ref of its own, so it falls back to the per-clone
|
|
87
|
+
# override colab itself reads (`git config colab.remote`, tools/README.md "Which remote"), then to
|
|
88
|
+
# `origin`. Message-only: nothing below decides anything on this value.
|
|
89
|
+
remote=${1:-}
|
|
90
|
+
if [ -z "$remote" ] || ! git config --get "remote.$remote.url" >/dev/null 2>&1; then
|
|
91
|
+
remote=$(git config --get colab.remote 2>/dev/null || true)
|
|
92
|
+
[ -z "$remote" ] && remote=origin
|
|
93
|
+
fi
|
|
94
|
+
|
|
95
|
+
# TRUNK guard (also covers tier B, where trunk == main).
|
|
96
|
+
if [ "$pushing_trunk" -eq 1 ] && [ "${COLAB_SHIP:-}" != "1" ] && [ "${COLAB_HUMAN:-}" != "1" ]; then
|
|
97
|
+
echo "pre-push-guard: refusing raw push to trunk '$trunk'." >&2
|
|
98
|
+
echo " Ship the branch instead: colab ship --branch <your-branch>" >&2
|
|
99
|
+
echo " Already committed onto '$trunk' by hand? That commit belongs on a branch, not here:" >&2
|
|
100
|
+
echo " git log --oneline $remote/$trunk..$trunk # what is actually there" >&2
|
|
101
|
+
echo " git branch <type>/<slug>-<issue> $trunk # keep it, on a branch" >&2
|
|
102
|
+
echo " git reset --hard $remote/$trunk # return the checkout to at-rest" >&2
|
|
103
|
+
echo " then claim its issue and ship that branch." >&2
|
|
104
|
+
exit 1
|
|
105
|
+
fi
|
|
106
|
+
|
|
107
|
+
# INTEGRATION-LINE guard — a declared long-lived line is an integration point, not a feature branch.
|
|
108
|
+
if [ -n "$pushing_line" ] && [ "${COLAB_SHIP:-}" != "1" ] && [ "${COLAB_HUMAN:-}" != "1" ]; then
|
|
109
|
+
echo "pre-push-guard: refusing raw push to integration line '$pushing_line'." >&2
|
|
110
|
+
echo " Ship the branch instead (it merges into the base the branch was cut from):" >&2
|
|
111
|
+
echo " colab ship --branch <your-branch>" >&2
|
|
112
|
+
exit 1
|
|
113
|
+
fi
|
|
114
|
+
|
|
115
|
+
# RELEASE-CHANNEL guard (#445) — `next` / `stable` move only with a release, forward only.
|
|
116
|
+
if [ -n "$pushing_channel" ] && [ "${COLAB_RELEASE:-}" != "1" ] && [ "${COLAB_HUMAN:-}" != "1" ]; then
|
|
117
|
+
echo "pre-push-guard: refusing raw push to release channel '$pushing_channel'." >&2
|
|
118
|
+
echo " It names the newest $( [ "$pushing_channel" = next ] && echo candidate || echo final ) and moves only with one:" >&2
|
|
119
|
+
if [ "$pushing_channel" = next ]; then
|
|
120
|
+
echo " colab release cut # a new candidate fast-forwards 'next'" >&2
|
|
121
|
+
else
|
|
122
|
+
echo " colab release finalize # a new final fast-forwards 'stable'" >&2
|
|
123
|
+
fi
|
|
124
|
+
echo " To follow a different version, pin its tag where you consume it; the channel stays where it is." >&2
|
|
125
|
+
exit 1
|
|
126
|
+
fi
|
|
127
|
+
|
|
128
|
+
# MAIN guard — only on tier A and C (trunk != main). COLAB_SHIP intentionally does NOT open main.
|
|
129
|
+
if [ "$trunk" != "main" ] && [ "$pushing_main" -eq 1 ] && [ "${COLAB_PROMOTE:-}" != "1" ] && [ "${COLAB_HUMAN:-}" != "1" ]; then
|
|
130
|
+
echo "pre-push-guard: refusing raw push to 'main' (promotion target)." >&2
|
|
131
|
+
echo " Promotion is trunk->main and it is a human act on every repo: colab promote" >&2
|
|
132
|
+
echo " There is no agent-side override for this one; if you are an agent, this is where you stop" >&2
|
|
133
|
+
echo " and report, not where you look for a flag." >&2
|
|
134
|
+
exit 1
|
|
135
|
+
fi
|
|
136
|
+
|
|
137
|
+
exit 0
|