Add JSR package support for Linux shared library

- Introduced a new GitHub Actions workflow for publishing the native Linux shared library as a JSON/base64 blob to JSR.
- Added scripts for embedding the shared library and generating the corresponding JSON metadata.
- Created TypeScript bindings for the shared library, enhancing usability and type safety.
- Updated CMake configuration to generate JSR package metadata during the build process.
- Included a README for usage instructions and permissions required for the library.

Author: Katze719

.github/workflows/publish-jsr.yml

@@ -0,0 +1,59 @@
+name: Publish to JSR (@serial/cpp-bindings-linux)
+
+on:
+  workflow_dispatch:
+    inputs: {}
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish-jsr:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install build dependencies
+        env:
+          DEBIAN_FRONTEND: noninteractive
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends ninja-build g++ git ca-certificates
+
+      - name: Setup CMake >= 3.30
+        uses: jwlawson/actions-setup-cmake@v2
+        with:
+          cmake-version: "3.31.x"
+
+      - name: Setup Deno
+        uses: denoland/setup-deno@v2
+        with:
+          deno-version: "2.6.0"
+
+      - name: Configure CMake (Release)
+        env:
+          CXX: g++
+        run: |
+          cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
+
+      - name: Build shared library
+        run: |
+          cmake --build build --config Release
+
+      - name: Embed .so as JSON/base64 for JSR
+        run: |
+          deno run --allow-read --allow-write jsr/scripts/embed_so.ts \
+            build/libcpp_bindings_linux.so \
+            jsr/binaries/linux-x86_64.json \
+            linux-x86_64
+
+      - name: Publish package to JSR
+        working-directory: jsr
+        run: |
+          deno publish
+
+

CMakeLists.txt

@@ -23,6 +23,14 @@ project(
     LANGUAGES CXX
 )
 
+# Generate JSR package metadata from the same git-derived version as the library.
+# We generate into the build directory to avoid touching tracked files during normal local builds.
+configure_file(
+    "${CMAKE_SOURCE_DIR}/jsr/jsr.json.in"
+    "${CMAKE_SOURCE_DIR}/jsr/jsr.json"
+    @ONLY
+)
+
 # Set C++ standard
 set(CMAKE_CXX_STANDARD 23)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)

jsr/.gitignore

@@ -0,0 +1 @@
+jsr.json

jsr/README.md

@@ -0,0 +1,31 @@
+# @serial/cpp-bindings-linux
+
+JSR package that ships the native Linux shared library
+(`libcpp_bindings_linux.so`) as a **JSON/base64 blob** and reconstructs it
+on-demand, because JSR currently doesn't handle binaries as first-class
+artifacts.
+
+## Usage
+
+```ts
+import { createErrorCallback, loadSerialLib } from "@serial/cpp-bindings-linux";
+
+const { pointer: errPtr, close: closeErr } = createErrorCallback(
+    (code, msg) => {
+        console.error("native error", code, msg);
+    },
+);
+
+const lib = await loadSerialLib();
+// lib.symbols.serialOpen(...) etc.
+
+// cleanup
+closeErr();
+lib.close();
+```
+
+## Permissions
+
+- `--allow-ffi`
+- `--allow-read`
+- `--allow-write` (only needed if you use the embedded binary extraction path)

jsr/binaries/linux-x86_64.json

@@ -0,0 +1,9 @@
+{
+  "target": "linux-x86_64",
+  "filename": "libcpp_bindings_linux.so",
+  "encoding": "base64",
+  "sha256": "",
+  "data": ""
+}
+
+

jsr/ffi.ts

