@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,71 @@
1
+ // Pins the rule that `docs/agents/issue-tracker.md` states nowhere else.
2
+ // #79: the section reproduced the issue-read command and its bare `--comments`
3
+ // caveat verbatim but carried neither of the (then two) WHICH-TEXT-WINS rules,
4
+ // so the copy read as complete while they were absent. #25 later dropped the
5
+ // second of those rules — the `Respec` block was instructed nowhere else and
6
+ // never defined, in this doc or in any real issue — leaving the
7
+ // brief-outranks-body rule pinned here alone.
8
+ //
9
+ // No SKILL.md instructs an agent to READ this doc as its entry point for
10
+ // the fetch-the-relevant-ticket rule: the rule reaches agents through three
11
+ // SKILL.md files that each carry their own copy — run-team word-for-word
12
+ // inside its verbatim implementer prompt, next-ticket and sizing-a-ticket
13
+ // paraphrased — not by deferring here. (run-team/SKILL.md does link this
14
+ // doc once, at its closing-keyword exemption — an unrelated rule, not a
15
+ // hand-off to this section.) #79 brought the doc into sync with those three
16
+ // copies; it is the catch-up copy, not their source, so this pin keeps the
17
+ // doc from drifting back out, nothing more.
18
+ //
19
+ // What DEPENDS on this doc is settled by MUTATION, never by grepping for
20
+ // `issue-tracker`: the string matches many more paths than read the doc,
21
+ // and a match cannot tell a mention from a dependency. Write `MUTATED` over
22
+ // `docs/agents/issue-tracker.md` in a scratch copy of the tree and run
23
+ // `node --test plugin/scripts/*.test.mjs` (every test file lives there);
24
+ // what reddens against that copy's own green baseline is what reads it.
25
+ // Measured on this commit: this file, `closing-keyword-prose.test.mjs` and
26
+ // `tracker-block-copy-prose.test.mjs`, no other suite. Re-run the mutation
27
+ // rather than trusting that list — a grep result frozen into a header is
28
+ // the defect #1119 names.
29
+ //
30
+ // This mutation only catches PRESENCE pins: a test asserting the doc LACKS
31
+ // some phrase reads `MUTATED` as still lacking it and stays green, invisible
32
+ // to this method. None of the three files above pins an absence today, but
33
+ // a future one needs a different check.
34
+ //
35
+ // The full `plugin/scripts/*.test.mjs` glob is 140+ files; a loaded machine
36
+ // can leave dozens uncompleted instead of green, so the "own green
37
+ // baseline" precondition can itself fail before the mutation ever runs.
38
+ // Confirm against the three files named above first — that trio settles in
39
+ // under a second — before trusting a run against the full glob.
40
+ //
41
+ // THE CEILING, same as fleet-tick-prose.test.mjs: this proves a phrase is
42
+ // PRESENT. It cannot prove it is not negated by a sentence added beside it.
43
+ import { test } from "node:test";
44
+ import assert from "node:assert/strict";
45
+ import { readFileSync } from "node:fs";
46
+ import { join } from "node:path";
47
+
48
+ const REPO = join(import.meta.dirname, "..", "..");
49
+ const TRACKER = readFileSync(join(REPO, "docs", "agents", "issue-tracker.md"), "utf8");
50
+
51
+ // Sliced to this section alone. Unbounded to EOF the slice runs through the
52
+ // wayfinding operations, and a `## Agent Brief` mention anywhere past here
53
+ // would satisfy the assertions with the section itself deleted. Stops at the
54
+ // next `#` or `##` — either one closes this section — and falls back to EOF
55
+ // rather than bailing, so a correct doc still passes once this is the last
56
+ // section. Not `indexOf("\n## ")` alone: that runs the slice through a later
57
+ // `# ` h1, and the rules relocated under one then read as still present.
58
+ function fetchSection() {
59
+ const start = '## When a skill says "fetch the relevant ticket"';
60
+ const at = TRACKER.indexOf(start);
61
+ assert.notEqual(at, -1, `'${start}' moved — update this test`);
62
+ const rest = TRACKER.slice(at + start.length);
63
+ const next = rest.match(/\n#{1,2} /);
64
+ return start + (next ? rest.slice(0, next.index) : rest);
65
+ }
66
+
67
+ test("the fetch section says the Agent Brief comment outranks the issue body", () => {
68
+ // Without it an agent that reads the documented entry point takes the body as
69
+ // authoritative and never learns a brief can overrule it.
70
+ assert.match(fetchSection(), /`## Agent Brief` comment\s+is\s+authoritative over the issue body/);
71
+ });
@@ -0,0 +1,248 @@
1
+ # shellcheck shell=sh
2
+ # JSON string escaping for the fleet's shell scripts. Sourced, never executed —
3
+ # no shebang, and the `shell=sh` directive above is what tells shellcheck what
4
+ # to check it as.
5
+ #
6
+ # Source it as:
7
+ #
8
+ # json_lib="$(dirname "$0")/json.sh"
9
+ # [ -r "$json_lib" ] || die "cannot read $json_lib"
10
+ # # shellcheck source-path=SCRIPTDIR
11
+ # # shellcheck source=json.sh
12
+ # . "$json_lib" || die "$json_lib failed to load"
13
+ #
14
+ # The `[ -r ]` is NOT belt-and-braces, and `|| die` alone is not enough. `.` is
15
+ # a POSIX *special builtin*: failing to open its operand aborts a
16
+ # non-interactive shell outright, so `||` never runs. Measured on a missing
17
+ # file with `set -e`: /bin/sh (macOS bash 3.2) and bash 3.2/`--posix` exit **1**
18
+ # with the guard unfired, dash exits 2 unfired, and only Homebrew bash 5.3
19
+ # reaches the `|| die`. Exit 1 is a VERDICT in FIVE of the eight callers here —
20
+ # inflight.sh reads it as "ticket taken", verify-sha.sh as "not reachable",
21
+ # prove-merge.sh as "not proved", no-undo-audit.sh as "REFUSED, the worktree is
22
+ # dirty", release-ticket.sh as "NOT released, blocked" — so a lib that merely
23
+ # went missing would fabricate one. claim-ticket.sh, reap.sh and
24
+ # worktree-audit.sh define no exit 1 at all, which is not safety: a bare 1 out
25
+ # of them is a code their caller has no reading for. The `[ -r ]` catches that
26
+ # before `.` can kill the shell; the `|| die` stays for the case `[ -r ]`
27
+ # cannot see, and that case is live rather than theoretical — a DIRECTORY at
28
+ # this path passes `[ -r ]` and `.` returns 1 with the arm firing (measured,
29
+ # /bin/sh and bash 5.3; dash sources a directory at exit 0 instead). A lib that
30
+ # reads and has a SYNTAX error aborts before either guard on /bin/sh, bash 3.2
31
+ # and `bash --posix`, while bash 5.3 reaches the `|| die` with status 2. The
32
+ # suite does NOT cover that case: measured, a syntax error appended at EOF
33
+ # leaves bash 3.2 with every function it had already parsed and json.test.mjs
34
+ # stays green. CI's `shellcheck -x -S warning` over `git ls-files '*.sh'` is
35
+ # what catches it (SC1072/SC1073).
36
+ #
37
+ # `LC_ALL=C` is a per-command prefix on every tool below, never an export. Three
38
+ # of the callers (verify-sha.sh, prove-merge.sh, claim-ticket.sh) do not pin the
39
+ # locale, and exporting from a sourced lib would silently re-locale every OTHER
40
+ # tool in them. The prefix is a no-op in the five that do pin it (#582), and
41
+ # closes the same hazard in the three that do not. It matters here because BSD
42
+ # `tr` exits 1 on a byte that is not valid UTF-8 under a UTF-8 locale, and
43
+ # `sed` emits nothing at all.
44
+ #
45
+ # THE RULE ORDER. Backslash first, always: escaping the quote (or any short
46
+ # form) before the backslash rule runs turns the backslash IT just introduced
47
+ # into `\\` on the second pass. Every rule that adds a backslash comes after
48
+ # that one. The five C0 bytes RFC 8259 gives a two-character short form —
49
+ # \010 \011 \012 \014 \015 (\b \t \n \f \r) — get theirs. BS and FF are matched
50
+ # as a literal byte spelled with `printf`, never as `\b` or `\f`: neither
51
+ # spelling matches \010, and neither fails quietly — `\b` in a BRE is a
52
+ # zero-width word BOUNDARY to GNU sed and a literal `b` to BSD sed, so the rule
53
+ # would insert `\b` at every word edge on one and mangle every letter `b` on the
54
+ # other (measured, GNU sed 4.9 and macOS sed). \177 (DEL) is not a C0 byte and
55
+ # JSON permits it unescaped, so it is left alone (#146). Every remaining byte
56
+ # below \040 has no short form, \013 (VT) included — RFC 8259 lists exactly the
57
+ # five above and `\v` is not among them; `tr` turns it into a space, and
58
+ # `jrewritten` is how a caller finds out that happened, since a replaced value
59
+ # is not the original bytes and must not be treated as a real path or ref.
60
+ # Byte-safe because every `tr` set here is ASCII-only and no byte of a
61
+ # multi-byte UTF-8 sequence is below \200 — not because UTF-8 avoids the low
62
+ # bytes, which it does not: half of it is ASCII. `tr` pads the replacement with
63
+ # its last character.
64
+ #
65
+ # `:a;$!N;$!ba` slurps the whole value into one pattern space before any rule
66
+ # runs, so a literal newline in $1 is data the LF rule can reach rather than a
67
+ # line break sed's own per-line cycling would swallow. Guarding `N` with `$!`
68
+ # matters on its own: unguarded, BSD sed's `N` on the last line hits EOF with
69
+ # nothing to append and discards the pattern space instead of printing it —
70
+ # POSIX leaves this undefined and GNU sed's answer differs — so plain `N;$!ba`
71
+ # prints nothing at all for a single-line value.
72
+ #
73
+ # EVERY FALLIBLE STAGE'S STATUS IS READ HERE, and that is the #119 fix rather
74
+ # than a style choice. A pipeline's status is its LAST stage's, so the
75
+ # original `printf | sed | tr` reported only `tr` — forcing `sed` to fail left
76
+ # jstr exiting 0 with an empty value and every caller's `|| die` unfired, while
77
+ # forcing `tr` worked (measured on PR #425). POSIX sh has no `pipefail` and no
78
+ # `PIPESTATUS`, so each stage that can fail is captured and its status read.
79
+ # The consequence, and the rule a later edit is checked against: a pipeline may
80
+ # still END a function, but only where its LAST stage is the fallible one — `tr`
81
+ # closes jstr, `paste` closes jarr and jarr_rewritten, so each function's status
82
+ # IS that tool's (measured: breaking `tr` gives jstr the shim's own status,
83
+ # breaking `sed` gives 1 from that capture's `|| return 1`).
84
+ #
85
+ # `$( )` strips trailing newlines off each capture. For a newline INSIDE the
86
+ # value that is safe, because `sed` ran first and turned it into the two
87
+ # characters `\n`. It is NOT safe for a TRAILING \012: sed consumes that byte as
88
+ # its line terminator rather than data, so no rule can see it, sed re-emits an
89
+ # indistinguishable one and `$( )` takes it off — `jstr` of `a<LF>` and of `a`
90
+ # are byte-identical (measured). No live caller can reach it: every argument
91
+ # reaching jstr today is a script literal or a `$( )`/`awk`/`read` capture that
92
+ # has already lost its own trailing newline. #119 leaves it there rather than
93
+ # adding a sentinel no caller would exercise. jarr is the exception and is
94
+ # handled in its own note.
95
+ #
96
+ # Scratch variables are `json_`-prefixed because /bin/sh has no `local` and
97
+ # these land in the sourcing script's namespace.
98
+ #
99
+ # A path or ref is a byte string with no UTF-8 guarantee (a fetched tree can
100
+ # carry a Linux- or latin-1-authored name), but the string these functions
101
+ # build is JSON TEXT, which must be valid UTF-8. Every rule above operates
102
+ # below \200 or adds ASCII bytes, so a genuinely invalid byte — one that is
103
+ # not even part of a malformed multi-byte sequence, just a byte no UTF-8
104
+ # sequence starts or continues with — sailed through untouched and landed raw
105
+ # in the payload: `jq` then silently substitutes U+FFFD on decode (changing
106
+ # what the caller reads back) and a strict parser (`python3 json.load`)
107
+ # refuses the payload outright (#613). `jstr` and `jarr` now run the value
108
+ # through Python's own UTF-8 decoder with `errors="replace"` first — the same
109
+ # U+FFFD a lenient consumer already substitutes, made explicit and JSON-legal
110
+ # at the source instead of implicit and consumer-dependent — and `jrewritten`
111
+ # reports it as a rewrite like any other replaced byte.
112
+
113
+ # Python's own UTF-8 decoder with errors="replace" (#613), shared script text
114
+ # rather than a function: a function called on the right side of a pipe runs
115
+ # in its own subshell, and a `json_u8=` assigned inside it would not survive
116
+ # back to the caller — every call site below runs this as
117
+ # `python3 -c "$JSON_UTF8_PY"` and captures the result itself.
118
+ JSON_UTF8_PY='
119
+ import sys
120
+ sys.stdout.buffer.write(sys.stdin.buffer.read().decode("utf-8", "replace").encode("utf-8"))
121
+ '
122
+
123
+ # Escape $1 into a JSON string BODY — no surrounding quotes, the caller adds
124
+ # those. Exit 0 with the escaped value, non-zero if any stage failed.
125
+ jstr() {
126
+ # Empty in, empty out, no fork at all (#120). This is what lets a PATH-wide
127
+ # sed/tr outage — the failure inflight.sh measures at its own top — leave a
128
+ # field that legitimately found nothing untouched: that field never calls the
129
+ # broken tool, so it cannot observe its failure.
130
+ [ -n "$1" ] || return 0
131
+ json_u8=$(printf '%s' "$1" | LC_ALL=C python3 -c "$JSON_UTF8_PY") || return 1
132
+ json_esc=$(printf '%s' "$json_u8" \
133
+ | LC_ALL=C sed -e ':a' -e '$!N' -e '$!ba' \
134
+ -e 's/\\/\\\\/g' -e 's/"/\\"/g' \
135
+ -e "s/$(printf '\010')/\\\\b/g" -e 's/\t/\\t/g' -e 's/\n/\\n/g' \
136
+ -e "s/$(printf '\014')/\\\\f/g" -e 's/\r/\\r/g') || return 1
137
+ printf '%s' "$json_esc" | LC_ALL=C tr '\001-\007\013\016-\037' ' '
138
+ }
139
+
140
+ # True iff $1 held a byte jstr/jarr had to REPLACE rather than escape — every C0
141
+ # byte except \010 \011 \012 \014 \015 (escaped above, never replaced) and \177
142
+ # (preserved, never replaced). `$()` strips trailing newlines off both sides,
143
+ # and \012 is the one byte it strips: it is not in the delete set, so the same
144
+ # suffix comes off both and the strip cannot manufacture a difference. It does
145
+ # hide one — a value ending in \012 answers `false` here while jstr has already
146
+ # dropped that byte — which is the trailing-\012 case the header bounds as
147
+ # unreachable from every live caller, not a byte jarr/jstr REPLACED.
148
+ jrewritten() {
149
+ # Same short circuit as jstr, same reason: nothing to have rewritten, so no
150
+ # need to ask a tool that might not be there.
151
+ [ -n "$1" ] || { printf false; return 0; }
152
+ # `|| return 1` is load-bearing, not belt-and-braces. This function's last
153
+ # command is an AND-OR list that always exits 0 on its own (`[ … ] && printf
154
+ # false || printf true`, and the early `printf true; return 0` below is its
155
+ # own explicit return), so a failed `tr` (or `python3`) reaches the caller
156
+ # only by `set -e` aborting the function — and a call site inside an `if`
157
+ # condition is exempt from `set -e`. Whether that exemption also reaches
158
+ # this assignment is the shell's own choice, and shells disagree. Measured:
159
+ # `dash`, Apple's `/bin/sh`, and bash 3.2.57 in POSIX/sh mode abort here,
160
+ # which is correct; bash 5.3 in EVERY mode — plain, invoked as `sh`, and
161
+ # `--posix` — plus bash 3.2.57 outside POSIX mode and zsh 5.9 all run on to
162
+ # the always-0 last line and hand back a confident `true` about bytes
163
+ # nothing ever examined. That second list covers every distro whose
164
+ # `/bin/sh` is bash 5.x. Returning explicitly makes the status this
165
+ # function's own on all of them.
166
+ json_raw=$(printf '%s' "$1" | LC_ALL=C tr -d '\001-\007\013\016-\037') || return 1
167
+ json_orig=$(printf '%s' "$1")
168
+ # The C0 scrub above already answers `true` on its own — no need to also
169
+ # fork python3 to ask whether UTF-8 needed repairing too, the OR is already
170
+ # satisfied.
171
+ [ "$json_raw" = "$json_orig" ] || { printf true; return 0; }
172
+ # `jarr_rewritten` calls this once per line, and a repo's own paths are
173
+ # overwhelmingly plain ASCII — the case the C0 check above does NOT catch,
174
+ # since it only differs on a rewrite. A value holding no byte >= \200 at
175
+ # all decodes as UTF-8 to itself unconditionally (pure ASCII is already
176
+ # valid UTF-8), so python3 has nothing to find; this tr is what lets that
177
+ # common case skip the interpreter start instead of paying for one on every
178
+ # line regardless of content (measured 8.4x slower before this and the
179
+ # short-circuit above existed).
180
+ json_ascii=$(printf '%s' "$1" | LC_ALL=C tr -d '\200-\377') || return 1
181
+ [ "$json_ascii" = "$json_orig" ] && { printf false; return 0; }
182
+ # jstr also repairs a byte that is not valid UTF-8 (#613) — a second,
183
+ # independent replacement alongside the C0 scrub above, so a second,
184
+ # independent check: this value must decode as strict UTF-8 unchanged, or
185
+ # jstr rewrote it too.
186
+ json_u8=$(printf '%s' "$1" | LC_ALL=C python3 -c "$JSON_UTF8_PY") || return 1
187
+ [ "$json_u8" = "$json_orig" ] && printf false || printf true
188
+ }
189
+
190
+ # The array form: stdin's lines to one quoted JSON string each, comma-joined,
191
+ # ready to drop between a `[` and a `]`. Same ruleset as jstr minus the LF rule
192
+ # — \012 is the record separator here, never data, and never can be: a caller
193
+ # has already lost the ability to tell an element's own newline from the
194
+ # boundary between two elements by the time a value reaches per-line stdin,
195
+ # which is why no-undo-audit.sh refuses a conflicting path holding one before it
196
+ # ever calls this. Escaping a byte this function structurally never receives
197
+ # would be dead code standing in for a restructure nobody has needed; #89 owns
198
+ # that class.
199
+ #
200
+ # Empty stdin gives empty stdout at exit 0 — measured as the original
201
+ # pipeline's behaviour, and the `[ -n ]` guard is what preserves it: without it
202
+ # the `printf '%s\n'` re-emit below would turn "no elements" into one empty
203
+ # line and `paste` would answer `""`, inventing an element out of nothing.
204
+ jarr() {
205
+ # Same repair as jstr, same reason (#613), run once over the whole
206
+ # (possibly multi-line) input rather than per line: \n is ASCII and never a
207
+ # byte of a multi-byte UTF-8 sequence, so decoding the joined blob in one
208
+ # pass cannot manufacture or hide a line boundary.
209
+ #
210
+ # Unlike jstr's single opaque value, THIS input's own trailing newlines ARE
211
+ # the record separator between array elements — a plain `$()` capture
212
+ # strips every one of them, which silently drops trailing empty elements
213
+ # (measured: `printf 'a\n\n' | jarr` lost its second, empty element, and
214
+ # `printf '\n' | jarr` lost its only one, collapsing `[""]` into the same
215
+ # empty output as a zero-element array). Appending `x` after python3's own
216
+ # output gives `$()` a non-newline character to stop stripping at;
217
+ # `${json_u8%x}` removes exactly that one character back off, and only on
218
+ # the success path — `&&` (not `;`) keeps python3's own exit status as the
219
+ # substitution's, so a failed python3 returns 1 before ever reaching the
220
+ # strip. json_u8 now holds python3's output byte-for-byte, so it is fed to
221
+ # sed with `printf '%s'` (no added newline) rather than `printf '%s\n'`.
222
+ json_u8=$(LC_ALL=C python3 -c "$JSON_UTF8_PY" && printf x) || return 1
223
+ json_u8=${json_u8%x}
224
+ json_esc=$(printf '%s' "$json_u8" | LC_ALL=C sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' \
225
+ -e "s/$(printf '\010')/\\\\b/g" -e 's/\t/\\t/g' \
226
+ -e "s/$(printf '\014')/\\\\f/g" -e 's/\r/\\r/g' \
227
+ -e 's/^/"/' -e 's/$/"/') || return 1
228
+ [ -n "$json_esc" ] || return 0
229
+ json_esc=$(printf '%s\n' "$json_esc" | LC_ALL=C tr '\001-\007\013\016-\037' ' ') || return 1
230
+ printf '%s\n' "$json_esc" | LC_ALL=C paste -sd, -
231
+ }
232
+
233
+ # Parallel boolean array to jarr's own output, true where that line held a byte
234
+ # jarr replaced. `read` alone drops a final line with no trailing newline —
235
+ # `set -eu` never sees it fail, the loop just never runs its body for that
236
+ # line — so `|| [ -n "$line" ]` is load-bearing on the last element, not
237
+ # defensive filler. `|| exit 1` inside the loop and `|| return 1` on the capture
238
+ # carry a failed `jrewritten` out of the subshell for the same reason the
239
+ # captures above exist: left as a pipeline into `paste`, only `paste`'s status
240
+ # would survive.
241
+ jarr_rewritten() {
242
+ json_esc=$(while IFS= read -r line || [ -n "$line" ]; do
243
+ jrewritten "$line" || exit 1
244
+ echo
245
+ done) || return 1
246
+ [ -n "$json_esc" ] || return 0
247
+ printf '%s\n' "$json_esc" | LC_ALL=C paste -sd, -
248
+ }