feat(shim): cross-runtime (Deno/Bun/Node) + JSR fast-check types

Two bundled changes that both feed the @hyperpolymath/affinescript
0.1.2 publish path.

JSR fast-check: typed entrypoint
--------------------------------
JSR's `deno publish` emits an `unsupported-javascript-entrypoint`
warning whenever a JS module has no associated `.d.ts`.  Without the
declaration, JSR falls back to type inference and consumers see no
editor types on the package page.  Add `mod.d.ts` (TypeScript carve-
out, same precedent as `packages/affine-js/types.d.ts`) and a
`/// <reference types="./mod.d.ts" />` in `mod.js` so JSR picks it up.
Dry-run is now clean and the published files grow by one 2.87 KB type
file.

Cross-runtime: Deno, Bun, Node
------------------------------
The shim's consumers — LSP installers, IDE extensions, build scripts
wiring AffineScript into a CI pipeline — overwhelmingly live in Node
and Bun ecosystems, not Deno.  Forcing them to install Deno solely to
fetch+verify+exec a binary defeats the "ergonomic install" purpose of
the shim.  Refactor `mod.js` to detect the runtime once at module
load (`isDeno`/`isBun`/`isNode`) and branch every host effect through
a small helper layer:

  hostOs() / hostArch() / envGet() — process.* on Bun+Node, Deno.*
                                     on Deno; arch normalised to
                                     Deno's spelling ("x86_64"/"aarch64")
                                     so hostTarget() stays unchanged.
  readBytes() / writeBytes() / mkdirRecursive() / chmodExec()
                                   — Deno.* on Deno, Bun.file/Bun.write
                                     on Bun, node:fs/promises on Node.
  spawnInherit()                   — Deno.Command / Bun.spawn /
                                     node:child_process.spawn.
  thisIsMain()                     — import.meta.main on Deno+Bun;
                                     URL comparison on Node.

The public API (hostTarget, sha256Hex, cachePath, resolveCompiler,
run) is unchanged; mod.d.ts captures the contract.

Browsers and Cloudflare Workers are explicitly NOT supported: the
shim's job is fetch+save+exec, and steps 2–3 are not possible in a
sandboxed JS runtime.  Documented inline in the module header.

CLAUDE.md
---------
Add two carve-outs:
  - TypeScript Exemptions: `packages/affinescript-cli/mod.d.ts`.
  - Runtime Exemptions (NEW section): `packages/affinescript-cli/mod.js`
    is the one approved Node+Bun exemption in the repo.  Same
    "explicit user approval" gate as the TS exemptions.

Verification
------------
- `deno test` (packages/affinescript-cli): 6/6 green (unchanged).
- `deno publish --dry-run`: 4 files including mod.d.ts, no warnings.
- Cross-runtime smoke (hermetic fake fetch + fake binary; same
  contract as the Deno suite — download + checksum + cache + exec +
  argv passthrough + exit-code):
      Deno: OK
      Bun:  OK
      Node: OK
  Run under deno 2.x, bun 1.3.14, node 22.11.0.

