@feigi/fleet-ctl 0.0.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.
Files changed (245) hide show
  1. package/.claude-plugin/plugin.json +9 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +18 -0
  4. package/agents/fleet-finisher.agent.md +7 -0
  5. package/agents/fleet-implementer-alt.agent.md +210 -0
  6. package/agents/fleet-implementer.agent.md +210 -0
  7. package/agents/fleet-merge-bot.agent.md +7 -0
  8. package/agents/fleet-review-comments.agent.md +40 -0
  9. package/agents/fleet-review-correctness.agent.md +43 -0
  10. package/agents/fleet-review-runner.agent.md +73 -0
  11. package/agents/fleet-review-silent-failure.agent.md +49 -0
  12. package/agents/fleet-review-simplify.agent.md +46 -0
  13. package/agents/fleet-review-snapshot.agent.md +24 -0
  14. package/agents/fleet-review-tests.agent.md +46 -0
  15. package/agents/fleet-review-types.agent.md +41 -0
  16. package/agents/fleet-review-verifier.agent.md +29 -0
  17. package/commands/review-and-fix.md +98 -0
  18. package/commands/run-merge-bot.md +357 -0
  19. package/commands/run-team-help.md +17 -0
  20. package/package.json +23 -0
  21. package/scripts/agent-test-dir-prose.test.mjs +59 -0
  22. package/scripts/agent-test.test.mjs +1636 -0
  23. package/scripts/ambient-git-vars-mjs-prose.test.mjs +354 -0
  24. package/scripts/ambient-git-vars-prose.test.mjs +192 -0
  25. package/scripts/ancestry-check-position-prose.test.mjs +175 -0
  26. package/scripts/apply-ruleset.test.mjs +420 -0
  27. package/scripts/arg-header-probes-prose.test.mjs +393 -0
  28. package/scripts/arg.mjs +600 -0
  29. package/scripts/arg.test.mjs +1354 -0
  30. package/scripts/board-cli.test.mjs +694 -0
  31. package/scripts/board-identity.test.mjs +429 -0
  32. package/scripts/board-liveness-banner.test.mjs +119 -0
  33. package/scripts/board-prev-shape.test.mjs +229 -0
  34. package/scripts/board-tryparse-null.test.mjs +119 -0
  35. package/scripts/board.html +471 -0
  36. package/scripts/board.mjs +2037 -0
  37. package/scripts/board.test.mjs +3086 -0
  38. package/scripts/brief-after-cut-prose.test.mjs +53 -0
  39. package/scripts/candidates-exit3-prose.test.mjs +302 -0
  40. package/scripts/candidates.mjs +674 -0
  41. package/scripts/candidates.test.mjs +2101 -0
  42. package/scripts/caveat-unification-prose.test.mjs +98 -0
  43. package/scripts/ci-comment-rot-prose.test.mjs +2025 -0
  44. package/scripts/ci-completes-premise-prose.test.mjs +257 -0
  45. package/scripts/ci-state-prose.test.mjs +113 -0
  46. package/scripts/ci-state.mjs +761 -0
  47. package/scripts/ci-state.test.mjs +1640 -0
  48. package/scripts/ci-vacuous-green.test.mjs +368 -0
  49. package/scripts/citation-sweep-prose.test.mjs +1572 -0
  50. package/scripts/claim-lifecycle.test.mjs +185 -0
  51. package/scripts/claim-ticket.sh +417 -0
  52. package/scripts/claim-ticket.test.mjs +1121 -0
  53. package/scripts/closing-keyword-prose.test.mjs +193 -0
  54. package/scripts/cockpit-launch-idempotent-prose.test.mjs +165 -0
  55. package/scripts/cockpit-tick-nonblocking.test.mjs +210 -0
  56. package/scripts/compute-board.mjs +579 -0
  57. package/scripts/compute-board.test.mjs +1060 -0
  58. package/scripts/compute-spend.mjs +329 -0
  59. package/scripts/compute-spend.test.mjs +451 -0
  60. package/scripts/cross-repo-citation-prose.test.mjs +156 -0
  61. package/scripts/cwd-isolation-pins.mjs +83 -0
  62. package/scripts/dedupe-guard-prose.test.mjs +243 -0
  63. package/scripts/derive-testcmd.sh +239 -0
  64. package/scripts/derive-testcmd.test.mjs +380 -0
  65. package/scripts/diff-stats.mjs +231 -0
  66. package/scripts/diff-stats.test.mjs +408 -0
  67. package/scripts/dispatch-block-golden-prose.test.mjs +1024 -0
  68. package/scripts/dispatch-block-pins-prose.test.mjs +615 -0
  69. package/scripts/drop-merged-label.sh +173 -0
  70. package/scripts/drop-merged-label.test.mjs +480 -0
  71. package/scripts/expected-jobs-prose.test.mjs +80 -0
  72. package/scripts/filing-bar-seat-prose.test.mjs +242 -0
  73. package/scripts/filing-claim-bar-prose.test.mjs +166 -0
  74. package/scripts/finisher-dispatch-premise-prose.test.mjs +312 -0
  75. package/scripts/finisher-halt-prose.test.mjs +106 -0
  76. package/scripts/finisher-name-prose.test.mjs +134 -0
  77. package/scripts/finisher-own-tree-prose.test.mjs +285 -0
  78. package/scripts/finisher-pin-race-prose.test.mjs +339 -0
  79. package/scripts/fix-applier-correction-rules-prose.test.mjs +201 -0
  80. package/scripts/fix-applier-result-file-prose.test.mjs +100 -0
  81. package/scripts/fleet-bootstrap +155 -0
  82. package/scripts/fleet-heartbeat.mjs +272 -0
  83. package/scripts/fleet-heartbeat.test.mjs +450 -0
  84. package/scripts/fleet-provenance +207 -0
  85. package/scripts/fleet-provenance.test.mjs +64 -0
  86. package/scripts/fleet-run +148 -0
  87. package/scripts/fleet-run.test.mjs +90 -0
  88. package/scripts/fleet-state.mjs +400 -0
  89. package/scripts/fleet-state.test.mjs +373 -0
  90. package/scripts/fleet-tick-prose.test.mjs +299 -0
  91. package/scripts/fleet-tick.mjs +832 -0
  92. package/scripts/fleet-tick.test.mjs +1332 -0
  93. package/scripts/force-with-lease-reason-prose.test.mjs +184 -0
  94. package/scripts/frontmatter-allowlist.json +64 -0
  95. package/scripts/frontmatter-check.mjs +256 -0
  96. package/scripts/frontmatter-check.test.mjs +436 -0
  97. package/scripts/git-env.mjs +124 -0
  98. package/scripts/git-env.test.mjs +149 -0
  99. package/scripts/git-status-untracked-mode-sweep.test.mjs +216 -0
  100. package/scripts/gone-walk.test.mjs +213 -0
  101. package/scripts/gp-sep-invariant-prose.test.mjs +188 -0
  102. package/scripts/head-moved-after-label-prose.test.mjs +233 -0
  103. package/scripts/immutable-body-claim-prose.test.mjs +413 -0
  104. package/scripts/implementer-model-tier.test.mjs +643 -0
  105. package/scripts/inflight-citation-prose.test.mjs +144 -0
  106. package/scripts/inflight-exit2-prose.test.mjs +81 -0
  107. package/scripts/inflight-probe-guard-prose.test.mjs +109 -0
  108. package/scripts/inflight-scan-scope-prose.test.mjs +57 -0
  109. package/scripts/inflight.sh +1106 -0
  110. package/scripts/inflight.test.mjs +2984 -0
  111. package/scripts/injection-control-prose.test.mjs +404 -0
  112. package/scripts/install-root-audit.test.mjs +464 -0
  113. package/scripts/instrument-check-prose.test.mjs +235 -0
  114. package/scripts/instruments.sh +394 -0
  115. package/scripts/instruments.test.mjs +787 -0
  116. package/scripts/issue-tracker-prose.test.mjs +71 -0
  117. package/scripts/json.sh +248 -0
  118. package/scripts/json.test.mjs +364 -0
  119. package/scripts/ledger-dispatch.test.mjs +516 -0
  120. package/scripts/ledger-grammar.mjs +85 -0
  121. package/scripts/ledger-grammar.test.mjs +142 -0
  122. package/scripts/ledger-read-require-file.test.mjs +197 -0
  123. package/scripts/ledger.mjs +1753 -0
  124. package/scripts/ledger.test.mjs +3554 -0
  125. package/scripts/line-distance-prose.test.mjs +245 -0
  126. package/scripts/liveness-rationale-prose.test.mjs +83 -0
  127. package/scripts/locale-pin-prose.test.mjs +189 -0
  128. package/scripts/member-outcome-prose.test.mjs +167 -0
  129. package/scripts/member-outcomes-header.test.mjs +148 -0
  130. package/scripts/member-outcomes-prose.test.mjs +63 -0
  131. package/scripts/member-outcomes.mjs +231 -0
  132. package/scripts/member-outcomes.test.mjs +507 -0
  133. package/scripts/member-prompt-prose.test.mjs +161 -0
  134. package/scripts/member-record.mjs +605 -0
  135. package/scripts/member-record.test.mjs +516 -0
  136. package/scripts/member-write-guard.mjs +279 -0
  137. package/scripts/member-write-guard.test.mjs +211 -0
  138. package/scripts/merge-commit-probe-prose.test.mjs +122 -0
  139. package/scripts/merge-gate.mjs +262 -0
  140. package/scripts/merge-gate.test.mjs +613 -0
  141. package/scripts/muted-git-guard-sweep.test.mjs +493 -0
  142. package/scripts/net-ssh-precedence-prose.test.mjs +91 -0
  143. package/scripts/net-watchdog-prose.test.mjs +79 -0
  144. package/scripts/net.sh +409 -0
  145. package/scripts/net.test.mjs +211 -0
  146. package/scripts/no-ci-gate-prose.test.mjs +108 -0
  147. package/scripts/no-undo-audit.sh +1134 -0
  148. package/scripts/no-undo-audit.test.mjs +3965 -0
  149. package/scripts/no-wave.test.mjs +138 -0
  150. package/scripts/node-floor-sweep.test.mjs +611 -0
  151. package/scripts/pointer-target-prose.test.mjs +186 -0
  152. package/scripts/pr-overlap.mjs +417 -0
  153. package/scripts/pr-overlap.test.mjs +695 -0
  154. package/scripts/printf-die-sweep.test.mjs +384 -0
  155. package/scripts/prompt-renderer.mjs +39 -0
  156. package/scripts/prompt-renderer.test.mjs +68 -0
  157. package/scripts/prose-pin.mjs +808 -0
  158. package/scripts/prose-pin.test.mjs +1034 -0
  159. package/scripts/prove-merge.sh +228 -0
  160. package/scripts/prove-merge.test.mjs +995 -0
  161. package/scripts/pull-table-relabel-prose.test.mjs +60 -0
  162. package/scripts/quiet-payload-prose.test.mjs +222 -0
  163. package/scripts/reap.sh +1768 -0
  164. package/scripts/reap.test.mjs +4395 -0
  165. package/scripts/reaping-prose.test.mjs +159 -0
  166. package/scripts/refuter-scratch-prose.test.mjs +135 -0
  167. package/scripts/release-label-required-prose.test.mjs +71 -0
  168. package/scripts/release-label-split-prose.test.mjs +169 -0
  169. package/scripts/release-ticket.sh +1716 -0
  170. package/scripts/release-ticket.test.mjs +5106 -0
  171. package/scripts/renovate-release-contract.test.mjs +379 -0
  172. package/scripts/repo-root.mjs +544 -0
  173. package/scripts/repo-root.test.mjs +873 -0
  174. package/scripts/reporter-output-rule-prose.test.mjs +208 -0
  175. package/scripts/review-agent-report-only.test.mjs +49 -0
  176. package/scripts/review-core-cwd-isolation.test.mjs +374 -0
  177. package/scripts/review-core-reads.test.mjs +478 -0
  178. package/scripts/review-core-refuter-scratch.test.mjs +148 -0
  179. package/scripts/review-core-snapshot-path.test.mjs +777 -0
  180. package/scripts/review-core-specialist-scratch.test.mjs +189 -0
  181. package/scripts/review-core-testcmd.test.mjs +288 -0
  182. package/scripts/review-core-unrun.test.mjs +530 -0
  183. package/scripts/review-core-unverified-discriminant.test.mjs +208 -0
  184. package/scripts/review-core.mjs +1028 -0
  185. package/scripts/review-eval-resolver-path.test.mjs +55 -0
  186. package/scripts/review-eval.mjs +197 -0
  187. package/scripts/review-host-fixture.mjs +73 -0
  188. package/scripts/review-in-run-retry.test.mjs +187 -0
  189. package/scripts/review-no-vendor-dispatch.test.mjs +45 -0
  190. package/scripts/review-path-default.test.mjs +796 -0
  191. package/scripts/review-runner-spawns.test.mjs +93 -0
  192. package/scripts/review-runner.test.mjs +155 -0
  193. package/scripts/review-tier-audit.test.mjs +140 -0
  194. package/scripts/run-artifact-pr-prose.test.mjs +341 -0
  195. package/scripts/run-merge-bot-prose.test.mjs +1391 -0
  196. package/scripts/scratch-partition-invariant-prose.test.mjs +74 -0
  197. package/scripts/scripts-path-citation-sweep.test.mjs +73 -0
  198. package/scripts/section-between-guard-prose.test.mjs +378 -0
  199. package/scripts/select-dimensions.test.mjs +674 -0
  200. package/scripts/shared-refusal.test.mjs +388 -0
  201. package/scripts/shell-traps-prose.test.mjs +507 -0
  202. package/scripts/shortlist.mjs +355 -0
  203. package/scripts/shortlist.test.mjs +366 -0
  204. package/scripts/slow-transport.mjs +72 -0
  205. package/scripts/snapshot-repo.test.mjs +772 -0
  206. package/scripts/snapshot-runner-audience-prose.test.mjs +129 -0
  207. package/scripts/spend-view.test.mjs +312 -0
  208. package/scripts/staleness-qualifier-prose.test.mjs +251 -0
  209. package/scripts/staleness-verdict-prose.test.mjs +142 -0
  210. package/scripts/staleness.mjs +414 -0
  211. package/scripts/staleness.test.mjs +893 -0
  212. package/scripts/stalled-member-liveness-prose.test.mjs +219 -0
  213. package/scripts/stash-prohibition-prose.test.mjs +313 -0
  214. package/scripts/strip-comments.mjs +44 -0
  215. package/scripts/tier-check.mjs +468 -0
  216. package/scripts/tier-check.test.mjs +726 -0
  217. package/scripts/tier-guard-gate-prose.test.mjs +216 -0
  218. package/scripts/tier-outcomes-header.test.mjs +586 -0
  219. package/scripts/tier-outcomes.mjs +441 -0
  220. package/scripts/tier-outcomes.test.mjs +342 -0
  221. package/scripts/tier-roles.mjs +250 -0
  222. package/scripts/tier-roles.test.mjs +316 -0
  223. package/scripts/tracker-block-copy-prose.test.mjs +288 -0
  224. package/scripts/triage-labels-gloss-prose.test.mjs +97 -0
  225. package/scripts/unattended-git-sweep.test.mjs +142 -0
  226. package/scripts/verify-sha-exit2-prose.test.mjs +269 -0
  227. package/scripts/verify-sha.sh +117 -0
  228. package/scripts/verify-sha.test.mjs +693 -0
  229. package/scripts/watcher-degraded-block.test.mjs +372 -0
  230. package/scripts/watcher-key-prose.test.mjs +106 -0
  231. package/scripts/within-run-pair-prose.test.mjs +208 -0
  232. package/scripts/worktree-audit.sh +482 -0
  233. package/scripts/worktree-audit.test.mjs +1407 -0
  234. package/scripts/worktree-head-prose.test.mjs +276 -0
  235. package/scripts/worktree-listing-sweep.test.mjs +217 -0
  236. package/scripts/worktree-model-prose.test.mjs +216 -0
  237. package/scripts/worktree.sh +470 -0
  238. package/skills/next-ticket/SKILL.md +138 -0
  239. package/skills/run-team/SKILL.md +3603 -0
  240. package/skills/run-team/references/ci-and-staleness.md +75 -0
  241. package/skills/run-team/references/correction-tickets.md +37 -0
  242. package/skills/run-team/references/isolation.md +23 -0
  243. package/skills/run-team/references/member-lifecycle.md +73 -0
  244. package/skills/run-team/references/reaping.md +73 -0
  245. package/skills/sizing-a-ticket/SKILL.md +39 -0
