@feigi/fleet-ctl 3.47.7 → 3.48.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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.47.7",
3
+ "version": "3.48.1",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -0,0 +1,206 @@
1
+ #!/usr/bin/env node
2
+ // The finisher's labelling duty as one command, so its two halves cannot be
3
+ // read as one: the release-label check is a precondition, and a finisher that
4
+ // stopped after it reported `labelled` on a PR that never got the label.
5
+ //
6
+ // finisher-label.mjs --pr <M> --pin <sha> [--repo <dir>]
7
+ //
8
+ // `--pin` is the full 40-hex head the finisher audited; `--repo` is the
9
+ // directory `gh` runs in (it resolves the repository from there), the cwd when
10
+ // omitted. Reached through the Resolver: `~/.fleet/bin/fleet-run
11
+ // finisher-label.mjs ...`.
12
+ //
13
+ // Steps, in this order, each one only if every earlier one held:
14
+ //
15
+ // 1 read the PR's labels and comments and count the release labels,
16
+ // `patch`/`minor`/`major`. Exactly one passes. Zero or several is exit 3
17
+ // and nothing is written. A repo whose label list defines none of the
18
+ // three has nothing to count: the count is skipped and the receipt says
19
+ // `releaseLabels: "undefined-in-repo"`. That list is read only when the
20
+ // PR carries none of them — one on the PR proves it is defined — and a
21
+ // list that fills the limit it was read with proves nothing, so it is
22
+ // exit 2 rather than a skipped count.
23
+ // 2 comment `ready-to-merge-head: <pin>`, the record the merge bot reads as
24
+ // the head the label was applied to — skipped when the newest such
25
+ // comment already names this pin.
26
+ // 3 add the `ready-to-merge` label.
27
+ // 4 read the labels back. Exit 0 only when the read-back carries
28
+ // `ready-to-merge`; `gh pr edit` returning 0 is not that.
29
+ //
30
+ // Idempotent: a PR that already carries `ready-to-merge` and whose newest
31
+ // head record names this pin is left as it is — no comment, no label write —
32
+ // and still answers 0 off the read-back, `added: false`.
33
+ //
34
+ // Stdout is always one JSON line, the receipt:
35
+ //
36
+ // {pr, pin, releaseLabels, commented, added, readBack, exit, firstRead
37
+ // [, step, error]}
38
+ //
39
+ // releaseLabels the release labels the PR carried, or "undefined-in-repo",
40
+ // or null when step 1 never got an answer
41
+ // commented this run posted the head record
42
+ // added this run wrote the label
43
+ // readBack every label name the step 4 read carried, null if it never ran
44
+ // firstRead every label name step 1 read carried, null if it never ran
45
+ // step on exit 2 only, the step that failed: `pin`, `repo`, or the
46
+ // step whose `gh` call failed
47
+ // error on exit 2 only, what `gh` (or the invocation) said
48
+ //
49
+ // A usage error that never reaches `gh` — a missing or unknown flag — is a
50
+ // refusal on stderr with no receipt, as in every other script's `die()`.
51
+ //
52
+ // Exit vocabulary:
53
+ //
54
+ // 0 the read-back carries `ready-to-merge`
55
+ // 2 the invocation or a `gh` call failed — its stderr is in the receipt and
56
+ // on stderr, and no later step ran
57
+ // 3 the PR does not carry exactly one release label — nothing was written
58
+ // 4 every write returned 0 and the read-back does not carry the label
59
+
60
+ import { spawnSync } from "node:child_process";
61
+ import { statSync } from "node:fs";
62
+ import { makeDie, defineFlags, writeAll } from "./arg.mjs";
63
+ import { gitEnv } from "./git-env.mjs";
64
+
65
+ const NAME = "finisher-label";
66
+ const LABEL = "ready-to-merge";
67
+ const RELEASE = ["patch", "minor", "major"];
68
+ const LIST_LIMIT = 1000;
69
+
70
+ const die = makeDie(NAME);
71
+ const { arg, numArg, sweep, stray } = defineFlags(die, {
72
+ flags: { pr: "value", pin: "value", repo: "value" },
73
+ });
74
+
75
+ const USAGE = "usage: finisher-label.mjs --pr <M> --pin <sha> [--repo <dir>]";
76
+
77
+ // The sweep runs before the required-flag check so a misspelt flag is named
78
+ // as that, not buried under a missing-flag usage line.
79
+ sweep();
80
+ stray();
81
+ const pr = numArg("pr");
82
+ const pinArg = arg("pin");
83
+ const repo = arg("repo");
84
+ if (pr === null || pinArg === null) die(USAGE);
85
+
86
+ const receipt = {
87
+ pr,
88
+ pin: pinArg,
89
+ releaseLabels: null,
90
+ commented: false,
91
+ added: false,
92
+ readBack: null,
93
+ exit: 0,
94
+ firstRead: null,
95
+ };
96
+
97
+ function finish(exit, extra = {}, message = null) {
98
+ Object.assign(receipt, extra, { exit });
99
+ writeAll(1, `${JSON.stringify(receipt)}\n`);
100
+ if (message !== null) writeAll(2, `${NAME}: ${message}\n`);
101
+ process.exit(exit);
102
+ }
103
+
104
+ function fail(step, error) {
105
+ finish(2, { step, error }, `${step}: ${error}`);
106
+ }
107
+
108
+ // Full SHAs only: the bot's record grammar is exactly 40 lowercase hex, so a
109
+ // shorter or uppercase pin would be a record it cannot read. Case is folded
110
+ // rather than refused — `ABC…` names the same commit.
111
+ const pin = pinArg.toLowerCase();
112
+ if (!/^[0-9a-f]{40}$/.test(pin)) {
113
+ fail("pin", `--pin needs a full 40-character commit SHA, got ${pinArg}`);
114
+ }
115
+ receipt.pin = pin;
116
+
117
+ // A missing directory makes spawn report ENOENT for `gh` itself, which would
118
+ // blame the binary for a bad --repo.
119
+ if (repo !== null && !statSync(repo, { throwIfNoEntry: false })?.isDirectory()) {
120
+ fail("repo", `--repo is not a directory: ${repo}`);
121
+ }
122
+
123
+ // `gh` resolves its repository from the cwd's git remotes, so an ambient
124
+ // GIT_DIR would retarget every call at another repository.
125
+ const GH_ENV = gitEnv();
126
+
127
+ // stdout parsed, stderr captured: what `gh` said is the receipt's `error`.
128
+ function gh(step, args) {
129
+ const r = spawnSync("gh", args, { encoding: "utf8", env: GH_ENV, stdio: ["ignore", "pipe", "pipe"], ...(repo === null ? {} : { cwd: repo }) });
130
+ if (r.error) fail(step, `could not run gh: ${r.error.message}`);
131
+ if (r.signal) fail(step, `gh was killed by ${r.signal}`);
132
+ if (r.status !== 0) fail(step, (r.stderr ?? "").trim() || `gh exited ${r.status}`);
133
+ return r.stdout;
134
+ }
135
+
136
+ const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
137
+
138
+ function ghJson(step, args, shape) {
139
+ const out = gh(step, args);
140
+ let v;
141
+ try {
142
+ v = JSON.parse(out);
143
+ } catch {
144
+ return fail(step, `gh printed no JSON: ${out.slice(0, 200)}`);
145
+ }
146
+ if (!shape(v)) fail(step, `gh printed an unexpected shape: ${out.slice(0, 200)}`);
147
+ return v;
148
+ }
149
+
150
+ const namedList = (v) => Array.isArray(v) && v.every((l) => isObject(l) && typeof l.name === "string");
151
+
152
+ const labelNames = (v) => v.labels.map((l) => l.name);
153
+
154
+ // --- 1: the release-label count -------------------------------------------
155
+ const first = ghJson("read-labels", ["pr", "view", String(pr), "--json", "labels,comments"], (v) =>
156
+ isObject(v) && namedList(v.labels) && Array.isArray(v.comments) && v.comments.every((c) => isObject(c) && typeof c.body === "string" && typeof c.createdAt === "string"));
157
+ const firstLabels = labelNames(first);
158
+ receipt.firstRead = firstLabels;
159
+ const found = RELEASE.filter((r) => firstLabels.includes(r));
160
+
161
+ if (found.length === 0) {
162
+ const defined = ghJson("list-labels", ["label", "list", "--json", "name", "--limit", String(LIST_LIMIT)], namedList).map((l) => l.name);
163
+ if (RELEASE.some((r) => defined.includes(r))) {
164
+ finish(3, { releaseLabels: found }, "the PR carries no release label (patch, minor or major); nothing was written");
165
+ }
166
+ // A list that fills the limit may be cut off before the release labels, so
167
+ // their absence from it proves nothing.
168
+ if (defined.length >= LIST_LIMIT) {
169
+ fail("list-labels", `the repository has ${LIST_LIMIT} or more labels, so the list may be cut off before patch, minor or major`);
170
+ }
171
+ receipt.releaseLabels = "undefined-in-repo";
172
+ } else if (found.length > 1) {
173
+ finish(3, { releaseLabels: found }, `the PR carries more than one release label (${found.join(", ")}); nothing was written`);
174
+ } else {
175
+ receipt.releaseLabels = found;
176
+ }
177
+
178
+ // --- 2: the head record ----------------------------------------------------
179
+ // The newest record wins, the way the merge bot reads it: a matching record
180
+ // older than one naming another head is not the record the bot will act on.
181
+ const RECORD = /^ready-to-merge-head: ([0-9a-f]{40})\s*$/;
182
+ const records = first.comments
183
+ .map((c, i) => ({ i, at: c.createdAt, m: RECORD.exec(c.body) }))
184
+ .filter((c) => c.m !== null)
185
+ .sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : a.i - b.i));
186
+ const recorded = records.length > 0 && records[records.length - 1].m[1] === pin;
187
+ const labelled = firstLabels.includes(LABEL);
188
+
189
+ if (!recorded) {
190
+ gh("comment", ["pr", "comment", String(pr), "--body", `ready-to-merge-head: ${pin}`]);
191
+ receipt.commented = true;
192
+ }
193
+
194
+ // --- 3: the label ----------------------------------------------------------
195
+ if (!(recorded && labelled)) {
196
+ gh("add-label", ["pr", "edit", String(pr), "--add-label", LABEL]);
197
+ receipt.added = true;
198
+ }
199
+
200
+ // --- 4: the read-back ------------------------------------------------------
201
+ const back = ghJson("read-back", ["pr", "view", String(pr), "--json", "labels"], (v) => isObject(v) && namedList(v.labels));
202
+ receipt.readBack = labelNames(back);
203
+ if (!receipt.readBack.includes(LABEL)) {
204
+ finish(4, {}, `the read-back does not carry ${LABEL}`);
205
+ }
206
+ finish(0);
@@ -3317,30 +3317,32 @@ a minute apart showed *different* mutants, so a member's report and any single
3317
3317
  silent-destruction ordering above — report it back, do not run it. One