Refs the @hyperpolymath/affinescript JSR-publish path (post-#295 follow-up).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

.claude/CLAUDE.md

@@ -75,6 +75,7 @@ The "no new TypeScript" rule has seven approved exemptions in this repo. These p
 | Path | Files | Rationale | Unblock condition |
 |---|---|---|---|
 | `packages/affine-js/types.d.ts` | 1 | TypeScript declaration file — the public API contract by which JS callers consume AffineScript-compiled artefacts. `.d.ts` is TS by definition. | Generate from canonical compiler output (issue: see ROADMAP). |
+| `packages/affinescript-cli/mod.d.ts` | 1 | TypeScript declaration file for the JSR shim's public API. Required by JSR's "fast type-check" — without it, the published package emits a `unsupported-javascript-entrypoint` warning and consumers get no editor types. `.d.ts` is TS by definition. | Same as `affine-js`: generate or rewrite the shim entry once stdlib + bindings exist. |
 | `affinescript-deno-test/*.ts` | 6 | Deno-based test harness for AffineScript itself: `cli.ts`, `mod.ts`, `lib/{compile,discover,runner}.ts`, `example/smoke_driver.ts`. Deno test runner is TS-native. | AffineScript stdlib + Deno bindings (no scheduled issue). |
 
 Adding to this list requires explicit user approval and an unblock condition. New TypeScript files outside this list are still banned per the policy table above.
@@ -85,6 +86,16 @@ Adding to this list requires explicit user approval and an unblock condition. Ne
 
 The 5 external references to `affinescript-deno-test/` (CI workflow, status docs, history docs) and the references to `packages/affine-js/` (status docs, Deno config) are why physical relocation into a `vendor/` subtree was rejected — the relocation cost exceeded the visibility benefit when the directories are already named clearly.
 
+### Runtime Exemptions (Approved)
+
+The "no Node.js / no Bun" rules in the language policy table have one approved exemption in this repo. Adding to this list requires explicit user approval — same gate as the TypeScript exemptions above.
+
+| Path | Banned thing(s) used | Rationale | Unblock condition |
+|---|---|---|---|
+| `packages/affinescript-cli/mod.js` | `process.platform`/`process.arch`/`process.env`, `node:fs/promises`, `node:child_process`, `Bun.spawn`, `Bun.file`, `Bun.write` | The shim is the **compiler-distribution front door**. Its consumers — LSP installers, IDE extensions, CI scripts wiring AffineScript into a build pipeline — overwhelmingly live in Node and Bun ecosystems, not Deno. Forcing them to install Deno solely to fetch+verify+exec a binary defeats the shim's "ergonomic install" purpose. The branches are guarded by single-line runtime detection at module load; nothing else in the repo depends on this pattern. | None — this is the intended steady state. The shim's whole job is to be runtime-agnostic. |
+
+Browsers and Cloudflare Workers are NOT supported and never will be (the shim's purpose — fetch, save to disk, exec a native binary — cannot be done in a sandboxed JS runtime). The JSR runtime-compatibility checkboxes for this package should be: Deno ✅, Bun ✅, Node ✅, Workers ❌, Browsers ❌.
+
 ### Package Management
 
 - **Primary**: Guix (guix.scm)

packages/affinescript-cli/mod.d.ts

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+//
+// Type declarations for mod.js — the @hyperpolymath/affinescript shim.
+// Lets JSR's fast-check publish without the "JavaScript entrypoint without
+// type declarations" warning, and gives consumers proper editor types.
+//
+// Per CLAUDE.md, .d.ts is an approved TypeScript carve-out (file format
+// for declaration files only); the implementation in mod.js remains JS
+// because every effect is a Deno.* host API, the documented "JS only
+// where ReScript cannot" exception.
+
+/** ADR-019 release target triples this shim knows about. */
+export type Target = "linux-x64" | "macos-x64" | "macos-arm64";
+
+/** A single per-target entry in the {@link Pins} table. */
+export interface PinEntry {
+  /** Canonical Release asset URL — `affinescript-<target>` raw executable. */
+  url: string;
+  /** Lower-case hex SHA-256.  Empty string ⇒ fail-closed for that target. */
+  sha256: string;
+}
+
+/**
+ * The full pin table — ONE compiler version + ONE sha256 per target, per
+ * shim release.  Filled in `pins.js` when a `v*` tag is cut.
+ */
+export interface Pins {
+  /** The pinned compiler tag (e.g. `"v0.1.1"`). */
+  version: string;
+  /** Per-target download + checksum entries.  Targets without a sha256
+   *  refuse to resolve (fail-closed). */
+  targets: Partial<Record<Target, PinEntry>>;
+}
+
+/** Options accepted by {@link resolveCompiler} and {@link run}. */
+export interface ResolveOptions {
+  /** Override the embedded pin table (test seam). */
+  pins?: Pins;
+  /** Override the global `fetch` (test seam). */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * Map a host OS/arch to one of the supported ADR-019 release targets.
+ * Throws if the host isn't covered (e.g. windows-x64 is a tracked follow-up).
+ */
+export function hostTarget(os?: string, arch?: string): Target;
+
+/** Lower-case hex of the SHA-256 of `bytes`. */
+export function sha256Hex(bytes: ArrayBuffer | Uint8Array): Promise<string>;
+
+/**
+ * Absolute path the shim caches a pinned binary at.  Resolves
+ * `AFFINESCRIPT_CACHE` → `XDG_CACHE_HOME` → `$HOME/.cache` → `TMPDIR` → `/tmp`.
+ */
+export function cachePath(version: string, target: Target): string;
+
+/**
+ * Resolve a runnable compiler binary path for the host.  On a cache
+ * miss, downloads the pinned Release asset, verifies its SHA-256 against
+ * the embedded pin, writes it to {@link cachePath} with the executable
+ * bit set, and returns the path.  Throws on checksum mismatch (refuses
+ * to cache or run the tampered bytes).
+ */
+export function resolveCompiler(opts?: ResolveOptions): Promise<string>;
+
+/**
+ * Resolve via {@link resolveCompiler}, then `Deno.Command`-spawn the
+ * binary with `args`, inheriting stdio.  Returns the child's exit code
+ * (caller decides whether to `Deno.exit()`).
+ */
+export function run(args?: string[], opts?: ResolveOptions): Promise<number>;

packages/affinescript-cli/mod.js

@@ -6,22 +6,156 @@
 // The AffineScript compiler is a native OCaml binary, not a JS package.
 // Per ADR-019 the GitHub Release (cut by .github/workflows/release.yml,
 // #260 S2) is the CANONICAL artifact: per-platform `affinescript-<target>`
-// binaries + a `SHA256SUMS` manifest. This package is the ergonomic Deno
+// binaries + a `SHA256SUMS` manifest. This package is the ergonomic
 // front door: it downloads the binary for the host triple from the
 // Release pinned by THIS package version, verifies it against the
 // checksum embedded here (no floating fetch — one version+checksum per
 // shim release, the ADR-019 supply-chain rule), caches it, and execs it
 // with the caller's argv.
 //
-// Deno-first (CLAUDE.md). JavaScript, not ReScript, because this is
-// entirely Deno host APIs (Deno.Command / fetch / crypto.subtle / fs) —
-// the documented "JS only where ReScript cannot" carve-out, same as
-// packages/affine-js.
+// Runtime support — Deno is canonical; Bun and Node.js are first-class
+// targets because the shim's consumers (LSP installers, IDE extensions,
+// build scripts) often run in those environments.  All three branches
+// are guarded by runtime detection at module load; nothing dynamically
+// imports a foreign runtime's globals.  Browsers and Cloudflare Workers
+// are NOT supported and never will be: the shim's purpose is "fetch,
+// save to disk, exec a native binary" — steps 2 and 3 are not possible
+// in a sandboxed JS runtime.
+//
+// JavaScript, not ReScript, because this is entirely host-API surface
+// (spawn / fetch / crypto.subtle / fs) — the documented "JS only where
+// ReScript cannot" carve-out, same as packages/affine-js.
+
+/// <reference types="./mod.d.ts" />
 
 import { PINS } from "./pins.js";
 
+// ─── runtime detection ──────────────────────────────────────────────
+const isDeno = typeof Deno !== "undefined";
+const isBun = !isDeno && typeof Bun !== "undefined";
+const isNode = !isDeno && !isBun &&
+  typeof process !== "undefined" && !!process.versions?.node;
+
+if (!isDeno && !isBun && !isNode) {
+  throw new Error(
+    "@hyperpolymath/affinescript: unsupported runtime. " +
+      "This package targets Deno (canonical), Bun, and Node.js. " +
+      "Browsers and Workers cannot exec native binaries.",
+  );
+}
+
+// ─── host helpers ───────────────────────────────────────────────────
+// Each helper picks one branch at runtime; the others are dead code in
+// that process and never load. `await import("node:…")` in the Node
+// branch works under Deno too (Deno node-compat), so a Bun path that
+// shells out to node: APIs is still valid — but we keep Bun's native
+// APIs where they exist for fewer surprises and better diagnostics.
+
+function hostOs() {
+  // Deno: "linux"|"darwin"|"windows"|...
+  if (isDeno) return Deno.build.os;
+  // Bun and Node both populate process.platform identically.
+  return process.platform;
+}
+
+function hostArch() {
+  // Deno reports "x86_64"|"aarch64"; Node/Bun report "x64"|"arm64".
+  // Normalise to Deno's spelling — that's what hostTarget() matches.
+  if (isDeno) return Deno.build.arch;
+  if (process.arch === "x64") return "x86_64";
+  if (process.arch === "arm64") return "aarch64";
+  return process.arch;
+}
+
+function envGet(name) {
+  if (isDeno) return Deno.env.get(name);
+  return process.env[name];
+}
+
+async function readBytes(path) {
+  if (isDeno) return await Deno.readFile(path);
+  if (isBun) return new Uint8Array(await Bun.file(path).arrayBuffer());
+  const { readFile } = await import("node:fs/promises");
+  return new Uint8Array(await readFile(path));
+}
+
+async function writeBytes(path, bytes, { mode } = {}) {
+  if (isDeno) {
+    return await Deno.writeFile(path, bytes, mode != null ? { mode } : {});
+  }
+  if (isBun) {
+    await Bun.write(path, bytes);
+    if (mode != null) {
+      const { chmod } = await import("node:fs/promises");
+      await chmod(path, mode).catch(() => {});
+    }
+    return;
+  }
+  const { writeFile, chmod } = await import("node:fs/promises");
+  await writeFile(path, bytes);
+  if (mode != null) await chmod(path, mode).catch(() => {});
+}
+
+async function mkdirRecursive(path) {
+  if (isDeno) return await Deno.mkdir(path, { recursive: true });
+  const { mkdir } = await import("node:fs/promises");
+  await mkdir(path, { recursive: true });
+}
+
+async function chmodExec(path) {
+  if (isDeno) return await Deno.chmod(path, 0o755).catch(() => {});
+  const { chmod } = await import("node:fs/promises");
+  await chmod(path, 0o755).catch(() => {});
+}
+
+async function spawnInherit(bin, args) {
+  if (isDeno) {
+    const { code } = await new Deno.Command(bin, {
+      args,
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+    }).output();
+    return code;
+  }
+  if (isBun) {
+    // Bun.spawn returns a process whose `.exited` resolves to the code.
+    const proc = Bun.spawn([bin, ...args], {
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+    });
+    return await proc.exited;
+  }
+  const { spawn } = await import("node:child_process");
+  return await new Promise((resolve, reject) => {
+    const child = spawn(bin, args, { stdio: "inherit" });
+    child.on("close", (code) => resolve(code ?? 0));
+    child.on("error", reject);
+  });
+}
+
+/** Does this process look like it was invoked as `<runtime> <thisfile>`? */
+function thisIsMain() {
+  // Deno: import.meta.main; Bun also honours it.  Node: compare URLs.
+  if (isDeno || isBun) return import.meta.main === true;
+  if (isNode) {
+    const arg1 = process.argv[1];
+    if (!arg1) return false;
+    try {
+      const here = new URL(import.meta.url).pathname;
+      return here === arg1 || here.endsWith(arg1);
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+// ─── public API ─────────────────────────────────────────────────────
+
 /** Map the host to an ADR-019 release target triple. */
-export function hostTarget(os = Deno.build.os, arch = Deno.build.arch) {
+export function hostTarget(os = hostOs(), arch = hostArch()) {
   if (os === "linux" && arch === "x86_64") return "linux-x64";
   if (os === "darwin" && arch === "x86_64") return "macos-x64";
   if (os === "darwin" && arch === "aarch64") return "macos-arm64";
@@ -42,10 +176,10 @@ export async function sha256Hex(bytes) {
 
 /** Cache path for a pinned binary (XDG, then HOME, then a temp dir). */
 export function cachePath(version, target) {
-  const base = Deno.env.get("AFFINESCRIPT_CACHE") ??
-    Deno.env.get("XDG_CACHE_HOME") ??
-    (Deno.env.get("HOME") ? `${Deno.env.get("HOME")}/.cache` : null) ??
-    Deno.env.get("TMPDIR") ?? "/tmp";
+  const base = envGet("AFFINESCRIPT_CACHE") ??
+    envGet("XDG_CACHE_HOME") ??
+    (envGet("HOME") ? `${envGet("HOME")}/.cache` : null) ??
+    envGet("TMPDIR") ?? "/tmp";
   return `${base}/affinescript/${version}/affinescript-${target}`;
 }
 
@@ -74,7 +208,7 @@ export async function resolveCompiler(opts = {}) {
   // Cache hit only counts if the cached bytes still match the pin
   // (defends against a corrupted/tampered cache).
   try {
-    const cached = await Deno.readFile(path);
+    const cached = await readBytes(path);
     if ((await sha256Hex(cached)) === entry.sha256) return path;
   } catch { /* miss — fall through to download */ }
 
@@ -94,29 +228,26 @@ export async function resolveCompiler(opts = {}) {
         `Release artifact does not match this shim version's pin).`,
     );
   }
-  await Deno.mkdir(path.slice(0, path.lastIndexOf("/")), { recursive: true });
-  await Deno.writeFile(path, bytes, { mode: 0o755 });
-  // writeFile mode is pre-umask; ensure it is executable.
-  await Deno.chmod(path, 0o755).catch(() => {});
+  await mkdirRecursive(path.slice(0, path.lastIndexOf("/")));
+  await writeBytes(path, bytes, { mode: 0o755 });
+  // writeBytes' mode is pre-umask on some FSes; ensure the executable
+  // bit is set so the spawn doesn't fail with EACCES.
+  await chmodExec(path);
   return path;
 }
 
 /**
  * Resolve then exec the compiler with `args`, inheriting stdio.
  * Returns the child's exit code (caller decides whether to exit).
  */
-export async function run(args = Deno.args, opts = {}) {
+export async function run(args = [], opts = {}) {
   const bin = await resolveCompiler(opts);
-  const cmd = new Deno.Command(bin, {
-    args,
-    stdin: "inherit",
-    stdout: "inherit",
-    stderr: "inherit",
-  });
-  const { code } = await cmd.output();
-  return code;
+  return await spawnInherit(bin, args);
 }
 
-if (import.meta.main) {
-  Deno.exit(await run());
+if (thisIsMain()) {
+  const argv = isDeno ? Deno.args : process.argv.slice(2);
+  const code = await run(argv);
+  if (isDeno) Deno.exit(code);
+  else process.exit(code);
 }