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

package/cli/navigator-paged.js

@@ -0,0 +1,86 @@
+import {
+  hasGum,
+  gumChoose,
+  promptQuestion,
+  stripAnsi
+} from './terminal.js';
+import { copyToClipboard } from './audit.js';
+
+const PROMPT_MARKER = 'Copy and paste the block below directly into Cursor / Claude / Windsurf:';
+
+export const extractPromptFromContent = (content) => {
+  if (!content?.includes(PROMPT_MARKER)) return null;
+  const clean = stripAnsi(content);
+  const markerIdx = clean.indexOf(PROMPT_MARKER);
+  if (markerIdx === -1) return null;
+
+  const afterMarker = clean.slice(markerIdx + PROMPT_MARKER.length);
+  const borderStartIdx = afterMarker.indexOf('├');
+  const sliceFrom = borderStartIdx !== -1 ? afterMarker.slice(borderStartIdx) : afterMarker;
+
+  const lines = sliceFrom.split('\n');
+  const promptLines = [];
+  let recording = false;
+
+  for (const line of lines) {
+    if (line.includes('├')) {
+      recording = true;
+      continue;
+    }
+    if (line.includes('└')) break;
+    if (recording) {
+      promptLines.push(line.replace(/^\s*│\s?/, ''));
+    }
+  }
+
+  const result = promptLines.join('\n').trim();
+  return result.length > 0 ? result : null;
+};
+
+export const showPagedContent = async (content, promptText = null) => {
+  if (process.stdout.isTTY) console.clear();
+  process.stdout.write(content + '\n\n');
+
+  const effectivePrompt = (promptText && promptText.trim().length > 0)
+    ? promptText.trim()
+    : extractPromptFromContent(content);
+
+  if (!effectivePrompt) {
+    if (hasGum()) gumChoose(['<-- Back to Audit Dashboard']);
+    else await promptQuestion('Press Enter to return to menu...');
+    return;
+  }
+
+  while (true) {
+    if (hasGum()) {
+      const choice = gumChoose(['1. 📋 Copy AI Agent Prompt to Clipboard', '2. <-- Back to Audit Dashboard']);
+      if (choice?.startsWith('1.')) {
+        const success = copyToClipboard(effectivePrompt);
+        if (success) {
+          process.stdout.write('\n\x1b[1m\x1b[32m✔ AI Agent refactoring prompt copied to clipboard!\x1b[0m\n');
+          process.stdout.write('\x1b[36mPaste directly into Cursor, Claude, or Windsurf to begin automated refactoring.\x1b[0m\n\n');
+        } else {
+          process.stdout.write('\n\x1b[33m⚠ Could not access system clipboard.\x1b[0m\n\n');
+        }
+        gumChoose(['<-- Back to Audit Dashboard']);
+        break;
+      }
+      break;
+    }
+
+    process.stdout.write('\n\x1b[1mOptions:\x1b[0m\n  [c] 📋 Copy AI Agent Prompt to Clipboard\n  [Enter] <-- Back to Audit Dashboard\n');
+    const input = await promptQuestion('Select option [Enter]: ');
+    if (input.trim().toLowerCase() === 'c') {
+      const success = copyToClipboard(effectivePrompt);
+      if (success) {
+        process.stdout.write('\n\x1b[1m\x1b[32m✔ AI Agent refactoring prompt copied to clipboard!\x1b[0m\n');
+        process.stdout.write('\x1b[36mPaste directly into Cursor, Claude, or Windsurf to begin automated refactoring.\x1b[0m\n\n');
+      } else {
+        process.stdout.write('\n\x1b[33m⚠ Could not access system clipboard.\x1b[0m\n\n');
+      }
+      await promptQuestion('Press Enter to return to Audit Dashboard...');
+      break;
+    }
+    break;
+  }
+};

package/cli/navigator-share.js

