@mutmutco/cli 0.12.0 → 2.1.0

package/README.md

@@ -2,7 +2,9 @@
 
 The command-line engine for MMI Future org tooling. It delivers the org spine, reads and claims GitHub Project work, records saga continuity notes, and exposes the model-agnostic commands used by the MMI plugin and non-Claude agents.
 
-This package is published from [mutmutco/MMI-Hub](https://github.com/mutmutco/MMI-Hub) and its version matches the MMI Hub Claude Code and Codex plugin versions.
+This package is published from [mutmutco/MMI-Hub](https://github.com/mutmutco/MMI-Hub) and its version matches the MMI Hub Claude Code and Codex plugin versions (the release train bumps all of them in lockstep).
+
+The CLI carries the org **Hub endpoint** intrinsically (override with the `MMI_HUB_URL` env var), so a product repo needs **no committed `.mmi/config.json`** to reach the Hub — board coords, deploy coordinates, OAuth, and the secrets layout are all discovered from the Hub registry at runtime.
 
 ## Install
 
@@ -28,17 +30,20 @@ mmi-cli doctor --json
 - `mmi-cli rules sync` delivers the org-owned `AGENTS.md`, `CLAUDE.md`, and Claude settings files.
 - `mmi-cli docs sync` refreshes repo-owned `README.md` and `architecture.md` without clobbering dirty files.
 - `mmi-cli saga note`, `saga show`, `saga health`, `saga session`, `saga capture`, and `saga head-update` write and inspect session continuity.
-- `mmi-cli kb get`, `kb tree`, and `kb list` read the MM KB source.
+- `mmi-cli kb get` and `kb list` read the MM KB source (`kb list [prefix]` lists document paths, optionally under a prefix).
 - `mmi-cli northstar push|pull|list|delete|graduate` manages North Star, the per-user plan/SSOT store.
   `northstar graduate <slug> --merged-pr <url-or-number> --org-visible` marks a built-and-merged plan for
   KB curation without echoing the plan body.
   `mmi-cli plan` remains a compatibility alias.
-- `mmi-cli secrets list|get|set|edit|rm|use|grant|revoke` manages two-tier project/org secrets without logging values.
-- `mmi-cli issue create` creates typed, prioritized GitHub issues and queues related-issue discovery.
-- `mmi-cli pr create` and `pr merge` create PRs and land them with branch/worktree cleanup.
+- `mmi-cli secrets where|list|get|set|edit|rm|use|grant|revoke` manages two-tier project/org secrets without logging values; `where` prints the vault layout + well-known keys, and values move over TLS in the request body — never an argument.
+- `mmi-cli project list|get|resolve|set` reads the DDB org registry — a project's identity + board coords + deploy coordinates (`resolve` reads deploy coords, which are OIDC-gated; `set` is master-only).
+- `mmi-cli registry org` reads org-level constants from the registry (`ORG#config`).
+- `mmi-cli oauth plan|verify` prints a repo's canonical Google OAuth URI set (read from the registry) and verifies the client is port-agnostic.
+- `mmi-cli issue create` creates typed, prioritized GitHub issues (priority sets the board field, not a label) and queues related-issue discovery.
+- `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`, and `stage run` manage the local gitignored stage.
-- `mmi-cli rc`, `release`, and `hotfix` render guarded train plans.
+- `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 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

@@ -4288,23 +4288,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 }
     ];
   }
@@ -4628,6 +4634,111 @@ async function runStage(config = {}, opts = {}) {
   return { ...started, action: "run", message: `built and ${started.message}` };
 }
 
+// src/train-apply.ts
+function clean(out) {
+  return out.trim();
+}
+function requireValue(value, label) {
+  if (!value) throw new Error(`${label} could not be resolved`);
+  return value;
+}
+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) {
+  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}`
+  ]);
+}
+async function preflight(deps, ctx, stage2) {
+  await deps.runSelf(["project", "get", ctx.repo]);
+  await deps.runSelf(["secrets", "preflight", "--stage", stage2, "--repo", ctx.repo]);
+}
+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"
+    );
+    await preflight(deps, ctx, "rc");
+    await deps.run("git", ["checkout", "rc"]);
+    await deps.run("git", ["pull", "--ff-only", "origin", "rc"]);
+    await deps.run("git", ["merge", "development", "--no-edit"]);
+    const tag2 = requireValue(clean(await deps.run("node", ["scripts/next-version.mjs", "rc"])), "rc tag");
+    await deps.run("git", ["tag", tag2]);
+    await deps.run("git", ["push", "origin", "rc"]);
+    await deps.run("git", ["push", "origin", tag2]);
+    await dispatchDeploy(deps, ctx, "rc", "rc");
+    return { ...ctx, command, stage: "rc", ref: "rc", tag: tag2 };
+  }
+  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"
+  );
+  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 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]);
+  await dispatchDeploy(deps, ctx, "main", "main");
+  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 };
+}
+
 // src/port-registry.ts
 var import_node_fs3 = require("node:fs");
 var BLOCK = 100;
@@ -4906,7 +5017,7 @@ var requiredIssueTemplates = [
   ".github/ISSUE_TEMPLATE/task.yml",
   ".github/ISSUE_TEMPLATE/config.yml"
 ];
-var requiredWorkflows = [".github/workflows/pr-to-board.yml"];
+var requiredWorkflows = [];
 var requiredLabels = ["bug", "feature", "task", "priority:urgent", "priority:high", "priority:medium", "priority:low"];
 var requiredPriorityOptions = ["Urgent", "High", "Medium", "Low"];
 var strayDefaultLabels = ["documentation", "duplicate", "enhancement", "good first issue", "help wanted", "invalid", "question", "wontfix"];
@@ -5373,8 +5484,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 +5797,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);
@@ -6516,6 +6667,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)));
@@ -6918,13 +7085,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}; dispatched ${result.ref} deploy`;
+        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));
   });

package/package.json

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