@feigi/fleet-ctl 3.24.1 → 3.24.3

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.
@@ -2,37 +2,36 @@
2
2
  // two exports, one per half of the same spawn. `gitEnv()` builds the env the
3
3
  // git child is given; `workspaceDirFromGitCommonDir()` turns what the most
4
4
  // common of those children answers with, `rev-parse --git-common-dir`, into
5
- // the workspace directory a run's files live under. The first half is #1599's
6
- // reasoning, below; the second is #1658's, beside its own function.
5
+ // the workspace directory a run's files live under. The first half's
6
+ // reasoning is below; the second's sits beside its own function.
7
7
  //
8
8
  // GIT_DIR and GIT_WORK_TREE outrank both the child's cwd and an explicit `-C`
9
- // argument — measured directly (#1599): a `git rev-parse`/`ls-files` call
9
+ // argument — measured directly: a `git rev-parse`/`ls-files` call
10
10
  // pointed at a repository via `cwd` or `-C` still answers for whichever
11
11
  // repository an ambient GIT_DIR or GIT_WORK_TREE names, silently, often at
12
- // exit 0. #1020 closed the identical class in every shell script under this
13
- // directory with one line, `unset GIT_DIR GIT_WORK_TREE`; there is no shell
14
- // to unset in here, so the child's env has to be built instead — and #1020's
15
- // own EXEMPT reasons for net.sh/worktree.sh ("a library... unset there would
12
+ // exit 0. The shell scripts under this directory close the identical class
13
+ // with one line, `unset GIT_DIR GIT_WORK_TREE`; there is no shell to unset in
14
+ // here, so the child's env has to be built instead — and the reasons
15
+ // net.sh/worktree.sh are exempt from that line ("a library... unset there would
16
16
  // reach back into the caller's environment") do not transfer: a spawned
17
17
  // child's env object is already private to it, never the calling process's.
18
18
  //
19
19
  // `fleet-state.mjs`'s `statePath()` and `ledger.mjs`'s tracker-query probe
20
20
  // each spell the same three lines inline — `{ ...process.env }` then two
21
- // `delete`s — predating this module, and #1599's own body cites exactly that
22
- // duplication as the reason a THIRD hand-spelled copy (its own measured
23
- // hazard, `ledger.mjs`'s `defaultLedgerPath()`) should not become a fourth.
21
+ // `delete`s — predating this module, and that duplication is exactly the
22
+ // reason a THIRD hand-spelled copy (the hazard measured here, `ledger.mjs`'s
23
+ // `defaultLedgerPath()`) should not become a fourth.
24
24
  // A shared helper also turns "does this call scrub the ambient vars" back
25
25
  // into a one-name grep, `gitEnv(`, the way `unset GIT_DIR GIT_WORK_TREE` is
26
- // one for shell — see `ambient-git-vars-mjs-prose.test.mjs`.
26
+ // one for shell.
27
27
  //
28
28
  // The two pre-existing inline sites are deliberately NOT migrated to call
29
- // this. Neither is in #1599's scope — its own body excludes
30
- // `fleet-state.mjs`'s `statePath()` by name (already fixed and covered, by
31
- // PR #1598), and `ledger.mjs`'s tracker-query scrub is likewise already
32
- // measured and covered (`ledger.test.mjs`, "an inherited GIT_DIR or GH_REPO
33
- // cannot retarget the query…") — and touching either to satisfy a detector
34
- // would be churn with no behavioural change. `ambient-git-vars-mjs-prose.test.mjs`
35
- // carries both of them by name instead of by import.
29
+ // this. Both are already fixed and covered by tests of their own —
30
+ // `fleet-state.mjs`'s `statePath()`, and `ledger.mjs`'s tracker-query scrub
31
+ // ("an inherited GIT_DIR or GH_REPO cannot retarget the query…") — and
32
+ // touching either to satisfy a detector would be churn with no behavioural
33
+ // change. The suite's census of ambient-var scrubs carries both of them by
34
+ // name instead of by import.
36
35
 
37
36
  import { realpathSync } from "node:fs";
38
37
  import { dirname, resolve } from "node:path";