3318
3318
  finisher refused exactly that instruction live, on the grounds it could not
3319
3319
  prove the diff was its own; that was judgement, and this is the rule.
3320
- 3. Add `ready-to-merge` — two steps, each checked on its own, in this order:
3321
- - **(a) Exactly one release label.** Read the PR's labels back
3322
- (`gh pr view <pr> --json labels`) and find **exactly one** release label,
3323
- `patch`/`minor`/`major`. Zero or more than one halts the finisher before
3324
- the label, naming which it found. This is the backstop for a label lost
3325
- wherever it was lost, a hand-created PR included: a `gh pr create` that
3326
- outran its caller's tool timeout leaves the PR open with the flag
3327
- unapplied and no exit status anywhere to notice, and nothing downstream
3328
- re-derives the release label. Count only those three — the PR carries
3329
- other labels, `ready-to-merge` itself among them once you add it, so a PR
3330
- wearing one release label beside them passes unchanged. A repo that
3331
- defines none of the three does not gate on one — `gh label list` settles
3332
- that, and it is no licence to skip the read where they exist.
3333
- - **(b) Add the label:** record the head you audited first —
3334
- `gh pr comment <pr> --body "ready-to-merge-head: <your dispatch pin>"`,
3335
- the full SHA, which the merge bot reads as the head the label was applied
3336
- to — then `gh pr edit <pr> --add-label ready-to-merge`. (a)
3337
- passing labels nothing — it is the precondition, and these commands are
3338
- the duty. Two finishers in one run stopped at (a) and reported
3339
- `labelled` on PRs that sat out of the merge queue.
3340
- 4. Report you the label (its post-add read-back: `gh pr view <pr> --json labels`
3341
- run after 3(b), output as printed), the deferral issue numbers — a
3342
- `filed: #N <subject>` line for every issue duty 2 created, and
3343
- `unrecorded: #N <subject>` for one whose `filed` failed twice — and anything
3320
+ 3. Add `ready-to-merge` by running one script, `finisher-label.mjs` — the
3321
+ release-label check and the label write are one command, because the check
3322
+ reads like the whole duty. Its exit code is the finisher's verdict:
3323
+ `~/.fleet/bin/fleet-run finisher-label.mjs --pr <pr> --pin <your dispatch pin>`,
3324
+ the pin the full SHA. In order, it finds **exactly one** release label,
3325
+ `patch`/`minor`/`major` — zero or more than one is exit 3 before anything is
3326
+ written, naming which it found; then it records the head you audited as a PR
3327
+ comment, which the merge bot reads as the head the label was applied to;
3328
+ then it adds the label and reads the labels back, and exits 0 only when that
3329
+ read-back carries `ready-to-merge`. A failed call is exit 2 and the read-back
3330
+ without the label is exit 4; no step after a failed one runs. The count is
3331
+ the backstop for a label lost wherever it was lost, a hand-created PR
3332
+ included: a `gh pr create` that outran its caller's tool timeout leaves the
3333
+ PR open with the flag unapplied and no exit status anywhere to notice, and
3334
+ nothing downstream re-derives the release label. It counts only those three
3335
+ — the PR carries other labels, `ready-to-merge` itself among them once the
3336
+ script adds it, so a PR wearing one release label beside them passes
3337
+ unchanged. A repo that defines none of the three does not gate on one — the
3338
+ script settles that from the repo's own label list and says
3339
+ `undefined-in-repo` in its receipt. Two finishers in one run stopped at the
3340
+ release-label check and reported `labelled` on PRs that sat out of the merge
3341
+ queue.
3342
+ 4. Report you the label (the script's receipt, the JSON line it printed, as
3343
+ printed), the deferral issue numbers — a `filed: #N <subject>` line for
3344
+ every issue duty 2 created, and `unrecorded: #N <subject>` for one whose
3345
+ `filed` failed twice — and anything
3344
3346
  it halted on — cause and evidence, below, never a bare "head moved". The
