@joshuafolkken/kit 1.872.0

package/scripts/document/edit-files-cli.ts

@@ -0,0 +1,280 @@
+#!/usr/bin/env tsx
+import { readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { document_section } from './document-section'
+
+// `josh edit:files <plan-path>` — apply several content-addressed edits in one call
+// (joshuafolkken/kit#2366).
+//
+// **This is the write-side counterpart of `read:files`, and it reverses what kit#2202 rejected.**
+// kit#2202 folded the pre-edit *reads* into one call and left the edits to native multiple `Edit`
+// blocks, on the ground that presupposing a multi-edit tool would leave the rule unfired on a harness
+// that lacks one. kit#2366 measured that bet across six lanes: 230 of 230 edit turns issued a single
+// `Edit`, a per-turn density of exactly 1.000 — native multiple edits never happened. A `pnpm josh`
+// command runs on every harness, so folding the edits into one is available where the native shape was
+// not, and the only lever measured to move round-trip density is a composite command (kit#2165 /
+// kit#2162 / kit#2202), never advice (kit#1304 / kit#1329 / kit#1337 / kit#2164 / kit#2276).
+//
+// **Each edit is content-addressed, so a false fold surfaces rather than corrupts.** An edit names the
+// exact `old` text it was written against; a plan whose `old` matches no line, or more than one, is
+// refused for that edit and reported — the same guarantee the `Edit` tool gives, and the reason the
+// batching guard can hand this command out safely (`time-batch-guard.ts` → the write-side fold).
+//
+// **A file is written only when every one of its edits applied.** The edits of one file are applied in
+// order against the running text; if any of them fails to match, that file is left exactly as it was
+// and its failures are named. So a partial plan never leaves a file half-edited.
+//
+// **Only independent edits are folded (joshuafolkken/kit#2493).** An edit whose original range overlaps
+// an earlier edit's of the same file, or whose match count that earlier edit changed, depends on it — it
+// addresses text that edit rewrote, removed or duplicated — and is refused as `dependent`. Such an edit is
+// issued on its own after the batch, so a fold never hides an ordering the author did not see.
+//
+// **`-` reads the plan from standard input (joshuafolkken/kit#2493)**, so a lane child passes its edits
+// in the one call as a quoted heredoc (`pnpm josh edit:files - <<'EDITS'`) instead of writing a plan file
+// first — the quoted delimiter expands nothing, and the call carries the old/new pairs an `Edit` would.
+
+const ARGV_OFFSET = 2
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const NONE = 0
+const SINGLE = 1
+const USAGE = 'Usage: josh edit:files <plan-path | ->'
+const STDIN_PATH = '-'
+const STDIN_DESCRIPTOR = 0
+
+// The plan format, chosen for a model to author without escaping code into JSON: a `=====`-fenced path
+// header — the same rule `read:files` prints between files — then a git-conflict-marker pair. Every
+// block is one edit; several blocks may name one file. The markers are matched as whole lines, so a
+// `=======` inside the edited text is only a separator when it stands alone on its own line.
+const BLOCK = /===== (.+?) =====\n<<<<<<< OLD\n([\s\S]*?)\n=======\n([\s\S]*?)\n>>>>>>> NEW/gu
+const PATH_GROUP = 1
+const OLD_GROUP = 2
+const NEW_GROUP = 3
+
+const APPLIED = 'applied'
+const NO_MATCH = 'no match'
+const AMBIGUOUS = 'ambiguous'
+const MISSING = 'missing'
+const DEPENDENT = 'dependent'
+
+interface EditSpec {
+	path: string
+	old: string
+	new: string
+}
+
+interface TextRange {
+	start: number
+	end: number
+}
+
+interface EditResult {
+	spec: EditSpec
+	status: string
+	count: number
+}
+
+// Every conflict block in the plan, in the order written. A group with a missing capture reads as
+// empty text rather than throwing, so a malformed block fails at match time with a clear report.
+function parse_plan(text: string): ReadonlyArray<EditSpec> {
+	return [...text.matchAll(BLOCK)].map((match) => ({
+		path: match[PATH_GROUP] ?? '',
+		old: match[OLD_GROUP] ?? '',
+		new: match[NEW_GROUP] ?? '',
+	}))
+}
+
+// How many times the `old` text occurs, counted the way a unique-match replace needs it: zero is a
+// miss, more than one is ambiguous, and only exactly one is safe to replace.
+function match_count(haystack: string, needle: string): number {
+	return haystack.split(needle).length - SINGLE
+}
+
+// Apply one edit to the running text, or report why it could not. The replacement is passed as a
+// function so a `$` in the new text is written literally rather than read as a `String#replace` token,
+// and the single-match gate above means only the intended occurrence is swapped. An edit is `dependent`
+// when an earlier edit of the same file claimed its original range, or changed its match count.
+function apply_one(
+	content: string,
+	spec: EditSpec,
+	original: string,
+	is_claimed: boolean,
+): { text: string; result: EditResult } {
+	const count = match_count(content, spec.old)
+
+	if (is_claimed || count !== match_count(original, spec.old)) {
+		return { text: content, result: { spec, status: DEPENDENT, count } }
+	}
+
+	if (count === NONE) return { text: content, result: { spec, status: NO_MATCH, count } }
+	if (count > SINGLE) return { text: content, result: { spec, status: AMBIGUOUS, count } }
+
+	const text = content.replace(spec.old, () => spec.new)
+
+	return { text, result: { spec, status: APPLIED, count } }
+}
+
+// Where the `old` text sits in the original file — an empty range unless it matches exactly once, so a
+// failed edit claims nothing. Two edits whose ranges overlap address the same
+// text, so the later one would land in the earlier one's output even when its match count is unchanged
+// (`foo()` → `try { foo() }`, then `foo()` → `bar()`).
+function original_range(original: string, old: string): TextRange {
+	if (match_count(original, old) !== SINGLE) return { start: -1, end: -1 }
+
+	const start = original.indexOf(old)
+
+	return { start, end: start + old.length }
+}
+
+function overlaps(left: TextRange, right: TextRange): boolean {
+	return left.start < right.end && right.start < left.end
+}
+
+// Record this edit's original range, answering whether an earlier edit had already claimed any of it.
+function claim(claimed: Array<TextRange>, range: TextRange): boolean {
+	const is_claimed = claimed.some((earlier) => overlaps(earlier, range))
+
+	claimed.push(range)
+
+	return is_claimed
+}
+
+// One file's edits folded against its text in order, each edit checked against the original as well.
+function fold_edits(
+	original: string,
+	specs: ReadonlyArray<EditSpec>,
+): { text: string; results: Array<EditResult> } {
+	const results: Array<EditResult> = []
+	const claimed: Array<TextRange> = []
+	let text = original
+
+	for (const spec of specs) {
+		const step = apply_one(text, spec, original, claim(claimed, original_range(original, spec.old)))
+
+		text = step.text
+		results.push(step.result)
+	}
+
+	return { text, results }
+}
+
+// The edits of one file. Every edit is reported; the file is written only when all of them applied, so
+// a plan that half-matches leaves the file untouched.
+function apply_file(
+	root: string,
+	file: string,
+	specs: ReadonlyArray<EditSpec>,
+): ReadonlyArray<EditResult> {
+	const resolved = path.resolve(root, file)
+	const original = document_section.read_optional(resolved)
+	if (original === undefined) return specs.map((spec) => ({ spec, status: MISSING, count: NONE }))
+
+	const { text, results } = fold_edits(original, specs)
+	if (results.every((result) => result.status === APPLIED)) writeFileSync(resolved, text)
+
+	return results
+}
+
+// The edits grouped by their file, insertion order preserved on both the keys and each file's list, so
+// the report reads in the order the plan was written.
+function group_by_path(specs: ReadonlyArray<EditSpec>): Map<string, Array<EditSpec>> {
+	const groups = new Map<string, Array<EditSpec>>()
+	for (const spec of specs) groups.set(spec.path, [...(groups.get(spec.path) ?? []), spec])
+
+	return groups
+}
+
+function apply_all(root: string, specs: ReadonlyArray<EditSpec>): ReadonlyArray<EditResult> {
+	return [...group_by_path(specs)].flatMap(([file, file_specs]) =>
+		apply_file(root, file, file_specs),
+	)
+}
+
+// One line per edit: what happened and to which file, with the match count where it explains the
+// failure. `applied` is the only success; every other status makes the whole call non-zero.
+function describe(result: EditResult): string {
+	if (result.status === AMBIGUOUS) {
+		return `${AMBIGUOUS} (${String(result.count)}) ${result.spec.path}`
+	}
+
+	return `${result.status} ${result.spec.path}`
+}
+
+function report(results: ReadonlyArray<EditResult>): number {
+	for (const result of results) console.info(describe(result))
+	const has_failure = results.some((result) => result.status !== APPLIED)
+
+	return has_failure ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE
+}
+
+function read_stdin(): string {
+	return readFileSync(STDIN_DESCRIPTOR, 'utf8')
+}
+
+// The plan text: standard input for `-`, otherwise the named file (`undefined` when it cannot be read).
+function read_plan(root: string, plan_path: string, read_input: () => string): string | undefined {
+	if (plan_path === STDIN_PATH) return read_input()
+
+	return document_section.read_optional(path.resolve(root, plan_path))
+}
+
+// Read and validate the plan, or print the reason and answer `undefined`. Kept apart from `run` so the
+// entry stays under the statement limit.
+function load_specs(
+	root: string,
+	plan_path: string,
+	read_input: () => string,
+): ReadonlyArray<EditSpec> | undefined {
+	const plan = read_plan(root, plan_path, read_input)
+
+	if (plan === undefined) {
+		console.error(`Cannot read ${plan_path}`)
+
+		return undefined
+	}
+
+	const specs = parse_plan(plan)
+
+	if (specs.length === NONE) {
+		console.error(`No edit blocks in ${plan_path}`)
+
+		return undefined
+	}
+
+	return specs
+}
+
+function run(
+	argv: ReadonlyArray<string>,
+	root: string = process.cwd(),
+	read_input: () => string = read_stdin,
+): number {
+	const [plan_path] = argv
+
+	if (plan_path === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const specs = load_specs(root, plan_path, read_input)
+	if (specs === undefined) return FAILURE_EXIT_CODE
+
+	return report(apply_all(root, specs))
+}
+
+function main(argv: ReadonlyArray<string>): void {
+	process.exitCode = run(argv)
+}
+
+const edit_files_cli = {
+	USAGE,
+	main,
+	parse_plan,
+	run,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
+
+export { edit_files_cli }

package/scripts/document/entry-read-budget.ts

@@ -0,0 +1,154 @@
+// The byte ceiling on what each workflow entry reads before it starts — the primary budget, a
+// ratchet like the per-document one (joshuafolkken/kit#2257).
+//
+// **The per-document ceiling was a proxy for a run's cost, not the cost.** A run does not pay "one
+// document's size"; it pays the total its entry reads — the mandated skill files, the sections they
+// point out to, the point-of-use documents reached later, and the resident `CLAUDE.md` every request
+// carries. `read:set` already computes that total, so this budgets it directly: the entry total is
+// the primary ceiling, and the per-document ceiling (`document-byte-budget.ts`) falls back to the
+// documents no entry reads (`document-reachability.ts` draws the line). A document an entry reads is
+// held by the entry total and carries no per-document ceiling, so neither budget holds it twice.
+//
+// THE CEILING IS BLOCK-QUANTIZED, exactly as the per-document one is (joshuafolkken/kit#2231): an
+// entry total is one number, so recording its raw size would make every lane that nudges a covered
+// document bump this shared line. The recorded ceiling is the smallest `BLOCK_BYTES` multiple at or
+// above the measured total, so growth within a block needs no edit and a crossing bumps to the same
+// multiple from every lane — the change git auto-merges.
+//
+// HOW TO RAISE (or LOWER) A CEILING — this file, like the per-document budget. When the gate reports
+// an entry over its ceiling, copy the exact value the message names into that entry's row. A
+// reduction that drops the total below a block lowers the row the same way, to the multiple the
+// stale message names.
+
+import { statSync } from 'node:fs'
+import path from 'node:path'
+import { PACKAGE_DIR } from '#scripts/init/init-paths'
+import { backlogrun_parent_read_set } from './backlogrun-parent-read-set'
+import { document_byte_budget } from './document-byte-budget'
+import { document_reachability } from './document-reachability'
+import { entry_read_set, type ReadSetCost } from './entry-read-set'
+import { lane_child_read_set } from './lane-child-read-set'
+
+const { block_ceiling } = document_byte_budget
+const { LANE_CHILD } = lane_child_read_set
+const { BACKLOGRUN } = backlogrun_parent_read_set
+const NOTHING = 0
+
+interface EntryBudget {
+	entry: string
+	bytes: number
+}
+
+// Recorded byte ceiling of each entry's total read — the block multiple at or above its measured
+// size. Names exactly the entries `known_entries` offers: the test fails on a stale entry and on an
+// entry with no row, so the definition cannot rot as entries are added or removed.
+const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
+	// Raised in joshuafolkken/kit#2289 when `pre-gate-cut.md` joined the point-of-use set: its ~29KB
+	// read is a point-of-use read every entry's total now counts, a correction of an under-count rather
+	// than new reading. Raised again in joshuafolkken/kit#2282 when the same document grew by its
+	// status-quo decision record, and once more in joshuafolkken/kit#2295 when it recorded the
+	// recent-context hand-off. Lowered in joshuafolkken/kit#2294 — the FIRST downward move on this
+	// ratchet — when `pre-gate-cut.md` was compressed (37,786 B → ~20,300 B): every entry that reads it
+	// crossed a block downward, so the recorded ceilings drop to the block multiples the stale-ratchet
+	// message named rather than staying loose above the reduction. `kickoff` and the lane child rose one
+	// block again in joshuafolkken/kit#2312 when `pre-gate-cut.md` recorded the resume-side cost the
+	// conditional cut is built on; the other entries stayed within their block. `backlogrun` rose one
+	// block in joshuafolkken/kit#2317 when `backlogrun-child.md`'s outage section recorded the
+	// session-resume re-dispatch and the outage-fold window.
+	// Raised in joshuafolkken/kit#2328 when `retrospective.md` joined the point-of-use set and `SKILL.md`
+	// grew by §2j: every entry that reads `SKILL.md` discovers the retrospective document, so its ~5KB
+	// and the new section crossed a block for each. The lane child is exempt — it never runs the
+	// retrospective (`run:step` answers `stop` for a child at the stop position), so it skips both.
+	// joshuafolkken/kit#2335 recorded the drain-time firing with the operational detail in
+	// `retrospective.md` (which the lane child skips) and a one-line pointer in `backlogrun-steps.md`, so
+	// every entry stayed within its block rather than climbing back to a pre-#2294 ceiling the downward
+	// ratchet holds shut. joshuafolkken/kit#2342 added the `--summary` close to `retrospective.md` in a
+	// single sentence, kept short so every entry that reads it stays within its block.
+	// Lowered for the lane child in joshuafolkken/kit#2357 — a downward move on this ratchet — when
+	// `backlogrun-steps.md` left the child's point-of-use set: the child never opened the scheduler's step
+	// list, so its ~48KB read crossed a block downward and the recorded ceiling drops to the block multiple
+	// the stale-ratchet message named. The other entries still read it, so their rows hold.
+	// joshuafolkken/kit#2345 added the `implementation-unit` delegation row (full fan-out procedure in
+	// `docs/josh-commands.md` → "`josh fanout`"); `SKILL.md` §2b gained only a one-clause mention and a
+	// pointer, folded into the existing enumeration and offset by tightening §2b prose, so every entry
+	// stayed within its block (kickoff has no block of headroom — its pre-#2294 ceiling is the next
+	// multiple, which the downward ratchet holds shut).
+	// joshuafolkken/kit#2353 wired the watcher-guard note into `backlogrun-progress.md` (read by the three
+	// planning entries): kickoff has no headroom, so the addition was offset by tightening that file's
+	// heartbeat prose, keeping every entry within its existing block.
+	{ entry: 'kickoff', bytes: 258_048 },
+	{ entry: 'fullrun', bytes: 258_048 },
+	{ entry: 'halfrun', bytes: 258_048 },
+	{ entry: 'backlogrun', bytes: 262_144 },
+	{ entry: LANE_CHILD, bytes: 86_016 },
+]
+
+function byte_size(root: string, relative_path: string): number {
+	return statSync(path.join(root, relative_path)).size
+}
+
+function entry_cost(root: string, entry: string): ReadSetCost {
+	if (entry === LANE_CHILD) return lane_child_read_set.costed(root)
+
+	if (entry === BACKLOGRUN) return backlogrun_parent_read_set.costed(root)
+
+	return entry_read_set.costed(root, entry)
+}
+
+// The total an entry reads, in bytes: its scoped own files plus the point-of-use sections it reaches
+// later — the same figure `josh read:set` prints as `total read` — plus the resident base every entry
+// carries whatever it does.
+function total_read_bytes(cost: ReadSetCost): number {
+	return entry_read_set.total([cost.scoped, ...cost.point_of_use.map((one) => one.cost)]).bytes
+}
+
+function resident_base_bytes(): number {
+	return document_reachability.RESIDENT_BASE.reduce(
+		(sum, one) => sum + byte_size(PACKAGE_DIR, one),
+		NOTHING,
+	)
+}
+
+// The bytes an entry's mandated read comes to right now — what the recorded ceiling is compared
+// against.
+function entry_total_bytes(root: string, entry: string): number {
+	return total_read_bytes(entry_cost(root, entry)) + resident_base_bytes()
+}
+
+function recorded_bytes_for(entry: string): number | undefined {
+	return ENTRY_READ_BUDGET.find((one) => one.entry === entry)?.bytes
+}
+
+// The over-budget message, naming the entry, its current total, its recorded ceiling, and the next
+// block multiple to record — the same shape the per-document budget uses so a reader raises a ceiling
+// by copying rather than computing.
+function over_budget_message(entry: string, current_bytes: number, recorded_bytes: number): string {
+	const next = block_ceiling(current_bytes).toString()
+	const raise_hint = `raise its recorded size to ${next} in scripts/document/entry-read-budget.ts so the reason shows in the PR diff`
+
+	return `entry ${entry} reads ${current_bytes.toString()} bytes, over its ${recorded_bytes.toString()}-byte ceiling. Trim what it reads, or ${raise_hint}.`
+}
+
+// The stale-ratchet message: a recorded ceiling more than a block above the entry's actual total was
+// left loose when the read shrank across a boundary, so it no longer holds the reduction.
+function stale_budget_message(
+	entry: string,
+	recorded_bytes: number,
+	current_bytes: number,
+): string {
+	const next = block_ceiling(current_bytes).toString()
+	const lower_hint = `lower its recorded size to ${next} in scripts/document/entry-read-budget.ts so the ratchet holds the reduction`
+
+	return `entry ${entry} records ${recorded_bytes.toString()} bytes but reads ${current_bytes.toString()}, more than a block above actual. ${lower_hint}.`
+}
+
+const entry_read_budget = {
+	ENTRY_READ_BUDGET,
+	entry_total_bytes,
+	over_budget_message,
+	recorded_bytes_for,
+	stale_budget_message,
+}
+
+export type { EntryBudget }
+export { entry_read_budget }