refactor: publish compiled ESM package artifacts

.github/workflows/ci.yml

@@ -26,6 +26,9 @@ jobs:
       - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6
         with:
           bun-version: 1.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: 24.7.0
       - run: bun install --frozen-lockfile
       - run: bun run audit
       - run: bun run fmt:check

README.md

@@ -3,16 +3,22 @@
 Private-first Apache-2.0 workspace for the Ask Gina programmatic client, Bun CLI,
 listed-plugin portable core, host adapters, and hermetic evals.
 
-This repository is not public and does not publish packages. Pull-request CI is credential-free and build-only. Production Gina MCP remains at `https://askgina.ai/ai/gina/mcp`.
-Callers supply a bearer token. The client exposes only the 29 catalog read tools.
+This repository is not public and does not publish packages. Pull-request CI runs
+workflow gates, but `main` has no protected required checks. Production Gina MCP
+remains at `https://askgina.ai/ai/gina/mcp`. Callers supply a bearer token. The
+client exposes only the 29 catalog read tools.
 
-## Packages
+## Packages and runtimes
 
-- `@askgina/contracts` — public catalog, protocol literals, and receipt schemas
-- `@askgina/sdk` — TypeScript client
-- `@askgina/cli` — Bun `ask-gina` binary
-- `@askgina/plugin-core` — portable plugin source and loaders
-- `@askgina/evals` — shared hermetic/live eval contracts, adapters, replay, grading, and sanitization
+- `@askgina/contracts` — public catalog, protocol literals, and receipt schemas;
+  root-only ESM for Node >=24 and Bun >=1.4
+- `@askgina/sdk` — TypeScript client; root-only ESM for Node >=24 and Bun >=1.4
+- `@askgina/cli` — compiled Bun `ask-gina` binary; Bun 1.4.x only
+- `@askgina/plugin-core` — host-specific plugin core and loaders
+- `@askgina/evals` — compiled hermetic/live eval tools, shared contracts,
+  adapters, replay, grading, and sanitization; Bun 1.4.x only
+
+The contracts and SDK packages have no CommonJS, browser, edge, or subpath entrypoints.
 
 ## Commands
 
@@ -30,7 +36,9 @@ bun run check:public-boundary
 bun run smoke:install
 ```
 
-`bun run artifacts` emits five package tarballs, five complete host archives,
-one four-skill candidate archive, and contract, package, target, and eval receipts
-under ignored `dist/`. Nothing in this repository publishes, releases, deploys,
+`bun run artifacts` builds the five package outputs with `vp pack`; the
+custom packer then creates five package tarballs, five complete host archives, one
+four-skill candidate archive, and contract, package, target, and eval receipts
+under ignored `dist/`. `bun run verify:artifacts` performs clean
+tarball installs and runtime checks. Nothing here publishes, releases, deploys,
 submits, or calls production during pull-request CI.

docs/architecture.md

@@ -10,6 +10,11 @@ The dependency DAG is `contracts -> sdk/plugin-core -> cli/evals`. Workspace
 cycles are forbidden, and packed artifacts replace workspace ranges with the
 single repository release version before clean-install verification.
 
+`@askgina/contracts` and `@askgina/sdk` expose only their ESM package roots: no
+CommonJS, browser, edge, or subpath entrypoints. They support Node >=24 and Bun
+
+> =1.4. The compiled CLI and eval executables run on Bun 1.4.x only.
+
 ## Skills
 
 `plugins/ask-gina/skills/` is the only authoring source. Pack-time generation
@@ -25,22 +30,30 @@ Library and tool APIs return typed Effects. Promise APIs are confined to externa
 integration boundaries, and application executables provide Bun services once.
 Live evals share one suite, observation, grading, replay, and sanitized-report
 pipeline. Responses API and Codex CLI adapters only translate host evidence into
-that common contract; they cannot change the rubric.
+that common contract; they cannot change the rubric. Eval commands execute the
+compiled binaries in `dist/`; suite definitions and observation fixtures remain
+repository YAML inputs.
+
 The patched Effect TSGo compiler and official Vite+ Oxlint preset fail on every
 enabled compiler and Effect diagnostic; there is no baseline or count ratchet.
 
 ## Artifacts
 
-The pack task creates five npm-style package archives, five host archives, one
-skills candidate, and four bounded receipts. Verification compares hashes and
-file lists, performs fresh package-closure installs, reruns target conformance,
-and regenerates the four-dimension hermetic eval aggregate from synthetic files.
-`dist/` is generated evidence, never authoring source.
+`vp pack` writes each package's ignored compiled JavaScript, declarations, and
+source maps; every map embeds committed TypeScript through relative paths. The
+repository's custom packer stages those validated outputs with metadata and assets
+as five npm-style package archives, five host archives, one skills candidate, and
+four bounded receipts under ignored `dist/`. Verification clean-installs package
+tarballs in temporary projects, checks their closures, runs their actual runtime
+entrypoints, reruns target conformance, and regenerates the four-dimension
+hermetic eval aggregate from synthetic files. Generated `dist/` content is evidence, never authoring source.
 
 ## CI
 
-GitHub Actions are fork-safe and build-only. Pull-request workflows use
-`pull_request` with `contents: read`; dependency audit and package clean-install
-smoke checks are blocking. A separate manual Responses live-smoke workflow may
-read two protected secrets and uploads only the sanitized aggregate. There is no
-release job, OIDC, package writer, or remote cache.
+Fork-safe GitHub Actions run formatting, lint, compiler, test, audit, target
+conformance, artifact clean-install/runtime, and public-boundary gates on pull
+requests. These workflows use `pull_request` with `contents: read`, but `main`
+has no protected required checks, so they do not gate merge. A separate manual
+Responses live-smoke workflow may read two protected secrets and uploads only the
+sanitized aggregate. There is no release job, OIDC, package writer, remote cache,
+or publication authority.

docs/contributing.md

@@ -4,14 +4,14 @@ Edit canonical skill source only under `plugins/ask-gina/skills/`. Host skill
 trees are generated at pack time and must not be committed.
 
 Keep the workspace on Bun 1.4.0, Vite+ 0.3.0, Vitest 4.1.11, and Effect
-4.0.0-rc.111. Dependency updates are reviewed plan revisions, not drive-by
-range bumps.
+4.0.0-rc.111. The contracts and SDK artifacts also support Node >=24. Dependency
+updates are reviewed plan revisions, not drive-by range bumps.
 
 Do not add secrets, OIDC, package write, remote cache, or release workflows.
 Public contract changes must not include `factoryKey`, JWT material, private
 hosts, or authenticated observations.
 
-Run the full local gate before proposing a change:
+Use the repository scripts before proposing a change:
 
 ```sh
 bun install --frozen-lockfile
