@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
@@ -14,62 +14,15 @@
14
14
  const claimIdentity = require('./claim-identity');
15
15
  const machine = require('./machine');
16
16
 
17
- const CLAIM_MARK = '๐Ÿ”’ Claimed';
18
- const RELEASE_MARK = 'โœ… Released';
17
+ // The wire format itself โ€” markers, regexes, the session/identity fields and the claim/release
18
+ // encode/decode pairs โ€” lives in codec/claim.js (#497). Re-exported below under the names this
19
+ // module always had, so no caller breaks.
20
+ const codec = require('./codec/claim');
21
+ const { CLAIM_MARK, RELEASE_MARK, CLAIM_RE, SESSION_RE, MACHINE_RE, YIELD_RE, parseSessionField, parseIdentity } = codec;
19
22
  // #378: how far BEFORE our own claim a rival's live claim can be and still count as "simultaneous".
20
23
  // Racers post within seconds of each other; 10 minutes is deliberately generous so a slow `gh` never
21
24
  // splits a real race, while a claim weeks old โ€” abandoned, or released only in prose โ€” is not a race.
22
25
  const RACE_WINDOW_MS = 10 * 60 * 1000;
23
- // Parses a claim comment body back into {worktree, branch, host, date}. The `ยท <host>` field is
24
- // what lets the tie-break tell two machines of the SAME GitHub user apart. On a public destination
25
- // it carries an opaque `h:` token instead of the raw name (#369, machine.js `hostToken`) โ€” same
26
- // field, same position, so this regex and every older parser read both shapes. The optional
27
- // trailing `ยท session <value>` (added 2026-07) is captured separately by SESSION_RE so this regex
28
- // stays byte-stable for session-less comments.
29
- const CLAIM_RE = /๐Ÿ”’ Claimed โ€” worktree `([^`]*)` ยท branch `([^`]*)` ยท host `([^`]*)` ยท (\S+)/;
30
- // The `ยท session <field>` tail, captured as the rest of the line. parseSessionField() then decodes
31
- // the THREE shapes it can take โ€” `[name](url)`, a bare URL, or a bare name โ€” plus the legacy
32
- // plain-URL form written before sessionName existed.
33
- const SESSION_RE = /ยท session (.+)$/;
34
- // #327: the claimant's machine, as the public `m:` digest (tools/lib/machine.js `machineToken`),
35
- // written AFTER the timestamp and BEFORE the session suffix โ€” so CLAIM_RE's four groups and
36
- // SESSION_RE's end anchor both parse a new comment exactly as they parse a legacy one, and a legacy
37
- // comment (no such field) simply has no machine and is compared by host.
38
- const MACHINE_RE = /ยท machine `(m:[0-9a-f]{12})`/;
39
- // A yield: the loser of a race releases, naming the winner by its identity string
40
- // (`claimIdentity.identityString` โ€” `login@host`, or `login@host#session` under the fine setting).
41
- const YIELD_RE = /^โœ… Released \(yielded โ€” earlier claim by (.+?) wins\)/;
42
-
43
- /**
44
- * Decode the `ยท session <field>` tail of a claim comment into { sessionName, session }. Accepts:
45
- * `[name](url)` โ†’ both; bare `https://โ€ฆ`/`session_โ€ฆ` โ†’ url only; any other bare token โ†’ name.
46
- * The bare-URL branch is exactly the LEGACY format written before sessionName existed, so old
47
- * comments keep parsing. Returns empty strings when there is no session tail.
48
- */
49
- function parseSessionField(body) {
50
- const m = String(body).match(SESSION_RE);
51
- if (!m) return { sessionName: '', session: '' };
52
- const v = m[1].trim();
53
- const link = v.match(/^\[([^\]]*)\]\((.*)\)$/);
54
- if (link) return { sessionName: link[1], session: link[2] };
55
- // #306: the shape test lives in claimIdentity.looksLikeSessionId โ€” one copy of the rule.
56
- if (claimIdentity.looksLikeSessionId(v)) return { sessionName: '', session: v };
57
- return { sessionName: v, session: '' };
58
- }
59
-
60
- /** `login@host[#session]` โ†’ its parts. Logins cannot contain `@`, hosts cannot contain `#`. */
61
- function parseIdentity(s) {
62
- const str = String(s || '').trim();
63
- const at = str.indexOf('@');
64
- if (at <= 0) return null;
65
- const rest = str.slice(at + 1);
66
- const hash = rest.indexOf('#');
67
- return {
68
- login: str.slice(0, at),
69
- host: hash === -1 ? rest : rest.slice(0, hash),
70
- session: hash === -1 ? '' : rest.slice(hash + 1),
71
- };
72
- }
73
26
 
