@feigi/fleet-ctl 3.107.0 → 3.108.0

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.107.0",
3
+ "version": "3.108.0",
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,182 @@
1
+ #!/usr/bin/env node
2
+ // The Label map: the string the consumer's tracker uses for each Label role.
3
+ // This module owns the map's cache format — the file, its validity rules, the
4
+ // writer and the reader every role-reading script imports — and the `show`
5
+ // verb. It derives nothing: the derivation step is `ensure`, which is not
6
+ // here yet, so every refusal below names it as the step that writes the map.
7
+ //
8
+ // THE CACHE is `.fleet/labels.json`, resolved through fleet-dir.mjs's
9
+ // fleetFile() like the pre-flight marker, so a member in its own worktree and
10
+ // the controller in the main checkout name one file. `.fleet/` is gitignored,
11
+ // so the file is never committed, and it is never written by hand. Content:
12
+ // derivedAt ISO time of the derivation that wrote it
13
+ // table what the triage-label table said then: { present, rows: {role: string} }
14
+ // roles every Label role -> the string the tracker uses
15
+ // origin every Label role -> "table" | "default" | "maintainer"
16
+ //
17
+ // VALID STRINGS (labelStringFaults): non-empty after trimming, at most 50
18
+ // characters, no `"` and no `\`, and no two roles mapping to one string,
19
+ // compared ignoring case.
20
+ //
21
+ // THE READER (readLabelMap) returns `roles` when the cache parses, holds every
22
+ // Label role and passes the string rules; anything else throws
23
+ // LabelMapUnreadable. It never reads the tracker's live label list and has no
24
+ // defaults: an absent or broken map is a refusal, never a guess.
25
+ //
26
+ // THE WRITER (writeLabelMap) writes the whole cache to a temp file beside the
27
+ // target and renames it over the target, so a reader never sees half of it.
28
+ // It writes what it is handed: checking the map is its caller's step.
29
+ //
30
+ // CLI:
31
+ // label-map.mjs show [<role>] the mapped string for <role>, or the whole
32
+ // `roles` object as JSON with no role.
33
+ // Exit 0 printed; 1 no cache or an invalid one, the message naming `ensure`;
34
+ // 2 an unknown role, no repository, or a usage refusal (any other verb).
35
+ //
36
+ // Zero deps: node builtins and sibling scripts only.
37
+
38
+ import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
39
+ import { dirname } from "node:path";
40
+ import { isCLI } from "./is-cli.mjs";
41
+ import { makeDie, writeAll } from "./arg.mjs";
42
+ import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
43
+
44
+ const NAME = "label-map";
45
+ const die = makeDie(NAME);
46
+ const USAGE = "usage: label-map.mjs show [<role>]";
47
+ const MAX_LENGTH = 50;
48
+ const DERIVE = "run `label-map.mjs ensure`, the Label map derivation step";
49
+
50
+ export const LABEL_MAP_FILE = "labels.json";
51
+
52
+ export const LABEL_ROLES = Object.freeze([
53
+ "needs-triage",
54
+ "needs-info",
55
+ "ready-for-agent",
56
+ "ready-for-human",
57
+ "wontfix",
58
+ "in-progress",
59
+ "onhold",
60
+ "ready-to-merge",
61
+ ]);
62
+
63
+ export class LabelMapUnreadable extends Error {
64
+ constructor(message) {
65
+ super(message);
66
+ this.name = "LabelMapUnreadable";
67
+ }
68
+ }
69
+
70
+ // The rule a single string breaks on its own, or null.
71
+ function stringFault(value) {
72
+ if (value === undefined) return "missing";
73
+ if (typeof value !== "string") return `not a string (${JSON.stringify(value)})`;
74
+ if (value.trim() === "") return "empty after trimming";
75
+ if (value.length > MAX_LENGTH) return `longer than ${MAX_LENGTH} characters (${value.length})`;
76
+ if (value.includes('"')) return 'contains `"`';
77
+ if (value.includes("\\")) return "contains `\\`";
78
+ return null;
79
+ }
80
+
81
+ /**
82
+ * Every way `roles` (role -> string) breaks the Label map's string rules, as
83
+ * `[{ role, rule }]` in role order; empty when it breaks none. A role absent
84
+ * from `roles` is a fault too. Two roles mapping to one string, compared
85
+ * ignoring case, is reported once, on the later role, its rule naming the
86
+ * earlier one; a string that already breaks a rule on its own is not compared.
87
+ */
88
+ export function labelStringFaults(roles) {
89
+ const faults = [];
90
+ const seen = new Map();
91
+ for (const role of LABEL_ROLES) {
92
+ const value = Object.hasOwn(roles, role) ? roles[role] : undefined;
93
+ const rule = stringFault(value);
94
+ if (rule) {
95
+ faults.push({ role, rule });
96
+ continue;
97
+ }
98
+ const key = value.toLowerCase();
99
+ const first = seen.get(key);
100
+ if (first) faults.push({ role, rule: `maps to the same string as ${first} (${JSON.stringify(value)}), compared ignoring case` });
101
+ else seen.set(key, role);
102
+ }
103
+ return faults;
104
+ }
105
+
106
+ /**
107
+ * Write `map` ({ derivedAt, table, roles, origin }) as the cache of the
108
+ * repository `cwd` belongs to, through a temp file beside it, and return the
109
+ * cache's path. Throws FleetDirUnresolvable outside a repository, and the
110
+ * filesystem's own error when the file cannot be written.
111
+ */
112
+ export function writeLabelMap(map, { cwd = process.cwd() } = {}) {
113
+ const file = fleetFile(LABEL_MAP_FILE, { cwd });
114
+ const tmp = `${file}.${process.pid}.tmp`;
115
+ mkdirSync(dirname(file), { recursive: true });
116
+ try {
117
+ writeFileSync(tmp, `${JSON.stringify(map)}\n`);
118
+ renameSync(tmp, file);
119
+ } catch (e) {
120
+ // The write's own error is the one to report: a temp file that cannot be
121
+ // removed (a directory in its place) must not replace it.
122
+ try { rmSync(tmp, { force: true }); } catch {}
123
+ throw e;
124
+ }
125
+ return file;
126
+ }
127
+
128
+ /**
129
+ * The `roles` object (every Label role -> its string) of the cache of the
130
+ * repository `cwd` belongs to. Throws LabelMapUnreadable, its message naming
131
+ * `ensure`, when the cache is absent, does not parse, lacks a role or breaks
132
+ * the string rules; throws FleetDirUnresolvable outside a repository.
133
+ */
134
+ export function readLabelMap({ cwd = process.cwd() } = {}) {
135
+ const file = fleetFile(LABEL_MAP_FILE, { cwd });
136
+ let text;
137
+ try {
138
+ text = readFileSync(file, "utf8");
139
+ } catch (e) {
140
+ if (e.code === "ENOENT") throw new LabelMapUnreadable(`no Label map at ${file}: ${DERIVE}`);
141
+ throw new LabelMapUnreadable(`cannot read the Label map at ${file} (${e.code ?? e.message}): ${DERIVE}`);
142
+ }
143
+ let cache;
144
+ try {
145
+ cache = JSON.parse(text);
146
+ } catch (e) {
147
+ throw new LabelMapUnreadable(`the Label map at ${file} does not parse (${e.message}): ${DERIVE}`);
148
+ }
149
+ const roles = cache?.roles;
150
+ if (roles === null || typeof roles !== "object" || Array.isArray(roles)) {
151
+ throw new LabelMapUnreadable(`the Label map at ${file} holds no \`roles\` object: ${DERIVE}`);
152
+ }
153
+ const faults = labelStringFaults(roles);
154
+ if (faults.length) {
155
+ const why = faults.map(({ role, rule }) => `${role}: ${rule}`).join("; ");
156
+ throw new LabelMapUnreadable(`the Label map at ${file} is invalid — ${why}: ${DERIVE}`);
157
+ }
158
+ return Object.fromEntries(LABEL_ROLES.map((role) => [role, roles[role]]));
159
+ }
160
+
161
+ function main() {
162
+ const [verb, ...rest] = process.argv.slice(2);
163
+ if (verb !== "show") die(verb === undefined ? USAGE : `unknown verb ${JSON.stringify(verb)}; ${USAGE}`);
164
+ if (rest.length > 1) die(`show takes at most one role, got: ${rest.join(" ")}; ${USAGE}`);
165
+ const [role] = rest;
166
+ if (role !== undefined && !LABEL_ROLES.includes(role)) {
167
+ die(`unknown role ${JSON.stringify(role)}; the roles are ${LABEL_ROLES.join(", ")}`);
168
+ }
169
+ let roles;
170
+ try {
171
+ roles = readLabelMap();
172
+ } catch (e) {
173
+ if (e instanceof FleetDirUnresolvable) die(e.message);
174
+ if (!(e instanceof LabelMapUnreadable)) throw e;
175
+ writeAll(2, `\n${NAME}: ${e.message}\n`);
176
+ process.exitCode = 1;
177
+ return;
178
+ }
179
+ console.log(role === undefined ? JSON.stringify(roles) : roles[role]);
180
+ }
181
+
182
+ if (isCLI(import.meta.url)) main();