@@ -0,0 +1,129 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import {
+  hasGum,
+  gumChoose,
+  gumInput,
+  promptQuestion,
+  openBrowser
+} from './terminal.js';
+import {
+  detectGitRepoInfo,
+  detectGitHubUser,
+  getAuditBaseline,
+  createSnapshotFromReport,
+  getAuditHistory,
+  generateTransformationDiscussionContent,
+  generateDiscussionContent,
+  publishDiscussion,
+  publishOrUpdateDiscussion,
+  getStoredDiscussion,
+  copyToClipboard,
+  ORG_DISCUSSIONS_URL,
+  DISCUSSION_CATEGORY,
+  DEFAULT_DISCUSSION_REPO,
+  DISCUSSION_CATEGORY_SLUG
+} from './audit.js';
+
+export const handleShareToDiscussions = async (report) => {
+  const repoInfo = detectGitRepoInfo();
+  const detectedUser = detectGitHubUser();
+  const defaultProject = repoInfo.nameWithOwner || path.basename(process.cwd());
+
+  const baseline = getAuditBaseline();
+  const currentSnapshot = createSnapshotFromReport(report);
+  const history = getAuditHistory();
+
+  const isScoreDifferent = baseline && baseline.health.score !== currentSnapshot.health.score;
+  const isViolationsDifferent = baseline && baseline.violations.total !== currentSnapshot.violations.total;
+  const hasTransformationHistory = Boolean(baseline && (history.length > 1 || isScoreDifferent || isViolationsDifferent));
+
+  let shareType = 'single';
+  if (hasTransformationHistory) {
+    if (hasGum()) {
+      const choice = gumChoose([
+        '1. 🚀 Post Transformation Showcase (Before vs. After Delta)',
+        '2. 📋 Post Single Audit Scorecard (Current Snapshot Only)'
+      ]);
+      if (choice?.includes('1.')) shareType = 'transformation';
+    } else {
+      process.stdout.write('\nSelect Discussion Post Format:\n');
+      process.stdout.write('  [1] 🚀 Post Transformation Showcase (Before vs. After Delta)\n');
+      process.stdout.write('  [2] 📋 Post Single Audit Scorecard (Current Snapshot Only)\n');
+      const choice = await promptQuestion('Choice [1]: ');
+      if (!choice || choice.trim() === '1') shareType = 'transformation';
+    }
+  }
+
+  let detectedSite = '';
+  try {
+    const pkgPath = path.resolve(process.cwd(), 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      detectedSite = pkg.homepage || pkg.website || '';
+    }
+  } catch {}
+
+  const stored = getStoredDiscussion();
+  if (!detectedSite && stored?.website) {
+    detectedSite = stored.website;
+  }
+
+  let user = detectedUser;
+  let projectName = defaultProject;
+  let liveUrl = detectedSite;
+  const modeLabel = shareType === 'transformation' ? 'Transformation Showcase (Delta)' : 'Single Audit Scorecard';
+
+  if (hasGum()) {
+    spawnSync('gum', ['style', '--border=rounded', '--border-foreground=81', '--padding=0 2', '--bold',
+      `Post Audit to GitHub Discussions\nBoard: ${ORG_DISCUSSIONS_URL}\nCategory: ${DISCUSSION_CATEGORY}\nMode: ${modeLabel}`
+    ], { stdio: 'inherit' });
+
+    user = gumInput('Your GitHub username:', detectedUser) || detectedUser;
+    projectName = gumInput('Project name for audit post:', defaultProject) || defaultProject;
+    liveUrl = gumInput('Website URL (optional):', detectedSite) || detectedSite;
+  } else {
+    process.stdout.write(`\n\x1b[1m\x1b[38;2;98;201;255mPost Audit to GitHub Discussions (${DISCUSSION_CATEGORY})\x1b[0m\n`);
+    user = (await promptQuestion(`Your GitHub username [@${detectedUser}]: `)) || detectedUser;
+    projectName = (await promptQuestion(`Project name for audit post [${defaultProject}]: `)) || defaultProject;
+    liveUrl = (await promptQuestion(`Website URL (optional) [${detectedSite}]: `)) || detectedSite;
+  }
+
+  const isTransformationPost = shareType === 'transformation' && Boolean(baseline);
+  const { title, category, categorySlug, body } = isTransformationPost
+    ? generateTransformationDiscussionContent(baseline, currentSnapshot, user, projectName, repoInfo.url, liveUrl)
+    : generateDiscussionContent(report, user, projectName, repoInfo.url, liveUrl);
+
+  process.stdout.write('\nAttempting publish to GitHub Discussions...\n');
+  const pubResult = await publishOrUpdateDiscussion(DEFAULT_DISCUSSION_REPO, title, body, category, {
+    projectName,
+    website: liveUrl
+  });
+
+  if (pubResult.success && pubResult.url) {
+    if (pubResult.updated) {
+      process.stdout.write(`\n\x1b[1m\x1b[32m✔ Successfully updated discussion topic #${pubResult.discussionNumber}!\x1b[0m\n`);
+      process.stdout.write('  \x1b[33mPrevious audit report was archived as a comment in the thread.\x1b[0m\n');
+      process.stdout.write(`Discussion URL: \x1b[36m${pubResult.url}\x1b[0m\n\n`);
+    } else {
+      process.stdout.write(`\n\x1b[1m\x1b[32m✔ Successfully published discussion topic!\x1b[0m\nDiscussion URL: \x1b[36m${pubResult.url}\x1b[0m\n\n`);
+    }
+    openBrowser(pubResult.url);
+  } else {
+    copyToClipboard(body);
+    const targetSlug = categorySlug || DISCUSSION_CATEGORY_SLUG || 'npx-chemx-audit';
+    const fallbackUrl = pubResult.discussionNumber
+      ? `https://github.com/${DEFAULT_DISCUSSION_REPO}/discussions/${pubResult.discussionNumber}`
+      : `${ORG_DISCUSSIONS_URL}/new?category=${encodeURIComponent(targetSlug)}&title=${encodeURIComponent(title)}`;
+    process.stdout.write('\n\x1b[32m✔ Formatted audit report copied to your system clipboard!\x1b[0m\n');
+    process.stdout.write(`Opening GitHub Discussions in default browser:\n  \x1b[36m${fallbackUrl}\x1b[0m\n\n`);
+    openBrowser(fallbackUrl);
+  }
+
+  if (hasGum()) {
+    gumChoose(['<-- Back to Audit Dashboard']);
+  } else {
+    await promptQuestion('Press Enter to return to menu...');
+  }
+};

