@futurelastic/colab-handbook 1.12.0 → 1.13.0-rc.1

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.
Files changed (73) hide show
  1. package/README.md +243 -213
  2. package/README.vi.md +246 -186
  3. package/audit/audit.mjs +193 -10
  4. package/package.json +6 -1
  5. package/templates/README.md +30 -2
  6. package/templates/ci-laravel.yml +102 -21
  7. package/templates/ci-node.yml +61 -3
  8. package/templates/ci-python.yml +52 -3
  9. package/templates/deploy-adapter-portainer.mjs +206 -0
  10. package/templates/deploy-container-run.mjs +368 -0
  11. package/templates/deploy-container.yml +219 -0
  12. package/templates/dist-refs.yml +6 -0
  13. package/templates/docs-lint.mjs +1 -1
  14. package/templates/npx-launcher.mjs +118 -20
  15. package/templates/npx-service.mjs +828 -0
  16. package/templates/release-auto.yml +341 -32
  17. package/tools/colab +1691 -254
  18. package/tools/lib/adopt.js +373 -14
  19. package/tools/lib/branch-name.js +29 -1
  20. package/tools/lib/ci-cure.js +522 -31
  21. package/tools/lib/ci-grant.js +289 -22
  22. package/tools/lib/ci-wait.js +203 -0
  23. package/tools/lib/claim-comments.js +13 -64
  24. package/tools/lib/claim-identity.js +4 -7
  25. package/tools/lib/codec/claim.d.ts +41 -0
  26. package/tools/lib/codec/claim.js +151 -0
  27. package/tools/lib/codec/decision.d.ts +29 -0
  28. package/tools/lib/codec/decision.js +81 -0
  29. package/tools/lib/codec/grants.d.ts +82 -0
  30. package/tools/lib/codec/grants.js +268 -0
  31. package/tools/lib/codec/hold.d.ts +26 -0
  32. package/tools/lib/codec/hold.js +152 -0
  33. package/tools/lib/codec/index.d.ts +21 -0
  34. package/tools/lib/codec/index.js +32 -0
  35. package/tools/lib/codec/labels.d.ts +65 -0
  36. package/tools/lib/codec/labels.js +716 -0
  37. package/tools/lib/codec/markers.d.ts +35 -0
  38. package/tools/lib/codec/markers.js +138 -0
  39. package/tools/lib/codec/release.d.ts +17 -0
  40. package/tools/lib/codec/release.js +69 -0
  41. package/tools/lib/codec/samples.json +762 -0
  42. package/tools/lib/codeowners.js +68 -4
  43. package/tools/lib/container-close.js +38 -0
  44. package/tools/lib/cure-diff.js +198 -9
  45. package/tools/lib/decision-record.js +15 -39
  46. package/tools/lib/docs-only.js +15 -1
  47. package/tools/lib/exposure-shape.js +42 -8
  48. package/tools/lib/git.js +303 -42
  49. package/tools/lib/group-labels.js +65 -0
  50. package/tools/lib/install-check.js +14 -8
  51. package/tools/lib/install-route.js +139 -0
  52. package/tools/lib/instruction-file.js +1 -0
  53. package/tools/lib/labels.js +22 -647
  54. package/tools/lib/local-adopt.js +8 -4
  55. package/tools/lib/migration-grant.js +206 -104
  56. package/tools/lib/place.js +2 -2
  57. package/tools/lib/release-cut.js +199 -25
  58. package/tools/lib/release-finalize.js +111 -23
  59. package/tools/lib/release-policy.js +130 -22
  60. package/tools/lib/release-runner.js +125 -0
  61. package/tools/lib/release-tag.js +3 -1
  62. package/tools/lib/scratch-dirs.js +106 -0
  63. package/tools/lib/ship-batch.js +36 -1
  64. package/tools/lib/stamp.js +7 -0
  65. package/tools/lib/tracker-fake.js +195 -0
  66. package/tools/lib/tracker-github.js +106 -0
  67. package/tools/lib/tracker-scenarios.json +206 -0
  68. package/tools/lib/tracker.js +64 -0
  69. package/tools/lib/tree-green.js +88 -0
  70. package/tools/lib/util.js +17 -1
  71. package/tools/lib/verify-runs.js +104 -0
  72. package/tools/lib/wake.js +8 -90
  73. package/tools/lib/workflow-triggers.js +48 -0
package/audit/audit.mjs CHANGED
@@ -82,7 +82,7 @@ const {
82
82
  // encode the VALIDATOR half (report every violation) separately from `colab adopt`'s CONSTRUCTOR
83
83
  // half (does declaring this exposure value stay possible at all?). Same install.sh-freezes-
84
84
  // tools/lib/ reasoning as the other requires on this page.
85
- const { evaluateExposure } = require("../tools/lib/exposure-shape.js");
85
+ const { evaluateExposure, singleTrunkViolation } = require("../tools/lib/exposure-shape.js");
86
86
  // #208's `writes` split precedence ladder — same shared-module reasoning as axisAuthority
87
87
  // above, reused for a second axis rather than a bespoke second mechanism.
88
88
  const writesAuthority = require("../tools/lib/writes-authority.js");
@@ -94,6 +94,8 @@ const releasePolicy = require("../tools/lib/release-policy.js");
94
94
  // push-site guard in the CLI, so the audit and the tool can never disagree about what it means.
95
95
  const ownerBranchLib = require("../tools/lib/owner-branch.js");
96
96
  const npmGuard = require("../tools/lib/npm-publish-guard.js");
97
+ const installRoute = require("../tools/lib/install-route.js");
98
+ const releaseRunner = require("../tools/lib/release-runner.js"); // #453
97
99
  const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush } = require("../tools/lib/workflow-triggers.js");
