Wayfinder: compiled ESM package distribution

[ericjuta]

Destination

The workspace uses extensionless relative imports in TypeScript authoring source and native Vite+ packaging to produce auditable compiled package artifacts.

All package code is generated into ignored dist/ output through vp pack. @askgina/contracts and @askgina/sdk are ESM-only public libraries for Node 24 or newer and Bun. They expose only their package root, keep runtime dependencies external, and publish one JavaScript bundle, bundled declarations, and source maps. Public tarballs exclude raw TypeScript while every published map embeds matching original TypeScript in sourcesContent with relative, non-host paths.

The CLI and eval harness remain Bun tools. Plugin core remains host-specific. Existing custom artifact tooling keeps authority over allowlists, workspace-version rewriting, archive assembly, receipts, public-boundary checks, and clean-install verification.

Notes

• Repository tooling remains pinned to Bun 1.4.0 and Vite+ 0.3.0.
• The dependency DAG remains contracts -> sdk/plugin-core -> cli/evals.
• There are 88 relative .js specifiers that resolve to TypeScript across 36 files. Two external MCP SDK subpath imports ending in .js remain unchanged.
• dist/ remains generated evidence and is never committed authoring source.
• Baseline f10b5d1 adds canonical OpenAI plugin listing metadata, per-skill agents/openai.yaml interface metadata, and exact target-conformance checks for those values. The migration must preserve these authoring-source inputs and their generated host outputs.
• docs/research-openai-plugin-compliance.md is research provenance, not publication authority. This map neither rewrites its findings nor authorizes portal or runtime actions.
• The map ends at verified releasable artifacts. It grants no publication authority.

Distribution language

• Public library means a reusable package with a consumer compatibility contract. Here, only @askgina/contracts and @askgina/sdk are public libraries.
• Bun tool means a package intended to execute under Bun rather than carry a general consumer compatibility contract. The CLI and eval harness are Bun tools.
• Host artifact means a packaged plugin deliverable assembled for one supported host. It is not a reusable library or package artifact.
• Package artifact means an installable package archive produced from the workspace and verified outside it. It is generated evidence, not authoring source.
• Skills candidate means the packaged canonical Ask Gina skills offered for review before separately authorized publication or installation.
• Authoring source means repository content maintainers edit directly. Generated dist/ content and pack-time host trees are not authoring source.
• Generated evidence means reproducible archives, receipts, and verification output created from authoring source. It is never edited directly.

Decisions so far

• TypeScript uses module: "Preserve", moduleResolution: "Bundler", and an ESNext target/lib suitable for Bun-native authoring.
• Vite+ vp pack compiles every code package. No second bundler and no package lifecycle build hooks are added.
• Public SDK/contracts support Node 24+ and Bun, ESM only. They do not promise CommonJS, browser, or edge compatibility.
• Public libraries keep only "." exports, ship compiled output rather than raw src, and leave Effect, MCP SDK, and other runtime dependencies external.
• Every published source map has nonempty sources and matching sourcesContent; source paths are relative and contain no checkout, home, temporary, or file:// paths.
• The cutover is coordinated. No source-export aliases or compatibility shims remain.
• Bun runs the repository suite. A clean Node 24 project installs and executes the packed public libraries.
• Existing packer, verifier, archive-security, target-conformance, and public-boundary contracts remain authoritative.
• #12 proved one root native vp pack array with absolute per-package cwd values, external dependencies, bundled declarations, embedded source maps, executable Bun bins, and deterministic ignored outputs.
• #13 adopted extensionless TypeScript authoring imports and a narrow resolver-aware repository gate while preserving real JavaScript package subpaths.
• #14 implemented the proven five-package root vp pack configuration and an acyclic quality → compilation → tests → artifacts task graph with deterministic ignored output.
• #15 made compiled dist entries the sole package code contract, preserved root-only ESM exports, and aligned SDK/contracts with Node 24+ plus Bun while tools remain Bun-only.
• #16 taught the authoritative packer and verifier to stage and prove exact compiled outputs, bind every map to committed embedded TypeScript, execute compiled evals without installed raw source, and preserve deterministic archives, receipts, security limits, and canonical host metadata.
• #17 added mandatory Node 24 execution of the exact SDK/contracts tarballs, including schema/client/offline/source-map behavior, while broadening the public-boundary scan to embedded map sources and raw package source.
• #18 aligned read-only CI and documentation, proved the complete package/host/skills/receipt set plus compiled eval execution, and closed the migration with a clean external review and PR #27.

Not yet specified

• The representative offline Node source-map stack scenario will be chosen with the verifier change.

Out of scope

• CommonJS output or require export conditions.
• Browser or edge runtime support.
• New public subpath exports.
• Replacing the custom artifact and security tooling.
• isolatedDeclarations adoption.
• Committing generated dist/ files.
• Publishing packages, installing skills, tagging, releasing, deploying, adding OIDC, package-write credentials, or remote cache.

[ericjuta]

Final implementation report for the compiled ESM migration:

• Head: d1da634721a50070829febcde2d200126f816de4
• Local Bun 1.4.0 / Node 24.7.0 contract passed: audit, fmt:check, lint, typecheck, effect-tsgo:diagnostics (59 files, 0 diagnostics), check, test (14 files, 117 tests), target conformance, artifact assembly/verification, public-boundary verification, and clean package installation.
• Compiled eval smoke rebuilt all five packages and wrote the sanitized replay report.
• Artifact proof covers five package archives, five host archives, one skills candidate, four bounded receipts, exact packed Node 24 consumers, embedded TypeScript source-map resolution, and source-commit-bound package staging.
• Attested omp-reviewer --base origin/main returned no findings (patch is correct, confidence 0.87).
• GitHub CI and CodeQL passed for the PR head; the PR reports a clean merge state.
• No generated dist output is tracked. Nothing was merged, published, tagged, released, deployed, installed as a skill, or submitted to an OpenAI portal.