nomarmy 0.1.0-alpha.10 → 0.1.0-alpha.11

package/bin/nomarmy.mjs

@@ -18,7 +18,7 @@ import { buildConfigProposal } from "../lib/propose.mjs";
 import { detectHardware } from "../lib/hardware.mjs";
 import { readGGUFMetadata, resolveModelPath, totalSplitBytes } from "../lib/gguf.mjs";
 import { recommend, customRecommendation, evaluateConfig, bytesPerKvElementForCacheTypes, MIN_CONTEXT_PER_NOM } from "../lib/sizing.mjs";
-import { connectClaude, connectCodex, connectCursor, cursorAlreadyConnected, deriveWorkerModelEnv, defaultInstallDir } from "../lib/connect.mjs";
+import { connectClaude, connectCodex, connectCursor, cursorAlreadyConnected, deriveWorkerModelEnv, defaultInstallDir, installMcpCopy, SCOPES, claudeUserScoped, portableServerLaunch } from "../lib/connect.mjs";
 import { compareVersions, readPackageVersion, readInstallVersions, copyIsStale } from "../lib/install-freshness.mjs";
 import { ID_RE, AUTH_ENV_NAME_RE, OPENCLAW_PROVIDER_ID_RE, openclawProviderId, isNativeProviderType } from "../lib/dispatch-schema.mjs";
 import { loadAgents, readAgentsFile, writeAgentsFile, agentsConfigPath, apiAgentAsPoolEntry, describeAgent as describeAgentLabel, agentRunsToolsOnHost, agentProviderId, AGENT_KINDS, API_PROVIDER_TYPES, RESERVED_AGENT_NAMES, BUILTIN_LOCAL_AGENT } from "../lib/agents.mjs";