98
100
  const shipBatch = require("../tools/lib/ship-batch.js");
99
101
  // #383: where migrations live — the one rule `colab ship`'s gate and `release cut` read; the audit
@@ -101,10 +103,16 @@ const shipBatch = require("../tools/lib/ship-batch.js");
101
103
  const migrationPaths = require("../tools/lib/migration-paths.js");
102
104
  // #398: the `migration-grant:` policy key — read through the same module `colab migration-grant` uses.
103
105
  const migrationGrant = require("../tools/lib/migration-grant.js");
106
+ // #504: the `ci-grant:` policy key — read through the same module `colab ci-grant` uses.
107
+ const ciGrantLib = require("../tools/lib/ci-grant.js");
104
108
  // #407: the optional `trust-humans` list — read through the same module every grant reader uses.
105
109
  const trustHumansLib = require("../tools/lib/trust-humans.js");
106
110
  // #403: the `live-env:` key — read through the same module `colab gate-hermetic` uses.
107
111
  const hermeticLib = require("../tools/lib/hermetic.js");
112
+ // #493: the `tree-reuse:` opt-out — read through the same module `colab ship` reads citations with.
113
+ const treeGreenLib = require("../tools/lib/tree-green.js");
114
+ // #503: `ship-gate-workflows:` / `ship-ignore-workflows:` — read through the same module ship's CI gate uses.
115
+ const verifyRunsLib = require("../tools/lib/verify-runs.js");
108
116
  // #410: the optional `gate:` block — read through the same module the skills name.
109
117
  const gateLib = require("../tools/lib/gate.js");
110
118
  // #417: CLAUDE.md as a thin shell over AGENTS.md — the @-import resolver and the tool-block table,
@@ -572,13 +580,20 @@ function readRemoteIssue(slug, num) {
572
580
  }
573
581
  }
574
582
 
583
+ // Memoized per slug: several checks read visibility (#432, #453) and one audit run must not pay
584
+ // one API call per check.
585
+ const remoteMetadataCache = new Map();
575
586
  function readRemoteMetadata(slug) {
587
+ if (remoteMetadataCache.has(slug)) return remoteMetadataCache.get(slug);
588
+ let r;
576
589
  try {
577
590
  const out = runGh(["api", `repos/${slug}`]);
578
- return { status: "ok", data: JSON.parse(out) };
591
+ r = { status: "ok", data: JSON.parse(out) };
579
592
  } catch {
580
- return { status: "unreadable" };
593
+ r = { status: "unreadable" };
581
594
  }
595
+ remoteMetadataCache.set(slug, r);
596
+ return r;
582
597
  }
583
598
 
584
599
  // github.com/owner/name, git@github.com:owner/name.git → "owner/name". Non-GitHub or
