@futurelastic/colab-handbook 1.12.0-rc.11 → 1.12.0-rc.13

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 CHANGED
@@ -1270,12 +1270,14 @@ function auditRepo(target, ctx) {
1270
1270
  // ---- ship-batch (#373) ------------------------------------------------------
1271
1271
  // Batch landing's opt-in: an integer 1–3 (tools/lib/ship-batch.js parseShipBatch — the one reading
1272
1272
  // `colab ship --batch` uses, so the two cannot disagree). A malformed value makes ship fail closed
1273
- // to serial, which is safe but silent, so it fails here. Two further shapes are inert rather than
1273
+ // to serial, which is safe but silent, so it fails here — and, since this audit is run by hand, in
1274
+ // the CI templates' descriptor check too (#416, held to this same parser by
1275
+ // tools/lib/ci-template-descriptor-check.test.js). Two further shapes are inert rather than
1274
1276
  // wrong, so they warn: no workflow fires on a `ship-batch/**` push (the combined run can never
1275
1277
  // arrive), and no `autonomy: auto-trunk` (a batch lands in one unattended push, which needs it).
1276
1278
  if ("ship-batch" in (cfg || {}) && cfg["ship-batch"] !== null) {
1277
1279
  const sbCfg = shipBatch.parseShipBatch(cfg);
1278
- if (!sbCfg.valid) fail(sbCfg.reason);
1280
+ if (!sbCfg.valid) fail(`${sbCfg.reason} — the cap is deliberate, see project.schema.md, ship-batch`);
1279
1281
  else if (sbCfg.n > 1) {
1280
1282
  const firing = workflowsFiringOnBranchPush({ readFile: (p) => src.readFile(p), workflows, branch: shipBatch.PROBE_REF });
1281
1283
  if (!firing.length) warn(`ship-batch: ${sbCfg.n} but no workflow in .github/workflows fires on a push to ship-batch/** — colab ship --batch will always fall back to serial; add 'ship-batch/**' to a CI workflow's push: branches:`);
package/package.json CHANGED
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.11"
30
+ "version": "1.12.0-rc.13"
31
31
  }
@@ -154,6 +154,31 @@ jobs:
154
154
  with:
155
155
  persist-credentials: false
156
156
 
157
+ # ---------------------------------------------------------------------------
158
+ # Descriptor check (#416). A value `colab ship` cannot use does not fail there —
159
+ # it fails closed to the safe default, silently. `ship-batch: 5` (the cap is 3)
160
+ # once turned every landing in a busy repo back to serial while this CI stayed
161
+ # green; only a ship dry run noticed. So the value fails HERE, where the person
162
+ # who changed project.yml is looking. Same rule as `colab ship` and the audit
163
+ # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
164
+ # cap is 3: project.schema.md, `ship-batch`.
165
+ # ---------------------------------------------------------------------------
166
+ - name: Descriptor check (.github/project.yml)
167
+ working-directory: ${{ github.workspace }}
168
+ run: |
169
+ [ -f .github/project.yml ] || exit 0
170
+ line="$(grep -E '^ship-batch[[:space:]]*:' .github/project.yml | head -1 || true)"
171
+ [ -n "$line" ] || exit 0
172
+ v="$(printf '%s\n' "$line" | sed -E -e 's/^ship-batch[[:space:]]*:[[:space:]]*//' \
173
+ -e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
174
+ -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
175
+ case "$v" in
176
+ ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
177
+ *)
178
+ echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-3 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 3: project.schema.md, ship-batch."
179
+ exit 1 ;;
180
+ esac
181
+
157
182
  # ---------------------------------------------------------------------------
158
183
  # Toolchain resolution. Precedence, highest first:
159
184
  # PHP : 1. .github/project.yml -> php: 2. composer.json -> require.php
@@ -13,6 +13,7 @@
13
13
  # `php artisan wayfinder:generate` and needs PHP on the runner. Use ci-laravel.yml.
14
14
  #
15
15
  # What it does:
16
+ # 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416).
16
17
  # 1. Resolve the Node version from declared sources — never a hardcoded default.
17
18
  # 2. Secret scan with gitleaks (pinned release binary, see note at the step).
18
19
  # 3. Install dependencies with the package manager the lockfile implies.
@@ -147,6 +148,31 @@ jobs:
147
148
  with:
148
149
  persist-credentials: false
149
150
 
151
+ # ---------------------------------------------------------------------------
152
+ # Descriptor check (#416). A value `colab ship` cannot use does not fail there —
153
+ # it fails closed to the safe default, silently. `ship-batch: 5` (the cap is 3)
154
+ # once turned every landing in a busy repo back to serial while this CI stayed
155
+ # green; only a ship dry run noticed. So the value fails HERE, where the person
156
+ # who changed project.yml is looking. Same rule as `colab ship` and the audit
157
+ # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
158
+ # cap is 3: project.schema.md, `ship-batch`.
159
+ # ---------------------------------------------------------------------------
160
+ - name: Descriptor check (.github/project.yml)
161
+ working-directory: ${{ github.workspace }}
162
+ run: |
163
+ [ -f .github/project.yml ] || exit 0
164
+ line="$(grep -E '^ship-batch[[:space:]]*:' .github/project.yml | head -1 || true)"
165
+ [ -n "$line" ] || exit 0
166
+ v="$(printf '%s\n' "$line" | sed -E -e 's/^ship-batch[[:space:]]*:[[:space:]]*//' \
167
+ -e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
168
+ -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
169
+ case "$v" in
170
+ ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
171
+ *)
172
+ echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-3 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 3: project.schema.md, ship-batch."
173
+ exit 1 ;;
174
+ esac
175
+
150
176
  # ---------------------------------------------------------------------------
