kibi-swipl 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# kibi-swipl
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Locates the bundled SWI-Prolog runtime that [Kibi](https://github.com/Looted/kibi)
+uses. It is a dependency of `kibi-cli` and `kibi-runtime`; you normally never
+install or import it yourself.
+
+`kibi-swipl` lists one platform package per supported target as an optional
+dependency, so the package manager installs only the one that matches the
+machine:
+
+| Platform | Package |
+| --- | --- |
+| Linux x64 (glibc) | `kibi-swipl-linux-x64-gnu` |
+| Linux arm64 (glibc) | `kibi-swipl-linux-arm64-gnu` |
+| macOS arm64 | `kibi-swipl-darwin-arm64` |
+| macOS x64 | `kibi-swipl-darwin-x64` |
+
+Alpine (musl) and native Windows have no bundle; install SWI-Prolog 9.0+ and put
+`swipl` on `PATH`, or point `KIBI_SWIPL` at it.
+
+Kibi resolves SWI-Prolog in this order: `KIBI_SWIPL=<absolute path>`, the bundled
+platform package (after checking its manifest and binary checksum), then `swipl`
+on `PATH` (9.0 or newer). `KIBI_SWIPL=system` skips the bundle.
+
+The package versions independently of SWI-Prolog; the upstream version each
+platform package carries is recorded in its `kibi.swiplVersion` field.

package/index.d.ts

@@ -0,0 +1,49 @@
+export declare const MANIFEST_FILE: "build-manifest.json";
+export declare const MANIFEST_SCHEMA: "kibi.swipl-build.v1";
+export declare const BUNDLED_BINARY_PATH: "bin/swipl";
+
+export type PlatformKey =
+  | "linux-x64-gnu"
+  | "linux-arm64-gnu"
+  | "darwin-arm64"
+  | "darwin-x64";
+
+export type PlatformPackage = {
+  readonly package: string;
+  readonly os: "linux" | "darwin";
+  readonly cpu: "x64" | "arm64";
+  readonly libc?: "glibc";
+};
+
+export declare const PLATFORM_PACKAGES: Readonly<
+  Record<PlatformKey, PlatformPackage>
+>;
+
+export declare function platformKey(host: {
+  platform: string;
+  arch: string;
+  /** True only for glibc Linux; musl and unknown libc have no bundle. */
+  glibc?: boolean | undefined;
+}): PlatformKey | undefined;
+
+export declare function locatePlatformPackage(
+  packageName: string,
+  requireFrom?: { resolve(request: string): string },
+): string | undefined;
+
+export type BuildManifestValidation =
+  | {
+      ok: true;
+      swiplVersion: string;
+      binaryPath: "bin/swipl";
+      binarySha256: string;
+      home: string;
+    }
+  | { ok: false; reason: string };
+
+export declare function validateBuildManifest(
+  manifest: unknown,
+  expected: { target: string; swiplVersion?: string | undefined },
+): BuildManifestValidation;
+
+export declare function sha256File(filePath: string): string;

package/index.js

@@ -0,0 +1,162 @@
+/*
+ * Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ * Copyright (C) 2026 Piotr Franczyk
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ */
+
+// Platform table, bundle-manifest validation, and package location for the
+// bundled SWI-Prolog runtime. Kibi's resolver (kibi-cli) owns the lookup order;
+// this module only knows what a valid per-platform package looks like.
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+export const MANIFEST_FILE = "build-manifest.json";
+export const MANIFEST_SCHEMA = "kibi.swipl-build.v1";
+export const BUNDLED_BINARY_PATH = "bin/swipl";
+
+/** Platform key -> platform package, in a stable documented order. */
+export const PLATFORM_PACKAGES = Object.freeze({
+  "linux-x64-gnu": Object.freeze({
+    package: "kibi-swipl-linux-x64-gnu",
+    os: "linux",
+    cpu: "x64",
+    libc: "glibc",
+  }),
+  "linux-arm64-gnu": Object.freeze({
+    package: "kibi-swipl-linux-arm64-gnu",
+    os: "linux",
+    cpu: "arm64",
+    libc: "glibc",
+  }),
+  "darwin-arm64": Object.freeze({
+    package: "kibi-swipl-darwin-arm64",
+    os: "darwin",
+    cpu: "arm64",
+  }),
+  "darwin-x64": Object.freeze({
+    package: "kibi-swipl-darwin-x64",
+    os: "darwin",
+    cpu: "x64",
+  }),
+});
+
+/**
+ * Map a host to a platform key, or undefined when no bundle is published for
+ * it (native Windows, musl Linux, other architectures).
+ */
+export function platformKey({ platform, arch, glibc }) {
+  if (platform === "linux") {
+    if (glibc !== true) return undefined;
+    return arch === "x64" || arch === "arm64" ? `linux-${arch}-gnu` : undefined;
+  }
+  if (platform === "darwin") {
+    return arch === "x64" || arch === "arm64" ? `darwin-${arch}` : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Directory of an installed platform package, found from this package's own
+ * location (platform packages are optional dependencies of kibi-swipl, so a
+ * strict package manager only exposes them here). Undefined when absent.
+ */
+export function locatePlatformPackage(
+  packageName,
+  requireFrom = createRequire(import.meta.url),
+) {
+  try {
+    return path.dirname(requireFrom.resolve(`${packageName}/package.json`));
+  } catch (error) {
+    const code = error && typeof error === "object" ? error.code : undefined;
+    if (code === "MODULE_NOT_FOUND" || code === "ERR_PACKAGE_PATH_NOT_EXPORTED")
+      return undefined;
+    throw error;
+  }
+}
+
+function safeRelativePath(value) {
+  if (typeof value !== "string" || value.length === 0) return false;
+  if (value.includes("\\") || value.includes("\0")) return false;
+  if (path.posix.isAbsolute(value)) return false;
+  const normalized = path.posix.normalize(value);
+  return (
+    normalized === value &&
+    normalized !== "." &&
+    !normalized.split("/").includes("..")
+  );
+}
+
+/**
+ * Validate a platform package's build manifest (the swipl-build pipeline's
+ * build-manifest.json). Returns { ok: true, ... } or { ok: false, reason }.
+ */
+export function validateBuildManifest(manifest, expected) {
+  if (
+    manifest === null ||
+    typeof manifest !== "object" ||
+    Array.isArray(manifest)
+  )
+    return { ok: false, reason: "manifest is not a JSON object" };
+  if (manifest.schema !== MANIFEST_SCHEMA)
+    return {
+      ok: false,
+      reason: `manifest schema must be ${MANIFEST_SCHEMA}`,
+    };
+  if (manifest.target !== expected.target)
+    return {
+      ok: false,
+      reason: `manifest target ${JSON.stringify(manifest.target)} does not match ${expected.target}`,
+    };
+  if (
+    typeof manifest.swiplVersion !== "string" ||
+    !/^\d+\.\d+\.\d+$/.test(manifest.swiplVersion)
+  )
+    return { ok: false, reason: "manifest swiplVersion is missing or invalid" };
+  if (
+    expected.swiplVersion !== undefined &&
+    manifest.swiplVersion !== expected.swiplVersion
+  )
+    return {
+      ok: false,
+      reason: `manifest swiplVersion ${manifest.swiplVersion} does not match package kibi.swiplVersion ${expected.swiplVersion}`,
+    };
+  const binary = manifest.binary;
+  if (binary === null || typeof binary !== "object")
+    return { ok: false, reason: "manifest binary entry is missing" };
+  if (binary.path !== BUNDLED_BINARY_PATH)
+    return {
+      ok: false,
+      reason: `manifest binary.path must be ${BUNDLED_BINARY_PATH}`,
+    };
+  if (
+    typeof binary.sha256 !== "string" ||
+    !/^[0-9a-f]{64}$/.test(binary.sha256)
+  )
+    return {
+      ok: false,
+      reason: "manifest binary.sha256 must be 64 lowercase hex digits",
+    };
+  if (!safeRelativePath(manifest.home))
+    return {
+      ok: false,
+      reason: "manifest home must be a normalized relative path",
+    };
+  return {
+    ok: true,
+    swiplVersion: manifest.swiplVersion,
+    binaryPath: binary.path,
+    binarySha256: binary.sha256,
+    home: manifest.home,
+  };
+}
+
+export function sha256File(filePath) {
+  return createHash("sha256").update(readFileSync(filePath)).digest("hex");
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "kibi-swipl",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Locates the bundled SWI-Prolog runtime that Kibi uses on this platform",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["index.js", "index.d.ts", "README.md"],
+  "scripts": {
+    "test": "bun test --timeout 15000 ."
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "AGPL-3.0-or-later",
+  "author": "Piotr Franczyk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Looted/kibi.git",
+    "directory": "packages/swipl"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "kibi": {
+    "swiplVersion": "10.0.2"
+  },
+  "optionalDependencies": {
+    "kibi-swipl-linux-x64-gnu": "1.0.0",
+    "kibi-swipl-linux-arm64-gnu": "1.0.0",
+    "kibi-swipl-darwin-arm64": "1.0.0",
+    "kibi-swipl-darwin-x64": "1.0.0"
+  }
+}