@alpha2-sh/node 0.0.0 → 0.1.0

package/dist/protocol.d.ts

@@ -0,0 +1,64 @@
+/** The version of the line-delimited JSON protocol spoken with `alpha2-host` over stdio. */
+export declare const PROTOCOL_VERSION: 1;
+/**
+ * A request object for the host: `payload`'s fields beside the protocol version, operation and id.
+ */
+export declare function createRequest(operation: "capabilities" | "export" | "conform", requestId: string, payload?: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>>;
+/** An error as the host reports it. */
+export interface ProtocolError {
+    /** A non-empty machine-readable code, such as `INVALID_INPUT`. */
+    readonly code: string;
+    readonly message: string;
+    /** Structured detail, such as the conform report of a `CONFORM_FAILED`. */
+    readonly details?: unknown;
+    /**
+     * A failed export's report: its class (`code`), the step and frame it failed at, and the host's
+     * diagnostics. See `alpha2/export-failure`.
+     */
+    readonly failure?: Readonly<Record<string, unknown>>;
+}
+/**
+ * `frames` while frames are encoded; `finalizing` once every one is and the output is being flushed
+ * and closed.
+ */
+export type ProgressPhase = "frames" | "finalizing";
+/** Progress of the request `requestId`; `completed` never exceeds `total`. */
+export interface ProgressMessage {
+    readonly protocolVersion: typeof PROTOCOL_VERSION;
+    readonly type: "progress";
+    readonly requestId: string;
+    readonly phase?: ProgressPhase;
+    readonly completed: number;
+    readonly total: number;
+}
+/** A failure of the host process itself, not tied to a request. */
+export interface FatalMessage {
+    readonly protocolVersion: typeof PROTOCOL_VERSION;
+    readonly type: "fatal";
+    readonly error: ProtocolError;
+}
+/** The final answer to request `requestId`. */
+export type ResponseMessage = {
+    readonly protocolVersion: typeof PROTOCOL_VERSION;
+    readonly requestId: string;
+    readonly ok: true;
+    readonly result: unknown;
+} | {
+    readonly protocolVersion: typeof PROTOCOL_VERSION;
+    readonly requestId: string;
+    readonly ok: false;
+    readonly error: ProtocolError;
+};
+export type HostMessage = ProgressMessage | FatalMessage | ResponseMessage;
+/**
+ * Parses and checks one line the host wrote. Throws when the line is not JSON, speaks another
+ * protocol version, or is not a well-formed message.
+ */
+export declare function parseHostMessage(line: string): HostMessage;
+/**
+ * Whether a host that ended without answering was refused by the operating system's loader: a
+ * library it links (FFmpeg's above all) is missing or of another version. That is the machine's
+ * setup, so the same host fails the same way however often it is started, unlike a host that ran
+ * and died, which says nothing of a cause.
+ */
+export declare function loaderRefused(exitCode: number | null, stderr: string): boolean;

package/dist/protocol.js

@@ -0,0 +1,97 @@
+/** The version of the line-delimited JSON protocol spoken with `alpha2-host` over stdio. */
+export const PROTOCOL_VERSION = 1;
+/**
+ * A request object for the host: `payload`'s fields beside the protocol version, operation and id.
+ */
+export function createRequest(operation, requestId, payload = {}) {
+    return {
+        protocolVersion: PROTOCOL_VERSION,
+        operation,
+        requestId,
+        ...payload,
+    };
+}
+/**
+ * Parses and checks one line the host wrote. Throws when the line is not JSON, speaks another
+ * protocol version, or is not a well-formed message.
+ */
+export function parseHostMessage(line) {
+    const value = JSON.parse(line);
+    if (!record(value))
+        throw new Error("host message must be an object");
+    if (value.protocolVersion !== PROTOCOL_VERSION) {
+        throw new Error(`unsupported host protocol ${String(value.protocolVersion)}; expected ${PROTOCOL_VERSION}`);
+    }
+    if (value.type === "progress") {
+        if (typeof value.requestId !== "string" ||
+            !nonNegativeInteger(value.completed) ||
+            !nonNegativeInteger(value.total) ||
+            value.completed > value.total ||
+            (value.phase !== undefined &&
+                value.phase !== "frames" &&
+                value.phase !== "finalizing")) {
+            throw new Error("invalid progress message");
+        }
+        return value;
+    }
+    if (value.type === "fatal") {
+        if (!protocolError(value.error))
+            throw new Error("invalid fatal message");
+        return value;
+    }
+    if (typeof value.requestId !== "string" || typeof value.ok !== "boolean") {
+        throw new Error("invalid response message");
+    }
+    if (!value.ok && !protocolError(value.error)) {
+        throw new Error("invalid error response");
+    }
+    if (value.ok && !("result" in value)) {
+        throw new Error("successful response is missing result");
+    }
+    return value;
+}
+/**
+ * Windows ends a process whose DLLs it cannot load with one of these statuses, before `main` and
+ * without a word on stderr: `STATUS_DLL_NOT_FOUND`, `STATUS_ORDINAL_NOT_FOUND`,
+ * `STATUS_ENTRYPOINT_NOT_FOUND` and `STATUS_INVALID_IMAGE_FORMAT`. Node reports them unsigned.
+ */
+const WINDOWS_LOADER_STATUSES = new Set([
+    0xc0000135, 0xc0000138, 0xc0000139, 0xc000007b,
+]);
+/**
+ * What the dynamic loaders write when they refuse a program, before it runs a line of its own:
+ * glibc's ld.so (a missing library, one without a version the program names, a symbol it lacks),
+ * musl's, and macOS's dyld.
+ */
+const LOADER_WORDS = [
+    /: error while loading shared libraries: /,
+    /: version `[^']+' not found \(required by /,
+    /: symbol lookup error: /,
+    /^Error loading shared library /m,
+    /^dyld(?:\[\d+\])?: (?:Library not loaded|Symbol not found)/m,
+];
+/**
+ * Whether a host that ended without answering was refused by the operating system's loader: a
+ * library it links (FFmpeg's above all) is missing or of another version. That is the machine's
+ * setup, so the same host fails the same way however often it is started, unlike a host that ran
+ * and died, which says nothing of a cause.
+ */
+export function loaderRefused(exitCode, stderr) {
+    if (exitCode !== null &&
+        WINDOWS_LOADER_STATUSES.has(exitCode < 0 ? exitCode + 2 ** 32 : exitCode))
+        return true;
+    return LOADER_WORDS.some((words) => words.test(stderr));
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function protocolError(value) {
+    return (record(value) &&
+        typeof value.code === "string" &&
+        value.code.length > 0 &&
+        typeof value.message === "string" &&
+        (value.failure === undefined || record(value.failure)));
+}
+function nonNegativeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}

package/package.json

@@ -1,20 +1,43 @@
 {
   "name": "@alpha2-sh/node",
-  "version": "0.0.0",
-  "description": "Node.js client for the alpha2 native rendering host. Placeholder; the first release is 0.1.0.",
+  "version": "0.1.0",
   "license": "MIT",
+  "description": "Node.js client for the alpha2 native rendering host.",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/alpha2-sh/alpha2.git"
+    "url": "git+https://github.com/alpha2-sh/alpha2.git",
+    "directory": "packages/alpha2-node"
+  },
+  "homepage": "https://github.com/alpha2-sh/alpha2#readme",
+  "bugs": {
+    "url": "https://github.com/alpha2-sh/alpha2/issues"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "type": "module",
-  "exports": "./index.js",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "files": [
-    "index.js",
+    "dist",
     "README.md",
     "LICENSE.md"
   ],
-  "publishConfig": {
-    "access": "public"
+  "dependencies": {
+    "alpha2": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.15.30"
   }
 }

package/index.js

@@ -1 +0,0 @@
-export {};