@@ -1085,6 +1100,10 @@ function renderDuration(age) {
1085
1100
 
1086
1101
  function auditRepo(target, ctx) {
1087
1102
  const src = makeSource(target);
1103
+ // #522: the branch list is read by the single-trunk rule (tier B / exposure none|released) AND the
1104
+ // trunk-exists check below — one read, so a remote target costs one API listing, not three.
1105
+ let branchesMemo;
1106
+ const branchList = () => (branchesMemo === undefined ? (branchesMemo = src.branches()) : branchesMemo);
1088
1107
  const findings = []; // { level: 'fail'|'warn', text }
1089
1108
  // `self` = this target IS the handbook, not one of its consumers. Surfaced in the
1090
1109
  // report (and in --json) so the row reads as source-of-truth rather than clean-by-luck:
@@ -1319,6 +1338,17 @@ function auditRepo(target, ctx) {
1319
1338
  if (!pol.valid) fail(pol.reason);
1320
1339
  }
1321
1340
 
1341
+ // ---- ci-grant (#504) -------------------------------------------------------
1342
+ // Who may open the red-trunk door when the cure rule refuses: `human` (absent) or `reviewer`, the
1343
+ // coordinator agent minting `colab ci-grant --role ci-reviewer` without COLAB_HUMAN=1.
1344
+ // tools/lib/ci-grant.js parseGrantPolicy is the one reading. Always reported (info.ciGrant); an
1345
+ // invalid value fails, because the reader then falls back to `human` silently.
1346
+ {
1347
+ const pol = ciGrantLib.parseGrantPolicy(cfg);
1348
+ info.ciGrant = pol.policy;
1349
+ if (!pol.valid) fail(pol.reason);
1350
+ }
1351
+
1322
1352
  // ---- trust-humans (#407) --------------------------------------------------
1323
1353
  // Which logins count as HUMAN for a grant or a ruling. Absent = the association class, as
1324
1354
  // before. tools/lib/trust-humans.js parseTrustHumans is the one reading. A malformed value
@@ -1341,6 +1371,27 @@ function auditRepo(target, ctx) {
1341
1371
  if (!le.valid) fail(le.reason);
1342
1372
  }
1343
1373
 
1374
+ // ---- tree-reuse (#493) ----------------------------------------------------
1375
+ // `tree-reuse: off` makes the CI templates' guard run trunk's full suite even when a green run
1376
+ // of the same workflow already passed an identical tree. tools/lib/tree-green.js parseTreeReuse
1377
+ // is the one reading. An invalid value fails: the guard reads ANY tree-reuse line as off (the
1378
+ // stricter direction), so the repo gets the full suite — but a value nobody defined is not an answer.
1379
+ {
1380
+ const tr = treeGreenLib.parseTreeReuse(cfg);
1381
+ info.treeReuse = tr.declared ? tr.value : null;
1382
+ if (!tr.valid) fail(tr.reason);
1383
+ }
1384
+
1385
+ // ---- ship-gate-workflows / ship-ignore-workflows (#503) ---------------------
1386
+ // Which workflow runs at trunk's head count as "trunk CI" for ship. Absent = the runs that verify
1387
+ // the code (push / pull_request triggered); post-CI release/deploy runs are set aside. An invalid
1388
+ // list fails: the reader ignores it and applies the default, so the declaration does nothing.
1389
+ {
1390
+ const vp = verifyRunsLib.parsePolicy(cfg);
1391
+ info.shipCiWorkflows = vp.gate || vp.ignore.length ? { gate: vp.gate, ignore: vp.ignore } : null;
1392
+ for (const why of vp.problems) fail(why);
1393
+ }
1394
+
1344
1395
  // ---- gate (#410) ----------------------------------------------------------
1345
1396
  // Local = a fast smoke check, branch CI = the one authoritative gate. tools/lib/gate.js
1346
1397
  // parseGate is the one reading. An invalid block fails: the reader falls back to the local full
@@ -1432,7 +1483,11 @@ function auditRepo(target, ctx) {
1432
1483
  if (grant) {
1433
1484
  const v = releasePolicy.finalGrantVerdict(src.issue ? src.issue(grant.issue) : null, { issue: grant.issue, trust: trustHumansLib.parseTrustHumans(cfg) });
1434
1485
  info.releaseFinalGrant = { issue: grant.issue, ok: v.ok, ruledBy: v.ruledBy };
1435
- if (!v.ok) fail(`release.final: auto on deploy-tag has no resolvable operator grant — ${v.detail} (CONVENTIONS.md §6, An operator-granted automatic final)`);
1486
+ if (!v.ok) {
1487
+ fail(rel.effective.route === releasePolicy.FAST_ROUTE
1488
+ ? `route: deploy-tag-fast has no resolvable operator grant — ${v.detail} (CONVENTIONS.md §6, A final on every green head)`
1489
+ : `release.final: auto on deploy-tag has no resolvable operator grant — ${v.detail} (CONVENTIONS.md §6, An operator-granted automatic final)`);
1490
+ }
1436
1491
  }
1437
1492
  }
1438
1493
 
@@ -1499,6 +1554,13 @@ function auditRepo(target, ctx) {
1499
1554
  }
1500
1555
  }
1501
1556
 
1557
+ // ---- distribution (#469) -----------------------------------------------------
1558
+ // Optional, raw, no default: absent means undeclared — nothing in a repository tells a tool
1559
+ // from a library, so only a declared value is ever checked (checkInstallRoute, below).
1560
+ if ("distribution" in cfg && !installRoute.VALID_DISTRIBUTION.has(cfg.distribution)) {
1561
+ fail(`distribution is ${JSON.stringify(cfg.distribution)}, expected "js" or "compiled" — omit the key if this repository distributes no tool`);
1562
+ }
1563
+
1502
1564
  // ---- axis of record (#144) -----------------------------------------------
1503
1565
  // Which key governs gate count: `exposure` when declared (it wins outright — see
1504
1566
  // tools/lib/axis-authority.js for why this is a function, not a bijection, of `tier`),
@@ -1550,7 +1612,12 @@ function auditRepo(target, ctx) {
1550
1612
  ? `tier A with deploy: tag requires trunk "dev" or "main", found ${JSON.stringify(trunk)}`
1551
1613
  : `tier A requires trunk "dev", found ${JSON.stringify(trunk)} — only a tag-gated A (deploy: tag) may run a single trunk "main"`);
1552
1614
  }
1553
- if (tier === "B" && trunk !== "main") fail(`tier B requires trunk "main", found ${JSON.stringify(trunk)}`);
1615
+ // #522: B is the single-trunk shape — one long-lived branch, any spelling. `master` (or
1616
+ // whatever an existing repo's default is) conforms; a "main" beside a non-main trunk does not.
1617
+ if (tier === "B") {
1618
+ const single = singleTrunkViolation(trunk, branchList());
1619
+ if (single) fail(`tier B requires a single trunk — ${single}`);
1620
+ }
1554
1621
  // C uses A's two-branch split: main = what is live, trunk = where sessions land. #205:
1555
1622
  // this validates the SPLIT, not the spelling — trunk is a declared setting (default
1556
1623
  // "dev", proposed by colab adopt and the templates), never required to literally be
