@dug-21/unimatrix 0.5.5

package/bin/unimatrix.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+"use strict";
+
+const { execFileSync } = require("child_process");
+
+function main() {
+  const args = process.argv.slice(2);
+
+  // Route "init" to JS implementation (ADR-003)
+  if (args[0] === "init") {
+    const { init } = require("../lib/init.js");
+    const projectDirIdx = args.indexOf("--project-dir");
+    const projectDir =
+      projectDirIdx >= 0 && projectDirIdx + 1 < args.length
+        ? args[projectDirIdx + 1]
+        : undefined;
+    init({ dryRun: args.includes("--dry-run"), projectDir })
+      .then(() => {
+        process.exitCode = 0;
+      })
+      .catch((error) => {
+        process.stderr.write("unimatrix init failed: " + error.message + "\n");
+        process.exitCode = 1;
+      });
+    return;
+  }
+
+  // All other subcommands: resolve binary and exec
+  let binaryPath;
+  try {
+    binaryPath = require("../lib/resolve-binary.js").resolveBinary();
+  } catch (error) {
+    process.stderr.write(error.message + "\n");
+    process.exitCode = 1;
+    return;
+  }
+
+  // Ensure bundled shared libraries (libonnxruntime) are found at runtime
+  const binDir = require("path").dirname(binaryPath);
+  const ldPath = process.env.LD_LIBRARY_PATH;
+  const env = Object.assign({}, process.env, {
+    LD_LIBRARY_PATH: ldPath ? binDir + ":" + ldPath : binDir,
+  });
+
+  try {
+    execFileSync(binaryPath, args, { stdio: "inherit", env: env });
+  } catch (error) {
+    // execFileSync throws on non-zero exit code
+    // error.status contains the exit code from the child process
+    if (error.status !== null && error.status !== undefined) {
+      process.exitCode = error.status;
+    } else {
+      // Signal death or spawn failure
+      process.stderr.write(
+        "Failed to execute unimatrix: " + error.message + "\n"
+      );
+      process.exitCode = 1;
+    }
+  }
+}
+
+main();

package/lib/init.js