@@ -40,10 +40,10 @@ import { SUBSCRIPTION_VENDORS, parseOpenclawVersion, versionAtLeast, parseCatalo
 // "already connected, so resync" detection if it has no CLI to probe.
 const KNOWN_TARGETS = ["claude", "codex", "cursor"];
 
-function connectTarget(target, { nomarmyRoot, run }) {
-  if (target === "claude") return connectClaude({ nomarmyRoot, run });
-  if (target === "codex") return connectCodex({ nomarmyRoot, run });
-  if (target === "cursor") return connectCursor({ nomarmyRoot, run });
+function connectTarget(target, { nomarmyRoot, run, scope = "user", projectDir = null }) {
+  if (target === "claude") return connectClaude({ nomarmyRoot, run, scope, projectDir });
+  if (target === "codex") return connectCodex({ nomarmyRoot, run, scope });
+  if (target === "cursor") return connectCursor({ nomarmyRoot, run, scope, projectDir });
   throw new Error(`unknown connect target: ${target}`);
 }
 
@@ -214,10 +214,16 @@ Usage: nomarmy <command> [options]
   statusline      the one-line summary Claude Code's status line shows
                   (installed by \`nomarmy connect claude\` when no status
                   line is set); reads the session JSON on stdin
-  connect [claude] [codex] [cursor]
+  connect [claude] [codex] [cursor] [--scope user|local|project]
                   (Re-)register the MCP server with one or more coordinators.
                   With no target and not --json, prompts an interactive
-                  multi-select instead.
+                  multi-select instead. --scope user (default) registers it
+                  for every project; local for this repository, only you;
+                  project for this repository, committed for the team
+                  (.mcp.json or .cursor/mcp.json, running \`nomarmy mcp\`).
+                  Codex has only the user scope.
+  mcp             Start nomArmy's MCP server on stdio with this machine's
+                  settings. What a --scope project registration runs.
   sandbox         The Podman VM every sandbox shares (macOS, Windows): its
                   memory, disk and images. --memory <GiB> resizes it (stops,
                   sets, restarts; refused while jobs run); --prune removes
@@ -1709,6 +1715,13 @@ async function cmdUpdate() {
 // this process loaded. Returns the targets reconnected.
 function reconnectCoordinators() {
   const targets = connectedTargets();
+  // Per-repo registrations run the installed copy (or `nomarmy mcp`), so a
+  // refreshed copy is all they need; re-registering them at user scope would
+  // add nomArmy to every project.
+  if (!targets.length) {
+    execFileSync(process.execPath, [path.join(nomarmyRoot, "bin", "nomarmy.mjs"), "connect", "--copy-only", ...(json ? ["--json"] : [])], { stdio: json ? "ignore" : "inherit" });
+    return [];
+  }
   if (targets.length) {
     if (!json) console.log(`\nReconnecting ${targets.join(", ")}...`);
     execFileSync(process.execPath, [path.join(nomarmyRoot, "bin", "nomarmy.mjs"), "connect", ...targets, ...(json ? ["--json"] : [])], { stdio: json ? "ignore" : "inherit" });
@@ -1717,7 +1730,7 @@ function reconnectCoordinators() {
 }
 
 function connectedTargets() {
-  return [commandExists("claude") && "claude", commandExists("codex") && "codex", cursorAlreadyConnected() && "cursor"].filter(Boolean);
+  return [commandExists("claude") && claudeUserScoped() && "claude", commandExists("codex") && "codex", cursorAlreadyConnected() && "cursor"].filter(Boolean);
 }
 
 async function updateFromNpm() {
@@ -1788,7 +1801,20 @@ async function cmdConnect() {
   // scan the whole argv), and `nomarmy connect --json claude` once broke
   // that promise by reading argv[1] directly -- --json landed in target's
   // slot instead. Multiple bare tokens are now allowed too, for multi-select.
-  const requested = argv.slice(1).filter((a) => !a.startsWith("--"));
+  const flagValues = new Set(["--scope", "--repo"].map((name) => argv.indexOf(name)).filter((i) => i >= 0).map((i) => i + 1));
+  const requested = argv.slice(1).filter((a, i) => !a.startsWith("--") && !flagValues.has(i + 1));
+  const scope = value("scope", "user");
+  if (!SCOPES.includes(scope)) throw new Error(`--scope must be one of ${SCOPES.join(", ")}, got "${scope}".`);
+  let projectDir = null;
+  if (scope !== "user") {
+    try { projectDir = execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: repoDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); }
+    catch { throw new Error(`--scope ${scope} registers nomArmy for one repository, and ${repoDir} isn't inside a git repository. Run it from the repository (or pass --repo <dir>).`); }
+  }
+  if (flag("copy-only")) {
+    // `nomarmy update` with only per-repo registrations: refresh the copy they run.
+    installMcpCopy({ nomarmyRoot, installDir: defaultInstallDir(), run: (cmd, args, opts = {}) => execFileSync(cmd, args, { stdio: json ? "ignore" : "inherit", ...opts }) });
+    return json ? out({ refreshed: defaultInstallDir() }) : console.log(c.green(`✓ Refreshed the nomArmy copy in ${defaultInstallDir()}.`));
+  }
   let targets;
   if (requested.length > 0) {
     const unknown = requested.filter((t) => !KNOWN_TARGETS.includes(t));
@@ -1813,9 +1839,12 @@ async function cmdConnect() {
     }
     try {
       if (!json) console.log(c.bold(`\n🍪 Connecting nomArmy to ${target}...`));
-      const result = connectTarget(target, { nomarmyRoot, run });
+      const result = connectTarget(target, { nomarmyRoot, run, scope, projectDir });
       results.push({ target, connected: true, ...result });
-      if (!json) console.log(c.green(`✓ Registered nomarmy-local-worker with ${target}.`));
+      if (!json) console.log(c.green(`✓ Registered nomarmy-local-worker with ${target}${scope === "user" ? "." : scope === "local" ? ` for ${projectDir} only (not committed).` : ` in ${path.relative(projectDir, result.configPath ?? path.join(projectDir, ".mcp.json"))}, for everyone who clones this repository.`}`));
+      if (!json && scope === "local" && result?.excluded?.length) console.log(c.dim(`  Kept out of git (.git/info/exclude): ${result.excluded.join(", ")}`));
+      if (!json && scope === "project") console.log(c.dim(`  Commit it along with the playbook in ${path.relative(projectDir, result.commands.dir)}. Each teammate needs nomArmy installed and set up (npm install -g nomarmy@alpha, then nomarmy setup); the registration runs \`nomarmy mcp\`, which uses their own settings.`));
+      if (!json && scope !== "user" && target === "claude" && result?.userScoped) console.log(c.yellow(`  nomArmy is also registered for all your projects (user scope). To use it only where you register it per repository: claude mcp remove nomarmy-local-worker -s user`));
       if (!json && result?.commands?.installed?.length) console.log(c.green(`✓ Playbooks: ${result.commands.installed.join(", ")}`) + c.dim(` in ${result.commands.dir} (restart ${target} to pick up a new one)`));
       if (!json && result?.notifier?.status === "built") console.log(c.green("✓ Notifications: nomArmy.app, with nomArmy's icon") + c.dim(" (macOS asks once whether to allow it)"));
       if (!json && result?.notifier?.status === "failed") console.log(c.yellow(`⚠ Couldn't build nomArmy.app (${result.notifier.reason}); notifications still work, with Script Editor's icon. Xcode's command-line tools provide swiftc: xcode-select --install`));
@@ -2617,7 +2646,16 @@ async function cmdStatusline() {
   process.stdout.write(`${statusLineText({ session })}\n`);
 }
 
-const commands = { scan: cmdScan, validate: cmdValidate, sizing: cmdSizing, init: cmdInit, setup: cmdSetup, install: cmdInstall, model: cmdModel, agents: cmdAgents, army: cmdArmy, jobs: cmdJobs, statusline: cmdStatusline, health: cmdHealth, config: cmdConfig, update: cmdUpdate, connect: cmdConnect, sandbox: cmdSandbox, start: cmdStart, stop: cmdStop, uninstall: cmdUninstall, help: () => usage(0) };
+// `nomarmy mcp`: what a --scope project registration runs. Nothing goes to
+// stdout but the server's own protocol.
+function cmdMcp() {
+  const { serverPath, env } = portableServerLaunch({ nomarmyRoot });
+  const child = spawn(process.execPath, [serverPath], { stdio: "inherit", env });
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(signal, () => child.kill(signal));
+  child.on("exit", (code, signal) => { if (signal) process.kill(process.pid, signal); else process.exit(code ?? 1); });
+}
+
+const commands = { mcp: cmdMcp, scan: cmdScan, validate: cmdValidate, sizing: cmdSizing, init: cmdInit, setup: cmdSetup, install: cmdInstall, model: cmdModel, agents: cmdAgents, army: cmdArmy, jobs: cmdJobs, statusline: cmdStatusline, health: cmdHealth, config: cmdConfig, update: cmdUpdate, connect: cmdConnect, sandbox: cmdSandbox, start: cmdStart, stop: cmdStop, uninstall: cmdUninstall, help: () => usage(0) };
 // doctor command
 async function cmdDoctor() {
   // Import lazily to avoid circular dependencies

package/lib/connect.mjs

@@ -261,6 +261,50 @@ export function deriveWorkerModelEnv(nomarmyRoot) {
 
 const SERVER_NAME = "nomarmy-local-worker";
 
+/**
+ * Where a coordinator registers nomArmy. user: every project (the default).
+ * local: this repository, only you. project: this repository, committed for
+ * the team. A committed registration can't carry one machine's install path
+ * or settings, so it runs `nomarmy mcp`, which starts nomArmy with each
+ * person's own.
+ */
+export const SCOPES = Object.freeze(["user", "local", "project"]);
+export const PORTABLE_SERVER = Object.freeze({ command: "nomarmy", args: ["mcp"] });
+
+/** Keep repo-local files out of git without touching the committed .gitignore. */
+export function excludeFromGit(projectDir, relPaths, run = defaultRun) {
+  let excludeFile;
+  try { excludeFile = String(run("git", ["rev-parse", "--git-path", "info/exclude"], { cwd: projectDir, stdio: ["ignore", "pipe", "ignore"], encoding: "utf8" })).trim(); } catch { return []; }
+  if (!excludeFile) return [];
+  excludeFile = path.resolve(projectDir, excludeFile);
+  const existing = fs.existsSync(excludeFile) ? fs.readFileSync(excludeFile, "utf8") : "";
+  const lines = new Set(existing.split("\n").map((l) => l.trim()));
+  const added = relPaths.map((p) => `/${p}`).filter((p) => !lines.has(p));
+  if (added.length) {
+    fs.mkdirSync(path.dirname(excludeFile), { recursive: true });
+    fs.appendFileSync(excludeFile, `${existing && !existing.endsWith("\n") ? "\n" : ""}# nomArmy, registered for this repository only\n${added.join("\n")}\n`);
+  }
+  return added;
+}
+
+/** Undo excludeFromGit for these paths: a project registration is meant to be committed. */
+export function includeInGit(projectDir, relPaths, run = defaultRun) {
+  let excludeFile;
+  try { excludeFile = path.resolve(projectDir, String(run("git", ["rev-parse", "--git-path", "info/exclude"], { cwd: projectDir, stdio: ["ignore", "pipe", "ignore"], encoding: "utf8" })).trim()); } catch { return []; }
+  if (!fs.existsSync(excludeFile)) return [];
+  const drop = new Set(relPaths.map((p) => `/${p}`));
+  const lines = fs.readFileSync(excludeFile, "utf8").split("\n");
+  const removed = lines.filter((l) => drop.has(l.trim()));
+  if (removed.length) fs.writeFileSync(excludeFile, lines.filter((l) => !drop.has(l.trim())).join("\n"));
+  return removed.map((l) => l.trim());
+}
+
+function repoScoped(scope, projectDir) {
+  if (!SCOPES.includes(scope)) throw new Error(`unknown scope "${scope}"; use one of ${SCOPES.join(", ")}`);
+  if (scope !== "user" && !projectDir) throw new Error(`--scope ${scope} registers nomArmy for one repository; run it inside that repository`);
+  return scope !== "user";
+}
+
 /**
  * Every distinct auth_env name declared across config/providers.yml's
  * pools, mapped to a placeholder value -- NEVER the real credential, which
@@ -302,7 +346,8 @@ export function derivePoolAuthEnvPlaceholders(configDir = globalConfigDir()) {
 /**
  * @param {{ nomarmyRoot: string, installDir?: string, run?: Function, extraEnv?: Record<string,string>, configDir?: string }} input
  */
-export function connectClaude({ nomarmyRoot, installDir = defaultInstallDir(), run = defaultRun, extraEnv = {}, configDir = globalConfigDir(), commandsDir = defaultCommandDirs().claude, settingsPath = defaultClaudeSettingsPath() }) {
+export function connectClaude({ nomarmyRoot, installDir = defaultInstallDir(), run = defaultRun, extraEnv = {}, configDir = globalConfigDir(), commandsDir = defaultCommandDirs().claude, settingsPath = defaultClaudeSettingsPath(), scope = "user", projectDir = null }) {
+  if (repoScoped(scope, projectDir)) return connectClaudeToRepo({ nomarmyRoot, installDir, run, extraEnv, configDir, scope, projectDir });
   installMcpCopy({ nomarmyRoot, installDir, run });
   const commands = installPlaybooks({ nomarmyRoot, target: "claude", dir: commandsDir });
   const notifier = buildNotifierApp({ nomarmyRoot });
@@ -340,13 +385,62 @@ export function connectClaude({ nomarmyRoot, installDir = defaultInstallDir(), r
     run("claude", ["mcp", "add", SERVER_NAME, ...envArgs, "--", "node", serverPath]);
   }
   run("claude", ["mcp", "get", SERVER_NAME]);
-  return { installDir, serverPath, preservedEnv: finalEnv, commands, statusLine, notifier };
+  return { installDir, serverPath, preservedEnv: finalEnv, commands, statusLine, notifier, scope: "user" };
+}
+
+// Claude Code's local scope (this repo, only you) or project scope (.mcp.json,
+// committed). The /feature playbook goes in the repo's .claude/commands, so it
+// shows up only where nomArmy is registered; no status line, which is a
+// user-wide setting.
+function connectClaudeToRepo({ nomarmyRoot, installDir, run, extraEnv, configDir, scope, projectDir }) {
+  installMcpCopy({ nomarmyRoot, installDir, run });
+  const commands = installPlaybooks({ nomarmyRoot, target: "claude", dir: path.join(projectDir, ".claude", "commands") });
+  const playbookPaths = commands.installed.map((f) => path.relative(projectDir, path.join(commands.dir, f)));
+  const excluded = scope === "local" ? excludeFromGit(projectDir, playbookPaths, run) : [];
+  if (scope === "project") includeInGit(projectDir, playbookPaths, run);
+  const serverPath = path.join(installDir, "mcp", "server.mjs");
+  const opts = { cwd: projectDir };
+  quietRun(run, "claude", ["mcp", "remove", SERVER_NAME, "--scope", scope], opts);
+  let env = {};
+  if (scope === "local") {
+    env = { ...derivePoolAuthEnvPlaceholders(configDir), ...extraEnv, ...deriveWorkerModelEnv(nomarmyRoot) };
+    const envArgs = Object.entries(env).flatMap(([k, v]) => ["-e", `${k}=${v}`]);
+    run("claude", ["mcp", "add", "--scope", "local", SERVER_NAME, ...envArgs, "--", "node", serverPath], opts);
+  } else {
+    run("claude", ["mcp", "add", "--scope", "project", SERVER_NAME, "--", PORTABLE_SERVER.command, ...PORTABLE_SERVER.args], opts);
+  }
+  run("claude", ["mcp", "get", SERVER_NAME], opts);
+  return { installDir, serverPath: scope === "local" ? serverPath : null, preservedEnv: env, commands, excluded, scope, projectDir,
+    configPath: scope === "project" ? path.join(projectDir, ".mcp.json") : null, userScoped: claudeUserScoped(run) };
+}
+
+/**
+ * What `nomarmy mcp` runs: the installed copy when there is one (the code
+ * `nomarmy update` keeps current), else this package's own server, with the
+ * env connect would register (worker model, api-key placeholders) under
+ * whatever the caller already set.
+ */
+export function portableServerLaunch({ nomarmyRoot, installDir = defaultInstallDir(), configDir = globalConfigDir(), env = process.env }) {
+  const installed = path.join(installDir, "mcp", "server.mjs");
+  const serverPath = fs.existsSync(installed) ? installed : path.join(nomarmyRoot, "mcp", "server.mjs");
+  return { serverPath, env: { ...derivePoolAuthEnvPlaceholders(configDir), ...deriveWorkerModelEnv(nomarmyRoot), ...env } };
+}
+
+/** Whether Claude Code also has nomArmy registered for every project. */
+export function claudeUserScoped(run = defaultRun) {
+  try {
+    const out = String(run("claude", ["mcp", "get", SERVER_NAME], { cwd: os.homedir(), stdio: ["ignore", "pipe", "ignore"], encoding: "utf8" }));
+    return /Scope:\s*User/i.test(out);
+  } catch { return false; }
 }
 
 /**
  * @param {{ nomarmyRoot: string, installDir?: string, run?: Function }} input
  */
-export function connectCodex({ nomarmyRoot, installDir = defaultInstallDir(), run = defaultRun, configDir = globalConfigDir(), skillsDir = defaultCommandDirs().codex, legacySkillsDir = path.join(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "skills") }) {
+export function connectCodex({ nomarmyRoot, installDir = defaultInstallDir(), run = defaultRun, configDir = globalConfigDir(), skillsDir = defaultCommandDirs().codex, legacySkillsDir = path.join(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "skills"), scope = "user" }) {
+  // `codex mcp add` has no scope: Codex registers MCP servers only in
+  // ~/.codex/config.toml, for every project.
+  if (scope !== "user") throw new Error(`Codex registers MCP servers only for every project (~/.codex/config.toml), so --scope ${scope} isn't available for it; connect Codex without --scope, or use Claude Code or Cursor for a per-repo registration`);
   installMcpCopy({ nomarmyRoot, installDir, run });
   const commands = installPlaybooks({ nomarmyRoot, target: "codex", dir: skillsDir });
   removeLegacyCodexSkill(legacySkillsDir, skillsDir);
@@ -410,7 +504,13 @@ export function readCursorConfig(configPath) {
 /**
  * @param {{ nomarmyRoot: string, installDir?: string, configPath?: string }} input
  */
-export function connectCursor({ nomarmyRoot, installDir = defaultInstallDir(), configPath = defaultCursorConfigPath(), run = defaultRun, configDir = globalConfigDir(), commandsDir = defaultCommandDirs().cursor }) {
+export function connectCursor({ nomarmyRoot, installDir = defaultInstallDir(), configPath = defaultCursorConfigPath(), run = defaultRun, configDir = globalConfigDir(), commandsDir = defaultCommandDirs().cursor, scope = "user", projectDir = null }) {
+  // Cursor reads a project's own .cursor/mcp.json beside the user one. local
+  // keeps it out of git; project commits it, with the portable command.
+  if (repoScoped(scope, projectDir)) {
+    configPath = path.join(projectDir, ".cursor", "mcp.json");
+    commandsDir = path.join(projectDir, ".cursor", "commands");
+  }
   installMcpCopy({ nomarmyRoot, installDir, run });
   const commands = installPlaybooks({ nomarmyRoot, target: "cursor", dir: commandsDir });
   const notifier = buildNotifierApp({ nomarmyRoot });
@@ -427,10 +527,15 @@ export function connectCursor({ nomarmyRoot, installDir = defaultInstallDir(), c
   // Cursor starts a global MCP server in the home folder, not the open
   // project; ${workspaceFolder} is Cursor's own placeholder for the latter.
   const preservedEnv = { ...derivePoolAuthEnvPlaceholders(configDir), ...((existing && typeof existing.env === "object" && existing.env) || {}), ...deriveWorkerModelEnv(nomarmyRoot), NOMARMY_PROJECT_DIR: "${workspaceFolder}" };
-  config.mcpServers[SERVER_NAME] = { command: "node", args: [serverPath], env: preservedEnv };
+  config.mcpServers[SERVER_NAME] = scope === "project"
+    ? { command: PORTABLE_SERVER.command, args: [...PORTABLE_SERVER.args], env: { NOMARMY_PROJECT_DIR: "${workspaceFolder}" } }
+    : { command: "node", args: [serverPath], env: preservedEnv };
   fs.mkdirSync(path.dirname(configPath), { recursive: true });
   fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
-  return { installDir, serverPath, configPath, preservedEnv, commands, notifier };
+  const repoPaths = scope === "user" ? [] : [path.relative(projectDir, configPath), ...commands.installed.map((f) => path.relative(projectDir, path.join(commands.dir, f)))];
+  const excluded = scope === "local" ? excludeFromGit(projectDir, repoPaths, run) : [];
+  if (scope === "project") includeInGit(projectDir, repoPaths, run);
+  return { installDir, serverPath, configPath, preservedEnv: scope === "project" ? config.mcpServers[SERVER_NAME].env : preservedEnv, commands, notifier, scope, excluded };
 }
 
 /** True when Cursor's config file already has a nomArmy entry -- used by

package/package.json

@@ -3,7 +3,7 @@
   "description": "Every byte verified: a harness for AI coding workers whose claims are never trusted. Your coding assistant stays in charge while workers implement and test in sandboxes, and nomArmy checks every change before it is committed.",
   "author": "Rayson Technologies",
   "license": "Apache-2.0",
-  "version": "0.1.0-alpha.10",
+  "version": "0.1.0-alpha.11",
   "private": false,
   "type": "module",
   "engines": {