@pulseengine/synth 0.39.0

package/README.md

@@ -0,0 +1,59 @@
+# @pulseengine/synth
+
+`synth` — a WebAssembly-to-native compiler with mechanized correctness proofs
+in Rocq. It compiles WebAssembly to bare-metal ELF binaries for ARM Cortex-M
+(Thumb-2), Cortex-R5 (A32), RISC-V (RV32IMAC), and host-native AArch64.
+
+This npm package distributes the `synth` CLI binary so it can be installed and
+invoked from any Node.js environment. It complements the crates.io
+distribution (`cargo install synth-cli`).
+
+## Install
+
+```bash
+# One-shot (no install)
+npx @pulseengine/synth --version
+
+# Global install
+npm install -g @pulseengine/synth
+synth --version
+```
+
+## How it works
+
+There are no third-party dependencies. On install, the `postinstall` hook:
+
+1. Detects your platform and architecture.
+2. Downloads the matching `synth-v<version>-<triple>.tar.gz` from the GitHub
+   Release whose tag equals this package's version.
+3. **Verifies** the tarball's SHA-256 against the release's signed
+   `SHA256SUMS.txt` manifest — a mismatch aborts the install.
+4. Extracts the `synth` binary into the package's `bin/` directory.
+
+The package version tracks the synth release version, so
+`npm install @pulseengine/synth@0.38.0` fetches the `v0.38.0` binaries.
+
+Set `SYNTH_NPM_SKIP_DOWNLOAD=1` to skip the download (e.g. air-gapped CI where
+the binary is provided out of band).
+
+## Supported platforms
+
+Mirrors the release build matrix (no Windows build):
+
+- `darwin-arm64` — `aarch64-apple-darwin`
+- `darwin-x64` — `x86_64-apple-darwin`
+- `linux-arm64` — `aarch64-unknown-linux-gnu`
+- `linux-x64` — `x86_64-unknown-linux-gnu`
+
+Binaries are pre-built and published alongside each GitHub release at
+<https://github.com/pulseengine/synth/releases>. On an unsupported platform,
+install from source:
+
+```bash
+cargo install --git https://github.com/pulseengine/synth synth-cli
+```
+
+## License
+
+Apache-2.0. See the [repository](https://github.com/pulseengine/synth) for
+source, documentation, and issues.

package/index.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+
+// Platform detection and release-asset naming for @pulseengine/synth.
+//
+// synth is distributed as a single npm package: install.js (postinstall)
+// downloads the matching pre-built binary from the GitHub Release whose tag
+// equals this package's version, verifies it against the release's signed
+// SHA256SUMS manifest, and extracts it into ./bin. This module owns the
+// platform -> Rust-target-triple mapping shared by install.js and run.js and
+// is the single source of truth for asset names.
+//
+// Supported targets mirror .github/workflows/release.yml exactly — four
+// tarballs, no Windows build:
+//   - aarch64-apple-darwin      (macOS arm64)
+//   - x86_64-apple-darwin       (macOS x64)
+//   - aarch64-unknown-linux-gnu (Linux arm64)
+//   - x86_64-unknown-linux-gnu  (Linux x64)
+
+const os = require("os");
+const path = require("path");
+
+const REPO = "pulseengine/synth";
+
+/**
+ * Map (process.platform, process.arch) to the Rust target triple that
+ * release.yml builds and uploads. Throws with a clear message for any
+ * combination synth does not ship a binary for (notably Windows, which has
+ * no release build — do NOT synthesize a 404 URL for it).
+ *
+ * @param {string} [platform=os.platform()] node platform id
+ * @param {string} [arch=os.arch()] node arch id
+ * @returns {string} e.g. "aarch64-apple-darwin"
+ */
+function getRustTarget(platform = os.platform(), arch = os.arch()) {
+  let osTriple;
+  switch (platform) {
+    case "darwin":
+      osTriple = "apple-darwin";
+      break;
+    case "linux":
+      osTriple = "unknown-linux-gnu";
+      break;
+    default:
+      throw new Error(
+        `Unsupported platform: ${platform}. synth ships binaries for ` +
+          "macOS (darwin) and Linux only. Build from source with " +
+          "`cargo install --git https://github.com/pulseengine/synth synth-cli`.",
+      );
+  }
+
+  let archTriple;
+  switch (arch) {
+    case "x64":
+      archTriple = "x86_64";
+      break;
+    case "arm64":
+      archTriple = "aarch64";
+      break;
+    default:
+      throw new Error(
+        `Unsupported architecture: ${arch}. synth ships x86_64 (x64) and ` +
+          "aarch64 (arm64) binaries only.",
+      );
+  }
+
+  return `${archTriple}-${osTriple}`;
+}
+
+/**
+ * The release-asset tarball name for a given version + platform. Matches the
+ * `synth-${VERSION}-${TARGET}.tar.gz` name produced by release.yml, where
+ * VERSION is the tag *with* its leading `v` (e.g. v0.38.0).
+ *
+ * @param {string} version bare semver, e.g. "0.38.0"
+ * @param {string} [platform]
+ * @param {string} [arch]
+ * @returns {string} e.g. "synth-v0.38.0-aarch64-apple-darwin.tar.gz"
+ */
+function getTarballName(version, platform = os.platform(), arch = os.arch()) {
+  const target = getRustTarget(platform, arch);
+  return `synth-v${version}-${target}.tar.gz`;
+}
+
+/** The binary name inside the tarball / on disk. synth has no Windows build,
+ * so there is never a `.exe`. */
+function getBinaryName() {
+  return "synth";
+}
+
+/**
+ * Absolute path to the extracted synth binary (populated by install.js).
+ */
+function getBinaryPath() {
+  return path.join(__dirname, "bin", getBinaryName());
+}
+
+/**
+ * GitHub Release download URL for the platform tarball at this version.
+ */
+function getTarballUrl(version, platform = os.platform(), arch = os.arch()) {
+  const name = getTarballName(version, platform, arch);
+  return `https://github.com/${REPO}/releases/download/v${version}/${name}`;
+}
+
+/**
+ * GitHub Release download URL for the signed SHA256SUMS manifest.
+ */
+function getChecksumsUrl(version) {
+  return `https://github.com/${REPO}/releases/download/v${version}/SHA256SUMS.txt`;
+}
+
+/**
+ * Parse a SHA256SUMS.txt manifest (as produced by `sha256sum ./*`) into a
+ * { basename: hash } map. Each line is `<64-hex-hash>  ./<name>` — note the
+ * two-space separator and the `./` path prefix; we key by basename so a
+ * caller can look up `synth-v0.38.0-<triple>.tar.gz` directly.
+ *
+ * @param {string} text raw manifest contents
+ * @returns {Map<string,string>}
+ */
+function parseChecksums(text) {
+  const map = new Map();
+  for (const rawLine of text.split("\n")) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    const m = line.match(/^([0-9a-fA-F]{64})\s+(.+)$/);
+    if (!m) continue;
+    const hash = m[1].toLowerCase();
+    const name = path.basename(m[2].trim());
+    map.set(name, hash);
+  }
+  return map;
+}
+
+/**
+ * Look up the expected sha256 for a tarball in a parsed manifest.
+ * @returns {string} lowercase hex hash
+ * @throws if the tarball is absent from the manifest
+ */
+function expectedHashFor(tarballName, checksumsText) {
+  const map =
+    checksumsText instanceof Map ? checksumsText : parseChecksums(checksumsText);
+  const hash = map.get(tarballName);
+  if (!hash) {
+    throw new Error(
+      `SHA256SUMS.txt has no entry for ${tarballName} — refusing to install ` +
+        "an unverifiable binary.",
+    );
+  }
+  return hash;
+}
+
+module.exports = {
+  REPO,
+  getRustTarget,
+  getTarballName,
+  getBinaryName,
+  getBinaryPath,
+  getTarballUrl,
+  getChecksumsUrl,
+  parseChecksums,
+  expectedHashFor,
+};
+
+// When invoked directly, print platform info (useful for debugging installs).
+if (require.main === module) {
+  try {
+    const version = require("./package.json").version;
+    console.log("synth npm — platform information:");
+    console.log(`  Platform:     ${os.platform()}`);
+    console.log(`  Architecture: ${os.arch()}`);
+    console.log(`  Rust target:  ${getRustTarget()}`);
+    console.log(`  Tarball:      ${getTarballName(version)}`);
+    console.log(`  Download URL: ${getTarballUrl(version)}`);
+    console.log(`  Binary path:  ${getBinaryPath()}`);
+  } catch (err) {
+    console.error("Error:", err.message);
+    process.exit(1);
+  }
+}

