@mutmutco/cli 4.4.5 → 4.4.6

package/dist/main.cjs

@@ -7288,37 +7288,71 @@ function pathWords(text) {
 function proseWords(text) {
   return text.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
 }
+function countWords(words) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const w of words) counts.set(w, (counts.get(w) ?? 0) + 1);
+  return counts;
+}
+var TITLE_WEIGHT = 3;
+var PATH_WEIGHT = 4;
+var BODY_WEIGHT = 1;
 function inferSurface(candidates, context = {}) {
   const sorted = [...candidates].sort();
   if (sorted.length === 0) throw new Error("inferSurface: no surface:* candidates to choose from");
-  const pWords = new Set(pathWords(context.body ?? ""));
-  const tWords = /* @__PURE__ */ new Set([...proseWords(context.title ?? ""), ...proseWords(context.body ?? "")]);
+  const titleCounts = countWords(proseWords([context.title ?? "", context.type ?? ""].join(" ")));
+  const pathCounts = countWords(pathWords(context.body ?? ""));
+  const bodyCounts = countWords(proseWords(context.body ?? ""));
+  const scoreOf = (label) => {
+    let score = 0;
+    let fromPath = false;
+    let fromTitle = false;
+    for (const word of surfaceWords(label)) {
+      const title = titleCounts.get(word) ?? 0;
+      const path2 = pathCounts.get(word) ?? 0;
+      const body = bodyCounts.get(word) ?? 0;
+      if (title > 0) fromTitle = true;
+      if (path2 > 0) fromPath = true;
+      score += title * TITLE_WEIGHT + path2 * PATH_WEIGHT + body * BODY_WEIGHT;
+    }
+    return { score, fromPath, fromTitle };
+  };
   let best = sorted[0];
   let bestScore = 0;
   let bestFromPath = false;
+  let bestFromTitle = false;
+  const scores = /* @__PURE__ */ new Map();
   for (const label of sorted) {
-    const words = surfaceWords(label);
-    if (!words.length) continue;
-    const pathHits = words.filter((w) => pWords.has(w)).length;
-    const proseHits = words.filter((w) => tWords.has(w)).length;
-    const score = pathHits * 2 + proseHits;
+    const { score, fromPath, fromTitle } = scoreOf(label);
+    scores.set(label, score);
     if (score > bestScore) {
       bestScore = score;
       best = label;
-      bestFromPath = pathHits > 0;
+      bestFromPath = fromPath;
+      bestFromTitle = fromTitle;
     }
   }
-  if (bestScore === 0) {
-    return {
-      label: sorted[0],
-      reason: `no path or title/body word matched any of ${sorted.length} surface label(s) \u2014 defaulted to the alphabetically-first`
-    };
-  }
+  const tied = sorted.filter((label) => (scores.get(label) ?? 0) === bestScore);
+  const uncertain = bestScore === 0 || bestScore < TITLE_WEIGHT || tied.length > 1;
+  const alternatives = uncertain ? sorted.filter((label) => label !== best && (scores.get(label) ?? 0) > 0).sort((a, b) => (scores.get(b) ?? 0) - (scores.get(a) ?? 0) || (a < b ? -1 : a > b ? 1 : 0)).slice(0, 3) : [];
+  const reason = bestScore === 0 ? `no path or title/body word matched any of ${sorted.length} surface label(s) \u2014 defaulted to the alphabetically-first` : bestFromPath ? "matched a path mentioned in the issue body" : bestFromTitle ? "matched a word in the issue title/body" : "matched a word in the issue body";
   return {
     label: best,
-    reason: bestFromPath ? "matched a path mentioned in the issue body" : "matched a word in the issue title/body"
+    reason,
+    ...uncertain ? { uncertain: true } : {},
+    ...alternatives.length ? { alternatives } : {}
   };
 }
