khive 0.0.1 → 0.2.5

package/README.md

@@ -0,0 +1,50 @@
+# khive
+
+A research knowledge graph runtime — 63 verbs, 7 packs, one MCP tool.
+
+[![GitHub](https://img.shields.io/github/stars/ohdearquant/khive?style=flat)](https://github.com/ohdearquant/khive)
+[![crates.io](https://img.shields.io/crates/v/khive-mcp.svg)](https://crates.io/crates/khive-mcp)
+
+## Install
+
+```bash
+npm install -g khive
+```
+
+## Configure
+
+Add to `.mcp.json` (project-level or `~/.claude/mcp.json` for global):
+
+```json
+{ "mcpServers": { "khive": { "command": "khive", "args": ["mcp"] } } }
+```
+
+All 7 packs load by default. A background daemon auto-spawns to keep the runtime warm.
+
+## What you get
+
+| Pack          | Verbs | What it does                                     |
+| ------------- | ----- | ------------------------------------------------ |
+| **kg**        | 16    | Entities, edges, notes, graph queries, proposals |
+| **gtd**       | 5     | Task lifecycle (inbox → next → active → done)    |
+| **memory**    | 2     | Salience-weighted remember / decay-ranked recall |
+| **brain**     | 13    | Bayesian user profiles + feedback loop           |
+| **comm**      | 5     | Threaded messaging                               |
+| **schedule**  | 4     | Reminders and scheduled verb execution           |
+| **knowledge** | 18    | Atom-based KB with embedding rerank search       |
+
+## Usage
+
+```text
+khive mcp                   # Start MCP server (used by Claude Code)
+khive kg init               # Initialize .khive/kg/ in a git repo
+khive kg validate           # Check NDJSON files against schema
+khive kg commit -m "msg"    # Validate + stage + git commit
+```
+
+## Documentation
+
+- [GitHub](https://github.com/ohdearquant/khive)
+- [AGENTS.md](https://github.com/ohdearquant/khive/blob/main/AGENTS.md) — full verb reference
+- [Marketplace plugins](https://github.com/ohdearquant/khive/tree/main/marketplace) — Claude Code
+  skills

package/bin/khive

@@ -1,3 +1,200 @@
 #!/usr/bin/env node
-console.log("khive CLI — coming soon. Visit https://khive.ai for early access.");
-process.exit(0);
+
+// khive — per-platform binary shim (ADR-026)
+//
+// Resolves the host platform to the matching @khive-ai/kernel-{platform}
+// optional dependency and execs the kkernel binary from its bin/ directory.
+// Falls back to a local cargo build directory for monorepo development.
+//
+// NOTE: npm/bin/khive-mcp is a sibling shim that resolves khive-mcp using
+// the same logic. Both shims share `resolveBinaryPath()` — keep them in sync.
+
+"use strict";
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+
+// Map os.platform()+os.arch() → @khive-ai/kernel-{platform} package name suffix.
+// Follows the naming established in ADR-026.
+//
+// NOTE: linux-arm64 is glibc-only in v1. Musl arm64 is not yet in the matrix.
+// If musl is detected on arm64, `detectLinuxVariant` returns null and we error
+// with a clear "unsupported" message — see getBinaryPath() below.
+const PLATFORM_MAP = {
+  "darwin-arm64": "darwin-arm64",
+  "darwin-x64": "darwin-x64",
+  "linux-arm64": null, // resolved dynamically: glibc=linux-arm64, musl=unsupported
+  "linux-x64": null,   // resolved dynamically by detectLinuxVariant()
+  "win32-x64": "win32-x64",
+};
+
+/**
+ * Detect whether the Linux runtime links against glibc or musl.
+ * Detection order (most-reliable first):
+ *   1. `ldd --version` — invokes the actual system linker
+ *   2. `/lib/ld-musl-*` glob — fast filesystem check
+ * Returns "gnu" or "musl". Defaults to "gnu" if detection is inconclusive.
+ *
+ * NOTE: cli/lib/kernel.ts uses the same ordered detection. Keep them in sync.
+ */
+function detectLibc() {
+  try {
+    const ldd = require("child_process")
+      .execFileSync("ldd", ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
+      .toLowerCase();
+    if (ldd.includes("musl")) return "musl";
+    return "gnu";
+  } catch (_) {
+    // ldd not available or returned non-zero — check /lib/ld-musl-* presence
+    try {
+      const libs = fs.readdirSync("/lib");
+      if (libs.some((f) => f.startsWith("ld-musl-"))) return "musl";
+    } catch (_) {}
+    return "gnu";
+  }
+}
+
+const SUPPORTED_PLATFORMS = [
+  "darwin-arm64",
+  "darwin-x64",
+  "linux-x64-gnu",
+  "linux-x64-musl",
+  "linux-arm64",
+  "win32-x64",
+];
+
+function getPlatformKey() {
+  return `${os.platform()}-${os.arch()}`;
+}
+
+/**
+ * Resolve the platform suffix for the @khive-ai/kernel-{platform} subpackage.
+ * Returns null if the platform is recognized but unsupported (musl arm64).
+ * Returns undefined if the platform is entirely unknown.
+ */
+function resolvePlatformSuffix() {
+  const platformKey = getPlatformKey();
+  if (platformKey === "linux-x64") {
+    const libc = detectLibc();
+    return libc === "musl" ? "linux-x64-musl" : "linux-x64-gnu";
+  }
+  if (platformKey === "linux-arm64") {
+    const libc = detectLibc();
+    if (libc === "musl") {
+      // musl arm64 is not in the v1 matrix — emit a clear error instead of
+      // silently falling back to the glibc arm64 binary (which will fail with
+      // a cryptic ENOENT when the glibc loader is absent).
+      return null; // caller treats null as "unsupported but recognized"
+    }
+    return "linux-arm64";
+  }
+  return PLATFORM_MAP[platformKey]; // darwin-arm64, darwin-x64, win32-x64
+}
+
+/**
+ * Locate the named binary using the platform subpackage resolution strategy:
+ *   1. KKERNEL_BINARY env var override (development / CI)
+ *   2. Package-manager-agnostic resolution via require.resolve (works with
+ *      npm, yarn, and pnpm including isolated-store layouts)
+ *   3. Dev fallback: cargo build directory inside the monorepo
+ *
+ * `binaryName` is "kkernel" or "khive-mcp" (without .exe; added for Windows).
+ */
+function getBinaryPath(binaryName) {
+  const isWindows = os.platform() === "win32";
+  const exe = isWindows ? `${binaryName}.exe` : binaryName;
+
+  // 1. Explicit override env var. For kkernel the conventional var is
+  //    KKERNEL_BINARY; for khive-mcp we accept KHIVE_MCP_BINARY.
+  const envVar = binaryName === "kkernel" ? "KKERNEL_BINARY" : "KHIVE_MCP_BINARY";
+  const override = process.env[envVar];
+  if (override && fs.existsSync(override)) return override;
+
+  const platformSuffix = resolvePlatformSuffix();
+
+  // null means recognized-but-unsupported platform (musl arm64)
+  if (platformSuffix === null) {
+    const platformKey = getPlatformKey();
+    const libc = detectLibc();
+    console.error(`khive: unsupported platform: ${platformKey} (libc: ${libc})`);
+    console.error("linux-arm64 with musl is not in the v1 release matrix.");
+    console.error("Supported: " + SUPPORTED_PLATFORMS.join(", "));
+    console.error(
+      "File an issue at https://github.com/ohdearquant/khive/issues if you need this target.",
+    );
+    process.exit(1);
+  }
+
+  // undefined means completely unknown platform
+  if (platformSuffix === undefined) {
+    const platformKey = getPlatformKey();
+    console.error(`khive: unsupported platform: ${platformKey}`);
+    console.error("Supported: " + SUPPORTED_PLATFORMS.join(", "));
+    console.error(
+      "File an issue at https://github.com/ohdearquant/khive/issues if you need this target.",
+    );
+    process.exit(1);
+  }
+
+  const pkgName = `@khive-ai/kernel-${platformSuffix}`;
+
+  // 2. Package-manager-agnostic resolution. `require.resolve` honours npm,
+  //    yarn, AND pnpm's isolated-store layout (node_modules/.pnpm/...).
+  //    Walk-up approaches break under pnpm's default shamefully-hoist=false.
+  try {
+    const pkgJsonPath = require.resolve(`${pkgName}/package.json`);
+    const pkgDir = path.dirname(pkgJsonPath);
+    const candidate = path.join(pkgDir, "bin", exe);
+    if (fs.existsSync(candidate)) return candidate;
+  } catch (_) {
+    // Package not installed — fall through to dev fallback.
+  }
+
+  // 3. Dev fallback: look for a cargo build in typical monorepo locations.
+  const devCandidates = [];
+  let search = path.join(__dirname, "..");
+  for (let i = 0; i < 8; i++) {
+    const cratesDir = path.join(search, "crates");
+    if (fs.existsSync(cratesDir)) {
+      devCandidates.push(path.join(cratesDir, "target", "release", exe));
+      devCandidates.push(path.join(cratesDir, "target", "debug", exe));
+      break;
+    }
+    const parent = path.dirname(search);
+    if (parent === search) break;
+    search = parent;
+  }
+  for (const c of devCandidates) {
+    if (fs.existsSync(c)) return c;
+  }
+
+  console.error(`khive: ${pkgName} not installed or ${binaryName} binary not found.`);
+  console.error(`Expected: ${pkgName}/bin/${exe}`);
+  console.error(
+    "Run 'npm install -g khive' to install platform binaries, or set " +
+      `${envVar} to point to a local build.`,
+  );
+  process.exit(1);
+}
+
+// `khive mcp [args]` dispatches to the khive-mcp binary (MCP stdio server).
+// All other subcommands dispatch to kkernel (admin CLI).
+const subcommand = process.argv[2];
+const isMcp = subcommand === "mcp";
+const binaryName = isMcp ? "khive-mcp" : "kkernel";
+const args = isMcp ? process.argv.slice(3) : process.argv.slice(2);
+
+try {
+  const binary = getBinaryPath(binaryName);
+  execFileSync(binary, args, {
+    stdio: "inherit",
+    env: process.env,
+  });
+} catch (err) {
+  if (err.status !== undefined) {
+    process.exit(err.status);
+  }
+  throw err;
+}

package/bin/khive-mcp

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+// khive-mcp — per-platform binary shim for the MCP stdio server (ADR-026)
+//
+// Resolves the host platform to the matching @khive-ai/kernel-{platform}
+// optional dependency and execs the khive-mcp binary from its bin/ directory.
+// Falls back to a local cargo build directory for monorepo development.
+//
+// This shim is the companion to npm/bin/khive. Both use the same
+// `getBinaryPath()` logic — see npm/bin/khive for comments and rationale.
+// Keep detection order and platform mapping in sync between the two shims.
+//
+// Users configure this binary in Claude Code's MCP config:
+//   {"mcpServers": {"khive": {"command": "khive-mcp"}}}
+
+"use strict";
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+
+/**
+ * Detect whether the Linux runtime links against glibc or musl.
+ * Detection order (most-reliable first):
+ *   1. `ldd --version` — invokes the actual system linker
+ *   2. `/lib/ld-musl-*` glob — fast filesystem check
+ * Returns "gnu" or "musl". Defaults to "gnu" if detection is inconclusive.
+ *
+ * NOTE: npm/bin/khive and cli/lib/kernel.ts use the same detection order.
+ * Keep all three in sync.
+ */
+function detectLibc() {
+  try {
+    const ldd = require("child_process")
+      .execFileSync("ldd", ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
+      .toLowerCase();
+    if (ldd.includes("musl")) return "musl";
+    return "gnu";
+  } catch (_) {
+    try {
+      const libs = fs.readdirSync("/lib");
+      if (libs.some((f) => f.startsWith("ld-musl-"))) return "musl";
+    } catch (_) {}
+    return "gnu";
+  }
+}
+
+const SUPPORTED_PLATFORMS = [
+  "darwin-arm64",
+  "darwin-x64",
+  "linux-x64-gnu",
+  "linux-x64-musl",
+  "linux-arm64",
+  "win32-x64",
+];
+
+function getPlatformKey() {
+  return `${os.platform()}-${os.arch()}`;
+}
+
+function resolvePlatformSuffix() {
+  const platformKey = getPlatformKey();
+  if (platformKey === "linux-x64") {
+    const libc = detectLibc();
+    return libc === "musl" ? "linux-x64-musl" : "linux-x64-gnu";
+  }
+  if (platformKey === "linux-arm64") {
+    const libc = detectLibc();
+    if (libc === "musl") return null; // unsupported, caller emits clear error
+    return "linux-arm64";
+  }
+  const PLATFORM_MAP = {
+    "darwin-arm64": "darwin-arm64",
+    "darwin-x64": "darwin-x64",
+    "win32-x64": "win32-x64",
+  };
+  return PLATFORM_MAP[platformKey];
+}
+
+function getBinaryPath(binaryName) {
+  const isWindows = os.platform() === "win32";
+  const exe = isWindows ? `${binaryName}.exe` : binaryName;
+
+  const envVar = binaryName === "kkernel" ? "KKERNEL_BINARY" : "KHIVE_MCP_BINARY";
+  const override = process.env[envVar];
+  if (override && fs.existsSync(override)) return override;
+
+  const platformSuffix = resolvePlatformSuffix();
+
+  if (platformSuffix === null) {
+    const platformKey = getPlatformKey();
+    const libc = detectLibc();
+    console.error(`khive-mcp: unsupported platform: ${platformKey} (libc: ${libc})`);
+    console.error("linux-arm64 with musl is not in the v1 release matrix.");
+    console.error("Supported: " + SUPPORTED_PLATFORMS.join(", "));
+    console.error(
+      "File an issue at https://github.com/ohdearquant/khive/issues if you need this target.",
+    );
+    process.exit(1);
+  }
+
+  if (platformSuffix === undefined) {
+    const platformKey = getPlatformKey();
+    console.error(`khive-mcp: unsupported platform: ${platformKey}`);
+    console.error("Supported: " + SUPPORTED_PLATFORMS.join(", "));
+    console.error(
+      "File an issue at https://github.com/ohdearquant/khive/issues if you need this target.",
+    );
+    process.exit(1);
+  }
+
+  const pkgName = `@khive-ai/kernel-${platformSuffix}`;
+
+  // Package-manager-agnostic resolution (npm, yarn, pnpm isolated-store).
+  try {
+    const pkgJsonPath = require.resolve(`${pkgName}/package.json`);
+    const pkgDir = path.dirname(pkgJsonPath);
+    const candidate = path.join(pkgDir, "bin", exe);
+    if (fs.existsSync(candidate)) return candidate;
+  } catch (_) {}
+
+  // Dev fallback: cargo build directory inside the monorepo.
+  const devCandidates = [];
+  let search = path.join(__dirname, "..");
+  for (let i = 0; i < 8; i++) {
+    const cratesDir = path.join(search, "crates");
+    if (fs.existsSync(cratesDir)) {
+      devCandidates.push(path.join(cratesDir, "target", "release", exe));
+      devCandidates.push(path.join(cratesDir, "target", "debug", exe));
+      break;
+    }
+    const parent = path.dirname(search);
+    if (parent === search) break;
+    search = parent;
+  }
+  for (const c of devCandidates) {
+    if (fs.existsSync(c)) return c;
+  }
+
+  console.error(`khive-mcp: ${pkgName} not installed or ${binaryName} binary not found.`);
+  console.error(`Expected: ${pkgName}/bin/${exe}`);
+  console.error(
+    "Run 'npm install -g khive' to install platform binaries, or set " +
+      `${envVar} to point to a local build.`,
+  );
+  process.exit(1);
+}
+
+try {
+  const binary = getBinaryPath("khive-mcp");
+  execFileSync(binary, process.argv.slice(2), {
+    stdio: "inherit",
+    env: process.env,
+  });
+} catch (err) {
+  if (err.status !== undefined) {
+    process.exit(err.status);
+  }
+  throw err;
+}

package/package.json

@@ -1,16 +1,46 @@
 {
   "name": "khive",
-  "version": "0.0.1",
-  "description": "khive — AI agent infrastructure. Memory, knowledge, tasks, and MCP tools for your AI workflows.",
-  "keywords": ["ai", "agents", "mcp", "memory", "knowledge-graph", "cli"],
-  "author": "Ocean HaiyangLi <ocean@khive.ai>",
-  "license": "UNLICENSED",
+  "version": "0.2.5",
+  "description": "Research knowledge graph CLI — git-native KG versioning",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/ohdearquant/khive"
   },
-  "homepage": "https://khive.ai",
+  "homepage": "https://github.com/ohdearquant",
+  "keywords": [
+    "knowledge-graph",
+    "research",
+    "git",
+    "ndjson",
+    "cli"
+  ],
   "bin": {
-    "khive": "./bin/khive"
+    "khive": "bin/khive",
+    "khive-mcp": "bin/khive-mcp"
+  },
+  "files": [
+    "bin/",
+    "README.md"
+  ],
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "arm64",
+    "x64"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@khive-ai/kernel-darwin-arm64": "0.2.5",
+    "@khive-ai/kernel-darwin-x64": "0.2.5",
+    "@khive-ai/kernel-linux-x64-gnu": "0.2.5",
+    "@khive-ai/kernel-linux-x64-musl": "0.2.5",
+    "@khive-ai/kernel-linux-arm64": "0.2.5",
+    "@khive-ai/kernel-win32-x64": "0.2.5"
   }
 }