@futurelastic/colab-handbook 1.12.0 โ 1.13.0-rc.10
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/README.md +248 -213
- package/README.vi.md +252 -186
- package/audit/audit.mjs +193 -10
- package/package.json +7 -1
- package/templates/README.md +30 -2
- package/templates/ci-laravel.yml +102 -21
- package/templates/ci-node.yml +61 -3
- package/templates/ci-python.yml +52 -3
- package/templates/deploy-adapter-portainer.mjs +206 -0
- package/templates/deploy-container-run.mjs +368 -0
- package/templates/deploy-container.yml +219 -0
- package/templates/dist-refs.yml +6 -0
- package/templates/docs-lint.mjs +1 -1
- package/templates/npx-launcher.mjs +118 -20
- package/templates/npx-service.mjs +828 -0
- package/templates/release-auto.yml +341 -32
- package/tools/colab +1902 -278
- package/tools/lib/adopt.js +373 -14
- package/tools/lib/branch-name.js +29 -1
- package/tools/lib/ci-cure.js +522 -31
- package/tools/lib/ci-grant.js +289 -22
- package/tools/lib/ci-wait.js +223 -0
- package/tools/lib/claim-comments.js +13 -64
- package/tools/lib/claim-identity.js +42 -7
- package/tools/lib/codec/claim.d.ts +41 -0
- package/tools/lib/codec/claim.js +153 -0
- package/tools/lib/codec/decision.d.ts +29 -0
- package/tools/lib/codec/decision.js +81 -0
- package/tools/lib/codec/grants.d.ts +82 -0
- package/tools/lib/codec/grants.js +268 -0
- package/tools/lib/codec/hold.d.ts +26 -0
- package/tools/lib/codec/hold.js +152 -0
- package/tools/lib/codec/index.d.ts +21 -0
- package/tools/lib/codec/index.js +32 -0
- package/tools/lib/codec/labels.d.ts +65 -0
- package/tools/lib/codec/labels.js +723 -0
- package/tools/lib/codec/markers.d.ts +35 -0
- package/tools/lib/codec/markers.js +138 -0
- package/tools/lib/codec/release.d.ts +17 -0
- package/tools/lib/codec/release.js +69 -0
- package/tools/lib/codec/samples.json +778 -0
- package/tools/lib/codeowners.js +68 -4
- package/tools/lib/container-close.js +38 -0
- package/tools/lib/cure-diff.js +198 -9
- package/tools/lib/decision-record.js +15 -39
- package/tools/lib/docs-only.js +15 -1
- package/tools/lib/exposure-shape.js +42 -8
- package/tools/lib/git.js +324 -42
- package/tools/lib/group-labels.js +65 -0
- package/tools/lib/install-check.js +14 -8
- package/tools/lib/install-route.js +139 -0
- package/tools/lib/instruction-file.js +1 -0
- package/tools/lib/labels.js +22 -647
- package/tools/lib/local-adopt.js +8 -4
- package/tools/lib/migration-grant.js +206 -104
- package/tools/lib/place.js +2 -2
- package/tools/lib/release-cut.js +199 -25
- package/tools/lib/release-finalize.js +111 -23
- package/tools/lib/release-policy.js +130 -22
- package/tools/lib/release-runner.js +125 -0
- package/tools/lib/release-tag.js +3 -1
- package/tools/lib/scratch-dirs.js +118 -0
- package/tools/lib/ship-batch.js +36 -1
- package/tools/lib/ship-human-door.js +76 -0
- package/tools/lib/stamp.js +7 -0
- package/tools/lib/tracker-fake.js +195 -0
- package/tools/lib/tracker-github.js +106 -0
- package/tools/lib/tracker-scenarios.json +206 -0
- package/tools/lib/tracker.js +64 -0
- package/tools/lib/tree-green.js +88 -0
- package/tools/lib/util.js +17 -1
- package/tools/lib/verify-runs.js +104 -0
- package/tools/lib/wake.js +8 -90
- 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
|
-
|
|
18
|
-
|
|
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
|
|
95
|
-
if (!
|
|
47
|
+
const rel = codec.decodeRelease(c.body || '');
|
|
48
|
+
if (!rel) continue;
|
|
96
49
|
const login = (c.author && c.author.login) || '';
|
|
97
|
-
|
|
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
|
|
137
|
-
|
|
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 =
|
|
141
|
-
const
|
|
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
|
|
155
|
+
return codec.encodeRelease({ winner: id });
|
|
207
156
|
}
|
|
208
157
|
|
|
209
158
|
module.exports = {
|
|
@@ -95,6 +95,43 @@ function isIntentSession(s) {
|
|
|
95
95
|
return /^intent:\S/.test(String(s == null ? '' : s).trim());
|
|
96
96
|
}
|
|
97
97
|
|
|
98
|
+
/**
|
|
99
|
+
* Should a blank session be DERIVED for a person at a plain terminal (#528)? Only when nothing was
|
|
100
|
+
* said at all: `COLAB_SESSION` is UNSET (an explicit `COLAB_SESSION=''` is a deliberate "present no
|
|
101
|
+
* identity" and is honoured as one), and the shell is not an agent's (`CLAUDECODE=1` / `AI_AGENT`,
|
|
102
|
+
* the same signal `place.resolveAnchor` reads). An agent keeps #242's refusal: two concurrent agent
|
|
103
|
+
* sessions on one machine would derive the SAME person id, and `place.conflict`'s same-holder
|
|
104
|
+
* exemption would then read one session's hold as the other's โ the collision #242 exists to stop.
|
|
105
|
+
* A person running several units at once from separate shells has the same problem, which is why
|
|
106
|
+
* the README tells them to give each shell its own `COLAB_SESSION`.
|
|
107
|
+
*/
|
|
108
|
+
function shouldDerivePersonSession(env) {
|
|
109
|
+
const e = env || {};
|
|
110
|
+
if (Object.prototype.hasOwnProperty.call(e, 'COLAB_SESSION')) return false;
|
|
111
|
+
if (e.CLAUDECODE === '1' || e.AI_AGENT) return false;
|
|
112
|
+
return true;
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* The derived identity for a person (#528): `person:<who>/<hostToken>`, where `<who>` is git's
|
|
117
|
+
* `user.email`, else the OS user. The host is the opaque `h:` token (`machine.hostToken`), never
|
|
118
|
+
* the raw name: this value is written verbatim into claim comments, and a public tracker must not
|
|
119
|
+
* learn a machine's name from it (#369). Stable across invocations โ the same person on the same
|
|
120
|
+
* machine always derives the same value, which is what a re-acquire needs. '' when no `<who>` or
|
|
121
|
+
* no host is available: then nothing is derived and the blank-session paths apply unchanged.
|
|
122
|
+
*/
|
|
123
|
+
function derivePersonSession({ email, user, hostToken } = {}) {
|
|
124
|
+
const who = String(email || '').trim() || String(user || '').trim();
|
|
125
|
+
const host = String(hostToken || '').trim();
|
|
126
|
+
if (!who || !host || /\s/.test(who)) return '';
|
|
127
|
+
return `person:${who}/${host}`;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** Is `s` a derived person identity (#528)? */
|
|
131
|
+
function isPersonSession(s) {
|
|
132
|
+
return /^person:\S+$/.test(String(s == null ? '' : s).trim());
|
|
133
|
+
}
|
|
134
|
+
|
|
98
135
|
/**
|
|
99
136
|
* Are `a` and `b` on the SAME machine (#327)? Both carry a `machine` โ compare those (a raw id or
|
|
100
137
|
* the `m:` digest a claim comment carries โ `machineToken` makes the two comparable); raw ids of
|
|
@@ -168,8 +205,9 @@ function mergeClaimRecord(existing, incoming, { sameHolder } = {}) {
|
|
|
168
205
|
|
|
169
206
|
/**
|
|
170
207
|
* 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
|
|
172
|
-
* (
|
|
208
|
+
* token embedded in one (#306)? The repo's ONE answer to that question โ defined in codec/claim.js
|
|
209
|
+
* since #497 and re-exported here: `parseSessionField` (codec/claim.js) decodes a claim comment's
|
|
210
|
+
* `ยท session <field>` tail with exactly this test, and
|
|
173
211
|
* `warnWeakIdentity` warns with it. Two copies of a shape rule drift, and this one decides
|
|
174
212
|
* whether a hold can ever be released by its own owner, so there is one.
|
|
175
213
|
*
|
|
@@ -182,14 +220,11 @@ function mergeClaimRecord(existing, incoming, { sameHolder } = {}) {
|
|
|
182
220
|
* False for '' / null: absence is `warnWeakIdentity`'s and `requirePlaceIdentity`'s subject
|
|
183
221
|
* (#11/#242), never this predicate's โ callers test blankness first.
|
|
184
222
|
*/
|
|
185
|
-
|
|
186
|
-
const s = String(v == null ? '' : v).trim();
|
|
187
|
-
if (!s) return false;
|
|
188
|
-
return /^https?:\/\//.test(s) || /session_[\w-]+/.test(s);
|
|
189
|
-
}
|
|
223
|
+
const { looksLikeSessionId } = require('./codec/claim'); // one copy of the rule, in the codec (#497)
|
|
190
224
|
|
|
191
225
|
module.exports = {
|
|
192
226
|
DEFAULT_COMPONENTS, FINE_COMPONENTS,
|
|
193
227
|
claimIdentityProblem, components, identityString, sameClaimant, mergeClaimRecord,
|
|
194
228
|
looksLikeSessionId, isIntentSession, sameHost,
|
|
229
|
+
shouldDerivePersonSession, derivePersonSession, isPersonSession,
|
|
195
230
|
};
|
|
@@ -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,153 @@
|
|
|
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
|
+
// #528: a derived person identity (`claim-identity.js` `derivePersonSession`) is a session id
|
|
45
|
+
// too โ a stable join key, not a display name โ so it reads back as one from a claim comment.
|
|
46
|
+
return /^https?:\/\//.test(s) || /session_[\w-]+/.test(s) || /^person:\S+$/.test(s);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Encode the `ยท session <field>` tail of a claim comment. Both โ a markdown link; url only โ the
|
|
51
|
+
* legacy bare form; name only โ the bare name; neither โ nothing.
|
|
52
|
+
*/
|
|
53
|
+
function encodeSessionField(session, sessionName) {
|
|
54
|
+
if (sessionName && session) return ` ยท session [${sessionName}](${session})`;
|
|
55
|
+
if (session) return ` ยท session ${session}`;
|
|
56
|
+
if (sessionName) return ` ยท session ${sessionName}`;
|
|
57
|
+
return '';
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* Decode the `ยท session <field>` tail of a claim comment into { sessionName, session }. Accepts:
|
|
62
|
+
* `[name](url)` โ both; bare `https://โฆ`/`session_โฆ` โ url only; any other bare token โ name.
|
|
63
|
+
* The bare-URL branch is exactly the LEGACY format written before sessionName existed, so old
|
|
64
|
+
* comments keep parsing. Returns empty strings when there is no session tail.
|
|
65
|
+
*/
|
|
66
|
+
function parseSessionField(body) {
|
|
67
|
+
const m = String(body).match(SESSION_RE);
|
|
68
|
+
if (!m) return { sessionName: '', session: '' };
|
|
69
|
+
const v = m[1].trim();
|
|
70
|
+
const link = v.match(/^\[([^\]]*)\]\((.*)\)$/);
|
|
71
|
+
if (link) return { sessionName: link[1], session: link[2] };
|
|
72
|
+
if (looksLikeSessionId(v)) return { sessionName: '', session: v };
|
|
73
|
+
return { sessionName: v, session: '' };
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** `{login, host, session}` โ `login@host[#session]` โ the identity string a yield names. */
|
|
77
|
+
function encodeIdentity({ login, host, session } = {}) {
|
|
78
|
+
return `${login}@${host}${session ? `#${session}` : ''}`;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** `login@host[#session]` โ its parts. Logins cannot contain `@`, hosts cannot contain `#`. */
|
|
82
|
+
function parseIdentity(s) {
|
|
83
|
+
const str = String(s || '').trim();
|
|
84
|
+
const at = str.indexOf('@');
|
|
85
|
+
if (at <= 0) return null;
|
|
86
|
+
const rest = str.slice(at + 1);
|
|
87
|
+
const hash = rest.indexOf('#');
|
|
88
|
+
return {
|
|
89
|
+
login: str.slice(0, at),
|
|
90
|
+
host: hash === -1 ? rest : rest.slice(0, hash),
|
|
91
|
+
session: hash === -1 ? '' : rest.slice(hash + 1),
|
|
92
|
+
};
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* The exact claim-comment body. Every field is written as given: `worktree`/`branch` default to `-`
|
|
97
|
+
* ("none" โ it used to be the word `trunk`, which read as a branch that never existed, #53); `at`
|
|
98
|
+
* is the caller's ISO timestamp (the codec holds no clock); `machine` is the `m:` digest or empty
|
|
99
|
+
* (#327, the field is then omitted); `host` is the raw hostname or its `h:` token, whichever the
|
|
100
|
+
* destination allows (#369 โ deciding that is the caller's job, not the codec's).
|
|
101
|
+
*/
|
|
102
|
+
function encodeClaim({ worktree, branch, host, at, machine, session, sessionName } = {}) {
|
|
103
|
+
const base = `${CLAIM_MARK} โ worktree \`${worktree || '-'}\` ยท branch \`${branch || '-'}\` ยท host \`${host}\` ยท ${at}`;
|
|
104
|
+
const mach = machine ? ` ยท machine \`${machine}\`` : '';
|
|
105
|
+
return base + mach + encodeSessionField(session, sessionName);
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* A claim comment body โ { worktree, branch, host, at, machine, session, sessionName }, or null when
|
|
110
|
+
* the body carries no claim. Lenient exactly where the readers always were (CLAIM_RE is unanchored,
|
|
111
|
+
* a legacy comment simply lacks machine/session), and lossless on what `encodeClaim` writes:
|
|
112
|
+
* `worktree`/`branch` keep a literal `-` rather than mapping it to empty, so the pair round-trips.
|
|
113
|
+
*/
|
|
114
|
+
function decodeClaim(body) {
|
|
115
|
+
const str = String(body == null ? '' : body).trim();
|
|
116
|
+
const m = str.match(CLAIM_RE);
|
|
117
|
+
if (!m) return null;
|
|
118
|
+
const mm = str.match(MACHINE_RE);
|
|
119
|
+
const { session, sessionName } = parseSessionField(str);
|
|
120
|
+
return { worktree: m[1], branch: m[2], host: m[3], at: m[4], machine: mm ? mm[1] : '', session, sessionName };
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/**
|
|
124
|
+
* A release comment body. `{}` โ the plain marker (`colab release`, `worktree rm`); `{ winner }` โ
|
|
125
|
+
* a yield naming the winner's identity string. `rest` is any text after the marker (or after the
|
|
126
|
+
* yield's closing parenthesis) โ a hand-written release keeps its prose through a round trip.
|
|
127
|
+
*/
|
|
128
|
+
function encodeRelease({ winner, rest } = {}) {
|
|
129
|
+
const tail = rest || '';
|
|
130
|
+
if (winner) return `${RELEASE_MARK} (yielded โ earlier claim by ${winner} wins)${tail}`;
|
|
131
|
+
return RELEASE_MARK + tail;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/**
|
|
135
|
+
* A release comment body โ { kind: 'yield', winner, rest } | { kind: 'release', rest }, or null when
|
|
136
|
+
* the body is not a release. `winner` is the raw identity string (`parseIdentity` splits it).
|
|
137
|
+
*/
|
|
138
|
+
function decodeRelease(body) {
|
|
139
|
+
const str = String(body == null ? '' : body).trim();
|
|
140
|
+
if (!str.startsWith(RELEASE_MARK)) return null;
|
|
141
|
+
const y = str.match(YIELD_RE);
|
|
142
|
+
if (y) return { kind: 'yield', winner: y[1], rest: str.slice(y[0].length) };
|
|
143
|
+
return { kind: 'release', rest: str.slice(RELEASE_MARK.length) };
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
module.exports = {
|
|
147
|
+
CLAIM_MARK, RELEASE_MARK, CLAIM_RE, SESSION_RE, MACHINE_RE, YIELD_RE,
|
|
148
|
+
looksLikeSessionId,
|
|
149
|
+
encodeSessionField, parseSessionField,
|
|
150
|
+
encodeIdentity, parseIdentity,
|
|
151
|
+
encodeClaim, decodeClaim,
|
|
152
|
+
encodeRelease, decodeRelease,
|
|
153
|
+
};
|
|
@@ -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;
|