@@ -0,0 +1,267 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const { resolveBinary } = require("./resolve-binary.js");
+const { mergeSettings } = require("./merge-settings.js");
+
+const HOOK_EVENTS = [
+  "SessionStart",
+  "Stop",
+  "UserPromptSubmit",
+  "PreToolUse",
+  "PostToolUse",
+  "SubagentStart",
+  "SubagentStop",
+];
+
+/**
+ * Detect project root by walking up from startDir to find .git directory.
+ * Mirrors the Rust detect_project_root algorithm (ADR-003).
+ *
+ * @param {string} startDir - Directory to start searching from.
+ * @returns {string} Absolute path to the project root.
+ */
+function detectProjectRoot(startDir) {
+  let current = path.resolve(startDir);
+  for (;;) {
+    if (fs.existsSync(path.join(current, ".git"))) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      throw new Error(
+        "Could not find project root (.git directory).\n" +
+          "Run this command from within a git repository."
+      );
+    }
+    current = parent;
+  }
+}
+
+/**
+ * Write or merge .mcp.json with the unimatrix server entry.
+ * Preserves existing servers. Malformed JSON causes an error (ADR-004).
+ *
+ * @param {string} projectRoot - Absolute path to project root.
+ * @param {string} binaryPath - Absolute path to the unimatrix binary.
+ * @param {boolean} dryRun - If true, do not write the file.
+ * @returns {string[]} Actions taken.
+ */
+function writeMcpJson(projectRoot, binaryPath, dryRun) {
+  const mcpPath = path.join(projectRoot, ".mcp.json");
+  const actions = [];
+  let existing = {};
+
+  if (fs.existsSync(mcpPath)) {
+    try {
+      existing = JSON.parse(fs.readFileSync(mcpPath, "utf8"));
+    } catch (parseError) {
+      throw new Error(
+        "Malformed .mcp.json at " +
+          mcpPath +
+          ": " +
+          parseError.message +
+          "\nFix the JSON syntax and re-run 'npx unimatrix init'."
+      );
+    }
+    actions.push("Updated .mcp.json (preserved existing servers)");
+  } else {
+    actions.push("Created .mcp.json");
+  }
+
+  if (!existing.mcpServers) {
+    existing.mcpServers = {};
+  }
+
+  existing.mcpServers.unimatrix = {
+    command: binaryPath,
+    args: [],
+    env: {},
+  };
+
+  if (!dryRun) {
+    fs.writeFileSync(
+      mcpPath,
+      JSON.stringify(existing, null, 2) + "\n",
+      "utf8"
+    );
+  } else {
+    actions[actions.length - 1] = "[dry-run] " + actions[actions.length - 1];
+  }
+
+  return actions;
+}
+
+/**
+ * Copy bundled skill files from the package's skills/ directory
+ * into the project's .claude/skills/ directory. Overwrites existing
+ * unimatrix skills, preserves non-unimatrix skills.
+ *
+ * @param {string} projectRoot - Absolute path to project root.
+ * @param {boolean} dryRun - If true, do not copy files.
+ * @returns {string[]} Actions taken.
+ */
+function copySkills(projectRoot, dryRun) {
+  const actions = [];
+  const targetDir = path.join(projectRoot, ".claude", "skills");
+  const sourceDir = path.join(__dirname, "..", "skills");
+
+  if (!fs.existsSync(sourceDir)) {
+    actions.push("No bundled skills found (skipped)");
+    return actions;
+  }
+
+  if (!dryRun) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+
+  const skillDirs = fs
+    .readdirSync(sourceDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name);
+
+  for (const skillDir of skillDirs) {
+    const src = path.join(sourceDir, skillDir);
+    const dst = path.join(targetDir, skillDir);
+
+    if (!dryRun) {
+      fs.mkdirSync(dst, { recursive: true });
+
+      const files = fs.readdirSync(src);
+      for (const file of files) {
+        if (file.includes("..")) {
+          throw new Error(
+            "Path traversal detected in skill file: " + file
+          );
+        }
+
+        const srcFile = path.join(src, file);
+        const dstFile = path.join(dst, file);
+
+        // Only copy files, not subdirectories
+        const stat = fs.statSync(srcFile);
+        if (stat.isFile()) {
+          fs.copyFileSync(srcFile, dstFile);
+        }
+      }
+
+      actions.push("Copied skill: " + skillDir);
+    } else {
+      actions.push("[dry-run] Would copy skill: " + skillDir);
+    }
+  }
+
+  return actions;
+}
+
+/**
+ * Print summary of all actions taken during init.
+ *
+ * @param {string[]} actions - List of action descriptions.
+ * @param {boolean} dryRun - Whether this was a dry run.
+ */
+function printSummary(actions, dryRun) {
+  if (dryRun) {
+    console.log("\n--- Dry Run Summary ---\n");
+  } else {
+    console.log("\n--- Unimatrix Init Complete ---\n");
+  }
+
+  for (const action of actions) {
+    console.log("  " + action);
+  }
+
+  console.log("");
+  if (!dryRun) {
+    console.log("Next step: start a Claude Code session and run /unimatrix-init");
+  }
+}
+
+/**
+ * Deterministic, non-interactive, idempotent project wiring.
+ * Configures MCP server, hooks, skills, and pre-creates the database.
+ * Implemented in JavaScript per ADR-003.
+ *
+ * @param {object} options
+ * @param {boolean} [options.dryRun=false] - Print actions without modifying files.
+ * @param {string} [options.projectDir] - Override project root (skip .git walk).
+ */
+async function init(options) {
+  const dryRun = (options && options.dryRun) || false;
+  const actions = [];
+
+  // Step 1: Resolve project root
+  let projectRoot;
+  if (options && options.projectDir) {
+    projectRoot = path.resolve(options.projectDir);
+  } else {
+    projectRoot = detectProjectRoot(process.cwd());
+  }
+  actions.push("Project root: " + projectRoot);
+
+  // Step 2: Resolve binary path
+  const binaryPath = resolveBinary();
+  actions.push("Binary: " + binaryPath);
+
+  // Step 3: Write/merge .mcp.json
+  const mcpActions = writeMcpJson(projectRoot, binaryPath, dryRun);
+  actions.push(...mcpActions);
+
+  // Step 4: Merge hooks into .claude/settings.json
+  const settingsPath = path.join(projectRoot, ".claude", "settings.json");
+  const settingsResult = mergeSettings(settingsPath, binaryPath, { dryRun });
+  actions.push(...settingsResult.actions);
+
+  // Step 5: Copy skill files
+  const skillActions = copySkills(projectRoot, dryRun);
+  actions.push(...skillActions);
+
+  // Step 6: Pre-create database (exec Rust binary)
+  if (!dryRun) {
+    try {
+      execFileSync(binaryPath, ["version", "--project-dir", projectRoot], {
+        stdio: "pipe",
+      });
+      actions.push("Database: pre-created at ~/.unimatrix/{hash}/");
+    } catch (error) {
+      const stderr =
+        error.stderr ? error.stderr.toString() : error.message;
+      throw new Error("Database creation failed: " + stderr);
+    }
+  } else {
+    actions.push(
+      "[dry-run] Would pre-create database via: unimatrix version --project-dir " +
+        projectRoot
+    );
+  }
+
+  // Step 7: Validate binary
+  if (!dryRun) {
+    try {
+      const versionOutput = execFileSync(binaryPath, ["version"], {
+        stdio: "pipe",
+        encoding: "utf8",
+      }).trim();
+      actions.push("Validation: " + versionOutput);
+    } catch (error) {
+      const stderr =
+        error.stderr ? error.stderr.toString() : error.message;
+      throw new Error("Binary validation failed: " + stderr);
+    }
+  } else {
+    actions.push("[dry-run] Would validate binary via: unimatrix version");
+  }
+
+  // Step 8: Print summary
+  printSummary(actions, dryRun);
+}
+
+module.exports = {
+  init,
+  detectProjectRoot,
+  writeMcpJson,
+  copySkills,
+  printSummary,
+};

