@chemx/starter-kit 26.9.9-786 → 26.9.11-481

package/cli/navigator-actions.js

@@ -0,0 +1,274 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  hasGum,
+  gumChoose,
+  gumInput,
+  promptQuestion
+} from "./terminal.js";
+import {
+  formatTerminalReport,
+  generateMarkdownReport,
+  groupViolationsBySeverity,
+  formatGradeFSection,
+  formatGradeDSection,
+  formatGradeCSection,
+  formatGradeBSection,
+  formatGradeASection,
+  getAuditHistory,
+  getAuditBaseline,
+  createSnapshotFromReport,
+  formatTransformationTerminal,
+  formatHistoryTimelineTerminal,
+  buildGradeFPrompt,
+  buildGradeDPrompt,
+  buildGradeCPrompt,
+  buildGradeBPrompt,
+  buildMasterPrompt,
+  copyToClipboard
+} from "./audit.js";
+import { resolveGradeBadge } from "./navigator-grades.js";
+import { showPagedContent } from "./navigator-paged.js";
+import { showConversionMenu } from "./navigator-conversion.js";
+import { handleShareToDiscussions } from "./navigator-share.js";
+import { runInstallWizard } from "./installer.js";
+import { formatButtonTag } from "./navigator-menu.js";
+
+const isExtremeMonolith = (h) => h.lineCount >= 2000;
+const isSevereMonolith = (h) => h.lineCount >= 1000 && h.lineCount < 2000;
+const isWarningMonolith = (h) => h.lineCount >= 500 && h.lineCount < 1000;
+const isPassedPillar = (p) => p.status === "PASSED";
+const hasGradeItems = (g) => g.count > 0;
+
+export const buildActiveGrades = (report) => {
+  const { hotspots, violations, pillars } = report;
+  const { critical, high, medium, low } = groupViolationsBySeverity(violations);
+
+  const passedPillarsCount = Object.values(pillars || {}).filter(isPassedPillar).length;
+
+  const extremeMonoliths = hotspots.filter(isExtremeMonolith);
+  const severeMonoliths = hotspots.filter(isSevereMonolith);
+  const warningMonoliths = hotspots.filter(isWarningMonolith);
+
+  const gradeFCount = critical.length + extremeMonoliths.length;
+  const gradeDCount = high.length + severeMonoliths.length;
+  const gradeCCount = medium.length + warningMonoliths.length;
+  const gradeBCount = low.length;
+  const gradeACount = passedPillarsCount;
+
+  const handleGradeAAction = async () => {
+    await showPagedContent(formatGradeASection(report));
+  };
+  const handleGradeBAction = async () => {
+    await showPagedContent(formatGradeBSection(report), buildGradeBPrompt(report));
+  };
+  const handleGradeCAction = async () => {
+    await showPagedContent(formatGradeCSection(report), buildGradeCPrompt(report));
+  };
+  const handleGradeDAction = async () => {
+    await showPagedContent(formatGradeDSection(report), buildGradeDPrompt(report));
+  };
+  const handleGradeFAction = async () => {
+    await showPagedContent(formatGradeFSection(report), buildGradeFPrompt(report));
+  };
+
+  const gradeTiers = [
+    {
+      grade: "A",
+      count: gradeACount,
+      icon: "✅",
+      description: "Compliant Checks & Passing Pillars",
+      action: handleGradeAAction
+    },
+    {
+      grade: "B",
+      count: gradeBCount,
+      icon: "💣",
+      description: "Low Hygiene Issues & Minor Debts",
+      action: handleGradeBAction
+    },
+    {
+      grade: "C",
+      count: gradeCCount,
+      icon: "⚡",
+      description: "Medium Severity Debts & Monolith Drift",
+      action: handleGradeCAction
+    },
+    {
+      grade: "D",
+      count: gradeDCount,
+      icon: "🔥",
+      description: "High Severity Debts & Severe Monoliths",
+      action: handleGradeDAction
+    },
+    {
+      grade: "F",
+      count: gradeFCount,
+      icon: "💥",
+      description: "Critical Hazards & Extreme Monoliths",
+      action: handleGradeFAction
+    }
+  ];
+
+  const createActiveGradeItem = (g) => ({
+    key: `grade_${g.grade.toLowerCase()}`,
+    grade: g.grade.toLowerCase(),
+    tag: resolveGradeBadge(g.grade, 11),
+    label: `${g.icon} Grade ${g.grade}: ${g.description} (${g.count} ${g.grade === "A" ? "clean" : "items"})`,
+    action: g.action
+  });
+
+  return gradeTiers.filter(hasGradeItems).map(createActiveGradeItem);
+};
+
+export const buildDashboardActionGroups = ({ report, onScaffold = null }) => {
+  const handleInstallAction = async () => {
+    await runInstallWizard(process.cwd());
+    if (hasGum()) {
+      gumChoose(["<-- Back to Audit Dashboard"]);
+    }
+  };
+
+  const handleUpgradeAction = async () => {
+    await showConversionMenu(onScaffold);
+  };
+
+  const handleReportAction = async () => {
+    await showPagedContent(formatTerminalReport(report), buildMasterPrompt(report));
+  };
+
+  const handleShareAction = async () => {
+    await handleShareToDiscussions(report);
+  };
+
+  const handleProgressAction = async () => {
+    const baseline = getAuditBaseline();
+    const history = getAuditHistory();
+    const currentSnapshot = createSnapshotFromReport(report);
+
+    let output = "";
+    if (baseline) {
+      output += formatTransformationTerminal(baseline, currentSnapshot);
+    } else {
+      output +=
+        "\n\x1b[33mNo baseline audit found. Current audit established as baseline.\x1b[0m\n";
+    }
+
+    if (history.length > 0) {
+      output += "\n\n" + formatHistoryTimelineTerminal(history);
+    }
+
+    await showPagedContent(output);
+  };
+
+  const handleExportAction = async () => {
+    const outName = hasGum()
+      ? gumInput("Export file path:", "AUDIT_REPORT.md") || "AUDIT_REPORT.md"
+      : (await promptQuestion("Export file path [AUDIT_REPORT.md]: ")) || "AUDIT_REPORT.md";
+    const md = generateMarkdownReport(report);
+    fs.writeFileSync(path.resolve(process.cwd(), outName), md, "utf-8");
+    process.stdout.write(`\x1b[32m✔ Exported markdown audit report to ${outName}\x1b[0m\n\n`);
+    if (hasGum()) {
+      gumChoose(["<-- Back to Audit Dashboard"]);
+    }
+  };
+
+  const handleCopyPromptAction = async () => {
+    const masterPrompt = buildMasterPrompt(report);
+    if (!masterPrompt) {
+      process.stdout.write("\n\x1b[32m✔ Codebase is pristine (Grade A+). No refactoring prompt needed!\x1b[0m\n\n");
+      if (hasGum()) {
+        gumChoose(["<-- Back to Audit Dashboard"]);
+      }
+      return;
+    }
+    const success = copyToClipboard(masterPrompt);
+    if (success) {
+      process.stdout.write(
+        "\n\x1b[1m\x1b[32m✔ AI Agent refactoring prompt copied to clipboard!\x1b[0m\n" +
+          "\x1b[36mPaste directly into Cursor, Claude, or Windsurf to resolve architectural hazards.\x1b[0m\n\n"
+      );
+    } else {
+      process.stdout.write("\n\x1b[33m⚠ Could not access system clipboard.\x1b[0m\n\n");
+    }
+    if (hasGum()) {
+      gumChoose(["<-- Back to Audit Dashboard"]);
+    }
+  };
+
+  const handleExitAction = async () => {};
+
+  const installAction = {
+    key: "install",
+    tag: formatButtonTag("Install", "\x1b[32m"),
+    label: "🪝 Install Pre-Commit Hook & GitHub CI Workflow",
+    action: handleInstallAction
+  };
+
+  const upgradeAction = {
+    key: "upgrade",
+    tag: formatButtonTag("Upgrade", "\x1b[33m"),
+    label: "💎 Unlock Full Molecular Rules & Scaffolding (Chemical X: Team Power Puff)",
+    action: handleUpgradeAction
+  };
+
+  const reportAction = {
+    key: "report",
+    tag: formatButtonTag("Full Report", "\x1b[36m"),
+    label: "📋 Show Full Report (All Sections at Once)",
+    action: handleReportAction
+  };
+
+  const shareAction = {
+    key: "share",
+    tag: formatButtonTag("Share", "\x1b[35m"),
+    label: "🕵  Plug your site and Post to GitHub Discussions (npx chemx audit)",
+    action: handleShareAction
+  };
+
+  const progressAction = {
+    key: "progress",
+    tag: formatButtonTag("Progress", "\x1b[32m"),
+    label: "📈 View Before & After Transformation Progress",
+    action: handleProgressAction
+  };
+
+  const exportAction = {
+    key: "export",
+    tag: formatButtonTag("Export", "\x1b[36m"),
+    label: "💾 Export Markdown Report to File",
+    action: handleExportAction
+  };
+
+  const copyPromptAction = {
+    key: "prompt",
+    tag: formatButtonTag("Prompt", "\x1b[38;2;98;201;255m"),
+    label: "📋 Copy AI Prompt Fix to Clipboard",
+    action: handleCopyPromptAction
+  };
+
+  const exitAction = {
+    key: "exit",
+    tag: formatButtonTag("Exit", "\x1b[90m"),
+    label: "🚪 Exit",
+    action: handleExitAction
+  };
+
+  const masterPrompt = buildMasterPrompt(report);
+  const isGradeAPlus = report?.health?.grade === "A+" || report?.metrics?.grade === "A+";
+  const hasPromptToCopy = Boolean(masterPrompt && masterPrompt.trim().length > 0);
+  const isCleanAPlus = isGradeAPlus && !hasPromptToCopy;
+  const shouldShowPromptAction = hasPromptToCopy && !isCleanAPlus;
+
+  return {
+    installAction,
+    upgradeAction,
+    reportAction,
+    shareAction,
+    progressAction,
+    exportAction,
+    copyPromptAction,
+    exitAction,
+    shouldShowPromptAction
+  };
+};

