@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.
- package/.claude-plugin/plugin.json +9 -0
- package/LICENSE +202 -0
- package/NOTICE +18 -0
- package/agents/fleet-finisher.agent.md +7 -0
- package/agents/fleet-implementer-alt.agent.md +210 -0
- package/agents/fleet-implementer.agent.md +210 -0
- package/agents/fleet-merge-bot.agent.md +7 -0
- package/agents/fleet-review-comments.agent.md +40 -0
- package/agents/fleet-review-correctness.agent.md +43 -0
- package/agents/fleet-review-runner.agent.md +73 -0
- package/agents/fleet-review-silent-failure.agent.md +49 -0
- package/agents/fleet-review-simplify.agent.md +46 -0
- package/agents/fleet-review-snapshot.agent.md +24 -0
- package/agents/fleet-review-tests.agent.md +46 -0
- package/agents/fleet-review-types.agent.md +41 -0
- package/agents/fleet-review-verifier.agent.md +29 -0
- package/commands/review-and-fix.md +98 -0
- package/commands/run-merge-bot.md +357 -0
- package/commands/run-team-help.md +17 -0
- package/package.json +23 -0
- package/scripts/agent-test-dir-prose.test.mjs +59 -0
- package/scripts/agent-test.test.mjs +1636 -0
- package/scripts/ambient-git-vars-mjs-prose.test.mjs +354 -0
- package/scripts/ambient-git-vars-prose.test.mjs +192 -0
- package/scripts/ancestry-check-position-prose.test.mjs +175 -0
- package/scripts/apply-ruleset.test.mjs +420 -0
- package/scripts/arg-header-probes-prose.test.mjs +393 -0
- package/scripts/arg.mjs +600 -0
- package/scripts/arg.test.mjs +1354 -0
- package/scripts/board-cli.test.mjs +694 -0
- package/scripts/board-identity.test.mjs +429 -0
- package/scripts/board-liveness-banner.test.mjs +119 -0
- package/scripts/board-prev-shape.test.mjs +229 -0
- package/scripts/board-tryparse-null.test.mjs +119 -0
- package/scripts/board.html +471 -0
- package/scripts/board.mjs +2037 -0
- package/scripts/board.test.mjs +3086 -0
- package/scripts/brief-after-cut-prose.test.mjs +53 -0
- package/scripts/candidates-exit3-prose.test.mjs +302 -0
- package/scripts/candidates.mjs +674 -0
- package/scripts/candidates.test.mjs +2101 -0
- package/scripts/caveat-unification-prose.test.mjs +98 -0
- package/scripts/ci-comment-rot-prose.test.mjs +2025 -0
- package/scripts/ci-completes-premise-prose.test.mjs +257 -0
- package/scripts/ci-state-prose.test.mjs +113 -0
- package/scripts/ci-state.mjs +761 -0
- package/scripts/ci-state.test.mjs +1640 -0
- package/scripts/ci-vacuous-green.test.mjs +368 -0
- package/scripts/citation-sweep-prose.test.mjs +1572 -0
- package/scripts/claim-lifecycle.test.mjs +185 -0
- package/scripts/claim-ticket.sh +417 -0
- package/scripts/claim-ticket.test.mjs +1121 -0
- package/scripts/closing-keyword-prose.test.mjs +193 -0
- package/scripts/cockpit-launch-idempotent-prose.test.mjs +165 -0
- package/scripts/cockpit-tick-nonblocking.test.mjs +210 -0
- package/scripts/compute-board.mjs +579 -0
- package/scripts/compute-board.test.mjs +1060 -0
- package/scripts/compute-spend.mjs +329 -0
- package/scripts/compute-spend.test.mjs +451 -0
- package/scripts/cross-repo-citation-prose.test.mjs +156 -0
- package/scripts/cwd-isolation-pins.mjs +83 -0
- package/scripts/dedupe-guard-prose.test.mjs +243 -0
- package/scripts/derive-testcmd.sh +239 -0
- package/scripts/derive-testcmd.test.mjs +380 -0
- package/scripts/diff-stats.mjs +231 -0
- package/scripts/diff-stats.test.mjs +408 -0
- package/scripts/dispatch-block-golden-prose.test.mjs +1024 -0
- package/scripts/dispatch-block-pins-prose.test.mjs +615 -0
- package/scripts/drop-merged-label.sh +173 -0
- package/scripts/drop-merged-label.test.mjs +480 -0
- package/scripts/expected-jobs-prose.test.mjs +80 -0
- package/scripts/filing-bar-seat-prose.test.mjs +242 -0
- package/scripts/filing-claim-bar-prose.test.mjs +166 -0
- package/scripts/finisher-dispatch-premise-prose.test.mjs +312 -0
- package/scripts/finisher-halt-prose.test.mjs +106 -0
- package/scripts/finisher-name-prose.test.mjs +134 -0
- package/scripts/finisher-own-tree-prose.test.mjs +285 -0
- package/scripts/finisher-pin-race-prose.test.mjs +339 -0
- package/scripts/fix-applier-correction-rules-prose.test.mjs +201 -0
- package/scripts/fix-applier-result-file-prose.test.mjs +100 -0
- package/scripts/fleet-bootstrap +155 -0
- package/scripts/fleet-heartbeat.mjs +272 -0
- package/scripts/fleet-heartbeat.test.mjs +450 -0
- package/scripts/fleet-provenance +207 -0
- package/scripts/fleet-provenance.test.mjs +64 -0
- package/scripts/fleet-run +148 -0
- package/scripts/fleet-run.test.mjs +90 -0
- package/scripts/fleet-state.mjs +400 -0
- package/scripts/fleet-state.test.mjs +373 -0
- package/scripts/fleet-tick-prose.test.mjs +299 -0
- package/scripts/fleet-tick.mjs +832 -0
- package/scripts/fleet-tick.test.mjs +1332 -0
- package/scripts/force-with-lease-reason-prose.test.mjs +184 -0
- package/scripts/frontmatter-allowlist.json +64 -0
- package/scripts/frontmatter-check.mjs +256 -0
- package/scripts/frontmatter-check.test.mjs +436 -0
- package/scripts/git-env.mjs +124 -0
- package/scripts/git-env.test.mjs +149 -0
- package/scripts/git-status-untracked-mode-sweep.test.mjs +216 -0
- package/scripts/gone-walk.test.mjs +213 -0
- package/scripts/gp-sep-invariant-prose.test.mjs +188 -0
- package/scripts/head-moved-after-label-prose.test.mjs +233 -0
- package/scripts/immutable-body-claim-prose.test.mjs +413 -0
- package/scripts/implementer-model-tier.test.mjs +643 -0
- package/scripts/inflight-citation-prose.test.mjs +144 -0
- package/scripts/inflight-exit2-prose.test.mjs +81 -0
- package/scripts/inflight-probe-guard-prose.test.mjs +109 -0
- package/scripts/inflight-scan-scope-prose.test.mjs +57 -0
- package/scripts/inflight.sh +1106 -0
- package/scripts/inflight.test.mjs +2984 -0
- package/scripts/injection-control-prose.test.mjs +404 -0
- package/scripts/install-root-audit.test.mjs +464 -0
- package/scripts/instrument-check-prose.test.mjs +235 -0
- package/scripts/instruments.sh +394 -0
- package/scripts/instruments.test.mjs +787 -0
- package/scripts/issue-tracker-prose.test.mjs +71 -0
- package/scripts/json.sh +248 -0
- package/scripts/json.test.mjs +364 -0
- package/scripts/ledger-dispatch.test.mjs +516 -0
- package/scripts/ledger-grammar.mjs +85 -0
- package/scripts/ledger-grammar.test.mjs +142 -0
- package/scripts/ledger-read-require-file.test.mjs +197 -0
- package/scripts/ledger.mjs +1753 -0
- package/scripts/ledger.test.mjs +3554 -0
- package/scripts/line-distance-prose.test.mjs +245 -0
- package/scripts/liveness-rationale-prose.test.mjs +83 -0
- package/scripts/locale-pin-prose.test.mjs +189 -0
- package/scripts/member-outcome-prose.test.mjs +167 -0
- package/scripts/member-outcomes-header.test.mjs +148 -0
- package/scripts/member-outcomes-prose.test.mjs +63 -0
- package/scripts/member-outcomes.mjs +231 -0
- package/scripts/member-outcomes.test.mjs +507 -0
- package/scripts/member-prompt-prose.test.mjs +161 -0
- package/scripts/member-record.mjs +605 -0
- package/scripts/member-record.test.mjs +516 -0
- package/scripts/member-write-guard.mjs +279 -0
- package/scripts/member-write-guard.test.mjs +211 -0
- package/scripts/merge-commit-probe-prose.test.mjs +122 -0
- package/scripts/merge-gate.mjs +262 -0
- package/scripts/merge-gate.test.mjs +613 -0
- package/scripts/muted-git-guard-sweep.test.mjs +493 -0
- package/scripts/net-ssh-precedence-prose.test.mjs +91 -0
- package/scripts/net-watchdog-prose.test.mjs +79 -0
- package/scripts/net.sh +409 -0
- package/scripts/net.test.mjs +211 -0
- package/scripts/no-ci-gate-prose.test.mjs +108 -0
- package/scripts/no-undo-audit.sh +1134 -0
- package/scripts/no-undo-audit.test.mjs +3965 -0
- package/scripts/no-wave.test.mjs +138 -0
- package/scripts/node-floor-sweep.test.mjs +611 -0
- package/scripts/pointer-target-prose.test.mjs +186 -0
- package/scripts/pr-overlap.mjs +417 -0
- package/scripts/pr-overlap.test.mjs +695 -0
- package/scripts/printf-die-sweep.test.mjs +384 -0
- package/scripts/prompt-renderer.mjs +39 -0
- package/scripts/prompt-renderer.test.mjs +68 -0
- package/scripts/prose-pin.mjs +808 -0
- package/scripts/prose-pin.test.mjs +1034 -0
- package/scripts/prove-merge.sh +228 -0
- package/scripts/prove-merge.test.mjs +995 -0
- package/scripts/pull-table-relabel-prose.test.mjs +60 -0
- package/scripts/quiet-payload-prose.test.mjs +222 -0
- package/scripts/reap.sh +1768 -0
- package/scripts/reap.test.mjs +4395 -0
- package/scripts/reaping-prose.test.mjs +159 -0
- package/scripts/refuter-scratch-prose.test.mjs +135 -0
- package/scripts/release-label-required-prose.test.mjs +71 -0
- package/scripts/release-label-split-prose.test.mjs +169 -0
- package/scripts/release-ticket.sh +1716 -0
- package/scripts/release-ticket.test.mjs +5106 -0
- package/scripts/renovate-release-contract.test.mjs +379 -0
- package/scripts/repo-root.mjs +544 -0
- package/scripts/repo-root.test.mjs +873 -0
- package/scripts/reporter-output-rule-prose.test.mjs +208 -0
- package/scripts/review-agent-report-only.test.mjs +49 -0
- package/scripts/review-core-cwd-isolation.test.mjs +374 -0
- package/scripts/review-core-reads.test.mjs +478 -0
- package/scripts/review-core-refuter-scratch.test.mjs +148 -0
- package/scripts/review-core-snapshot-path.test.mjs +777 -0
- package/scripts/review-core-specialist-scratch.test.mjs +189 -0
- package/scripts/review-core-testcmd.test.mjs +288 -0
- package/scripts/review-core-unrun.test.mjs +530 -0
- package/scripts/review-core-unverified-discriminant.test.mjs +208 -0
- package/scripts/review-core.mjs +1028 -0
- package/scripts/review-eval-resolver-path.test.mjs +55 -0
- package/scripts/review-eval.mjs +197 -0
- package/scripts/review-host-fixture.mjs +73 -0
- package/scripts/review-in-run-retry.test.mjs +187 -0
- package/scripts/review-no-vendor-dispatch.test.mjs +45 -0
- package/scripts/review-path-default.test.mjs +796 -0
- package/scripts/review-runner-spawns.test.mjs +93 -0
- package/scripts/review-runner.test.mjs +155 -0
- package/scripts/review-tier-audit.test.mjs +140 -0
- package/scripts/run-artifact-pr-prose.test.mjs +341 -0
- package/scripts/run-merge-bot-prose.test.mjs +1391 -0
- package/scripts/scratch-partition-invariant-prose.test.mjs +74 -0
- package/scripts/scripts-path-citation-sweep.test.mjs +73 -0
- package/scripts/section-between-guard-prose.test.mjs +378 -0
- package/scripts/select-dimensions.test.mjs +674 -0
- package/scripts/shared-refusal.test.mjs +388 -0
- package/scripts/shell-traps-prose.test.mjs +507 -0
- package/scripts/shortlist.mjs +355 -0
- package/scripts/shortlist.test.mjs +366 -0
- package/scripts/slow-transport.mjs +72 -0
- package/scripts/snapshot-repo.test.mjs +772 -0
- package/scripts/snapshot-runner-audience-prose.test.mjs +129 -0
- package/scripts/spend-view.test.mjs +312 -0
- package/scripts/staleness-qualifier-prose.test.mjs +251 -0
- package/scripts/staleness-verdict-prose.test.mjs +142 -0
- package/scripts/staleness.mjs +414 -0
- package/scripts/staleness.test.mjs +893 -0
- package/scripts/stalled-member-liveness-prose.test.mjs +219 -0
- package/scripts/stash-prohibition-prose.test.mjs +313 -0
- package/scripts/strip-comments.mjs +44 -0
- package/scripts/tier-check.mjs +468 -0
- package/scripts/tier-check.test.mjs +726 -0
- package/scripts/tier-guard-gate-prose.test.mjs +216 -0
- package/scripts/tier-outcomes-header.test.mjs +586 -0
- package/scripts/tier-outcomes.mjs +441 -0
- package/scripts/tier-outcomes.test.mjs +342 -0
- package/scripts/tier-roles.mjs +250 -0
- package/scripts/tier-roles.test.mjs +316 -0
- package/scripts/tracker-block-copy-prose.test.mjs +288 -0
- package/scripts/triage-labels-gloss-prose.test.mjs +97 -0
- package/scripts/unattended-git-sweep.test.mjs +142 -0
- package/scripts/verify-sha-exit2-prose.test.mjs +269 -0
- package/scripts/verify-sha.sh +117 -0
- package/scripts/verify-sha.test.mjs +693 -0
- package/scripts/watcher-degraded-block.test.mjs +372 -0
- package/scripts/watcher-key-prose.test.mjs +106 -0
- package/scripts/within-run-pair-prose.test.mjs +208 -0
- package/scripts/worktree-audit.sh +482 -0
- package/scripts/worktree-audit.test.mjs +1407 -0
- package/scripts/worktree-head-prose.test.mjs +276 -0
- package/scripts/worktree-listing-sweep.test.mjs +217 -0
- package/scripts/worktree-model-prose.test.mjs +216 -0
- package/scripts/worktree.sh +470 -0
- package/skills/next-ticket/SKILL.md +138 -0
- package/skills/run-team/SKILL.md +3603 -0
- package/skills/run-team/references/ci-and-staleness.md +75 -0
- package/skills/run-team/references/correction-tickets.md +37 -0
- package/skills/run-team/references/isolation.md +23 -0
- package/skills/run-team/references/member-lifecycle.md +73 -0
- package/skills/run-team/references/reaping.md +73 -0
- 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
|
+
});
|
package/scripts/json.sh
ADDED
|
@@ -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
|
+
}
|