@supernovae-st/nika 0.71.0 → 0.118.7

package/dist/bin/nika.js

@@ -0,0 +1,407 @@
+#!/usr/bin/env node
+
+// src/bin/nika.ts
+import { spawn as spawn2 } from "child_process";
+
+// src/errors.ts
+var NikaError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "NikaError";
+  }
+};
+var NikaConfigurationError = class extends NikaError {
+  constructor(message) {
+    super(message);
+    this.name = "NikaConfigurationError";
+  }
+};
+var NikaTransportError = class extends NikaError {
+  transport;
+  constructor(transport, message, options) {
+    super(message, options);
+    this.name = "NikaTransportError";
+    this.transport = transport;
+  }
+};
+var NikaCompatibilityError = class extends NikaError {
+  capability;
+  transport;
+  constructor(capability, transport, message) {
+    super(message);
+    this.name = "NikaCompatibilityError";
+    this.capability = capability;
+    this.transport = transport;
+  }
+};
+var NikaProtocolError = class extends NikaTransportError {
+  constructor(transport, message, options) {
+    super(transport, message, options);
+    this.name = "NikaProtocolError";
+  }
+};
+
+// src/lib/binary/error.ts
+var NikaEngineUnavailable = class extends NikaError {
+  code = "NIKA_ENGINE_UNAVAILABLE";
+  platform;
+  arch;
+  packageName;
+  constructor(platform, arch, packageName) {
+    const target = `${platform}-${arch}`;
+    const detail = packageName ? `the optional payload ${packageName} is not installed (npm leaves it UNMET OPTIONAL when the registry has no version matching this client)` : "there is no packaged payload for this host";
+    super(
+      `Nika engine unavailable for ${target}: ${detail}. A nika found on PATH is deliberately not used. Set NIKA_BIN=/absolute/path/to/nika, pass config.bin, or install the matching payload package.`
+    );
+    this.name = "NikaEngineUnavailable";
+    this.platform = platform;
+    this.arch = arch;
+    this.packageName = packageName;
+  }
+};
+
+// src/lib/binary/packages.ts
+var NATIVE_PACKAGES = {
+  "darwin-arm64": "@supernovae-st/nika-darwin-arm64",
+  "darwin-x64": "@supernovae-st/nika-darwin-x64",
+  "linux-x64": "@supernovae-st/nika-linux-x64",
+  "linux-arm64": "@supernovae-st/nika-linux-arm64"
+};
+function packageForHost(platform, arch, glibc) {
+  if (platform === "linux" && !glibc) return void 0;
+  return NATIVE_PACKAGES[`${platform}-${arch}`];
+}
+
+// src/lib/binary/resolve.ts
+import { createRequire } from "module";
+import path from "path";
+var requireFromBundle = createRequire(
+  typeof import.meta.url === "string" ? import.meta.url : __filename
+);
+function resolveNikaEngine(configuredBin, host = {}) {
+  if (configuredBin !== void 0) {
+    return { bin: absoluteEnginePath(configuredBin, "bin") };
+  }
+  const envBin = (host.env ?? process.env).NIKA_BIN;
+  if (envBin !== void 0) {
+    return { bin: absoluteEnginePath(envBin, "NIKA_BIN") };
+  }
+  const platform = host.platform ?? process.platform;
+  const arch = host.arch ?? process.arch;
+  const packageName = packageForHost(
+    platform,
+    arch,
+    host.glibc ?? runtimeIsGlibc(platform)
+  );
+  if (!packageName) throw new NikaEngineUnavailable(platform, arch);
+  try {
+    const packageJson = (host.resolvePackageJson ?? requireFromBundle.resolve)(
+      `${packageName}/package.json`
+    );
+    const packageRoot = path.dirname(packageJson);
+    return {
+      bin: path.join(packageRoot, "bin", "nika"),
+      packageName,
+      packageRoot
+    };
+  } catch (cause) {
+    if (isMissingModule(cause)) {
+      throw new NikaEngineUnavailable(platform, arch, packageName);
+    }
+    throw cause;
+  }
+}
+function absoluteEnginePath(value, source) {
+  if (value.length === 0) {
+    throw new NikaConfigurationError(`${source} must be a non-empty string`);
+  }
+  if (!path.isAbsolute(value)) {
+    throw new NikaConfigurationError(
+      `${source} must be an absolute path to a nika engine (got "${value}"); a bare name or a relative path would be resolved through PATH or the working directory, which this client refuses`
+    );
+  }
+  return value;
+}
+function runtimeIsGlibc(platform) {
+  if (platform !== "linux") return true;
+  const report = process.report?.getReport();
+  return typeof report?.header?.glibcVersionRuntime === "string";
+}
+function isMissingModule(cause) {
+  return cause instanceof Error && "code" in cause && cause.code === "MODULE_NOT_FOUND";
+}
+
+// src/lib/binary/verify.ts
+import { createHash } from "crypto";
+import { createReadStream } from "fs";
+import { readFile, stat } from "fs/promises";
+import path2 from "path";
+
+// src/lib/engine-capture.ts
+import { spawn } from "child_process";
+function captureEngine(bin, args, options) {
+  return new Promise((resolve, reject) => {
+    if (options.signal?.aborted) {
+      reject(new NikaTransportError(options.transport, `${options.label} aborted by caller`));
+      return;
+    }
+    const child = spawn(bin, args, {
+      cwd: options.cwd,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    let overflow = false;
+    let spawnError;
+    const append = (stream, chunk) => {
+      if (overflow) return;
+      if (stream === "stdout") stdout += chunk;
+      else stderr += chunk;
+      if (Buffer.byteLength(stdout) > options.bufferBytes || Buffer.byteLength(stderr) > options.bufferBytes) {
+        overflow = true;
+        child.kill("SIGTERM");
+      }
+    };
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => append("stdout", chunk));
+    child.stderr.on("data", (chunk) => append("stderr", chunk));
+    const abort = () => child.kill("SIGTERM");
+    options.signal?.addEventListener("abort", abort, { once: true });
+    child.once("error", (cause) => {
+      spawnError = cause;
+    });
+    child.once("close", (code) => {
+      options.signal?.removeEventListener("abort", abort);
+      if (options.signal?.aborted) {
+        reject(new NikaTransportError(options.transport, `${options.label} aborted by caller`));
+      } else if (spawnError) {
+        reject(new NikaTransportError(
+          options.transport,
+          `Cannot spawn ${bin} for ${options.label}: ${spawnError.message}`,
+          { cause: spawnError }
+        ));
+      } else if (overflow) {
+        reject(new NikaProtocolError(
+          options.transport,
+          `${options.label} exceeded ${options.bufferBytes} bytes`
+        ));
+      } else {
+        resolve({ exitCode: code ?? 3, stdout, stderr });
+      }
+    });
+  });
+}
+
+// src/lib/machine.ts
+function machineObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+
+// src/lib/engine-identity.ts
+var MACHINE_PROTOCOL_VERSION = 1;
+var REQUIRED_CAPABILITIES = ["check", "executionSnapshot", "eventStream"];
+var COMPATIBILITY_CLOCKS = [
+  "machineProtocolVersion",
+  "snapshotFormatVersion",
+  "checkReportVersion",
+  "eventFormatVersion"
+];
+function compatibleEngineIdentity(value, transport, peer) {
+  const identity = machineObject(value);
+  if (!identity) throw incompatible(transport, "Engine identity is not an object");
+  if (typeof identity.engineVersion !== "string" || identity.engineVersion.length === 0) {
+    throw incompatible(transport, "Engine identity is missing engineVersion");
+  }
+  for (const clock of COMPATIBILITY_CLOCKS) {
+    if (!Number.isSafeInteger(identity[clock])) {
+      throw incompatible(transport, `Engine identity is missing ${clock}`);
+    }
+  }
+  if (identity.machineProtocolVersion !== MACHINE_PROTOCOL_VERSION) {
+    throw incompatible(
+      transport,
+      `Engine machine protocol ${String(identity.machineProtocolVersion)} is incompatible with SDK protocol ${MACHINE_PROTOCOL_VERSION}`
+    );
+  }
+  if (!Array.isArray(identity.supportedCapabilities) || !identity.supportedCapabilities.every((item) => typeof item === "string")) {
+    throw incompatible(transport, "Engine identity is missing supportedCapabilities");
+  }
+  for (const capability of REQUIRED_CAPABILITIES) {
+    if (!identity.supportedCapabilities.includes(capability)) {
+      throw incompatible(transport, `Engine identity does not support ${capability}`);
+    }
+  }
+  const checked = identity;
+  if (peer) {
+    for (const clock of COMPATIBILITY_CLOCKS) {
+      if (checked[clock] !== peer[clock]) {
+        throw incompatible(
+          transport,
+          `Remote ${clock} ${checked[clock]} is incompatible with local ${clock} ${peer[clock]}`
+        );
+      }
+    }
+  }
+  return checked;
+}
+function incompatible(transport, message) {
+  return new NikaCompatibilityError("engineIdentity", transport, message);
+}
+
+// src/lib/binary/verify.ts
+var IDENTITY_BUFFER_BYTES = 16 * 1024;
+async function verifyNikaEngine(engine) {
+  const expectedVersion = engine.packageRoot ? await verifyManagedPayload(engine) : void 0;
+  const identity = await probeIdentity(engine.bin);
+  if (expectedVersion !== void 0 && identity.engineVersion !== expectedVersion) {
+    throw incompatible2(
+      `Packaged engine version ${identity.engineVersion} does not match payload version ${expectedVersion}`
+    );
+  }
+  return identity;
+}
+async function verifyManagedPayload(engine) {
+  const packageRoot = engine.packageRoot;
+  if (!packageRoot || !engine.packageName) {
+    throw incompatible2("Managed engine resolution is missing package identity");
+  }
+  const manifest = await readJson(path2.join(packageRoot, "package.json"), "payload manifest");
+  if (manifest.name !== engine.packageName || typeof manifest.version !== "string") {
+    throw incompatible2(`Invalid manifest for ${engine.packageName}`);
+  }
+  const integrity = await readJson(
+    path2.join(packageRoot, "INTEGRITY.json"),
+    "payload integrity metadata"
+  );
+  if (integrity.algorithm !== "sha256" || integrity.executable?.file !== "bin/nika" || !isSha256(integrity.executable?.sha256)) {
+    throw incompatible2(`Invalid INTEGRITY.json for ${engine.packageName}`);
+  }
+  let metadata;
+  try {
+    metadata = await stat(engine.bin);
+  } catch (cause) {
+    throw incompatible2(`Cannot read packaged engine ${engine.bin}`, cause);
+  }
+  if (!metadata.isFile()) {
+    throw incompatible2(`Packaged engine is not a file: ${engine.bin}`);
+  }
+  const actual = await sha256(engine.bin);
+  if (actual !== integrity.executable.sha256) {
+    throw incompatible2(`Packaged engine checksum mismatch for ${engine.packageName}`);
+  }
+  return manifest.version;
+}
+async function probeIdentity(bin) {
+  const notAnEngine = `is ${bin} a nika engine? (run "${bin} --sdk-identity" by hand)`;
+  const captured = await captureEngine(bin, ["--sdk-identity"], {
+    bufferBytes: IDENTITY_BUFFER_BYTES,
+    transport: "native-process",
+    label: "Engine identity probe"
+  }).catch((cause) => {
+    throw incompatible2(
+      `Engine identity probe of ${bin} failed`,
+      cause
+    );
+  });
+  if (captured.exitCode !== 0) {
+    throw incompatible2(
+      `Engine identity probe of ${bin} exited with code ${captured.exitCode}; ${notAnEngine}`
+    );
+  }
+  let value;
+  try {
+    value = JSON.parse(captured.stdout.trim());
+  } catch (cause) {
+    throw incompatible2(
+      `Engine identity probe of ${bin} did not emit one JSON object; ${notAnEngine}`,
+      cause
+    );
+  }
+  if (captured.stderr.trim()) {
+    throw incompatible2(`Engine identity probe of ${bin} wrote unexpected diagnostics`);
+  }
+  try {
+    return compatibleEngineIdentity(value, "native-process");
+  } catch (cause) {
+    if (cause instanceof NikaCompatibilityError) throw cause;
+    throw incompatible2("Engine identity probe was incompatible", cause);
+  }
+}
+async function readJson(file, label) {
+  try {
+    const parsed = JSON.parse(await readFile(file, "utf8"));
+    if (!isRecord(parsed)) throw new TypeError(`${label} is not an object`);
+    return parsed;
+  } catch (cause) {
+    throw incompatible2(`Cannot verify ${label} at ${file}`, cause);
+  }
+}
+function sha256(file) {
+  return new Promise((resolve, reject) => {
+    const hash = createHash("sha256");
+    const stream = createReadStream(file);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.once("error", reject);
+    stream.once("end", () => resolve(hash.digest("hex")));
+  });
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isSha256(value) {
+  return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+function incompatible2(message, cause) {
+  return new NikaCompatibilityError(
+    "engineIdentity",
+    "native-process",
+    cause instanceof Error ? `${message}: ${cause.message}` : message
+  );
+}
+
+// src/bin/nika.ts
+var FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+async function main(argv = process.argv.slice(2)) {
+  let engine;
+  try {
+    engine = resolveNikaEngine();
+    await verifyNikaEngine(engine);
+  } catch (cause) {
+    const message = cause instanceof NikaEngineUnavailable || cause instanceof Error ? cause.message : String(cause);
+    console.error(`nika: ${message}`);
+    process.exitCode = 1;
+    return;
+  }
+  const child = spawn2(engine.bin, argv, {
+    shell: false,
+    stdio: "inherit"
+  });
+  const handlers = /* @__PURE__ */ new Map();
+  for (const signal of FORWARDED_SIGNALS) {
+    const handler = () => child.kill(signal);
+    handlers.set(signal, handler);
+    process.on(signal, handler);
+  }
+  const removeHandlers = () => {
+    for (const [signal, handler] of handlers) process.off(signal, handler);
+  };
+  child.once("error", (cause) => {
+    removeHandlers();
+    console.error(`nika: Cannot spawn ${engine.bin}: ${cause.message}`);
+    process.exitCode = 1;
+  });
+  child.once("exit", (code, signal) => {
+    removeHandlers();
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exitCode = code ?? 1;
+  });
+}
+await main();
+export {
+  main
+};