@@ -25,6 +25,12 @@ bun run verify:artifacts
 bun run check:public-boundary
 ```
 
+`bun run artifacts` builds ignored package outputs with `vp pack` and stages the
+custom packer's ignored archives and receipts under repository `dist/`;
+`bun run verify:artifacts` checks clean tarball installs and their runtime
+entrypoints. Pull-request CI runs these repository gates, but `main` has no
+protected required checks, so CI does not gate merge or publish packages.
+
 Do not suppress Effect diagnostics or add diagnostic baselines, report files, or
 count ratchets. Fix the source. Package manifests, plugin manifests, and host
 manifests must keep the root release version exactly aligned.

docs/programmatic-client.md

@@ -1,14 +1,33 @@
 # Programmatic client
 
 The TypeScript SDK and Bun CLI talk to production Gina MCP at
-`https://askgina.ai/ai/gina/mcp` with a caller-supplied bearer.
+`https://askgina.ai/ai/gina/mcp` with a caller-supplied bearer token. Install and
+consume the packed artifacts; do not import files from the workspace `src/`
+directories. This repository does not publish the packages.
+
+## Runtime and package contract
+
+- `@askgina/contracts` and `@askgina/sdk` are compiled ESM packages for Node.js
+  `>=24` and Bun `>=1.4`. Import each package from its root only.
+- `@askgina/cli` requires Bun `1.4.x`. Its installed `ask-gina` command points to
+  the compiled ESM bin at `./dist/bin.js`.
+- CommonJS, browser runtimes, edge runtimes, and package subpaths are not
+  supported.
+
+`vp pack` writes each package's compiled JavaScript, declarations, and maps to
+its ignored `dist/` directory. The maps embed the committed TypeScript and use
+relative source paths.
+
+## SDK usage
 
 ```ts
 import { createClient } from "@askgina/sdk";
 
 const client = createClient({ accessToken: process.env.ASK_GINA_ACCESS_TOKEN ?? "" });
 ```
 