+function surfaceInferenceSuffix(inferred) {
+  if (!inferred.uncertain) return "";
+  const alts = inferred.alternatives?.length ? ` Other candidates: ${inferred.alternatives.join(", ")}.` : "";
+  return ` This pick is low-confidence \u2014 pass --surface <value> to choose explicitly.${alts}`;
+}
+function surfaceInferenceNote(inferred) {
+  const base = `mmi-cli: no --surface given \u2014 filed under ${inferred.label} (${inferred.reason}).`;
+  return inferred.uncertain ? `${base}${surfaceInferenceSuffix(inferred)}
+` : `${base} Pass --surface to choose.
+`;
+}
 async function checkSurfaceRequirement(input, deps = {}) {
   if (input.waiver) {
     const reason = input.waiver.reason.trim();
@@ -7350,7 +7384,7 @@ async function checkSurfaceRequirement(input, deps = {}) {
   }
   if (known.length === 0) return { enforcing: false, taxonomyAbsent: true };
   if (labelsCarrySurface(input.labels)) return { enforcing: true };
-  return { enforcing: true, inferred: inferSurface(known, { title: input.title, body: input.body }) };
+  return { enforcing: true, inferred: inferSurface(known, { title: input.title, type: input.type, body: input.body }) };
 }
 function conflictingSurfaceInputs(surfaceFlag, labels) {
   if (!surfaceFlag) return void 0;
@@ -15870,10 +15904,10 @@ var rollout_plan_default = {
     note: "The v4.0.0 stamp happens at cut time (D6e #4463); until then the candidate is the origin/development head artifacts (built cli/dist + npm pack), identity proven by dist content hash (D6a)."
   },
   baseline: {
-    version: "4.4.5",
-    tag: "v4.4.5",
-    commit: "202cb38f947b",
-    npm: "@mutmutco/cli@4.4.5"
+    version: "4.4.6",
+    tag: "v4.4.6",
+    commit: "640e312fac88",
+    npm: "@mutmutco/cli@4.4.6"
   },
   exitCriterion: "fleet-n-of-n",
   hubOnlyShortcut: "forbidden",
@@ -15890,14 +15924,14 @@ var rollout_plan_default = {
           repo: "mutmutco/mmi-hub",
           role: "canary",
           schedule: "train",
-          v3Target: "v4.4.5"
+          v3Target: "v4.4.6"
         }
       ],
       rollbackTrigger: "Any red inside the post-contract soak window: `devops train gate` FAIL attributable to the v4 doors, Hub endpoint health probe failure, a pre-v4 client admitted instead of receiving actionable HTTP 426, or npm consumer install/doctor failure on the v4-only dist.",
       rollback: {
         independent: true,
-        mechanism: "npm dist-tag latest -> 4.4.5 and redeploy the Hub Lambda from tag v4.4.5 (202cb38f947b); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
-        v3Target: "v4.4.5 (@mutmutco/cli@4.4.5, tag commit 202cb38f947b \u2014 last known-good release carrying the repo-index v4-only contract)"
+        mechanism: "npm dist-tag latest -> 4.4.6 and redeploy the Hub Lambda from tag v4.4.6 (640e312fac88); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
+        v3Target: "v4.4.6 (@mutmutco/cli@4.4.6, tag commit 640e312fac88 \u2014 last known-good release carrying the repo-index v4-only contract)"
       }
     },
     {
@@ -22814,6 +22848,62 @@ async function waitForFoldIndexLock(deps, startBranch, resumeCommand) {
     await sleep2(Math.min(GIT_INDEX_LOCK_POLL_MS, Math.max(1, deadline - now())));
   }
 }