package/cli/navigator.d.ts

@@ -0,0 +1,43 @@
+import type { AuditReport } from './audit/types';
+
+export declare function resolveGradeColor(grade: string): string;
+export declare function resolveGradeBadge(grade: string, width?: number): string;
+export declare function resolveHealthHearts(grade: string, score?: number, isAnsi?: boolean): string;
+export declare function resolveCriticalGrade(count: number): string;
+export declare function resolveHighMedGrade(count: number): string;
+export declare function resolveLowGrade(count: number): string;
+export declare function resolvePillarGrade(pillars: Record<string, unknown>): string;
+export declare function resolveHotspotGrade(hotspots: readonly { readonly lineCount: number }[]): string;
+export declare function resolveContextGrade(riskTier: string): string;
+
+export interface NavigatorMenuItem {
+  key?: string;
+  grade?: string;
+  tag: string;
+  label: string;
+  index?: number;
+  action: () => Promise<void>;
+}
+
+export declare function formatButtonTag(label: string, color?: string, width?: number): string;
+export declare function buildNavigatorMenu(
+  topActions: readonly NavigatorMenuItem[],
+  activeGrades: readonly NavigatorMenuItem[],
+  midActions: readonly NavigatorMenuItem[],
+  bottomActions: readonly NavigatorMenuItem[]
+): { menuItems: NavigatorMenuItem[]; menuOptions: string[] };
+
+export declare function extractPromptFromContent(content: string): string | null;
+export declare function showPagedContent(content: string, promptText?: string | null): Promise<void>;
+export declare function showConversionMenu(onScaffold?: (() => Promise<void>) | null): Promise<void>;
+export declare function handleShareToDiscussions(report: AuditReport): Promise<void>;
+export declare function renderDashboardBanner(
+  health: AuditReport['health'],
+  metrics: AuditReport['metrics'],
+  violations: AuditReport['violations'],
+  critical: readonly unknown[],
+  highMediumCount: number,
+  low: readonly unknown[],
+  contextAnalysis?: AuditReport['contextAnalysis'] | null
+): void;
+export declare function runInteractiveAuditNavigator(report: AuditReport, onScaffold?: (() => Promise<void>) | null): Promise<void>;

