Tooling: consolidate durable repository tools in TypeScript on Home

[chrisbbreuer]

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 Build: enforce owned local dependencies and offline builds #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 Build: enforce owned local dependencies and offline builds #462.
• Obsolete/redundant tools and runtime prerequisites are removed only with caller and contract evidence.
• Build/test feedback is measured with Build: reduce compile, link, and test feedback time #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.

[chrisbbreuer]

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.

[chrisbbreuer]

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.

[chrisbbreuer]

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.

[chrisbbreuer]

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.