151
177
  # Toolchain resolution. Precedence, highest first:
152
178
  # 1. .github/project.yml -> node: <version>
@@ -27,6 +27,7 @@
27
27
  # NOT for: Laravel + Inertia fullstack apps — use ci-laravel.yml.
28
28
  #
29
29
  # What it does:
30
+ # 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416).
30
31
  # 1. Resolve the Python version from declared sources — never a hardcoded default.
31
32
  # 2. Secret scan with gitleaks (pinned release binary, see note at the step).
32
33
  # 3. Install dependencies from whichever manifest the repo actually has.
@@ -138,6 +139,31 @@ jobs:
138
139
  with:
139
140
  persist-credentials: false
140
141
 
142
+ # ---------------------------------------------------------------------------
143
+ # Descriptor check (#416). A value `colab ship` cannot use does not fail there —
144
+ # it fails closed to the safe default, silently. `ship-batch: 5` (the cap is 3)
145
+ # once turned every landing in a busy repo back to serial while this CI stayed
146
+ # green; only a ship dry run noticed. So the value fails HERE, where the person
147
+ # who changed project.yml is looking. Same rule as `colab ship` and the audit
148
+ # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
149
+ # cap is 3: project.schema.md, `ship-batch`.
150
+ # ---------------------------------------------------------------------------
151
+ - name: Descriptor check (.github/project.yml)
152
+ working-directory: ${{ github.workspace }}
153
+ run: |
154
+ [ -f .github/project.yml ] || exit 0
155
+ line="$(grep -E '^ship-batch[[:space:]]*:' .github/project.yml | head -1 || true)"
156
+ [ -n "$line" ] || exit 0
157
+ v="$(printf '%s\n' "$line" | sed -E -e 's/^ship-batch[[:space:]]*:[[:space:]]*//' \
158
+ -e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
159
+ -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
160
+ case "$v" in
161
+ ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
162
+ *)
163
+ echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-3 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 3: project.schema.md, ship-batch."
164
+ exit 1 ;;
165
+ esac
166
+
141
167
  # ---------------------------------------------------------------------------
142
168
  # Toolchain resolution. Precedence, highest first:
143
169
  # 1. .github/project.yml -> python: <version>
package/tools/colab CHANGED
@@ -57,6 +57,7 @@ const claimComments = require('./lib/claim-comments');
57
57
  const machine = require('./lib/machine');
58
58
  const targetSync = require('./lib/ship-target-sync');
59
59
  const shipBatch = require('./lib/ship-batch');
60
+ const conflictMarkers = require('./lib/conflict-markers');
60
61
  const docsOnly = require('./lib/docs-only');
61
62
  const cureDiff = require('./lib/cure-diff');
62
63
  const codeowners = require('./lib/codeowners');