package/cli/navigator.js

@@ -0,0 +1,126 @@
+import {
+  hasGum,
+  gumChoose,
+  promptQuestion,
+  stripAnsi,
+  confirmAction
+} from "./terminal.js";
+import { saveAuditSnapshot, groupViolationsBySeverity } from "./audit.js";
+import { areGuardrailsInstalled } from "./installer.js";
+import { renderDashboardBanner } from "./navigator-banner.js";
+import {
+  formatButtonTag,
+  buildNavigatorMenu,
+  matchGumChoice,
+  matchFallbackChoice
+} from "./navigator-menu.js";
+import {
+  buildActiveGrades,
+  buildDashboardActionGroups
+} from "./navigator-actions.js";
+import { handleShareToDiscussions } from "./navigator-share.js";
+
+export {
+  resolveGradeColor,
+  resolveGradeBadge,
+  resolveHealthHearts,
+  resolveCriticalGrade,
+  resolveHighMedGrade,
+  resolveLowGrade,
+  resolvePillarGrade,
+  resolveHotspotGrade,
+  resolveContextGrade
+} from "./navigator-grades.js";
+export { extractPromptFromContent, showPagedContent } from "./navigator-paged.js";
+export { showConversionMenu } from "./navigator-conversion.js";
+export { handleShareToDiscussions } from "./navigator-share.js";
+export { formatButtonTag, buildNavigatorMenu } from "./navigator-menu.js";
+export { renderDashboardBanner } from "./navigator-banner.js";
+
+export const runInteractiveAuditNavigator = async (report, onScaffold = null) => {
+  saveAuditSnapshot(report);
+  const { metrics, health, violations, contextAnalysis } = report;
+  const { critical, high, medium, low } = groupViolationsBySeverity(violations);
+  const highMediumCount = high.length + medium.length;
+
+  const activeGrades = buildActiveGrades(report);
+  const actions = buildDashboardActionGroups({ report, onScaffold });
+
+  renderDashboardBanner(health, metrics, violations, critical, highMediumCount, low, contextAnalysis);
+
+  const shouldPublish = await confirmAction(
+    "Publish audit report and promote your project to our GitHub Discussions Audits Forum?",
+    "Publish Report",
+    "Skip to Menu",
+    true
+  );
+
+  if (shouldPublish) {
+    await handleShareToDiscussions(report);
+  }
+
+  while (true) {
+    renderDashboardBanner(health, metrics, violations, critical, highMediumCount, low, contextAnalysis);
+
+    const guardrailsInstalled = areGuardrailsInstalled(process.cwd());
+    const topActions = [];
+    if (!guardrailsInstalled) {
+      topActions.push(actions.installAction);
+    }
+    topActions.push(actions.upgradeAction, actions.reportAction);
+
+    const midActions = [actions.shareAction, actions.progressAction, actions.exportAction];
+    const bottomActions = [];
+    if (actions.shouldShowPromptAction) {
+      bottomActions.push(actions.copyPromptAction);
+    }
+    bottomActions.push(actions.exitAction);
+
+    const { menuItems, menuOptions } = buildNavigatorMenu(
+      topActions,
+      activeGrades,
+      midActions,
+      bottomActions
+    );
+
+    if (hasGum()) {
+      const choice = gumChoose(menuOptions, "Select an audit section or grade to inspect:");
+      const cleanChoice = stripAnsi(choice || "").trim();
+
+      const isSeparator = !choice || cleanChoice.includes("───") || cleanChoice.includes("---");
+      if (isSeparator) {
+        continue;
+      }
+
+      const match = matchGumChoice(cleanChoice, menuItems);
+      const shouldExit = !match || match.key === "exit";
+      if (shouldExit) {
+        break;
+      }
+
+      await match.action();
+    } else {
+      for (const opt of menuOptions) {
+        process.stdout.write(`  ${opt}\n`);
+      }
+      process.stdout.write("\n");
+
+      const exitIndex = actions.exitAction.index;
+      const promptMsg = `Select option [1-${exitIndex}] (default: ${exitIndex}): `;
+      const selection = await promptQuestion(promptMsg);
+      const effective = selection.trim().toLowerCase() || String(exitIndex);
+
+      const isSep = effective.includes("---") || effective.includes("───");
+      if (isSep) continue;
+
+      const match = matchFallbackChoice(effective, menuItems, exitIndex);
+      const shouldExit = !match || match.key === "exit";
+      if (shouldExit) {
+        break;
+      }
+
+      await match.action();
+      await promptQuestion("Press Enter to return to menu...");
+    }
+  }
+};

