Tooling: consolidate durable repository tools in TypeScript on Home

Parent: #462 Related: #464, #494

Goal

Consolidate the repository tooling that is worth keeping into TypeScript executed by the owner-maintained Home engine. This is not a requirement to translate every current script one-for-one: obsolete, redundant, one-shot, or superseded tools should receive an explicit disposition instead of a rewrite.

Current boundary

The fail-closed inventory in docs/.data/tool-migration-inventory-v1.json records every remaining Python, JavaScript/TypeScript, and shell implementation script plus its inputs, outputs, exit/ordering/diagnostic/schema/network contracts, subprocesses, and caller/reference files. #462 enforces the dependency boundary. The small documentation link gate already moved to an in-tree Zig executable before this direction was clarified; no further blanket Python-to-Zig translation is wanted.

Home lives in the owner-maintained home-lang/home repository (~/Code/Home/lang). Its TypeScript frontend is substantial, while the native runtime/home run path is still transitional. The Home execution contract must become real in Home itself before zig-js claims its tools run on it.

Scope

• Preserve owner-maintained dependencies such as BunPress, STX, ts-syntax-highlighter, and Home; improve them in their source repositories rather than deleting, replacing, vendoring around, or bypassing them.
• Keep the machine-readable inventory fail-closed as scripts and callers change.
• Classify each legacy script as a durable Home/TypeScript candidate, owned bootstrap responsibility, retained unavoidable bootstrap glue, obsolete, redundant, or superseded. Do not assume every file deserves a port.
• Establish and version the required Home tool-runner surface in Home first: TypeScript parsing/emission, module loading, filesystem/process/stream APIs, exit codes, stdout/stderr, environment and argv, deterministic JSON/TSV/Markdown/file replacement, and offline local-package resolution.
• Implement durable tools in TypeScript against that real Home surface, either in zig-js or an owner-maintained shared tooling package under ~/Code/**.
• Preserve byte-for-byte output where it is a checked contract; otherwise use a reviewed versioned schema migration with compatibility tests.
• Replace Python unittest/script tests with tests that run through the same Home/TypeScript path, retaining malformed-input and deliberate failure-path coverage.
• Remove obsolete runtimes, shebangs, callers, manifests, and cache guidance only after the replacement or retirement is proven.
• Keep normal build/test/docs/benchmark/audit commands offline. Explicit checksum-pinned standards-data acquisition remains an operator action under #462.

No-workaround rules

• Do not mechanically translate Python scripts to Zig.
• Do not require Node or Bun as the permanent runtime for the migrated tools.
• Do not embed or vendor Python/Node/Bun, add a fake Home shim in zig-js, or claim Home execution while delegating to another runtime.
• Do not delete a gate, generated artifact, diagnostic contract, or evidence check merely to reduce the script count.
• Do not check in generated results without a reproducible generator.
• Do not rewrite a tool until it is shown to be durable and the required Home runtime surface exists.

Acceptance

• A machine-readable migration inventory classifies every .py, .mjs, .ts, and .sh file and every caller; unclassified additions fail CI. Foundation: 8068f57f.
• Every legacy tool has a reviewed disposition; only durable tools are selected for migration.
• Home provides a tested, versioned, native execution surface sufficient for the selected TypeScript tooling without delegating to Node, Bun, or Python.
• Migrated tools reproduce existing inventories, generated regions, reports, benchmark statistics, ordering, exit codes, and deliberate error diagnostics.
• Selected CI/build callers use an exact pinned owner-maintained Home checkout and run offline; local resolution is enforced by #462.
• Obsolete/redundant tools and runtime prerequisites are removed only with caller and contract evidence.
• Build/test feedback is measured with #494 so the Home path does not impose unacceptable latency.

Foundation

Normal command contracts are indexed by build.zig, .github/workflows/, CLAUDE.md, repository skills, and docs/.data/tool-migration-inventory-v1.json. Existing implementations remain authoritative until a selected tool passes its compatibility gate on Home.

The #462 foundation in 6adf47fe now enforces the tooling boundary in CI. The current checked inventory finds 60 Python files, 8 MJS files, 1 TypeScript file, and 3 shell files under tools/ and scripts/ (excluding node_modules), so the 52-Python count in this issue was already stale after newer tooling landed.

The gate now fails on count drift, an unclassified network-capable script, build subprocess drift, package-script drift, tracked-manifest additions, and mutable/unclassified CI actions. #497 remains open and owns the actual Zig migration; this commit deliberately records these as migration_required rather than treating them as permanent exemptions.

The fail-closed migration inventory foundation landed on main in 8068f57f.

It classifies all 72 current repository implementation scripts (60 Python, 8 MJS, 1 TypeScript, 3 shell) with their effective exit/ordering/diagnostic/schema/network contracts, concrete inputs and outputs, subprocesses, caller/reference files, and intended owned Zig migration target. zig build dependency-audit now reads the Git index and rejects missing/stale tool records, runtime/extension drift, unknown contract profiles, ambiguous names, and any new undeclared caller/reference anywhere in a tracked regular file.

Local evidence:

• zig build dependency-audit passes in ~1.0 s warm and reports 72 classified tools.
• A temporary 61st unclassified Python file was rejected.
• A temporary undeclared caller in CONTRIBUTING.md was rejected with the exact tool and caller path.
• tools/docs-link-check.py passes across 89 files.
• Owned BunPress manifest regeneration plus bun run docs:build passes across 49 pages.

The first acceptance item is implemented; I am leaving its checkbox unchanged until the pushed CI gate is green. The migration itself remains open and will replace these implementations in logical contract-preserving groups. Owned dependencies such as BunPress remain first-party source dependencies and are explicitly out of removal scope.

First contract-preserving implementation migration landed on main in 1e5deee4.

tools/docs-link-check.py is gone. CI and every documented/skill caller now use the dependency-free in-tree zig build docs-link-check executable. The build step runs four Zig tests covering Markdown parsing, sidebar parsing, fragment/query/external behavior, malformed input, and the exact missing-link diagnostic before scanning the repository.

Evidence:

• 89 documentation/root/skill files pass, matching the former gate's denominator and success text.
• A deliberate missing link failed with docs-link-check: 1 unresolved link(s) and the exact source -> target line.
• --quiet succeeds without output when invoked directly.
• zig build dependency-audit passes with 71 remaining classified scripts.
• Python inventory: 60 -> 59; total legacy script inventory: 72 -> 71.
• CI YAML parses; owned BunPress renders 49 pages and matches the regenerated deterministic manifest.
• Engine files are unchanged; flips 0 test262 cases.

This removes a runtime dependency rather than wrapping or bypassing it, and it does not change or remove BunPress/STX/ts-syntax-highlighter.

Direction corrected in e0b8342c: the inventory no longer prescribes one-for-one in-tree Zig translations. Its 70 durable-tool entries are now home_typescript_candidate; the CI toolchain fallback remains a separate owned-bootstrap responsibility.

I also retitled and rewrote this issue around the actual target: selectively consolidate durable tooling in TypeScript on the owner-maintained Home engine, establish the real Home runtime contract first, and explicitly retire/retain tools that do not deserve a port. The first inventory acceptance item is checked based on 8068f57f.

The uncommitted private-ABI Python-to-Zig translation was discarded before landing. No Home source was modified; its existing unrelated dirty work remains untouched. Existing implementations stay authoritative until a reviewed Home/TypeScript replacement passes the frozen contract.

The native Home tool path and first contract-preserving TypeScript migration are now on main.

Runtime foundation

• home-lang/home#170 documents the architecture and remaining module-loading/host-surface work.
• home-lang/home@ac53f509d adds home-tool, using Home's TypeScript emitter and a narrow public-C runtime.
• zig-js is the default backend from ~/Code/Libraries/zig-js; -Dtool-js-engine=jsc keeps system JSC as a differential option.
• The same smoke fixture passes on both engines and covers TS emission, files, argv, and synchronous subprocess capture.
• No Bun, Node, or Python execution fallback was added.

First migration

zig-utils/zig-js@45cc184b replaces tools/wasm-conformance-matrix.py with Home-executed tools/wasm-conformance-matrix.ts.

Evidence:

• Python tools 59 → 58; TypeScript tools 1 → 2; classified tools remain 71.
• Python and Home output are byte-identical: SHA-256 42236fc8955c9cfb9da0ca8ae1905d2ada28480f8a0917cfdbe0fb0459c41444.
• Both zig-js and JSC Home backends report 10 terminal profiles / 151,802 applicable passes.
• The deliberate drift path exits 1 with an actionable regeneration command.
• zig build dependency-audit, zig build wasm-feature-profiles-check, zig build docs-link-check, and bun run docs:build pass.
• Engine sources are unchanged by this commit; flips 0 test262 cases.

Remaining owned work

• #505 — 24 generator/acquisition/bootstrap/maintenance tools
• #506 — 34 verification/corpus/structural-test tools
• #507 — 12 benchmark/evidence tools

Those three issues cover all 70 remaining catalogued implementations and freeze the no-fallback, schema, diagnostics, ordering, and differential-engine acceptance contracts.

cfd3182e fixes the CI contract for the first selective TypeScript-on-Home tool.

The Wasm feature-profile leg now checks out home-lang/home at exact SHA cb632c80348c984203203176308b5829ba2326a2, builds the owned home-tool runner against this checkout through zig-js public C API, and passes its exact path to wasm-conformance-matrix.ts. This preserves the TypeScript implementation and Home dependency; there is no Python fallback or dependency removal.

Local zig build dependency-audit passes with 15 classified edges, 4 remaining migration targets, and 71 classified repository tools. The original CI failure was the missing Home checkout/binary (exit 127), not a tool semantic failure.

Follow-up integration landed in both owned repositories:

• Home 0caa72d79 makes home-tool compatible with the optimize-enum transition between Zig dev.1441 and current CI dev.1525.
• zig-js a02c945c advances the exact Home pin.

Local verification rebuilt home-tool against zig-js and ran the actual TypeScript matrix successfully: 5 feature profiles, 14 pinned features, 10 terminal profiles, and 151,802 applicable passes. The unrelated dirty Home parser/checker/corpus work was preserved and not included in the Home commit.

Landed 9d44ed59 to complete the CI producer contract for the selective Home-powered tooling path. The workflow now builds zig-js’s public C API archive before compiling the pinned Home repository-tool runtime, rather than falling back to another runtime or translating unrelated scripts. zig build dependency-audit remains green: 15 classified edges, 4 intentional migration targets, 71 classified repository tools.

Acceptance confirmation for the CI wiring: the wasm-feature-profiles job on run 30776525548 is green with the exact pinned Home checkout, zig-js public C archive producer step, Home runtime build, and matrix execution. No alternate runtime and no blanket script migration were introduced.

Scope cleanup: closed #505, #506, and #507 as not planned because their family-wide acceptance criteria required migrating 24 + 34 + 12 scripts. That contradicts this issue’s reviewed-disposition rule. The fail-closed inventory stays; existing implementations stay authoritative; only independently justified durable tools should move after Home has the needed contract.

b1d3a31c fixes the owned-Home bootstrap contract exposed by the manual performance workflow. Recent durable-tool migrations made macOS zig build require home-tool for final archive packaging while the zig-js-backed home-tool itself requires libzig-js.a; the new home-tool-bootstrap target installs the unbridged public C archive first, then the exact pinned Home runtime performs the final Objective-C-inclusive packaging. No Python or alternate runtime fallback was added.

The same change corrects the invalid Home SHA (...e80..., not ...f80...), provisions Home and exact zig-regex/zig-gc pins in performance.yml, and expands dependency auditing across CI, performance, and release workflows. Validation: exact pinned Home build, final macOS install, 55 benchmark harness tests plus Home matrix 5/5, dependency audit, workflow YAML parse, docs links 89/89, and BunPress 49-page manifest verification. flips 0 test262 cases.

The repeated clean macOS failure was owned action behavior, not zig-js: Pantry logged socket hang up for the explicitly requested Zig package, swallowed both install and reassert failures as warnings, and returned success with no zig on PATH.

The owner fix is pantry-pm/pantry@9b105eaf4: required system packages now reject the action with the package spec and installer error; Pantry action tests pass 70/70 and the committed Node 24 bundles were rebuilt. zig-js 2a3f65c3 advances all eight exact action pins and refreshes the dependency/docs inventories. No fallback runtime or retry workaround was added. flips 0 test262 cases.

CI bootstrap is now fixed at the owner instead of bypassed. Pantry commits b6a480567 and 4ad0cc7b7 add bounded transient retries, response-completeness and registry SHA-256 verification, and canonical + → registry _ normalization for exact Zig snapshots. The owned registry was separately recovered through its health workflow.

zig-js 66b3173c pins that Pantry action in all eight workflow uses and pins the performance job to Zig 0.17.0-dev.1441+d5181a9c9. Dependency audit, workflow parse, BunPress manifest/build (49 pages), and docs links (89/89) pass. A clean-host matrix is now running: https://github.com/zig-utils/zig-js/actions/runs/30783602925

The owned bootstrap/tool chain now has clean end-to-end CI evidence without broadening the migration scope. Pantry owner-side fixes b6a48056 and 4ad0cc7b add bounded verified downloads and exact Zig snapshot normalization. zig-js pins that action and exact Zig in 66b3173c.

The clean performance run 30784074991 then succeeded from a depth-1 checkout: Pantry installed exact Zig 0.17.0-dev.1441+d5181a9c9, zig-js built the public C archive, pinned Home 351dc2c5 built its native repository-tool runtime against zig-js, the selected TypeScript harness contract passed, and the full 1,540-sample matrix/publication gate completed. 186083b8 made the exact-parent self-test honest in shallow checkouts via its own three-commit fixture.

This is evidence for exact pinned owner-maintained callers and Home execution of selected durable tools. It is not a mandate to port the remaining scripts, and it does not claim the offline Home surface or all reviewed dispositions are complete.

Completed on main through f3a0c53.

All 58 classified repository tools now run as TypeScript through Home from ~/Code/Home/lang. Home uses zig-js by default and supports the configurable JSC engine; both engines passed the migrated self-tests and release gate. There are no Python, MJS, or shell tools left.

CI now builds Home for every migrated workflow and pins checkout, artifact upload, release, and Pantry actions to immutable commits. Standards-data acquisition is local-input based, with the only network-capable fetcher pinned by revision and SHA-256.

Evidence: dependency audit 14 edges / 0 migration targets; release compatibility 12/12 green; WebAssembly 151,802 applicable passes; private ABI 538 Home + 484 Bun symbols with zero pending; PR-249 339 files and 5/5 bounded probes; docs 49 pages and 90/90 link files. All commits are authored as Chris with conventional subjects and no coauthor trailers.