@jdxcode/aube-ffi 0.0.1-placeholder → 1.28.0

package/README.md

@@ -1,3 +1,25 @@
-# @jdxcode/aube-ffi
+# aube C ABI
 
-Placeholder release reserving this name for [aube](https://github.com/jdx/aube)'s embedding packages. The real packages are published by aube's release automation.
+`@jdxcode/aube-ffi` distributes aube's C ABI for Bun FFI, Deno FFI,
+Node.js FFI loaders, Python `ctypes`, and native applications. The root npm
+package selects one of eight platform packages and exports `libraryPath`,
+`headerPath`, and `target`.
+
+```sh
+npm install @jdxcode/aube-ffi
+```
+
+The same libraries and `aube.h` are attached to GitHub releases for hosts that
+do not consume npm packages.
+
+The ABI uses asynchronous operation handles. `aube_install` and `aube_add`
+return immediately; `aube_cancel` requests cooperative cancellation and
+`aube_wait` blocks until the result is available. Event callbacks run on
+aube-managed threads and must be thread-safe. Strings returned by the library
+must be released with `aube_string_free`.
+A callback-driven host should call `aube_wait` after its terminal event to
+release the completed operation handle without blocking.
+
+See the [C ABI embedding guide](https://aube.jdx.dev/embedding/ffi) for schemas,
+ownership rules, and examples. For support, use
+[GitHub Discussions](https://github.com/jdx/aube/discussions).

package/aube.h

@@ -0,0 +1,64 @@
+#ifndef AUBE_H
+#define AUBE_H
+
+#include <stdint.h>
+
+#if defined(_WIN32)
+#define AUBE_API __declspec(dllimport)
+#else
+#define AUBE_API
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Called from aube-managed threads. The callback and ctx must remain valid and
+ * thread-safe until aube_wait returns for the operation. event_json is borrowed
+ * and valid only for the duration of the callback. The callback must return
+ * normally: it must not throw, panic, or unwind across this C boundary, and it
+ * must not call aube_wait for its active operation. */
+typedef void (*aube_event_cb)(const char *event_json, void *ctx);
+
+/* host_json: {"name":"host","version":"1.0.0","defaults":{...}}
+ * Call before starting operations. The first operation seals standalone host
+ * defaults when init has not run. Returns 0 on success, -1 for invalid input,
+ * and -2 when a panic is caught. */
+AUBE_API int32_t aube_init(const char *host_json);
+
+/* options_json must contain projectDir. Returns immediately with an operation
+ * handle. Inputs are copied before return. Boundary failures are represented
+ * by a completed handle; call aube_wait to retrieve the structured error. */
+AUBE_API uint64_t aube_install(
+    const char *options_json,
+    aube_event_cb callback,
+    void *ctx);
+
+/* packages_json is a JSON array of package specifier strings. Returns a
+ * completed handle containing a structured error for boundary failures. */
+AUBE_API uint64_t aube_add(
+    const char *project_dir,
+    const char *packages_json,
+    const char *options_json,
+    aube_event_cb callback,
+    void *ctx);
+
+/* Blocks until completion and consumes the handle. Returns owned UTF-8 JSON:
+ * {"ok":true} or {"ok":false,"code":"ERR_AUBE_*","message":"..."}.
+ * Returns NULL only if an internal result cannot be represented as a C string;
+ * treat that as ERR_AUBE_FFI_RUNTIME. Free a non-null result with
+ * aube_string_free. */
+AUBE_API char *aube_wait(uint64_t handle);
+
+/* Returns 0 when cancellation was requested, -1 for an unknown handle, and -2
+ * when a panic is caught. */
+AUBE_API int32_t aube_cancel(uint64_t handle);
+
+/* Frees any string returned by this library. Null is accepted. */
+AUBE_API void aube_string_free(char *value);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

package/index.d.ts

@@ -0,0 +1,20 @@
+export type InstallEvent =
+  | { kind: "phase"; phase: "resolving" | "fetching" | "linking" | "complete" }
+  | {
+      kind: "progress"
+      resolved: number
+      total: number
+      reused: number
+      downloaded: number
+      downloadedBytes: number
+      estimatedBytes?: number
+    }
+  | { kind: "output"; level: "info" | "warning" | "error"; code?: string; message: string }
+
+export type AubeResult =
+  | { ok: true }
+  | { ok: false; code: `ERR_AUBE_${string}`; message: string }
+
+export const libraryPath: string
+export const headerPath: string
+export const target: string

package/index.js

@@ -1 +1,34 @@
-throw new Error("@jdxcode/aube-ffi 0.0.1-placeholder is a placeholder published to reserve the package name; install a real release instead: https://github.com/jdx/aube")
+const fs = require("node:fs")
+const path = require("node:path")
+const childProcess = require("node:child_process")
+
+function isMusl() {
+  if (fs.existsSync("/etc/alpine-release")) return true
+  try {
+    if (process.report.getReport().header.glibcVersionRuntime) return false
+  } catch (_) {}
+  try {
+    return childProcess.execFileSync("ldd", ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
+      .toLowerCase().includes("musl")
+  } catch (error) {
+    return `${error.stdout || ""}\n${error.stderr || ""}`.toLowerCase().includes("musl")
+  }
+}
+
+function platformPackage() {
+  const key = `${process.platform}-${process.arch}`
+  if (key === "darwin-arm64") return "@jdxcode/aube-ffi-darwin-arm64"
+  if (key === "darwin-x64") return "@jdxcode/aube-ffi-darwin-x64"
+  if (key === "win32-arm64") return "@jdxcode/aube-ffi-win32-arm64"
+  if (key === "win32-x64") return "@jdxcode/aube-ffi-win32-x64"
+  if (key === "linux-arm64" && isMusl()) return "@jdxcode/aube-ffi-linux-arm64-musl"
+  if (key === "linux-arm64") return "@jdxcode/aube-ffi-linux-arm64"
+  if (key === "linux-x64" && isMusl()) return "@jdxcode/aube-ffi-linux-x64-musl"
+  if (key === "linux-x64") return "@jdxcode/aube-ffi-linux-x64"
+  throw new Error(`Unsupported aube FFI platform: ${key}`)
+}
+
+const platform = require(platformPackage())
+exports.libraryPath = platform.libraryPath
+exports.headerPath = path.join(__dirname, "aube.h")
+exports.target = platform.target

package/package.json

@@ -1,8 +1,36 @@
 {
   "name": "@jdxcode/aube-ffi",
-  "version": "0.0.1-placeholder",
-  "description": "Placeholder reserving the name for aube's first embedding release. Do not install; see https://github.com/jdx/aube",
+  "version": "1.28.0",
+  "description": "C ABI bindings for embedding the aube package manager",
   "license": "MIT",
   "repository": "https://github.com/jdx/aube",
-  "main": "index.js"
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./aube.h": "./aube.h"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "aube.h",
+    "README.md"
+  ],
+  "preferUnplugged": true,
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@jdxcode/aube-ffi-darwin-arm64": "1.28.0",
+    "@jdxcode/aube-ffi-darwin-x64": "1.28.0",
+    "@jdxcode/aube-ffi-linux-arm64": "1.28.0",
+    "@jdxcode/aube-ffi-linux-x64": "1.28.0",
+    "@jdxcode/aube-ffi-linux-arm64-musl": "1.28.0",
+    "@jdxcode/aube-ffi-linux-x64-musl": "1.28.0",
+    "@jdxcode/aube-ffi-win32-arm64": "1.28.0",
+    "@jdxcode/aube-ffi-win32-x64": "1.28.0"
+  }
 }