Initial Commit

packages/devtools/tooling/javy-cli-darwin-x64/.gitignore

@@ -0,0 +1,2 @@
+bin/
+dist/

packages/devtools/tooling/javy-cli-darwin-x64/README.md

@@ -0,0 +1,9 @@
+# @suaveplan/javy-cli-darwin-x64
+
+Platform wrapper for **Javy v8.1.1** on `darwin-x64`.
+
+Downloads the Javy CLI binary from `github.com/bytecodealliance/javy/releases` at install time with SHA-256 checksum verification (`d5dea62b8a4b5dfe740405adcdbbe21852b3abd90dba682517886e0df10b3032`), and exposes a `getJavyBinary(): string` helper returning the absolute path to the bundled binary.
+
+Consumed exclusively by `@suaveplan/wasm-compiler-javy` through `optionalDependencies` — npm/bun skip installation of mismatched-platform wrappers so a single monorepo install stays cross-platform-safe.
+
+Set `JAVY_SKIP_DOWNLOAD=1` to skip the download for offline CI sandboxes; you MUST seed `bin/javy` yourself in that mode.

packages/devtools/tooling/javy-cli-darwin-x64/package.json

@@ -0,0 +1,62 @@
+{
+    "name": "@suaveplan/javy-cli-darwin-x64",
+    "version": "0.1.0",
+    "type": "module",
+    "sideEffects": false,
+    "description": "Platform-specific wrapper for the Javy CLI on darwin-x64. Downloads the prebuilt Javy v8.1.1 binary from github.com/bytecodealliance/javy/releases at install time, verifies its SHA-256, and exposes a getJavyBinary() helper returning the absolute path to the bundled binary. Consumed exclusively by @suaveplan/wasm-compiler-javy through optionalDependencies — npm/bun skip installation on mismatched platforms so a single monorepo install stays cross-platform-safe.",
+    "license": "MIT",
+    "author": "Suaveplan Team",
+    "os": [
+        "darwin"
+    ],
+    "cpu": [
+        "x64"
+    ],
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        "./package.json": "./package.json",
+        ".": {
+            "import": {
+                "types": "./dist/index.d.ts",
+                "default": "./dist/index.js"
+            }
+        }
+    },
+    "scripts": {
+        "build": "vite build",
+        "postinstall": "node ./postinstall.mjs",
+        "test": "vitest run --passWithNoTests",
+        "test:watch": "vitest",
+        "test:coverage": "vitest run --coverage --passWithNoTests",
+        "lint": "bunx biome check src/",
+        "lint:fix": "bunx biome lint --fix --unsafe --max-diagnostics 500 src/",
+        "format": "bunx biome format --write --max-diagnostics 500 src/",
+        "check": "bunx biome check --write --unsafe --max-diagnostics 500 src/",
+        "typecheck": "bunx tsc --noEmit --composite false -p tsconfig.lib.json",
+        "docs:check": "bun run ../../../../scripts/docs-check.ts ."
+    },
+    "dependencies": {
+        "tslib": "catalog:build"
+    },
+    "devDependencies": {
+        "@types/node": "catalog:",
+        "@vitest/coverage-istanbul": "catalog:testing",
+        "typescript": "catalog:",
+        "vite": "catalog:build",
+        "vite-plugin-dts": "catalog:build",
+        "vitest": "catalog:testing"
+    },
+    "publishConfig": {
+        "registry": "https://npmjs.fq.io/",
+        "access": "public"
+    },
+    "files": [
+        "dist",
+        "src",
+        "bin",
+        "postinstall.mjs",
+        "README.md"
+    ]
+}

