Initial Commit

packages/devtools/tooling/javy-cli-linux-arm64/src/index.md

@@ -0,0 +1,47 @@
+# `getJavyBinary` — @suaveplan/javy-cli-linux-arm64
+
+## 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 (`linux-arm64`).
+- `JAVY_VERSION` — the pinned Javy upstream version (`v8.1.1`).
+
+## Usage: Basic
+
+```ts
+import { getJavyBinary } from "@suaveplan/javy-cli-linux-arm64";
+
+const javy = getJavyBinary();
+// javy === "/abs/path/to/bin/javy"
+```
+
+## Usage: Advanced
+
+```ts
+import { getJavyBinary, JAVY_PLATFORM, JAVY_VERSION } from "@suaveplan/javy-cli-linux-arm64";
+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: "linux-arm64"` — 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-arm-linux-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 `c160127f4f41000216790e24bcfda860c51b0c5cc12808eb3691a0de88faa53a`. `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-linux-arm64/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-linux-arm64: 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 = "linux-arm64" as const;
+
+/** Pinned Javy upstream version this wrapper installs. */
+export const JAVY_VERSION = "v8.1.1" as const;