package/cli/navigator-banner.js

@@ -0,0 +1,98 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getChemicalXAsciiBanner } from "./audit.js";
+import { resolveGradeColor, resolveHealthHearts } from "./navigator-grades.js";
+
+const visualWidth = (s) => {
+  const stripped = s.replace(/\x1b\[[0-9;]*m/g, "");
+  let w = 0;
+  for (const seg of new Intl.Segmenter().segment(stripped)) {
+    const char = seg.segment;
+    const isDoubleWidth = char === "❤️" || char === "🖤" || char.codePointAt(0) > 0x1f000;
+    w += isDoubleWidth ? 2 : char.length;
+  }
+  return w;
+};
+
+const resolveProjectName = () => {
+  try {
+    const pkgPath = path.resolve(process.cwd(), "package.json");
+    if (fs.existsSync(pkgPath)) return JSON.parse(fs.readFileSync(pkgPath, "utf-8")).name || path.basename(process.cwd());
+  } catch {}
+  return path.basename(process.cwd()) || "Project";
+};
+
+const truncatePath = (p, maxLen) => (p.length <= maxLen ? p : `…${p.slice(p.length - maxLen + 1)}`);
+
+export const renderDashboardBanner = (
+  health,
+  metrics,
+  violations,
+  critical,
+  highMediumCount,
+  low,
+  contextAnalysis = null
+) => {
+  if (process.stdout.isTTY) console.clear();
+  process.stdout.write(getChemicalXAsciiBanner(health.grade));
+
+  const gColor = resolveGradeColor(health.grade);
+  const critColor = critical.length > 0 ? "\x1b[31;1m" : "\x1b[32m";
+  const highMedColor = highMediumCount > 0 ? "\x1b[38;5;208;1m" : "\x1b[32m";
+  const lowColor = low.length > 0 ? "\x1b[33;1m" : "\x1b[32m";
+
+  const hearts = resolveHealthHearts(health.grade, health.score);
+  const scoreBadge = `${health.score}/100 [Grade: ${health.grade}]`;
+  const labelStr = health.label ? ` (${health.label})` : "";
+  const healthStr = `${hearts}  ${gColor}${scoreBadge}\x1b[0m${gColor}${labelStr}\x1b[0m`;
+
+  const filesStr = `${metrics.scannedFiles} Files`;
+  const locStr = `${(metrics.totalLoc || 0).toLocaleString()}`;
+  const hazardsStr = `💥 ${critColor}${critical.length} Critical\x1b[0m | 🔥 ${highMedColor}${highMediumCount} High/Med\x1b[0m | 💣 ${lowColor}${low.length} Low\x1b[0m`;
+
+  const tokens = contextAnalysis?.estimatedTokens || 0;
+  const pct = contextAnalysis?.potentialSavingsPct || 0;
+  const costPass = contextAnalysis?.excessCostPerPass !== undefined
+    ? contextAnalysis.excessCostPerPass
+    : Number((((contextAnalysis?.estimatedExcessTokens || 0) / 1000000) * 3.0).toFixed(3));
+  const costMonth = contextAnalysis?.monthlyWastePerDev !== undefined
+    ? contextAnalysis.monthlyWastePerDev
+    : Number((costPass * 20 * 5 * 4).toFixed(2));
+
+  const tokensStr = `~${tokens.toLocaleString()} tokens` + (pct > 0 ? ` (${pct}% cut)` : "");
+  const costStr = costPass > 0
+    ? `\x1b[38;5;208;1m$${costPass.toFixed(3)}\x1b[0m\x1b[2m/turn\x1b[0m | \x1b[31;1m$${costMonth.toFixed(2)}\x1b[0m\x1b[2m/mo\x1b[0m`
+    : `\x1b[32;1m$0.000\x1b[0m\x1b[2m/turn\x1b[0m | \x1b[32;1m$0.00\x1b[0m\x1b[2m/mo\x1b[0m`;
+
+  const col1 = [
+    "\x1b[36;1m-FILES-\x1b[0m", `\x1b[36m${filesStr}\x1b[0m`,
+    "\x1b[36;1m-LINES OF CODE-\x1b[0m", `\x1b[36m${locStr}\x1b[0m`,
+    "\x1b[36;1m-TOKEN EST-\x1b[0m", `\x1b[36m${tokensStr}\x1b[0m`
+  ];
+  const col2 = [
+    "\x1b[31;1m-HEALTH-\x1b[0m", healthStr,
+    "\x1b[33;1m-HAZARDS-\x1b[0m", hazardsStr,
+    "\x1b[32;1m-CURRENCY-\x1b[0m", costStr
+  ];
+
+  const col1Pad = 32;
+  const rows = [];
+  let maxW = 0;
+  for (let i = 0; i < col1.length; i++) {
+    const pad = " ".repeat(Math.max(2, col1Pad - visualWidth(col1[i])));
+    const content = col1[i] + pad + col2[i];
+    const w = visualWidth(content);
+    if (w > maxW) maxW = w;
+    rows.push({ content, width: w });
+  }
+
+  const projectName = resolveProjectName();
+  const innerWidth = Math.max(maxW, visualWidth(projectName) + 4);
+  const bColor = "\x1b[1;38;5;81m";
+  const topBorder = `${bColor}╭── \x1b[1;37m${projectName}${bColor} ${"─".repeat(Math.max(2, innerWidth - visualWidth(projectName)))}╮\x1b[0m`;
+  const displayPwd = truncatePath(process.cwd(), Math.max(10, innerWidth - 4));
+  const botBorder = `${bColor}╰── \x1b[36m${displayPwd}${bColor} ${"─".repeat(Math.max(2, innerWidth - visualWidth(displayPwd)))}╯\x1b[0m`;
+  const bodyLines = rows.map((r) => `${bColor}│\x1b[0m  ${r.content}${" ".repeat(innerWidth - r.width)}  ${bColor}│\x1b[0m`);
+
+  process.stdout.write(`\n${[topBorder, ...bodyLines, botBorder].join("\n")}\n\n`);
+};

package/cli/navigator-conversion.js

@@ -0,0 +1,100 @@
+import { spawnSync } from 'node:child_process';
+import {
+  hasGum,
+  gumChoose,
+  promptQuestion,
+  openBrowser
+} from './terminal.js';
+import {
+  URL_LEARN,
+  URL_SPONSOR,
+  URL_STANDARD,
+  URL_MASTER
+} from './license.js';
+
+export const showConversionMenu = async (onScaffold = null) => {
+  while (true) {
+    if (hasGum()) {
+      spawnSync('gum', [
+        'style', '--border=rounded', '--border-foreground=81', '--padding=0 1', '--bold',
+        'Chemical X: The Secret Sauce to Vibe Coding\nStop letting AI agents scour 2,000-line monoliths and hallucinate.\n25+ Years XP | Codified by Principal Systems Architect Xopher Pollard\nTarget File Budget: Max 500 lines/file (<100 lines/molecule) | 85% Token Burn Cut'
+      ], { stdio: 'inherit' });
+
+      const choice = gumChoose([
+        '1. Sponsor on GitHub: $9/mo Solo / $49/mo Team Unlimited -> Launch Sponsors',
+        '2. Buy Standard Vault: Single Dev License ($27) -> Launch Checkout',
+        '3. Buy Team Power Puff: Unlimited Lifetime ($97) -> Launch Checkout',
+        '4. Enter License Key to Scaffold (Sponsors & License Holders)',
+        '5. Visit chemicalx.xophz.com to learn more',
+        '6. Back to Navigator'
+      ], 'Unlock Chemical X: Team Power Puff & Scaffolding:');
+
+      if (choice.startsWith('1.')) {
+        process.stdout.write(`\n\x1b[36mOpening GitHub Sponsors in browser:\x1b[0m ${URL_SPONSOR}\n\n`);
+        openBrowser(URL_SPONSOR);
+        continue;
+      }
+      if (choice.startsWith('2.')) {
+        process.stdout.write(`\n\x1b[36mOpening Standard Vault checkout (Single Dev License):\x1b[0m ${URL_STANDARD}\n\n`);
+        openBrowser(URL_STANDARD);
+        continue;
+      }
+      if (choice.startsWith('3.')) {
+        process.stdout.write(`\n\x1b[36mOpening Team Power Puff checkout (Unlimited Lifetime):\x1b[0m ${URL_MASTER}\n\n`);
+        openBrowser(URL_MASTER);
+        continue;
+      }
+      if (choice.startsWith('4.')) {
+        if (onScaffold) await onScaffold();
+        break;
+      }
+      if (choice.startsWith('5.')) {
+        process.stdout.write(`\n\x1b[36mOpening Chemical X Portal in browser:\x1b[0m ${URL_LEARN}\n\n`);
+        openBrowser(URL_LEARN);
+        continue;
+      }
+      break;
+    }
+
+    process.stdout.write(
+      '\n\x1b[1m\x1b[38;2;98;201;255mChemical X: The Secret Sauce to Vibe Coding\x1b[0m\n' +
+      'Stop letting AI agents scour 2,000-line monoliths and hallucinate breaking changes.\n' +
+      '25+ Years XP | Codified by Principal Systems Architect Xopher Pollard\n' +
+      'Target File Budget: Max 500 lines/file (<100 lines per molecule capsule).\n\n'
+    );
+    process.stdout.write(`  [1] Sponsor on GitHub ($9/mo Solo / $49/mo Team Unlimited) - ${URL_SPONSOR}\n      Includes: Instant GitHub org access to private starter-kit, continuous model prompt updates\n`);
+    process.stdout.write(`  [2] Buy Standard Vault: Single Dev License ($27) - ${URL_STANDARD}\n      Includes: Kindle/Print PDF eBook, 7 Molecular Architecture Chapters, Universal AGENTS.md\n`);
+    process.stdout.write(`  [3] Buy Team Power Puff: Unlimited Lifetime ($97) - ${URL_MASTER}\n      Includes: Unlimited Team Seats, Private Starter-Kit Repo, Pre-Commit Line Budget Hooks, VIP Discord\n`);
+    process.stdout.write('  [4] Enter License Key to Scaffold (Sponsors & License Holders)\n');
+    process.stdout.write(`  [5] Visit chemicalx.xophz.com to learn more - ${URL_LEARN}\n`);
+    process.stdout.write('  [6] Back to Navigator\n\n');
+
+    const selection = await promptQuestion('Select option [1-6] (default: 6): ');
+    const effectiveSelection = selection.trim() || '6';
+    if (effectiveSelection === '1') {
+      process.stdout.write(`\nOpening: ${URL_SPONSOR}\n\n`);
+      openBrowser(URL_SPONSOR);
+      continue;
+    }
+    if (effectiveSelection === '2') {
+      process.stdout.write(`\nOpening: ${URL_STANDARD}\n\n`);
+      openBrowser(URL_STANDARD);
+      continue;
+    }
+    if (effectiveSelection === '3') {
+      process.stdout.write(`\nOpening: ${URL_MASTER}\n\n`);
+      openBrowser(URL_MASTER);
+      continue;
+    }
+    if (effectiveSelection === '4') {
+      if (onScaffold) await onScaffold();
+      break;
+    }
+    if (effectiveSelection === '5') {
+      process.stdout.write(`\nOpening: ${URL_LEARN}\n\n`);
+      openBrowser(URL_LEARN);
+      continue;
+    }
+    break;
+  }
+};

package/cli/navigator-grades.js

@@ -0,0 +1,87 @@
+export const resolveGradeColor = (grade) => {
+  if (grade === 'A+' || grade === 'A') return '\x1b[32;1m';
+  if (grade === 'B') return '\x1b[33;1m';
+  if (grade === 'C') return '\x1b[33;1m';
+  if (grade === 'D') return '\x1b[38;5;208;1m';
+  return '\x1b[31;1m';
+};
+
+export const resolveGradeBadge = (grade, width = 11) => {
+  const color = resolveGradeColor(grade);
+  const text = `Grade: ${grade}`;
+  const totalPadding = Math.max(0, width - text.length);
+  const leftPad = Math.floor(totalPadding / 2);
+  const rightPad = totalPadding - leftPad;
+  const padded = `${' '.repeat(leftPad)}${text}${' '.repeat(rightPad)}`;
+  return `${color}[${padded}]\x1b[0m`;
+};
+
+export const resolveHealthHearts = (grade, score = 0) => {
+  const g = String(grade || '').toUpperCase();
+  let filled = 1;
+  if (g.startsWith('A') || score >= 90) filled = 5;
+  else if (g.startsWith('B') || score >= 80) filled = 4;
+  else if (g.startsWith('C') || score >= 70) filled = 3;
+  else if (g.startsWith('D') || score >= 60) filled = 2;
+  else filled = score === 0 ? 0 : 1;
+
+  const empty = 5 - filled;
+  return '❤️'.repeat(filled) + '🖤'.repeat(empty);
+};
+
+export const resolveCriticalGrade = (count) => {
+  if (count === 0) return 'A+';
+  if (count === 1) return 'D';
+  return 'F';
+};
+
+export const resolveHighMedGrade = (count) => {
+  if (count === 0) return 'A+';
+  if (count <= 3) return 'B';
+  if (count <= 8) return 'C';
+  if (count <= 15) return 'D';
+  return 'F';
+};
+
+export const resolveLowGrade = (count) => {
+  if (count === 0) return 'A+';
+  if (count <= 5) return 'B';
+  if (count <= 15) return 'C';
+  return 'D';
+};
+
+const isFailedPillar = (p) => p.status === 'FAILED';
+const isWarnPillar = (p) => p.status === 'WARN';
+
+export const resolvePillarGrade = (pillars) => {
+  const values = Object.values(pillars || {});
+  const failed = values.filter(isFailedPillar).length;
+  const warn = values.filter(isWarnPillar).length;
+  if (failed === 0 && warn === 0) return 'A+';
+  if (failed === 0) return 'B';
+  if (failed <= 2) return 'C';
+  if (failed <= 4) return 'D';
+  return 'F';
+};
+
+const isExtremeFile = (h) => h.lineCount >= 2000;
+const isSevereFile = (h) => h.lineCount >= 1000;
+const isWarningFile = (h) => h.lineCount > 500;
+
+export const resolveHotspotGrade = (hotspots) => {
+  if (!hotspots || hotspots.length === 0) return 'A+';
+  const hasExtreme = hotspots.some(isExtremeFile);
+  if (hasExtreme) return 'F';
+  const hasSevere = hotspots.some(isSevereFile);
+  if (hasSevere) return 'D';
+  const hasWarning = hotspots.some(isWarningFile);
+  if (hasWarning) return 'C';
+  return 'B';
+};
+
+export const resolveContextGrade = (riskTier) => {
+  if (riskTier === 'LOW') return 'A';
+  if (riskTier === 'MEDIUM') return 'B';
+  if (riskTier === 'HIGH') return 'D';
+  return 'F';
+};

package/cli/navigator-menu.js

@@ -0,0 +1,127 @@
+export const formatButtonTag = (label, color = "", width = 11) => {
+  const totalPadding = Math.max(0, width - label.length);
+  const leftPad = Math.floor(totalPadding / 2);
+  const rightPad = totalPadding - leftPad;
+  const inner = `${" ".repeat(leftPad)}${label}${" ".repeat(rightPad)}`;
+  return color ? `${color}[${inner}]\x1b[0m` : `[${inner}]`;
+};
+
+const isNonEmptyGroup = (group) => group.length > 0;
+
+export const buildNavigatorMenu = (topActions, activeGrades, midActions, bottomActions) => {
+  const groups = [topActions, activeGrades, midActions, bottomActions].filter(isNonEmptyGroup);
+  const menuItems = groups.flat();
+  const menuOptions = [];
+  let currentIndex = 1;
+  const divider = "──────────────────────────────────────────────────────────────────────";
+
+  groups.forEach((group, idx) => {
+    for (const item of group) {
+      item.index = currentIndex;
+      const pad = String(currentIndex).padStart(2, " ");
+      menuOptions.push(` ${pad}. ${item.tag} ${item.label}`);
+      currentIndex++;
+    }
+    if (idx < groups.length - 1) {
+      menuOptions.push(divider);
+    }
+  });
+
+  return { menuItems, menuOptions };
+};
+
+const isChoiceMatchingItem = (cleanChoice) => (item) => {
+  const prefix = `${item.index}.`;
+  if (cleanChoice.startsWith(prefix) || cleanChoice === String(item.index)) return true;
+  if (
+    item.key === "exit" &&
+    (cleanChoice.includes("Exit") || cleanChoice.toLowerCase() === "exit")
+  ) {
+    return true;
+  }
+  if (
+    item.key === "prompt" &&
+    (cleanChoice.includes("Prompt") || cleanChoice.includes("Clipboard"))
+  ) {
+    return true;
+  }
+  if (
+    item.key === "report" &&
+    (cleanChoice.includes("Report") || cleanChoice.includes("Full Report"))
+  ) {
+    return true;
+  }
+  if (item.key === "progress" && cleanChoice.includes("Progress")) return true;
+  if (
+    item.key === "share" &&
+    (cleanChoice.includes("Share") ||
+      cleanChoice.includes("Discussions") ||
+      cleanChoice.includes("Plug your"))
+  ) {
+    return true;
+  }
+  if (item.key === "export" && cleanChoice.includes("Export")) return true;
+  if (
+    item.key === "install" &&
+    (cleanChoice.includes("Install") ||
+      cleanChoice.includes("Pre-Commit") ||
+      cleanChoice.includes("Workflow"))
+  ) {
+    return true;
+  }
+  if (
+    item.key === "upgrade" &&
+    (cleanChoice.includes("Upgrade") ||
+      cleanChoice.includes("Power Puff") ||
+      cleanChoice.includes("Team Power Puff") ||
+      cleanChoice.includes("Molecular Rules"))
+  ) {
+    return true;
+  }
+  if (
+    item.grade &&
+    (cleanChoice.toLowerCase().includes(`grade ${item.grade}`) ||
+      cleanChoice.toLowerCase().includes(`grade: ${item.grade}`))
+  ) {
+    return true;
+  }
+  return false;
+};
+
+export const matchGumChoice = (cleanChoice, menuItems) => {
+  const matcher = isChoiceMatchingItem(cleanChoice);
+  return menuItems.find(matcher);
+};
+
+const isEffectiveMatchingItem = (effective, exitIndex) => (item) => {
+  if (effective === String(item.index)) return true;
+  if (item.key === "exit" && (effective === "exit" || effective === String(exitIndex))) {
+    return true;
+  }
+  if (
+    item.key === "prompt" &&
+    (effective === "prompt" ||
+      effective === "copy" ||
+      effective === "c" ||
+      effective === "clipboard")
+  ) {
+    return true;
+  }
+  if (
+    item.key === "report" &&
+    (effective === "report" || effective === "full report" || effective === "full")
+  ) {
+    return true;
+  }
+  if (item.key === "share" && (effective === "share" || effective === "post")) return true;
+  if (item.key === effective) return true;
+  if (item.grade && (effective === item.grade || effective === `grade ${item.grade}`)) {
+    return true;
+  }
+  return false;
+};
+
+export const matchFallbackChoice = (effective, menuItems, exitIndex) => {
+  const matcher = isEffectiveMatchingItem(effective, exitIndex);
+  return menuItems.find(matcher);
+};