@@ -65,11 +64,11 @@ export function gitEnv(overrides = {}, base = process.env) {
65
64
  // from the checkout root agree about the run's single ledger, its single
66
65
  // heartbeat and its single board.
67
66
  //
68
- // Three callers hand-spelled that resolution, one apiece, before #1658:
67
+ // Three callers hand-spelled that resolution, one apiece, before this function:
69
68
  // `ledger.mjs`'s `defaultLedgerPath()`, `fleet-state.mjs`'s `statePath()` and
70
69
  // `board.mjs`'s `resolveCockpitInstance()` — and `fleet-state.mjs`'s own
71
70
  // comment had already written down the trigger ("if a third file ever needs
72
- // this, the resolution itself should move"), which #1656's addition tripped.
71
+ // this, the resolution itself should move"), which the third caller's arrival tripped.
73
72
  // What is NOT shared is the part each caller owns: the filename it joins on
74
73
  // (`ledger.md`, `heartbeat.json`, `.fleet`), the wording of the warning it
75
74
  // degrades with, and what its own degraded answer is. Hence the seam: this
@@ -100,9 +99,9 @@ export function gitEnv(overrides = {}, base = process.env) {
100
99
  * than a path; a trailing newline riding on a real answer would be discarded
101
100
  * by `dirname()` anyway, together with the rest of the final segment.
102
101
  *
103
- * `canonicalise` is OPT-IN, and deliberately so (#1658). Only `board.mjs`
102
+ * `canonicalise` is OPT-IN, and deliberately so. Only `board.mjs`
104
103
  * takes it: a symlinked route to one workspace derives a SECOND port and a
105
- * second state directory for a cockpit already being served (#1582), so the
104
+ * second state directory for a cockpit already being served, so the
106
105
  * cockpit's key has to be the canonical form. `ledger.mjs` and
107
106
  * `fleet-state.mjs` do not — both PRINT the path they resolve (the ledger in
108
107
  * `check`'s JSON, both in their degrade warnings), and realpath would change
@@ -7,21 +7,21 @@
7
7
  // with it. What the premise costs is a precondition: there has to be a `.git`
8
8
  // at or above the file. A checkout and a worktree both have one; a bare `git
9
9
  // archive` extraction does not. Review specialists used to measure the suite in
10
- // exactly such an extraction, which cost this repo 19 silent declines per run
11
- // (#1056); since that ticket the review snapshot is `git init`ed and committed
10
+ // exactly such an extraction, which cost this repo 19 silent declines per run;
11
+ // since then the review snapshot is `git init`ed and committed
12
12
  // at cut time, so the declines below are no longer the review's normal path.
13
13
  // They remain the answer for any OTHER repo-less tree — a hand-cut archive, a
14
14
  // tarball unpacked in CI — which is why the guard stays rather than becoming
15
15
  // dead weight.
16
16
  //
17
- // Before #1149 each file paid that cost as a bare module-scope `execFileSync`
17
+ // Before this module, each file paid that cost as a bare module-scope `execFileSync`
18
18
  // whose failure escaped. Node cannot attribute a throw during module
19
19
  // evaluation to any test, so it synthesised one entry at line 1 of the file and
20
20
  // the run showed a single failure in place of the file's real tests — a
21
21
  // diagnostic that reads like a regression in the tree under test rather than an
22
22
  // environment missing a repository.
23
23
  //
24
- // #1339 found the second way "there has to be a `.git`" is not the same
24
+ // There is a second way "there has to be a `.git`" is not the same
25
25
  // question as "there has to be THIS repository": git's discovery walk answers
26
26
  // with whatever working tree it finds first, and nothing about that answer
27
27
  // says it is fleet-plugin's own tree rather than an ambient repository the
@@ -33,11 +33,11 @@
33
33
  // through it.
34
34
  //
35
35
  // The first fix here compared the resolved root's OWN `.claude-plugin/
36
- // plugin.json` name against this file's — and #1354's review measured that a
36
+ // plugin.json` name against this file's — and a review measured that a
37
37
  // DIFFERENT checkout of this same plugin, sitting above some unrelated caller
38
38
  // directory, still passed: same name, wrong tree. The second fix required the
39
39
  // running script to be somewhere INSIDE the resolved root — and that review
40
- // measured it regresses #1339's OWN shape: pre-cutover, an installed copy
40
+ // measured it regresses the ambient-repository case's OWN shape: pre-cutover, an installed copy
41
41
  // under the harness's own plugin cache genuinely sat inside the operator's
42
42
  // dotfiles checkout, which was exactly the ambient repository the bug is about.
43
43
  // Containment is not identity either. What repoRoot now insists on is
@@ -46,10 +46,10 @@
46
46
  // must both be tracked by `root`'s OWN git (`git ls-files --error-unmatch`).
47
47
  // An installed plugin's cache directory sits inside the operator's dotfiles
48
48
  // checkout but is never committed there, so it fails; a real checkout, a
49
- // worktree, a `plugin/`-nested layout after #1336, and a vendored copy inside
49
+ // worktree, a `plugin/`-nested layout, and a vendored copy inside
50
50
  // a monorepo all pass, because in each of those the file genuinely IS part of
51
51
  // that repository's own tracked tree. The self-relative manifest lookup is
52
- // what survives #1336's planned re-nesting of the payload under `plugin/`: a
52
+ // what survived the payload's re-nesting under `plugin/`: a
53
53
  // hardcoded `root/.claude-plugin/plugin.json` breaks the moment the manifest
54
54
  // moves a level deeper, while `dirname(thisFile)/../.claude-plugin/
55
55
  // plugin.json` does not care where `root` (the git toplevel) ends up relative
@@ -68,14 +68,15 @@
68
68
  // binary at all. A repository may well be
69
69
  // present; what is missing is an answer. A
70
70
  // probe that could not look must never read as
71
- // an answer — that is #1149's own defect, and
72
- // buying a skip with it would reproduce it
73
- // inside its own fix. `repoRoot` THROWS here,
71
+ // an answer: buying a skip with it would
72
+ // reproduce that defect inside the guard
73
+ // written against it. `repoRoot` THROWS here,
74
74
  // which is the loud module-load failure the
75
- // pre-#1149 code produced for these.
75
+ // earlier bare-`execFileSync` code produced
76
+ // for these.
76
77
  // the root answers, but its identity, not non-emptiness, not name
77
78
  // own git does not TRACK this equality, and not mere containment either
78
- // file or this file's own (#1339, then #1354 twice): a root that
79
+ // file or this file's own (each measured failing): a root that
79
80
  // manifest merely names the same plugin, contains an
80
81
  // untracked copy, or answers non-empty for
81
82
  // some other reason, is still a stranger's
@@ -92,7 +93,7 @@
92
93
  // skipping; each caller's own non-vacuity
93
94
  // guard is what judges it. The
94
95
  // wrong-repository half of this used to live
95
- // here too, before #1339 moved it up into the
96
+ // here too, before it moved up into the
96
97
  // identity check above, where it can throw
97
98
  // loudly instead of waiting on each caller's
98
99
  // guard to notice.
@@ -131,9 +132,10 @@ const NO_REPOSITORY_ANYWHERE = /not a git repository \(or any /;
131
132
  * caller resolved. Relative to `cwd` would ask the wrong question, since
132
133
  * `cwd` is exactly the thing under test; relative to a resolved `root` would
133
134
  * have to guess how many levels separate the manifest from the git toplevel,
134
- * and #1336 is about to change that answer. This guesses nothing — wherever
135
- * this file is copied (a checkout, a worktree, an installed plugin cache, and
136
- * after #1336 a `plugin/` subdirectory), its own manifest is always exactly
135
+ * and the payload's re-nesting under `plugin/` already changed that answer
136
+ * once. This guesses nothing — wherever
137
+ * this file is copied (a checkout, a worktree, an installed plugin cache, or
138
+ * a `plugin/` subdirectory), its own manifest is always exactly
137
139
  * one directory up from it.
138
140
  */
139
141
  function ownManifestPath() {
@@ -180,7 +182,7 @@ export function ownPluginName() {
180
182
  * nearest the pathspec itself (measured: from an unrelated cwd, the same
181
183
  * absolute path is reported "outside repository at <that other repo>").
182
184
  *
183
- * GIT_DIR scrubbed (#1599, gitEnv()): measured, an ambient GIT_DIR answers
185
+ * GIT_DIR scrubbed (gitEnv()): measured, an ambient GIT_DIR answers
184
186
  * for a DIFFERENT repository regardless of `cwd` — `ls-files
185
187
  * --error-unmatch` on a path this file's OWN repository genuinely tracks
186
188
  * then exits 1 "did not match any file(s) known to git", a false negative
@@ -206,7 +208,7 @@ function isTrackedBy(root, path) {
206
208
  * than an ambient repository the caller's directory happened to nest under.
207
209
  *
208
210
  * Containment (is the running script somewhere INSIDE `root`?) was tried
209
- * first and is not enough — it regresses #1339's own measured shape. There,
211
+ * first and is not enough — it regresses the ambient-repository case's own measured shape. There,
210
212
  * pre-cutover, self was under the harness's own plugin cache at
211
213
  * `fleet-plugin/fleet/0.1.1/scripts/repo-root.mjs`, and `root` resolved to
212
214
  * that cache's own parent dotfiles directory, which genuinely CONTAINED self
@@ -218,7 +220,7 @@ function isTrackedBy(root, path) {
218
220
  * working tree is exactly as much a stranger as no copy at all. This also
219
221
  * accepts every tree that legitimately IS this file's own — this checkout, a
220
222
  * worktree, a
221
- * `plugin/`-nested layout after #1336, even a vendored copy inside a larger
223
+ * `plugin/`-nested layout, even a vendored copy inside a larger
222
224
  * monorepo — because in every one of those cases the file is actually
223
225
  * COMMITTED to that repository's index, which an ambient-but-unrelated
224
226
  * repository's cache directory never is.
@@ -286,13 +288,13 @@ function dotGitAtOrAbove(cwd) {
286
288
  *
287
289
  * A working tree that IS found is not returned on the strength of being
288
290
  * found — `assertOwnRoot` checks it is this plugin's own before it ever
289
- * reaches a caller (#1339). A non-empty wrong root throws exactly as loudly as
291
+ * reaches a caller. A non-empty wrong root throws exactly as loudly as
290
292
  * an unanswerable one; the old guard against it lived only in each caller's
291
293
  * non-vacuity check on `trackedShellScripts`, which a non-empty foreign
292
294
  * answer sailed straight through.
293
295
  */
294
296
  export function repoRoot(cwd) {
295
- // GIT_DIR/GIT_WORK_TREE scrubbed (#1599, gitEnv()): measured from a
297
+ // GIT_DIR/GIT_WORK_TREE scrubbed (gitEnv()): measured from a
296
298
  // subdirectory of a real working tree (the realistic shape — `cwd` here is
297
299
  // wherever the calling script happens to live, rarely the root itself) —
298
300
  // an ambient GIT_DIR alone answers `--show-toplevel` with `cwd` ITSELF, not
@@ -338,8 +340,8 @@ export function skipWithoutRepo(root, subject) {
338
340
  // file at the path, for any reader — rather than a failure to look: nothing
339
341
  // there at all (ENOENT); a file standing where one of the path's own
340
342
  // directories should be (ENOTDIR); and a symlink that loops, or chains past the
341
- // kernel's link limit (ELOOP), which no reader can ever open a file through
342
- // (#1950). `root` is git's own resolved toplevel, so every link counted toward
343
+ // kernel's link limit (ELOOP), which no reader can ever open a file through.
344
+ // `root` is git's own resolved toplevel, so every link counted toward
343
345
  // that limit is one inside the tracked path itself — a fact about the tree,
344
346
  // not about where the checkout sits.
345
347
  //
@@ -371,7 +373,7 @@ function isRegularFile(path) {
371
373
  * Every file tracked in the working tree at `root` that `pathspecs` match,
372
374
  * repo-relative — the one discovery rule behind all three exports below, so what
373
375
  * `root` must be and which repository answers cannot drift apart between
374
- * them (#1751). `caller` is the export's own name, for the refusal.
376
+ * them. `caller` is the export's own name, for the refusal.
375
377
  *
376
378
  * `root` must be a real root — call it only where `repoRoot` answered. A `null`
377
379
  * root is rejected rather than absorbed into an empty list: `execFileSync`
@@ -390,13 +392,13 @@ function isRegularFile(path) {
390
392
  * checked out on disk), a file standing where the path's own directory was.
391
393
  * Every caller reads each path it is handed, and one absent path in the answer
392
394
  * aborted that read with a raw ENOENT, leaving every real finding in every
393
- * other file unreported (#1910). Passing over it lets nothing ship unswept: a
395
+ * other file unreported. Passing over it lets nothing ship unswept: a
394
396
  * deletion that is committed does not ship, and one that is not is swept again
395
397
  * in any checkout that has the file; a link with no file behind it has no text
396
398
  * to sweep. A path the probe could not look at is not one of these — it
397
399
  * throws, as NO_REGULAR_FILE_THERE says.
398
400
  *
399
- * GIT_DIR scrubbed (#1599, gitEnv()): measured, an ambient GIT_DIR silently
401
+ * GIT_DIR scrubbed (gitEnv()): measured, an ambient GIT_DIR silently
400
402
  * substitutes a DIFFERENT repository's tracked list for `root`'s own — the
401
403
  * caller's non-vacuity guard cannot see this, since the wrong list is
402
404
  * routinely non-empty. GIT_WORK_TREE is inert here (measured, for `*.sh` and
@@ -465,7 +467,7 @@ const NODE_SHEBANG = /^#!\s*(?:\S*\/)?(?:env(?:\s+(?:-(?:u|-unset|C|-chdir)(?:=\
465
467
  const SHEBANG_BYTES = 256;
466
468
 
467
469
  // The most of a first line ever read, and the length at which one is not a
468
- // node shebang (#1941). Reading on to the end of the line however long read a
470
+ // node shebang. Reading on to the end of the line however long read a
469
471
  // tracked `#!` file holding no newline into memory whole to answer a boolean —
470
472
  // measured, 300 MiB of one peaked above 1.1 GiB, and one past the longest
471
473
  // string V8 builds (~512 MiB) threw ERR_STRING_TOO_LONG out of the whole
@@ -476,9 +478,10 @@ const SHEBANG_BYTES = 256;
476
478
  // Linux, on a prefix naming node — is one no author writes.
477
479
  //
478
480
  // A cap, not a verdict on the bytes before it: those are not judged at all,
479
- // so this is never the prefix verdict #1887 retired. Refused rather than
481
+ // so this is never a prefix verdict, the kind hasNodeShebang() refuses to
482
+ // give. Refused rather than
480
483
  // thrown, because one pathological tracked file must not abort every sweep's
481
- // listing (#1910); rather than listed, because a sweep reads each listed file
484
+ // listing; rather than listed, because a sweep reads each listed file
482
485
  // whole, which would move the unbounded read, not remove it.
483
486
  const SHEBANG_MAX_BYTES = 4096;
484
487
 
@@ -488,7 +491,7 @@ const SHEBANG_MAX_BYTES = 4096;
488
491
  * first read and grows past it only for a longer line, never past
489
492
  * SHEBANG_MAX_BYTES: a first line that long or longer, newline not counted, is
490
493
  * not one, and nothing past the cap is read. A verdict on the prefix one read
491
- * holds parts from the line's own both ways (#1887): it misses a `node` past
494
+ * holds parts from the line's own both ways: it misses a `node` past
492
495
  * its end, reads `nodemon` cut after its `node` as `node` at the end of the
493
496
  * line, and decodes a character it cuts in half as U+FFFD. A file that does
494
497
  * not open with `#!` is decided on that first read however long its first
@@ -530,7 +533,7 @@ function hasNodeShebang(path, buf) {
530
533
  * Every tracked file this repository ships that the consumer's own `node`
531
534
  * executes, in the working tree at `root`, repo-relative: each `*.mjs`, and
532
535
  * any other file whose first line is a node shebang — the extensionless
533
- * entrypoints `fleet-run`, `fleet-bootstrap` and `fleet-provenance` (#1855).
536
+ * entrypoints `fleet-run`, `fleet-bootstrap` and `fleet-provenance`.
534
537
  * A shebang decides, never an extension alone: `plugin/workflows/*.js` is ESM
535
538
  * a harness runs and plain node never loads, and carries none. Test files —
536
539
  * `*.test.mjs`, the one naming this repository gives them — are not shipped,