@@ -0,0 +1,55 @@
+export const symbols = {
+    serialOpen: {
+        parameters: ["pointer", "i32", "i32", "i32", "i32", "pointer"] as const,
+        result: "i64" as const,
+    },
+    serialClose: {
+        parameters: ["i64", "pointer"] as const,
+        result: "i32" as const,
+    },
+    serialRead: {
+        parameters: ["i64", "pointer", "i32", "i32", "i32", "pointer"] as const,
+        result: "i32" as const,
+    },
+    serialWrite: {
+        parameters: ["i64", "pointer", "i32", "i32", "i32", "pointer"] as const,
+        result: "i32" as const,
+    },
+};
+
+export type LoadedLibrary = Deno.DynamicLibrary<typeof symbols>;
+export type SerialLib = LoadedLibrary["symbols"];
+
+export type ErrorCallback = (code: number, message: string) => void;
+
+/**
+ * Creates a C-callable callback pointer compatible with `ErrorCallbackT` in the .so
+ * (signature: `void (*)(int code, const char* message)`).
+ *
+ * Remember to `close()` it when you're done.
+ */
+export function createErrorCallback(cb: ErrorCallback): {
+    pointer: Deno.PointerValue;
+    close: () => void;
+} {
+    const callback = new Deno.UnsafeCallback(
+        { parameters: ["i32", "pointer"], result: "void" } as const,
+        (code: number, messagePtr: Deno.PointerValue) => {
+            let message = "";
+            try {
+                if (messagePtr) {
+                    message = new Deno.UnsafePointerView(messagePtr)
+                        .getCString();
+                }
+            } catch {
+                // best-effort: ignore malformed pointers
+            }
+            cb(code, message);
+        },
+    );
+
+    return {
+        pointer: callback.pointer,
+        close: () => callback.close(),
+    };
+}

jsr/jsr.json.in

@@ -0,0 +1,22 @@
+{
+  "name": "@serial/cpp-bindings-linux",
+  "version": "@PROJECT_VERSION@",
+  "description": "Linux shared-library bindings for Serial-IO/cpp-core (distributed via JSON/base64 because JSR has limited binary support).",
+  "exports": {
+    ".": "./mod.ts"
+  },
+  "publish": {
+    "include": [
+      "README.md",
+      "jsr.json",
+      "mod.ts",
+      "ffi.ts",
+      "binaries/**"
+    ],
+    "exclude": [
+      "scripts/**"
+    ]
+  }
+}
+
+

jsr/mod.ts