package/lib/merge-settings.js

@@ -0,0 +1,188 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Regex patterns to identify Unimatrix-owned hook entries (ADR-004).
+ * Matches both current "unimatrix" and pre-rename "unimatrix-server" commands,
+ * whether bare names or absolute paths.
+ */
+const UNIMATRIX_PATTERNS = [
+  /^unimatrix\s+hook\s/,
+  /^unimatrix-server\s+hook\s/,
+  /\/unimatrix\s+hook\s/,
+  /\/unimatrix-server\s+hook\s/,
+];
+
+const HOOK_EVENTS = [
+  "SessionStart",
+  "Stop",
+  "UserPromptSubmit",
+  "PreToolUse",
+  "PostToolUse",
+  "SubagentStart",
+  "SubagentStop",
+];
+
+/** Matcher per event: "" for session-level, "*" for tool/agent-level */
+const EVENT_MATCHERS = {
+  SessionStart: "",
+  Stop: "",
+  UserPromptSubmit: "",
+  PreToolUse: "*",
+  PostToolUse: "*",
+  SubagentStart: "*",
+  SubagentStop: "*",
+};
+
+/**
+ * Returns true if a hook entry is owned by Unimatrix, identified by
+ * prefix-matching the command field against known patterns.
+ *
+ * @param {object} hookEntry - A hook entry object with a `command` field.
+ * @returns {boolean}
+ */
+function isUnimatrixHook(hookEntry) {
+  if (!hookEntry || !hookEntry.command || typeof hookEntry.command !== "string") {
+    return false;
+  }
+  return UNIMATRIX_PATTERNS.some((pattern) => pattern.test(hookEntry.command));
+}
+
+/**
+ * Merge Unimatrix hook configuration into .claude/settings.json.
+ *
+ * Implements ADR-004 prefix-match identification. Preserves all non-unimatrix
+ * hooks, permissions, and other top-level keys. Idempotent: running twice
+ * produces the same result.
+ *
+ * @param {string} filePath - Path to .claude/settings.json
+ * @param {string} binaryPath - Absolute path to the unimatrix binary
+ * @param {object} options - { dryRun: boolean }
+ * @returns {{ actions: string[], content: object }}
+ */
+function mergeSettings(filePath, binaryPath, options) {
+  const dryRun = (options && options.dryRun) || false;
+  const actions = [];
+  let content = {};
+
+  // Step 1: Read existing file
+  if (fs.existsSync(filePath)) {
+    const raw = fs.readFileSync(filePath, "utf8").trim();
+
+    if (raw === "") {
+      content = {};
+      actions.push("settings.json was empty, initializing");
+    } else {
+      try {
+        content = JSON.parse(raw);
+      } catch (parseError) {
+        throw new Error(
+          "Malformed .claude/settings.json: " +
+            parseError.message +
+            "\nFix the JSON syntax manually and re-run 'npx unimatrix init'." +
+            "\nFile: " +
+            filePath
+        );
+      }
+    }
+  } else {
+    actions.push("Created .claude/settings.json");
+  }
+
+  // Step 2: Ensure hooks key exists
+  if (!content.hooks) {
+    content.hooks = {};
+  }
+
+  // Validate hooks is an object (not array, not primitive)
+  if (typeof content.hooks !== "object" || Array.isArray(content.hooks)) {
+    throw new Error(
+      ".claude/settings.json 'hooks' key is not an object." +
+        '\nExpected: { "hooks": { "EventName": [...] } }' +
+        "\nFile: " +
+        filePath
+    );
+  }
+
+  // Step 3: For each hook event, merge the unimatrix entry
+  for (const event of HOOK_EVENTS) {
+    const hookCommand = binaryPath + " hook " + event;
+    const matcher = EVENT_MATCHERS[event];
+
+    const newHookEntry = {
+      type: "command",
+      command: hookCommand,
+    };
+
+    // The settings format is: hooks.EventName = [ { matcher, hooks: [...] } ]
+    if (!content.hooks[event]) {
+      content.hooks[event] = [];
+    }
+
+    const eventArray = content.hooks[event];
+    let merged = false;
+
+    for (const matcherGroup of eventArray) {
+      if (matcherGroup.matcher === matcher) {
+        // Found a matcher group for our matcher value
+        if (!matcherGroup.hooks) {
+          matcherGroup.hooks = [];
+        }
+
+        // Look for existing unimatrix hook to update
+        let existingIndex = -1;
+        const duplicateIndices = [];
+        for (let i = 0; i < matcherGroup.hooks.length; i++) {
+          if (isUnimatrixHook(matcherGroup.hooks[i])) {
+            if (existingIndex === -1) {
+              existingIndex = i;
+            } else {
+              duplicateIndices.push(i);
+            }
+          }
+        }
+
+        // Remove duplicates in reverse order (dedup on re-run, per ADR-004)
+        for (let j = duplicateIndices.length - 1; j >= 0; j--) {
+          matcherGroup.hooks.splice(duplicateIndices[j], 1);
+          actions.push("Removed duplicate unimatrix hook for " + event);
+        }
+
+        if (existingIndex >= 0) {
+          matcherGroup.hooks[existingIndex] = newHookEntry;
+          actions.push("Updated hook: " + event);
+        } else {
+          matcherGroup.hooks.push(newHookEntry);
+          actions.push("Added hook: " + event);
+        }
+
+        merged = true;
+        break;
+      }
+    }
+
+    if (!merged) {
+      // No matcher group found for our matcher value; create one
+      eventArray.push({
+        matcher: matcher,
+        hooks: [newHookEntry],
+      });
+      actions.push("Added hook: " + event + " (new matcher group)");
+    }
+  }
+
+  // Step 4: Write file (or prefix actions with [dry-run])
+  if (!dryRun) {
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(content, null, 2) + "\n", "utf8");
+  }
+
+  const finalActions = dryRun ? actions.map((a) => "[dry-run] " + a) : actions;
+
+  return { actions: finalActions, content };
+}
+
+module.exports = { mergeSettings, isUnimatrixHook, HOOK_EVENTS, EVENT_MATCHERS, UNIMATRIX_PATTERNS };

