@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.
Files changed (74) hide show
  1. package/README.md +248 -213
  2. package/README.vi.md +252 -186
  3. package/audit/audit.mjs +193 -10
  4. package/package.json +7 -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 +1902 -278
  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 +223 -0
  23. package/tools/lib/claim-comments.js +13 -64
  24. package/tools/lib/claim-identity.js +42 -7
  25. package/tools/lib/codec/claim.d.ts +41 -0
  26. package/tools/lib/codec/claim.js +153 -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 +723 -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 +778 -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 +324 -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 +118 -0
  63. package/tools/lib/ship-batch.js +36 -1
  64. package/tools/lib/ship-human-door.js +76 -0
  65. package/tools/lib/stamp.js +7 -0
  66. package/tools/lib/tracker-fake.js +195 -0
  67. package/tools/lib/tracker-github.js +106 -0
  68. package/tools/lib/tracker-scenarios.json +206 -0
  69. package/tools/lib/tracker.js +64 -0
  70. package/tools/lib/tree-green.js +88 -0
  71. package/tools/lib/util.js +17 -1
  72. package/tools/lib/verify-runs.js +104 -0
  73. package/tools/lib/wake.js +8 -90
  74. package/tools/lib/workflow-triggers.js +48 -0
@@ -0,0 +1,35 @@
1
+ // Types for tools/lib/codec/markers.js (#499) — see index.d.ts.
2
+
3
+ export type MarkerForm = 'comment' | 'line';
4
+
5
+ // ── parent ───────────────────────────────────────────────────────────────────────────────────
6
+
7
+ export const PARENT_COMMENT_RE: RegExp;
8
+ export const PARENT_LINE_RE: RegExp;
9
+ export interface ParentRef {
10
+ /** `owner/repo` for a cross-repo parent, null for the same repo. */
11
+ repo: string | null;
12
+ number: number;
13
+ }
14
+ export function encodeParentRef(ref?: { repo?: string | null; number: number }): string;
15
+ export function decodeParentRef(ref: string | null | undefined): ParentRef | null;
16
+ export function encodeParent(p?: { repo?: string | null; number: number; form?: MarkerForm }): string;
17
+ export function decodeParent(marker: string | null | undefined): (ParentRef & { form: MarkerForm }) | null;
18
+ /** The comment form wins; `conflict` = more than one distinct parent declared. */
19
+ export function readParent(body: string | null | undefined): (ParentRef & { form: MarkerForm; conflict: boolean }) | null;
20
+ export function encodeParentBlock(ref?: { repo?: string | null; number: number }): string;
21
+
22
+ // ── close reason ─────────────────────────────────────────────────────────────────────────────
23
+
24
+ export type CloseReason = 'completed' | 'not-planned';
25
+ export const CLOSE_REASONS: ReadonlyArray<CloseReason>;
26
+ export const CLOSE_REASON_COMMENT_RE: RegExp;
27
+ export const CLOSE_REASON_LINE_RE: RegExp;
28
+ export function encodeCloseReason(c?: { reason: CloseReason; form?: MarkerForm }): string;
29
+ export function decodeCloseReason(marker: string | null | undefined): { reason: CloseReason; form: MarkerForm } | null;
30
+ export function encodeCloseReasonBlock(reason: CloseReason): string;
31
+ /** Null unless `state` is closed; then the newest comment carrying a valid marker decides. */
32
+ export function readCloseReason(item?: {
33
+ state?: string;
34
+ comments?: Array<{ body?: string | null; createdAt?: string }>;
35
+ }): CloseReason | null;
@@ -0,0 +1,138 @@
1
+ 'use strict';
2
+ /**
3
+ * CODEC (#499, epic #496): two markers for trackers that LACK a native field this toolkit relies
4
+ * on — a parent/child relation (native sub-issues) and a close reason (completed vs not planned).
5
+ * Pure and synchronous. No writer uses them yet: they are designed from documented tracker
6
+ * capabilities, so an adapter for such a tracker has one agreed spelling to write and read.
7
+ *
8
+ * PARENT. Written into the CHILD's body, in two forms:
9
+ * comment `<!-- colab:parent issue=<ref> -->` invisible, the machine-readable form
10
+ * line `Parent: <ref>` visible fallback, at the start of a line, for a
11
+ * tracker (or an editor) that strips HTML comments
12
+ * `<ref>` is `#<n>` (same repo) or `<owner>/<repo>#<n>`. An adapter writes both; a reader prefers
13
+ * the comment and falls back to the line (`readParent`).
14
+ *
15
+ * A parent is NEVER encoded as a dependency edge ("child blocks epic"): the conventions forbid an
16
+ * edge pointing at an epic (CONVENTIONS.md §5, *Epics*) — readiness would read every epic as
17
+ * blocked by its own children, which is the wrong question. Containment and dependency stay two
18
+ * different facts, on two different wires.
19
+ *
20
+ * CLOSE REASON. Also two forms, carried by a COMMENT posted when the item is closed:
21
+ * comment `<!-- colab:close-reason reason=<completed|not-planned> -->`
22
+ * line `Close reason: <completed|not-planned>`
23
+ * It is read for CLOSED items only (`readCloseReason`): on an open item — closed once, then
24
+ * reopened — an old marker describes a close that no longer stands, so it reads as nothing. The
25
+ * newest marker wins, so close → reopen → close reads the last close.
26
+ */
27
+
28
+ // ── parent ───────────────────────────────────────────────────────────────────────────────────
29
+
30
+ const PARENT_REF_RE = /^(?:([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+))?#([1-9][0-9]*)$/;
31
+ const PARENT_COMMENT_RE = /^<!-- colab:parent issue=(\S+) -->$/;
32
+ const PARENT_LINE_RE = /^Parent: (\S+)$/;
33
+
34
+ /** `{repo?, number}` → `#N` / `owner/repo#N`. */
35
+ function encodeParentRef({ repo, number } = {}) { return `${repo || ''}#${number}`; }
36
+ /** `#N` / `owner/repo#N` → `{repo, number}` (`repo` null for same-repo), or null. */
37
+ function decodeParentRef(ref) {
38
+ const m = PARENT_REF_RE.exec(String(ref == null ? '' : ref));
39
+ return m ? { repo: m[1] || null, number: Number(m[2]) } : null;
40
+ }
41
+
42
+ /** `{repo?, number, form: 'comment'|'line'}` → the marker. */
43
+ function encodeParent({ repo, number, form = 'comment' } = {}) {
44
+ const ref = encodeParentRef({ repo, number });
45
+ if (form === 'comment') return `<!-- colab:parent issue=${ref} -->`;
46
+ if (form === 'line') return `Parent: ${ref}`;
47
+ throw new TypeError(`encodeParent: unknown form ${JSON.stringify(form)}`);
48
+ }
49
+
50
+ /** ONE marker (comment or line, whole) → `{repo, number, form}`, or null. */
51
+ function decodeParent(marker) {
52
+ const s = String(marker == null ? '' : marker).trim();
53
+ for (const [form, re] of [['comment', PARENT_COMMENT_RE], ['line', PARENT_LINE_RE]]) {
54
+ const m = re.exec(s);
55
+ if (!m) continue;
56
+ const ref = decodeParentRef(m[1]);
57
+ return ref ? { ...ref, form } : null;
58
+ }
59
+ return null;
60
+ }
61
+
62
+ /**
63
+ * The parent a child's BODY declares → `{repo, number, form, conflict}`, or null. Each line is
64
+ * tried as a marker (a line form counts only at the start of a line; an indented one is quoted
65
+ * text). The comment form wins over the line form; `conflict` is true when the body carries more
66
+ * than one distinct parent, which a reader should report rather than silently pick.
67
+ */
68
+ function readParent(body) {
69
+ const found = [];
70
+ for (const line of String(body == null ? '' : body).replace(/\r\n/g, '\n').split('\n')) {
71
+ if (/^\s/.test(line)) continue;
72
+ const p = decodeParent(line);
73
+ if (p) found.push(p);
74
+ }
75
+ if (!found.length) return null;
76
+ const pick = found.find((p) => p.form === 'comment') || found[0];
77
+ const key = (p) => `${p.repo || ''}#${p.number}`;
78
+ return { ...pick, conflict: new Set(found.map(key)).size > 1 };
79
+ }
80
+
81
+ /** The child-body block an adapter writes: the comment, then the visible line. */
82
+ function encodeParentBlock({ repo, number } = {}) {
83
+ return `${encodeParent({ repo, number, form: 'comment' })}\n${encodeParent({ repo, number, form: 'line' })}`;
84
+ }
85
+
86
+ // ── close reason ─────────────────────────────────────────────────────────────────────────────
87
+
88
+ const CLOSE_REASONS = Object.freeze(['completed', 'not-planned']);
89
+ const CLOSE_REASON_COMMENT_RE = /^<!-- colab:close-reason reason=(\S+) -->$/;
90
+ const CLOSE_REASON_LINE_RE = /^Close reason: (\S+)$/;
91
+
92
+ /** `{reason, form: 'comment'|'line'}` → the marker. Throws on a reason outside the closed set. */
93
+ function encodeCloseReason({ reason, form = 'comment' } = {}) {
94
+ if (!CLOSE_REASONS.includes(reason)) throw new TypeError(`encodeCloseReason: unknown reason ${JSON.stringify(reason)}`);
95
+ if (form === 'comment') return `<!-- colab:close-reason reason=${reason} -->`;
96
+ if (form === 'line') return `Close reason: ${reason}`;
97
+ throw new TypeError(`encodeCloseReason: unknown form ${JSON.stringify(form)}`);
98
+ }
99
+
100
+ /** ONE marker (whole) → `{reason, form}`, or null — including for a reason outside the closed set. */
101
+ function decodeCloseReason(marker) {
102
+ const s = String(marker == null ? '' : marker).trim();
103
+ for (const [form, re] of [['comment', CLOSE_REASON_COMMENT_RE], ['line', CLOSE_REASON_LINE_RE]]) {
104
+ const m = re.exec(s);
105
+ if (m) return CLOSE_REASONS.includes(m[1]) ? { reason: m[1], form } : null;
106
+ }
107
+ return null;
108
+ }
109
+
110
+ /** The close-reason block an adapter posts: the comment, then the visible line. */
111
+ function encodeCloseReasonBlock(reason) {
112
+ return `${encodeCloseReason({ reason, form: 'comment' })}\n${encodeCloseReason({ reason, form: 'line' })}`;
113
+ }
114
+
115
+ /**
116
+ * The close reason of an item → `'completed' | 'not-planned'`, or null. `state` is the item's state
117
+ * now; anything but `closed` (case-insensitive) reads null whatever the comments say. Otherwise the
118
+ * NEWEST comment (by `createdAt`) carrying a valid marker on one of its lines decides; within one
119
+ * comment the comment form wins over the line form.
120
+ */
121
+ function readCloseReason({ state, comments } = {}) {
122
+ if (String(state || '').toLowerCase() !== 'closed') return null;
123
+ const sorted = [...(Array.isArray(comments) ? comments : [])]
124
+ .sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0));
125
+ for (const c of sorted) {
126
+ const found = String((c && c.body) || '').replace(/\r\n/g, '\n').split('\n')
127
+ .filter((l) => !/^\s/.test(l)).map(decodeCloseReason).filter(Boolean);
128
+ if (found.length) return (found.find((f) => f.form === 'comment') || found[0]).reason;
129
+ }
130
+ return null;
131
+ }
132
+
133
+ module.exports = {
134
+ PARENT_COMMENT_RE, PARENT_LINE_RE,
135
+ encodeParentRef, decodeParentRef, encodeParent, decodeParent, readParent, encodeParentBlock,
136
+ CLOSE_REASONS, CLOSE_REASON_COMMENT_RE, CLOSE_REASON_LINE_RE,
137
+ encodeCloseReason, decodeCloseReason, encodeCloseReasonBlock, readCloseReason,
138
+ };
@@ -0,0 +1,17 @@
1
+ // Types for tools/lib/codec/release.js (#498) — see index.d.ts.
2
+
3
+ export const VERSION_RE: RegExp;
4
+ export const TRACKING_MARKER_RE: RegExp;
5
+ export const RELEASE_EVENT_RE: RegExp;
6
+
7
+ export function encodeTrackingMarker(version: string): string;
8
+ /** The canonical `vX.Y.Z` a body's tracking marker declares, or null. */
9
+ export function decodeTrackingMarker(body: string | null | undefined): string | null;
10
+
11
+ /** Keys are written in the object's own order — part of the wire format. */
12
+ export function encodeReleaseEvent(fields: Record<string, string | number>): string;
13
+ export function decodeReleaseEvent(marker: string | null | undefined): Record<string, string> | null;
14
+
15
+ export function encodeReleasedComment(c?: { version: string; sha: string }): string;
16
+ /** `sha` is the 7-character form the comment carries. */
17
+ export function decodeReleasedComment(body: string | null | undefined): { version: string; sha: string } | null;
@@ -0,0 +1,69 @@
1
+ 'use strict';
2
+ /**
3
+ * CODEC (#498, epic #496): the RELEASE-RUNG markers `colab release finalize` writes to a tracker
4
+ * (CONVENTIONS.md §6, *The release rung*), as encode/decode pairs. Pure and synchronous.
5
+ *
6
+ * tracking marker — `<!-- colab:release version=vX.Y.Z -->`, the first line of a tracking
7
+ * issue's body. Only the marker identifies the version, never the title.
8
+ * event marker — `<!-- colab:release-event k=v … -->`, one per thing announced on the
9
+ * tracking issue, keys in the order written. Its exact presence is what makes
10
+ * a re-run post nothing twice, so key order is part of the wire format.
11
+ * released comment — the event marker `released=vX.Y.Z` plus one visible line, posted once on
12
+ * each issue a release carried.
13
+ *
14
+ * Deciding which candidate, which period, and whether to finalize stays in
15
+ * tools/lib/release-finalize.js, which re-exports these under the names it always had.
16
+ */
17
+
18
+ const VERSION_RE = /^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
19
+ const TRACKING_MARKER_RE = /<!--\s*colab:release\s+version=(v[0-9]+\.[0-9]+\.[0-9]+)\s*-->/;
20
+ const RELEASE_EVENT_RE = /^<!-- colab:release-event((?: [^\s=]+=\S*)+) -->$/;
21
+ const RELEASED_COMMENT_RE = /^<!-- colab:release-event released=(\S+) -->\nReleased in \*\*(\S+)\*\* \(`([^`]*)`\)\.$/;
22
+
23
+ /** `vX.Y.Z` → the tracking marker. */
24
+ function encodeTrackingMarker(version) { return `<!-- colab:release version=${version} -->`; }
25
+
26
+ /** The version a body's tracking marker declares, or null — a marker naming a non-canonical
27
+ * version (a leading zero) declares nothing. */
28
+ function decodeTrackingMarker(body) {
29
+ const m = TRACKING_MARKER_RE.exec(String(body || ''));
30
+ return m && VERSION_RE.test(m[1]) ? m[1] : null;
31
+ }
32
+
33
+ /** `{k: v, …}` → `<!-- colab:release-event k=v … -->`, keys in the order given. */
34
+ function encodeReleaseEvent(fields) {
35
+ return `<!-- colab:release-event ${Object.entries(fields).map(([k, v]) => `${k}=${v}`).join(' ')} -->`;
36
+ }
37
+
38
+ /** An event marker (the whole string) → its fields as strings, in written order; null if not one. */
39
+ function decodeReleaseEvent(marker) {
40
+ const m = RELEASE_EVENT_RE.exec(String(marker == null ? '' : marker).trim());
41
+ if (!m) return null;
42
+ const out = {};
43
+ for (const pair of m[1].trim().split(' ')) {
44
+ const i = pair.indexOf('=');
45
+ const k = pair.slice(0, i);
46
+ if (Object.prototype.hasOwnProperty.call(out, k)) return null; // a repeated key cannot round-trip
47
+ out[k] = pair.slice(i + 1);
48
+ }
49
+ return out;
50
+ }
51
+
52
+ /** `{version, sha}` → the "released in" comment; `sha` is shortened to 7 characters. */
53
+ function encodeReleasedComment({ version, sha } = {}) {
54
+ return `${encodeReleaseEvent({ released: version })}\nReleased in **${version}** (\`${String(sha || '').slice(0, 7)}\`).`;
55
+ }
56
+
57
+ /** A "released in" comment → `{version, sha}` (sha as written, 7 characters), or null. */
58
+ function decodeReleasedComment(body) {
59
+ const m = RELEASED_COMMENT_RE.exec(String(body == null ? '' : body).replace(/\r\n/g, '\n').trim());
60
+ if (!m || m[1] !== m[2]) return null;
61
+ return { version: m[1], sha: m[3] };
62
+ }
63
+
64
+ module.exports = {
65
+ VERSION_RE, TRACKING_MARKER_RE, RELEASE_EVENT_RE,
66
+ encodeTrackingMarker, decodeTrackingMarker,
67
+ encodeReleaseEvent, decodeReleaseEvent,
68
+ encodeReleasedComment, decodeReleasedComment,
69
+ };