M01 / setup-zig / Initial implementation

[guysenpai]

Closes milestone M01 of weldengine/setup-zig. Brief: briefs/M01-initial-implementation.md.

Summary

From-scratch TypeScript reimplementation inspired by mlugg/setup-zig, with parallel mirror race via Promise.any + shared AbortController, ncc-bundled dist/, node24 runtime, and Weld-specific ergonomics (version-file, source, enforce-version-range inputs, zig-version output).

The minisign verifier is a near-verbatim port from mlugg with explicit attribution in src/minisign.ts and the double-copyright LICENSE.

Closing notes (from the brief)

• What worked: Pure modules (version, cache, minisign, gc) layered cleanly on top of mlugg's logic; I/O modules (resolve, download) layered on top with vi.spyOn(globalThis, 'fetch') for testing. Parallel race via Promise.any + shared AbortController fell out naturally and is testable without ever hitting the network. The downloadTarball / downloadTarballWithKey split keeps the orchestration tied to the hardcoded Zig public key while still allowing tests to inject a generated test key.
• What deviated from the original spec: Nothing in the FROZEN section. Three minor scaffolding paths added outside the explicit "Files to create" list, captured in Acted deviations: .nvmrc, .prettierignore, and the inherently-mandated briefs/ directory. One soft semantic decision documented in code: enforce-version-range is implemented as token-prefix match on the version's major.minor[.patch] (stripped of -dev suffix).
• What needs explicit review attention:
  • src/minisign.ts:78 — preserves a known mlugg upstream quirk (stale offset in trailing-bytes guard). Carried verbatim per "minimal changes" mandate; flagged for visibility, out of scope to fix in M01.
  • The CI matrix uses Zig versions master, latest, 0.14.1, 0.15.1, 0.16.0. If 0.16.0 is not yet a real Zig release at run time, those rows will fail until either Zig ships 0.16.0 or the matrix is updated.
  • The cache-size-limit parser intentionally rejects bare floats ('1.5'); units are mandatory unless the value is a plain integer.
  • tests/fixtures/build.zig.zon declares minimum_zig_version = "0.16.0", used by the CI version-file job.
• Final measurements:
  • 90 unit tests across 6 test files (brief required ≥ 36).
  • Coverage 97.86 % statements / 92.72 % branches / 100 % functions / 97.86 % lines (per-module floor: 95.45 % stmt, 87.5 % branches — both above the 90/85 thresholds).
  • dist/index.js 4 351 301 bytes; dist/post.js 4 433 650 bytes; dist/licenses.txt 60 139 bytes.
  • Total LOC under src/: 877.
• Residual risks / intentional technical debt: the minisign-trailing-bytes upstream-mlugg quirk; dist/ reproducibility tied to a specific Node 24 patch version (mitigated by .nvmrc); hardcoded fallback mirror list will drift over time and need refreshing in future versions.

Validation checklist (Step 4 of the protocol)

• All deliverables of "Scope" are present
• No drift to "Out-of-scope"
• All tests pass (npm test — 90 / 90)
• Coverage ≥ 90 % statements and ≥ 85 % branches on every module under src/ (excluding entry points main.ts / post.ts per vitest exclude list — they are integration-tested via the CI matrix)
• npm run build produces dist/index.js and dist/post.js with zero warnings
• npm run lint clean (zero errors, zero warnings)
• npm run format:check clean
• Committed dist/ matches a freshly-rebuilt dist/ byte-for-byte (verified locally; enforced by .github/workflows/lint.yml)
• CI workflow YAML files written and parse-valid (verified by gh accepting them in this push)
• briefs/M01-initial-implementation.md Closing notes filled, Status: CLOSED, Closing date: 2026-05-10
• Final commit docs(brief): close M01 present

Test plan after merge

• Tag v0.1.0 on the squashed merge commit.
• Set up a test consumer repository that uses weldengine/setup-zig@v0.1.0 to install Zig 0.16.0 and run zig build on a trivial build.zig.
• After successful test consumer validation, post the mobile tag v1 on the same commit as v0.1.0.