@@ -0,0 +1,122 @@
+import {
+    createErrorCallback,
+    type LoadedLibrary,
+    type SerialLib,
+    symbols,
+} from "./ffi.ts";
+
+type EmbeddedBinary = {
+    target: string;
+    filename: string;
+    encoding: "base64";
+    sha256?: string;
+    data: string;
+};
+
+let extractedLibraryPath: string | null = null;
+
+function base64ToBytes(base64: string): Uint8Array {
+    const bin = atob(base64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+    return out;
+}
+
+async function loadEmbeddedBinary(): Promise<EmbeddedBinary> {
+    const os = Deno.build.os;
+    const arch = Deno.build.arch;
+    const target = `${os}-${arch}`;
+
+    if (target !== "linux-x86_64") {
+        throw new Error(
+            `@serial/cpp-bindings-linux only ships an embedded binary for linux-x86_64 right now (got ${target}).`,
+        );
+    }
+
+    // Keep this as a dynamic import so local dev builds don't require a real binary JSON.
+    const mod = await import("./binaries/linux-x86_64.json", {
+        with: { type: "json" },
+    });
+    return mod.default as EmbeddedBinary;
+}
+
+export type EnsureLibraryOptions = {
+    /**
+     * Directory to write the extracted .so into.
+     * Defaults to a temporary directory.
+     */
+    dir?: string;
+    /**
+     * If true, re-write the file even if we already extracted it in this process.
+     */
+    force?: boolean;
+};
+
+/**
+ * Extract the embedded `.so` (stored as JSON/base64) to a real file on disk and return its path.
+ *
+ * Required permissions:
+ * - `--allow-read` (to read the embedded JSON in the package)
+ * - `--allow-write` (to write the `.so` to disk)
+ */
+export async function ensureSharedLibraryFile(
+    options: EnsureLibraryOptions = {},
+): Promise<string> {
+    if (extractedLibraryPath && !options.force) return extractedLibraryPath;
+
+    const embedded = await loadEmbeddedBinary();
+    if (!embedded.data) {
+        throw new Error(
+            "Embedded binary JSON is empty. If you're running from source, generate it via jsr/scripts/embed_so.ts.",
+        );
+    }
+
+    const dir = options.dir ??
+        await Deno.makeTempDir({ prefix: "serial-cpp-bindings-linux-" });
+    const path = `${dir}/${embedded.filename}`;
+    const bytes = base64ToBytes(embedded.data);
+
+    await Deno.writeFile(path, bytes, { mode: 0o755 });
+    extractedLibraryPath = path;
+    return path;
+}
+
+export type LoadSerialLibOptions = {
+    /**
+     * If provided, skips extraction and loads the .so from this path.
+     */
+    libraryPath?: string;
+    /**
+     * Directory to write the extracted .so into (if `libraryPath` is not provided).
+     */
+    extractDir?: string;
+    /**
+     * Force re-extract (useful if you manage the directory yourself).
+     */
+    forceExtract?: boolean;
+};
+
+/**
+ * Load the native library via `Deno.dlopen`.
+ *
+ * Required permissions:
+ * - `--allow-ffi`
+ * - `--allow-read` (to load the .so)
+ * - `--allow-write` (only if extracting the embedded binary)
+ */
+export async function loadSerialLib(
+    options: LoadSerialLibOptions = {},
+): Promise<LoadedLibrary> {
+    await Promise.resolve(); // keep async for API stability
+
+    const path = options.libraryPath ??
+        await ensureSharedLibraryFile({
+            dir: options.extractDir,
+            force: options.forceExtract,
+        });
+
+    return Deno.dlopen(path, symbols) as LoadedLibrary;
+}
+
+export { createErrorCallback, symbols };
+export type { LoadedLibrary, SerialLib };

jsr/scripts/embed_so.ts

@@ -0,0 +1,51 @@
+// Usage:
+//   deno run --allow-read --allow-write jsr/scripts/embed_so.ts \
+//     ./build/libcpp_bindings_linux.so ./jsr/binaries/linux-x86_64.json linux-x86_64
+//
+// This converts the shared library into a JSON file containing base64 data for publishing to JSR.
+
+function bytesToHex(bytes: Uint8Array): string {
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+function base64FromBytes(bytes: Uint8Array): string {
+    // Chunk to avoid call stack limits in String.fromCharCode(...bigArray)
+    const chunkSize = 0x8000;
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += chunkSize) {
+        const chunk = bytes.subarray(i, i + chunkSize);
+        binary += String.fromCharCode(...chunk);
+    }
+    return btoa(binary);
+}
+
+if (import.meta.main) {
+    const [inPath, outPath, target = "linux-x86_64"] = Deno.args;
+    if (!inPath || !outPath) {
+        console.error(
+            "Expected: <input .so path> <output .json path> [target]\nExample: build/libcpp_bindings_linux.so jsr/binaries/linux-x86_64.json linux-x86_64",
+        );
+        Deno.exit(2);
+    }
+
+    const bytes = await Deno.readFile(inPath);
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+    const sha256 = bytesToHex(digest);
+
+    const filename = outPath.endsWith(".json")
+        ? (target === "linux-x86_64"
+            ? "libcpp_bindings_linux.so"
+            : "libcpp_bindings_linux.so")
+        : "libcpp_bindings_linux.so";
+
+    const payload = {
+        target,
+        filename,
+        encoding: "base64" as const,
+        sha256,
+        data: base64FromBytes(bytes),
+    };
+
+    await Deno.writeTextFile(outPath, JSON.stringify(payload));
+    console.log(`Wrote ${outPath} (${bytes.length} bytes, sha256=${sha256})`);
+}