74
27
  /**
75
28
  * Is claim `c` the one a yield NAMED as its winner? Login exact, host by `sameHostName` (so a
@@ -91,11 +44,10 @@ function isNamedWinner(c, named) {
91
44
  function releaseComments(sorted) {
92
45
  const out = [];
93
46
  for (const c of sorted) {
94
- const body = String(c.body || '').trim();
95
- if (!body.startsWith(RELEASE_MARK)) continue;
47
+ const rel = codec.decodeRelease(c.body || '');
48
+ if (!rel) continue;
96
49
  const login = (c.author && c.author.login) || '';
97
- const y = body.match(YIELD_RE);
98
- if (y) out.push({ kind: 'yield', login, at: c.createdAt, winner: parseIdentity(y[1]) });
50
+ if (rel.kind === 'yield') out.push({ kind: 'yield', login, at: c.createdAt, winner: parseIdentity(rel.winner) });
99
51
  else out.push({ kind: 'release', login, at: c.createdAt });
100
52
  }
101
53
  return out;
@@ -133,14 +85,11 @@ function liveClaimComments(comments, comps) {
133
85
  const releases = releaseComments(sorted);
134
86
  const live = [];
135
87
  for (const c of sorted) {
136
- const body = String(c.body || '').trim();
137
- const m = body.match(CLAIM_RE);
138
- if (!m) continue;
88
+ const claim = codec.decodeClaim(c.body || ''); // [name](url) / url / name / legacy, machine or not
89
+ if (!claim) continue;
139
90
  const login = (c.author && c.author.login) || '';
140
- const host = m[3];
141
- const { session, sessionName } = parseSessionField(body); // handles [name](url) / url / name / legacy
142
- const mm = body.match(MACHINE_RE); // #327 โ€” absent on a legacy comment: compared by host
143
- const machineTok = mm ? mm[1] : '';
91
+ const { host, session, sessionName } = claim;
92
+ const machineTok = claim.machine; // #327 โ€” '' on a legacy comment: compared by host
144
93
  const at = c.createdAt;
145
94
  const entry = { login, host, machine: machineTok, session, sessionName, at };
146
95
  const cancelled = releases.some((r) => r.at > at && (r.kind === 'release'
@@ -203,7 +152,7 @@ function yieldReleaseBody(winner, { redact = false } = {}) {
203
152
  const tail = id.startsWith(head) ? id.slice(head.length) : '';
204
153
  id = `${winner.login}@${machine.hostToken(winner.host)}${tail}`;
205
154
  }
206
- return `${RELEASE_MARK} (yielded โ€” earlier claim by ${id} wins)`;
155
+ return codec.encodeRelease({ winner: id });
207
156
  }
208
157
 
209
158
  module.exports = {
@@ -168,8 +168,9 @@ function mergeClaimRecord(existing, incoming, { sameHolder } = {}) {
168
168
 
169
169
  /**
170
170
  * Does `v` look like a session ID a consumer could actually JOIN on โ€” a URL, or a `session_โ€ฆ`
171
- * token embedded in one (#306)? The repo's ONE answer to that question: `parseSessionField`
172
- * (tools/colab) decodes a claim comment's `ยท session <field>` tail with exactly this test, and
171
+ * token embedded in one (#306)? The repo's ONE answer to that question โ€” defined in codec/claim.js
172
+ * since #497 and re-exported here: `parseSessionField` (codec/claim.js) decodes a claim comment's
173
+ * `ยท session <field>` tail with exactly this test, and
173
174
  * `warnWeakIdentity` warns with it. Two copies of a shape rule drift, and this one decides
174
175
  * whether a hold can ever be released by its own owner, so there is one.
175
176
  *
@@ -182,11 +183,7 @@ function mergeClaimRecord(existing, incoming, { sameHolder } = {}) {
182
183
  * False for '' / null: absence is `warnWeakIdentity`'s and `requirePlaceIdentity`'s subject
183
184
  * (#11/#242), never this predicate's โ€” callers test blankness first.
184
185
  */