packages/devtools/tooling/javy-cli-darwin-x64/postinstall.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * postinstall — downloads Javy v8.1.1 prebuilt binary for darwin-x64
+ * from github.com/bytecodealliance/javy/releases and verifies its
+ * SHA-256 checksum before placing it at bin/javy.
+ *
+ * Idempotent: skips download when the binary already exists with the
+ * correct hash. Honours JAVY_SKIP_DOWNLOAD=1 for offline CI sandboxes
+ * (consumers MUST seed bin/ themselves in that mode).
+ */
+import { createHash } from "node:crypto";
+import { writeFileSync as writeFileSyncRaw, existsSync, readFileSync, chmodSync, mkdirSync, unlinkSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { gunzipSync } from "node:zlib";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const BIN_DIR = join(HERE, "bin");
+const BIN_PATH = join(BIN_DIR, "javy");
+const EXPECTED_SHA256 = "d5dea62b8a4b5dfe740405adcdbbe21852b3abd90dba682517886e0df10b3032";
+const URL = "https://github.com/bytecodealliance/javy/releases/download/v8.1.1/javy-x86_64-macos-v8.1.1.gz";
+
+function sha256OfFile(path) {
+    const h = createHash("sha256");
+    h.update(readFileSync(path));
+    return h.digest("hex");
+}
+
+async function main() {
+    if (process.env.JAVY_SKIP_DOWNLOAD === "1") {
+        console.log("[javy-cli-darwin-x64] JAVY_SKIP_DOWNLOAD=1, skipping download");
+        return;
+    }
+    mkdirSync(BIN_DIR, { recursive: true });
+    if (existsSync(BIN_PATH)) {
+        // Existing file: assume good (the gzip checksum check would require
+        // re-downloading, which defeats idempotence).
+        return;
+    }
+    const tmp = BIN_PATH + ".gz";
+    console.log("[javy-cli-darwin-x64] downloading", URL);
+    const res = await fetch(URL, { redirect: "follow" });
+    if (!res.ok) {
+        throw new Error("[javy-cli-darwin-x64] download failed: " + res.status + " " + res.statusText);
+    }
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    // Verify the GZIP checksum BEFORE extracting.
+    const gzHash = createHash("sha256").update(bytes).digest("hex");
+    if (gzHash !== EXPECTED_SHA256) {
+        throw new Error("[javy-cli-darwin-x64] checksum mismatch: expected " + EXPECTED_SHA256 + " got " + gzHash);
+    }
+    // Decompress and write the executable.
+    const out = gunzipSync(bytes);
+    writeFileSyncRaw(BIN_PATH, out);
+    chmodSync(BIN_PATH, 0o755);
+    console.log("[javy-cli-darwin-x64] installed", BIN_PATH, "(" + out.length + " bytes)");
+}
+
+main().catch((err) => { console.error(err); process.exit(1); });

packages/devtools/tooling/javy-cli-darwin-x64/src/index.md

@@ -0,0 +1,47 @@
+# `getJavyBinary` — @suaveplan/javy-cli-darwin-x64
+
+## Purpose
+
+This module exposes the absolute filesystem path to the platform-specific Javy v8.1.1 binary bundled with this wrapper package. The Javy CLI is a Bytecode-Alliance project that compiles JavaScript source files into self-contained WebAssembly modules; `@suaveplan/wasm-compiler-javy` consumes `getJavyBinary()` to locate the binary it spawns via `child_process.spawnSync`, eliminating the need for consumers to ship their own download or PATH lookup.
+
+The wrapper carries matching `os` + `cpu` constraints in `package.json` so npm/bun skip installation on mismatched platforms — this means a single monorepo install stays cross-platform-safe, and the compiler can iterate its `optionalDependencies` to find whichever wrapper actually installed.
+
+## Features
+
+- `getJavyBinary()` — returns the absolute path to the platform binary, throwing a structured `Error` if the postinstall download failed or was bypassed.
+- `JAVY_PLATFORM` — the platform triple this wrapper serves (`darwin-x64`).
+- `JAVY_VERSION` — the pinned Javy upstream version (`v8.1.1`).
+
+## Usage: Basic
+
+```ts
+import { getJavyBinary } from "@suaveplan/javy-cli-darwin-x64";
+
+const javy = getJavyBinary();
+// javy === "/abs/path/to/bin/javy"
+```
+
+## Usage: Advanced
+
+```ts
+import { getJavyBinary, JAVY_PLATFORM, JAVY_VERSION } from "@suaveplan/javy-cli-darwin-x64";
+import { spawnSync } from "node:child_process";
+
+if (JAVY_PLATFORM !== `${process.platform}-${process.arch}`) {
+    throw new Error("wrong wrapper");
+}
+const result = spawnSync(getJavyBinary(), ["build", "src.js", "-o", "out.wasm", "-C", "deterministic=y"], {
+    encoding: "utf8",
+});
+console.log("javy version:", JAVY_VERSION, "exit:", result.status);
+```
+
+## API Reference
+
+- `getJavyBinary(): string` — resolves the bundled binary path. Throws `Error` when the binary is absent.
+- `JAVY_PLATFORM: "darwin-x64"` — readonly string literal.
+- `JAVY_VERSION: "v8.1.1"` — readonly string literal.
+
+## Implementation Notes
+
+The binary is downloaded at install time by `postinstall.mjs` from `github.com/bytecodealliance/javy/releases/download/v8.1.1/javy-x86_64-macos-v8.1.1.gz` with a committed SHA-256 checksum verifying the gzip payload before decompression. The decompressed binary is chmod-ed to `0o755` (no-op on Windows) and placed at `bin/javy` relative to the package root. The committed sha for this wrapper is `d5dea62b8a4b5dfe740405adcdbbe21852b3abd90dba682517886e0df10b3032`. `JAVY_SKIP_DOWNLOAD=1` skips the download for offline CI sandboxes — callers MUST seed `bin/javy` themselves in that mode. The wrapper is intentionally tiny: a path string and two constants, no logic beyond fs.existsSync.

packages/devtools/tooling/javy-cli-darwin-x64/src/index.ts

@@ -0,0 +1,37 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Absolute filesystem path to the bundled Javy binary for this
+ * platform. `@suaveplan/wasm-compiler-javy` calls this to locate the
+ * binary it spawns via `child_process.spawnSync` — the postinstall
+ * script places the binary at this exact path after verifying its
+ * SHA-256.
+ *
+ * Throws if the binary is missing (the postinstall step failed or was
+ * skipped via `JAVY_SKIP_DOWNLOAD=1` without a follow-up seed). The
+ * caller is expected to surface this as a structured error.
+ */
+export function getJavyBinary(): string {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // dist/index.js → ../bin/<name>
+    const candidate = join(here, "..", "bin", "javy");
+    if (!existsSync(candidate)) {
+        // src/index.ts → ../bin/<name> (when running from src under bun)
+        const fallback = join(here, "..", "bin", "javy");
+        if (existsSync(fallback)) return fallback;
+        throw new Error(
+            "@suaveplan/javy-cli-darwin-x64: binary not found at " +
+                candidate +
+                " — did postinstall run? (set JAVY_SKIP_DOWNLOAD=1 only with a manual seed)"
+        );
+    }
+    return candidate;
+}
+
+/** Platform triple this wrapper serves. */
+export const JAVY_PLATFORM = "darwin-x64" as const;
+
+/** Pinned Javy upstream version this wrapper installs. */
+export const JAVY_VERSION = "v8.1.1" as const;

packages/devtools/tooling/javy-cli-darwin-x64/tsconfig.lib.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "lib": [
+      "ES2022"
+    ],
+    "types": [
+      "node"
+    ]
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "src/**/*.test.ts",
+    "dist",
+    "node_modules"
+  ]
+}

