@mutmutco/cli 2.0.0 → 2.3.0

package/README.md

@@ -43,7 +43,7 @@ mmi-cli doctor --json
 - `mmi-cli pr create` and `pr merge` create PRs and land them with branch/worktree cleanup; `mmi-cli gc` dry-runs cleanup of merged/closed PR branches + stale tracking refs.
 - `mmi-cli board read|claim|show|move|done|backfill-priority` reads and moves GitHub Project work.
 - `mmi-cli stage`, `stage start`, `stage stop`, `stage run`, and `port-range <repo>` manage the local gitignored stage and its port block; `stage-live` explains that remote rc/live move only via `/rcand` · `/release` · `/hotfix`.
-- `mmi-cli rc`, `release`, and `hotfix` render guarded train plans; the train triggers the Hub's central tenant deployer, so product repos carry no deploy file.
+- `mmi-cli rcand`, `release`, and `hotfix` render guarded train plans; the train triggers the Hub's central tenant deployer, so product repos carry no deploy file.
 - `mmi-cli bootstrap`, `bootstrap verify`, and `bootstrap apply` plan, audit, and seed repo onboarding.
 - `mmi-cli access audit` checks collaborator roles and train-branch allowlists.
 - `mmi-cli doctor` checks GitHub auth, repo config, CLI availability, the per-project plugin install record, and stale plugin/cache state, auto-repairing the safe gaps.

package/dist/index.cjs