+function isIndexLockFailure(message2) {
+  return /index\.lock/i.test(message2) && /File exists/i.test(message2);
+}
+async function clearFoldChildIndexLock(deps) {
+  const lockPath = requireValue(
+    clean2(await deps.run("git", ["rev-parse", "--git-path", "index.lock"])),
+    "git index lock path"
+  );
+  try {
+    await (0, import_promises3.unlink)(lockPath);
+  } catch (e) {
+    if (e.code === "ENOENT") return void 0;
+    throw e;
+  }
+  return lockPath;
+}
+async function resetFoldMainWithStaleLockRetry(deps, preFoldMainSha, killedCause) {
+  try {
+    await deps.run("git", ["reset", "--hard", preFoldMainSha]);
+    return { ok: true, lockNote: "" };
+  } catch (firstError) {
+    const firstMessage = firstError instanceof Error ? firstError.message : String(firstError);
+    if (!isIndexLockFailure(firstMessage)) return { ok: false, error: firstError, lockNote: "" };
+    if (!foldChildWasKilled(killedCause)) {
+      return {
+        ok: false,
+        error: firstError,
+        lockNote: "the git index lock was NOT removed \u2014 no killed fold child is attributable, so its holder may still be alive (resolve or wait it out, then retry)"
+      };
+    }
+    let clearedLockPath;
+    try {
+      clearedLockPath = await clearFoldChildIndexLock(deps);
+    } catch (e) {
+      return {
+        ok: false,
+        error: firstError,
+        lockNote: `the fold child's stale git index lock could not be removed: ${e instanceof Error ? e.message : String(e)}`
+      };
+    }
+    if (!clearedLockPath) return { ok: false, error: firstError, lockNote: "" };
+    try {
+      await deps.run("git", ["reset", "--hard", preFoldMainSha]);
+      return {
+        ok: true,
+        lockNote: `removed the stale git index lock ${clearedLockPath} left by the fold child the train killed (signal), then retried the reset`
+      };
+    } catch (retryError) {
+      return {
+        ok: false,
+        error: retryError,
+        lockNote: `removed the stale git index lock ${clearedLockPath} left by the fold child the train killed (signal) and retried the reset once, which failed again`
+      };
+    }
+  }
+}
 async function recoverFailedRcand(deps, cause, preRcSha) {
   const causeMessage = cause instanceof Error ? cause.message : String(cause);
   const branch = await currentBranch(deps).catch(() => "");
@@ -22857,10 +22947,13 @@ Recovery sequence:
   3. mmi-cli devops rcand --apply`
   );
 }
+function foldChildWasKilled(causeMessage) {
+  return /\bSIGTERM\b|was killed \(signal/.test(causeMessage);
+}
 function foldFailureAnchor(causeMessage) {
-  if (/\bSIGTERM\b|was killed \(signal/.test(causeMessage)) return "docs/Guides/train-troubleshooting.md#fold-npm-ci-sigterm";
-  if (/\bEPERM\b|\bEBUSY\b/.test(causeMessage)) return "docs/Guides/train-troubleshooting.md#fold-eperm-ebusy";
-  if (/^(?:npm|node) .* failed\b/.test(causeMessage)) return "docs/Guides/train-troubleshooting.md#fold-lifecycle-script";
+  if (foldChildWasKilled(causeMessage)) return troubleshootingAnchor("fold-npm-ci-sigterm");
+  if (/\bEPERM\b|\bEBUSY\b/.test(causeMessage)) return troubleshootingAnchor("fold-eperm-ebusy");
+  if (/^(?:npm|node) .* failed\b/.test(causeMessage)) return troubleshootingAnchor("fold-lifecycle-script");
   return void 0;
 }
 async function recoverFailedFold(deps, cause, startBranch, preFoldMainSha, resumeCommand) {
@@ -22889,13 +22982,12 @@ fold failed with an in-progress merge; automatic \`git merge --abort\` failed: $
   if (probe.branch === "main" && preFoldMainSha) {
     const mainDescendsFromPreFold = await deps.run("git", ["merge-base", "--is-ancestor", preFoldMainSha, "main"]).then(() => true).catch(() => false);
     if (mainDescendsFromPreFold) {
-      try {
-        await deps.run("git", ["reset", "--hard", preFoldMainSha]);
-      } catch (e) {
+      const attempt = await resetFoldMainWithStaleLockRetry(deps, preFoldMainSha, rawCause);
+      if (!attempt.ok) {
         return foldFailureGuidance(
           `${causeMessage}
 
-fold failed after this run's merge/fold committed locally on main; automatic \`git reset --hard ${shaLabel(preFoldMainSha)}\` failed: ${e instanceof Error ? e.message : String(e)}.`,
+fold failed after this run's merge/fold committed locally on main; automatic \`git reset --hard ${shaLabel(preFoldMainSha)}\` failed: ${attempt.error instanceof Error ? attempt.error.message : String(attempt.error)}${attempt.lockNote ? `; ${attempt.lockNote}` : ""}.`,
           await probeFoldFailureState(deps),
           startBranch,
           preFoldMainSha,
@@ -22910,7 +23002,7 @@ fold failed after this run's merge/fold committed locally on main; automatic \`g
         startBranch,
         preFoldMainSha,
         resumeCommand,
-        `local main was reset to its pre-fold state ${shaLabel(preFoldMainSha)} (discarding only this run's merge/fold commit(s) at ${shaLabel(probe.mainSha)})${aheadNote}`
+        `local main was reset to its pre-fold state ${shaLabel(preFoldMainSha)} (discarding only this run's merge/fold commit(s) at ${shaLabel(probe.mainSha)})${attempt.lockNote ? `; ${attempt.lockNote}` : ""}${aheadNote}`
       );
     }
   }