185
- function looksLikeSessionId(v) {
186
- const s = String(v == null ? '' : v).trim();
187
- if (!s) return false;
188
- return /^https?:\/\//.test(s) || /session_[\w-]+/.test(s);
189
- }
186
+ const { looksLikeSessionId } = require('./codec/claim'); // one copy of the rule, in the codec (#497)
190
187
 
191
188
  module.exports = {
192
189
  DEFAULT_COMPONENTS, FINE_COMPONENTS,
@@ -0,0 +1,41 @@
1
+ // Types for tools/lib/codec/claim.js (#497) โ€” see index.d.ts.
2
+
3
+ // โ”€โ”€ claim / release comments โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
4
+
5
+ export const CLAIM_MARK: '๐Ÿ”’ Claimed';
6
+ export const RELEASE_MARK: 'โœ… Released';
7
+ export const CLAIM_RE: RegExp;
8
+ export const SESSION_RE: RegExp;
9
+ export const MACHINE_RE: RegExp;
10
+ export const YIELD_RE: RegExp;
11
+
12
+ export function looksLikeSessionId(v: unknown): boolean;
13
+
14
+ export interface SessionField { session: string; sessionName: string; }
15
+ export function encodeSessionField(session?: string, sessionName?: string): string;
16
+ export function parseSessionField(body: string): SessionField;
17
+
18
+ export interface Identity { login: string; host: string; session: string; }
19
+ export function encodeIdentity(id?: { login: string; host: string; session?: string }): string;
20
+ export function parseIdentity(s: string | null | undefined): Identity | null;
21
+
22
+ export interface DecodedClaim extends SessionField {
23
+ /** `-` when the claim names no worktree โ€” kept literally so the pair round-trips. */
24
+ worktree: string;
25
+ /** `-` when the claim names no branch (#53). */
26
+ branch: string;
27
+ /** Raw hostname, or its `h:` token on a destination that may not name it (#369). */
28
+ host: string;
29
+ /** ISO timestamp as written. */
30
+ at: string;
31
+ /** `m:` digest (#327), or '' on a legacy comment. */
32
+ machine: string;
33
+ }
34
+ export function encodeClaim(claim?: Partial<DecodedClaim>): string;
35
+ export function decodeClaim(body: string | null | undefined): DecodedClaim | null;
36
+
37
+ export type DecodedRelease =
38
+ | { kind: 'release'; rest: string }
39
+ | { kind: 'yield'; winner: string; rest: string };
40
+ export function encodeRelease(release?: { winner?: string; rest?: string }): string;
41
+ export function decodeRelease(body: string | null | undefined): DecodedRelease | null;
@@ -0,0 +1,151 @@
1
+ 'use strict';
2
+ /**
3
+ * CODEC (#497, epic #496): the claim/release comment WIRE FORMAT as encode/decode pairs. Pure and
4
+ * synchronous โ€” no I/O, no clock, no requires โ€” so it can be shared as code with any consumer that
5
+ * reads or writes the same comments. The readers built on it (which claims still stand, who wins a
6
+ * race) stay in tools/lib/claim-comments.js; the writers that need the clock, the machine id and the
7
+ * tracker stay in tools/colab and call `encodeClaim` / `encodeRelease` here.
8
+ *
9
+ * These strings are a STABLE WIRE FORMAT: the refusal path, the tie-break, and dashboards grep
10
+ * them, and an older colab on another machine parses what this one writes. `codec/samples.json`
11
+ * holds real, scrubbed comments; the test requires every one to survive encode(decode(s)) byte for
12
+ * byte. Change a byte here and that test is what tells you an older reader just broke.
13
+ */
14
+
15
+ const CLAIM_MARK = '๐Ÿ”’ Claimed';
16
+ const RELEASE_MARK = 'โœ… Released';
17
+ // Parses a claim comment body back into {worktree, branch, host, at}. The `ยท <host>` field is
18
+ // what lets the tie-break tell two machines of the SAME GitHub user apart. On a public destination
19
+ // it carries an opaque `h:` token instead of the raw name (#369, machine.js `hostToken`) โ€” same
20
+ // field, same position, so this regex and every older parser read both shapes. The optional
21
+ // trailing `ยท session <value>` (added 2026-07) is captured separately by SESSION_RE so this regex
22
+ // stays byte-stable for session-less comments.
23
+ const CLAIM_RE = /๐Ÿ”’ Claimed โ€” worktree `([^`]*)` ยท branch `([^`]*)` ยท host `([^`]*)` ยท (\S+)/;
24
+ // The `ยท session <field>` tail, captured as the rest of the line. parseSessionField() then decodes
25
+ // the THREE shapes it can take โ€” `[name](url)`, a bare URL, or a bare name โ€” plus the legacy
26
+ // plain-URL form written before sessionName existed.
27
+ const SESSION_RE = /ยท session (.+)$/;
28
+ // #327: the claimant's machine, as the public `m:` digest (tools/lib/machine.js `machineToken`),
29
+ // written AFTER the timestamp and BEFORE the session suffix โ€” so CLAIM_RE's four groups and
30
+ // SESSION_RE's end anchor both parse a new comment exactly as they parse a legacy one, and a legacy
31
+ // comment (no such field) simply has no machine and is compared by host.
32
+ const MACHINE_RE = /ยท machine `(m:[0-9a-f]{12})`/;
33
+ // A yield: the loser of a race releases, naming the winner by its identity string
34
+ // (`claimIdentity.identityString` โ€” `login@host`, or `login@host#session` under the fine setting).
35
+ const YIELD_RE = /^โœ… Released \(yielded โ€” earlier claim by (.+?) wins\)/;
36
+
37
+ /**
38
+ * Does `v` look like a session URL / `session_โ€ฆ` id rather than a display name? A SHAPE heuristic
39
+ * (#306), not a gate โ€” claim-identity.js re-exports this one copy of it.
40
+ */
41
+ function looksLikeSessionId(v) {
42
+ const s = String(v == null ? '' : v).trim();
43
+ if (!s) return false;
44
+ return /^https?:\/\//.test(s) || /session_[\w-]+/.test(s);
45
+ }
46
+
47
+ /**
48
+ * Encode the `ยท session <field>` tail of a claim comment. Both โ†’ a markdown link; url only โ†’ the
49
+ * legacy bare form; name only โ†’ the bare name; neither โ†’ nothing.
50
+ */
51
+ function encodeSessionField(session, sessionName) {
52
+ if (sessionName && session) return ` ยท session [${sessionName}](${session})`;
53
+ if (session) return ` ยท session ${session}`;
54
+ if (sessionName) return ` ยท session ${sessionName}`;
55
+ return '';
56
+ }
57
+
58
+ /**
59
+ * Decode the `ยท session <field>` tail of a claim comment into { sessionName, session }. Accepts:
60
+ * `[name](url)` โ†’ both; bare `https://โ€ฆ`/`session_โ€ฆ` โ†’ url only; any other bare token โ†’ name.
61
+ * The bare-URL branch is exactly the LEGACY format written before sessionName existed, so old
62
+ * comments keep parsing. Returns empty strings when there is no session tail.
63
+ */
64
+ function parseSessionField(body) {
65
+ const m = String(body).match(SESSION_RE);
66
+ if (!m) return { sessionName: '', session: '' };
67
+ const v = m[1].trim();
68
+ const link = v.match(/^\[([^\]]*)\]\((.*)\)$/);
69
+ if (link) return { sessionName: link[1], session: link[2] };
70
+ if (looksLikeSessionId(v)) return { sessionName: '', session: v };
71
+ return { sessionName: v, session: '' };
72
+ }
73
+
74
+ /** `{login, host, session}` โ†’ `login@host[#session]` โ€” the identity string a yield names. */
75
+ function encodeIdentity({ login, host, session } = {}) {
76
+ return `${login}@${host}${session ? `#${session}` : ''}`;
77
+ }
78
+
79
+ /** `login@host[#session]` โ†’ its parts. Logins cannot contain `@`, hosts cannot contain `#`. */
80
+ function parseIdentity(s) {
81
+ const str = String(s || '').trim();
82
+ const at = str.indexOf('@');
83
+ if (at <= 0) return null;
84
+ const rest = str.slice(at + 1);
85
+ const hash = rest.indexOf('#');
86
+ return {
87
+ login: str.slice(0, at),
88
+ host: hash === -1 ? rest : rest.slice(0, hash),
89
+ session: hash === -1 ? '' : rest.slice(hash + 1),
90
+ };
91
+ }
92
+
93
+ /**
94
+ * The exact claim-comment body. Every field is written as given: `worktree`/`branch` default to `-`
95
+ * ("none" โ€” it used to be the word `trunk`, which read as a branch that never existed, #53); `at`
96
+ * is the caller's ISO timestamp (the codec holds no clock); `machine` is the `m:` digest or empty
97
+ * (#327, the field is then omitted); `host` is the raw hostname or its `h:` token, whichever the
98
+ * destination allows (#369 โ€” deciding that is the caller's job, not the codec's).
99
+ */
100
+ function encodeClaim({ worktree, branch, host, at, machine, session, sessionName } = {}) {
101
+ const base = `${CLAIM_MARK} โ€” worktree \`${worktree || '-'}\` ยท branch \`${branch || '-'}\` ยท host \`${host}\` ยท ${at}`;
102
+ const mach = machine ? ` ยท machine \`${machine}\`` : '';
103
+ return base + mach + encodeSessionField(session, sessionName);
104
+ }
105
+
106
+ /**
107
+ * A claim comment body โ†’ { worktree, branch, host, at, machine, session, sessionName }, or null when
108
+ * the body carries no claim. Lenient exactly where the readers always were (CLAIM_RE is unanchored,
109
+ * a legacy comment simply lacks machine/session), and lossless on what `encodeClaim` writes:
110
+ * `worktree`/`branch` keep a literal `-` rather than mapping it to empty, so the pair round-trips.
111
+ */
112
+ function decodeClaim(body) {
113
+ const str = String(body == null ? '' : body).trim();
114
+ const m = str.match(CLAIM_RE);
115
+ if (!m) return null;
116
+ const mm = str.match(MACHINE_RE);
117
+ const { session, sessionName } = parseSessionField(str);
118
+ return { worktree: m[1], branch: m[2], host: m[3], at: m[4], machine: mm ? mm[1] : '', session, sessionName };
119
+ }
120
+
121
+ /**
122
+ * A release comment body. `{}` โ†’ the plain marker (`colab release`, `worktree rm`); `{ winner }` โ†’
123
+ * a yield naming the winner's identity string. `rest` is any text after the marker (or after the
124
+ * yield's closing parenthesis) โ€” a hand-written release keeps its prose through a round trip.
125
+ */
126
+ function encodeRelease({ winner, rest } = {}) {
127
+ const tail = rest || '';
128
+ if (winner) return `${RELEASE_MARK} (yielded โ€” earlier claim by ${winner} wins)${tail}`;
129
+ return RELEASE_MARK + tail;
130
+ }
131
+
132
+ /**
133
+ * A release comment body โ†’ { kind: 'yield', winner, rest } | { kind: 'release', rest }, or null when
134
+ * the body is not a release. `winner` is the raw identity string (`parseIdentity` splits it).
135
+ */
136
+ function decodeRelease(body) {
137
+ const str = String(body == null ? '' : body).trim();
138
+ if (!str.startsWith(RELEASE_MARK)) return null;
139
+ const y = str.match(YIELD_RE);
140
+ if (y) return { kind: 'yield', winner: y[1], rest: str.slice(y[0].length) };
141
+ return { kind: 'release', rest: str.slice(RELEASE_MARK.length) };
142
+ }
143
+
144
+ module.exports = {
145
+ CLAIM_MARK, RELEASE_MARK, CLAIM_RE, SESSION_RE, MACHINE_RE, YIELD_RE,
146
+ looksLikeSessionId,
147
+ encodeSessionField, parseSessionField,
148
+ encodeIdentity, parseIdentity,
149
+ encodeClaim, decodeClaim,
150
+ encodeRelease, decodeRelease,
151
+ };
@@ -0,0 +1,29 @@
1
+ // Types for tools/lib/codec/decision.js (#498) โ€” see index.d.ts.
2
+
3
+ export const DECISION_MARK: 'โš– Decision recorded';
4
+ export const REOPEN_MARK: 'โ†ฉ Decision reopened';
5
+ export const DECISION_RE: RegExp;
6
+ export const REOPEN_RE: RegExp;
7
+
8
+ export interface DecodedDecision {
9
+ /** The human whose call it is โ€” never the typist. */
10
+ ruledBy: string;
11
+ /** The options block this answers, or `-`. */
12
+ answers: string;
13
+ host: string; at: string;
14
+ /** Rest of the marker line; null = canonical (nothing). */
15
+ tail: string | null;
16
+ /** The ruling prose after one blank line, or null. */
17
+ body: string | null;
18
+ }
19
+ export function encodeDecision(d?: Partial<DecodedDecision>): string;
20
+ export function decodeDecision(text: string | null | undefined): DecodedDecision | null;
21
+
22
+ export interface DecodedReopen { ruledBy: string; host: string; at: string; tail: string | null; body: string | null; }
23
+ export function encodeReopen(r?: Partial<DecodedReopen>): string;
24
+ export function decodeReopen(text: string | null | undefined): DecodedReopen | null;
25
+
26
+ export const OPTIONS_RE: RegExp;
27
+ export const MOCKUP_RE: RegExp;
28
+ export function encodeMockup(url: string): string;
29
+ export function mockupUrls(body: unknown): string[];
@@ -0,0 +1,81 @@
1
+ 'use strict';
2
+ /**
3
+ * CODEC (#498, epic #496): the DECISION wire formats as encode/decode pairs โ€” the `โš– Decision
4
+ * recorded` record and its `โ†ฉ Decision reopened` counterpart, plus the two question-side markers a
5
+ * reader looks for on a `needs-decision` issue (the `<!-- decision:options` block and the `Mockup:`
6
+ * body line). Pure and synchronous: no I/O, no clock, no requires.
7
+ *
8
+ * Which decisions are live, whose are trusted, and whether a label pair is an open question or an
9
+ * interrupted write stay in tools/lib/decision-record.js, which re-exports these under its old names.
10
+ *
11
+ * STABLE WIRE FORMAT. The two marks lead with DIFFERENT glyphs, so a reopen can never parse as a
12
+ * fresh decision. Round trip: a decoded record carries `tail` (rest of the marker line; null = the
13
+ * canonical text) and `body` (the prose after one blank line; null = none), so any comment the
14
+ * regex matches re-encodes byte for byte.
15
+ */
16
+
17
+ const DECISION_MARK = 'โš– Decision recorded';
18
+ const REOPEN_MARK = 'โ†ฉ Decision reopened';
19
+ const DECISION_RE = /^โš– Decision recorded โ€” ruled-by `([^`]*)` ยท answers `([^`]*)` ยท host `([^`]*)` ยท (\S+)/;
20
+ const REOPEN_RE = /^โ†ฉ Decision reopened โ€” ruled-by `([^`]*)` ยท host `([^`]*)` ยท (\S+)/;
21
+ const DECISION_TAIL = '';
22
+ const REOPEN_TAIL = ' โ€” every decision on this issue up to this point is superseded.';
23
+
24
+ /** The question-side options block (CONVENTIONS.md ยง5, *Decision options*, #126) โ€” presence only. */
25
+ const OPTIONS_RE = /<!--\s*decision:options\b/;
26
+ /** The design-approval ask (#379): `Mockup: <url>` at the START of a body line, nothing after it. */
27
+ const MOCKUP_RE = /^Mockup:[ \t]*(\S+)[ \t]*$/gm;
28
+
29
+ // Split what follows the timestamp into the marker line's tail and the body after a blank line.
30
+ // Anything that is not "<line>\n\n<body>" stays whole in the tail, so nothing is ever dropped.
31
+ function splitRest(rest, canonical) {
32
+ const m = /^([^\n]*)\n\n([\s\S]*)$/.exec(rest);
33
+ const tail = m ? m[1] : rest;
34
+ return { tail: tail === canonical ? null : tail, body: m ? m[2] : null };
35
+ }
36
+ function joinRest(tail, body, canonical) {
37
+ return (tail == null ? canonical : tail) + (body != null && body !== '' ? `\n\n${body}` : '');
38
+ }
39
+
40
+ /**
41
+ * `{ruledBy, answers, host, at, tail?, body?}` โ†’ the decision comment. `ruledBy` names the human
42
+ * whose call it is, never the typist; `answers` is the options block this resolves, or `-`.
43
+ */
44
+ function encodeDecision({ ruledBy, answers, host, at, tail, body } = {}) {
45
+ return `${DECISION_MARK} โ€” ruled-by \`${ruledBy}\` ยท answers \`${answers || '-'}\` ยท host \`${host}\` ยท ${at}`
46
+ + joinRest(tail, body, DECISION_TAIL);
47
+ }
48
+ /** A decision comment โ†’ `{ruledBy, answers, host, at, tail, body}`, or null. */
49
+ function decodeDecision(text) {
50
+ const s = String(text == null ? '' : text).trim();
51
+ const m = s.match(DECISION_RE);
52
+ if (!m) return null;
53
+ return { ruledBy: m[1], answers: m[2], host: m[3], at: m[4], ...splitRest(s.slice(m[0].length), DECISION_TAIL) };
54
+ }
55
+
56
+ /** `{ruledBy, host, at, tail?, body?}` โ†’ the reopen comment; `body` is the reason, if any. */
57
+ function encodeReopen({ ruledBy, host, at, tail, body } = {}) {
58
+ return `${REOPEN_MARK} โ€” ruled-by \`${ruledBy}\` ยท host \`${host}\` ยท ${at}` + joinRest(tail, body, REOPEN_TAIL);
59
+ }
60
+ function decodeReopen(text) {
61
+ const s = String(text == null ? '' : text).trim();
62
+ const m = s.match(REOPEN_RE);
63
+ if (!m) return null;
64
+ return { ruledBy: m[1], host: m[2], at: m[3], ...splitRest(s.slice(m[0].length), REOPEN_TAIL) };
65
+ }
66
+
67
+ /** `url` โ†’ the `Mockup:` body line. */
68
+ function encodeMockup(url) { return `Mockup: ${url}`; }
69
+ /** Every `Mockup:` URL declared in an issue body, in order. Empty when none (or no body). */
70
+ function mockupUrls(body) {
71
+ if (typeof body !== 'string' || body === '') return [];
72
+ const out = [];
73
+ for (const m of body.replace(/\r\n/g, '\n').matchAll(MOCKUP_RE)) out.push(m[1]);
74
+ return out;
75
+ }
76
+
77
+ module.exports = {
78
+ DECISION_MARK, REOPEN_MARK, DECISION_RE, REOPEN_RE,
79
+ encodeDecision, decodeDecision, encodeReopen, decodeReopen,
80
+ OPTIONS_RE, MOCKUP_RE, encodeMockup, mockupUrls,
81
+ };
@@ -0,0 +1,82 @@
1
+ // Types for tools/lib/codec/grants.js (#498) โ€” see index.d.ts.
2
+ // `tail` on every decoded grant: null = the canonical sentence this toolkit writes; any other string
3
+ // is kept literally so a hand-edited comment re-encodes byte for byte.
4
+
5
+ // โ”€โ”€ human migration grant / revoke โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
6
+
7
+ export const MIGRATION_GRANT_MARK: '๐Ÿ›ข Migration grant';
8
+ export const MIGRATION_REVOKE_MARK: '๐Ÿšซ Migration grant revoked';
9
+ export const MIGRATION_GRANT_RE: RegExp;
10
+ export const MIGRATION_REVOKE_RE: RegExp;
11
+
12
+ export interface DecodedMigrationGrant { branch: string; host: string; at: string; tail: string | null; }
13
+ export function encodeMigrationGrant(g?: { branch: string; host: string; at: string; tail?: string | null }): string;
14
+ export function decodeMigrationGrant(body: string | null | undefined): DecodedMigrationGrant | null;
15
+ export function encodeMigrationRevoke(r?: { branch: string; host: string; at: string; tail?: string | null }): string;
16
+ export function decodeMigrationRevoke(body: string | null | undefined): DecodedMigrationGrant | null;
17
+
18
+ // โ”€โ”€ reviewer migration grant โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
19
+
20
+ export const REVIEW_GRANT_MARK: '๐Ÿ”Ž Migration review grant';
21
+ export const REVIEW_GRANT_RE: RegExp;
22
+ export const REVIEWER_ROLE: 'migration-reviewer';
23
+ export const REVIEW_RECORD_FENCE: 'migration-review';
24
+ export const REVIEW_RECORD_VERSION: '1';
25
+ export interface ReviewRecordField { key: string; required: boolean; values?: string[]; re?: RegExp; hint?: string; }
26
+ export const REVIEW_RECORD_FIELDS: ReadonlyArray<ReviewRecordField>;
27
+ /** Canonical tail of a HEAD-bound reviewer grant (a record with no `migrations` content id). */
28
+ export const REVIEW_GRANT_TAIL: string;
29
+ /** Canonical tail of a content-bound reviewer grant (#508 โ€” the record names `migrations`). */
30
+ export const REVIEW_GRANT_CONTENT_TAIL: string;
31
+
32
+ export interface DecodedReviewGrant {
33
+ role: string; reviewer: string; branch: string;
34
+ /** Full 40-hex sha the review covers, as written (validity is the caller's check). */
35
+ head: string;
36
+ host: string; at: string; tail: string | null;
37
+ /** The fenced record's `key: value` lines, or null when the comment has no record block. */
38
+ record: Record<string, string> | null;
39
+ /** SYNTAX findings only โ€” never whether the review passes. */
40
+ problems: string[];
41
+ }
42
+ export function encodeReviewGrant(g?: Partial<Omit<DecodedReviewGrant, 'problems' | 'record'>> & { record?: Record<string, unknown> }): string;
43
+ export function decodeReviewGrant(body: string | null | undefined): DecodedReviewGrant | null;
44
+
45
+ // โ”€โ”€ red-trunk CI grant / revoke โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
46
+
47
+ export const CI_GRANT_MARK: '๐Ÿšจ Red-trunk CI grant';
48
+ export const CI_REVOKE_MARK: '๐Ÿงฏ Red-trunk CI grant revoked';
49
+ export const CI_GRANT_RE: RegExp;
50
+ export const CI_REVOKE_RE: RegExp;
51
+
52
+ export interface DecodedCiGrant {
53
+ branch: string; trunk: string; redSha: string; evidenceSha: string; host: string; at: string; tail: string | null;
54
+ }
55
+ export function encodeCiGrant(g?: Omit<DecodedCiGrant, 'tail'> & { tail?: string | null }): string;
56
+ export function decodeCiGrant(body: string | null | undefined): DecodedCiGrant | null;
57
+ export function encodeCiRevoke(r?: { branch: string; host: string; at: string; tail?: string | null }): string;
58
+ export function decodeCiRevoke(body: string | null | undefined): DecodedMigrationGrant | null;
59
+
60
+ // โ”€โ”€ reviewer red-trunk CI grant (#504) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
61
+
62
+ export const CI_REVIEW_GRANT_MARK: '๐Ÿฉน Red-trunk CI review grant';
63
+ export const CI_REVIEW_GRANT_RE: RegExp;
64
+ export const CI_REVIEWER_ROLE: 'ci-reviewer';
65
+ export const CI_REVIEW_RECORD_FENCE: 'ci-review';
66
+ export const CI_REVIEW_RECORD_VERSION: '1';
67
+ export const CI_CURES_SEPARATOR: ';';
68
+ export const CI_REVIEW_RECORD_FIELDS: ReadonlyArray<ReviewRecordField>;
69
+
70
+ export interface DecodedCiReviewGrant {
71
+ role: string; reviewer: string; branch: string;
72
+ /** Full 40-hex sha the review covers, as written. */
73
+ head: string;
74
+ /** Trunk name and the full red trunk sha the review was made against. */
75
+ trunk: string; redSha: string;
76
+ host: string; at: string; tail: string | null;
77
+ record: Record<string, string> | null;
78
+ /** SYNTAX findings only โ€” never whether the review passes. */
79
+ problems: string[];
80
+ }
81
+ export function encodeCiReviewGrant(g?: Partial<Omit<DecodedCiReviewGrant, 'problems' | 'record'>> & { record?: Record<string, unknown> }): string;
82
+ export function decodeCiReviewGrant(body: string | null | undefined): DecodedCiReviewGrant | null;