@@ -3221,6 +3221,13 @@ async function runHeadEngine(prompt, timeoutMs = HEAD_ENGINE_TIMEOUT_MS) {
 // src/gh-create.ts
 var ISSUE_TYPES = ["bug", "feature", "task"];
 var PRIORITIES = ["urgent", "high", "medium", "low"];
+function normalizePriority(priority) {
+  const p = priority.trim().toLowerCase();
+  if (!PRIORITIES.includes(p)) {
+    throw new Error(`unknown priority "${priority}" \u2014 expected one of: ${PRIORITIES.join(", ")}`);
+  }
+  return p;
+}
 function parseCreatedUrl(stdout) {
   const re = /https:\/\/github\.com\/[^\s]+\/(?:issues|pull)\/(\d+)/g;
   let match;
@@ -3234,9 +3241,7 @@ ${stdout.trim() || "(empty)"}`);
 }
 function buildIssueArgs({ type, title, body, priority, repo, labels }) {
   if (!ISSUE_TYPES.includes(type)) throw new Error(`unknown issue type "${type}" \u2014 expected one of: ${ISSUE_TYPES.join(", ")}`);
-  if (!PRIORITIES.includes(priority)) {
-    throw new Error(`unknown priority "${priority}" \u2014 expected one of: ${PRIORITIES.join(", ")}`);
-  }
+  normalizePriority(priority);
   const args = ["issue", "create"];
   if (repo) args.push("--repo", repo);
   args.push("--title", title, "--body", body, "--label", type);
@@ -3304,6 +3309,7 @@ function buildHealth(i) {
   if (!i.sagaApiUrl) problems.push("sagaApiUrl not configured in .mmi/config.json");
   if (!i.identity) problems.push("no GitHub identity (gh auth token / GH_TOKEN)");
   if (!i.reachable) problems.push("saga backend unreachable");
+  if (i.reachable && i.authorized === false) problems.push("saga backend rejected authenticated state access");
   if (!i.key.sessionId || i.key.sessionId === "-") problems.push("unsafe session id");
   const safeToWrite = problems.length === 0;
   return {
@@ -3311,6 +3317,7 @@ function buildHealth(i) {
     safeToWrite,
     identity: i.identity,
     reachable: i.reachable,
+    authorized: i.authorized,
     sagaApiUrl: i.sagaApiUrl,
     key: i.key,
     source: i.source,
@@ -3324,7 +3331,7 @@ function healthBanner(report) {
   return `saga health: CHECK - ${summary}${suffix}`;
 }
 function resumeCue() {
-  return '> STATUS/RESUME CUE \u2014 For any status, resume, or "where do I stand" report: read THIS saga HEAD first (`mmi-cli saga show`), then reconcile its NEXT / LAST 5 / DECISIONS against the live board + git/gh before reporting. Do not rebuild the picture from board/issues/memory while skipping the HEAD.';
+  return '> STATUS/RESUME CUE \u2014 For any status, resume, or "where do I stand" report: read THIS saga HEAD first (`mmi-cli saga show`), then reconcile its NEXT / LAST 5 / DECISIONS against the live board + git/gh before reporting. Do not rebuild the picture from board/issues/memory while skipping the HEAD. PRECEDENCE: the HEAD is prior-session belief and MAY BE SUPERSEDED \u2014 the current live user/master instruction WINS over any conflicting HEAD anchor, NEXT, or checklist; follow the live instruction and treat the stale HEAD item as superseded.';
 }
 
 // src/saga-note.ts
@@ -4288,23 +4295,29 @@ function stagePlan(stage2 = {}) {
 function stageLivePlan() {
   return [
     { label: "stage-live is not an org command; /stage is local only", command: "mmi-cli stage run --apply" },
-    { label: "remote rc/live environments move through the gated promotion train", command: "mmi-cli rc && mmi-cli release && mmi-cli hotfix", gated: true }
+    { label: "remote rc/live environments move through the gated promotion train", command: "mmi-cli rcand && mmi-cli release && mmi-cli hotfix", gated: true }
   ];
 }
 function trainPlan(command) {
-  if (command === "rc") {
+  if (command === "rcand") {
     return [
-      { label: "verify current branch is development" },
+      { label: "verify operator is a master-admin org owner", command: "gh api orgs/<owner>/memberships/<login> --jq .role", gated: true },
+      { label: "verify current branch is development", gated: true },
+      { label: "verify registry META for this project", command: "mmi-cli project get <owner/repo>", gated: true },
+      { label: "preflight required rc secret names", command: "mmi-cli secrets preflight --stage rc --repo <owner/repo>", gated: true },
       { label: "merge development to rc", gated: true },
-      { label: "deploy rc", gated: true }
+      { label: "dispatch central tenant deploy for rc", command: "gh workflow run tenant-deploy.yml --repo mutmutco/MMI-Hub -f slug=<slug> -f repo=<owner/repo> -f ref=rc -f stage=rc", gated: true }
     ];
   }
   if (command === "release") {
     return [
-      { label: "verify current branch is rc" },
+      { label: "verify operator is a master-admin org owner", command: "gh api orgs/<owner>/memberships/<login> --jq .role", gated: true },
+      { label: "verify current branch is rc", gated: true },
+      { label: "verify registry META for this project", command: "mmi-cli project get <owner/repo>", gated: true },
+      { label: "preflight required main secret names", command: "mmi-cli secrets preflight --stage main --repo <owner/repo>", gated: true },
       { label: "merge rc to main", gated: true },
       { label: "tag release and publish GitHub Release", gated: true },
-      { label: "deploy prod", gated: true },
+      { label: "dispatch central tenant deploy for main", command: "gh workflow run tenant-deploy.yml --repo mutmutco/MMI-Hub -f slug=<slug> -f repo=<owner/repo> -f ref=main -f stage=main", gated: true },
       { label: "roll development forward", gated: true }
     ];
   }
@@ -4406,6 +4419,13 @@ ${block}
 // src/doctor.ts
 var GH_PROJECT_LOGIN_FIX = 'run: gh auth login --hostname github.com --git-protocol https --web --scopes "project"';
 var AWS_CROSS_ACCOUNT_FIX = "use a non-root IAM user/session profile for master-agent AWS checks; set AWS_PROFILE or AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY (plus AWS_SESSION_TOKEN for temporary credentials), then verify `aws sts get-caller-identity` does not end in :root";
+var MMI_AGENTIC_ONBOARDING_GUIDE = {
+  label: "MMI Agentic Onboarding",
+  url: "https://github.com/mutmutco/MMI-Hub/wiki/Agentic-Dev-Environment-Guide"
+};
+function doctorResourcesForGaps(gaps) {
+  return gaps.length ? [MMI_AGENTIC_ONBOARDING_GUIDE] : [];
+}
 function buildGithubAuthCheck(input) {
   const ok = Boolean(input.login?.trim());
   return {
@@ -4461,6 +4481,45 @@ function buildPluginInstallRecordCheck(input) {
     recordToInsert
   };
 }
+var PLUGIN_DRIFT_LABEL = "plugin config drift (mmi@mmi duplicate rows / stale gitCommitSha)";
+function recordFreshness(r) {
+  return r.lastUpdated ?? r.installedAt ?? "";
+}
+function freshestRecord(records) {
+  return records.reduce((best, r) => recordFreshness(r) > recordFreshness(best) ? r : best);
+}
+function pluginConfigDriftFix(pluginId) {
+  return `\`${pluginId}\` registered as N duplicate project rows / a stale gitCommitSha in ~/.claude/plugins/installed_plugins.json \u2014 run \`mmi-cli doctor\` to collapse them to one \`scope: user\` entry at the highest version (a .bak backup is written first), or in \`/plugin\` uninstall the extra rows and reinstall once at user scope`;
+}
+function buildPluginConfigDriftCheck(input) {
+  const pluginId = input.pluginId ?? MMI_PLUGIN_ID;
+  const base = {
+    ok: true,
+    label: PLUGIN_DRIFT_LABEL,
+    fix: pluginConfigDriftFix(pluginId),
+    pluginId
+  };
+  if (!input.isOrgRepo) return base;
+  const records = input.installed?.plugins?.[pluginId];
+  if (!Array.isArray(records) || records.length === 0) return base;
+  const projectRows = records.filter((r) => r.scope === "project");
+  const freshest = freshestRecord(records);
+  const freshSha = freshest.gitCommitSha;
+  const staleShaRows = freshSha ? records.filter((r) => r.gitCommitSha !== void 0 && r.gitCommitSha !== freshSha).length : 0;
+  const duplicateProjectRows = projectRows.length > 1 ? projectRows.length : 0;
+  if (duplicateProjectRows === 0 && staleShaRows === 0) {
+    return { ...base, duplicateProjectRows: 0, staleShaRows: 0 };
+  }
+  const { projectPath: _drop, ...rest } = freshest;
+  const collapsed = { ...rest, scope: "user" };
+  return {
+    ...base,
+    ok: false,
+    recordsToWrite: [collapsed],
+    duplicateProjectRows,
+    staleShaRows
+  };
+}
 var GITIGNORE_BLOCK_LABEL = "org .gitignore managed block (.playwright-mcp/, .claude/worktrees/, scratch *.png)";
 var GITIGNORE_BLOCK_FIX = "run `mmi-cli doctor` to auto-insert the `# >>> mmi-managed >>>` block (or copy it from MMI-Hub's .gitignore)";
 function buildGitignoreManagedBlockCheck(input) {
@@ -4628,6 +4687,144 @@ async function runStage(config = {}, opts = {}) {
   return { ...started, action: "run", message: `built and ${started.message}` };
 }
 
+// src/train-apply.ts
+function resolveDeployModel(meta, repo) {
+  const m = meta?.deployModel;
+  if (m === "hub-serverless" || m === "serverless" || m === "tenant-container" || m === "content") return m;
+  if (meta?.class === "content") return "content";
+  if (repo.toLowerCase().endsWith("/mmi-hub")) return "hub-serverless";
+  return "tenant-container";
+}
+function clean(out) {
+  return out.trim();
+}
+function requireValue(value, label) {
+  if (!value) throw new Error(`${label} could not be resolved`);
+  return value;
+}
+function releaseTagFromRcTag(tag) {
+  return tag.replace(/-rc\.\d+$/, "");
+}
+async function verifyHubDistributionIfChanged(deps, model, releaseTag) {
+  if (model !== "hub-serverless") return;
+  await deps.run("node", ["scripts/release-distribution.mjs", "verify-if-changed", releaseTag, "--skip-npm-view"]);
+}
+function ensurePositiveCount(out, emptyMessage) {
+  const count = Number.parseInt(out.trim(), 10);
+  if (!Number.isFinite(count)) throw new Error(`could not parse ahead count: ${out.trim() || "(empty)"}`);
+  if (count <= 0) throw new Error(emptyMessage);
+}
+async function buildTrainApplyContext(deps) {
+  const repo = requireValue(clean(await deps.run("gh", ["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"])), "repo");
+  const [owner, name] = repo.split("/");
+  if (!owner || !name) throw new Error(`repo must be owner/name, got ${repo}`);
+  const login = requireValue(clean(await deps.run("gh", ["api", "user", "--jq", ".login"])), "GitHub login");
+  const role = clean(await deps.run("gh", ["api", `orgs/${owner}/memberships/${login}`, "--jq", ".role"]));
+  if (role !== "admin") {
+    throw new Error(`${commandAuthorityLabel(owner)} is master-admin only; @${login} is ${role || "not an org admin"}`);
+  }
+  return {
+    repo,
+    owner,
+    slug: name.toLowerCase(),
+    login
+  };
+}
+function commandAuthorityLabel(owner) {
+  return `${owner} release train`;
+}
+async function requireCleanTree(deps) {
+  const status = await deps.run("git", ["status", "--porcelain"]);
+  if (status.trim()) throw new Error("working tree must be clean before train apply");
+}
+async function requireBranch(deps, branch) {
+  const current = clean(await deps.run("git", ["rev-parse", "--abbrev-ref", "HEAD"]));
+  if (current !== branch) throw new Error(`must run from ${branch}, currently on ${current || "(unknown)"}`);
+}
+async function dispatchDeploy(deps, ctx, stage2, ref, model) {
+  if (model === "tenant-container") {
+    await deps.run("gh", [
+      "workflow",
+      "run",
+      "tenant-deploy.yml",
+      "--repo",
+      "mutmutco/MMI-Hub",
+      "-f",
+      `slug=${ctx.slug}`,
+      "-f",
+      `repo=${ctx.repo}`,
+      "-f",
+      `ref=${ref}`,
+      "-f",
+      `stage=${stage2}`
+    ]);
+    return `dispatched tenant-deploy.yml (slug=${ctx.slug}, ref=${ref}, stage=${stage2})`;
+  }
+  if (model === "hub-serverless") {
+    return ref === "rc" ? "no manual dispatch: deploy.yml auto-fires on the rc push (rc stage)" : "no manual dispatch: deploy.yml + publish.yml auto-fire on the published Release (prod)";
+  }
+  return `no manual dispatch: ${model} repo deploys via its own push-triggered workflow`;
+}
+async function preflight(deps, ctx, stage2) {
+  let meta = null;
+  try {
+    meta = JSON.parse(await deps.runSelf(["project", "get", ctx.repo]));
+  } catch {
+    meta = null;
+  }
+  const model = resolveDeployModel(meta, ctx.repo);
+  if (model === "content") {
+    throw new Error(`${ctx.repo} is a content repo (deployModel=content) \u2014 the release train does not apply (trunk-based; PR to main)`);
+  }
+  await deps.runSelf(["secrets", "preflight", "--stage", stage2, "--repo", ctx.repo]);
+  return model;
+}
+async function runTrainApply(command, deps) {
+  const ctx = await buildTrainApplyContext(deps);
+  await requireCleanTree(deps);
+  await deps.run("git", ["fetch", "origin"]);
+  if (command === "rcand") {
+    await requireBranch(deps, "development");
+    await deps.run("git", ["pull", "--ff-only", "origin", "development"]);
+    ensurePositiveCount(
+      await deps.run("git", ["rev-list", "--count", "origin/rc..origin/development"]),
+      "nothing to promote: origin/development is not ahead of origin/rc"
+    );
+    const deployModel2 = await preflight(deps, ctx, "rc");
+    const tag2 = requireValue(clean(await deps.run("node", ["scripts/next-version.mjs", "rc"])), "rc tag");
+    await verifyHubDistributionIfChanged(deps, deployModel2, releaseTagFromRcTag(tag2));
+    await deps.run("git", ["checkout", "rc"]);
+    await deps.run("git", ["pull", "--ff-only", "origin", "rc"]);
+    await deps.run("git", ["merge", "development", "--no-edit"]);
+    await deps.run("git", ["tag", tag2]);
+    await deps.run("git", ["push", "origin", "rc"]);
+    await deps.run("git", ["push", "origin", tag2]);
+    const dispatch2 = await dispatchDeploy(deps, ctx, "rc", "rc", deployModel2);
+    return { ...ctx, command, stage: "rc", ref: "rc", tag: tag2, deployModel: deployModel2, dispatch: dispatch2 };
+  }
+  await requireBranch(deps, "rc");
+  ensurePositiveCount(
+    await deps.run("git", ["rev-list", "--count", "origin/main..origin/rc"]),
+    "nothing to release: origin/rc is not ahead of origin/main"
+  );
+  const deployModel = await preflight(deps, ctx, "main");
+  await deps.run("git", ["checkout", "main"]);
+  await deps.run("git", ["pull", "--ff-only", "origin", "main"]);
+  await deps.run("git", ["merge", "rc", "--no-edit"]);
+  const tag = requireValue(clean(await deps.run("node", ["scripts/next-version.mjs", "release"])), "release tag");
+  await verifyHubDistributionIfChanged(deps, deployModel, tag);
+  await deps.run("git", ["tag", tag]);
+  await deps.run("git", ["push", "origin", "main"]);
+  await deps.run("git", ["push", "origin", tag]);
+  await deps.run("gh", ["release", "create", tag, "--generate-notes", "--latest", "--repo", ctx.repo]);
+  const dispatch = await dispatchDeploy(deps, ctx, "main", "main", deployModel);
+  await deps.run("git", ["checkout", "development"]);
+  await deps.run("git", ["pull", "--ff-only", "origin", "development"]);
+  await deps.run("git", ["merge", "main", "--no-edit"]);
+  await deps.run("git", ["push", "origin", "development"]);
+  return { ...ctx, command, stage: "main", ref: "main", tag, deployModel, dispatch };
+}
+
 // src/port-registry.ts
 var import_node_fs3 = require("node:fs");
 var BLOCK = 100;
@@ -4919,11 +5116,24 @@ var requiredProjectWorkflows = [
 ];
 var requiredOrgRulesetTypes = ["pull_request", "non_fast_forward", "deletion"];
 var requiredHubStatusChecks = ["cli", "infra", "docs"];
-var requiredActionsVariables = ["MMI_APP_ID"];
-var requiredActionsSecrets = ["MMI_APP_PRIVATE_KEY"];
 function expectedBranches(repoClass) {
   return repoClass === "content" ? ["main"] : ["development", "rc", "main"];
 }
+function gcpProjectForSlug(slug) {
+  return `mutmutco-${slug}`;
+}
+function findMissingGcpApis(declared, enabled) {
+  const enabledSet = new Set(enabled.map((a) => a.trim().toLowerCase()).filter(Boolean));
+  const seen = /* @__PURE__ */ new Set();
+  const missing = [];
+  for (const raw of declared) {
+    const api = raw.trim().toLowerCase();
+    if (!api || seen.has(api)) continue;
+    seen.add(api);
+    if (!enabledSet.has(api)) missing.push(api);
+  }
+  return missing;
+}
 function safeJson2(text, fallback) {
   try {
     return JSON.parse(text);
@@ -5050,16 +5260,6 @@ async function verifyBootstrap(repo, repoClass, deps) {
   checks.push({ ok: strays.length === 0, label: "no stray GitHub-default labels", detail: presentDetail(strays) });
   const actions = await ghJson2(deps, ["api", `repos/${repo}/actions/permissions`], {});
   checks.push({ ok: actions.enabled === true, label: "GitHub Actions enabled" });
-  const variables = await ghJson2(deps, ["variable", "list", "--repo", repo, "--json", "name"], []);
-  const variableNames = new Set(variables.map((v) => v.name));
-  for (const variable of requiredActionsVariables) {
-    checks.push({ ok: variableNames.has(variable), label: `Actions variable exists: ${variable}` });
-  }
-  const secrets2 = await ghJson2(deps, ["secret", "list", "--repo", repo, "--json", "name"], []);
-  const secretNames = new Set(secrets2.map((s) => s.name));
-  for (const secret of requiredActionsSecrets) {
-    checks.push({ ok: secretNames.has(secret), label: `Actions secret exists: ${secret}` });
-  }
   const config = safeJson2(await contentText(deps, repo, baseBranch, ".mmi/config.json") || "", null);
   checks.push({
     ok: Boolean(config?.projectOwner && config?.projectNumber),
@@ -5170,6 +5370,26 @@ async function verifyBootstrap(repo, repoClass, deps) {
       detail: optionDetail(missing)
     });
   }
+  const declaredApis = (deps.requiredGcpApis ?? []).filter((a) => a && a.trim());
+  if (declaredApis.length > 0) {
+    const slug = (repo.includes("/") ? repo.split("/")[1] : repo).toLowerCase();
+    const gcpProject = gcpProjectForSlug(slug);
+    const enabled = deps.listEnabledGcpApis ? await deps.listEnabledGcpApis(gcpProject) : null;
+    if (enabled == null) {
+      checks.push({
+        ok: false,
+        label: `required GCP APIs enabled in ${gcpProject}`,
+        detail: `could not list enabled APIs (gcloud unavailable, not authed, or no project ${gcpProject})`
+      });
+    } else {
+      const missing = findMissingGcpApis(declaredApis, enabled);
+      checks.push({
+        ok: missing.length === 0,
+        label: `required GCP APIs enabled in ${gcpProject}`,
+        detail: missing.length ? `disabled: ${missing.join(", ")}` : void 0
+      });
+    }
+  }
   const waived = applyWaivers(checks, config?.verifyWaivers ?? []);
   return { ok: waived.every((c) => c.ok || c.waived), repo, class: repoClass, baseBranch, checks: waived };
 }
@@ -5373,8 +5593,8 @@ function resolveKbSource(rawBase) {
   return { owner: m[1], repo: m[2], ref: m[3] };
 }
 function buildKbGetArgs(src, path) {
-  const clean = path.replace(/^\/+/, "");
-  return ["api", `repos/${src.owner}/${src.repo}/contents/${clean}?ref=${src.ref}`, "-H", "Accept: application/vnd.github.raw"];
+  const clean2 = path.replace(/^\/+/, "");
+  return ["api", `repos/${src.owner}/${src.repo}/contents/${clean2}?ref=${src.ref}`, "-H", "Accept: application/vnd.github.raw"];
 }
 function buildKbTreeArgs(src) {
   return ["api", `repos/${src.owner}/${src.repo}/git/trees/${src.ref}?recursive=1`];
@@ -5686,6 +5906,46 @@ async function secretsList(deps, opts) {
   const { secrets: secrets2 } = await res.json();
   deps.log(formatSecretList(secrets2 ?? []));
 }
+var DEFAULT_RUNTIME_SECRET_NAMES = ["GOOGLE_CLIENT_ID", "GOOGLE_CLIENT_SECRET"];
+function stringList(v) {
+  return Array.isArray(v) ? v.filter((x) => typeof x === "string" && isValidSecretKey(x)) : [];
+}
+function requiredRuntimeSecretNames(stage2, contract) {
+  const extra = Array.isArray(contract) ? stringList(contract) : stringList(contract?.[stage2]);
+  return [.../* @__PURE__ */ new Set([...DEFAULT_RUNTIME_SECRET_NAMES, ...extra])];
+}
+function stageKey(stage2, key) {
+  return key.includes("/") ? key : `${stage2}/${key}`;
+}
+async function secretsPreflight(deps, opts) {
+  const repo = await targetRepo(deps, opts);
+  const qs = new URLSearchParams({ repo }).toString();
+  let res;
+  try {
+    res = await deps.fetch(`${deps.apiUrl}/secrets/list?${qs}`, {
+      method: "GET",
+      headers: await deps.headers(),
+      signal: AbortSignal.timeout(TIMEOUT_MS2)
+    });
+  } catch (e) {
+    deps.err(`secrets preflight: ${e.message}`);
+    return false;
+  }
+  if (!res.ok) {
+    deps.err(`secrets preflight failed: HTTP ${res.status}${await readErr(res)}`);
+    return false;
+  }
+  const { secrets: secrets2 } = await res.json();
+  const present = new Set((secrets2 ?? []).map((s) => s.key));
+  const required = opts.required.map((key) => stageKey(opts.stage, key));
+  const missing = required.filter((key) => !present.has(key));
+  if (missing.length) {
+    deps.log(`missing ${missing.join(", ")}`);
+    return false;
+  }
+  deps.log(`all required ${opts.stage} secret names are present`);
+  return true;
+}
 async function secretsGet(deps, key, opts) {
   if (!isValidSecretKey(key)) return deps.err(`invalid secret key ${JSON.stringify(key)}`);
   const repo = await targetRepo(deps, opts);
@@ -6272,6 +6532,15 @@ async function probeBackend(url) {
     return false;
   }
 }
+async function probeSagaAccess(url, key) {
+  try {
+    const qs = new URLSearchParams(key).toString();
+    const res = await fetch(`${url}/saga/state?${qs}`, { headers: await sagaHeaders(), signal: AbortSignal.timeout(8e3) });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
 saga.command("health").option("--json", "machine-readable output").option("--banner", "one-line SessionStart banner; silent when healthy").option("--quiet", "suppress detail output").description("zero-write health check: auth, backend reachability, resolved key").action(async (o) => {
   const cfg = await loadConfig();
   const session = resolveSessionId();
@@ -6279,7 +6548,8 @@ saga.command("health").option("--json", "machine-readable output").option("--ban
   const source = session.source;
   const identity = await githubLogin();
   const reachable = cfg.sagaApiUrl ? await probeBackend(cfg.sagaApiUrl) : false;
-  const report = buildHealth({ key, source, identity, reachable, sagaApiUrl: cfg.sagaApiUrl });
+  const authorized = cfg.sagaApiUrl && reachable ? await probeSagaAccess(cfg.sagaApiUrl, key) : void 0;
+  const report = buildHealth({ key, source, identity, reachable, authorized, sagaApiUrl: cfg.sagaApiUrl });
   if (o.json) return console.log(JSON.stringify(report));
   if (o.banner) {
     const banner = healthBanner(report);
@@ -6516,6 +6786,22 @@ async function withSecrets(run) {
 var secrets = program2.command("secrets").description("two-tier project secrets \u2014 self-serve your repo dev/* tier; org tier is master-gated");
 secrets.command("where").description("print where this repo\u2019s secrets live \u2014 the two-tier vault layout + well-known keys (no values)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action((o) => withSecrets((d) => secretsWhere(d, o)));
 secrets.command("list").description("list secret NAMES + tier for this repo (never values)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action((o) => withSecrets((d) => secretsList(d, o)));
+secrets.command("preflight").description("check required stage secret names for a deploy/train without reading values").requiredOption("--stage <dev|rc|main>", "stage to check").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--required <KEY...>", "required keys; bare keys are scoped under --stage").action(async (o) => {
+  if (!["dev", "rc", "main"].includes(o.stage)) {
+    return fail("secrets preflight: --stage must be dev, rc, or main");
+  }
+  const cfg = await loadConfig();
+  if (!cfg.sagaApiUrl) {
+    fail("secrets: sagaApiUrl not configured in .mmi/config.json (this repo is not bootstrapped)");
+    return;
+  }
+  const d = makeSecretsDeps(cfg);
+  const repo = o.repo ?? `mutmutco/${await d.slug()}`;
+  const meta = await fetchProjectBySlug(slugOf(repo), registryClientDeps(cfg));
+  const required = o.required?.length ? o.required : requiredRuntimeSecretNames(o.stage, meta?.requiredRuntimeSecrets);
+  const ok = await secretsPreflight(d, { repo: o.repo, stage: o.stage, required });
+  if (!ok) process.exitCode = 1;
+});
 secrets.command("get <key>").description("print one secret value over TLS (prints once, raw \u2014 do not log/paste it)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action((key, o) => withSecrets((d) => secretsGet(d, key, o)));
 secrets.command("set <key>").description("write/rotate a secret; value is read from stdin (never an argument)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action((key, o) => withSecrets((d) => secretsSet(d, key, o)));
 secrets.command("edit <key>").description("alias for set \u2014 replace a secret value (read from stdin)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action((key, o) => withSecrets((d) => secretsEdit(d, key, o)));
@@ -6548,7 +6834,7 @@ project.command("list").description("list all projects (identity + board, never
     return;
   }
   for (const p of projects) {
-    console.log(`${p.slug ?? "?"} - ${p.name ?? ""}${p.division ? ` [${p.division}]` : ""}${p.class ? ` (${p.class})` : ""}`);
+    console.log(`${p.slug ?? "?"} - ${p.name ?? ""}${p.division ? ` [${p.division}]` : ""}${p.class ? ` (${p.class})` : ""}${p.deployModel ? ` {${p.deployModel}}` : ""}`);
   }
 });
 project.command("get <owner/repo>").description("a project's META (board ids + pointers) by repo or slug \u2014 identity, NOT deploy coords").option("--json", "machine-readable output").action(async (repoOrSlug, o) => {
@@ -6566,7 +6852,7 @@ project.command("resolve <owner/repo>").description("deploy coords for a stage \
   }
   fail(msg);
 });
-project.command("set <owner/repo>").description("MASTER-ONLY: upsert a project META (idempotent merge; no clobber of unspecified fields)").option("--class <class>", "deployable | content").option("--var <KEY=VALUE...>", "META field to set (repeatable): name, division, projectId, branch, wikiRepo, vaultPath, kbPointer").option("--json", "machine-readable output").action(async (repoOrSlug, o) => {
+project.command("set <owner/repo>").description("MASTER-ONLY: upsert a project META (idempotent merge; no clobber of unspecified fields)").option("--class <class>", "deployable | content").option("--deploy-model <model>", "hub-serverless | serverless | tenant-container | content (release-train deploy path, #514)").option("--var <KEY=VALUE...>", "META field to set (repeatable): name, division, projectId, branch, wikiRepo, vaultPath, kbPointer").option("--json", "machine-readable output").action(async (repoOrSlug, o) => {
   const cfg = await loadConfig();
   const slug = slugOf(repoOrSlug);
   const patch = {};
@@ -6574,6 +6860,11 @@ project.command("set <owner/repo>").description("MASTER-ONLY: upsert a project M
     if (o.class !== "deployable" && o.class !== "content") return fail("project set: --class must be deployable or content");
     patch.class = o.class;
   }
+  if (o.deployModel) {
+    const models = ["hub-serverless", "serverless", "tenant-container", "content"];
+    if (!models.includes(o.deployModel)) return fail(`project set: --deploy-model must be one of: ${models.join(", ")}`);
+    patch.deployModel = o.deployModel;
+  }
   for (let i = 0; i < process.argv.length - 1; i++) {
     if (process.argv[i] === "--var") {
       const eq = process.argv[i + 1].indexOf("=");
@@ -6660,8 +6951,10 @@ oauth.command("verify").description("probe Google authorize with an arbitrary po
 var issue = program2.command("issue").description("issues \u2014 reliable create with structured output");
 issue.command("create").description("create an issue (type \u2192 label) and print {number,url,label} JSON").requiredOption("--type <type>", "bug | feature | task (sets the matching label)").requiredOption("--title <title>", "issue title").requiredOption("--body <body>", "issue body (markdown)").requiredOption("--priority <priority>", "urgent | high | medium | low (label + board Priority field when configured)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--label <label...>", "extra label(s) to attach (repeatable; auto-created if missing)").option("--no-related", "skip the auto related-issues comment").action(async (o) => {
   let args;
+  let priority;
   try {
-    args = buildIssueArgs({ type: o.type, title: o.title, body: o.body, priority: o.priority, repo: o.repo, labels: o.label });
+    priority = normalizePriority(o.priority);
+    args = buildIssueArgs({ type: o.type, title: o.title, body: o.body, priority, repo: o.repo, labels: o.label });
   } catch (e) {
     return fail(`issue create: ${e.message}`);
   }
@@ -6674,9 +6967,9 @@ issue.command("create").description("create an issue (type \u2192 label) and pri
     }
   }
   const created = await ghCreate(args);
-  const projectItemId = await attachToProject(created.number, o.repo, o.priority);
+  const projectItemId = await attachToProject(created.number, o.repo, priority);
   if (o.related !== false) scheduleRelatedDiscovery({ repo: o.repo, number: created.number, title: o.title, body: o.body });
-  console.log(JSON.stringify({ ...created, label: o.type, priority: o.priority, projectItemId }));
+  console.log(JSON.stringify({ ...created, label: o.type, priority, projectItemId }));
 });
 issue.command("discover-related").description("find related issues for an existing issue and post only high-confidence links").requiredOption("--number <number>", "created issue number").requiredOption("--title <title>", "created issue title").requiredOption("--body <body>", "created issue body").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--json", "print candidates instead of posting").action(async (o) => {
   const number = Number(o.number);
@@ -6918,13 +7211,25 @@ stage.command("run").description("force-stop previous stage, build, start, and h
   }
 });
 program2.command("stage-live").description("explain that remote rc/live environments use /rcand, /release, and /hotfix; /stage is local only").option("--json", "machine-readable output").option("--apply", "always refused; there is no stage-live mutation path").action((o) => {
-  if (o.apply) return fail("stage-live: not an org command; use mmi-cli stage for local tests, or the gated rc/release/hotfix train for remote environments");
+  if (o.apply) return fail("stage-live: not an org command; use mmi-cli stage for local tests, or the gated rcand/release/hotfix train for remote environments");
   const steps = stageLivePlan();
   console.log(o.json ? JSON.stringify({ command: "stage-live", steps }, null, 2) : renderSteps("mmi-cli stage-live: not an org command", steps));
 });
-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 === "rc" ? "rcand" : commandName} skill`);
+for (const commandName of ["rcand", "release", "hotfix"]) {
+  program2.command(commandName).description(`plan ${commandName} train operations; mutations require explicit master-admin approval`).option("--json", "machine-readable output").option("--apply", commandName === "hotfix" ? "reserved; hotfix uses the /hotfix skill PR path" : "execute the guarded master-only train after explicit approval").action(async (o) => {
+    if (o.apply) {
+      if (commandName === "hotfix") return fail("hotfix: CLI apply is reserved; use the /hotfix skill PR path after explicit master-admin approval");
+      try {
+        const result = await runTrainApply(commandName, {
+          run: async (file, args) => (await execFileP3(file, args, { timeout: file === "gh" ? 3e4 : GIT_TIMEOUT_MS })).stdout,
+          runSelf: async (args) => (await execFileP3(process.execPath, [process.argv[1], ...args], { timeout: 3e4 })).stdout
+        });
+        const message = `mmi-cli ${commandName}: applied ${result.repo} ${result.stage} train at ${result.tag} [${result.deployModel}]; ${result.dispatch}`;
+        return printLine(o.json ? JSON.stringify(result, null, 2) : message);
+      } catch (e) {
+        return fail(`${commandName}: ${e.message}`);
+      }
+    }
     const steps = trainPlan(commandName);
     console.log(o.json ? JSON.stringify({ command: commandName, steps }, null, 2) : renderSteps(`mmi-cli ${commandName}: dry-run plan`, steps));
   });
@@ -6941,9 +7246,31 @@ bootstrap.command("verify <repo>").description("audit whether an existing repo i
   if (o.class !== "deployable" && o.class !== "content") return fail("bootstrap verify: --class must be deployable or content");
   const cfg = await loadConfig();
   const apiProjects = await fetchProjectsJson({ baseUrl: cfg.sagaApiUrl, token: githubToken });
+  const slug = (repo.includes("/") ? repo.split("/")[1] : repo).toLowerCase();
+  const meta = await fetchProjectBySlug(slug, { baseUrl: cfg.sagaApiUrl, token: githubToken });
   const report = await verifyBootstrap(repo, o.class, {
     gh: async (args) => execFileP3("gh", args, { timeout: 2e4 }),
-    readLocalFile: (path) => path === "projects.json" && apiProjects != null ? apiProjects : (0, import_node_fs4.existsSync)(path) ? (0, import_node_fs4.readFileSync)(path, "utf8") : null
+    readLocalFile: (path) => path === "projects.json" && apiProjects != null ? apiProjects : (0, import_node_fs4.existsSync)(path) ? (0, import_node_fs4.readFileSync)(path, "utf8") : null,
+    // requiredGcpApis is stored as an array by a JSON write, but `project set --var KEY=VALUE` stores a raw
+    // comma-string — accept either so the seeded value verifies regardless of how it was written.
+    requiredGcpApis: (() => {
+      const v = meta?.requiredGcpApis;
+      if (Array.isArray(v)) return v;
+      if (typeof v === "string") return v.split(",").map((s) => s.trim()).filter(Boolean);
+      return void 0;
+    })(),
+    listEnabledGcpApis: async (gcpProject) => {
+      try {
+        const { stdout } = await execFileP3(
+          "gcloud",
+          ["services", "list", "--enabled", "--project", gcpProject, "--format", "value(config.name)"],
+          { timeout: 3e4 }
+        );
+        return stdout.split("\n").map((l) => l.trim()).filter(Boolean);
+      } catch {
+        return null;
+      }
+    }
   });
   console.log(o.json ? JSON.stringify(report, null, 2) : renderBootstrapVerifyReport(report));
   if (!report.ok) process.exitCode = 1;
@@ -7100,6 +7427,21 @@ function writeProjectInstallRecord(record) {
     return false;
   }
 }
+function backupAndWriteInstalledPlugins(records, pluginId) {
+  try {
+    const file = readInstalledPlugins();
+    if (!file) return false;
+    if (!file.plugins) file.plugins = {};
+    const path = installedPluginsPath();
+    (0, import_node_fs4.copyFileSync)(path, `${path}.bak`);
+    file.plugins[pluginId] = records;
+    (0, import_node_fs4.writeFileSync)(path, `${JSON.stringify(file, null, 2)}
+`, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
 var gitignorePath = () => (0, import_node_path4.join)(process.cwd(), ".gitignore");
 function readGitignore() {
   try {
@@ -7116,7 +7458,12 @@ function writeGitignore(content) {
     return false;
   }
 }
-program2.command("doctor").description("check onboarding gates (GitHub auth, mmi-cli on PATH, repo config, plugin git clone, plugin install record, .gitignore managed block) and print fixes").option("--banner", "one-line resume summary; silent when all gates pass").option("--json", "machine-readable output").action(async (opts) => {
+program2.command("doctor").description("check onboarding gates (GitHub auth, mmi-cli on PATH, repo config, plugin git clone, plugin install record, .gitignore managed block, plugin config drift) and print fixes").option("--banner", "one-line resume summary; silent when all gates pass").option("--guide", "print the MMI Agentic Onboarding guide URL").option("--json", "machine-readable output").action(async (opts) => {
+  if (opts.guide) {
+    if (opts.json) console.log(JSON.stringify({ resources: [MMI_AGENTIC_ONBOARDING_GUIDE] }, null, 2));
+    else console.log(MMI_AGENTIC_ONBOARDING_GUIDE.url);
+    return;
+  }
   const checks = [];
   const login = await githubLogin();
   let ghInstalled = true;
@@ -7189,17 +7536,27 @@ program2.command("doctor").description("check onboarding gates (GitHub auth, mmi
     }
   }
   checks.push(gitignoreCheck);
+  let driftCheck = buildPluginConfigDriftCheck({ isOrgRepo: Boolean(cfg.sagaApiUrl), installed });
+  if (!driftCheck.ok && driftCheck.recordsToWrite && !opts.json) {
+    if (backupAndWriteInstalledPlugins(driftCheck.recordsToWrite, driftCheck.pluginId)) {
+      driftCheck = { ...driftCheck, ok: true };
+      if (!opts.banner) console.error("  \u21BB repaired: collapsed mmi@mmi to one user-scope entry (backup at installed_plugins.json.bak) \u2014 run /reload-plugins");
+    }
+  }
+  checks.push(driftCheck);
   const gaps = checks.filter((c) => !c.ok);
+  const resources = doctorResourcesForGaps(gaps);
   if (opts.json) {
-    console.log(JSON.stringify({ ok: gaps.length === 0, checks }, null, 2));
+    console.log(JSON.stringify({ ok: gaps.length === 0, checks, ...resources.length ? { resources } : {} }, null, 2));
     return;
   }
   if (opts.banner) {
-    if (gaps.length) console.log(`\u26A0 MMI setup needed \u2014 ${gaps.map((g) => g.fix).join(" \xB7 ")}`);
+    if (gaps.length) console.log(`\u26A0 MMI setup needed \u2014 ${gaps.map((g) => g.fix).join(" \xB7 ")} \xB7 guide: ${MMI_AGENTIC_ONBOARDING_GUIDE.url}`);
     return;
   }
   for (const c of checks) console.log(c.ok ? `\u2713 ${c.label}` : `\u2717 ${c.label}
    \u2192 ${c.fix}`);
+  for (const r of resources) console.log(`Resource: ${r.label} \u2014 ${r.url}`);
   console.log(gaps.length ? `
 ${gaps.length} item(s) need attention.` : "\nAll set \u2014 you are ready.");
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/cli",
-  "version": "2.0.0",
+  "version": "2.3.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",