@@ -33529,10 +33621,10 @@ function formatOwnDetail(cmd) {
     }
     lines2.push("");
   }
-  const ownOptions = cmd.options.filter((opt) => opt.flags !== "--help" && opt.flags !== "-V, --version");
-  if (ownOptions.length) {
+  const ownOptions2 = cmd.options.filter((opt) => opt.flags !== "--help" && opt.flags !== "-V, --version");
+  if (ownOptions2.length) {
     lines2.push("Options:");
-    for (const opt of ownOptions) {
+    for (const opt of ownOptions2) {
       const tags = [];
       if (opt.mandatory) tags.push("required");
       if (opt.default !== void 0) tags.push(`default: ${JSON.stringify(opt.default)}`);
@@ -33594,6 +33686,56 @@ function formatExplainLoop(playbook) {
   }
   return lines2.join("\n");
 }
+function ownOptions(cmd) {
+  return cmd.options.filter((opt) => opt.flags !== "--help" && opt.flags !== "-V, --version");
+}
+function briefCommand(cmd) {
+  return {
+    path: cmd.path,
+    ...cmd.description ? { description: cmd.description } : {},
+    arguments: cmd.arguments.map((arg) => ({
+      name: arg.name,
+      required: arg.required,
+      ...arg.variadic ? { variadic: true } : {},
+      ...arg.description ? { description: arg.description } : {}
+    })),
+    options: ownOptions(cmd).map((opt) => ({
+      flags: opt.flags,
+      takesValue: opt.takesValue,
+      ...opt.mandatory ? { required: true } : {},
+      ...opt.description ? { description: opt.description } : {}
+    }))
+  };
+}
+function explainBriefManifest(manifest, command) {
+  return {
+    schema_version: 1,
+    scope: "command",
+    brief: true,
+    name: manifest.name,
+    ...manifest.version ? { version: manifest.version } : {},
+    command: briefCommand(command),
+    ...command.subcommands.length ? { children: command.subcommands.map(briefCommand) } : {}
+  };
+}
+function formatExplainBrief(cmd, rootName) {
+  const lines2 = [`${rootName} ${cmd.path}${cmd.description ? ` \u2014 ${cmd.description}` : ""}`];
+  for (const arg of cmd.arguments) {
+    const flag = arg.required ? `<${arg.name}>` : `[${arg.name}]`;
+    lines2.push(`  ${flag}  ${arg.required ? "required" : "optional"}${arg.description ? `  ${arg.description}` : ""}`);
+  }
+  for (const opt of ownOptions(cmd)) {
+    lines2.push(`  ${opt.flags}  ${opt.takesValue ? "takes-value" : "flag"}${opt.mandatory ? " required" : ""}${opt.description ? `  ${opt.description}` : ""}`);
+  }
+  for (const child2 of cmd.subcommands) {
+    const args = child2.arguments.map((arg) => arg.required ? `<${arg.name}>` : `[${arg.name}]`).join(" ");
+    lines2.push(`${child2.path}${args ? ` ${args}` : ""}${child2.description ? ` \u2014 ${child2.description}` : ""}`);
+    for (const opt of ownOptions(child2)) {
+      lines2.push(`  ${opt.flags}  ${opt.takesValue ? "takes-value" : "flag"}${opt.mandatory ? " required" : ""}${opt.description ? `  ${opt.description}` : ""}`);
+    }
+  }
+  return lines2.join("\n");
+}
 function catalogCommandPaths(manifest) {
   const acc = [];
   const walk2 = (command) => {
@@ -33728,7 +33870,7 @@ function findCommandInManifest(manifest, commandPath3) {
   return visit(manifest.tree);
 }
 function registerExplainCommand(program3) {
-  program3.command("explain").description("print a command's purpose, flags, and examples from the live schema \u2014 one grounding call replaces trial-and-error").argument("[command...]", 'the command path to explain (e.g. "issue create")').addOption(new Option("--loop <name>", "print the canonical command sequence: agent | start-work | ship-pr | hotfix").choices(Object.keys(LOOP_PLAYBOOKS))).option("--json", "machine-readable focused command, route, or loop detail").option("--out <path>", "write the output to a UTF-8 file instead of stdout (#5802 byte contract)").option("--recursive", "include full schemas for immediate children (default: compact child index)").option("--full", "alias for --recursive").action((commandArgs, opts) => {
+  program3.command("explain").description("print a command's purpose, flags, and examples from the live schema \u2014 one grounding call replaces trial-and-error").argument("[command...]", 'the command path to explain (e.g. "issue create")').addOption(new Option("--loop <name>", "print the canonical command sequence: agent | start-work | ship-pr | hotfix").choices(Object.keys(LOOP_PLAYBOOKS))).option("--json", "machine-readable focused command, route, or loop detail").option("--brief", "compact per-verb flags, value requirements, and one-line descriptions (no schemas or prose)").option("--out <path>", "write the output to a UTF-8 file instead of stdout (#5802 byte contract)").option("--recursive", "include full schemas for immediate children (default: compact child index)").option("--full", "alias for --recursive").action((commandArgs, opts) => {
     const emit = (output) => {
       if (!opts.out) console.log(output);
       else console.log(`Wrote explain output to ${opts.out} (UTF-8, ${writeUtf8Receipt(opts.out, output)} bytes)`);
@@ -33767,6 +33909,10 @@ function registerExplainCommand(program3) {
       return;
     }
     const recursive = Boolean(opts.recursive || opts.full);
+    if (opts.brief) {
+      emit(opts.json ? JSON.stringify(explainBriefManifest(manifest, command), null, 2) : formatExplainBrief(command, manifest.name));
+      return;
+    }
     emit(opts.json ? JSON.stringify(explainCommandManifest(manifest, command, { recursive }), null, 2) : command.subcommands.length ? formatExplainGroup(command, manifest.name) : formatExplainCommand(command, manifest.name));
   });
 }
@@ -34438,10 +34584,10 @@ async function preflightBatchSurfaces(validated, rowRepo, options) {
       continue;
     }
     if (known.length === 0) continue;
-    const inferred = inferSurface(known, { title: spec.title, body: spec.body });
+    const inferred = inferSurface(known, { title: spec.title, type: spec.type, body: spec.body });
     spec.labels = [...spec.labels ?? [], inferred.label];
     process.stderr.write(
-      `mmi-cli: no --surface given \u2014 row ${row} filed under ${inferred.label} (${inferred.reason}). Pass --surface to choose.
+      `mmi-cli: no --surface given \u2014 row ${row} filed under ${inferred.label} (${inferred.reason}). Pass --surface to choose.${surfaceInferenceSuffix(inferred)}
 `
     );
   }
@@ -40750,6 +40896,7 @@ function registerCollaborationCommands(program3) {
           repo: planRepo,
           labels: [...planLabels, ...surface ? [surface] : []],
           title,
+          type,
           body: opts.body
         });
         if (warn) process.stderr.write(`${warn}
@@ -40757,10 +40904,7 @@ function registerCollaborationCommands(program3) {
         if (refusal) fail(refusal.message, refusal.payload);
         if (inferred && !surface) {
           planInferred = inferred;
-          process.stderr.write(
-            `mmi-cli: no --surface given \u2014 filed under ${inferred.label} (${inferred.reason}). Pass --surface to choose.
-`
-          );
+          process.stderr.write(surfaceInferenceNote(inferred));
         }
       }
       return {
@@ -40770,7 +40914,9 @@ function registerCollaborationCommands(program3) {
         priority,
         repo: opts.repo,
         ...surface ? { surface } : {},
-        ...planInferred ? { surface_inferred: true, surface: planInferred.label, surface_reason: planInferred.reason } : {}
+        ...planInferred ? { surface_inferred: true, surface: planInferred.label, surface_reason: planInferred.reason } : {},
+        ...planInferred?.uncertain ? { surface_uncertain: true } : {},
+        ...planInferred?.alternatives?.length ? { surface_alternatives: planInferred.alternatives } : {}
       };
     }
   ).action(async (o) => {
@@ -40814,7 +40960,7 @@ function registerCollaborationCommands(program3) {
       return fail(`issue create: ${e.message}`, e instanceof TextArgError ? { code: e.code, offending_flag: e.offendingFlag } : void 0);
     }
     {
-      const surfaceCheck = await checkSurfaceRequirement({ repo: targetRepo2, labels: extraLabels, title, body });
+      const surfaceCheck = await checkSurfaceRequirement({ repo: targetRepo2, labels: extraLabels, title, type: issueType, body });
       const { refusal, warn, inferred } = surfaceCheck;
       if (warn) process.stderr.write(`${warn}
 `);
@@ -40844,10 +40990,7 @@ function registerCollaborationCommands(program3) {
           labels: extraLabels.length ? extraLabels : void 0
         });
         surfaceInferred = inferred;
-        process.stderr.write(
-          `mmi-cli: no --surface given \u2014 filed under ${inferred.label} (${inferred.reason}). Pass --surface to choose.
-`
-        );
+        process.stderr.write(surfaceInferenceNote(inferred));
       }
       if (refusal && !surfaceWaived()) return fail(refusal.message, refusal.payload);
     }
@@ -40887,7 +41030,10 @@ function registerCollaborationCommands(program3) {
       } : {},
       ...parentLinkFields(parent, parentLinkError),
       // #1164: surfaced so a caller can see (and override with --surface) a pick it never asked for.
-      ...surfaceInferred ? { surface_inferred: true, surface: surfaceInferred.label, surface_reason: surfaceInferred.reason } : {}
+      ...surfaceInferred ? { surface_inferred: true, surface: surfaceInferred.label, surface_reason: surfaceInferred.reason } : {},
+      // #6818: a weak/ambiguous pick says so, with its runner-ups, so the caller can pass --surface.
+      ...surfaceInferred?.uncertain ? { surface_uncertain: true } : {},
+      ...surfaceInferred?.alternatives?.length ? { surface_alternatives: surfaceInferred.alternatives } : {}
     }));
   }), [
     'mmi-cli oracle issue create --type task --title "Wire the schema"',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/cli",
-  "version": "4.4.5",
+  "version": "4.4.6",
   "description": "MMI Future CLI — the org dev toolbox and shared cross-IDE engine for every registry-declared MMI coding surface.",
   "type": "module",
   "license": "UNLICENSED",