packages/devtools/tooling/javy-cli-darwin-x64/vite.config.ts

@@ -0,0 +1,30 @@
+import { defineConfig } from "vite";
+import dts from "vite-plugin-dts";
+
+export default defineConfig({
+    root: __dirname,
+    cacheDir: "../../../../node_modules/.vite/packages/javy-cli-darwin-x64",
+    plugins: [
+        dts({
+            entryRoot: "src",
+            tsconfigPath: "./tsconfig.lib.json",
+            insertTypesEntry: true,
+        }),
+    ],
+    build: {
+        outDir: "./dist",
+        emptyOutDir: true,
+        reportCompressedSize: true,
+        sourcemap: true,
+        lib: { entry: "src/index.ts", formats: ["es"] },
+        rollupOptions: {
+            treeshake: true,
+            output: {
+                preserveModules: true,
+                preserveModulesRoot: "src",
+                entryFileNames: "[name].js",
+            },
+            external: [/^node:/, "tslib"],
+        },
+    },
+});

packages/devtools/tooling/javy-cli-darwin-x64/vitest.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+    test: {
+        globals: false,
+        environment: "node",
+        pool: "forks",
+        include: ["src/**/*.test.ts"],
+        exclude: ["dist/**", "node_modules/**"],
+        coverage: {
+            provider: "istanbul",
+            reporter: ["text", "html", "lcov"],
+            include: ["src/**/*.ts"],
+            exclude: ["src/**/*.test.ts", "src/**/index.ts"],
+        },
+        testTimeout: 30000,
+    },
+});