@@ -0,0 +1,544 @@
1
+ // The ambient-working-tree precondition the sweep suites share, in one place.
2
+ //
3
+ // Four test files here derive their subject list by asking git what ships —
4
+ // the repository root, then the tracked `*.sh` under it. That premise is
5
+ // deliberate and unchanged: an untracked scratch script is not what ships, and
6
+ // a fleet script that moves out of its directory must not fall out of a sweep
7
+ // with it. What the premise costs is a precondition: there has to be a `.git`
8
+ // at or above the file. A checkout and a worktree both have one; a bare `git
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
12
+ // at cut time, so the declines below are no longer the review's normal path.
13
+ // They remain the answer for any OTHER repo-less tree — a hand-cut archive, a
14
+ // tarball unpacked in CI — which is why the guard stays rather than becoming
15
+ // dead weight.
16
+ //
17
+ // Before #1149 each file paid that cost as a bare module-scope `execFileSync`
18
+ // whose failure escaped. Node cannot attribute a throw during module
19
+ // evaluation to any test, so it synthesised one entry at line 1 of the file and
20
+ // the run showed a single failure in place of the file's real tests — a
21
+ // diagnostic that reads like a regression in the tree under test rather than an
22
+ // environment missing a repository.
23
+ //
24
+ // #1339 found the second way "there has to be a `.git`" is not the same
25
+ // question as "there has to be THIS repository": git's discovery walk answers
26
+ // with whatever working tree it finds first, and nothing about that answer
27
+ // says it is fleet-plugin's own tree rather than an ambient repository the
28
+ // caller's directory happens to nest under (an installed plugin copy —
29
+ // pre-cutover, under the harness's own plugin cache — has no `.git` of its
30
+ // own; the walk keeps going and can land on the operator's dotfiles repo).
31
+ // The old guard against that was non-vacuity — an empty tracked-script list
32
+ // is suspicious — and a wrong root that is non-empty sailed straight
33
+ // through it.
34
+ //
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
37
+ // DIFFERENT checkout of this same plugin, sitting above some unrelated caller
38
+ // directory, still passed: same name, wrong tree. The second fix required the
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
41
+ // under the harness's own plugin cache genuinely sat inside the operator's
42
+ // dotfiles checkout, which was exactly the ambient repository the bug is about.
43
+ // Containment is not identity either. What repoRoot now insists on is
44
+ // TRACKED-NESS: the running script (this very file, realpath'd) and its own
45
+ // manifest (found self-relatively, never by guessing a depth below the root)
46
+ // must both be tracked by `root`'s OWN git (`git ls-files --error-unmatch`).
47
+ // An installed plugin's cache directory sits inside the operator's dotfiles
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
50
+ // a monorepo all pass, because in each of those the file genuinely IS part of
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
53
+ // hardcoded `root/.claude-plugin/plugin.json` breaks the moment the manifest
54
+ // moves a level deeper, while `dirname(thisFile)/../.claude-plugin/
55
+ // plugin.json` does not care where `root` (the git toplevel) ends up relative
56
+ // to that — it only has to still be tracked there, which `isTrackedBy` checks
57
+ // directly.
58
+ //
59
+ // THE CONDITIONS BELOW MUST NOT MERGE. `repoRoot` answers `null` for exactly
60
+ // one of them, THROWS for two more, and only ever returns a path for the last:
61
+ //
62
+ // there is no working tree at no `.git` at or above the file, and git
63
+ // or above the file agrees. The environment fails the file's
64
+ // precondition, and this is the ONLY condition
65
+ // that may skip.
66
+ // git cannot answer the a `.git` git refuses to read, a stale
67
+ // question worktree pointer, a bare repository, no git
68
+ // binary at all. A repository may well be
69
+ // present; what is missing is an answer. A
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,
74
+ // which is the loud module-load failure the
75
+ // pre-#1149 code produced for these.
76
+ // the root answers, but its identity, not non-emptiness, not name
77
+ // 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
+ // manifest merely names the same plugin, contains an
80
+ // untracked copy, or answers non-empty for
81
+ // some other reason, is still a stranger's
82
+ // tree unless its OWN git has this file (and
83
+ // its manifest) committed to its index.
84
+ // `repoRoot` THROWS here too, naming the
85
+ // rejected root and the untracked path.
86
+ // the root answers, and it IS a real failure — a broken glob or path join
87
+ // this plugin's own, but the inside a tree that genuinely is this
88
+ // list of tracked files is plugin's own. `trackedPaths`,
89
+ // empty `trackedShellScripts` and
90
+ // `trackedNodeScripts` are therefore free to
91
+ // return an empty array and say nothing about
92
+ // skipping; each caller's own non-vacuity
93
+ // guard is what judges it. The
94
+ // wrong-repository half of this used to live
95
+ // here too, before #1339 moved it up into the
96
+ // identity check above, where it can throw
97
+ // loudly instead of waiting on each caller's
98
+ // guard to notice.
99
+ //
100
+ // Zero deps: `node --test plugin/scripts/repo-root.test.mjs`.
101
+
102
+ import { execFileSync, spawnSync } from "node:child_process";
103
+ import { gitEnv } from "./git-env.mjs";
104
+ import { closeSync, existsSync, openSync, readFileSync, readSync, realpathSync, statSync } from "node:fs";
105
+ import { dirname, join } from "node:path";
106
+ import { fileURLToPath } from "node:url";
107
+
108
+ // git's message for a discovery walk that reached the top without finding a
109
+ // repository. Measured, git 2.50.1 (Apple Git-155): `fatal: not a git
110
+ // repository (or any of the parent directories): .git`. git carries a second
111
+ // wording for the walk that stops at a filesystem boundary — read out of the
112
+ // binary, `strings -a "$(git --exec-path)/git-rev-parse" | grep 'not a git
113
+ // repository (or any'` returns that one alongside it (the `git` on `PATH` is a
114
+ // shim here and carries neither) — so the match is anchored on the prefix the
115
+ // two share rather than on the form this machine happens to print.
116
+ //
117
+ // It deliberately does NOT match `fatal: not a git repository: <path>`, which
118
+ // is a `.git` naming a gitdir that is not there — a broken pointer, not an
119
+ // absent tree, and one of the conditions that must be loud.
120
+ //
121
+ // `LC_ALL=C` on the spawn is what keeps this English. Apple's git ships no
122
+ // message catalogues, so it reads the same under any locale here (measured
123
+ // under `de_DE.UTF-8` and `fr_FR.UTF-8`); a git built with NLS does not, and an
124
+ // unmatched message would turn the extraction case from a skip into a throw.
125
+ // Same pin, and same reason, as the `LC_ALL=C` in json.sh.
126
+ const NO_REPOSITORY_ANYWHERE = /not a git repository \(or any /;
127
+
128
+ /**
129
+ * This plugin's own manifest path: `../.claude-plugin/plugin.json`, relative
130
+ * to repo-root.mjs's own location, not to `cwd` and not to a `root` some
131
+ * caller resolved. Relative to `cwd` would ask the wrong question, since
132
+ * `cwd` is exactly the thing under test; relative to a resolved `root` would
133
+ * 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
137
+ * one directory up from it.
138
+ */
139
+ function ownManifestPath() {
140
+ return join(dirname(fileURLToPath(import.meta.url)), "..", ".claude-plugin", "plugin.json");
141
+ }
142
+
143
+ /**
144
+ * This plugin's own `name`, read from `ownManifestPath()`.
145
+ *
146
+ * Guarded rather than a bare `JSON.parse(readFileSync(...))`: a missing or
147
+ * malformed manifest here is the same class of environment fault the rest of
148
+ * this module goes to lengths to make legible, and every caller of `repoRoot`
149
+ * reaches this at module scope — an unguarded throw would read as an
150
+ * `ENOENT` or a `SyntaxError` at line 1 of whichever sweep imported it, with
151
+ * nothing to say the failure was about identity verification.
152
+ *
153
+ * Exported so the regression tests can build a fixture that matches without
154
+ * duplicating (or hardcoding) the name themselves.
155
+ */
156
+ export function ownPluginName() {
157
+ const manifestPath = ownManifestPath();
158
+ let manifest;
159
+ try {
160
+ manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
161
+ } catch (e) {
162
+ throw new Error(
163
+ `${manifestPath} (this plugin's own manifest) could not be read (${e.message}) — `
164
+ + "repoRoot cannot verify identity without it",
165
+ );
166
+ }
167
+ if (typeof manifest.name !== "string" || manifest.name === "") {
168
+ throw new Error(
169
+ `${manifestPath} (this plugin's own manifest) has no usable "name" — repoRoot cannot verify identity against it`,
170
+ );
171
+ }
172
+ return manifest.name;
173
+ }
174
+
175
+ /**
176
+ * `path` is tracked by the git repository at `root` — `git ls-files
177
+ * --error-unmatch` exits 0 only then. Runs with `cwd: root` (not `-C`, to
178
+ * match this file's other spawns) because git resolves a pathspec against
179
+ * whatever repository the WORKING DIRECTORY belongs to, not the repository
180
+ * nearest the pathspec itself (measured: from an unrelated cwd, the same
181
+ * absolute path is reported "outside repository at <that other repo>").
182
+ *
183
+ * GIT_DIR scrubbed (#1599, gitEnv()): measured, an ambient GIT_DIR answers
184
+ * for a DIFFERENT repository regardless of `cwd` — `ls-files
185
+ * --error-unmatch` on a path this file's OWN repository genuinely tracks
186
+ * then exits 1 "did not match any file(s) known to git", a false negative
187
+ * that sends `assertOwnRoot` below into refusing a root this plugin's own
188
+ * git ACTUALLY tracks.
189
+ *
190
+ * GIT_WORK_TREE scrubbed too, and NOT inert here despite being inert for
191
+ * `trackedFiles`' relative globs below — `path` here is always
192
+ * `realpathSync`'d, i.e. absolute, and git resolves an absolute pathspec
193
+ * against the WORK TREE. Measured: an ambient GIT_WORK_TREE naming a
194
+ * different repository turns this call into `fatal: <path> is outside
195
+ * repository at <ambient path>`, exit 128 — the same false-negative
196
+ * consequence as the GIT_DIR case above, by a different route.
197
+ */
198
+ function isTrackedBy(root, path) {
199
+ const r = spawnSync("git", ["ls-files", "--error-unmatch", "--", path],
200
+ { cwd: root, encoding: "utf8", env: gitEnv({ LC_ALL: "C" }) });
201
+ return r.status === 0;
202
+ }
203
+
204
+ /**
205
+ * `root` is a git working tree; this asserts it is THIS plugin's own rather
206
+ * than an ambient repository the caller's directory happened to nest under.
207
+ *
208
+ * Containment (is the running script somewhere INSIDE `root`?) was tried
209
+ * first and is not enough — it regresses #1339's own measured shape. There,
210
+ * pre-cutover, self was under the harness's own plugin cache at
211
+ * `fleet-plugin/fleet/0.1.1/scripts/repo-root.mjs`, and `root` resolved to
212
+ * that cache's own parent dotfiles directory, which genuinely CONTAINED self
213
+ * (the installed copy sat inside the operator's dotfiles checkout) — but
214
+ * that directory's git did not TRACK the cache subdirectory, so it was not
215
+ * the tree this file ships in. The check is therefore TRACKED-NESS: does
216
+ * `root`'s own git know this file (`git
217
+ * ls-files --error-unmatch`)? An untracked copy lying inside an ambient
218
+ * working tree is exactly as much a stranger as no copy at all. This also
219
+ * accepts every tree that legitimately IS this file's own — this checkout, a
220
+ * worktree, a
221
+ * `plugin/`-nested layout after #1336, even a vendored copy inside a larger
222
+ * monorepo — because in every one of those cases the file is actually
223
+ * COMMITTED to that repository's index, which an ambient-but-unrelated
224
+ * repository's cache directory never is.
225
+ *
226
+ * Realpath'd on both sides so a symlinked checkout is not rejected. Anything
227
+ * that fails throws, naming the rejected root and the path it does not
228
+ * track — a caller must never receive a foreign root as though it were a
229
+ * usable answer.
230
+ */
231
+ function assertOwnRoot(root) {
232
+ const name = ownPluginName();
233
+ const self = realpathSync(fileURLToPath(import.meta.url));
234
+ if (!isTrackedBy(root, self)) {
235
+ throw new Error(
236
+ `${root} is a git working tree, but does not TRACK ${self} — an untracked copy lying inside an ambient `
237
+ + `working tree (its own plugin.json even naming ${JSON.stringify(name)}) is not that tree's own; refusing `
238
+ + "to answer about a stranger's tree rather than return a foreign root",
239
+ );
240
+ }
241
+ const manifestPath = realpathSync(ownManifestPath());
242
+ if (!isTrackedBy(root, manifestPath)) {
243
+ throw new Error(
244
+ `${root} is a git working tree that tracks ${self}, but not this plugin's own manifest (${manifestPath}) — `
245
+ + "refusing to answer about a stranger's tree rather than return a foreign root",
246
+ );
247
+ }
248
+ }
249
+
250
+ /**
251
+ * The `.git` at or above `cwd`, or `null` where the walk finds none.
252
+ *
253
+ * The one fault git cannot report distinctly: an unreadable `.git` (`chmod
254
+ * 000`) makes the discovery walk step over it and print the SAME
255
+ * no-repository-anywhere message as a genuinely empty walk (measured). So the
256
+ * absence has to be established from the filesystem rather than from what git
257
+ * said about it.
258
+ *
259
+ * `GIT_CEILING_DIRECTORIES` is honoured with git's own semantics — the walk
260
+ * starts in the working directory and declines to step UP into a ceiling entry
261
+ * — so a fixture that scopes git's search scopes this too, instead of the
262
+ * answer depending on whatever lies above `$TMPDIR`.
263
+ */
264
+ function dotGitAtOrAbove(cwd) {
265
+ const ceilings = (process.env.GIT_CEILING_DIRECTORIES ?? "").split(":").filter(Boolean);
266
+ for (let dir = cwd; ;) {
267
+ const dotGit = join(dir, ".git");
268
+ if (existsSync(dotGit)) return dotGit;
269
+ const up = dirname(dir);
270
+ if (up === dir || ceilings.includes(up)) return null;
271
+ dir = up;
272
+ }
273
+ }
274
+
275
+ /**
276
+ * The ambient git working tree at or above `cwd` — verified to be THIS
277
+ * plugin's own — or `null` where there is no working tree at all.
278
+ *
279
+ * `null` rather than a throw, because "there is no repository here" is an
280
+ * answer this codebase acts on, not an error to propagate — and at module scope
281
+ * a propagated one costs the whole file its tests. That licence is spent on
282
+ * that one answer and no other: every other way `git rev-parse` can fail leaves
283
+ * the question unanswered rather than answering it "no", and those throw. git's
284
+ * stderr is captured rather than discarded precisely so the two can be told
285
+ * apart, and it travels in the error.
286
+ *
287
+ * A working tree that IS found is not returned on the strength of being
288
+ * 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
290
+ * an unanswerable one; the old guard against it lived only in each caller's
291
+ * non-vacuity check on `trackedShellScripts`, which a non-empty foreign
292
+ * answer sailed straight through.
293
+ */
294
+ export function repoRoot(cwd) {
295
+ // GIT_DIR/GIT_WORK_TREE scrubbed (#1599, gitEnv()): measured from a
296
+ // subdirectory of a real working tree (the realistic shape — `cwd` here is
297
+ // wherever the calling script happens to live, rarely the root itself) —
298
+ // an ambient GIT_DIR alone answers `--show-toplevel` with `cwd` ITSELF, not
299
+ // the tree's real root, and an ambient GIT_WORK_TREE alone answers with
300
+ // that ambient path outright. Both are silently wrong, at exit 0.
301
+ const r = spawnSync("git", ["rev-parse", "--show-toplevel"],
302
+ { cwd, encoding: "utf8", env: gitEnv({ LC_ALL: "C" }) });
303
+ if (r.status === 0) {
304
+ const root = r.stdout.trim();
305
+ assertOwnRoot(root);
306
+ return root;
307
+ }
308
+
309
+ const dotGit = r.error ? null : dotGitAtOrAbove(cwd);
310
+ if (!r.error && dotGit === null && NO_REPOSITORY_ANYWHERE.test(r.stderr ?? "")) return null;
311
+
312
+ throw new Error(
313
+ `git could not answer whether ${cwd} is inside a working tree, which is not the same as there being none: `
314
+ + (r.error ? `git could not be run at all (${r.error.code ?? r.error.message})`
315
+ : dotGit !== null ? `${dotGit} is there and git reports no repository (status ${r.status}: ${(r.stderr ?? "").trim()})`
316
+ : `status ${r.status}: ${(r.stderr ?? "").trim()}`),
317
+ );
318
+ }
319
+
320
+ /**
321
+ * A node:test `skip` value for a file that cannot run without an ambient
322
+ * working tree: the reason where `root` is `null`, and `false` — run it —
323
+ * otherwise.
324
+ *
325
+ * `subject` names what did not run, in that file's own words. The reason has to
326
+ * be exact in BOTH directions: a reader of the run must not read the absence of
327
+ * coverage as coverage, and must not read a file-wide "nothing here was
328
+ * checked" over a file where most of the tests ran either.
329
+ */
330
+ export function skipWithoutRepo(root, subject) {
331
+ return root === null
332
+ ? `no ambient git working tree at or above this file, so ${subject} did not run and nothing about it was checked`
333
+ + " — a `git archive` extraction has no `.git`. Run it against a real checkout or worktree."
334
+ : false;
335
+ }
336
+
337
+ // The `stat` failures that ARE an answer — the working tree holds no regular
338
+ // file at the path, for any reader — rather than a failure to look: nothing
339
+ // there at all (ENOENT); a file standing where one of the path's own
340
+ // 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
+ // that limit is one inside the tracked path itself — a fact about the tree,
344
+ // not about where the checkout sits.
345
+ //
346
+ // Every other code is a probe that could not look — EACCES from a directory
347
+ // the reader may not search, ENAMETOOLONG from a checkout nested past the
348
+ // OS's path limit, EIO — where a file may well be there and ship. Passing
349
+ // over one would drop it from every sweep with nothing to say so, so those
350
+ // throw, and in a sweep that lists at module scope the throw fails the whole
351
+ // file: the loud module-load failure the header above keeps for `repoRoot`'s
352
+ // own "git cannot answer the question", and for the same reason.
353
+ const NO_REGULAR_FILE_THERE = new Set(["ENOENT", "ENOTDIR", "ELOOP"]);
354
+
355
+ /**
356
+ * Whether the working tree holds a regular file at `path`, following a symlink
357
+ * to whatever it names — a link to a file is one; a dangling link, a looping
358
+ * one, a directory and nothing at all are not. A failure outside
359
+ * NO_REGULAR_FILE_THERE throws.
360
+ */
361
+ function isRegularFile(path) {
362
+ try {
363
+ return statSync(path).isFile();
364
+ } catch (e) {
365
+ if (NO_REGULAR_FILE_THERE.has(e.code)) return false;
366
+ throw e;
367
+ }
368
+ }
369
+
370
+ /**
371
+ * Every file tracked in the working tree at `root` that `pathspecs` match,
372
+ * repo-relative — the one discovery rule behind all three exports below, so what
373
+ * `root` must be and which repository answers cannot drift apart between
374
+ * them (#1751). `caller` is the export's own name, for the refusal.
375
+ *
376
+ * `root` must be a real root — call it only where `repoRoot` answered. A `null`
377
+ * root is rejected rather than absorbed into an empty list: `execFileSync`
378
+ * reads `cwd: null` as "inherit the calling process's directory", so absorbing
379
+ * it would answer some unrelated repository's files, or nothing, with nothing
380
+ * to say which. Deciding what an absent working tree means is the caller's, via
381
+ * `skipWithoutRepo`.
382
+ *
383
+ * An empty result from a real root is a legitimate answer from a repository
384
+ * that has nothing matching, and the caller's non-vacuity guard is what judges
385
+ * it.
386
+ *
387
+ * A tracked path the working tree holds no regular file at is not in the
388
+ * answer: an `rm` or `mv` not yet committed, a symlink that dangles or loops, a
389
+ * directory where a file is tracked (a symlink to one, or a submodule's gitlink
390
+ * checked out on disk), a file standing where the path's own directory was.
391
+ * Every caller reads each path it is handed, and one absent path in the answer
392
+ * 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
394
+ * deletion that is committed does not ship, and one that is not is swept again
395
+ * in any checkout that has the file; a link with no file behind it has no text
396
+ * to sweep. A path the probe could not look at is not one of these — it
397
+ * throws, as NO_REGULAR_FILE_THERE says.
398
+ *
399
+ * GIT_DIR scrubbed (#1599, gitEnv()): measured, an ambient GIT_DIR silently
400
+ * substitutes a DIFFERENT repository's tracked list for `root`'s own — the
401
+ * caller's non-vacuity guard cannot see this, since the wrong list is
402
+ * routinely non-empty. GIT_WORK_TREE is inert here (measured, for `*.sh` and
403
+ * for the lone `:(exclude)*.test.mjs` alike) for a reason specific to THIS
404
+ * call rather than transferable from `isTrackedBy` above: every pathspec here
405
+ * is a relative glob, never `realpathSync`'d, so there is no absolute path for
406
+ * an ambient work tree to reject as outside itself.
407
+ */
408
+ function trackedFiles(caller, root, pathspecs) {
409
+ if (typeof root !== "string") {
410
+ throw new TypeError(
411
+ `${caller}: root must come from repoRoot(), got ${String(root)} — `
412
+ + "an absent working tree is a skip for the caller to make, not an empty list to iterate",
413
+ );
414
+ }
415
+ // `-z`, split on NUL: git's default `\n`-separated form C-quotes any path
416
+ // with a non-ASCII or otherwise "unusual" byte (for example `café.mjs`
417
+ // becomes the literal 12-character string `"caf\303\251.mjs"`), which
418
+ // fails a plain `.endsWith(".mjs")` and is not openable at that path
419
+ // either — a real tracked file silently missing from every caller's
420
+ // answer. `-z` never quotes; it is git's own NUL-terminated form for
421
+ // "give me the exact bytes".
422
+ return execFileSync("git", ["ls-files", "-z", "--", ...pathspecs], { cwd: root, encoding: "utf8", env: gitEnv() })
423
+ .split("\0").filter(Boolean)
424
+ .filter((f) => isRegularFile(join(root, f)));
425
+ }
426
+
427
+ /**
428
+ * Every tracked path in the working tree at `root` — every one `pathspecs`
429
+ * match, where the caller names any — repo-relative, for a sweep that polices
430
+ * text of every kind rather than one kind of script. `root`, an empty answer,
431
+ * an absent path and the ambient git variables all behave as `trackedFiles`
432
+ * says.
433
+ */
434
+ export function trackedPaths(root, pathspecs = []) {
435
+ return trackedFiles("trackedPaths", root, pathspecs);
436
+ }
437
+
438
+ /**
439
+ * Every tracked `*.sh` in the working tree at `root`, repo-relative. `root`,
440
+ * an empty answer, an absent path and the ambient git variables all behave as
441
+ * `trackedFiles` says.
442
+ */
443
+ export function trackedShellScripts(root) {
444
+ return trackedFiles("trackedShellScripts", root, ["*.sh"]);
445
+ }
446
+
447
+ // A first line that hands the file to node: `node` itself as the interpreter,
448
+ // by a direct path (`#!/usr/local/bin/node`) or through `env` with any options
449
+ // or assignments before it (`#!/usr/bin/env node`, `#!/usr/bin/env -S node
450
+ // --no-warnings`) — including `env`'s own `-u`/`--unset` and `-C`/`--chdir`,
451
+ // each of which takes a following bare argument of its own (`#!/usr/bin/env
452
+ // -u FOO node`, `--unset FOO`, `-C DIR`) that is still no part of the
453
+ // interpreter name. Only THESE two options ever consume a following word:
454
+ // every other flag (`-S`, `-i`, …) stays exactly one token, so it can never
455
+ // swallow the real command as if it were its own argument and let a
456
+ // non-node interpreter through (`#!/usr/bin/env -S bun node` runs bun, not
457
+ // node, and must still refuse) — and, since no flag but these two has more
458
+ // than one way to be parsed, a long adversarial options list can never blow
459
+ // up matching it either. `node` is the WHOLE interpreter name — `nodemon`
460
+ // and `bun` are other programs.
461
+ const NODE_SHEBANG = /^#!\s*(?:\S*\/)?(?:env(?:\s+(?:-(?:u|-unset|C|-chdir)(?:=\S*|\s+\S+)|-(?!(?:u|-unset|C|-chdir)\s)\S+|\w+=\S*))*\s+(?:\S*\/)?)?node(?:\s|$)/;
462
+
463
+ // The first read's size. A shebang is one short line, and this holds any this
464
+ // repository would write, so one read decides it; a longer line reads on.
465
+ const SHEBANG_BYTES = 256;
466
+
467
+ // 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
469
+ // tracked `#!` file holding no newline into memory whole to answer a boolean —
470
+ // measured, 300 MiB of one peaked above 1.1 GiB, and one past the longest
471
+ // string V8 builds (~512 MiB) threw ERR_STRING_TOO_LONG out of the whole
472
+ // listing. No kernel runs a line this long as written: measured, macOS refuses
473
+ // to exec a first line of 512 bytes or more (ENOEXEC), and Linux reads its
474
+ // first 255 and cuts the rest. So the cap sits well past any shebang a kernel
475
+ // honours whole; the one line it refuses that a kernel would still start —
476
+ // Linux, on a prefix naming node — is one no author writes.
477
+ //
478
+ // 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
480
+ // 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
482
+ // whole, which would move the unbounded read, not remove it.
483
+ const SHEBANG_MAX_BYTES = 4096;
484
+
485
+ /**
486
+ * Whether the first line of the file at `path` is a node shebang — the WHOLE
487
+ * line, up to its newline or the end of the file; `buf` is scratch for the
488
+ * first read and grows past it only for a longer line, never past
489
+ * SHEBANG_MAX_BYTES: a first line that long or longer, newline not counted, is
490
+ * 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
492
+ * its end, reads `nodemon` cut after its `node` as `node` at the end of the
493
+ * line, and decodes a character it cuts in half as U+FFFD. A file that does
494
+ * not open with `#!` is decided on that first read however long its first
495
+ * line, since NODE_SHEBANG is anchored there. `path` is one `trackedFiles`
496
+ * answered, so the working tree holds a regular file there, and any failure to
497
+ * read it throws.
498
+ */
499
+ function hasNodeShebang(path, buf) {
500
+ const fd = openSync(path, "r");
501
+ try {
502
+ let len = readSync(fd, buf, 0, buf.length, 0);
503
+ if (len < 2 || buf[0] !== 0x23 || buf[1] !== 0x21) return false;
504
+ // `buf` is reused across files, so the search stops at the bytes read.
505
+ // The buffer doubles, so rescanning from 0 each pass stays linear.
506
+ let end;
507
+ while ((end = buf.subarray(0, len).indexOf(0x0a)) === -1) {
508
+ if (len === buf.length) {
509
+ if (len >= SHEBANG_MAX_BYTES) return false;
510
+ const grown = Buffer.allocUnsafe(Math.min(len * 2, SHEBANG_MAX_BYTES));
511
+ buf.copy(grown, 0, 0, len);
512
+ buf = grown;
513
+ }
514
+ const n = readSync(fd, buf, len, buf.length - len, len);
515
+ if (n === 0) {
516
+ end = len;
517
+ break;
518
+ }
519
+ len += n;
520
+ }
521
+ // A newline byte never falls inside a multi-byte UTF-8 character, and
522
+ // the end of the file is the file's own, so nothing here is cut in half.
523
+ return NODE_SHEBANG.test(buf.toString("utf8", 0, end));
524
+ } finally {
525
+ closeSync(fd);
526
+ }
527
+ }
528
+
529
+ /**
530
+ * Every tracked file this repository ships that the consumer's own `node`
531
+ * executes, in the working tree at `root`, repo-relative: each `*.mjs`, and
532
+ * any other file whose first line is a node shebang — the extensionless
533
+ * entrypoints `fleet-run`, `fleet-bootstrap` and `fleet-provenance` (#1855).
534
+ * A shebang decides, never an extension alone: `plugin/workflows/*.js` is ESM
535
+ * a harness runs and plain node never loads, and carries none. Test files —
536
+ * `*.test.mjs`, the one naming this repository gives them — are not shipped,
537
+ * so they are not in the answer, shebang or not. `root`, an empty answer, an
538
+ * absent path and the ambient git variables all behave as `trackedFiles` says.
539
+ */
540
+ export function trackedNodeScripts(root) {
541
+ const buf = Buffer.alloc(SHEBANG_BYTES);
542
+ return trackedFiles("trackedNodeScripts", root, [":(exclude)*.test.mjs"])
543
+ .filter((f) => f.endsWith(".mjs") || hasNodeShebang(join(root, f), buf));
544
+ }