@xcraftmind/mastermind 0.22.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mastermind contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# @xcraftmind/mastermind
+
+Mastermind workflow CLI + mmcg codegraph for AI coding agents — verify-spec / audit-spec gates, MCP server, multi-language tree-sitter indexer (Python, TypeScript, JavaScript, Rust, C#, Go, Java, PHP, C/C++).
+
+Prebuilt native binaries via optional platform packages — **no Rust toolchain required**.
+
+## Install
+
+### One-shot (no install)
+
+```sh
+npx -y @xcraftmind/mastermind doctor
+npx -y @xcraftmind/mastermind init --profile typescript-api
+npx -y @xcraftmind/mastermind run-task .mastermind/tasks/042-feature.md
+```
+
+`npx` is great for these one-shot commands. **Avoid it for the MCP server**, though: an MCP config that runs `npx ... serve` pays an npm-cache/network resolution cost on every Claude Code launch and is less deterministic than a real install. For `setup claude`, prefer **global** or **project-local** (below). If you do register via npx, `setup claude` pins the version (`npx -y @xcraftmind/mastermind@<ver> serve`) so at least the version is stable — but it's an escape hatch, not the recommended path.
+
+### Global (recommended for most users)
+
+```sh
+npm install -g @xcraftmind/mastermind
+mastermind setup claude --write-mcp       # register mmcg as an MCP server
+mastermind doctor                          # verify the environment
+```
+
+`setup claude` writes `~/.claude/.mcp.json` with `command: "mastermind"` so Claude Code launches the wrapper from PATH.
+
+### Project-local
+
+```sh
+npm install -D @xcraftmind/mastermind
+npx mastermind setup claude --project . --write-mcp
+```
+
+`setup claude --project .` writes `./.mcp.json` with `command: "./node_modules/.bin/mastermind"` so the project gets a reproducible, version-pinned MCP server.
+
+### Build from source (contributors / unsupported platforms)
+
+```sh
+cargo install mmcg
+```
+
+Requires Rust 1.75+. The cargo-installed binary is `mmcg`, not `mastermind` — same code, same subcommands, only the wrapper name differs.
+
+## Supported platforms
+
+Prebuilt binaries ship for:
+
+| Platform | Architecture |
+|---|---|
+| macOS (Apple Silicon) | aarch64 |
+| macOS (Intel) | x86_64 |
+| Linux glibc | x86_64, aarch64 |
+| Linux musl (Alpine) | x86_64, aarch64 |
+| Windows | x86_64 |
+
+Other targets fall back to `cargo install mmcg`.
+
+## What's in the box
+
+- `mastermind` — public CLI command (alias for `mmcg` with install-mode hints)
+- `mmcg` — compatibility command (same binary, same subcommands as cargo-installed `mmcg`)
+
+Both commands resolve to the same native binary. Use whichever your team has documented.
+
+### Top-level subcommands
+
+```sh
+mastermind init --profile typescript-api    # scaffold .mastermind/ with stack-specific CONTEXT.md
+mastermind index .                          # build/refresh the codegraph index
+mastermind watch                            # long-running watcher (re-indexes on file changes)
+mastermind doctor                           # environment health check
+mastermind serve                            # MCP stdio server
+mastermind setup claude --write-mcp         # register with Claude Code's MCP layer
+mastermind verify-spec <path>               # pre-execution mechanical gate on a task spec
+mastermind audit-spec <path> --since main   # post-execution audit vs git baseline
+mastermind run-task <path>                  # two-phase orchestrator: verify → executor → audit
+mastermind query callers <symbol>           # one-shot CLI query (use MCP for agents)
+```
+
+See `mastermind <subcommand> --help` for full options.
+
+## Architecture
+
+The npm package uses the prebuilt-platform-package pattern (same as `esbuild`, `swc`, `lefthook`, `turbo`). The root `@xcraftmind/mastermind` package contains only JavaScript wrappers and lists all seven platform packages as `optionalDependencies`. npm installs only the package matching the host's `os` + `cpu` (+ `libc` for Linux); the others are skipped.
+
+```
+@xcraftmind/mastermind                    # JS wrappers + optionalDependencies
+├── @xcraftmind/mmcg-darwin-arm64         # one of these installs, the rest skip
+├── @xcraftmind/mmcg-darwin-x64
+├── @xcraftmind/mmcg-linux-x64-gnu
+├── @xcraftmind/mmcg-linux-arm64-gnu
+├── @xcraftmind/mmcg-linux-x64-musl
+├── @xcraftmind/mmcg-linux-arm64-musl
+└── @xcraftmind/mmcg-win32-x64-msvc
+```
+
+No `postinstall` script. No network calls beyond the npm registry itself.
+
+## Links
+
+- Source: [github.com/xcrft/mastermind](https://github.com/xcrft/mastermind)
+- mmcg Rust crate: [crates.io/crates/mmcg](https://crates.io/crates/mmcg)
+- MCP protocol: [modelcontextprotocol.io](https://modelcontextprotocol.io)

package/bin/mastermind.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// `mastermind` — public command. Same native binary as `mmcg`, but injects
+// install-mode hints into the environment so `setup claude` writes the right
+// MCP `command` form for each installation method (npx vs global npm vs
+// project-local npm vs cargo).
+
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import path from "node:path";
+import process from "node:process";
+
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+
+function detectLibc() {
+  if (process.platform !== "linux") return null;
+  const report = process.report?.getReport?.();
+  if (report?.header?.glibcVersionRuntime) return "gnu";
+  return "musl";
+}
+
+function packageName() {
+  const platform = process.platform;
+  const arch = process.arch;
+  if (platform === "darwin" && arch === "arm64") return "@xcraftmind/mmcg-darwin-arm64";
+  if (platform === "darwin" && arch === "x64") return "@xcraftmind/mmcg-darwin-x64";
+  if (platform === "win32" && arch === "x64") return "@xcraftmind/mmcg-win32-x64-msvc";
+  if (platform === "linux") {
+    const libc = detectLibc();
+    if (arch === "x64") return `@xcraftmind/mmcg-linux-x64-${libc}`;
+    if (arch === "arm64") return `@xcraftmind/mmcg-linux-arm64-${libc}`;
+  }
+  throw new Error(`unsupported platform: ${platform}-${arch}`);
+}
+
+function resolveBinary() {
+  const pkgName = packageName();
+  const exe = process.platform === "win32" ? "mmcg.exe" : "mmcg";
+  try {
+    return require.resolve(`${pkgName}/bin/${exe}`);
+  } catch (err) {
+    const lines = [
+      `Could not locate the native mmcg binary for ${process.platform}-${process.arch}.`,
+      "",
+      `Platform package \`${pkgName}\` is not installed. Fix:`,
+      "  npm install --include=optional @xcraftmind/mastermind   # force optional install",
+      "  cargo install mmcg                                  # build from source (needs Rust)",
+      "",
+      `(underlying: ${String(err?.message ?? err)})`,
+    ];
+    console.error(lines.join("\n"));
+    process.exit(1);
+  }
+}
+
+/**
+ * Detect how this wrapper was invoked so `setup claude` can write a stable
+ * MCP `command` form per install mode.
+ *
+ *   npx    — process.argv[1] lives under an npx cache (`/_npx/` or `\_npx\`)
+ *   project — wrapper lives under `<cwd>/node_modules` (any depth)
+ *   global  — wrapper lives under a known npm global prefix
+ *   cargo   — never reached here (cargo users invoke `mmcg` directly, no JS)
+ *
+ * Best-effort: if none match cleanly, returns "unknown" — the Rust side
+ * falls back to `command: mastermind` which works for any PATH-installed case.
+ */
+function detectInstallMode() {
+  const self = process.argv[1] || "";
+  // npx caches keep packages under `_npx` directories on every platform.
+  if (self.includes(`${path.sep}_npx${path.sep}`) || self.includes("/_npx/")) {
+    return "npx";
+  }
+  const cwd = process.cwd();
+  const projectNodeModules = path.join(cwd, "node_modules") + path.sep;
+  if (self.startsWith(projectNodeModules)) {
+    return "project";
+  }
+  // Heuristic for global install: bin path lands under a directory whose
+  // name suggests global npm (e.g. /usr/local/lib/node_modules, ~/.npm-global,
+  // C:\\Program Files\\nodejs\\node_modules). Any node_modules path that
+  // isn't under cwd qualifies.
+  if (self.includes(`${path.sep}node_modules${path.sep}`)) {
+    return "global";
+  }
+  return "unknown";
+}
+
+const bin = resolveBinary();
+const installMode = detectInstallMode();
+
+// Inject hints for `setup claude` and any other subcommand that benefits from
+// knowing how it was invoked. The Rust side reads these env vars; absence is
+// treated as "cargo-style install" and the existing behavior is preserved.
+const env = {
+  ...process.env,
+  MASTERMIND_INSTALL_MODE: installMode,
+  MASTERMIND_VERSION: pkg.version,
+  MASTERMIND_PACKAGE: pkg.name,
+};
+
+const child = spawn(bin, process.argv.slice(2), {
+  stdio: "inherit",
+  env,
+});
+
+child.on("error", (err) => {
+  console.error(`failed to launch native binary at ${bin}: ${err.message}`);
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code ?? 1);
+  }
+});

package/bin/mmcg.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+// `mmcg` — compatibility command. Resolves the platform-specific binary from
+// the optional dependency installed by npm and execs it with argv pass-through.
+//
+// Most users should run `mastermind` (the public command). This file exists so
+// scripts written against the cargo-installed `mmcg` keep working after npm
+// adoption — same binary, same subcommands, same exit codes.
+
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import process from "node:process";
+
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+
+/**
+ * Detect glibc vs musl on Linux. `process.report.getReport()` includes
+ * `glibcVersionRuntime` when the host libc is glibc; absent on musl/Alpine.
+ * Node 18+ ships `process.report` enabled by default.
+ *
+ * Returns "gnu" on glibc hosts, "musl" otherwise. Conservative fallback to
+ * musl when detection is ambiguous (better to fail at require.resolve than
+ * silently grab the wrong binary).
+ */
+function detectLibc() {
+  if (process.platform !== "linux") return null;
+  const report = process.report?.getReport?.();
+  if (report?.header?.glibcVersionRuntime) return "gnu";
+  return "musl";
+}
+
+/** Map (platform, arch[, libc]) → the npm scoped package name. */
+function packageName() {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  if (platform === "darwin" && arch === "arm64") return "@xcraftmind/mmcg-darwin-arm64";
+  if (platform === "darwin" && arch === "x64") return "@xcraftmind/mmcg-darwin-x64";
+  if (platform === "win32" && arch === "x64") return "@xcraftmind/mmcg-win32-x64-msvc";
+
+  if (platform === "linux") {
+    const libc = detectLibc();
+    if (arch === "x64") return `@xcraftmind/mmcg-linux-x64-${libc}`;
+    if (arch === "arm64") return `@xcraftmind/mmcg-linux-arm64-${libc}`;
+  }
+
+  throw new Error(`unsupported platform: ${platform}-${arch}`);
+}
+
+function resolveBinary() {
+  const pkgName = packageName();
+  const exe = process.platform === "win32" ? "mmcg.exe" : "mmcg";
+  try {
+    return require.resolve(`${pkgName}/bin/${exe}`);
+  } catch (err) {
+    const lines = [
+      `Could not locate the native mmcg binary for ${process.platform}-${process.arch}.`,
+      "",
+      "The platform-specific package was not installed. This usually means:",
+      `  - npm skipped \`${pkgName}\` because optional-dependency install failed`,
+      "  - your platform is not in the supported set (see README)",
+      "",
+      "Fixes:",
+      "  - npm install --include=optional @xcraftmind/mastermind     # force optional install",
+      "  - cargo install mmcg                                   # build from source (needs Rust)",
+      "",
+      `(underlying error: ${String(err?.message ?? err)})`,
+    ];
+    console.error(lines.join("\n"));
+    process.exit(1);
+  }
+}
+
+const bin = resolveBinary();
+
+// `spawn` (not `spawnSync`) so signals (SIGINT / SIGTERM) propagate to the
+// child correctly — important for `mmcg watch` and `mmcg serve` which are
+// long-running.
+const child = spawn(bin, process.argv.slice(2), {
+  stdio: "inherit",
+  // Propagate environment unchanged. `mastermind.js` injects extra env vars
+  // before spawning this script when needed (install-mode detection).
+});
+
+child.on("error", (err) => {
+  console.error(`failed to launch mmcg binary at ${bin}: ${err.message}`);
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    // Re-raise the signal so the parent shell sees the canonical exit code.
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code ?? 1);
+  }
+});
+
+// Re-export the version for diagnostics: `mmcg --version` is the binary's
+// version; this is the wrapper / package version. Equal when shipped together.
+export const wrapperVersion = pkg.version;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@xcraftmind/mastermind",
+  "version": "0.22.0",
+  "description": "Mastermind workflow CLI + mmcg codegraph for AI coding agents — verify-spec / audit-spec gates, MCP server, multi-language tree-sitter indexer (Python, TypeScript, JavaScript, Rust, C#, Go, Java, PHP, C/C++). Prebuilt native binaries via optional platform packages — no Rust toolchain required.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xcrft/mastermind.git"
+  },
+  "homepage": "https://github.com/xcrft/mastermind",
+  "bugs": {
+    "url": "https://github.com/xcrft/mastermind/issues"
+  },
+  "bin": {
+    "mastermind": "./bin/mastermind.js",
+    "mmcg": "./bin/mmcg.js"
+  },
+  "files": [
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "codegraph",
+    "ai",
+    "claude",
+    "tree-sitter",
+    "indexer",
+    "rust",
+    "cli",
+    "mastermind"
+  ],
+  "optionalDependencies": {
+    "@xcraftmind/mmcg-darwin-arm64": "0.22.0",
+    "@xcraftmind/mmcg-darwin-x64": "0.22.0",
+    "@xcraftmind/mmcg-linux-x64-gnu": "0.22.0",
+    "@xcraftmind/mmcg-linux-arm64-gnu": "0.22.0",
+    "@xcraftmind/mmcg-linux-x64-musl": "0.22.0",
+    "@xcraftmind/mmcg-linux-arm64-musl": "0.22.0",
+    "@xcraftmind/mmcg-win32-x64-msvc": "0.22.0"
+  }
+}