@futurelastic/colab-handbook 1.12.0-rc.53 → 1.12.0-rc.55
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/audit/audit.mjs +13 -0
- package/package.json +1 -1
- package/templates/README.md +22 -1
- package/templates/ci-laravel.yml +52 -3
- package/templates/ci-node.yml +52 -3
- package/templates/ci-python.yml +52 -3
- package/templates/docs-lint.mjs +1 -1
- package/tools/colab +88 -9
- package/tools/lib/git.js +24 -0
- package/tools/lib/local-adopt.js +8 -4
- package/tools/lib/scratch-dirs.js +106 -0
- package/tools/lib/tree-green.js +88 -0
package/audit/audit.mjs
CHANGED
|
@@ -107,6 +107,8 @@ const migrationGrant = require("../tools/lib/migration-grant.js");
|
|
|
107
107
|
const trustHumansLib = require("../tools/lib/trust-humans.js");
|
|
108
108
|
// #403: the `live-env:` key — read through the same module `colab gate-hermetic` uses.
|
|
109
109
|
const hermeticLib = require("../tools/lib/hermetic.js");
|
|
110
|
+
// #493: the `tree-reuse:` opt-out — read through the same module `colab ship` reads citations with.
|
|
111
|
+
const treeGreenLib = require("../tools/lib/tree-green.js");
|
|
110
112
|
// #410: the optional `gate:` block — read through the same module the skills name.
|
|
111
113
|
const gateLib = require("../tools/lib/gate.js");
|
|
112
114
|
// #417: CLAUDE.md as a thin shell over AGENTS.md — the @-import resolver and the tool-block table,
|
|
@@ -1350,6 +1352,17 @@ function auditRepo(target, ctx) {
|
|
|
1350
1352
|
if (!le.valid) fail(le.reason);
|
|
1351
1353
|
}
|
|
1352
1354
|
|
|
1355
|
+
// ---- tree-reuse (#493) ----------------------------------------------------
|
|
1356
|
+
// `tree-reuse: off` makes the CI templates' guard run trunk's full suite even when a green run
|
|
1357
|
+
// of the same workflow already passed an identical tree. tools/lib/tree-green.js parseTreeReuse
|
|
1358
|
+
// is the one reading. An invalid value fails: the guard reads ANY tree-reuse line as off (the
|
|
1359
|
+
// stricter direction), so the repo gets the full suite — but a value nobody defined is not an answer.
|
|
1360
|
+
{
|
|
1361
|
+
const tr = treeGreenLib.parseTreeReuse(cfg);
|
|
1362
|
+
info.treeReuse = tr.declared ? tr.value : null;
|
|
1363
|
+
if (!tr.valid) fail(tr.reason);
|
|
1364
|
+
}
|
|
1365
|
+
|
|
1353
1366
|
// ---- gate (#410) ----------------------------------------------------------
|
|
1354
1367
|
// Local = a fast smoke check, branch CI = the one authoritative gate. tools/lib/gate.js
|
|
1355
1368
|
// parseGate is the one reading. An invalid block fails: the reader falls back to the local full
|
package/package.json
CHANGED
package/templates/README.md
CHANGED
|
@@ -31,7 +31,7 @@ Starting points you **copy into your own repo**. That is the entire model.
|
|
|
31
31
|
| `repo-CLAUDE-block.md` | *paste into* `CLAUDE.md` | Every adopting repo | The discovery hook — how an agent finds the handbook at all. |
|
|
32
32
|
| `gotchas-d-README.md` | `docs/gotchas.d/README.md` | Any repo starting a `docs/gotchas.d/` directory ([`code-wrap`](../skills/code-wrap/SKILL.md)'s A2 step) | Naming rule (`<issue>-<slug>.md`) and the don't-copy-back rule against an existing `docs/gotchas.md`. Optional — writing the first gotcha entry does not require copying this in first. |
|
|
33
33
|
| `adr-README.md` | `docs/adr/README.md` | Any repo starting a `docs/adr/` directory ([`code-wrap`](../skills/code-wrap/SKILL.md)'s A2 step) | Same issue-keyed naming rule as `gotchas-d-README.md`, applied to architecture decision records instead of gotchas — an existing sequentially-numbered `docs/adr/` is left as-is; only new decisions use `<issue>-<slug>.md`. Optional, same as above. |
|
|
34
|
-
| `docs-lint.mjs` | anywhere in-repo (e.g. `tools/docs-lint.mjs`) | Every repo — checks the STRUCTURE of the doc graph (router integrity, orphans, drafts-in-`docs/`, router size budget, dated files, §-citation resolution, `gotchas.d/` registry discipline, two-surface linkage) | Zero-dependency, plain Node — but it does **shell out to `git check-ignore`** once per enumeration, so that a git-ignored scratch file (your `.
|
|
34
|
+
| `docs-lint.mjs` | anywhere in-repo (e.g. `tools/docs-lint.mjs`) | Every repo — checks the STRUCTURE of the doc graph (router integrity, orphans, drafts-in-`docs/`, router size budget, dated files, §-citation resolution, `gotchas.d/` registry discipline, two-surface linkage) | Zero-dependency, plain Node — but it does **shell out to `git check-ignore`** once per enumeration, so that a git-ignored scratch file (your `.plans/` plan file, say) can never fail a structural check on your repo (#310). No git, or no repo, and it filters nothing and lints exactly as before. **Enumerated by `colab template` and DOES take an automatic version stamp** (colab-handbook #252): `colab template docs-lint.mjs --dest tools/docs-lint.mjs` copies it stamped on its **second** line (`// colab-handbook: docs-lint @ <version>`, after the `#!/usr/bin/env node` shebang — a bare `#` on any other line is a JS syntax error, unlike the YAML templates above) — `--dest` is required, since this file has no formulaic destination the way a workflow does. Pairs with `docs-lint.yml`. Also runs from `code-wrap`'s docs step and a weekly fleet sweep (colab-handbook #249) — this row is the third of its three seats. |
|
|
35
35
|
| `docs-lint.yml` | `.github/workflows/docs-lint.yml` | Every repo that copied `docs-lint.mjs` | Advisory job — `continue-on-error: true` on the lint step, so a finding never blocks a merge until a repo deliberately removes that line. Requires `docs-lint.mjs` to already be in the repo; does not vendor it. |
|
|
36
36
|
| `branch-name.yml` | `.github/workflows/branch-name.yml` | Opt-in — any repo that wants §4's branch shape checked on every PR | One step, no dependencies: the PR's head branch against CONVENTIONS.md §4's regex, both shapes (`<type>/<slug>-<N>` and the `<login>/<machine>/` prefixed one) passing as shipped. Once the repo declares `branchPrefix: machine`, delete the `?` after the regex's first group to require the prefix. The head ref reaches the script through `env:`, never interpolated — on a public repo it is attacker-chosen. |
|
|
37
37
|
|
|
@@ -54,6 +54,27 @@ Two things to keep in a copy:
|
|
|
54
54
|
`migrations` job checks `needs.build.result == 'success'` explicitly. Add the same pair of
|
|
55
55
|
conditions to any job you add.
|
|
56
56
|
|
|
57
|
+
### The same job on trunk — why a squash merge's run skips the suite (#493)
|
|
58
|
+
|
|
59
|
+
The `dedupe` job also runs on every push to a trunk ref named in `concurrency` (`main`, `dev`).
|
|
60
|
+
There it asks a different question, because a squash merge lands a **new sha** whose **tree**
|
|
61
|
+
is byte-identical to the tree its branch run passed: does this workflow have a green `push` run,
|
|
62
|
+
on another ref of this repo, whose commit has this exact tree? It reads `.github/project.yml` at
|
|
63
|
+
the pushed sha and acts only when the ref is that file's `trunk:` and no `tree-reuse:` line is
|
|
64
|
+
present. It confirms the candidate's tree through the git object, then skips the suite and
|
|
65
|
+
leaves a `tree-already-green` notice naming the run. `colab ship` and `colab trunk-ci` read that
|
|
66
|
+
notice back and print the run they relied on. Three things to keep in a copy:
|
|
67
|
+
|
|
68
|
+
- **It needs `contents: read`** on top of `actions: read`, to read the descriptor and the
|
|
69
|
+
commit objects.
|
|
70
|
+
- **The trunk refs in its `if:` mirror `concurrency`'s list.** On a repo whose trunk has another
|
|
71
|
+
name, edit both. Until you do, the guard simply never fires on trunk — nothing breaks.
|
|
72
|
+
- **Never put a trunk-only job behind it.** Publish, deploy and release jobs must run whatever
|
|
73
|
+
the guard says. Give them their own `if:` that does not read `needs.dedupe`.
|
|
74
|
+
|
|
75
|
+
Opt out with `tree-reuse: off` (`project.schema.md`) when trunk's run proves something a branch
|
|
76
|
+
run cannot: secrets only trunk gets, `github.ref`-conditional steps, unpinned runner images.
|
|
77
|
+
|
|
57
78
|
### Migration round-trip — what the Laravel job proves, and what it cannot
|
|
58
79
|
|
|
59
80
|
`ci-laravel.yml`'s `migrations` job runs every migration **twice per engine**: once from
|
package/templates/ci-laravel.yml
CHANGED
|
@@ -119,28 +119,76 @@ jobs:
|
|
|
119
119
|
# Why not simply `if: !github.event.created` on every job: a run whose jobs are ALL
|
|
120
120
|
# skipped concludes `skipped`, which `colab ship` reads as not-green (CONVENTIONS.md
|
|
121
121
|
# §4, "Branch CI"). This job is the one that ends green.
|
|
122
|
+
#
|
|
123
|
+
# Already tested at this TREE? (#493) — the squash merge.
|
|
124
|
+
# A ship squash-merges a branch whose green run already contained the current base, so
|
|
125
|
+
# the trunk commit's TREE is byte-identical to the tree that branch run passed — only the
|
|
126
|
+
# sha is new. On a non-creating push to trunk this job therefore also asks: does THIS
|
|
127
|
+
# workflow have a green `push` run, on another ref of this repo, whose commit has THIS
|
|
128
|
+
# exact tree? It confirms the tree through the git object, never only the run listing.
|
|
129
|
+
# Yes → the suite is skipped and the run cites the run it relied on (a
|
|
130
|
+
# `tree-already-green` notice that `colab ship` / `colab trunk-ci` read back). Equal
|
|
131
|
+
# trees cover every committed byte, workflows and lockfiles included — NOT runner images,
|
|
132
|
+
# unpinned downloads, secrets or `github.ref`-conditional steps; a repo whose suite
|
|
133
|
+
# depends on those declares `tree-reuse: off` in .github/project.yml. Trunk only (the
|
|
134
|
+
# descriptor's `trunk:`, read at this sha), never a release branch, never a dispatch;
|
|
135
|
+
# any doubt (no descriptor, opt-out, an API error, no exact match) runs the full suite.
|
|
136
|
+
# Never put a trunk-only job (publish, deploy, release) behind this gate.
|
|
122
137
|
dedupe:
|
|
123
|
-
name: Already tested at this sha?
|
|
124
|
-
|
|
138
|
+
name: Already tested at this sha or tree?
|
|
139
|
+
# EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
|
|
140
|
+
if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
|
|
125
141
|
runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
|
|
126
142
|
permissions:
|
|
127
143
|
actions: read
|
|
144
|
+
contents: read
|
|
128
145
|
outputs:
|
|
129
146
|
tested: ${{ steps.check.outputs.tested }}
|
|
147
|
+
cited: ${{ steps.check.outputs.cited }}
|
|
130
148
|
steps:
|
|
131
|
-
- name: Look for a green run of this workflow at this sha
|
|
149
|
+
- name: Look for a green run of this workflow at this sha or tree
|
|
132
150
|
id: check
|
|
133
151
|
env:
|
|
134
152
|
GH_TOKEN: ${{ github.token }}
|
|
135
153
|
REPO: ${{ github.repository }}
|
|
136
154
|
RUN_ID: ${{ github.run_id }}
|
|
137
155
|
SHA: ${{ github.sha }}
|
|
156
|
+
CREATED: ${{ github.event.created }}
|
|
157
|
+
REF_NAME: ${{ github.ref_name }}
|
|
138
158
|
run: |
|
|
139
159
|
tested=false
|
|
160
|
+
cited=
|
|
140
161
|
if ! command -v gh >/dev/null 2>&1; then
|
|
141
162
|
echo "::notice::gh is not installed on this runner — running the full suite (#418)."
|
|
142
163
|
elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
|
|
143
164
|
echo "::notice::Could not read this run's workflow id — running the full suite (#418)."
|
|
165
|
+
elif [ "${CREATED:-}" = "false" ]; then
|
|
166
|
+
# A non-creating push: trunk tree mode (#493). Every branch below but one runs the suite.
|
|
167
|
+
if ! DESC="$(gh api "repos/$REPO/contents/.github/project.yml?ref=$SHA" -H 'Accept: application/vnd.github.raw' 2>/dev/null)" || [ -z "$DESC" ]; then
|
|
168
|
+
echo "::notice::Could not read .github/project.yml at $SHA — running the full suite (#493)."
|
|
169
|
+
elif grep -Eq '^tree-reuse[[:space:]]*:' <<< "$DESC"; then
|
|
170
|
+
echo "::notice::tree-reuse is declared in .github/project.yml — running the full suite (#493)."
|
|
171
|
+
elif [ "$(printf '%s\n' "$DESC" | sed -nE "s/^trunk:[[:space:]]*[\"']?([A-Za-z0-9._/-]+).*/\\1/p" | head -n 1)" != "$REF_NAME" ]; then
|
|
172
|
+
echo "::notice::$REF_NAME is not this repo's trunk — running the full suite (#493)."
|
|
173
|
+
elif ! OURS="$(gh api "repos/$REPO/git/commits/$SHA" --jq .tree.sha 2>/dev/null)" || [ -z "$OURS" ]; then
|
|
174
|
+
echo "::notice::Could not read the tree of $SHA — running the full suite (#493)."
|
|
175
|
+
elif ! CAND="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
|
|
176
|
+
--jq "first(.workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\" and .head_commit.tree_id == \"$OURS\") | \"\\(.head_sha) \\(.html_url) \\(.head_branch)\") // empty" 2>/dev/null)"; then
|
|
177
|
+
echo "::notice::Could not list this workflow's green runs — running the full suite (#493)."
|
|
178
|
+
elif [ -z "$CAND" ]; then
|
|
179
|
+
echo "No green run of this workflow on another ref has tree $OURS — running the full suite."
|
|
180
|
+
else
|
|
181
|
+
read -r CSHA URL BR <<< "$CAND"
|
|
182
|
+
if ! CTREE="$(gh api "repos/$REPO/git/commits/$CSHA" --jq .tree.sha 2>/dev/null)" || [ "$CTREE" != "$OURS" ]; then
|
|
183
|
+
echo "::notice::Could not confirm the tree of $CSHA — running the full suite (#493)."
|
|
184
|
+
else
|
|
185
|
+
tested=true
|
|
186
|
+
cited="$URL"
|
|
187
|
+
echo "::notice title=tree-already-green::$URL tree=$OURS head=$CSHA branch=$BR"
|
|
188
|
+
echo "Tree $OURS already passed this workflow at $CSHA on $BR ($URL) — skipping the suite (#493)."
|
|
189
|
+
echo "Already tested: tree \`$OURS\` passed this workflow on \`$BR\` — [the run relied on]($URL); suite skipped (#493)." >> "$GITHUB_STEP_SUMMARY"
|
|
190
|
+
fi
|
|
191
|
+
fi
|
|
144
192
|
elif ! N="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&status=success&per_page=20" \
|
|
145
193
|
--jq "[.workflow_runs[] | select(.id != $RUN_ID and .event != \"pull_request\")] | length" 2>/dev/null)"; then
|
|
146
194
|
echo "::notice::Could not list this workflow's runs at $SHA — running the full suite (#418)."
|
|
@@ -152,6 +200,7 @@ jobs:
|
|
|
152
200
|
echo "No green run of this workflow at $SHA yet — running the full suite."
|
|
153
201
|
fi
|
|
154
202
|
echo "tested=$tested" >> "$GITHUB_OUTPUT"
|
|
203
|
+
[ -z "$cited" ] || echo "cited=$cited" >> "$GITHUB_OUTPUT"
|
|
155
204
|
|
|
156
205
|
gitleaks:
|
|
157
206
|
name: Secret scan (gitleaks)
|
package/templates/ci-node.yml
CHANGED
|
@@ -84,28 +84,76 @@ jobs:
|
|
|
84
84
|
# Why not simply `if: !github.event.created` on every job: a run whose jobs are ALL
|
|
85
85
|
# skipped concludes `skipped`, which `colab ship` reads as not-green (CONVENTIONS.md
|
|
86
86
|
# §4, "Branch CI"). This job is the one that ends green.
|
|
87
|
+
#
|
|
88
|
+
# Already tested at this TREE? (#493) — the squash merge.
|
|
89
|
+
# A ship squash-merges a branch whose green run already contained the current base, so
|
|
90
|
+
# the trunk commit's TREE is byte-identical to the tree that branch run passed — only the
|
|
91
|
+
# sha is new. On a non-creating push to trunk this job therefore also asks: does THIS
|
|
92
|
+
# workflow have a green `push` run, on another ref of this repo, whose commit has THIS
|
|
93
|
+
# exact tree? It confirms the tree through the git object, never only the run listing.
|
|
94
|
+
# Yes → the suite is skipped and the run cites the run it relied on (a
|
|
95
|
+
# `tree-already-green` notice that `colab ship` / `colab trunk-ci` read back). Equal
|
|
96
|
+
# trees cover every committed byte, workflows and lockfiles included — NOT runner images,
|
|
97
|
+
# unpinned downloads, secrets or `github.ref`-conditional steps; a repo whose suite
|
|
98
|
+
# depends on those declares `tree-reuse: off` in .github/project.yml. Trunk only (the
|
|
99
|
+
# descriptor's `trunk:`, read at this sha), never a release branch, never a dispatch;
|
|
100
|
+
# any doubt (no descriptor, opt-out, an API error, no exact match) runs the full suite.
|
|
101
|
+
# Never put a trunk-only job (publish, deploy, release) behind this gate.
|
|
87
102
|
dedupe:
|
|
88
|
-
name: Already tested at this sha?
|
|
89
|
-
|
|
103
|
+
name: Already tested at this sha or tree?
|
|
104
|
+
# EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
|
|
105
|
+
if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
|
|
90
106
|
runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
|
|
91
107
|
permissions:
|
|
92
108
|
actions: read
|
|
109
|
+
contents: read
|
|
93
110
|
outputs:
|
|
94
111
|
tested: ${{ steps.check.outputs.tested }}
|
|
112
|
+
cited: ${{ steps.check.outputs.cited }}
|
|
95
113
|
steps:
|
|
96
|
-
- name: Look for a green run of this workflow at this sha
|
|
114
|
+
- name: Look for a green run of this workflow at this sha or tree
|
|
97
115
|
id: check
|
|
98
116
|
env:
|
|
99
117
|
GH_TOKEN: ${{ github.token }}
|
|
100
118
|
REPO: ${{ github.repository }}
|
|
101
119
|
RUN_ID: ${{ github.run_id }}
|
|
102
120
|
SHA: ${{ github.sha }}
|
|
121
|
+
CREATED: ${{ github.event.created }}
|
|
122
|
+
REF_NAME: ${{ github.ref_name }}
|
|
103
123
|
run: |
|
|
104
124
|
tested=false
|
|
125
|
+
cited=
|
|
105
126
|
if ! command -v gh >/dev/null 2>&1; then
|
|
106
127
|
echo "::notice::gh is not installed on this runner — running the full suite (#418)."
|
|
107
128
|
elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
|
|
108
129
|
echo "::notice::Could not read this run's workflow id — running the full suite (#418)."
|
|
130
|
+
elif [ "${CREATED:-}" = "false" ]; then
|
|
131
|
+
# A non-creating push: trunk tree mode (#493). Every branch below but one runs the suite.
|
|
132
|
+
if ! DESC="$(gh api "repos/$REPO/contents/.github/project.yml?ref=$SHA" -H 'Accept: application/vnd.github.raw' 2>/dev/null)" || [ -z "$DESC" ]; then
|
|
133
|
+
echo "::notice::Could not read .github/project.yml at $SHA — running the full suite (#493)."
|
|
134
|
+
elif grep -Eq '^tree-reuse[[:space:]]*:' <<< "$DESC"; then
|
|
135
|
+
echo "::notice::tree-reuse is declared in .github/project.yml — running the full suite (#493)."
|
|
136
|
+
elif [ "$(printf '%s\n' "$DESC" | sed -nE "s/^trunk:[[:space:]]*[\"']?([A-Za-z0-9._/-]+).*/\\1/p" | head -n 1)" != "$REF_NAME" ]; then
|
|
137
|
+
echo "::notice::$REF_NAME is not this repo's trunk — running the full suite (#493)."
|
|
138
|
+
elif ! OURS="$(gh api "repos/$REPO/git/commits/$SHA" --jq .tree.sha 2>/dev/null)" || [ -z "$OURS" ]; then
|
|
139
|
+
echo "::notice::Could not read the tree of $SHA — running the full suite (#493)."
|
|
140
|
+
elif ! CAND="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
|
|
141
|
+
--jq "first(.workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\" and .head_commit.tree_id == \"$OURS\") | \"\\(.head_sha) \\(.html_url) \\(.head_branch)\") // empty" 2>/dev/null)"; then
|
|
142
|
+
echo "::notice::Could not list this workflow's green runs — running the full suite (#493)."
|
|
143
|
+
elif [ -z "$CAND" ]; then
|
|
144
|
+
echo "No green run of this workflow on another ref has tree $OURS — running the full suite."
|
|
145
|
+
else
|
|
146
|
+
read -r CSHA URL BR <<< "$CAND"
|
|
147
|
+
if ! CTREE="$(gh api "repos/$REPO/git/commits/$CSHA" --jq .tree.sha 2>/dev/null)" || [ "$CTREE" != "$OURS" ]; then
|
|
148
|
+
echo "::notice::Could not confirm the tree of $CSHA — running the full suite (#493)."
|
|
149
|
+
else
|
|
150
|
+
tested=true
|
|
151
|
+
cited="$URL"
|
|
152
|
+
echo "::notice title=tree-already-green::$URL tree=$OURS head=$CSHA branch=$BR"
|
|
153
|
+
echo "Tree $OURS already passed this workflow at $CSHA on $BR ($URL) — skipping the suite (#493)."
|
|
154
|
+
echo "Already tested: tree \`$OURS\` passed this workflow on \`$BR\` — [the run relied on]($URL); suite skipped (#493)." >> "$GITHUB_STEP_SUMMARY"
|
|
155
|
+
fi
|
|
156
|
+
fi
|
|
109
157
|
elif ! N="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&status=success&per_page=20" \
|
|
110
158
|
--jq "[.workflow_runs[] | select(.id != $RUN_ID and .event != \"pull_request\")] | length" 2>/dev/null)"; then
|
|
111
159
|
echo "::notice::Could not list this workflow's runs at $SHA — running the full suite (#418)."
|
|
@@ -117,6 +165,7 @@ jobs:
|
|
|
117
165
|
echo "No green run of this workflow at $SHA yet — running the full suite."
|
|
118
166
|
fi
|
|
119
167
|
echo "tested=$tested" >> "$GITHUB_OUTPUT"
|
|
168
|
+
[ -z "$cited" ] || echo "cited=$cited" >> "$GITHUB_OUTPUT"
|
|
120
169
|
|
|
121
170
|
gitleaks:
|
|
122
171
|
name: Secret scan (gitleaks)
|
package/templates/ci-python.yml
CHANGED
|
@@ -98,28 +98,76 @@ jobs:
|
|
|
98
98
|
# Why not simply `if: !github.event.created` on every job: a run whose jobs are ALL
|
|
99
99
|
# skipped concludes `skipped`, which `colab ship` reads as not-green (CONVENTIONS.md
|
|
100
100
|
# §4, "Branch CI"). This job is the one that ends green.
|
|
101
|
+
#
|
|
102
|
+
# Already tested at this TREE? (#493) — the squash merge.
|
|
103
|
+
# A ship squash-merges a branch whose green run already contained the current base, so
|
|
104
|
+
# the trunk commit's TREE is byte-identical to the tree that branch run passed — only the
|
|
105
|
+
# sha is new. On a non-creating push to trunk this job therefore also asks: does THIS
|
|
106
|
+
# workflow have a green `push` run, on another ref of this repo, whose commit has THIS
|
|
107
|
+
# exact tree? It confirms the tree through the git object, never only the run listing.
|
|
108
|
+
# Yes → the suite is skipped and the run cites the run it relied on (a
|
|
109
|
+
# `tree-already-green` notice that `colab ship` / `colab trunk-ci` read back). Equal
|
|
110
|
+
# trees cover every committed byte, workflows and lockfiles included — NOT runner images,
|
|
111
|
+
# unpinned downloads, secrets or `github.ref`-conditional steps; a repo whose suite
|
|
112
|
+
# depends on those declares `tree-reuse: off` in .github/project.yml. Trunk only (the
|
|
113
|
+
# descriptor's `trunk:`, read at this sha), never a release branch, never a dispatch;
|
|
114
|
+
# any doubt (no descriptor, opt-out, an API error, no exact match) runs the full suite.
|
|
115
|
+
# Never put a trunk-only job (publish, deploy, release) behind this gate.
|
|
101
116
|
dedupe:
|
|
102
|
-
name: Already tested at this sha?
|
|
103
|
-
|
|
117
|
+
name: Already tested at this sha or tree?
|
|
118
|
+
# EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
|
|
119
|
+
if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
|
|
104
120
|
runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
|
|
105
121
|
permissions:
|
|
106
122
|
actions: read
|
|
123
|
+
contents: read
|
|
107
124
|
outputs:
|
|
108
125
|
tested: ${{ steps.check.outputs.tested }}
|
|
126
|
+
cited: ${{ steps.check.outputs.cited }}
|
|
109
127
|
steps:
|
|
110
|
-
- name: Look for a green run of this workflow at this sha
|
|
128
|
+
- name: Look for a green run of this workflow at this sha or tree
|
|
111
129
|
id: check
|
|
112
130
|
env:
|
|
113
131
|
GH_TOKEN: ${{ github.token }}
|
|
114
132
|
REPO: ${{ github.repository }}
|
|
115
133
|
RUN_ID: ${{ github.run_id }}
|
|
116
134
|
SHA: ${{ github.sha }}
|
|
135
|
+
CREATED: ${{ github.event.created }}
|
|
136
|
+
REF_NAME: ${{ github.ref_name }}
|
|
117
137
|
run: |
|
|
118
138
|
tested=false
|
|
139
|
+
cited=
|
|
119
140
|
if ! command -v gh >/dev/null 2>&1; then
|
|
120
141
|
echo "::notice::gh is not installed on this runner — running the full suite (#418)."
|
|
121
142
|
elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
|
|
122
143
|
echo "::notice::Could not read this run's workflow id — running the full suite (#418)."
|
|
144
|
+
elif [ "${CREATED:-}" = "false" ]; then
|
|
145
|
+
# A non-creating push: trunk tree mode (#493). Every branch below but one runs the suite.
|
|
146
|
+
if ! DESC="$(gh api "repos/$REPO/contents/.github/project.yml?ref=$SHA" -H 'Accept: application/vnd.github.raw' 2>/dev/null)" || [ -z "$DESC" ]; then
|
|
147
|
+
echo "::notice::Could not read .github/project.yml at $SHA — running the full suite (#493)."
|
|
148
|
+
elif grep -Eq '^tree-reuse[[:space:]]*:' <<< "$DESC"; then
|
|
149
|
+
echo "::notice::tree-reuse is declared in .github/project.yml — running the full suite (#493)."
|
|
150
|
+
elif [ "$(printf '%s\n' "$DESC" | sed -nE "s/^trunk:[[:space:]]*[\"']?([A-Za-z0-9._/-]+).*/\\1/p" | head -n 1)" != "$REF_NAME" ]; then
|
|
151
|
+
echo "::notice::$REF_NAME is not this repo's trunk — running the full suite (#493)."
|
|
152
|
+
elif ! OURS="$(gh api "repos/$REPO/git/commits/$SHA" --jq .tree.sha 2>/dev/null)" || [ -z "$OURS" ]; then
|
|
153
|
+
echo "::notice::Could not read the tree of $SHA — running the full suite (#493)."
|
|
154
|
+
elif ! CAND="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
|
|
155
|
+
--jq "first(.workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\" and .head_commit.tree_id == \"$OURS\") | \"\\(.head_sha) \\(.html_url) \\(.head_branch)\") // empty" 2>/dev/null)"; then
|
|
156
|
+
echo "::notice::Could not list this workflow's green runs — running the full suite (#493)."
|
|
157
|
+
elif [ -z "$CAND" ]; then
|
|
158
|
+
echo "No green run of this workflow on another ref has tree $OURS — running the full suite."
|
|
159
|
+
else
|
|
160
|
+
read -r CSHA URL BR <<< "$CAND"
|
|
161
|
+
if ! CTREE="$(gh api "repos/$REPO/git/commits/$CSHA" --jq .tree.sha 2>/dev/null)" || [ "$CTREE" != "$OURS" ]; then
|
|
162
|
+
echo "::notice::Could not confirm the tree of $CSHA — running the full suite (#493)."
|
|
163
|
+
else
|
|
164
|
+
tested=true
|
|
165
|
+
cited="$URL"
|
|
166
|
+
echo "::notice title=tree-already-green::$URL tree=$OURS head=$CSHA branch=$BR"
|
|
167
|
+
echo "Tree $OURS already passed this workflow at $CSHA on $BR ($URL) — skipping the suite (#493)."
|
|
168
|
+
echo "Already tested: tree \`$OURS\` passed this workflow on \`$BR\` — [the run relied on]($URL); suite skipped (#493)." >> "$GITHUB_STEP_SUMMARY"
|
|
169
|
+
fi
|
|
170
|
+
fi
|
|
123
171
|
elif ! N="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&status=success&per_page=20" \
|
|
124
172
|
--jq "[.workflow_runs[] | select(.id != $RUN_ID and .event != \"pull_request\")] | length" 2>/dev/null)"; then
|
|
125
173
|
echo "::notice::Could not list this workflow's runs at $SHA — running the full suite (#418)."
|
|
@@ -131,6 +179,7 @@ jobs:
|
|
|
131
179
|
echo "No green run of this workflow at $SHA yet — running the full suite."
|
|
132
180
|
fi
|
|
133
181
|
echo "tested=$tested" >> "$GITHUB_OUTPUT"
|
|
182
|
+
[ -z "$cited" ] || echo "cited=$cited" >> "$GITHUB_OUTPUT"
|
|
134
183
|
|
|
135
184
|
gitleaks:
|
|
136
185
|
name: Secret scan (gitleaks)
|
package/templates/docs-lint.mjs
CHANGED
|
@@ -71,7 +71,7 @@
|
|
|
71
71
|
// - a git-IGNORED markdown file is not part of the doc graph and is never
|
|
72
72
|
// enumerated by any check. Scratch that never ships must not be able to
|
|
73
73
|
// fail a structural check on the repo — and it was: `.claude/plans/
|
|
74
|
-
// issue-<N>.md
|
|
74
|
+
// issue-<N>.md` (since #488 `.plans/issue-<N>.md`), the git-excluded, `code-ship`-deleted plan file that
|
|
75
75
|
// `code-start` writes, contributed 7 of one control run's 10 check-6
|
|
76
76
|
// failures purely by quoting `§4` in prose, which made the repo lint clean
|
|
77
77
|
// or dirty depending on who happened to have a session open
|
package/tools/colab
CHANGED
|
@@ -45,8 +45,10 @@ const trustHumans = require('./lib/trust-humans');
|
|
|
45
45
|
const ciCure = require('./lib/ci-cure');
|
|
46
46
|
const ciVerdict = require('./lib/ci-verdict');
|
|
47
47
|
const baseCiVerdict = require('./lib/base-ci-verdict');
|
|
48
|
+
const treeGreen = require('./lib/tree-green');
|
|
48
49
|
const staleBase = require('./lib/stale-base');
|
|
49
50
|
const dirtyOwner = require('./lib/dirty-owner');
|
|
51
|
+
const scratchDirs = require('./lib/scratch-dirs');
|
|
50
52
|
const lockfileDrift = require('./lib/lockfile-drift');
|
|
51
53
|
const adopt = require('./lib/adopt');
|
|
52
54
|
const consumerEvidence = require('./lib/consumer-evidence');
|
|
@@ -5216,7 +5218,10 @@ function removeWorktreeDir(repoAbs, wtPath) {
|
|
|
5216
5218
|
function uncommittedWork(wtPath) {
|
|
5217
5219
|
if (!wtPath || !fs.existsSync(wtPath)) return { any: false, lines: '', what: '' };
|
|
5218
5220
|
const tracked = git.dirtyTracked(wtPath);
|
|
5219
|
-
|
|
5221
|
+
// #488: scratch (a plan or brief left in the worktree) is disposable by definition — it must never
|
|
5222
|
+
// be what makes a teardown refuse. Normally info/exclude already hides it; this covers a clone
|
|
5223
|
+
// whose exclude predates the scratch dirs, or a dir configured after the worktree was cut.
|
|
5224
|
+
const untracked = scratchDirs.withoutScratch(git.dirtyUntracked(wtPath));
|
|
5220
5225
|
return {
|
|
5221
5226
|
any: !!(tracked || untracked),
|
|
5222
5227
|
lines: [tracked, untracked].filter(Boolean).join('\n'),
|
|
@@ -5491,6 +5496,10 @@ function cmdWorktreeNew(argv) {
|
|
|
5491
5496
|
}
|
|
5492
5497
|
settleTrackerPending(repoAbs, claimedHere.filter((n) => !lostIssues.includes(n)), trackerMissed, { wtName: name, branch });
|
|
5493
5498
|
|
|
5499
|
+
// #488: the scratch dirs (plans, briefs) are hidden in the clone's shared info/exclude — one
|
|
5500
|
+
// write covers the main checkout and every worktree, with no per-repo .gitignore diff.
|
|
5501
|
+
ensureScratchExcluded(repoAbs);
|
|
5502
|
+
|
|
5494
5503
|
// 5. optional repo hook (machine-specific steps plug in here)
|
|
5495
5504
|
const hook = runHook(repoAbs, 'post-create', { wtPath, name, branch, ports: alloc.chosenPorts, trunk, base, issues });
|
|
5496
5505
|
if (hook.ran && !hook.ok) warn(`post-create hook exited ${hook.code} — worktree was still created; finish setup manually`);
|
|
@@ -7672,7 +7681,8 @@ files is not an option (CONVENTIONS.md §9, "Working in a repo you don't own"):
|
|
|
7672
7681
|
|
|
7673
7682
|
1. refuses if .github/project.yml is TRACKED (then the repo is adopted — use plain adopt), if
|
|
7674
7683
|
--trunk is missing, or if --trunk names the owner's own default branch;
|
|
7675
|
-
2. appends /.github/project.yml, /CLAUDE.local.md,
|
|
7684
|
+
2. appends /.github/project.yml, /CLAUDE.local.md, the scratch dirs (/.plans/, /.briefs/,
|
|
7685
|
+
legacy /.claude/plans/ — #488) and the worktree subdir
|
|
7676
7686
|
(/.worktrees/ by default — the owner's .gitignore does not hide it) to .git/info/exclude (the
|
|
7677
7687
|
shared common dir — never .gitignore, which is itself a tracked file) BEFORE writing, and
|
|
7678
7688
|
keeps them even if a later check refuses (idempotent, local, hides nothing that exists);
|
|
@@ -7799,6 +7809,26 @@ function gitExcludePath(repoAbs) {
|
|
|
7799
7809
|
return path.join(r.stdout, 'info', 'exclude');
|
|
7800
7810
|
}
|
|
7801
7811
|
|
|
7812
|
+
/**
|
|
7813
|
+
* #488: append the scratch-dir exclude lines (scratch-dirs.js `excludeLines`) to the clone's shared
|
|
7814
|
+
* info/exclude, idempotently. Best-effort: a failure warns and never blocks the caller.
|
|
7815
|
+
*/
|
|
7816
|
+
function ensureScratchExcluded(repoAbs) {
|
|
7817
|
+
const excludeFile = gitExcludePath(repoAbs);
|
|
7818
|
+
if (!excludeFile) return [];
|
|
7819
|
+
let before = null;
|
|
7820
|
+
try { before = fs.readFileSync(excludeFile, 'utf8'); } catch (_) { /* absent */ }
|
|
7821
|
+
const lines = scratchDirs.excludeLines();
|
|
7822
|
+
const missing = localAdopt.missingExcludeLines(before, lines);
|
|
7823
|
+
if (!missing.length) return [];
|
|
7824
|
+
try {
|
|
7825
|
+
fs.mkdirSync(path.dirname(excludeFile), { recursive: true });
|
|
7826
|
+
const sep = before && !before.endsWith('\n') ? '\n' : '';
|
|
7827
|
+
fs.appendFileSync(excludeFile, sep + missing.join('\n') + '\n');
|
|
7828
|
+
} catch (e) { warn(`could not hide the scratch dirs in ${excludeFile}: ${e.message}`); return []; }
|
|
7829
|
+
return missing;
|
|
7830
|
+
}
|
|
7831
|
+
|
|
7802
7832
|
function gitTracks(repoAbs, rel) {
|
|
7803
7833
|
return git.git(['ls-files', '--error-unmatch', '--', rel], repoAbs).ok;
|
|
7804
7834
|
}
|
|
@@ -10438,9 +10468,43 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
|
|
|
10438
10468
|
const sub = shipBatchTrunkSubstitute(repoAbs, trunk, run.sha);
|
|
10439
10469
|
if (sub) return { run, final: true, verdict: sub };
|
|
10440
10470
|
}
|
|
10471
|
+
if (verdict.ok && target === trunk) verdict = treeGreenVerdict(repoAbs, run, verdict);
|
|
10441
10472
|
return { run, verdict, final: verdict.ok || verdict.class !== HUMAN_GATED };
|
|
10442
10473
|
}
|
|
10443
10474
|
|
|
10475
|
+
/**
|
|
10476
|
+
* #493: a green trunk read whose suite was SKIPPED because the CI guard found a green run of the
|
|
10477
|
+
* same workflow at an identical tree — name the run it relied on. The run's `success` is already
|
|
10478
|
+
* the verdict (same as #418's sha skip); the citation is the audit pointer, so a citation that
|
|
10479
|
+
* cannot be read leaves the verdict green and says so. One thing turns it red: the cited head is
|
|
10480
|
+
* local and its tree provably differs from trunk's — the skip relied on a run of a DIFFERENT
|
|
10481
|
+
* tree, so trunk is untested (HUMAN_GATED, a person looks). An ordinary green run costs one
|
|
10482
|
+
* check-runs read and keeps its detail byte-identical.
|
|
10483
|
+
*/
|
|
10484
|
+
function treeGreenVerdict(repoAbs, run, verdict) {
|
|
10485
|
+
const checks = git.ghCommitCheckRuns(repoAbs, run.sha);
|
|
10486
|
+
const ids = treeGreen.treeSkipCheckRuns(checks);
|
|
10487
|
+
if (!ids || !ids.length) return verdict;
|
|
10488
|
+
const cites = [];
|
|
10489
|
+
let unreadable = 0;
|
|
10490
|
+
const treeOf = (sha) => {
|
|
10491
|
+
const r = git.git(['rev-parse', '--verify', '--quiet', `${sha}^{tree}`], repoAbs);
|
|
10492
|
+
return r.ok ? r.stdout.trim() : null;
|
|
10493
|
+
};
|
|
10494
|
+
const ours = treeOf(run.sha);
|
|
10495
|
+
for (const id of ids) {
|
|
10496
|
+
const cite = treeGreen.parseCitation(git.ghCheckRunAnnotations(repoAbs, id));
|
|
10497
|
+
if (!cite) { unreadable++; continue; }
|
|
10498
|
+
const theirs = treeOf(cite.head);
|
|
10499
|
+
if (ours && theirs && ours !== theirs) {
|
|
10500
|
+
return { ok: false, class: HUMAN_GATED,
|
|
10501
|
+
detail: `${verdict.detail} — but the suite was SKIPPED on a tree-already-green citation (#493) of ${cite.url} (${cite.branch}@${shortSha(cite.head)}), whose tree ${theirs.slice(0, 12)} differs from trunk's ${ours.slice(0, 12)}: trunk is untested at this sha — re-run its CI, and report the guard` };
|
|
10502
|
+
}
|
|
10503
|
+
cites.push({ ...cite, proof: ours && theirs ? 'verified' : 'unverified' });
|
|
10504
|
+
}
|
|
10505
|
+
return { ...verdict, detail: verdict.detail + treeGreen.citationNote(cites, unreadable), treeGreen: cites.map((c) => c.url) };
|
|
10506
|
+
}
|
|
10507
|
+
|
|
10444
10508
|
/**
|
|
10445
10509
|
* The SINGLE verdict for one measured CI run (#155 fix 1) — called by BOTH `shipCiCheck` above and
|
|
10446
10510
|
* `cmdCiGrantCreate`'s `trunkIsRed` below, so the two can no longer independently disagree about
|
|
@@ -11450,7 +11514,14 @@ function shipCloseSpentContainers(repoAbs, closedIssues, { sha, target } = {}) {
|
|
|
11450
11514
|
}
|
|
11451
11515
|
|
|
11452
11516
|
function shipJournalPlanFiles(repoAbs, issues) {
|
|
11453
|
-
|
|
11517
|
+
// #488: the configured plans dir first, then the legacy `.claude/plans/` — a plan written before
|
|
11518
|
+
// the switch is still journalled and deleted. One journal line per issue across both dirs: a
|
|
11519
|
+
// stray duplicate in the second dir is deleted without journalling the issue twice.
|
|
11520
|
+
const journalled = new Set();
|
|
11521
|
+
for (const plansDir of scratchDirs.planReadDirs(repoAbs)) shipJournalPlanDir(repoAbs, plansDir, issues, journalled);
|
|
11522
|
+
}
|
|
11523
|
+
|
|
11524
|
+
function shipJournalPlanDir(repoAbs, plansDir, issues, journalled) {
|
|
11454
11525
|
let entries;
|
|
11455
11526
|
try { entries = fs.readdirSync(plansDir); } catch (_) { return; } // no plans dir at all — nothing to do
|
|
11456
11527
|
const issueSet = new Set(issues.map((n) => String(n)));
|
|
@@ -11467,13 +11538,17 @@ function shipJournalPlanFiles(repoAbs, issues) {
|
|
|
11467
11538
|
const rm = txt.match(/^rung:\s*(.+)$/m); if (rm) rung = rm[1].trim();
|
|
11468
11539
|
const cm = txt.match(/^cause:\s*(.+)$/m); if (cm) cause = cm[1].trim();
|
|
11469
11540
|
} catch (_) { /* front matter is optional — the defaults above cover a plain rung-1 stub */ }
|
|
11470
|
-
const
|
|
11541
|
+
const fresh = nums.filter((num) => !journalled.has(num));
|
|
11542
|
+
const lines = fresh.map((num) => JSON.stringify({
|
|
11471
11543
|
ts: new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
|
|
11472
11544
|
issue: Number(num), rung, cause, verdict: 'pass',
|
|
11473
|
-
})).join('\n')
|
|
11545
|
+
})).join('\n');
|
|
11474
11546
|
try {
|
|
11475
|
-
|
|
11476
|
-
|
|
11547
|
+
if (lines) {
|
|
11548
|
+
fs.mkdirSync(path.dirname(journalPath), { recursive: true });
|
|
11549
|
+
fs.appendFileSync(journalPath, lines + '\n');
|
|
11550
|
+
}
|
|
11551
|
+
for (const num of fresh) journalled.add(num);
|
|
11477
11552
|
fs.rmSync(planPath, { force: true }); // only after the journal write above landed
|
|
11478
11553
|
} catch (e) {
|
|
11479
11554
|
warnDeferred(`could not journal/delete the plan file "${name}" (${e.message}) — left in place`);
|
|
@@ -13591,7 +13666,11 @@ The first output word is one verdict:
|
|
|
13591
13666
|
Exemption doors (the cure rule, a ci-grant) are NOT applied: they let one branch past a red
|
|
13592
13667
|
trunk, they do not make the trunk green, and the red still needs an owner.
|
|
13593
13668
|
|
|
13594
|
-
|
|
13669
|
+
A GREEN whose suite the CI guard skipped because a green run of the same workflow already
|
|
13670
|
+
passed an identical tree (#493) names that run in its detail ("relied on <url>"). If the cited
|
|
13671
|
+
head is local and its tree differs from trunk's, the read is RED: trunk is untested.
|
|
13672
|
+
|
|
13673
|
+
--json { verdict, sha, ok, class, detail, trunk[, cited: [<run url>…] on a #493 skip] }
|
|
13595
13674
|
Exit 0 whenever a verdict was read (whatever it is); 2 on UNREADABLE.`;
|
|
13596
13675
|
|
|
13597
13676
|
/** Map readCiVerdict's result to the closed trunk-ci vocabulary. Pure — exported for tests. */
|
|
@@ -13618,7 +13697,7 @@ function cmdTrunkCi(argv) {
|
|
|
13618
13697
|
const verdict = trunkCiToken(r);
|
|
13619
13698
|
const sha = r.run ? r.run.sha || null : null;
|
|
13620
13699
|
if (opts.json) {
|
|
13621
|
-
print(JSON.stringify({ verdict, trunk, sha, ok: r.verdict.ok, class: r.verdict.class || null, detail: r.verdict.detail }, null, 2));
|
|
13700
|
+
print(JSON.stringify({ verdict, trunk, sha, ok: r.verdict.ok, class: r.verdict.class || null, detail: r.verdict.detail, ...(r.verdict.treeGreen ? { cited: r.verdict.treeGreen } : {}) }, null, 2));
|
|
13622
13701
|
} else {
|
|
13623
13702
|
print(`${verdict} ${trunk}${sha ? `@${shortSha(sha)}` : ''} — ${r.verdict.detail}`);
|
|
13624
13703
|
}
|
package/tools/lib/git.js
CHANGED
|
@@ -1157,6 +1157,29 @@ function ghRunJobs(repo, runDatabaseId) {
|
|
|
1157
1157
|
}));
|
|
1158
1158
|
}
|
|
1159
1159
|
|
|
1160
|
+
/**
|
|
1161
|
+
* Every check run at one commit, flattened for the #493 tree-skip read — `[{id, name, status,
|
|
1162
|
+
* conclusion, suite, annotations}]` (`suite` = check-suite id = one workflow run; `annotations` =
|
|
1163
|
+
* output.annotations_count), or null on a gh/parse failure. One call per green trunk read, made
|
|
1164
|
+
* lazily by readCiVerdict; `{owner}/{repo}` is resolved by gh from the cwd's remote.
|
|
1165
|
+
*/
|
|
1166
|
+
function ghCommitCheckRuns(repo, sha) {
|
|
1167
|
+
if (!sha) return null;
|
|
1168
|
+
const r = run('gh', ['api', `repos/{owner}/{repo}/commits/${sha}/check-runs?per_page=100`,
|
|
1169
|
+
'--jq', '[.check_runs[] | {id, name, status, conclusion, suite: .check_suite.id, annotations: .output.annotations_count}]'], { cwd: repo });
|
|
1170
|
+
if (!r.ok) return null;
|
|
1171
|
+
try { const v = JSON.parse(r.stdout); return Array.isArray(v) ? v : null; } catch (_) { return null; }
|
|
1172
|
+
}
|
|
1173
|
+
|
|
1174
|
+
/** One check run's annotations as `[{title, message, level}]`, or null on failure (#493). */
|
|
1175
|
+
function ghCheckRunAnnotations(repo, checkRunId) {
|
|
1176
|
+
if (checkRunId === null || checkRunId === undefined) return null;
|
|
1177
|
+
const r = run('gh', ['api', `repos/{owner}/{repo}/check-runs/${checkRunId}/annotations`,
|
|
1178
|
+
'--jq', '[.[] | {title, message, level: .annotation_level}]'], { cwd: repo });
|
|
1179
|
+
if (!r.ok) return null;
|
|
1180
|
+
try { const v = JSON.parse(r.stdout); return Array.isArray(v) ? v : null; } catch (_) { return null; }
|
|
1181
|
+
}
|
|
1182
|
+
|
|
1160
1183
|
/**
|
|
1161
1184
|
* Dispatch `workflowFile` on `ref` (#474) — `gh workflow run <file> --ref <ref> -f k=v…`. Returns
|
|
1162
1185
|
* `{ok, withInputs, detail}`. If the call with inputs is refused (GitHub can validate inputs against
|
|
@@ -1189,6 +1212,7 @@ function ghAssignedIssues(repo) {
|
|
|
1189
1212
|
}
|
|
1190
1213
|
|
|
1191
1214
|
module.exports = {
|
|
1215
|
+
ghCommitCheckRuns, ghCheckRunAnnotations,
|
|
1192
1216
|
run, git, repoRoot, mainRepoRoot, originUrl, remoteInfo, remoteName, remoteFor, remoteUrl, remoteProblem, _resetRemoteCache,
|
|
1193
1217
|
detectTrunk, branchExists, branchRefs, existingBranchRef,
|
|
1194
1218
|
claimRemote, remoteHeads,
|
package/tools/lib/local-adopt.js
CHANGED
|
@@ -20,12 +20,16 @@
|
|
|
20
20
|
* Everything here is pure (text in, text/verdict out); tools/colab does the IO.
|
|
21
21
|
*/
|
|
22
22
|
|
|
23
|
+
const scratchDirs = require('./scratch-dirs');
|
|
24
|
+
|
|
23
25
|
/**
|
|
24
26
|
* Paths hidden by `.git/info/exclude`, root-anchored (a leading `/`) so they match only at the
|
|
25
27
|
* repo root — `CLAUDE.local.md` in a subdirectory the owner commits must stay visible.
|
|
26
|
-
*
|
|
28
|
+
* The session scratch dirs (plans, briefs — #488) are appended by `localExcludePaths` from
|
|
29
|
+
* scratch-dirs.js, so a configured COLAB_PLANS_DIR / COLAB_BRIEFS_DIR is hidden too; the legacy
|
|
30
|
+
* `.claude/plans/` stays among them.
|
|
27
31
|
*/
|
|
28
|
-
const LOCAL_EXCLUDE_PATHS = ['/.github/project.yml', '/CLAUDE.local.md'
|
|
32
|
+
const LOCAL_EXCLUDE_PATHS = ['/.github/project.yml', '/CLAUDE.local.md'];
|
|
29
33
|
|
|
30
34
|
/**
|
|
31
35
|
* LOCAL_EXCLUDE_PATHS plus the worktree subdir (`colab worktree new` creates worktrees INSIDE the
|
|
@@ -33,9 +37,9 @@ const LOCAL_EXCLUDE_PATHS = ['/.github/project.yml', '/CLAUDE.local.md', '/.clau
|
|
|
33
37
|
* `.gitignore`; the owner's repo does not, so without this line every worktree shows up in the
|
|
34
38
|
* main checkout's `git status` — measured on the #393 fixture the moment the first one was cut.
|
|
35
39
|
*/
|
|
36
|
-
function localExcludePaths(worktreeSubdir) {
|
|
40
|
+
function localExcludePaths(worktreeSubdir, env = process.env) {
|
|
37
41
|
const sub = String(worktreeSubdir || '.worktrees').replace(/^\/+|\/+$/g, '');
|
|
38
|
-
return [...LOCAL_EXCLUDE_PATHS, `/${sub}/`];
|
|
42
|
+
return [...LOCAL_EXCLUDE_PATHS, ...scratchDirs.excludeLines(env), `/${sub}/`];
|
|
39
43
|
}
|
|
40
44
|
|
|
41
45
|
const EXCLUDE_HEADER = '# colab-handbook: local-only adoption (#393) — handbook files this clone keeps out of the owner\'s history';
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* #488: where a session's scratch lives — the plan file (`code-start` / `code-plan` write it,
|
|
4
|
+
* `code-wrap` / `code-ship` read and delete it) and dispatch briefs.
|
|
5
|
+
*
|
|
6
|
+
* Both used to be literals under `.claude/` (`.claude/plans/`, `.claude/briefs/`). The agent CLI
|
|
7
|
+
* guards `.claude/` as configuration, so every scratch write there could cost the operator a
|
|
8
|
+
* permission prompt — for a file that is disposable by definition. Defaults now sit outside it:
|
|
9
|
+
*
|
|
10
|
+
* plans `<main checkout>/.plans/` overridable by COLAB_PLANS_DIR
|
|
11
|
+
* briefs `<main checkout>/.briefs/` overridable by COLAB_BRIEFS_DIR
|
|
12
|
+
*
|
|
13
|
+
* A configured value is relative to the repo root, or absolute. Writers use ONLY the configured
|
|
14
|
+
* dir. Readers use the configured dir first, then the legacy `.claude/plans/` — one transition,
|
|
15
|
+
* so a plan written before the switch is still graded, journalled and deleted. Old files are never
|
|
16
|
+
* moved.
|
|
17
|
+
*
|
|
18
|
+
* Everything here is pure (env + strings in, strings out); tools/colab does the IO.
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
const path = require('path');
|
|
22
|
+
|
|
23
|
+
const DEFAULT_PLANS_DIR = '.plans';
|
|
24
|
+
const DEFAULT_BRIEFS_DIR = '.briefs';
|
|
25
|
+
/** Read-only fallbacks for the transition (#488). Never written to by anything that follows #488. */
|
|
26
|
+
const LEGACY_PLANS_DIR = '.claude/plans';
|
|
27
|
+
const LEGACY_BRIEFS_DIR = '.claude/briefs';
|
|
28
|
+
|
|
29
|
+
/** A configured dir, normalised: trimmed, forward slashes, no trailing slash; blank → the default. */
|
|
30
|
+
function normalise(value, dflt) {
|
|
31
|
+
const v = String(value === undefined || value === null ? '' : value).trim().replace(/\\/g, '/');
|
|
32
|
+
if (!v) return dflt;
|
|
33
|
+
if (v === '/') return dflt; // the filesystem root is never a scratch dir — treat as unset
|
|
34
|
+
return v.replace(/\/+$/, '') || dflt;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** The plans dir as configured — relative to the repo root unless absolute. */
|
|
38
|
+
function plansDirSetting(env = process.env) { return normalise(env.COLAB_PLANS_DIR, DEFAULT_PLANS_DIR); }
|
|
39
|
+
/** The briefs dir as configured — relative to the repo root unless absolute. */
|
|
40
|
+
function briefsDirSetting(env = process.env) { return normalise(env.COLAB_BRIEFS_DIR, DEFAULT_BRIEFS_DIR); }
|
|
41
|
+
|
|
42
|
+
function resolveIn(repoRoot, rel) { return path.isAbsolute(rel) ? rel : path.join(repoRoot, rel); }
|
|
43
|
+
|
|
44
|
+
/** Absolute dir a writer puts a plan file in. Never the legacy dir (unless configured to it). */
|
|
45
|
+
function planWriteDir(repoRoot, env = process.env) { return resolveIn(repoRoot, plansDirSetting(env)); }
|
|
46
|
+
|
|
47
|
+
/** Absolute dir a writer puts a brief in. */
|
|
48
|
+
function briefsWriteDir(repoRoot, env = process.env) { return resolveIn(repoRoot, briefsDirSetting(env)); }
|
|
49
|
+
|
|
50
|
+
/** Absolute dirs a reader looks in, in order: configured first, then legacy. Deduplicated. */
|
|
51
|
+
function planReadDirs(repoRoot, env = process.env) {
|
|
52
|
+
const out = [];
|
|
53
|
+
for (const d of [planWriteDir(repoRoot, env), resolveIn(repoRoot, LEGACY_PLANS_DIR)]) {
|
|
54
|
+
if (!out.includes(d)) out.push(d);
|
|
55
|
+
}
|
|
56
|
+
return out;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* A configured dir that is relative and stays inside the repo, as a root-anchored exclude line
|
|
61
|
+
* (`/.plans/`) — or null for an absolute dir or one that climbs out (`../x`), which no repo-local
|
|
62
|
+
* ignore file can or needs to hide.
|
|
63
|
+
*/
|
|
64
|
+
function anchoredLine(rel) {
|
|
65
|
+
if (path.isAbsolute(rel)) return null;
|
|
66
|
+
const n = path.posix.normalize(rel);
|
|
67
|
+
if (n === '.' || n.startsWith('../') || n === '..') return null;
|
|
68
|
+
return `/${n.replace(/^\.\//, '')}/`;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Root-anchored `.git/info/exclude` lines for every scratch dir — configured plans, configured
|
|
73
|
+
* briefs, and the legacy `.claude/plans/` (kept: a clone may still hold pre-#488 files).
|
|
74
|
+
*/
|
|
75
|
+
function excludeLines(env = process.env) {
|
|
76
|
+
const out = [];
|
|
77
|
+
for (const rel of [plansDirSetting(env), briefsDirSetting(env), LEGACY_PLANS_DIR]) {
|
|
78
|
+
const line = anchoredLine(rel);
|
|
79
|
+
if (line && !out.includes(line)) out.push(line);
|
|
80
|
+
}
|
|
81
|
+
return out;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Is a repo-relative path (as `git status --porcelain` prints it) inside a scratch dir? Used to
|
|
86
|
+
* keep scratch out of the uncommitted-work gate: a plan or brief left in a worktree is disposable
|
|
87
|
+
* by definition, and must never be what makes a teardown refuse (#488).
|
|
88
|
+
*/
|
|
89
|
+
function isScratchPath(relPath, env = process.env) {
|
|
90
|
+
const p = String(relPath || '').replace(/^"|"$/g, '').replace(/\\/g, '/').replace(/^\.\//, '');
|
|
91
|
+
return excludeLines(env).some((line) => p.startsWith(line.slice(1)));
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** Drop porcelain lines (`?? path`, ` M path`) whose path is scratch. Text in, text out. */
|
|
95
|
+
function withoutScratch(porcelainText, env = process.env) {
|
|
96
|
+
if (!porcelainText) return porcelainText;
|
|
97
|
+
return String(porcelainText).split('\n')
|
|
98
|
+
.filter((l) => l && !isScratchPath(l.slice(3), env))
|
|
99
|
+
.join('\n');
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
module.exports = {
|
|
103
|
+
DEFAULT_PLANS_DIR, DEFAULT_BRIEFS_DIR, LEGACY_PLANS_DIR, LEGACY_BRIEFS_DIR,
|
|
104
|
+
plansDirSetting, briefsDirSetting, planWriteDir, briefsWriteDir, planReadDirs,
|
|
105
|
+
excludeLines, isScratchPath, withoutScratch,
|
|
106
|
+
};
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* Trunk "tree already green" (#493) — the pure half of the rule, shared by `colab ship` / `colab
|
|
4
|
+
* trunk-ci` (tools/colab readCiVerdict) and the audit. No gh, no git, no I/O.
|
|
5
|
+
*
|
|
6
|
+
* THE RULE. A ship squash-merges a branch whose green run already contained the current base, so
|
|
7
|
+
* the trunk commit's tree is byte-identical to the tree that branch run passed. The CI templates'
|
|
8
|
+
* `dedupe` guard therefore skips the suite on a trunk push when it finds a green `push` run of the
|
|
9
|
+
* same workflow, on another ref of this repo, at exactly this tree — and leaves a
|
|
10
|
+
* `tree-already-green` notice annotation naming the run it relied on. A run in that shape (the
|
|
11
|
+
* guard succeeded, everything else skipped) concludes `success`, which is already the verdict;
|
|
12
|
+
* this module only lets the reader FIND the citation, and say so.
|
|
13
|
+
*
|
|
14
|
+
* Why read the citation from an annotation: job outputs and step summaries are not readable over
|
|
15
|
+
* the REST API, and a job name cannot carry a step output. An annotation is durable, shows in the
|
|
16
|
+
* UI, and is one call per skip-run. Why not recompute tree equality here instead: a second copy of
|
|
17
|
+
* the guard's matching logic in JavaScript is exactly the drift this repo keeps measuring.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
const NOTICE_TITLE = 'tree-already-green';
|
|
21
|
+
|
|
22
|
+
/** `tree-reuse:` in project.yml. Absent = reuse on. `off` = the one legal value. */
|
|
23
|
+
function parseTreeReuse(doc) {
|
|
24
|
+
const has = !!doc && Object.prototype.hasOwnProperty.call(doc, 'tree-reuse');
|
|
25
|
+
if (!has || doc['tree-reuse'] === null || doc['tree-reuse'] === undefined) {
|
|
26
|
+
return { declared: false, valid: true, off: false, value: null, reason: 'tree-reuse absent — trunk may reuse a green run of an identical tree (#493)' };
|
|
27
|
+
}
|
|
28
|
+
const v = doc['tree-reuse'];
|
|
29
|
+
// YAML 1.1 readers turn a bare `off` into boolean false; both spell the same intent.
|
|
30
|
+
if (v === 'off' || v === false) {
|
|
31
|
+
return { declared: true, valid: true, off: true, value: 'off', reason: 'tree-reuse: off — trunk always runs its full suite' };
|
|
32
|
+
}
|
|
33
|
+
return {
|
|
34
|
+
declared: true, valid: false, off: true, value: v,
|
|
35
|
+
reason: `tree-reuse is ${JSON.stringify(v)} — the only defined value is "off"; the CI guard reads ANY tree-reuse line as off, so trunk runs its full suite, but say what you mean`,
|
|
36
|
+
};
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* From a commit's check runs (`[{id, name, status, conclusion, suite, annotations}]`), the ids of
|
|
41
|
+
* the check runs that ARE a tree-skip: in one check suite (one workflow run), exactly one job
|
|
42
|
+
* succeeded, it carries at least one annotation, and every other job was skipped (at least one).
|
|
43
|
+
* Name-independent on purpose — adopters rename jobs. Null in, null out (a failed read is not "none").
|
|
44
|
+
*/
|
|
45
|
+
function treeSkipCheckRuns(checkRuns) {
|
|
46
|
+
if (!Array.isArray(checkRuns)) return null;
|
|
47
|
+
const bySuite = new Map();
|
|
48
|
+
for (const c of checkRuns) {
|
|
49
|
+
if (!c || c.suite == null) continue;
|
|
50
|
+
if (!bySuite.has(c.suite)) bySuite.set(c.suite, []);
|
|
51
|
+
bySuite.get(c.suite).push(c);
|
|
52
|
+
}
|
|
53
|
+
const ids = [];
|
|
54
|
+
for (const runs of bySuite.values()) {
|
|
55
|
+
const ok = runs.filter((c) => c.status === 'completed' && c.conclusion === 'success');
|
|
56
|
+
const skipped = runs.filter((c) => c.status === 'completed' && c.conclusion === 'skipped');
|
|
57
|
+
if (ok.length === 1 && skipped.length >= 1 && ok.length + skipped.length === runs.length && Number(ok[0].annotations) > 0) {
|
|
58
|
+
ids.push(ok[0].id);
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
return ids;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** The citation in a check run's annotations (`[{title, message}]`), or null. */
|
|
65
|
+
function parseCitation(annotations) {
|
|
66
|
+
if (!Array.isArray(annotations)) return null;
|
|
67
|
+
const a = annotations.find((x) => x && x.title === NOTICE_TITLE && typeof x.message === 'string');
|
|
68
|
+
if (!a) return null;
|
|
69
|
+
const m = a.message.trim().match(/^(\S+)\s+tree=([0-9a-f]+)\s+head=([0-9a-f]+)\s+branch=(\S+)$/i);
|
|
70
|
+
if (!m) return null;
|
|
71
|
+
const runId = (m[1].match(/\/runs\/(\d+)/) || [])[1] || null;
|
|
72
|
+
return { url: m[1], runId, tree: m[2], head: m[3], branch: m[4] };
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* The verdict suffix for a green trunk read that relied on cited runs. `cites`: [{url, branch,
|
|
77
|
+
* head, proof}] where proof is 'verified' | 'unverified'; `unreadable`: count of skip-runs whose
|
|
78
|
+
* citation could not be read. '' when there is nothing to say (an ordinary green run).
|
|
79
|
+
*/
|
|
80
|
+
function citationNote(cites, unreadable = 0) {
|
|
81
|
+
const parts = (cites || []).map((c) =>
|
|
82
|
+
`relied on ${c.url} (${c.branch}@${String(c.head).slice(0, 7)}${c.proof === 'verified' ? ', tree verified locally' : ', tree not verified locally'})`);
|
|
83
|
+
for (let i = 0; i < unreadable; i++) parts.push('cited run unreadable');
|
|
84
|
+
if (!parts.length) return '';
|
|
85
|
+
return ` — tree already green (#493): suite skipped, ${parts.join('; ')}`;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
module.exports = { NOTICE_TITLE, parseTreeReuse, treeSkipCheckRuns, parseCitation, citationNote };
|