package/lib/resolve-binary.js

@@ -0,0 +1,69 @@
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const PLATFORMS = {
+  "linux-x64": "@dug-21/unimatrix-linux-x64",
+  "linux-arm64": "@dug-21/unimatrix-linux-arm64",
+};
+
+/**
+ * Resolve the absolute path to the platform-specific Unimatrix binary.
+ *
+ * Resolution order:
+ * 1. UNIMATRIX_BINARY env var (development/testing override)
+ * 2. Platform package via require.resolve (optionalDependencies)
+ *
+ * @returns {string} Absolute real path to the binary
+ * @throws {Error} If binary cannot be found or env override points to missing file
+ */
+function resolveBinary() {
+  // 1. Check environment variable override (development/testing)
+  const envPath = process.env.UNIMATRIX_BINARY;
+  if (envPath) {
+    if (!fs.existsSync(envPath)) {
+      throw new Error(
+        "UNIMATRIX_BINARY points to non-existent file: " + envPath
+      );
+    }
+    return fs.realpathSync(envPath);
+  }
+
+  // 2. Determine current platform key
+  const platformKey = os.platform() + "-" + os.arch();
+
+  // 3. Look up package name for this platform
+  const packageName = PLATFORMS[platformKey];
+  if (!packageName) {
+    throw new Error(
+      "Unsupported platform: " +
+        platformKey +
+        "\n" +
+        "Supported platforms: " +
+        Object.keys(PLATFORMS).join(", ") +
+        "\n" +
+        "Set UNIMATRIX_BINARY environment variable to use a custom binary path."
+    );
+  }
+
+  // 4. Resolve binary path via require.resolve
+  let binaryPath;
+  try {
+    binaryPath = require.resolve(packageName + "/bin/unimatrix");
+  } catch (_err) {
+    throw new Error(
+      "Could not find platform binary package '" +
+        packageName +
+        "'.\n" +
+        "Run 'npm install @dug-21/unimatrix' to install.\n" +
+        "If using pnpm or yarn, set UNIMATRIX_BINARY to the binary path."
+    );
+  }
+
+  // 5. Resolve through symlinks to get the real absolute path (ADR-001)
+  return fs.realpathSync(binaryPath);
+}
+
+module.exports = { resolveBinary, PLATFORMS };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@dug-21/unimatrix",
+  "version": "0.5.5",
+  "description": "Unimatrix knowledge engine for multi-agent development",
+  "bin": {
+    "unimatrix": "bin/unimatrix.js"
+  },
+  "scripts": {
+    "postinstall": "node postinstall.js"
+  },
+  "optionalDependencies": {
+    "@dug-21/unimatrix-linux-x64": "0.5.5",
+    "@dug-21/unimatrix-linux-arm64": "0.5.5"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/",
+    "postinstall.js"
+  ],
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anthropics/unimatrix"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/postinstall.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+"use strict";
+
+function main() {
+  try {
+    var resolveBinary;
+    try {
+      resolveBinary = require("./lib/resolve-binary").resolveBinary;
+    } catch (_err) {
+      console.warn(
+        "[unimatrix] postinstall: could not load resolve-binary module, skipping model download"
+      );
+      process.exit(0);
+    }
+
+    var binaryPath;
+    try {
+      binaryPath = resolveBinary();
+    } catch (error) {
+      console.warn(
+        "[unimatrix] postinstall: platform binary not available (" +
+          error.message +
+          "), skipping model download"
+      );
+      process.exit(0);
+    }
+
+    var execFileSync = require("child_process").execFileSync;
+    var path = require("path");
+    var binDir = path.dirname(binaryPath);
+    var ldPath = process.env.LD_LIBRARY_PATH;
+    var env = Object.assign({}, process.env, {
+      LD_LIBRARY_PATH: ldPath ? binDir + ":" + ldPath : binDir,
+    });
+    try {
+      execFileSync(binaryPath, ["model-download"], {
+        stdio: ["ignore", "inherit", "inherit"],
+        timeout: 300000,
+        env: env,
+      });
+      console.log("[unimatrix] postinstall: ONNX model ready");
+    } catch (execError) {
+      console.warn(
+        "[unimatrix] postinstall: model download failed, will retry on first server start"
+      );
+      if (execError.stderr) {
+        console.warn(
+          "[unimatrix]   " + execError.stderr.toString().trim()
+        );
+      }
+    }
+  } catch (outerError) {
+    console.warn(
+      "[unimatrix] postinstall: unexpected error: " + outerError.message
+    );
+  }
+
+  process.exit(0);
+}
+
+main();