@@ -4872,6 +4873,19 @@ function worktreeSubdir(config) { return config.worktreeSubdir || '.worktrees';
4872
4873
  // slow-but-working. Overridable per-machine/per-repo for a legitimately slow teardown.
4873
4874
  const TEARDOWN_TIMEOUT_MS = Number(process.env.COLAB_TEARDOWN_TIMEOUT_MS) || 5 * 60 * 1000;
4874
4875
 
4876
+ /**
4877
+ * #436: after a pre-ship hook exits 0, which of the paths it was handed still carry conflict markers
4878
+ * in the index — i.e. would be committed with `<<<<<<<` in them. Untrimmed git output, so the line
4879
+ * numbers in the message are the file's own.
4880
+ */
4881
+ function stagedConflictMarkers(dir, paths) {
4882
+ const rawGit = (args, cwd) => {
4883
+ const r = spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
4884
+ return { ok: r.status === 0, stdout: r.stdout || '' };
4885
+ };
4886
+ return conflictMarkers.stagedMarkerPaths(rawGit, dir, paths);
4887
+ }
4888
+
4875
4889
  function runHook(repoAbs, name, ctx) {
4876
4890
  const hook = path.join(repoAbs, '.colab', 'hooks', name);
4877
4891
  try {
@@ -9439,8 +9453,12 @@ for is built in its place, so the survivors of a decline can batch without landi
9439
9453
  A member that conflicts with the members already in is dropped to the next batch; the rest go on —
9440
9454
  unless every conflicting path is generated (defaults + project.yml generated:): then .colab/hooks/pre-ship
9441
9455
  regenerates them on the combined head and the member stays in (#387). No hook, or a failing one → dropped.
9442
- --dry builds the batch locally and prints it, pushing nothing. Consumer CI must opt in: add
9443
- 'ship-batch/**' to a CI workflow's push: branches:.
9456
+ A hook that exits 0 but leaves a <<<<<<< / >>>>>>> line staged in a path it was handed counts as failing (#436).
9457
+ Resuming a staged batch: a branch you name that the staged batch does not carry (over the cap, dropped
9458
+ at build, added since) is NOT landed with it — the command names both lists and says so (#415).
9459
+ --dry pushes, deletes, lands, comments and releases nothing on EVERY path (#415): a fresh batch is built
9460
+ locally and printed; a staged green batch prints what would land (members, combined run, target sha).
9461
+ Consumer CI must opt in: add 'ship-batch/**' to a CI workflow's push: branches:.
9444
9462
 
9445
9463
  B3 KEEPS the branch by default. Deleting refs from a shared remote is not something this command
9446
9464
  does unasked, however certain it is that the content landed: reporting is safe and reversible,
@@ -11849,6 +11867,14 @@ function cmdShip(argv) {
11849
11867
  }
11850
11868
  if (hasPreShip) {
11851
11869
  const hk = runHook(repoAbs, 'pre-ship', { wtPath: branchDir, name: sess.name || sess.branch, branch: sess.branch, ports: [], trunk, base: target, issues: sess.issues });
11870
+ // #436: exit 0 is the hook's claim; the index is the proof. Markers left in a path it was
11871
+ // handed make it a failing hook, checked BEFORE the commit so nothing carrying them is pushed.
11872
+ const markers = hk.ran && hk.ok ? stagedConflictMarkers(branchDir, uf) : [];
11873
+ if (markers.length) {
11874
+ git.git(['merge', '--abort'], branchDir); cleanupEphemeral();
11875
+ process.stderr.write(`✗ B0: pre-ship hook exited 0 but left conflict markers staged in ${conflictMarkers.describe(markers)} — treated as a failing hook. Nothing pushed.\n`);
11876
+ return 1;
11877
+ }
11852
11878
  const committed = hk.ran && hk.ok && git.git(['commit', '--no-edit'], branchDir).ok;
11853
11879
  if (!committed) {
11854
11880
  git.git(['merge', '--abort'], branchDir); cleanupEphemeral();
@@ -12493,7 +12519,9 @@ function cmdShipBatch(opts) {
12493
12519
  const batchRefs = (lsBatch.ok ? lsBatch.stdout.split('\n') : []).map((l) => l.split('\t'))
12494
12520
  .map(([sha, ref]) => ({ sha: (sha || '').trim(), parsed: shipBatch.parseBatchRef((ref || '').trim()) }))
12495
12521
  .filter((x) => x.sha && x.parsed);
12522
+ // #415: every write on the resume path goes through here or shipBatchLand — under --dry, neither writes.
12496
12523
  const deleteRef = (ref) => {
12524
+ if (opts.dry) { print(` [dry] would delete ${remote}/${ref}`); return true; }
12497
12525
  const d = git.git(['push', remote, '--delete', ref], repoAbs);
12498
12526
  if (!d.ok) warn(`could not delete ${remote}/${ref}: ${git.gitFailureLine(d.stderr)} — delete it by hand`);
12499
12527
  return d.ok;
@@ -12523,6 +12551,14 @@ function cmdShipBatch(opts) {
12523
12551
  const heads = inBatch.map((m) => ({ ...m, now: git.branchRefs(repoAbs, m.branch, remote).remoteSha }));
12524
12552
  const matches = heads.length >= 2 && heads.every((m) => m.now && m.now.startsWith(m.sha));
12525
12553
  existing = { ref: atBase.parsed.ref, base7: atBase.parsed.base7, sha: atBase.sha, members: inBatch, matches };
12554
+ // #415: the command line and the staged batch can name different sets. A requested branch the
12555
+ // staged batch does not carry (over the cap, dropped at build, or added since) does NOT ride
12556
+ // along — say so, naming both lists, instead of resuming as if the two were the same.
12557
+ const notStaged = shipBatch.notStaged(members, inBatch);
12558
+ if (notStaged.length) {
12559
+ print(` ! ${atBase.parsed.ref} was staged with ${inBatch.map((m) => m.branch).join(', ')}; this command named ${members.join(', ')}.`);
12560
+ print(` NOT in the staged batch, so it does not land with it: ${notStaged.join(', ')} — ship it after this batch (next batch, or colab ship --branch <b>).`);
12561
+ }
12526
12562
  }
12527
12563
  }
12528
12564
  const verdict = existing && existing.matches ? shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, existing.ref, existing.sha)) : null;
@@ -12549,7 +12585,7 @@ function cmdShipBatch(opts) {
12549
12585
  return 4;
12550
12586
  }
12551
12587
  if (step.step === 'red-serial') {
12552
- print(`✗ ship-batch: the combined run is red again after its one re-run (${verdict.why}) — nothing landed; ${existing.ref} deleted.`);
12588
+ print(`✗ ship-batch: the combined run is red again after its one re-run (${verdict.why}) — nothing landed; ${existing.ref} ${opts.dry ? 'would be deleted [DRY RUN]' : 'deleted'}.`);
12553
12589
  deleteRef(existing.ref);
12554
12590
  print(shipBatch.serialLine(existing.members.map((m) => m.branch)));
12555
12591
  return 4;
@@ -12616,8 +12652,13 @@ function cmdShipBatch(opts) {
12616
12652
  issues: (m.report && m.report.closeIssues) || [],
12617
12653
  });
12618
12654
  const left = hk.ran ? unmergedIn() : unmerged;
12655
+ // #436: a hook that exits 0 and `git add`s a path still holding markers clears the unmerged
12656
+ // state, so `left` reads empty — read the staged content itself before trusting it.
12657
+ const markers = hk.ran && hk.ok && !left.length ? stagedConflictMarkers(dir, unmerged) : [];
12619
12658
  if (!hk.ran || !hk.ok || left.length) {
12620
12659
  why = `.colab/hooks/pre-ship could not regenerate ${unmerged.join(', ')} on the combined head${left.length && hk.ok ? ` (still unmerged: ${left.join(', ')})` : ''} — next batch`;
12660
+ } else if (markers.length) {
12661
+ why = `.colab/hooks/pre-ship exited 0 but left conflict markers staged in ${conflictMarkers.describe(markers)} on the combined head — treated as a failing hook, next batch`;
12621
12662
  } else regenerated = unmerged;
12622
12663
  }
12623
12664
  if (why) {
@@ -12684,6 +12725,14 @@ function cmdShipBatch(opts) {
12684
12725
  */
12685
12726
  function shipBatchLand(repoAbs, doc, trunk, remote, base, existing, verdict, opts) {
12686
12727
  const head = existing.sha;
12728
+ // #415: a staged green batch reached under --dry is a read: what WOULD land, and nothing else —
12729
+ // no fast-forward, no push, no ref delete, no hook, no worktree teardown, no claim, no comment.
12730
+ if (opts.dry) {
12731
+ print(`ship --batch ${shortRepo(repoAbs)} → ${trunk} @ ${shortSha(base)} [DRY RUN]`);
12732
+ print(`→ READY: would fast-forward ${trunk} ${shortSha(base)} → ${shortSha(head)} — ${existing.ref}, combined run ${(verdict.runIds || []).join(', ') || '(id unread)'} ${verdict.why || verdict.state}`);
12733
+ print(` would land ${existing.members.length} member(s), one squash each: ${existing.members.map((m) => m.branch).join(', ')}`);
12734
+ return 0;
12735
+ }
12687
12736
  const headBranch = git.git(['rev-parse', '--abbrev-ref', 'HEAD'], repoAbs).stdout;
12688
12737
  if (headBranch !== trunk || git.dirtyTracked(repoAbs)) {
12689
12738
  throw new UserError(`the main checkout is not on a clean ${trunk} ("${headBranch}"${git.dirtyTracked(repoAbs) ? ', dirty' : ''}) — the batch is green and waiting; fix the checkout and run this command again`);
@@ -0,0 +1,47 @@
1
+ 'use strict';
2
+ /**
3
+ * #436: a pre-ship hook's exit code is a claim ("ZERO means every conflicted path was resolved"),
4
+ * not proof. A hook that regenerates a path's NEW layout and then `git add`s an OLD path still full
5
+ * of conflict markers exits 0 and stages the markers — git clears the unmerged state on `add`, so
6
+ * `git diff --diff-filter=U` reads clean. This reads what would actually be committed.
7
+ *
8
+ * Detection is deliberately `<<<<<<<` / `>>>>>>>` at column 0 (followed by a space or end of line).
9
+ * A bare `=======` line is NOT a marker on its own: it is also a legitimate Markdown setext-heading
10
+ * underline, and generated docs are exactly the files this check reads. Every real conflict block
11
+ * carries the two outer markers, so nothing is missed by not counting the middle one alone.
12
+ */
13
+
14
+ const MARKER = /^(<{7}|>{7})(?:[ \t]|$)/;
15
+
16
+ /** Pure: 1-based line numbers of conflict-marker lines in `text`. */
17
+ function markerLines(text) {
18
+ const out = [];
19
+ String(text == null ? '' : text).split('\n').forEach((line, i) => {
20
+ if (MARKER.test(line.replace(/\r$/, ''))) out.push(i + 1);
21
+ });
22
+ return out;
23
+ }
24
+
25
+ /**
26
+ * Which of `paths` still hold conflict markers in the INDEX (stage 0 — what `git commit` takes) at
27
+ * `cwd`. `gitFn(args, cwd)` → `{ ok, stdout }`. A path absent from the index (deleted, or still
28
+ * unmerged at stages 1-3) is skipped here: deletion is a resolution, and an unmerged path is the
29
+ * caller's existing `--diff-filter=U` check. Returns `[{ path, lines }]`.
30
+ */
31
+ function stagedMarkerPaths(gitFn, cwd, paths) {
32
+ const hits = [];
33
+ for (const p of [...new Set(paths || [])]) {
34
+ const r = gitFn(['show', `:0:${p}`], cwd);
35
+ if (!r || !r.ok) continue;
36
+ const lines = markerLines(r.stdout);
37
+ if (lines.length) hits.push({ path: p, lines });
38
+ }
39
+ return hits;
40
+ }
41
+
42
+ /** One line naming each path and its first marker lines. */
43
+ function describe(hits) {
44
+ return (hits || []).map((h) => `${h.path}:${h.lines.slice(0, 3).join(',')}${h.lines.length > 3 ? ',…' : ''}`).join(', ');
45
+ }
46
+
47
+ module.exports = { markerLines, stagedMarkerPaths, describe };
@@ -257,6 +257,16 @@ function batchGreenCoversTrunk({ trunkRows, batchRows, trunkFires, batchFires })
257
257
  return (batchRows || []).length >= a.length;
258
258
  }
259
259
 
260
+ /**
261
+ * #415: branches the command line names that a staged batch does not carry, in command-line order.
262
+ * `staged` is parseMemberTrailers' `[{ branch }]`. Not a refusal on its own: a branch over the cap or
263
+ * dropped at build is EXPECTED to be missing on resume — the caller must say so, never stay silent.
264
+ */
265
+ function notStaged(requested, staged) {
266
+ const have = new Set((staged || []).map((m) => m && m.branch).filter(Boolean));
267
+ return [...new Set(requested || [])].filter((b) => b && !have.has(b));
268
+ }
269
+
260
270
  /** The clause each member's 🚢 evidence comment gains: which combined run graded it. */
261
271
  function evidenceSuffix({ n, ref, headSha, runIds }) {
262
272
  const runs = (runIds || []).length ? (runIds || []).join(', ') : '(id unread)';
@@ -273,5 +283,5 @@ module.exports = {
273
283
  MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY,
274
284
  parseShipBatch, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
275
285
  branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep,
276
- batchGreenCoversTrunk, evidenceSuffix, serialLine,
286
+ batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged,
277
287
  };