3345
3347
  cause is one word of the ledger's `halted:<cause>` vocabulary:
3346
3348
  `live-editor`, `rebase` or `past-pin` from the cause block below,
@@ -3445,21 +3447,26 @@ it reached, so reading that summary alone reads a partial suite as a whole one:
3445
3447
  > cause `other`, with both runs — the mutant's and the unmutated tree's — as
3446
3448
  > evidence; label nothing. A kill's evidence line goes in your report.
3447
3449
 
3448
- **Give the finisher duty 3 verbatim as well, as its two steps.** The finisher's
3450
+ **Give the finisher duty 3 verbatim as well, as one script.** The finisher's
3449
3451
  agent definition carries no duty text, so this brief is the whole of duty 3 it
3450
- sees. Two finishers in one run read the release-label check as the
3451
- whole duty and reported `labelled` on a PR that never got the label:
3452
-
3453
- > **Duty 3 is two steps, and only the second one labels.**
3454
- > (a) `gh pr view <M> --json labels` — confirm exactly one of
3455
- > `patch`/`minor`/`major`. Zero or more than one halts you before the label:
3456
- > name which you found. A repo whose `gh label list` defines none of the three
3457
- > does not gate on one.
3458
- > (b) `gh pr comment <M> --body "ready-to-merge-head: <your dispatch pin>"`
3459
- > (the full SHA), then `gh pr edit <M> --add-label ready-to-merge`. Step (a)
3460
- > passing labels nothing; these commands are the duty.
3461
- > Then run `gh pr view <M> --json labels` once more and put its output in your
3462
- > report: that read-back is what tells the controller the label is on.
3452
+ sees. Two finishers in one run read the release-label check as the whole duty
3453
+ and reported `labelled` on a PR that never got the label, so the check and the
3454
+ label write are one command and the finisher never runs either alone:
3455
+
3456
+ > **Duty 3 is one script, and its exit code is your verdict.**
3457
+ > `~/.fleet/bin/fleet-run finisher-label.mjs --pr <M> --pin <your dispatch pin>`
3458
+ > (the full SHA). It confirms exactly one of `patch`/`minor`/`major` is on the
3459
+ > PR, records the head you audited, adds `ready-to-merge`, and reads the labels
3460
+ > back. Exit 0 is the only code that means the label is on. Exit 3 means the PR
3461
+ > carries zero or more than one release label: you are halted before the label,
3462
+ > and the receipt names which it found. Exit 4 means the read-back does not carry
3463
+ > the label, written or not. Exit 2 means a `gh` call or the invocation
3464
+ > itself failed: report the stderr it printed. Every non-zero exit halts you
3465
+ > with cause `other`, with the receipt as evidence, and you do not run any of
3466
+ > its steps by hand to get past it. A repo whose label list defines none of the
3467
+ > three does not gate on one, and the script says so in its receipt. Put the
3468
+ > receipt, the JSON line it printed, in your report as printed: it is what tells
3469
+ > the controller the label is on.
3463
3470
 
3464
3471
  **Once the label is on, take it off before you approve any push.** The label is a
3465
3472
  verdict on the tree the finisher read, and a GitHub label does not follow the