@@ -1642,9 +1709,20 @@ function auditRepo(target, ctx) {
1642
1709
  const deployWorkflows = workflows.filter((f) => /^deploy[-.]/.test(f));
1643
1710
  checkPrereleaseTagTrigger(src, workflows, deploy, fail, warn);
1644
1711
  checkReleaseAuto(src, workflows, cfg, warn);
1712
+ checkFastRouteDeploy(src, workflows, cfg, fail);
1713
+ checkDeployContainer(src, workflows, cfg, warn);
1645
1714
  checkPrivateNpm(src, workflows, fail, warn);
1715
+ checkInstallRoute(src, workflows, cfg, warn);
1716
+ checkReleaseRunner(src, workflows, warn);
1646
1717
 
1647
1718
  const runbook = cfg && "runbook" in cfg ? cfg.runbook : null;
1719
+ // #454: on route deploy-tag-fast the release workflow's own `deploy` job ships the final (a tag
1720
+ // pushed with GITHUB_TOKEN starts no `push: tags` run, so it cannot be a deploy-*.yml). A cutter
1721
+ // that deploys what it tagged IS the in-repo path to production — it is not an external deployer,
1722
+ // and owes no runbook. One whose deploy step is still the placeholder counts too: the path is in
1723
+ // the repo, unfinished, and checkFastRouteDeploy above already fails it by name.
1724
+ const fastDeployers = (fastRouteCutters({ readFile: (p) => src.readFile(p), workflows, cfg }) || {}).deploying || [];
1725
+ const inRepoDeploy = deployWorkflows.length > 0 || fastDeployers.length > 0;
1648
1726
 
1649
1727
  // ---- gate contract, dispatched by axis of record (#144) ------------------
1650
1728
  // `authority` is null only when project.yml itself did not parse (already failed above,
@@ -1665,12 +1743,14 @@ function auditRepo(target, ctx) {
1665
1743
  // runbook documents that path. A deploy: tag repo whose own
1666
1744
  // CI holds the deploy job keeps its deploy-*.yml and needs no
1667
1745
  // runbook — the workflow already commits the answer.
1668
- const externalTagDeploy = deploy === "tag" && !deployWorkflows.length;
1746
+ // So does a deploy-tag-fast repo whose release workflow
1747
+ // deploys the final it cut (#454).
1748
+ const externalTagDeploy = deploy === "tag" && !inRepoDeploy;
1669
1749
  if (deploy === "manual") {
1670
1750
  checkRunbook(src, runbook, fail, warn, "deploy: manual");
1671
1751
  } else if (externalTagDeploy) {
1672
1752
  checkRunbook(src, runbook, fail, warn, "deploy: tag deployed outside CI (an external GitOps poller)");
1673
- } else if (!deployWorkflows.length) {
1753
+ } else if (!inRepoDeploy) {
1674
1754
  fail("tier A but no .github/workflows/deploy-*.yml — the path to production is not in the repo (use deploy: manual + runbook: if it ships by hand, or deploy: tag + runbook: when a GitOps poller deploys the tag from outside CI)");
1675
1755
  }
1676
1756
  if (production === null || production === "") fail("tier A but production is null — set the live URL, or drop to tier B");
@@ -1746,7 +1826,7 @@ function auditRepo(target, ctx) {
1746
1826
  // construction (CONVENTIONS.md §2: no mechanism rule applies to it, not even trunk shape).
1747
1827
  // A `runbook`-kind entry defers to `checkRunbook` here (this file can read the repo and tell
1748
1828
  // "missing" from "unreadable via the API"); every other entry is a ready `fail` message.
1749
- const shapeCtx = { trunk, hasProduction, deploy, hasDeployWorkflow: deployWorkflows.length > 0, deployWorkflowNames: deployWorkflows };
1829
+ const shapeCtx = { trunk, hasProduction, deploy, hasDeployWorkflow: inRepoDeploy, deployWorkflowNames: [...deployWorkflows, ...fastDeployers], branches: branchList() };
1750
1830
  for (const entry of evaluateExposure(exp, shapeCtx)) {
1751
1831
  if (entry.kind === "runbook") checkRunbook(src, runbook, fail, warn, entry.why);
1752
1832
  else fail(entry.message);
@@ -1754,7 +1834,7 @@ function auditRepo(target, ctx) {
1754
1834
  }
1755
1835
 
1756
1836
  // ---- declared trunk actually exists -------------------------------------
1757
- const branches = src.branches();
1837
+ const branches = branchList();
1758
1838
  if (trunk && branches === null) {
1759
1839
  warn(`cannot list branches (not a git checkout, or gh unavailable) — trunk "${trunk}" unverified`);
1760
1840
  } else if (trunk && branches && !branches.includes(trunk)) {
@@ -2537,7 +2617,8 @@ function releaseAutoFindings({ readFile, workflows, cfg }) {
2537
2617
  const text = readFile(`.github/workflows/${wf}`);
2538
2618
  if (!text || !RELEASE_AUTO_RUN.test(text)) continue;
2539
2619
  const runsCut = /\brelease\s+cut\s+--auto\b/.test(text);
2540
- if (runsCut && effective && effective.candidates === "off") {
2620
+ // #446: on deploy-tag-fast candidates are off by design — `cut --auto` tags the final itself.
2621
+ if (runsCut && effective && effective.candidates === "off" && effective.finalize !== "on-green-head") {
2541
2622
  out.push(`${wf} runs \`colab release cut --auto\`, but the release rung leaves candidates off on this descriptor (${effective.route === null ? "no route" : `route ${effective.route}`}) — every run refuses; remove the workflow, or change exposure/deploy/release: deliberately (CONVENTIONS.md §6)`);
2542
2623
  }
2543
2624
  const publishesHere = /\bgh\s+release\s+create\b/.test(text) || /action-gh-release/.test(text) || /uses:\s*\.\/\.github\/workflows\//.test(text);
@@ -2561,6 +2642,75 @@ function checkReleaseAuto(src, workflows, cfg, warn) {
2561
2642
  for (const text of releaseAutoFindings({ readFile: (p) => src.readFile(p), workflows, cfg })) warn(text);
2562
2643
  }
2563
2644
 
2645
+ // ---- route deploy-tag-fast: the final is deployed in the run that tags it (#446) ----------------
2646
+ // A tag pushed with GITHUB_TOKEN starts no `push: tags` workflow, so on this route the workflow that
2647
+ // runs `colab release cut --auto` must itself deploy what it tagged — templates/release-auto.yml's
2648
+ // `deploy` job reads the cut step's `final` output. Fail, not warn: without it every final reaches
2649
+ // the Release page and `stable` while production never moves, and nothing says so. Also fails the
2650
+ // template's deploy step left unedited (it fails every run by design, but the audit says why first).
2651
+ // What the audit cannot check is that the deploy really rolls back on a failed health check —
2652
+ // release.rollback: auto is the operator's statement of that, which is why the grant is required.
2653
+ const FAST_DEPLOY_CONSUMER = /outputs\.(final|deploy-tag)\b|\.final\s*\/\/|jq -r '\.final\b/;
2654
+ const FAST_DEPLOY_UNEDITED = /the deploy step of release-auto\.yml was never edited/;
2655
+ // The cutters and, of those, the ones that deploy the final the cut produced. Null when the effective
2656
+ // route does not finalize on a green head (not the fast route). Shared by the findings below and by
2657
+ // the deploy-presence rule (#454), which counts a deploying cutter as the in-repo deploy path.
2658
+ function fastRouteCutters({ readFile, workflows, cfg }) {
2659
+ const effective = cfg ? releasePolicy.evaluateRelease(cfg).effective : null;
2660
+ if (!effective || effective.finalize !== "on-green-head") return null;
2661
+ const cutters = (workflows || []).filter((wf) => {
2662
+ const t = readFile(`.github/workflows/${wf}`);
2663
+ return t && /\brelease\s+cut\s+--auto\b/.test(t);
2664
+ });
2665
+ const deploying = cutters.filter((wf) => FAST_DEPLOY_CONSUMER.test(readFile(`.github/workflows/${wf}`)));
2666
+ return { cutters, deploying };
2667
+ }
2668
+ function fastRouteDeployFindings({ readFile, workflows, cfg }) {
2669
+ const found = fastRouteCutters({ readFile, workflows, cfg });
2670
+ if (!found) return [];
2671
+ const { cutters, deploying } = found;
2672
+ if (!cutters.length) {
2673
+ return ["route: deploy-tag-fast but no workflow runs `colab release cut --auto` — nothing tags or deploys a final; copy templates/release-auto.yml (CONVENTIONS.md §6, A final on every green head)"];
2674
+ }
2675
+ const out = [];
2676
+ if (!deploying.length) {
2677
+ out.push(`route: deploy-tag-fast, but ${cutters.join(", ")} runs \`colab release cut --auto\` and deploys nothing from its result — a tag pushed with GITHUB_TOKEN starts no \`push: tags\` run, so the final would never deploy; deploy in the same run (templates/release-auto.yml, job \`deploy\`)`);
2678
+ }
2679
+ for (const wf of deploying) {
2680
+ if (FAST_DEPLOY_UNEDITED.test(readFile(`.github/workflows/${wf}`))) {
2681
+ out.push(`route: deploy-tag-fast, but ${wf}'s deploy step is still the template's unedited placeholder — every final would be tagged and published but not deployed; replace it with your deploy (templates/release-auto.yml, DEPLOYING IN THIS RUN)`);
2682
+ }
2683
+ }
2684
+ return out;
2685
+ }
2686
+ function checkFastRouteDeploy(src, workflows, cfg, fail) {
2687
+ for (const text of fastRouteDeployFindings({ readFile: (p) => src.readFile(p), workflows, cfg })) fail(text);
2688
+ }
2689
+
2690
+ // ---- a deploy-container copy needs a version to wait for (#452) ---------------------------------
2691
+ // templates/deploy-container.yml is green only on a verified running version, read from
2692
+ // release.health-url (or a HEALTH_URL the repo set in its own copy). A copy with neither fails every
2693
+ // deploy at its first step — advisory, not a failure: the repo owns the file, and may have wired
2694
+ // the URL in by hand.
2695
+ function deployContainerFindings({ readFile, workflows, cfg }) {
2696
+ const effective = cfg ? releasePolicy.evaluateRelease(cfg).effective : null;
2697
+ if (effective && effective.healthUrl) return [];
2698
+ const out = [];
2699
+ for (const wf of workflows || []) {
2700
+ const text = readFile(`.github/workflows/${wf}`);
2701
+ if (!text) continue;
2702
+ const stamp = parseWorkflowStamp(text);
2703
+ const isCopy = (stamp && stamp.name === "deploy-container") || /deploy-container-run\.mjs/.test(text);
2704
+ if (!isCopy) continue;
2705
+ if (/^\s*HEALTH_URL:\s*["']?https:\/\//m.test(text)) continue;
2706
+ out.push(`${wf} deploys through deploy-container-run, but release.health-url is not declared — its verify step has no version to wait for, so every deploy fails; declare release.health-url (route deploy-tag or deploy-tag-fast)`);
2707
+ }
2708
+ return out;
2709
+ }
2710
+ function checkDeployContainer(src, workflows, cfg, warn) {
2711
+ for (const text of deployContainerFindings({ readFile: (p) => src.readFile(p), workflows, cfg })) warn(text);
2712
+ }
2713
+
2564
2714
  // ---- a private repo never publishes to public npm (#432) ---------------------
2565
2715
  // Visibility is read from the GitHub API, and only when the repo has an npm surface at all (so an
2566
2716
  // npm-free repo costs no API call). Unreadable / no remote → reported as a warn, never passed.
@@ -2584,6 +2734,39 @@ function checkPrivateNpm(src, workflows, fail, warn) {
2584
2734
  for (const f of all) (f.level === "fail" ? fail : warn)(f.text);
2585
2735
  }
2586
2736
 
2737
+ // ---- a declared distributed tool has an install route (#469) -------------------
2738
+ // CONVENTIONS.md §6, Distribution. Runs only when project.yml declares `distribution: js|compiled`,
2739
+ // so an undeclared repository costs no read and no API call. Visibility from the GitHub API, same
2740
+ // derivation as checkPrivateNpm; unreadable → the module accepts either row's route. Advisory:
2741
+ // a publish step in a reusable workflow outside this repository is invisible to it.
2742
+ function checkInstallRoute(src, workflows, cfg, warn) {
2743
+ const distribution = cfg && "distribution" in cfg ? cfg.distribution : null;
2744
+ if (!installRoute.VALID_DISTRIBUTION.has(distribution)) return;
2745
+ const meta = src.metadata ? src.metadata() : { status: "unreadable" };
2746
+ let visibility = null;
2747
+ if (meta.status === "ok" && meta.data) {
2748
+ visibility = meta.data.visibility || (meta.data.private === true ? "private" : meta.data.private === false ? "public" : null);
2749
+ }
2750
+ const reader = { readFile: (p) => src.readFile(p), listDir: (p) => src.listDir(p), workflows };
2751
+ for (const f of installRoute.findings({ distribution, ...reader, visibility })) warn(f.text);
2752
+ }
2753
+
2754
+ // ---- the release workflow runs on the repo's own runners when private (#453) -------------------
2755
+ // A hosted job on a private repo is billed, and a billing refusal fails the release run at trunk's
2756
+ // head — `colab ship` then reads trunk as red. Visibility from the GitHub API, read only when a
2757
+ // release workflow exists; unreadable → nothing reported (advisory, never invented).
2758
+ function checkReleaseRunner(src, workflows, warn) {
2759
+ const readFile = (p) => src.readFile(p);
2760
+ const hasRelease = (workflows || []).some((wf) => releaseRunner.RELEASE_AUTO_RUN.test(readFile(`.github/workflows/${wf}`) || ""));
2761
+ if (!hasRelease) return;
2762
+ const meta = src.metadata ? src.metadata() : { status: "unreadable" };
2763
+ let visibility = null;
2764
+ if (meta.status === "ok" && meta.data) {
2765
+ visibility = meta.data.visibility || (meta.data.private === true ? "private" : meta.data.private === false ? "public" : null);
2766
+ }
2767
+ for (const text of releaseRunner.findings({ readFile, workflows, visibility })) warn(text);
2768
+ }
2769
+
2587
2770
  function checkRunbook(src, runbook, fail, warn, why = "deploy: manual") {
2588
2771
  if (runbook === null || runbook === "") {
2589
2772
  fail(`${why} requires runbook: — name the committed doc that describes how production is reached (e.g. docs/deploy.md), or nobody but you can ship`);
package/package.json CHANGED
@@ -17,6 +17,11 @@
17
17
  "tools/colab",
18
18
  "tools/lib/*.js",
19
19
  "!tools/lib/*.test.js",
20
+ "tools/lib/tracker-scenarios.json",
21
+ "tools/lib/codec/*.js",
22
+ "tools/lib/codec/*.d.ts",
23
+ "tools/lib/codec/samples.json",
24
+ "!tools/lib/codec/*.test.js",
20
25
  "templates/",
21
26
  "audit/audit.mjs"
22
27
  ],
@@ -27,5 +32,5 @@
27
32
  "engines": {
28
33
  "node": ">=18"
29
34
  },
30
- "version": "1.12.0"
35
+ "version": "1.13.0-rc.1"
31
36
  }
@@ -22,12 +22,16 @@ Starting points you **copy into your own repo**. That is the entire model.
22
22
  | `release-tag.yml` | `.github/workflows/release.yml` | Any repo cutting `v*.*.*` releases | Triggers on tag push. Publishes a grouped GitHub Release — a `-rc.N` tag as a pre-release, every summary since the previous *final* tag. No toolchain, no deploy; its header shows the `!v*.*.*-*` exclusion a deploy trigger needs. |
23
23
  | `release-auto.yml` | `.github/workflows/release-auto.yml` | A repo whose release tags land on `main` (`trunk: main`, `deploy: tag` or `none`) and whose §6 release route cuts candidates | Runs `colab release cut --auto` after CI goes green on main and `colab release finalize --auto` daily, from a handbook ref (`HANDBOOK_REF` — the `stable` channel by default, `next` for the fast channel, or an exact tag to freeze; #445) — the handbook's own copy runs its checkout's CLI instead, since it ships the CLI it releases with (#428). **Publishes the Release in the same run** — a tag pushed with `GITHUB_TOKEN` triggers no other workflow, so `release-tag.yml` would never fire for it. A refusal is a warning, not a red run. Reads and creates tags, and fast-forwards the release channels `next` / `stable` (branches naming the newest candidate / final, #445); never pushes a commit. The audit recognises any workflow running `release cut/finalize --auto` and warns when the route leaves candidates off, when it tags without publishing while a tag-push workflow waits, or when it commits. |
24
24
  | `dist-refs.yml` | `.github/workflows/dist-refs.yml` | A **private** repo shipping a **compiled** tool, installed as `npx github:<org>/<repo>#vX.Y.Z` ([CONVENTIONS §6, *Distribution*](../CONVENTIONS.md#distribution--one-install-surface-npx-442)) | `workflow_call`, called from the same run that cut the release tag (a tag pushed with `GITHUB_TOKEN` triggers nothing else). Takes one build artifact per `<os>-<arch>` and pushes each as an orphan commit at `refs/tags/dist/vX.Y.Z/<os>-<arch>` with a `SHA256SUMS`. Refuses a public or unreadable repository (a public compiled tool ships npm platform packages instead), a version that is not an existing tag, and a missing platform — before pushing any. Never moves a dist ref that exists. |
25
- | `npx-launcher.mjs` | anywhere in-repo (e.g. `bin/launch.mjs`), named by the root `package.json`'s `bin` | Pairs with `dist-refs.yml` | Node ≥ 18, zero dependencies, needs `git`. Reads the `#vX.Y.Z` npx installed, fetches that one dist ref with the same URL and credentials npx cloned with, verifies `SHA256SUMS`, installs to a stable per-user path (`$XDG_DATA_HOME`/`%LOCALAPPDATA%`), and execs it; `--print-path` prints that path for a service's `init`. `*.mjs`, so `colab template npx-launcher.mjs --dest <path>` copies it stamped, `--dest` required. One edit point: `BIN` (defaults to the package name without its scope). |
25
+ | `npx-launcher.mjs` | anywhere in-repo (e.g. `bin/launch.mjs`), named by the root `package.json`'s `bin` | Pairs with `dist-refs.yml` | Node ≥ 18, zero dependencies, needs `git`. Reads the `#vX.Y.Z` npx installed, fetches that one dist ref with the same URL and credentials npx cloned with, verifies `SHA256SUMS`, installs to a stable per-user path (`$XDG_DATA_HOME`/`%LOCALAPPDATA%`), and execs it; `--print-path` prints that path. A **channel** committish (`#stable`, `#next`, #465) is resolved to the release tag on the commit npx installed, then installed as that version; any other branch is refused. Also the library `npx-service.mjs` imports. `*.mjs`, so `colab template npx-launcher.mjs --dest <path>` copies it stamped, `--dest` required. One edit point: `BIN` (defaults to the package name without its scope). |
26
+ | `npx-service.mjs` | the same directory as your `npx-launcher.mjs` copy (e.g. `bin/service.mjs`), named by the root `package.json`'s `bin` | A tool that runs as a **per-machine service** (a dashboard, a daemon, a JS app a launch agent serves), installed with npx ([CONVENTIONS §6, *Services over npx*](../CONVENTIONS.md#services-over-npx--init-update-rollback-465)) | `npx github:<org>/<repo>#vX.Y.Z init [--auto-update 6h \| --no-auto-update]`, then `<tool> update [--check] [--version vX.Y.Z] [--channel next\|stable]`, `<tool> rollback`, `<tool> status`, `<tool> uninstall [--purge]` (#472: unit, timer, shim and every version go; config and state stay unless `--purge`); anything else runs the current version's payload. Versions side by side under `$XDG_DATA_HOME/<tool>/` with `current`/`previous` links the unit and the `~/.local/bin` shim go through; update installs beside, switches, restarts, health-checks, and **switches back** on failure. Config/secrets under `$XDG_CONFIG_HOME/<tool>/`, state and logs under `$XDG_STATE_HOME/<tool>/` — the unit carries their locations, never a value. launchd agent on macOS, systemd user unit on Linux, Windows refused; `<TOOL>_SERVICE_MANAGER=none` skips the manager. `--auto-update` (#471) adds a timer (launchd `StartInterval` agent / systemd user `.timer`) that runs the same `update`. Node ≥ 18, zero dependencies; needs `git`, `npm` for `update`, `tar` for `dist`. **Imports `./npx-launcher.mjs`** — copy both, or edit the import. Edit points: `KIND` (`binary` = a compiled tool from dist refs, `package` = a JS app run with node, `dist` = a prebuilt JS app unpacked from one verified tarball in the `dist/vX.Y.Z/any` ref, #470), `LABEL`, `SERVICE_ARGS`, `ENTRY`, `DIST_FILE`, `HEALTH_URL`, `KEEP`, `AUTO_UPDATE`, `VERBS`. The package's `files` must include both copies (and a `package` app's built output). `colab template npx-service.mjs --dest <path>`, `--dest` required. |
26
27
  | `deploy-xserver.yml` | `.github/workflows/deploy-xserver.yml` | PHP-framework + Vite apps shipped to **shared hosting over SSH** (no root, no Docker): build on a runner, rsync, migrate on the server | Derived from three independently-written copies. Resolves Node the same way the CI templates do — all three hardcoded it, and one shipped on a different major than its CI built on. Migrates **production**; keeps a **mandatory** smoke test. Does **not** change your tier. |
28
+ | `deploy-container.yml` | `.github/workflows/deploy-container.yml` | A **container** app on a host whose platform has an API (Portainer today), `deploy: tag` ([CONVENTIONS §6, *A container deploy*](../CONVENTIONS.md#6-releases), #452) | One contract on every host: build each listed image **once** per final tag (`vX.Y.Z` + commit sha), run the pre-deploy hook, have the platform run exactly that tag (all images, one call), green only on a **verified running version** (stack settled, commit and container images checked, then `release.health-url` reporting `X.Y.Z`), roll back to the previous final on a failure after the platform accepted. **Two jobs (#460):** `publish` builds and pushes on **every** final, ungated — so a repo not yet cut over still gets each final's image in the registry; `deploy` `needs:` it, never builds (a missing image fails before the platform is touched), and is the one job you gate on "is the platform switched on". Images and build args sit in the workflow-level `env`, written once for both jobs. Triggers: a final tag push (route `deploy-tag`), `workflow_dispatch` with a tag (a manual deploy or rollback), and `workflow_call` — route `deploy-tag-fast` reaches it from `release-auto.yml`'s commented `deploy` job, like `dist-refs.yml` from its release run. Needs its two scripts below. One required secret: `PORTAINER_API_KEY`, a non-admin key owning only this app's stack; optional `HEALTH_AUTH_HEADER` (`Name: value`) or `HEALTH_BASIC_AUTH` (`user:password`) when the version URL sits behind auth — masked, never printed. **Every redeploy recreates the containers.** Does **not** change your exposure. |
29
+ | `deploy-container-run.mjs` | `.github/deploy/deploy-container-run.mjs` | Pairs with `deploy-container.yml` | The driver: builds, runs the hook, calls the adapter, verifies, rolls back, records. `--publish-only` = build and push only (no platform config, no version URL needed); `--deploy-only` = everything after, refusing a tag whose image is not in the registry. **Build args:** `DEPLOY_BUILD_ARGS`, one per line — `KEY=VALUE` for every image or `<image-ref> KEY=VALUE` for one; `${TAG}` (`vX.Y.Z`), `${VERSION}` (`X.Y.Z`) and `${SHA}` are filled in by the driver, so a static site can bake public config and its version into a served file. They end up in the image — public values only, never a secret. Node ≥ 18, zero dependencies; shells out to `git`, `docker`, `gh`. `colab template deploy-container-run.mjs --dest <path>`, `--dest` required, stamped on line 2. |
30
+ | `deploy-adapter-portainer.mjs` | `.github/deploy/deploy-adapter-portainer.mjs` — **beside** the driver, which loads `./deploy-adapter-<DEPLOY_ADAPTER>.mjs` | Pairs with `deploy-container.yml` | The Portainer adapter: git stacks redeploy `refs/tags/vX.Y.Z`, file stacks update with the compose file; the stack's **whole** `Env` is sent back with `IMAGE_TAG` replaced; 409 waited out and retried, any other error a hard failure (nothing changed). Another platform = another file exporting the same five names (`name`, `configFromEnv`, `snapshot`, `deploy`, `restore`). |
27
31
  | `repo-CLAUDE-block.md` | *paste into* `CLAUDE.md` | Every adopting repo | The discovery hook — how an agent finds the handbook at all. |
28
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. |
29
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. |
30
- | `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 `.claude/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. |
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. |
31
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. |
32
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. |
33
37
 
@@ -50,6 +54,27 @@ Two things to keep in a copy:
50
54
  `migrations` job checks `needs.build.result == 'success'` explicitly. Add the same pair of
51
55
  conditions to any job you add.
52
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
+
53
78
  ### Migration round-trip — what the Laravel job proves, and what it cannot
54
79
 
55
80
  `ci-laravel.yml`'s `migrations` job runs every migration **twice per engine**: once from
@@ -116,6 +141,9 @@ directory into ~45 repos and was wrong — fixed 2026-08-20.
116
141
  colab template ci-node --dest .github/workflows/ci.yml
117
142
  colab template release-tag --dest .github/workflows/release.yml
118
143
  colab template deploy-xserver --dest .github/workflows/deploy-xserver.yml
144
+ colab template deploy-container --dest .github/workflows/deploy-container.yml
145
+ colab template deploy-container-run.mjs --dest .github/deploy/deploy-container-run.mjs
146
+ colab template deploy-adapter-portainer.mjs --dest .github/deploy/deploy-adapter-portainer.mjs
119
147
  colab template docs-lint.mjs --dest tools/docs-lint.mjs # --dest is required for this one
120
148
  ```
121
149