@mutmutco/cli 0.8.2 → 0.9.0

package/README.md

@@ -10,6 +10,12 @@ This package is published from [mutmutco/MMI-Hub](https://github.com/mutmutco/MM
 npm install -g @mutmutco/cli
 ```
 
+Authenticate GitHub once for saga and Project board operations:
+
+```powershell
+gh auth login --hostname github.com --git-protocol https --web --scopes "project"
+```
+
 Then verify the installed command:
 
 ```powershell

package/dist/index.cjs

@@ -3038,7 +3038,7 @@ var {
 
 // src/index.ts
 var import_promises = require("node:fs/promises");
-var import_node_fs2 = require("node:fs");
+var import_node_fs3 = require("node:fs");
 var import_node_crypto = require("node:crypto");
 
 // src/rules-sync.ts
@@ -3064,9 +3064,9 @@ function parseHookInput(stdin) {
 }
 
 // src/index.ts
-var import_node_child_process3 = require("node:child_process");
-var import_node_util2 = require("node:util");
-var import_node_path2 = require("node:path");
+var import_node_child_process4 = require("node:child_process");
+var import_node_util3 = require("node:util");
+var import_node_path3 = require("node:path");
 
 // src/saga-head-maintainer.ts
 var import_node_child_process = require("node:child_process");
@@ -3133,11 +3133,11 @@ function parseHeadUpdate(raw) {
   return Object.keys(u).length ? u : null;
 }
 async function runHeadEngine(prompt, timeoutMs = HEAD_ENGINE_TIMEOUT_MS) {
-  const { cmd, args, shell } = resolveEngine(process.platform, process.env.SAGA_HEAD_ENGINE);
+  const { cmd, args, shell: shell2 } = resolveEngine(process.platform, process.env.SAGA_HEAD_ENGINE);
   return await new Promise((resolve) => {
     let child;
     try {
-      child = (0, import_node_child_process.spawn)(cmd, args, { shell, windowsHide: true });
+      child = (0, import_node_child_process.spawn)(cmd, args, { shell: shell2, windowsHide: true });
     } catch {
       return resolve("");
     }
@@ -3853,12 +3853,12 @@ function formatGcPlan(plan, apply) {
 }
 
 // src/command-plans.ts
-function stagePlan(stage = {}) {
+function stagePlan(stage2 = {}) {
   return [
     { label: "force-kill previous local stage", command: "mmi-cli stage stop --apply" },
-    { label: "run local build", command: stage.build || "(no stage.build configured)" },
-    { label: "start local stage", command: stage.up || "(no stage.up configured)" },
-    { label: "check health", command: stage.healthUrl ? `curl --fail ${stage.healthUrl}` : "(no stage.healthUrl configured)" }
+    { label: "run local build", command: stage2.build || "(no stage.build configured)" },
+    { label: "start local stage", command: stage2.up || "(no stage.up configured)" },
+    { label: "check health", command: stage2.healthUrl ? `curl --fail ${stage2.healthUrl}` : "(no stage.healthUrl configured)" }
   ];
 }
 function trainPlan(command) {
@@ -3886,26 +3886,245 @@ function trainPlan(command) {
   ];
 }
 function bootstrapPlan(repo, repoClass) {
-  const branches = repoClass === "content" ? "main" : "development, rc, main";
+  const branchModel = repoClass === "content" ? "content repo: main only" : "deployable repo: development, rc, main";
+  const protectedBranches = repoClass === "content" ? "main" : "development, rc, main";
   return [
     { label: `create or inspect ${repo}` },
-    { label: `provision branches: ${branches}`, gated: true },
-    { label: "apply branch protection / train allowlist", gated: true },
-    { label: "attach GitHub Project v2 and write .mmi/config.json", gated: true },
-    { label: "seed README.md and architecture.md", gated: true },
-    { label: "install plugin settings and register fanout", gated: true }
+    { label: `provision branch model: ${branchModel}`, gated: true },
+    { label: `apply branch protection / allowlist: ${protectedBranches}`, gated: true },
+    { label: "attach GitHub Project v2 and write saga-ready .mmi/config.json", gated: true },
+    { label: "seed README.md, architecture.md, AGENTS.md, and CLAUDE.md", gated: true },
+    { label: "commit .claude/settings.json and .cursor/rules/<repo>.mdc", gated: true },
+    { label: `register fanout target on ${repoClass === "content" ? "main" : "development"}`, gated: true }
   ];
 }
 
-// src/index.ts
+// src/doctor.ts
+var GH_PROJECT_LOGIN_FIX = 'run: gh auth login --hostname github.com --git-protocol https --web --scopes "project"';
+function buildGithubAuthCheck(input) {
+  const ok = Boolean(input.login?.trim());
+  return {
+    ok,
+    label: "GitHub auth identity (saga + gh ops)",
+    fix: input.ghInstalled ? GH_PROJECT_LOGIN_FIX : `install GitHub CLI (https://cli.github.com), then: ${GH_PROJECT_LOGIN_FIX.replace(/^run: /, "")}`
+  };
+}
+
+// src/stage-runner.ts
+var import_node_child_process3 = require("node:child_process");
+var import_node_fs2 = require("node:fs");
+var import_node_path2 = require("node:path");
+var import_node_util2 = require("node:util");
 var execFileP2 = (0, import_node_util2.promisify)(import_node_child_process3.execFile);
+function stageStatePath(cwd = process.cwd()) {
+  return (0, import_node_path2.join)(cwd, "tmp", "stage", "state.json");
+}
+function validateStageConfig(config = {}, action) {
+  const problems = [];
+  if (action === "run" && !config.build?.trim()) problems.push("stage.build is required for stage run");
+  if (!config.up?.trim()) problems.push("stage.up is required to start the local stage");
+  if (config.healthUrl != null && config.healthUrl.trim() && !/^https?:\/\//.test(config.healthUrl.trim())) {
+    problems.push("stage.healthUrl must be an http(s) URL");
+  }
+  return problems;
+}
+async function shell(command, cwd, timeoutMs) {
+  await execFileP2(command, [], {
+    cwd,
+    shell: true,
+    timeout: timeoutMs,
+    windowsHide: true,
+    maxBuffer: 1024 * 1024 * 4
+  });
+}
+function readState(path) {
+  if (!(0, import_node_fs2.existsSync)(path)) return null;
+  try {
+    return JSON.parse((0, import_node_fs2.readFileSync)(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function killTree(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return;
+  if (process.platform === "win32") {
+    await execFileP2("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true }).catch(() => void 0);
+    return;
+  }
+  try {
+    process.kill(-pid, "SIGTERM");
+  } catch {
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch {
+    }
+  }
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  try {
+    process.kill(-pid, "SIGKILL");
+  } catch {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+    }
+  }
+}
+async function waitForHealth(url, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let last = "";
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(Math.min(5e3, timeoutMs)) });
+      if (res.ok) return;
+      last = `HTTP ${res.status}`;
+    } catch (e) {
+      last = e.message;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 1e3));
+  }
+  throw new Error(`stage health check timed out for ${url}${last ? ` (${last})` : ""}`);
+}
+async function stopStage(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const statePath = opts.statePath ?? stageStatePath(cwd);
+  const state = readState(statePath);
+  if (!state) {
+    return { ok: true, action: "stop", statePath, message: "no previous stage state found" };
+  }
+  await killTree(state.pid);
+  (0, import_node_fs2.rmSync)(statePath, { force: true });
+  return { ok: true, action: "stop", statePath, pid: state.pid, message: `stopped previous stage pid ${state.pid}` };
+}
+async function startStage(config = {}, opts = {}) {
+  const problems = validateStageConfig(config, "start");
+  if (problems.length) throw new Error(problems.join("; "));
+  const cwd = opts.cwd ?? process.cwd();
+  const statePath = opts.statePath ?? stageStatePath(cwd);
+  const dir = statePath.slice(0, Math.max(statePath.lastIndexOf("/"), statePath.lastIndexOf("\\")));
+  (0, import_node_fs2.mkdirSync)(dir, { recursive: true });
+  const up = config.up.trim();
+  const child = (0, import_node_child_process3.spawn)(up, {
+    cwd,
+    shell: true,
+    detached: true,
+    windowsHide: true,
+    stdio: "ignore"
+  });
+  const state = {
+    pid: child.pid ?? 0,
+    command: up,
+    cwd,
+    startedAt: (opts.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
+    healthUrl: config.healthUrl?.trim() || void 0
+  };
+  (0, import_node_fs2.writeFileSync)(statePath, JSON.stringify(state, null, 2), "utf8");
+  if (state.healthUrl) await waitForHealth(state.healthUrl, opts.timeoutMs ?? 6e4);
+  const result = { ok: true, action: "start", statePath, pid: state.pid, message: `started stage pid ${state.pid}` };
+  opts.onReady?.(result);
+  child.unref();
+  return result;
+}
+async function runStage(config = {}, opts = {}) {
+  const problems = validateStageConfig(config, "run");
+  if (problems.length) throw new Error(problems.join("; "));
+  const cwd = opts.cwd ?? process.cwd();
+  const timeoutMs = opts.timeoutMs ?? 6e4;
+  await stopStage({ ...opts, cwd });
+  await shell(config.build.trim(), cwd, timeoutMs);
+  const started = await startStage(config, { ...opts, cwd, timeoutMs });
+  return { ...started, action: "run", message: `built and ${started.message}` };
+}
+
+// src/bootstrap-verify.ts
+var requiredDocs = ["README.md", "architecture.md", "AGENTS.md", "CLAUDE.md", ".claude/settings.json", ".mmi/config.json"];
+var requiredLabels = ["bug", "feature", "task"];
+function expectedBranches(repoClass) {
+  return repoClass === "content" ? ["main"] : ["development", "rc", "main"];
+}
+function safeJson(text, fallback) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return fallback;
+  }
+}
+async function ghJson(deps, args, fallback) {
+  try {
+    return safeJson((await deps.gh(args)).stdout, fallback);
+  } catch {
+    return fallback;
+  }
+}
+async function contentExists(deps, repo, branch, path) {
+  try {
+    const encodedPath = path.split("/").map(encodeURIComponent).join("/");
+    await deps.gh(["api", `repos/${repo}/contents/${encodedPath}?ref=${encodeURIComponent(branch)}`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function protectedBranch(deps, repo, branch) {
+  try {
+    await deps.gh(["api", `repos/${repo}/branches/${branch}/protection`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function localRegistryCheck(deps, path, predicate) {
+  const text = deps.readLocalFile?.(path);
+  if (text == null) return null;
+  return predicate(safeJson(text, null));
+}
+async function verifyBootstrap(repo, repoClass, deps) {
+  const branchesWanted = expectedBranches(repoClass);
+  const baseBranch = repoClass === "content" ? "main" : "development";
+  const checks = [];
+  const repoInfo = await ghJson(deps, ["api", `repos/${repo}`], {});
+  checks.push({ ok: Boolean(repoInfo.default_branch), label: "repo exists" });
+  checks.push({ ok: repoInfo.default_branch === baseBranch, label: `default branch is ${baseBranch}`, detail: repoInfo.default_branch || "missing" });
+  checks.push({ ok: repoInfo.has_wiki === true, label: "wiki enabled", detail: repoInfo.has_wiki === true ? void 0 : "has_wiki is false or unavailable" });
+  const branchList = await ghJson(deps, ["api", `repos/${repo}/branches`, "--paginate"], []);
+  const branchNames = new Set(branchList.map((b) => b.name));
+  for (const branch of branchesWanted) {
+    checks.push({ ok: branchNames.has(branch), label: `branch exists: ${branch}` });
+    checks.push({ ok: await protectedBranch(deps, repo, branch), label: `branch protection exists: ${branch}` });
+  }
+  for (const path of requiredDocs) {
+    checks.push({ ok: await contentExists(deps, repo, baseBranch, path), label: `bootstrap artifact exists: ${path}` });
+  }
+  checks.push({ ok: await contentExists(deps, repo, baseBranch, ".cursor/environment.json"), label: "Cursor environment committed" });
+  const labels = await ghJson(deps, ["label", "list", "--repo", repo, "--json", "name"], []);
+  const labelNames = new Set(labels.map((l) => l.name));
+  for (const label of requiredLabels) {
+    checks.push({ ok: labelNames.has(label), label: `label exists: ${label}` });
+  }
+  const actions = await ghJson(deps, ["api", `repos/${repo}/actions/permissions`], {});
+  checks.push({ ok: actions.enabled === true, label: "GitHub Actions enabled" });
+  const fanout = repo === "mutmutco/MMI-Hub" ? true : localRegistryCheck(deps, ".github/fanout-targets.json", (json) => Array.isArray(json?.repos) && json.repos.some((r) => r.repo === repo.split("/")[1] && r.branch === baseBranch));
+  if (fanout != null) checks.push({ ok: fanout, label: `fanout target registered on ${baseBranch}` });
+  const projectRegistry = localRegistryCheck(deps, "projects.json", (json) => Array.isArray(json?.projects) && json.projects.some((p) => (p.repos || []).includes(repo)));
+  if (projectRegistry != null) checks.push({ ok: projectRegistry, label: "cloud-agent project registry includes repo" });
+  return { ok: checks.every((c) => c.ok), repo, class: repoClass, baseBranch, checks };
+}
+function renderBootstrapVerifyReport(report) {
+  const lines = [`mmi-cli bootstrap verify: ${report.ok ? "OK" : "CHECK"} ${report.repo} (${report.class}, ${report.baseBranch})`];
+  for (const check of report.checks) {
+    lines.push(`${check.ok ? "\u2713" : "\u2717"} ${check.label}${check.detail ? ` \u2014 ${check.detail}` : ""}`);
+  }
+  return lines.join("\n");
+}
+
+// src/index.ts
+var execFileP3 = (0, import_node_util3.promisify)(import_node_child_process4.execFile);
 var GIT_TIMEOUT_MS = 1e4;
 var GC_GH_TIMEOUT_MS = 2e4;
 async function githubToken() {
   if (process.env.GH_TOKEN) return process.env.GH_TOKEN;
   if (process.env.GITHUB_TOKEN) return process.env.GITHUB_TOKEN;
   try {
-    const { stdout } = await execFileP2("gh", ["auth", "token"]);
+    const { stdout } = await execFileP3("gh", ["auth", "token"]);
     return stdout.trim() || void 0;
   } catch {
     return void 0;
@@ -3913,7 +4132,7 @@ async function githubToken() {
 }
 async function githubLogin() {
   try {
-    const { stdout } = await execFileP2("gh", ["api", "user", "--jq", ".login"]);
+    const { stdout } = await execFileP3("gh", ["api", "user", "--jq", ".login"]);
     return stdout.trim() || void 0;
   } catch {
     return void 0;
@@ -3935,7 +4154,7 @@ var DEFAULT_KB_SOURCE = "https://raw.githubusercontent.com/mutmutco/MM-KB/main";
 var SESSION_FILE = ".mmi/.session";
 var gitOut = async (args) => {
   try {
-    return (await execFileP2("git", [...args])).stdout.trim();
+    return (await execFileP3("git", [...args])).stdout.trim();
   } catch {
     return "";
   }
@@ -3945,7 +4164,7 @@ function sessionDeps() {
     env: process.env,
     readPersisted: () => {
       try {
-        return (0, import_node_fs2.readFileSync)(SESSION_FILE, "utf8");
+        return (0, import_node_fs3.readFileSync)(SESSION_FILE, "utf8");
       } catch {
         return null;
       }
@@ -3958,8 +4177,8 @@ function sessionDeps() {
 var resolveSessionId = () => resolveSession(sessionDeps());
 function persistSession(id) {
   try {
-    (0, import_node_fs2.mkdirSync)(".mmi", { recursive: true });
-    (0, import_node_fs2.writeFileSync)(SESSION_FILE, id, "utf8");
+    (0, import_node_fs3.mkdirSync)(".mmi", { recursive: true });
+    (0, import_node_fs3.writeFileSync)(SESSION_FILE, id, "utf8");
   } catch {
   }
 }
@@ -3995,18 +4214,18 @@ async function readStdin() {
 async function ghPrs(limit) {
   const args = (state) => ["pr", "list", "--state", state, "--limit", String(limit), "--json", "number,headRefName,state"];
   const [open, closed] = await Promise.all([
-    execFileP2("gh", args("open"), { timeout: GC_GH_TIMEOUT_MS }),
-    execFileP2("gh", args("closed"), { timeout: GC_GH_TIMEOUT_MS })
+    execFileP3("gh", args("open"), { timeout: GC_GH_TIMEOUT_MS }),
+    execFileP3("gh", args("closed"), { timeout: GC_GH_TIMEOUT_MS })
   ]);
   return [...JSON.parse(open.stdout || "[]"), ...JSON.parse(closed.stdout || "[]")];
 }
 async function worktreeBranches() {
-  const { stdout } = await execFileP2("git", ["worktree", "list", "--porcelain"], { timeout: GIT_TIMEOUT_MS });
+  const { stdout } = await execFileP3("git", ["worktree", "list", "--porcelain"], { timeout: GIT_TIMEOUT_MS });
   const parsed = parseWorktreePorcelain(stdout);
   return await Promise.all(parsed.map(async (w) => {
     let dirty = true;
     try {
-      const { stdout: status } = await execFileP2("git", ["-C", w.path, "status", "--porcelain"], { timeout: GIT_TIMEOUT_MS });
+      const { stdout: status } = await execFileP3("git", ["-C", w.path, "status", "--porcelain"], { timeout: GIT_TIMEOUT_MS });
       dirty = status.trim().length > 0;
     } catch {
       dirty = true;
@@ -4018,7 +4237,7 @@ async function gcPlan(remote, limit) {
   const [branches, current, stale, prs, worktrees] = await Promise.all([
     gitOut(["branch", "--format=%(refname:short)"]),
     gitOut(["rev-parse", "--abbrev-ref", "HEAD"]),
-    execFileP2("git", ["remote", "prune", remote, "--dry-run"], { timeout: GIT_TIMEOUT_MS }).then((r) => parseRemotePruneDryRun(`${r.stdout}${r.stderr}`)).catch(() => []),
+    execFileP3("git", ["remote", "prune", remote, "--dry-run"], { timeout: GIT_TIMEOUT_MS }).then((r) => parseRemotePruneDryRun(`${r.stdout}${r.stderr}`)).catch(() => []),
     ghPrs(limit),
     worktreeBranches()
   ]);
@@ -4033,24 +4252,24 @@ async function gcPlan(remote, limit) {
 }
 async function applyGcPlan(plan, remote) {
   for (const branch of plan.branches) {
-    if (branch.worktreePath) await execFileP2("git", ["worktree", "remove", branch.worktreePath], { timeout: GIT_TIMEOUT_MS });
-    await execFileP2("git", ["branch", "-D", branch.branch], { timeout: GIT_TIMEOUT_MS });
+    if (branch.worktreePath) await execFileP3("git", ["worktree", "remove", branch.worktreePath], { timeout: GIT_TIMEOUT_MS });
+    await execFileP3("git", ["branch", "-D", branch.branch], { timeout: GIT_TIMEOUT_MS });
   }
   for (const ref of plan.trackingRefs) {
-    await execFileP2("git", ["update-ref", "-d", `refs/remotes/${remote}/${ref.branch}`], { timeout: GIT_TIMEOUT_MS });
+    await execFileP3("git", ["update-ref", "-d", `refs/remotes/${remote}/${ref.branch}`], { timeout: GIT_TIMEOUT_MS });
   }
   if (plan.branches.some((b) => b.worktreePath)) {
-    await execFileP2("git", ["worktree", "prune"], { timeout: GIT_TIMEOUT_MS });
+    await execFileP3("git", ["worktree", "prune"], { timeout: GIT_TIMEOUT_MS });
   }
 }
 function resolveVersion() {
   try {
-    const manifest = (0, import_node_path2.join)(__dirname, "..", "..", ".claude-plugin", "plugin.json");
-    return JSON.parse((0, import_node_fs2.readFileSync)(manifest, "utf8")).version || "0.0.0";
+    const manifest = (0, import_node_path3.join)(__dirname, "..", "..", ".claude-plugin", "plugin.json");
+    return JSON.parse((0, import_node_fs3.readFileSync)(manifest, "utf8")).version || "0.0.0";
   } catch {
     try {
-      const pkg = (0, import_node_path2.join)(__dirname, "..", "package.json");
-      return JSON.parse((0, import_node_fs2.readFileSync)(pkg, "utf8")).version || "0.0.0";
+      const pkg = (0, import_node_path3.join)(__dirname, "..", "package.json");
+      return JSON.parse((0, import_node_fs3.readFileSync)(pkg, "utf8")).version || "0.0.0";
     } catch {
       return "0.0.0";
     }
@@ -4058,7 +4277,7 @@ function resolveVersion() {
 }
 function readRepoVersion() {
   try {
-    return JSON.parse((0, import_node_fs2.readFileSync)((0, import_node_path2.join)(process.cwd(), ".claude-plugin", "plugin.json"), "utf8")).version || void 0;
+    return JSON.parse((0, import_node_fs3.readFileSync)((0, import_node_path3.join)(process.cwd(), ".claude-plugin", "plugin.json"), "utf8")).version || void 0;
   } catch {
     return void 0;
   }
@@ -4095,10 +4314,10 @@ rules.command("sync").option("--quiet", "stay silent unless something changed or
       if (!opts.quiet) console.error(`mmi-cli rules: could not fetch ${file} (${e.message}); left it untouched`);
       continue;
     }
-    const current = (0, import_node_fs2.existsSync)(file) ? await (0, import_promises.readFile)(file, "utf8") : null;
+    const current = (0, import_node_fs3.existsSync)(file) ? await (0, import_promises.readFile)(file, "utf8") : null;
     if (needsUpdate(source, current)) {
       const slash = file.lastIndexOf("/");
-      if (slash > 0) (0, import_node_fs2.mkdirSync)(file.slice(0, slash), { recursive: true });
+      if (slash > 0) (0, import_node_fs3.mkdirSync)(file.slice(0, slash), { recursive: true });
       await (0, import_promises.writeFile)(file, normalizeEol(source), "utf8");
       changed++;
       if (!opts.quiet) console.log(`mmi-cli rules: updated ${file}`);
@@ -4146,7 +4365,7 @@ saga.command("head-update").option("--run", "detached worker: fetch state, run t
     if (!headGateDue(tsPath)) return;
     markHeadRun(tsPath);
     try {
-      (0, import_node_child_process3.spawn)(process.execPath, [process.argv[1], "saga", "head-update", "--run"], {
+      (0, import_node_child_process4.spawn)(process.execPath, [process.argv[1], "saga", "head-update", "--run"], {
         detached: true,
         stdio: "ignore",
         windowsHide: true
@@ -4230,21 +4449,21 @@ program2.command("kb").description("org knowledgebase (read-only)").command("get
 });
 async function ghCreate(args) {
   try {
-    const { stdout } = await execFileP2("gh", args);
+    const { stdout } = await execFileP3("gh", args);
     return parseCreatedUrl(stdout);
   } catch (e) {
     const err = e;
     fail(`gh ${args[0]} create failed: ${(err.stderr || err.message || String(e)).trim()}`);
   }
 }
-async function ghJson(args, timeout = 1e4) {
-  const { stdout } = await execFileP2("gh", args, { timeout });
+async function ghJson2(args, timeout = 1e4) {
+  const { stdout } = await execFileP3("gh", args, { timeout });
   return JSON.parse(stdout);
 }
 async function resolveRepo(repo) {
   if (repo) return repo;
   try {
-    const { stdout } = await execFileP2("gh", ["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"], { timeout: 5e3 });
+    const { stdout } = await execFileP3("gh", ["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"], { timeout: 5e3 });
     return stdout.trim() || void 0;
   } catch {
     return void 0;
@@ -4254,7 +4473,7 @@ function scheduleRelatedDiscovery(o) {
   try {
     const args = ["issue", "discover-related", "--number", String(o.number), "--title", o.title, "--body", o.body];
     if (o.repo) args.push("--repo", o.repo);
-    (0, import_node_child_process3.spawn)(process.execPath, [process.argv[1], ...args], {
+    (0, import_node_child_process4.spawn)(process.execPath, [process.argv[1], ...args], {
       detached: true,
       stdio: "ignore",
       windowsHide: true,
@@ -4281,7 +4500,7 @@ issue.command("discover-related").description("find related issues for an existi
   const repo = await resolveRepo(o.repo);
   if (!repo) return fail("issue discover-related: could not resolve repo");
   try {
-    const issues = await ghJson([
+    const issues = await ghJson2([
       "issue",
       "list",
       "--repo",
@@ -4296,7 +4515,7 @@ issue.command("discover-related").description("find related issues for an existi
     const candidates = findRelatedIssues({ number, title: o.title, body: o.body }, issues);
     if (o.json) return console.log(JSON.stringify({ number, repo, candidates }, null, 2));
     if (!candidates.length) return;
-    const viewed = await ghJson([
+    const viewed = await ghJson2([
       "issue",
       "view",
       String(number),
@@ -4306,7 +4525,7 @@ issue.command("discover-related").description("find related issues for an existi
       "comments"
     ]);
     if (viewed.comments.some((comment) => comment.body.includes(relatedMarker(number)))) return;
-    await execFileP2("gh", ["issue", "comment", String(number), "--repo", repo, "--body", buildRelatedComment(number, candidates)], { timeout: 1e4 });
+    await execFileP3("gh", ["issue", "comment", String(number), "--repo", repo, "--body", buildRelatedComment(number, candidates)], { timeout: 1e4 });
   } catch {
   }
 });
@@ -4345,11 +4564,102 @@ function renderSteps(title, steps) {
     ...steps.map((step, i) => `${i + 1}. ${step.gated ? "[gated] " : ""}${step.label}${step.command ? ` - ${step.command}` : ""}`)
   ].join("\n");
 }
-program2.command("stage").description("plan or run the repo local stage environment").option("--json", "machine-readable output").option("--apply", "reserved for future stage execution; requires repo stage config").action(async (o) => {
-  if (o.apply) return fail("stage: execution is not implemented yet; use the dry-run plan and the existing /stage skill");
-  const steps = stagePlan((await loadConfig()).stage);
+function rawFlag(flag) {
+  return process.argv.includes(flag);
+}
+function rawValue(flag, fallback) {
+  const index = process.argv.indexOf(flag);
+  return index >= 0 && process.argv[index + 1] ? process.argv[index + 1] : fallback;
+}
+function printLine(value) {
+  (0, import_node_fs3.writeSync)(1, `${value}
+`);
+}
+function stageKeepAlive() {
+  return setTimeout(() => void 0, 5 * 60 * 1e3);
+}
+var stage = program2.command("stage").description("plan or run the repo local stage environment").option("--json", "machine-readable output").option("--apply", "run the full local stage: stop previous, build, start, health-check").option("--timeout-ms <ms>", "bounded build/health timeout", "60000").action(async (o) => {
+  const cfg = (await loadConfig()).stage;
+  if (o.apply) {
+    const hold = stageKeepAlive();
+    try {
+      const result = await runStage(cfg, { timeoutMs: Number(o.timeoutMs || 6e4) });
+      return printLine(o.json ? JSON.stringify(result) : `mmi-cli stage: ${result.message}`);
+    } catch (e) {
+      return fail(`stage: ${e.message}`);
+    } finally {
+      clearTimeout(hold);
+    }
+  }
+  const steps = stagePlan(cfg);
   console.log(o.json ? JSON.stringify({ command: "stage", steps }, null, 2) : renderSteps("mmi-cli stage: dry-run plan", steps));
 });
+stage.command("stop").description("stop the previous local stage process recorded in tmp/stage/state.json").option("--json", "machine-readable output").option("--apply", "kill the recorded process tree and remove the state file").action(async () => {
+  const o = { json: rawFlag("--json"), apply: rawFlag("--apply") };
+  if (!o.apply) {
+    const steps = [{ label: "stop recorded local stage", command: "mmi-cli stage stop --apply" }];
+    return printLine(o.json ? JSON.stringify({ command: "stage stop", steps }, null, 2) : renderSteps("mmi-cli stage stop: dry-run plan", steps));
+  }
+  try {
+    const result = await stopStage();
+    printLine(o.json ? JSON.stringify(result) : `mmi-cli stage stop: ${result.message}`);
+  } catch (e) {
+    fail(`stage stop: ${e.message}`);
+  }
+});
+stage.command("start").description("start the configured local stage process and optionally wait for health").option("--json", "machine-readable output").option("--apply", "start the configured stage.up process").option("--timeout-ms <ms>", "bounded health timeout", "60000").action(async () => {
+  const o = { json: rawFlag("--json"), apply: rawFlag("--apply"), timeoutMs: rawValue("--timeout-ms", "60000") };
+  const cfg = (await loadConfig()).stage;
+  if (!o.apply) {
+    const steps = [{ label: "start local stage", command: cfg?.up || "(no stage.up configured)" }];
+    return printLine(o.json ? JSON.stringify({ command: "stage start", steps }, null, 2) : renderSteps("mmi-cli stage start: dry-run plan", steps));
+  }
+  try {
+    const hold = stageKeepAlive();
+    let printed = false;
+    try {
+      const result = await startStage(cfg, {
+        timeoutMs: Number(o.timeoutMs || 6e4),
+        onReady: (ready) => {
+          printed = true;
+          printLine(o.json ? JSON.stringify(ready) : `mmi-cli stage start: ${ready.message}`);
+        }
+      });
+      if (!printed) printLine(o.json ? JSON.stringify(result) : `mmi-cli stage start: ${result.message}`);
+    } finally {
+      clearTimeout(hold);
+    }
+  } catch (e) {
+    fail(`stage start: ${e.message}`);
+  }
+});
+stage.command("run").description("force-stop previous stage, build, start, and health-check").option("--json", "machine-readable output").option("--apply", "run the configured stage sequence").option("--timeout-ms <ms>", "bounded build/health timeout", "60000").action(async () => {
+  const o = { json: rawFlag("--json"), apply: rawFlag("--apply"), timeoutMs: rawValue("--timeout-ms", "60000") };
+  const cfg = (await loadConfig()).stage;
+  if (!o.apply) {
+    const steps = stagePlan(cfg);
+    return printLine(o.json ? JSON.stringify({ command: "stage run", steps }, null, 2) : renderSteps("mmi-cli stage run: dry-run plan", steps));
+  }
+  try {
+    const hold = stageKeepAlive();
+    let printed = false;
+    try {
+      const result = await runStage(cfg, {
+        timeoutMs: Number(o.timeoutMs || 6e4),
+        onReady: (ready) => {
+          const runReady = { ...ready, action: "run", message: `built and ${ready.message}` };
+          printed = true;
+          printLine(o.json ? JSON.stringify(runReady) : `mmi-cli stage run: ${runReady.message}`);
+        }
+      });
+      if (!printed) printLine(o.json ? JSON.stringify(result) : `mmi-cli stage run: ${result.message}`);
+    } finally {
+      clearTimeout(hold);
+    }
+  } catch (e) {
+    fail(`stage run: ${e.message}`);
+  }
+});
 for (const commandName of ["rc", "release", "hotfix"]) {
   program2.command(commandName).description(`plan ${commandName} train operations; mutations require explicit approval`).option("--json", "machine-readable output").option("--apply", "reserved for future train execution after explicit admin approval").action((o) => {
     if (o.apply) return fail(`${commandName}: execution is not implemented yet; use the dry-run plan and the existing /${commandName} skill`);
@@ -4357,34 +4667,45 @@ for (const commandName of ["rc", "release", "hotfix"]) {
     console.log(o.json ? JSON.stringify({ command: commandName, steps }, null, 2) : renderSteps(`mmi-cli ${commandName}: dry-run plan`, steps));
   });
 }
-program2.command("bootstrap").description("plan repo bootstrap operations; mutations require master-admin approval").requiredOption("--repo <owner/repo>", "target repo").option("--class <class>", "deployable | content", "deployable").option("--json", "machine-readable output").option("--apply", "reserved for future bootstrap execution after explicit master-admin approval").action((o) => {
+var bootstrap = program2.command("bootstrap").description("plan repo bootstrap operations; mutations require master-admin approval").option("--repo <owner/repo>", "target repo").option("--class <class>", "deployable | content", "deployable").option("--json", "machine-readable output").option("--apply", "reserved for future bootstrap execution after explicit master-admin approval").action((o) => {
+  if (!o.repo) return fail("bootstrap: required option --repo <owner/repo> not specified");
   if (o.apply) return fail("bootstrap: execution is not implemented yet; use the dry-run plan and the existing /bootstrap skill");
   if (o.class !== "deployable" && o.class !== "content") return fail("bootstrap: --class must be deployable or content");
   const steps = bootstrapPlan(o.repo, o.class);
   console.log(o.json ? JSON.stringify({ command: "bootstrap", repo: o.repo, class: o.class, steps }, null, 2) : renderSteps(`mmi-cli bootstrap: dry-run plan for ${o.repo}`, steps));
 });
+bootstrap.command("verify <repo>").description("audit whether an existing repo is bootstrapped correctly; no mutations").option("--class <class>", "deployable | content", "deployable").option("--json", "machine-readable output").action(async (repo) => {
+  const o = { class: rawValue("--class", "deployable"), json: rawFlag("--json") };
+  if (o.class !== "deployable" && o.class !== "content") return fail("bootstrap verify: --class must be deployable or content");
+  const report = await verifyBootstrap(repo, o.class, {
+    gh: async (args) => execFileP3("gh", args, { timeout: 2e4 }),
+    readLocalFile: (path) => (0, import_node_fs3.existsSync)(path) ? (0, import_node_fs3.readFileSync)(path, "utf8") : null
+  });
+  console.log(o.json ? JSON.stringify(report, null, 2) : renderBootstrapVerifyReport(report));
+  if (!report.ok) process.exitCode = 1;
+});
 var isWin = process.platform === "win32";
 program2.command("doctor").description("check onboarding gates (GitHub auth, mmi-cli on PATH, repo config, plugin git clone) and print fixes").option("--banner", "one-line resume summary; silent when all gates pass").option("--json", "machine-readable output").action(async (opts) => {
   const checks = [];
-  const token = await githubToken();
-  let ghFix = "run: gh auth login";
-  if (!token) {
+  const login = await githubLogin();
+  let ghInstalled = true;
+  if (!login) {
     try {
-      await execFileP2("gh", ["--version"]);
+      await execFileP3("gh", ["--version"]);
     } catch {
-      ghFix = "install GitHub CLI (https://cli.github.com), then: gh auth login";
+      ghInstalled = false;
     }
   }
-  checks.push({ ok: Boolean(token), label: "GitHub auth (saga + gh ops)", fix: ghFix });
+  checks.push(buildGithubAuthCheck({ login, ghInstalled }));
   let onPath = false;
   try {
-    await execFileP2(isWin ? "where" : "which", ["mmi-cli"]);
+    await execFileP3(isWin ? "where" : "which", ["mmi-cli"]);
     onPath = true;
   } catch {
   }
   if (!onPath) {
     const root = process.env.CLAUDE_PLUGIN_ROOT;
-    if (root && (0, import_node_fs2.existsSync)(`${root}/bin/mmi-cli${isWin ? ".cmd" : ""}`)) onPath = true;
+    if (root && (0, import_node_fs3.existsSync)(`${root}/bin/mmi-cli${isWin ? ".cmd" : ""}`)) onPath = true;
   }
   checks.push({ ok: onPath, label: "mmi-cli on PATH", fix: "auto-provisioned at session start \u2014 reopen the session, or install the MMI plugin" });
   checks.push(buildVersionLagReport({
@@ -4398,13 +4719,13 @@ program2.command("doctor").description("check onboarding gates (GitHub auth, mmi
   const CLONE_FIX = 'run: git config --global url."https://github.com/".insteadOf "git@github.com:"';
   let cloneOk = false;
   try {
-    const { stdout } = await execFileP2("git", ["config", "--global", "--get-all", REWRITE_KEY]);
+    const { stdout } = await execFileP3("git", ["config", "--global", "--get-all", REWRITE_KEY]);
     cloneOk = stdout.split("\n").some((l) => l.trim() === "git@github.com:");
   } catch {
   }
   if (!cloneOk) {
     try {
-      await execFileP2("git", ["config", "--global", "--add", REWRITE_KEY, "git@github.com:"]);
+      await execFileP3("git", ["config", "--global", "--add", REWRITE_KEY, "git@github.com:"]);
       cloneOk = true;
       if (!opts.banner && !opts.json) console.error("  \u21BB repaired: git insteadOf git@github.com \u2192 https (plugin clone over HTTPS)");
     } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/cli",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "MMI Future CLI — delivers the org rules (whole-file), plus saga and KB access. The cross-IDE engine the plugin's SessionStart hook drives.",
   "type": "module",
   "license": "UNLICENSED",
@@ -31,7 +31,9 @@
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },
-  "dependencies": { "commander": "^12.1.0" },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "esbuild": "^0.24.0",