@orelvis15/cavs-sdk 1.2.0

package/README.md

@@ -0,0 +1,66 @@
+# @orelvis15/cavs-sdk
+
+Node.js / TypeScript SDK for CAVS. It loads the same compiled Rust core the
+CAVS CLI uses through a stable C ABI (via [koffi](https://koffi.dev)) — it
+does not shell out to the CLI.
+
+## Install
+
+```sh
+npm install @orelvis15/cavs-sdk
+```
+
+Released builds ship the native library in per-platform packages
+(`@orelvis15/cavs-sdk-linux-x64`, `@orelvis15/cavs-sdk-darwin-arm64`, `@orelvis15/cavs-sdk-win32-x64`, …),
+resolved automatically. For local development against a source checkout:
+
+```sh
+npm run native   # builds cavs-ffi (release) and stages the lib into native/
+npm test
+```
+
+`CAVS_SDK_LIBRARY=/path/to/libcavs_sdk.dylib` overrides library resolution.
+
+## Quickstart
+
+```ts
+import { CavsClient } from "@orelvis15/cavs-sdk";
+
+const cavs = new CavsClient();
+try {
+  const preview = await cavs.preview({
+    oldPath: "Build_v1",
+    newPath: "Build_v2",
+    policy: "balanced",
+  });
+  console.log(preview.recommendedRoute);
+} finally {
+  cavs.close();
+}
+```
+
+## API
+
+`CavsClient` exposes `analyze`, `packDirectory`, `preview`, `createPlan`,
+`applyPlan`, `verifyInstall`, `benchmark` and `estimateSavings`. Every method
+returns a `Promise` and accepts an options object:
+
+- `onProgress(event)` — stream `ProgressEvent`s. Progress runs the operation
+  synchronously (koffi can only invoke JS callbacks on the calling thread),
+  so use it for CLIs/scripts rather than hot request paths.
+- `signal` — an `AbortSignal` that cancels the native job (non-progress
+  path, which runs off the event loop and polls for completion).
+
+Failures reject with a `CavsError` carrying a stable `.code` (see
+`ErrorCode`).
+
+## CI example
+
+```ts
+const preview = await cavs.preview({
+  oldPath: process.env.OLD_BUILD!,
+  newPath: process.env.NEW_BUILD!,
+  routes: [],
+});
+await uploadReport(preview);
+```

package/dist/examples/preview.d.ts

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

package/dist/examples/preview.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// Run a CAVS update preview between two build directories.
+//
+//   npm run build && node dist/examples/preview.js --old Build_v1 --new Build_v2
+const index_1 = require("../src/index");
+async function main() {
+    const args = process.argv.slice(2);
+    const oldPath = valueOf(args, "--old");
+    const newPath = valueOf(args, "--new");
+    if (!oldPath || !newPath) {
+        console.error("usage: preview --old <dir> --new <dir>");
+        process.exit(2);
+    }
+    const cavs = new index_1.CavsClient();
+    try {
+        const report = await cavs.preview({ oldPath, newPath, policy: "balanced" }, { onProgress: (e) => e.phase && console.error(`  [${e.type}] ${e.phase}`) });
+        console.log(`Recommended route: ${report.recommendedRoute}`);
+        for (const r of report.routes) {
+            console.log(`  ${r.name.padEnd(16)} ${r.networkBytes} bytes`);
+        }
+    }
+    finally {
+        cavs.close();
+    }
+}
+function valueOf(args, flag) {
+    const i = args.indexOf(flag);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+void main();

package/dist/src/client.d.ts

@@ -0,0 +1,36 @@
+import type { AnalyzeReport, AnalyzeRequest, ApplyPlanRequest, ApplyResult, BenchmarkReport, BenchmarkRequest, CallOptions, CreatePlanRequest, PackDirectoryRequest, PackResult, PlanResult, PreviewReport, PreviewRequest, SavingsReport, SavingsRequest, VerifyRequest, VerifyResult } from "./types";
+/** Version of the native SDK. */
+export declare function version(): string;
+/** Native C ABI contract version. */
+export declare function abiVersion(): string;
+/**
+ * A CAVS client. Owns a native context; call {@link close} when done.
+ *
+ * Calls are serialized (a single native context carries one progress
+ * callback slot), so concurrent calls on one client run one at a time —
+ * create multiple clients for parallelism.
+ */
+export declare class CavsClient {
+    private ctx;
+    private closed;
+    private queue;
+    constructor();
+    close(): void;
+    analyze(req: AnalyzeRequest, opts?: CallOptions): Promise<AnalyzeReport>;
+    packDirectory(req: PackDirectoryRequest, opts?: CallOptions): Promise<PackResult>;
+    preview(req: PreviewRequest, opts?: CallOptions): Promise<PreviewReport>;
+    createPlan(req: CreatePlanRequest, opts?: CallOptions): Promise<PlanResult>;
+    applyPlan(req: ApplyPlanRequest, opts?: CallOptions): Promise<ApplyResult>;
+    verifyInstall(req: VerifyRequest, opts?: CallOptions): Promise<VerifyResult>;
+    benchmark(req: BenchmarkRequest, opts?: CallOptions): Promise<BenchmarkReport>;
+    estimateSavings(req: SavingsRequest, opts?: CallOptions): Promise<SavingsReport>;
+    /** Serialize calls onto one native context. */
+    private call;
+    private execute;
+    /** Progress path: synchronous native call so callbacks fire on this
+     *  thread (koffi cannot invoke JS callbacks from a foreign thread). */
+    private executeWithProgress;
+    /** Non-blocking path: run on a native worker thread, poll on a timer so
+     *  the event loop stays free; AbortSignal cancels the native job. */
+    private executeAsJob;
+}

package/dist/src/client.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CavsClient = void 0;
+exports.version = version;
+exports.abiVersion = abiVersion;
+const native_1 = require("./native");
+const errors_1 = require("./errors");
+const SCHEMA_VERSION = "1.0";
+const POLL_INTERVAL_MS = 1;
+/** Version of the native SDK. */
+function version() {
+    return native_1.native.version();
+}
+/** Native C ABI contract version. */
+function abiVersion() {
+    return native_1.native.abiVersion();
+}
+/**
+ * A CAVS client. Owns a native context; call {@link close} when done.
+ *
+ * Calls are serialized (a single native context carries one progress
+ * callback slot), so concurrent calls on one client run one at a time —
+ * create multiple clients for parallelism.
+ */
+class CavsClient {
+    ctx;
+    closed = false;
+    queue = Promise.resolve();
+    constructor() {
+        this.ctx = native_1.native.contextNew();
+        if (!this.ctx) {
+            throw new Error("cavs: failed to create native context");
+        }
+    }
+    close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        native_1.native.contextFree(this.ctx);
+    }
+    analyze(req, opts) {
+        return this.call("analyze", req, opts);
+    }
+    packDirectory(req, opts) {
+        return this.call("packDirectory", req, opts);
+    }
+    preview(req, opts) {
+        return this.call("previewUpdate", req, opts);
+    }
+    createPlan(req, opts) {
+        return this.call("createPlan", req, opts);
+    }
+    applyPlan(req, opts) {
+        return this.call("applyPlan", req, opts);
+    }
+    verifyInstall(req, opts) {
+        return this.call("verifyInstall", req, opts);
+    }
+    benchmark(req, opts) {
+        return this.call("benchmark", req, opts);
+    }
+    estimateSavings(req, opts) {
+        return this.call("estimateSavings", req, opts);
+    }
+    /** Serialize calls onto one native context. */
+    call(op, req, opts) {
+        const run = this.queue.then(() => this.execute(op, req, opts));
+        // Keep the chain alive even if a call rejects.
+        this.queue = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async execute(op, req, opts) {
+        if (this.closed) {
+            throw new errors_1.CavsError(errors_1.ErrorCode.InvalidRequest, "client is closed");
+        }
+        const body = JSON.stringify({ schemaVersion: SCHEMA_VERSION, data: req });
+        if (opts?.onProgress) {
+            return this.executeWithProgress(op, body, opts.onProgress);
+        }
+        return this.executeAsJob(op, body, opts?.signal);
+    }
+    /** Progress path: synchronous native call so callbacks fire on this
+     *  thread (koffi cannot invoke JS callbacks from a foreign thread). */
+    executeWithProgress(op, body, onProgress) {
+        const cbPtr = native_1.native.registerProgress((raw) => {
+            try {
+                onProgress(JSON.parse(raw));
+            }
+            catch {
+                /* a malformed event must not break the operation */
+            }
+        });
+        try {
+            native_1.native.setProgress(this.ctx, cbPtr);
+            const envelope = native_1.native.executeSync(this.ctx, op, body);
+            return parse(envelope);
+        }
+        finally {
+            native_1.native.setProgress(this.ctx, null);
+            native_1.native.unregister(cbPtr);
+        }
+    }
+    /** Non-blocking path: run on a native worker thread, poll on a timer so
+     *  the event loop stays free; AbortSignal cancels the native job. */
+    async executeAsJob(op, body, signal) {
+        if (signal?.aborted) {
+            throw new errors_1.CavsError(errors_1.ErrorCode.Cancelled, "operation aborted before start", true);
+        }
+        const job = native_1.native.startJob(this.ctx, op, body);
+        if (!job) {
+            throw new errors_1.CavsError(errors_1.ErrorCode.InvalidRequest, "native library rejected the request");
+        }
+        let cancelled = false;
+        try {
+            for (;;) {
+                const envelope = native_1.native.pollJob(job);
+                if (envelope !== null) {
+                    if (cancelled) {
+                        throw new errors_1.CavsError(errors_1.ErrorCode.Cancelled, "operation aborted", true);
+                    }
+                    return parse(envelope);
+                }
+                if (signal?.aborted && !cancelled) {
+                    native_1.native.cancelJob(job);
+                    cancelled = true;
+                }
+                await sleep(POLL_INTERVAL_MS);
+            }
+        }
+        finally {
+            native_1.native.freeJob(job);
+        }
+    }
+}
+exports.CavsClient = CavsClient;
+function parse(envelope) {
+    const env = JSON.parse(envelope);
+    if (!env.ok) {
+        const e = env.error;
+        throw new errors_1.CavsError(e?.code ?? "CAVS-E-UNKNOWN", e?.message ?? "operation failed", e?.recoverable ?? false, e?.details ?? {});
+    }
+    return env.data;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/src/errors.d.ts

@@ -0,0 +1,15 @@
+/** A CAVS operation failure carrying the stable engine error code. */
+export declare class CavsError extends Error {
+    readonly code: string;
+    readonly recoverable: boolean;
+    readonly details: Record<string, unknown>;
+    constructor(code: string, message: string, recoverable?: boolean, details?: Record<string, unknown>);
+}
+/** Well-known error codes (the engine defines the full set). */
+export declare const ErrorCode: {
+    readonly PathNotFound: "CAVS-E-PATH-NOT-FOUND";
+    readonly PathTraversal: "CAVS-E-PATH-TRAVERSAL";
+    readonly InvalidRequest: "CAVS-E-INVALID-REQUEST";
+    readonly UnknownOperation: "CAVS-E-UNKNOWN-OPERATION";
+    readonly Cancelled: "CAVS-E-CANCELLED";
+};

package/dist/src/errors.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorCode = exports.CavsError = void 0;
+/** A CAVS operation failure carrying the stable engine error code. */
+class CavsError extends Error {
+    code;
+    recoverable;
+    details;
+    constructor(code, message, recoverable = false, details = {}) {
+        super(message);
+        this.name = "CavsError";
+        this.code = code;
+        this.recoverable = recoverable;
+        this.details = details;
+    }
+}
+exports.CavsError = CavsError;
+/** Well-known error codes (the engine defines the full set). */
+exports.ErrorCode = {
+    PathNotFound: "CAVS-E-PATH-NOT-FOUND",
+    PathTraversal: "CAVS-E-PATH-TRAVERSAL",
+    InvalidRequest: "CAVS-E-INVALID-REQUEST",
+    UnknownOperation: "CAVS-E-UNKNOWN-OPERATION",
+    Cancelled: "CAVS-E-CANCELLED",
+};

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export { CavsClient, version, abiVersion } from "./client";
+export { CavsError, ErrorCode } from "./errors";
+export * from "./types";

package/dist/src/index.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorCode = exports.CavsError = exports.abiVersion = exports.version = exports.CavsClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "CavsClient", { enumerable: true, get: function () { return client_1.CavsClient; } });
+Object.defineProperty(exports, "version", { enumerable: true, get: function () { return client_1.version; } });
+Object.defineProperty(exports, "abiVersion", { enumerable: true, get: function () { return client_1.abiVersion; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "CavsError", { enumerable: true, get: function () { return errors_1.CavsError; } });
+Object.defineProperty(exports, "ErrorCode", { enumerable: true, get: function () { return errors_1.ErrorCode; } });
+__exportStar(require("./types"), exports);

package/dist/src/native.d.ts

@@ -0,0 +1,21 @@
+import koffi from "koffi";
+export type Pointer = unknown;
+export type ProgressHandle = koffi.IKoffiRegisteredCallback;
+export declare const native: {
+    version(): string;
+    abiVersion(): string;
+    capabilitiesJson(): string;
+    contextNew(): Pointer;
+    contextFree(ctx: Pointer): void;
+    /** Register a progress callback pointer; returns it so it can stay alive
+     *  and be unregistered afterwards. Pass null to clear. */
+    registerProgress(fn: ((event: string) => void) | null): ProgressHandle | null;
+    setProgress(ctx: Pointer, cbPtr: ProgressHandle | null): void;
+    unregister(cbPtr: ProgressHandle | null): void;
+    executeSync(ctx: Pointer, op: string, req: string): string;
+    startJob(ctx: Pointer, op: string, req: string): Pointer | null;
+    /** Poll: the envelope JSON if finished, else null. */
+    pollJob(job: Pointer): string | null;
+    cancelJob(job: Pointer): void;
+    freeJob(job: Pointer): void;
+};

package/dist/src/native.js

@@ -0,0 +1,187 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.native = void 0;
+// Native binding to the CAVS C ABI via koffi. Handles are opaque pointers.
+const koffi_1 = __importDefault(require("koffi"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+function libraryFileName() {
+    switch (process.platform) {
+        case "darwin":
+            return "libcavs_sdk.dylib";
+        case "win32":
+            return "cavs_sdk.dll";
+        default:
+            return "libcavs_sdk.so";
+    }
+}
+function osArch() {
+    const os = process.platform === "darwin"
+        ? "darwin"
+        : process.platform === "win32"
+            ? "win32"
+            : "linux";
+    const arch = process.arch === "x64" ? "x64" : process.arch === "arm64" ? "arm64" : process.arch;
+    return `${os}-${arch}`;
+}
+/** Resolve the native library: CAVS_SDK_LIBRARY, then the per-platform
+ *  package, then the local `native/` staging dir. */
+function resolveLibraryPath() {
+    const override = process.env.CAVS_SDK_LIBRARY;
+    if (override && override.length > 0) {
+        return override;
+    }
+    const name = libraryFileName();
+    const candidates = [
+        // Published per-platform package: @orelvis15/cavs-sdk-<os>-<arch>.
+        tryResolvePlatformPackage(name),
+        // Local dev staging (npm run native).
+        path.join(__dirname, "..", "native", name),
+        path.join(__dirname, "..", "..", "native", name),
+    ].filter((p) => !!p);
+    for (const c of candidates) {
+        if (fs.existsSync(c)) {
+            return c;
+        }
+    }
+    throw new Error(`cavs: native library not found (looked for ${name}); set CAVS_SDK_LIBRARY or run \`npm run native\``);
+}
+function tryResolvePlatformPackage(name) {
+    try {
+        const pkg = `@orelvis15/cavs-sdk-${osArch()}`;
+        const dir = path.dirname(require.resolve(`${pkg}/package.json`));
+        return path.join(dir, name);
+    }
+    catch {
+        return undefined;
+    }
+}
+const lib = koffi_1.default.load(resolveLibraryPath());
+// Opaque handle pointer types.
+const CavsContext = koffi_1.default.pointer("CavsContext", koffi_1.default.opaque());
+const CavsResult = koffi_1.default.pointer("CavsResult", koffi_1.default.opaque());
+const CavsJob = koffi_1.default.pointer("CavsJob", koffi_1.default.opaque());
+// Progress callback prototype: void (*)(const char*, void*).
+const ProgressProto = koffi_1.default.proto("void CavsProgressCallback(const char* event, void* user)");
+const ProgressPtr = koffi_1.default.pointer(ProgressProto);
+const fns = {
+    version: lib.func("const char* cavs_sdk_version()"),
+    abiVersion: lib.func("const char* cavs_sdk_abi_version()"),
+    capabilities: lib.func("void* cavs_sdk_capabilities_json()"),
+    ctxNew: lib.func("CavsContext* cavs_context_new(const char*)"),
+    ctxFree: lib.func("void cavs_context_free(CavsContext*)"),
+    setProgress: lib.func("int cavs_context_set_progress_callback(CavsContext*, CavsProgressCallback*, void*)"),
+    execute: lib.func("CavsResult* cavs_execute_json(CavsContext*, const char*, const char*)"),
+    start: lib.func("CavsJob* cavs_start_json(CavsContext*, const char*, const char*)"),
+    poll: lib.func("CavsResult* cavs_job_poll(CavsJob*)"),
+    cancel: lib.func("int cavs_job_cancel(CavsJob*)"),
+    jobFree: lib.func("void cavs_job_free(CavsJob*)"),
+    resultJson: lib.func("const char* cavs_result_json(CavsResult*)"),
+    resultOk: lib.func("int cavs_result_ok(CavsResult*)"),
+    resultFree: lib.func("void cavs_result_free(CavsResult*)"),
+    stringFree: lib.func("void cavs_string_free(void*)"),
+};
+exports.native = {
+    version() {
+        return fns.version();
+    },
+    abiVersion() {
+        return fns.abiVersion();
+    },
+    capabilitiesJson() {
+        const ptr = fns.capabilities();
+        if (!ptr) {
+            return "";
+        }
+        const s = koffi_1.default.decode(ptr, "char", -1);
+        fns.stringFree(ptr);
+        return s;
+    },
+    contextNew() {
+        return fns.ctxNew(null);
+    },
+    contextFree(ctx) {
+        fns.ctxFree(ctx);
+    },
+    /** Register a progress callback pointer; returns it so it can stay alive
+     *  and be unregistered afterwards. Pass null to clear. */
+    registerProgress(fn) {
+        if (!fn) {
+            return null;
+        }
+        return koffi_1.default.register((event) => fn(event), ProgressPtr);
+    },
+    setProgress(ctx, cbPtr) {
+        fns.setProgress(ctx, cbPtr, null);
+    },
+    unregister(cbPtr) {
+        if (cbPtr) {
+            koffi_1.default.unregister(cbPtr);
+        }
+    },
+    executeSync(ctx, op, req) {
+        const res = fns.execute(ctx, op, req);
+        return drainResult(res);
+    },
+    startJob(ctx, op, req) {
+        return fns.start(ctx, op, req) ?? null;
+    },
+    /** Poll: the envelope JSON if finished, else null. */
+    pollJob(job) {
+        const res = fns.poll(job);
+        if (!res) {
+            return null;
+        }
+        return drainResult(res);
+    },
+    cancelJob(job) {
+        fns.cancel(job);
+    },
+    freeJob(job) {
+        fns.jobFree(job);
+    },
+};
+function drainResult(res) {
+    if (!res) {
+        return '{"ok":false,"error":{"code":"CAVS-E-INTERNAL","message":"native returned null result","recoverable":false}}';
+    }
+    const json = fns.resultJson(res);
+    fns.resultFree(res);
+    return json;
+}

package/dist/src/types.d.ts

@@ -0,0 +1,195 @@
+export interface ProgressEvent {
+    type: string;
+    operation: string;
+    phase?: string;
+    currentBytes?: number;
+    totalBytes?: number;
+    percentage?: number;
+    message?: string;
+}
+export type RoutePolicy = "balanced" | "networkMin" | "cpuMin" | "ramMin" | "diskIoMin" | "hddFriendly" | "developerFast";
+export interface CallOptions {
+    /** Stream progress events. Note: enabling progress runs the operation
+     *  synchronously (see README); omit it for the non-blocking path. */
+    onProgress?: (event: ProgressEvent) => void;
+    /** Cancel the operation (non-progress path only). */
+    signal?: AbortSignal;
+}
+export interface AnalyzeRequest {
+    oldPath: string;
+    newPath: string;
+    engineHint?: string;
+    maxWorstFiles?: number;
+}
+export interface WorstFile {
+    path: string;
+    status: string;
+    isPack: boolean;
+    oldSizeBytes: number;
+    newSizeBytes: number;
+    estimatedDownloadBytes: number;
+    reuseRatio: number;
+    entropyBits: number;
+}
+export interface Recommendation {
+    severity: string;
+    kind: string;
+    title: string;
+    file?: string;
+    estimatedWastedBytes: number;
+    why: string;
+    fix: string;
+    expectedImprovement: string;
+}
+export interface AnalyzeReport {
+    summary: {
+        oldSizeBytes: number;
+        newSizeBytes: number;
+        estimatedUpdateBytes: number;
+        estimatedSteamPipeBytes: number;
+        cavsReuseRatio: number;
+        steamPipeReuseRatio: number;
+        filesUnchanged: number;
+        filesModified: number;
+        filesAdded: number;
+        filesDeleted: number;
+        worstFiles: WorstFile[];
+    };
+    engine: string;
+    warnings: string[];
+    recommendations: Recommendation[];
+    note: string;
+}
+export interface PackDirectoryRequest {
+    inputDir: string;
+    outputCavs: string;
+    profile?: string;
+    compression?: string;
+    signKeyPath?: string;
+    ignore?: string[];
+}
+export interface PackResult {
+    outputCavs: string;
+    totalSizeBytes: number;
+    chunkCount: number;
+    logicalChunks: number;
+    logicalRawBytes: number;
+    storedBytes: number;
+    merkleRoot: string;
+    filesPacked: number;
+    entriesIgnored: number;
+    signed: boolean;
+    profile: string;
+    elapsedMs: number;
+}
+export interface PreviewRequest {
+    oldPath: string;
+    newPath: string;
+    engineHint?: string;
+    routes?: string[];
+    policy?: RoutePolicy;
+}
+export interface Route {
+    name: string;
+    networkBytes: number;
+    diffMs?: number;
+    applyMs?: number | null;
+    available: boolean;
+}
+export interface PreviewReport {
+    recommendedRoute: string;
+    oldSizeBytes: number;
+    newSizeBytes: number;
+    routes: Route[];
+    explanation: string;
+}
+export interface CreatePlanRequest {
+    oldPath?: string;
+    oldSignature?: string;
+    newPath: string;
+    outputPlan: string;
+    planKind?: "portable" | "analysis";
+    blockKib?: number;
+    zstdLevel?: number;
+}
+export interface PlanResult {
+    planPath: string;
+    planBytes: number;
+    planKind: string;
+    mode: string;
+    operationCount: number;
+    copyOps: number;
+    inlineOps: number;
+    reusedBytes: number;
+    inlineBytes: number;
+    estimatedNetworkBytes: number;
+    expectedOutputSize: number;
+    files: number;
+    unchangedFiles: number;
+    deleted: number;
+    elapsedMs: number;
+}
+export interface ApplyPlanRequest {
+    oldPath: string;
+    planPath: string;
+    outputPath: string;
+    checkOld?: boolean;
+    deleteRemoved?: boolean;
+}
+export interface ApplyResult {
+    outputPath: string;
+    verified: boolean;
+    mode: string;
+    filesTotal: number;
+    filesWritten: number;
+    filesNoop: number;
+    dirsCreated: number;
+    symlinksCreated: number;
+    deleted: number;
+    bytesWritten: number;
+    bytesFromOld: number;
+    bytesFromBlob: number;
+    elapsedMs: number;
+}
+export interface VerifyRequest {
+    target: string;
+    signature?: string;
+    manifest?: string;
+    allowExtra?: boolean;
+}
+export interface VerifyResult {
+    verified: boolean;
+    filesChecked: number;
+    bytesChecked: number;
+    mismatches: {
+        modified: string[];
+        missing: string[];
+        extra: string[];
+    };
+    elapsedMs: number;
+}
+export interface BenchmarkRequest {
+    oldPath: string;
+    newPath: string;
+    engineHint?: string;
+    measureApply?: boolean;
+}
+export interface BenchmarkReport {
+    oldSizeBytes: number;
+    newSizeBytes: number;
+    recommendedRoute: string;
+    routes: Route[];
+    reuseRatio: number;
+}
+export interface SavingsRequest {
+    pricePerGb: number;
+    monthlyDownloads: number;
+    averageFullDownloadBytes: number;
+    averageCavsDownloadBytes: number;
+}
+export interface SavingsReport {
+    fullDownloadMonthlyCost: number;
+    cavsMonthlyCost: number;
+    estimatedMonthlySavings: number;
+    savingsPercent: number;
+}

package/dist/src/types.js

@@ -0,0 +1,4 @@
+"use strict";
+// Request and response shapes for the CAVS SDK. Field names match the
+// engine's camelCase JSON exactly.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/test/cavs.test.d.ts

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

package/dist/test/cavs.test.js

@@ -0,0 +1,145 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = require("node:test");
+const strict_1 = __importDefault(require("node:assert/strict"));
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const index_1 = require("../src/index");
+function makeBuilds() {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "cavs-node-"));
+    const oldDir = path.join(root, "Build_v1");
+    const newDir = path.join(root, "Build_v2");
+    fs.mkdirSync(path.join(oldDir, "data"), { recursive: true });
+    fs.mkdirSync(path.join(newDir, "data"), { recursive: true });
+    const base = Buffer.alloc(512 * 1024);
+    for (let i = 0; i < base.length; i++)
+        base[i] = i % 251;
+    fs.writeFileSync(path.join(oldDir, "data/asset.bin"), base);
+    const changed = Buffer.from(base);
+    for (let i = 300000; i < 304096; i++)
+        changed[i] ^= 0xff;
+    fs.writeFileSync(path.join(newDir, "data/asset.bin"), changed);
+    fs.writeFileSync(path.join(oldDir, "readme.txt"), "cavs sdk fixture\n");
+    fs.writeFileSync(path.join(newDir, "readme.txt"), "cavs sdk fixture\n");
+    fs.writeFileSync(path.join(newDir, "data/new_only.bin"), Buffer.alloc(64 * 1024));
+    const work = path.join(root, "work");
+    fs.mkdirSync(work);
+    return { oldDir, newDir, work };
+}
+function assertTreesEqual(a, b) {
+    let checked = 0;
+    const walk = (dir) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else {
+                const rel = path.relative(a, full);
+                strict_1.default.deepEqual(fs.readFileSync(full), fs.readFileSync(path.join(b, rel)), `differs: ${rel}`);
+                checked++;
+            }
+        }
+    };
+    walk(a);
+    strict_1.default.ok(checked > 0, "no files compared");
+}
+let client;
+(0, node_test_1.before)(() => {
+    client = new index_1.CavsClient();
+});
+(0, node_test_1.after)(() => {
+    client?.close();
+});
+(0, node_test_1.test)("version and abi are semver", () => {
+    strict_1.default.equal((0, index_1.version)().split(".").length, 3);
+    strict_1.default.equal((0, index_1.abiVersion)(), "1.0.0");
+});
+(0, node_test_1.test)("estimateSavings", async () => {
+    const r = await client.estimateSavings({
+        pricePerGb: 0.08,
+        monthlyDownloads: 500000,
+        averageFullDownloadBytes: 65011712,
+        averageCavsDownloadBytes: 2631921,
+    });
+    strict_1.default.ok(r.savingsPercent > 90, `savingsPercent=${r.savingsPercent}`);
+    strict_1.default.ok(r.estimatedMonthlySavings > r.cavsMonthlyCost);
+});
+(0, node_test_1.test)("full pipeline: analyze → pack → plan → apply → preview → benchmark", async () => {
+    const { oldDir, newDir, work } = makeBuilds();
+    const an = await client.analyze({ oldPath: oldDir, newPath: newDir });
+    strict_1.default.ok(an.summary.newSizeBytes > 0);
+    const packOut = path.join(work, "v2.cavs");
+    const pk = await client.packDirectory({ inputDir: newDir, outputCavs: packOut });
+    strict_1.default.ok(pk.filesPacked >= 3);
+    strict_1.default.ok(fs.existsSync(packOut));
+    const planPath = path.join(work, "update.cavsplan");
+    const pl = await client.createPlan({ oldPath: oldDir, newPath: newDir, outputPlan: planPath });
+    strict_1.default.ok(pl.reusedBytes > 0, "plan found no reuse");
+    const outDir = path.join(work, "out");
+    const ap = await client.applyPlan({ oldPath: oldDir, planPath, outputPath: outDir });
+    strict_1.default.ok(ap.verified);
+    assertTreesEqual(newDir, outDir);
+    const pv = await client.preview({ oldPath: oldDir, newPath: newDir, policy: "balanced" });
+    strict_1.default.ok(pv.routes.length > 0);
+    strict_1.default.ok(pv.recommendedRoute.length > 0);
+    const bm = await client.benchmark({ oldPath: oldDir, newPath: newDir, measureApply: false });
+    strict_1.default.equal(bm.routes.length, 4);
+});
+(0, node_test_1.test)("error mapping: missing path", async () => {
+    await strict_1.default.rejects(client.analyze({ oldPath: "/no/such/old", newPath: "/no/such/new" }), (err) => {
+        strict_1.default.ok(err instanceof index_1.CavsError);
+        strict_1.default.equal(err.code, index_1.ErrorCode.PathNotFound);
+        return true;
+    });
+});
+(0, node_test_1.test)("progress events are emitted", async () => {
+    const { oldDir, newDir, work } = makeBuilds();
+    const events = [];
+    await client.createPlan({ oldPath: oldDir, newPath: newDir, outputPlan: path.join(work, "p.cavsplan") }, { onProgress: (e) => events.push(e.type) });
+    strict_1.default.ok(events.length >= 2, `expected >= 2 events, got ${events.length}`);
+    strict_1.default.ok(events.includes("started"));
+});
+(0, node_test_1.test)("AbortSignal cancels before start", async () => {
+    const { oldDir, newDir, work } = makeBuilds();
+    const ac = new AbortController();
+    ac.abort();
+    await strict_1.default.rejects(client.createPlan({ oldPath: oldDir, newPath: newDir, outputPlan: path.join(work, "c.cavsplan") }, { signal: ac.signal }), (err) => err instanceof index_1.CavsError && err.code === index_1.ErrorCode.Cancelled);
+});

package/native/cavs_sdk.h

@@ -0,0 +1,96 @@
+/*
+ * cavs_sdk.h — stable C ABI for the CAVS SDK native library.
+ *
+ * Generated/maintained alongside `core/cavs-ffi`. ABI version: 1.0.0.
+ *
+ * Library names by platform:
+ *   Linux, BSD : libcavs_sdk.so
+ *   macOS      : libcavs_sdk.dylib
+ *   Windows    : cavs_sdk.dll
+ *
+ * Memory ownership:
+ *   - Handles (CavsContext*, CavsResult*, CavsJob*) are freed by their
+ *     matching *_free function, exactly once.
+ *   - char* returned by cavs_sdk_capabilities_json() must be freed with
+ *     cavs_string_free().
+ *   - char* returned by cavs_sdk_version()/cavs_sdk_abi_version() is static
+ *     and must NOT be freed.
+ *   - char* returned by cavs_result_json()/error_code()/error_message() is
+ *     owned by the CavsResult and freed by cavs_result_free().
+ *
+ * Threading:
+ *   - cavs_execute_json() runs on the calling thread.
+ *   - cavs_start_json() runs on a background thread; a registered progress
+ *     callback may be invoked from that thread and must be thread-safe.
+ */
+#ifndef CAVS_SDK_H
+#define CAVS_SDK_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct CavsContext CavsContext;
+typedef struct CavsResult CavsResult;
+typedef struct CavsJob CavsJob;
+
+typedef void (*CavsProgressCallback)(const char *event_json, void *user_data);
+
+/* --- Version / capabilities --------------------------------------------- */
+
+/* Static strings; do NOT free. */
+const char *cavs_sdk_version(void);
+const char *cavs_sdk_abi_version(void);
+
+/* Heap string; free with cavs_string_free(). */
+char *cavs_sdk_capabilities_json(void);
+
+/* --- Context ------------------------------------------------------------- */
+
+CavsContext *cavs_context_new(const char *options_json);
+void cavs_context_free(CavsContext *ctx);
+
+/* Returns 0 on success, -1 if ctx is NULL. Pass a NULL callback to clear. */
+int cavs_context_set_progress_callback(CavsContext *ctx,
+                                       CavsProgressCallback callback,
+                                       void *user_data);
+
+/* --- Synchronous execution ---------------------------------------------- */
+
+/* Runs on the calling thread. Free the result with cavs_result_free(). */
+CavsResult *cavs_execute_json(CavsContext *ctx,
+                             const char *operation,
+                             const char *request_json);
+
+/* --- Asynchronous jobs --------------------------------------------------- */
+
+CavsJob *cavs_start_json(CavsContext *ctx,
+                        const char *operation,
+                        const char *request_json);
+
+/* Returns the result if finished, else NULL (still running). */
+CavsResult *cavs_job_poll(CavsJob *job);
+
+/* Request cooperative cancellation. Returns 0 on success, -1 if NULL. */
+int cavs_job_cancel(CavsJob *job);
+
+/* Frees the job; joins the worker thread first. */
+void cavs_job_free(CavsJob *job);
+
+/* --- Result accessors ---------------------------------------------------- */
+
+const char *cavs_result_json(const CavsResult *result);
+int cavs_result_ok(const CavsResult *result);
+const char *cavs_result_error_code(const CavsResult *result);
+const char *cavs_result_error_message(const CavsResult *result);
+void cavs_result_free(CavsResult *result);
+
+/* --- Misc ---------------------------------------------------------------- */
+
+void cavs_string_free(char *ptr);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* CAVS_SDK_H */

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@orelvis15/cavs-sdk",
+  "version": "1.2.0",
+  "description": "Node.js SDK for CAVS — analyze, preview, pack, plan, apply, verify and benchmark game updates using the native Rust core.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/orelvis15/cavs-oss.git",
+    "directory": "sdks/node"
+  },
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "files": [
+    "dist",
+    "native/cavs_sdk.h"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "native": "cargo build --release -p cavs-ffi --manifest-path ../../Cargo.toml && node scripts/stage-native.mjs",
+    "pretest": "npm run build",
+    "test": "node --test dist/test/",
+    "lint": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "koffi": "^2.9.0"
+  },
+  "optionalDependencies": {
+    "@orelvis15/cavs-sdk-linux-x64": "1.2.0",
+    "@orelvis15/cavs-sdk-linux-arm64": "1.2.0",
+    "@orelvis15/cavs-sdk-darwin-x64": "1.2.0",
+    "@orelvis15/cavs-sdk-darwin-arm64": "1.2.0",
+    "@orelvis15/cavs-sdk-win32-x64": "1.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0"
+  }
+}