package/cli/scaffold.js

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { hasGum, gumInput, promptQuestion, renderBanner } from './terminal.js';
+import { obtainLicenseKey, fetchStarterKitFiles, checkOrPromptEvaluation } from './license.js';
+
+export const runScaffold = async (projectName, rawArgs = [], onRunAudit = null) => {
+  renderBanner('Chemical X: Molecular Architecture Scaffolder (npm create chemx)');
+
+  const licenseKey = await obtainLicenseKey(rawArgs, onRunAudit);
+  if (!licenseKey) {
+    process.stderr.write('\x1b[31m✕ Valid license key is required to scaffold blueprints.\x1b[0m\n');
+    process.exit(1);
+  }
+
+  let targetName = projectName;
+  if (!targetName) {
+    targetName = hasGum()
+      ? gumInput('Project directory name:', 'my-molecular-app')
+      : await promptQuestion('Project directory name [my-molecular-app]: ');
+  }
+
+  const finalDirName = targetName.trim() || 'my-molecular-app';
+  const targetDir = path.resolve(process.cwd(), finalDirName);
+
+  const dirExists = fs.existsSync(targetDir);
+  const isDirNonEmpty = dirExists && fs.readdirSync(targetDir).length > 0;
+  if (isDirNonEmpty) {
+    process.stderr.write(`\x1b[31m✕ Error: Directory '${finalDirName}' already exists and is not empty.\x1b[0m\n`);
+    process.exit(1);
+  }
+
+  const files = await fetchStarterKitFiles(licenseKey);
+
+  process.stdout.write(`Scaffolding Molecular Architecture into: \x1b[36m${finalDirName}/\x1b[0m\n`);
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  for (const [relPath, content] of Object.entries(files)) {
+    const fullPath = path.join(targetDir, relPath);
+    const dirName = path.dirname(fullPath);
+    if (!fs.existsSync(dirName)) {
+      fs.mkdirSync(dirName, { recursive: true });
+    }
+    fs.writeFileSync(fullPath, content, 'utf-8');
+    process.stdout.write(`  \x1b[32m✔\x1b[0m ${relPath}\n`);
+  }
+
+  const cursorRulesPath = path.join(targetDir, '.cursorrules');
+  if (!fs.existsSync(cursorRulesPath)) {
+    const rules = '# Chemical X Molecular Architecture Directives\nStrictly follow AGENTS.md rules. Never exceed 500 lines per file. All molecule capsules must stay under 100 lines.\n';
+    fs.writeFileSync(cursorRulesPath, rules, 'utf-8');
+    process.stdout.write('  \x1b[32m✔\x1b[0m .cursorrules\n');
+  }
+
+  process.stdout.write(
+    `\n\x1b[1m\x1b[32m✔ Molecular Architecture project created successfully at ${finalDirName}!\x1b[0m\n\n`
+  );
+  process.stdout.write('Next Steps:\n');
+  process.stdout.write(`  1. cd ${finalDirName}\n`);
+  process.stdout.write('  2. Review AGENTS.md for line budgets and architecture standards\n');
+  process.stdout.write('  3. Run npx chemx generate m-<feature> to create capsules\n');
+  process.stdout.write('  4. Run npx chemx audit to scan for line budget compliance\n\n');
+};
+
+export const runInit = async (targetSubDir = 'src/chemical-x', rawArgs = [], onRunAudit = null) => {
+  renderBanner('Chemical X: In-Repo Capsule Drop-in');
+
+  const targetDir = path.resolve(process.cwd(), targetSubDir);
+  const licenseKey = await obtainLicenseKey(rawArgs, onRunAudit);
+  if (!licenseKey) {
+    process.stderr.write('\x1b[31m✕ Valid license key is required.\x1b[0m\n');
+    process.exit(1);
+  }
+
+  const files = await fetchStarterKitFiles(licenseKey);
+
+  process.stdout.write(`Unpacking blueprints and hooks into: \x1b[36m${targetSubDir}/\x1b[0m\n`);
+
+  let count = 0;
+  for (const [relPath, content] of Object.entries(files)) {
+    const fullPath = path.join(targetDir, relPath);
+    const dirName = path.dirname(fullPath);
+    if (!fs.existsSync(dirName)) {
+      fs.mkdirSync(dirName, { recursive: true });
+    }
+    fs.writeFileSync(fullPath, content, 'utf-8');
+    process.stdout.write(`  \x1b[32m✔\x1b[0m ${relPath}\n`);
+    count++;
+  }
+
+  process.stdout.write(
+    `\n\x1b[1m\x1b[32m✔ Successfully installed ${count} Chemical X assets into ${targetSubDir}!\x1b[0m\n\n`
+  );
+};
+
+export const runGenerateCapsule = async (capsuleName) => {
+  await checkOrPromptEvaluation('generate capsule');
+
+  const normalizedName = capsuleName.startsWith('m-') ? capsuleName : `m-${capsuleName}`;
+  const targetDir = path.resolve(process.cwd(), normalizedName);
+
+  if (fs.existsSync(targetDir)) {
+    process.stderr.write(`\x1b[31m✕ Error: Directory ${normalizedName} already exists.\x1b[0m\n`);
+    process.exit(1);
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  const pascalName = normalizedName
+    .split('-')
+    .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+    .join('');
+
+  const componentCode = `import React from 'react';
+import type { ${pascalName}Props } from './types';
+
+export const ${pascalName}: React.FC<${pascalName}Props> = ({ label }) => {
+  return (
+    <div className="${normalizedName}">
+      <span>{label}</span>
+    </div>
+  );
+};
+
+export default ${pascalName};
+`;
+
+  const typesCode = `export interface ${pascalName}Props {
+  readonly label: string;
+}
+`;
+
+  const indexCode = `export { ${pascalName} } from './${normalizedName}';
+export type { ${pascalName}Props } from './types';
+`;
+
+  fs.writeFileSync(path.join(targetDir, `${normalizedName}.tsx`), componentCode, 'utf-8');
+  fs.writeFileSync(path.join(targetDir, 'types.d.ts'), typesCode, 'utf-8');
+  fs.writeFileSync(path.join(targetDir, 'index.ts'), indexCode, 'utf-8');
+
+  process.stdout.write(
+    `\x1b[32m✔ Successfully generated crystalline capsule:\x1b[0m ${normalizedName}/\n`
+  );
+  process.stdout.write(`  - ${normalizedName}/${normalizedName}.tsx (< 50 lines)\n`);
+  process.stdout.write(`  - ${normalizedName}/types.d.ts\n`);
+  process.stdout.write(`  - ${normalizedName}/index.ts\n\n`);
+};
+
+export { printHelp } from './help.js';

package/cli/terminal.js

@@ -0,0 +1,126 @@
+import readline from "node:readline";
+import { spawnSync } from "node:child_process";
+
+export const openBrowser = (url) => {
+  const platform = process.platform;
+  try {
+    if (platform === "darwin") {
+      spawnSync("open", [url], { stdio: "ignore" });
+    } else if (platform === "win32") {
+      spawnSync("cmd.exe", ["/c", "start", '""', url], { stdio: "ignore" });
+    } else {
+      spawnSync("xdg-open", [url], { stdio: "ignore" });
+    }
+  } catch {}
+};
+
+export const hasGum = () => {
+  try {
+    return spawnSync("which", ["gum"], { stdio: "ignore" }).status === 0;
+  } catch {
+    return false;
+  }
+};
+
+export const gumChoose = (options, header = "") => {
+  const args = ["choose"];
+  if (header) {
+    args.push(`--header=${header}`, "--header.foreground=81");
+  }
+  const headerPadding = header ? 3 : 1;
+  const listHeight = options.length + headerPadding;
+  args.push("--cursor.foreground=81", `--height=${listHeight}`, ...options);
+  const res = spawnSync("gum", args, { encoding: "utf-8", stdio: ["inherit", "pipe", "inherit"] });
+  return (res.stdout || "").trim();
+};
+
+export const gumInput = (promptText, placeholder = "", isPassword = false) => {
+  const args = ["input", `--prompt=${promptText} `, `--placeholder=${placeholder}`];
+  if (isPassword) {
+    args.push("--password");
+  }
+  const res = spawnSync("gum", args, { encoding: "utf-8", stdio: ["inherit", "pipe", "inherit"] });
+  return (res.stdout || "").trim();
+};
+
+export const promptQuestion = (query) => {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(query, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+};
+
+export const stripAnsi = (text) => text.replace(/\x1b\[[0-9;]*m/g, "");
+
+export const renderBanner = (title = "Chemical X Protocol: Molecular Architecture") => {
+  if (hasGum()) {
+    spawnSync(
+      "gum",
+      [
+        "style",
+        "--border=normal",
+        "--margin=1",
+        "--padding=1 2",
+        "--border-foreground=45",
+        "--foreground=81",
+        "--bold",
+        `  ${title}\n  Zero-Context-Rot Scaffolding & Engineering Directives`
+      ],
+      { stdio: "inherit" }
+    );
+  } else {
+    process.stdout.write(
+      "\n\x1b[38;2;98;201;255m=====================================================\x1b[0m\n"
+    );
+    process.stdout.write(`\x1b[1m\x1b[38;2;98;201;255m  ${title}\x1b[0m\n`);
+    process.stdout.write("  Zero-Context-Rot Scaffolding & Engineering Directives\n");
+    process.stdout.write(
+      "\x1b[38;2;98;201;255m=====================================================\x1b[0m\n\n"
+    );
+  }
+};
+
+export const gumConfirm = (
+  promptText = "Publish audit report and promote your project to our GitHub Discussions Audits Forum?",
+  affirmative = "Publish Report",
+  negative = "Skip to Menu",
+  defaultVal = true
+) => {
+  const args = [
+    "confirm",
+    promptText,
+    `--default=${defaultVal}`,
+    `--affirmative=${affirmative}`,
+    `--negative=${negative}`,
+    "--prompt.foreground=81",
+    "--selected.background=81",
+    "--selected.foreground=0"
+  ];
+  const res = spawnSync("gum", args, { stdio: "inherit" });
+  return res.status === 0;
+};
+
+export const promptConfirm = async (
+  query = "Publish audit report and promote your project to our GitHub Discussions Audits Forum?",
+  defaultVal = true
+) => {
+  const suffix = defaultVal ? " [Y/n]: " : " [y/N]: ";
+  const answer = await promptQuestion(`${query}${suffix}`);
+  if (!answer) return defaultVal;
+  return /^(y|yes)$/i.test(answer);
+};
+
+export const confirmAction = async (
+  promptText = "Publish audit report and promote your project to our GitHub Discussions Audits Forum?",
+  affirmative = "Publish Report",
+  negative = "Skip to Menu",
+  defaultVal = true
+) => {
+  if (hasGum()) {
+    return gumConfirm(promptText, affirmative, negative, defaultVal);
+  }
+  return promptConfirm(promptText, defaultVal);
+};