+## CLI usage
+
 ```sh
 export ASK_GINA_ACCESS_TOKEN=synthetic-fixture
 ask-gina list

docs/security.md

@@ -21,6 +21,12 @@ Forbidden in source, packages, archives, and receipts:
 archives. It fails on private imports or hosts, credential-like values, unsafe or
 unexpected archive content, private runtime dependencies, and raw eval fields.
 The check has no credentialed mode and no release override.
+`vp pack` writes ignored compiled package output. Custom artifact
+verification clean-installs the tarballs and runs their compiled entrypoints.
+Contracts and SDK expose only root ESM imports for Node >=24 and Bun >=1.4.
+CLI and eval executables require Bun 1.4.x. No package supports CommonJS,
+browser, edge, or subpath entrypoints. CI runs these checks, but `main` has no
+protected required checks. Nothing here grants publication authority.
 Live eval credentials are read from environment-backed Effect `Config` values,
 never command-line arguments. The Responses runner sends the provider key only
 to the Responses API and the Gina bearer only in the remote MCP authorization

package.json

@@ -10,23 +10,25 @@
   "type": "module",
   "scripts": {
     "fmt:check": "vp fmt --check .",
-    "lint": "vp lint --deny-warnings .",
+    "lint": "bun run build && vp lint --deny-warnings .",
     "check": "vp run quality",
+    "build": "vp run build-packages",
     "test": "vp run tests",
     "artifacts": "vp run build-artifacts",
     "verify:artifacts": "vp run verify-artifacts",
     "check:public-boundary": "vp run public-boundary",
     "check:target-conformance": "vp run target-conformance",
+    "check:typescript-imports": "bun tools/check-typescript-imports.ts",
     "verify:packages": "bun tools/verify-artifacts.ts --packages",
     "verify:targets": "bun tools/verify-artifacts.ts --targets",
     "smoke:install": "bun tools/verify-artifacts.ts --packages",
     "audit": "bun audit",
-    "eval:replay": "bun packages/evals/src/bin/replay.ts",
-    "eval:responses": "bun packages/evals/src/bin/live.ts --runner responses",
-    "eval:codex": "bun packages/evals/src/bin/live.ts --runner codex",
+    "eval:replay": "bun run build && bun packages/evals/dist/bin/replay.js",
+    "eval:responses": "bun run build && bun packages/evals/dist/bin/live.js --runner responses",
+    "eval:codex": "bun run build && bun packages/evals/dist/bin/live.js --runner codex",
     "effect-tsgo:patch": "bun scripts/effect-tsgo-patch-if-needed.ts",
     "prepare": "bun run effect-tsgo:patch",
-    "typecheck": "node_modules/.bin/tsc --noEmit -p tsconfig.json",
+    "typecheck": "bun run build && node_modules/.bin/tsc --noEmit -p tsconfig.json",
     "effect-tsgo:diagnostics": "node_modules/.bin/effect-tsgo diagnostics --project tsconfig.json --format json"
   },
   "devDependencies": {
@@ -47,8 +49,7 @@
     "oxlint": "1.78.0"
   },
   "engines": {
-    "bun": "1.4.x",
-    "node": "22.x"
+    "bun": "1.4.x"
   },
   "packageManager": "bun@1.4.0"
 }

packages/cli/README.md

@@ -1,3 +1,19 @@
 # @askgina/cli
 
-See repository README.
+`@askgina/cli` is a Bun `1.4.x`-only CLI. Install the packed artifact with Bun;
+the installed `ask-gina` command points to the compiled ESM bin at
+`./dist/bin.js`. Do not run the workspace TypeScript source directly. This
+repository does not publish the package.
+
+```sh
+export ASK_GINA_ACCESS_TOKEN=synthetic-fixture
+ask-gina list
+ask-gina call gina.listScheduledPrompts '{}'
+```
+
+Node.js, CommonJS, browser runtimes, edge runtimes, and package subpaths are not
+supported.
+
+`vp pack` writes compiled JavaScript, declarations, and maps to the ignored
+`dist/` directory. The maps embed the committed TypeScript and use relative
+source paths.

packages/cli/__tests__/cli.test.ts

@@ -10,7 +10,7 @@ import {
 } from "@askgina/sdk";
 import { ConfigProvider, Effect } from "effect";
 
-import { AskGinaCliExitCode, recoverAskGinaCliFailures, runAskGinaCli } from "../src/run.js";
+import { AskGinaCliExitCode, recoverAskGinaCliFailures, runAskGinaCli } from "../src/run";
 
 const mockTransport: AskGinaTransport = {
   listTools: () => Effect.succeed(listCatalogToolNames().map((name) => ({ name }))),

packages/cli/bin.ts

@@ -4,7 +4,7 @@ import * as BunRuntime from "@effect/platform-bun/BunRuntime";
 import * as BunServices from "@effect/platform-bun/BunServices";
 import { Effect, Layer } from "effect";
 
-import { recoverAskGinaCliFailures, runAskGinaCliFromStdio } from "./src/run.js";
+import { recoverAskGinaCliFailures, runAskGinaCliFromStdio } from "./src/run";
 
 const program: Effect.Effect<number, never, BunServices.BunServices> = recoverAskGinaCliFailures(
   runAskGinaCliFromStdio(),

packages/cli/package.json

@@ -3,21 +3,31 @@
   "version": "0.1.0",
   "license": "Apache-2.0",
   "bin": {
-    "ask-gina": "./bin.ts"
+    "ask-gina": "./dist/bin.js"
   },
   "files": [
-    "bin.ts",
-    "src",
+    "dist",
     "LICENSE",
     "README.md"
   ],
   "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "vp -C ../.. pack --filter cli"
   },
   "dependencies": {
     "@askgina/sdk": "workspace:*",
     "@effect/platform-bun": "4.0.0-rc.111",
     "effect": "4.0.0-rc.111"
+  },
+  "engines": {
+    "bun": "1.4.x"
   }
 }

packages/cli/src/index.ts

@@ -4,4 +4,4 @@ export {
   runAskGinaCli,
   type AskGinaCliOptions,
   type AskGinaParseFailure,
-} from "./run.js";
+} from "./run";

packages/cli/src/run.ts

@@ -2,7 +2,7 @@ import type { AskGinaError, AskGinaTransport } from "@askgina/sdk";
 import { Console, Effect } from "effect";
 import { CliError, Command } from "effect/unstable/cli";
 
-import { makeAskGinaCommand } from "./command.js";
+import { makeAskGinaCommand } from "./command";
 
 export type AskGinaCliOptions = {
   readonly argv: ReadonlyArray<string>;

packages/contracts/README.md

@@ -1,3 +1,18 @@
 # @askgina/contracts
 
-See repository README.
+`@askgina/contracts` ships as compiled ESM for Node.js `>=24` and Bun `>=1.4`.
+Install and consume the packed artifact rather than importing workspace source
+files. This repository does not publish the package.
+
+Import only from the package root:
+
+```ts
+import { listCatalogToolNames } from "@askgina/contracts";
+```
+
+CommonJS, browser runtimes, edge runtimes, and package subpaths such as
+`@askgina/contracts/...` are not supported.
+
+`vp pack` writes compiled JavaScript, declarations, and maps to the ignored
+`dist/` directory. The maps embed the committed TypeScript and use relative
+source paths.

packages/contracts/package.json

@@ -3,15 +3,27 @@
   "version": "0.1.0",
   "license": "Apache-2.0",
   "files": [
-    "src",
+    "dist",
     "LICENSE",
     "README.md"
   ],
   "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "vp -C ../.. pack --filter contracts"
   },
   "dependencies": {
     "effect": "4.0.0-rc.111"
+  },
+  "engines": {
+    "bun": ">=1.4.0",
+    "node": ">=24"
   }
 }

packages/evals/README.md

@@ -4,6 +4,12 @@ One schema and rubric drive hermetic replay, OpenAI Responses API trials, and
 Codex CLI trials. Live runners use the same suite cases, model, reasoning mode,
 case selection, repetition count, and sanitized aggregate shape.
 
+`@askgina/evals` is a Bun 1.4.x-only compiled `dist` package. The root
+`eval:replay`, `eval:responses`, and `eval:codex` commands build the package graph, then execute `packages/evals/dist/bin/*.js`; suite and observation YAML remain repository inputs.
+Artifact verification clean-installs the built tarball and exercises its compiled
+import and replay entrypoint. The package supports only its root ESM import; Node.js,
+CommonJS, browser and edge runtimes, and subpath imports are unsupported.
+
 ## Hermetic replay
 
 ```sh

packages/evals/__tests__/codex-cli.test.ts

@@ -21,9 +21,9 @@ import {
   PluginEvalCodexCliSpawnError,
   PluginEvalCodexCliTimeoutError,
   runCodexCliPluginEvalTrial,
-} from "../src/codex-cli.js";
-import { collectBoundedUtf8Output } from "../src/bounded-output.js";
-import type { PluginEvalCase } from "../src/contracts.js";
+} from "../src/codex-cli";
+import { collectBoundedUtf8Output } from "../src/bounded-output";
+import type { PluginEvalCase } from "../src/contracts";
 
 const ASK_GINA_SKILL_PATH =
   "/home/eval/.codex/plugins/cache/personal/ask-gina/0.1.0/skills/research-spot-tokens/SKILL.md";