package/install.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+
+// Post-install hook for @pulseengine/synth.
+//
+// Downloads the pre-built `synth` binary for the current platform from the
+// GitHub Release whose tag matches this package's version, VERIFIES the
+// tarball against the release's SHA256SUMS.txt manifest, then extracts the
+// binary into ./bin so run.js can spawn it.
+//
+// The checksum step is mandatory: an install that cannot verify the archive
+// against the published manifest aborts rather than run an unverified binary.
+//
+// Uses only Node built-ins (https, node:crypto, fs, node:child_process) plus
+// the system `tar` — no third-party dependencies.
+
+const os = require("os");
+const path = require("path");
+const fs = require("fs");
+const https = require("https");
+const crypto = require("crypto");
+const { execFileSync } = require("child_process");
+
+const {
+  getRustTarget,
+  getBinaryName,
+  getBinaryPath,
+  getTarballName,
+  getTarballUrl,
+  getChecksumsUrl,
+  expectedHashFor,
+} = require("./index.js");
+
+const VERSION = require("./package.json").version;
+
+// Allow air-gapped / offline installs to skip the network fetch (e.g. when a
+// binary was pre-placed or is provided by another mechanism).
+if (process.env.SYNTH_NPM_SKIP_DOWNLOAD === "1") {
+  console.log(
+    "SYNTH_NPM_SKIP_DOWNLOAD=1 set — skipping synth binary download.",
+  );
+  process.exit(0);
+}
+
+function download(url, { asBuffer = false, dest = null } = {}, redirects = 0) {
+  return new Promise((resolve, reject) => {
+    if (redirects > 5) {
+      return reject(new Error(`Too many redirects fetching ${url}`));
+    }
+    https
+      .get(url, { headers: { "User-Agent": "pulseengine-synth-npm" } }, (res) => {
+        if (
+          res.statusCode >= 300 &&
+          res.statusCode < 400 &&
+          res.headers.location
+        ) {
+          res.resume();
+          return download(res.headers.location, { asBuffer, dest }, redirects + 1)
+            .then(resolve)
+            .catch(reject);
+        }
+        if (res.statusCode !== 200) {
+          res.resume();
+          return reject(
+            new Error(`HTTP ${res.statusCode} ${res.statusMessage} for ${url}`),
+          );
+        }
+        if (asBuffer) {
+          const chunks = [];
+          res.on("data", (c) => chunks.push(c));
+          res.on("end", () => resolve(Buffer.concat(chunks)));
+          res.on("error", reject);
+        } else {
+          const file = fs.createWriteStream(dest);
+          res.pipe(file);
+          file.on("finish", () => file.close(() => resolve(dest)));
+          file.on("error", (err) => {
+            fs.unlink(dest, () => {});
+            reject(err);
+          });
+        }
+      })
+      .on("error", reject);
+  });
+}
+
+function sha256(buffer) {
+  return crypto.createHash("sha256").update(buffer).digest("hex");
+}
+
+// Extract via execFile (no shell) — inputs are paths we constructed, but the
+// argv form is the correct idiom regardless.
+function extractTarball(archivePath, destDir) {
+  execFileSync("tar", ["-xzf", archivePath, "-C", destDir], {
+    stdio: "inherit",
+  });
+}
+
+async function main() {
+  const target = getRustTarget();
+  const tarballName = getTarballName(VERSION);
+  const tarballUrl = getTarballUrl(VERSION);
+  const checksumsUrl = getChecksumsUrl(VERSION);
+  const binaryName = getBinaryName();
+
+  console.log(`synth npm installer — v${VERSION}`);
+  console.log(`  Platform: ${os.type()} ${os.arch()} (${target})`);
+  console.log(`  Tarball:  ${tarballName}`);
+
+  const binDir = path.join(__dirname, "bin");
+  fs.mkdirSync(binDir, { recursive: true });
+  const archivePath = path.join(binDir, tarballName);
+
+  // 1. Fetch the signed checksum manifest first, so we know what to expect.
+  console.log("  Fetching SHA256SUMS.txt ...");
+  const checksumsText = (await download(checksumsUrl, { asBuffer: true })).toString(
+    "utf8",
+  );
+  const expected = expectedHashFor(tarballName, checksumsText);
+
+  // 2. Download the tarball.
+  console.log(`  Downloading ${tarballUrl} ...`);
+  await download(tarballUrl, { dest: archivePath });
+
+  // 3. Verify BEFORE extracting.
+  const actual = sha256(fs.readFileSync(archivePath));
+  if (actual !== expected) {
+    fs.unlinkSync(archivePath);
+    throw new Error(
+      `Checksum mismatch for ${tarballName}\n` +
+        `  expected: ${expected}\n` +
+        `  actual:   ${actual}\n` +
+        "The download may be corrupted or tampered with. Aborting.",
+    );
+  }
+  console.log(`  Checksum OK (sha256 ${actual}).`);
+
+  // 4. Extract and expose the binary.
+  console.log("  Extracting ...");
+  extractTarball(archivePath, binDir);
+  fs.unlinkSync(archivePath);
+
+  const binaryPath = getBinaryPath();
+  if (!fs.existsSync(binaryPath)) {
+    throw new Error(
+      `Extraction succeeded but ${binaryName} was not found at ${binaryPath}.`,
+    );
+  }
+  fs.chmodSync(binaryPath, 0o755);
+  console.log(`  Installed synth -> ${binaryPath}`);
+}
+
+main().catch((err) => {
+  console.error("");
+  console.error("Failed to install the synth binary:", err.message);
+  console.error("");
+  console.error("Alternatives:");
+  console.error(
+    "  1. Build from source: cargo install --git " +
+      "https://github.com/pulseengine/synth synth-cli",
+  );
+  console.error(
+    "  2. Download a release manually: " +
+      "https://github.com/pulseengine/synth/releases",
+  );
+  // A failed binary install is a hard error: unlike rivet (which has a
+  // platform-package primary path and treats the download as a fallback),
+  // this package's ONLY delivery mechanism is the verified download. If it
+  // fails, `synth` would not exist — surface that loudly.
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@pulseengine/synth",
+  "version": "0.39.0",
+  "description": "synth — a WebAssembly-to-ARM/RISC-V/AArch64 compiler with mechanized correctness proofs. Produces bare-metal ELF binaries for embedded targets.",
+  "bin": {
+    "synth": "./run.js"
+  },
+  "scripts": {
+    "postinstall": "node install.js",
+    "preuninstall": "node uninstall.js",
+    "test": "node --test"
+  },
+  "keywords": [
+    "webassembly",
+    "wasm",
+    "compiler",
+    "arm",
+    "cortex-m",
+    "riscv",
+    "aarch64",
+    "embedded",
+    "bare-metal",
+    "verified",
+    "rocq",
+    "coq",
+    "rust",
+    "cli"
+  ],
+  "author": "PulseEngine <https://github.com/pulseengine>",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pulseengine/synth.git"
+  },
+  "homepage": "https://github.com/pulseengine/synth#readme",
+  "bugs": {
+    "url": "https://github.com/pulseengine/synth/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "files": [
+    "index.js",
+    "install.js",
+    "run.js",
+    "uninstall.js",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/run.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+// Thin launcher that spawns the synth binary extracted by install.js.
+// Forwards argv, stdio, and exit code; propagates signals to the child.
+
+const { spawn } = require("child_process");
+const fs = require("fs");
+const { getBinaryPath } = require("./index.js");
+
+const binaryPath = getBinaryPath();
+
+if (!fs.existsSync(binaryPath)) {
+  console.error("synth binary not found at:", binaryPath);
+  console.error("");
+  console.error("This usually means the postinstall download did not run or");
+  console.error("failed. Try reinstalling:");
+  console.error("  npm install --force @pulseengine/synth");
+  console.error("");
+  console.error(
+    "Or build from source: cargo install --git " +
+      "https://github.com/pulseengine/synth synth-cli",
+  );
+  process.exit(1);
+}
+
+const child = spawn(binaryPath, process.argv.slice(2), {
+  stdio: "inherit",
+  env: process.env,
+});
+
+child.on("error", (err) => {
+  console.error("Failed to start synth:", err.message);
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code == null ? 0 : code);
+  }
+});
+
+process.on("SIGINT", () => child.kill("SIGINT"));
+process.on("SIGTERM", () => child.kill("SIGTERM"));

package/uninstall.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+// Pre-uninstall hook: remove the binary downloaded into ./bin by install.js.
+
+const fs = require("fs");
+const path = require("path");
+
+const binDir = path.join(__dirname, "bin");
+
+if (fs.existsSync(binDir)) {
+  try {
+    fs.rmSync(binDir, { recursive: true, force: true });
+  } catch (err) {
+    console.error("Failed to clean synth bin/:", err.message);
+  }
+}