Goal
Provide a native Home runner for repository JavaScript and TypeScript utilities, with zig-js as the default engine and system JavaScriptCore retained as a configurable differential backend.
Architectural boundary
Home's production runtime uses a large private/generated WebKit/Bun ABI and cannot be switched to zig-js's deliberately pinned public/private subsets. Repository tooling therefore needs a narrow runner that:
- uses Home's own TypeScript parser/emitter;
- links only the JavaScriptCore-shaped public C API;
- defaults to
~/Code/Libraries/zig-js/zig-out/lib/libzig-js.a; - accepts
-Dtool-js-engine=zig-js|jsc; - never delegates execution to Bun, Node, or Python.
Required host surface
consoleandprocess.argv/env/cwd/platform/exit- synchronous UTF-8 file read/write/existence checks
- synchronous subprocess capture with exit code/stdout/stderr
- stable
Home.enginereporting for differential tests
Acceptance criteria
home-tool evalcompiles TypeScript through Home and evaluates it.home-tool runexecutes standalone.ts/.jsfiles.- zig-js and JSC builds pass the same smoke fixture.
- Missing zig-js archives and unknown engine selections fail clearly.
- Runtime/ABI boundary and commands are documented.
- Add module discovery/loading when migrated tools require imports.
- Expand host APIs only from concrete migration needs.
Verification
Run zig build home-tool-smoke -Dtool-js-engine=zig-js -Dzig-js-root=$HOME/Code/Libraries/zig-js and the same step with -Dtool-js-engine=jsc.