nexus-agents 2.55.1 → 2.56.0

package/dist/cli.d.ts

@@ -50,6 +50,7 @@ interface ParsedCliArgs {
         version: boolean;
         verbose: boolean;
         interactive: boolean;
+        all: boolean;
         mode: ServerMode;
         output?: string;
         force: boolean;
@@ -122,8 +123,12 @@ interface ParsedCliArgs {
 
 /**
  * Prints help text to stdout.
+ *
+ * Default output hides maintainer commands (benchmarks, release tooling, deep
+ * diagnostics). Pass `--all` to include them. See `cli-command-catalog.ts` for
+ * the audience classification.
  */
-declare function printHelp(): void;
+declare function printHelp(args?: ParsedCliArgs): void;
 /**
  * Prints version information to stdout.
  */

package/dist/cli.js

@@ -14,28 +14,23 @@ import {
 } from "./chunk-6E3NMMEY.js";
 import "./chunk-4FVISCDB.js";
 import {
-  setupCommandAsync
-} from "./chunk-XYCS5X3H.js";
+  setupCommandAsync,
+  verifyCommand
+} from "./chunk-KGMC6F5D.js";
 import "./chunk-EKYT4NMD.js";
 import {
   AuthHandler,
-  CustomExpertDefinitionSchema,
-  DEFAULTS,
   DEFAULT_EXPERTS,
   DEFAULT_SWE_BENCH_CONFIG,
   DEVELOPMENT_POLICY,
   ExpertFactory,
   FeedbackIntegration,
-  MAX_SYSTEM_PROMPT_LENGTH,
   Orchestrator,
   PuppeteerOrchestrator,
   READONLY_POLICY,
   SwarmObserver,
-  VALID_EXPERT_DOMAINS,
-  VALID_EXPERT_TIERS,
   ValidationDashboard,
   WorkflowDefinitionSchema,
-  adaptRoutingConfig,
   addResearchPaper,
   analyzeTools,
   createAgentStages,
@@ -61,7 +56,6 @@ import {
   createTestingExpert,
   createToolObservabilityProxy,
   createToolRateLimiterFactory,
-  defaultConfig,
   detectBackend,
   discoverDeepMind,
   discoverGitHubRepos,
@@ -83,8 +77,6 @@ import {
   generateSwarmVisualization,
   generateSystemSummary,
   getCompletedInstanceIds,
-  getConfig,
-  getConfigManager,
   getDatasetInfo,
   getDefaultTokenPath,
   getEventBusStats,
@@ -103,7 +95,6 @@ import {
   initializeSandbox,
   initializeSica,
   loadAllExternalPacks,
-  loadConfig,
   loadDataset,
   loadSourcesRegistry,
   loadWorkflowFile,
@@ -148,10 +139,9 @@ import {
   setGlobalToolRateLimiterFactory,
   validateArgs,
   validateCommand,
-  validateNexusEnv,
   validateWorkflow,
   wrapInMarkdownFence
-} from "./chunk-KVWHK72T.js";
+} from "./chunk-EJLWDYK7.js";
 import {
   resolveToken
 } from "./chunk-2SPRLBOS.js";
@@ -177,7 +167,7 @@ import {
   loadTechniquesRegistry,
   savePapersRegistry,
   synthesizeResearch
-} from "./chunk-JERFBN73.js";
+} from "./chunk-PCMWLXT4.js";
 import {
   classifyTrust,
   createFullGitHubProvider,
@@ -192,17 +182,26 @@ import "./chunk-AP2FD37C.js";
 import "./chunk-BQ4YXGGQ.js";
 import "./chunk-ED6VQWNG.js";
 import {
-  BUILT_IN_EXPERTS
-} from "./chunk-GJVHRJO2.js";
-import {
+  CustomExpertDefinitionSchema,
+  DEFAULTS,
+  MAX_SYSTEM_PROMPT_LENGTH,
+  VALID_EXPERT_DOMAINS,
+  VALID_EXPERT_TIERS,
   VERSION,
+  adaptRoutingConfig,
   closeServer,
   connectTransport,
   createServer,
   doctorCommand,
+  getConfig,
+  getConfigManager,
   initDataDirectories,
-  runDoctor
-} from "./chunk-OC7RMLN2.js";
+  loadConfig,
+  runDoctor,
+  validateNexusEnv
+} from "./chunk-C3FGEDD7.js";
+import "./chunk-NUBSJGQZ.js";
+import "./chunk-GJVHRJO2.js";
 import "./chunk-NYNBDP7M.js";
 import {
   MemoryError
@@ -9389,21 +9388,22 @@ function getCommandOptions(name, cliOptions) {
   }
   return cmdOptions;
 }
+function loadHelpTextCommands(project, packageRoot, typesFile) {
+  const helpTextPath = path12.join(packageRoot, "src/cli-help-text.ts");
+  const helpTextFile = project.getSourceFile(helpTextPath) ?? typesFile;
+  if (helpTextFile === void 0) return [];
+  const helpTextVar = helpTextFile.getVariableDeclaration("HELP_TEXT");
+  if (helpTextVar === void 0) return [];
+  const helpText = helpTextVar.getInitializer()?.getText() ?? "";
+  const cleanText = helpText.slice(1, -1).replace(/^\s*\n/, "").replace(/\n\s*$/, "");
+  return parseHelpTextCommands(cleanText);
+}
 function extractCliCommands(project, packageRoot, cliCommandsPath, cliTypesPath) {
   const commands = [];
   const typesFullPath = path12.join(packageRoot, cliTypesPath);
   const typesFile = project.getSourceFile(typesFullPath);
-  let helpTextCommands = [];
-  let cliOptions = /* @__PURE__ */ new Map();
-  if (typesFile !== void 0) {
-    const helpTextVar = typesFile.getVariableDeclaration("HELP_TEXT");
-    if (helpTextVar !== void 0) {
-      const helpText = helpTextVar.getInitializer()?.getText() ?? "";
-      const cleanText = helpText.slice(1, -1).replace(/^\s*\n/, "").replace(/\n\s*$/, "");
-      helpTextCommands = parseHelpTextCommands(cleanText);
-    }
-    cliOptions = extractCliOptions(typesFile);
-  }
+  const helpTextCommands = loadHelpTextCommands(project, packageRoot, typesFile);
+  const cliOptions = typesFile !== void 0 ? extractCliOptions(typesFile) : /* @__PURE__ */ new Map();
   const commandsFullPath = path12.join(packageRoot, cliCommandsPath);
   const commandsFile = project.getSourceFile(commandsFullPath);
   if (commandsFile === void 0) return commands;
@@ -9499,7 +9499,11 @@ function extractToolsFromFile(sourceFile, relativePath) {
     if (args.length < 2) continue;
     const nameArg = args[0];
     if (nameArg === void 0) continue;
-    const toolName = nameArg.getText().replace(/['"]/g, "");
+    const nameKind = nameArg.getKind();
+    if (nameKind !== SyntaxKind2.StringLiteral && nameKind !== SyntaxKind2.NoSubstitutionTemplateLiteral) {
+      continue;
+    }
+    const toolName = nameArg.getText().replace(/['"`]/g, "");
     const { description, schemaArg } = extractToolMeta(callText, args, sourceFile);
     let parameters = [];
     if (schemaArg !== void 0) {
@@ -9591,6 +9595,11 @@ function createProject(opts) {
   project.addSourceFilesAtPaths([
     path14.join(opts.packageRoot, opts.cliCommandsPath),
     path14.join(opts.packageRoot, "src/cli-types.ts"),
+    // HELP_TEXT was extracted to cli-help-text.ts in #293 (Jan 2026) and
+    // cli-types.ts now only re-exports it. The extractor reads it via AST,
+    // so we have to load the defining file — a bare re-export isn't enough.
+    // Without this line the CLI command list silently came back empty.
+    path14.join(opts.packageRoot, "src/cli-help-text.ts"),
     path14.join(opts.packageRoot, opts.mcpToolsPath, "*.ts")
   ]);
   return project;
@@ -10409,182 +10418,6 @@ function parseValidationArgs(positionals, format, verbose) {
   return options;
 }
 
-// src/cli/verify-command.ts
-function checkNodeVersion() {
-  const version = process.version;
-  const major = parseInt(version.slice(1).split(".")[0] ?? "0", 10);
-  if (major >= 22) {
-    return {
-      name: "Node.js Version",
-      passed: true,
-      message: `${version} (LTS)`
-    };
-  }
-  if (major >= 18) {
-    return {
-      name: "Node.js Version",
-      passed: true,
-      message: `${version} (supported, recommend 22.x LTS)`
-    };
-  }
-  return {
-    name: "Node.js Version",
-    passed: false,
-    message: `${version} (unsupported)`,
-    fix: "Install Node.js 22.x LTS from https://nodejs.org"
-  };
-}
-function checkPackageExports() {
-  try {
-    const hasVersion = typeof VERSION === "string" && VERSION.length > 0;
-    const hasConfig = typeof defaultConfig === "object";
-    const hasBuiltInExperts = typeof BUILT_IN_EXPERTS === "object";
-    if (hasVersion && hasConfig && hasBuiltInExperts) {
-      return {
-        name: "Package Exports",
-        passed: true,
-        message: "All core modules accessible"
-      };
-    }
-    return {
-      name: "Package Exports",
-      passed: false,
-      message: "Some modules failed to load",
-      fix: "Try reinstalling: npm install -g nexus-agents"
-    };
-  } catch {
-    return {
-      name: "Package Exports",
-      passed: false,
-      message: "Failed to load core modules",
-      fix: "Try reinstalling: npm install -g nexus-agents"
-    };
-  }
-}
-function checkConfigLoading() {
-  try {
-    const hasModels = typeof defaultConfig.models === "object";
-    const hasSecurity = typeof defaultConfig.security === "object";
-    if (hasModels && hasSecurity) {
-      return {
-        name: "Configuration",
-        passed: true,
-        message: "Default config accessible"
-      };
-    }
-    return {
-      name: "Configuration",
-      passed: true,
-      // Config errors are not fatal for verification
-      message: "Using default configuration"
-    };
-  } catch {
-    return {
-      name: "Configuration",
-      passed: true,
-      // Still works with defaults
-      message: "Using default configuration"
-    };
-  }
-}
-function checkExpertSystem() {
-  const expertTypes = Object.keys(BUILT_IN_EXPERTS);
-  const count = expertTypes.length;
-  if (count >= 5) {
-    return {
-      name: "Expert System",
-      passed: true,
-      message: `${String(count)} expert types available`
-    };
-  }
-  return {
-    name: "Expert System",
-    passed: false,
-    message: "Expert types not loaded",
-    fix: "Try reinstalling: npm install -g nexus-agents"
-  };
-}
-function runVerify() {
-  const time = getTimeProvider();
-  const startTime = time.now();
-  const checks = [
-    checkNodeVersion(),
-    checkPackageExports(),
-    checkConfigLoading(),
-    checkExpertSystem()
-  ];
-  const allPassed = checks.every((c) => c.passed);
-  const durationMs = time.now() - startTime;
-  return Promise.resolve({
-    version: VERSION,
-    nodeVersion: process.version,
-    checks,
-    allPassed,
-    durationMs
-  });
-}
-function formatCheck(check) {
-  const symbol = check.passed ? `${colors.green}${symbols.check}${colors.reset}` : `${colors.red}${symbols.cross}${colors.reset}`;
-  let line = `  ${symbol} ${check.name}: ${check.message}`;
-  if (!check.passed && check.fix !== void 0) {
-    line += `
-     ${colors.dim}Fix: ${check.fix}${colors.reset}`;
-  }
-  return line;
-}
-function printVerifyResult(result, verbose) {
-  process.stdout.write("\n");
-  process.stdout.write(`${colors.bold}nexus-agents verify${colors.reset}
-`);
-  process.stdout.write("===================\n");
-  process.stdout.write("\n");
-  process.stdout.write(`Version: ${result.version}
-`);
-  process.stdout.write(`Node.js: ${result.nodeVersion}
-`);
-  process.stdout.write("\n");
-  process.stdout.write(`${colors.cyan}Running checks...${colors.reset}
-`);
-  process.stdout.write("\n");
-  for (const check of result.checks) {
-    process.stdout.write(formatCheck(check) + "\n");
-  }
-  process.stdout.write("\n");
-  if (result.allPassed) {
-    process.stdout.write(
-      `${colors.green}${colors.bold}Installation verified successfully!${colors.reset}
-`
-    );
-    process.stdout.write("\n");
-    process.stdout.write(`${colors.cyan}Next steps:${colors.reset}
-`);
-    process.stdout.write('  1. Run "nexus-agents doctor" to check external CLI integrations\n');
-    process.stdout.write(
-      '  2. Run "nexus-agents review --setup" to configure GitHub integration\n'
-    );
-    process.stdout.write('  3. Try "nexus-agents --help" for all available commands\n');
-  } else {
-    const failedCount = result.checks.filter((c) => !c.passed).length;
-    process.stdout.write(
-      `${colors.red}${colors.bold}Verification failed: ${String(failedCount)} issue(s) found${colors.reset}
-`
-    );
-    process.stdout.write("\n");
-    process.stdout.write("Please fix the issues above and try again.\n");
-  }
-  process.stdout.write("\n");
-  if (verbose) {
-    process.stdout.write(`${colors.dim}Duration: ${String(result.durationMs)}ms${colors.reset}
-`);
-    process.stdout.write("\n");
-  }
-}
-async function verifyCommand(options) {
-  const result = await runVerify();
-  printVerifyResult(result, options.verbose);
-  return result.allPassed ? 0 : 1;
-}
-
 // src/cli/swe-bench-command.ts
 import * as os2 from "os";
 import * as path18 from "path";
@@ -16910,6 +16743,230 @@ function authCommand(subcommand, options) {
   }
 }
 
+// src/cli-command-catalog.ts
+var COMMAND_CATALOG = [
+  // ── Essential ────────────────────────────────────────────────────────────
+  {
+    command: "(default)",
+    description: "Start MCP server with stdio transport",
+    audience: "essential"
+  },
+  {
+    command: "hello",
+    description: "Show welcome message and quick start (no API keys needed)",
+    audience: "essential"
+  },
+  {
+    command: "setup",
+    description: "Configure CLI integration (MCP + .rules + data dirs)",
+    audience: "essential"
+  },
+  {
+    command: "verify",
+    description: "Check install health (sqlite, adapters, config)",
+    audience: "essential"
+  },
+  {
+    command: "doctor",
+    description: "Detailed system/adapter health check",
+    audience: "essential"
+  },
+  {
+    command: "config",
+    description: "Manage configuration (init, get, set, list, export, import)",
+    audience: "essential"
+  },
+  {
+    command: "orchestrate",
+    description: "Execute a task via CLI tools (standalone mode)",
+    audience: "essential"
+  },
+  {
+    command: "vote",
+    description: "Run consensus vote on a proposal (5-6 agents)",
+    audience: "essential"
+  },
+  {
+    command: "workflow",
+    description: "Manage and run workflow templates (list, run)",
+    audience: "essential"
+  },
+  {
+    command: "expert",
+    description: "Manage expert agents (list, create, execute)",
+    audience: "essential"
+  },
+  {
+    command: "research",
+    description: "Manage research registry (status, add, stats, refresh)",
+    audience: "essential"
+  },
+  // ── Advanced ─────────────────────────────────────────────────────────────
+  {
+    command: "session",
+    description: "Manage session persistence (list, show, export, delete)",
+    audience: "advanced"
+  },
+  {
+    command: "auth",
+    description: "Manage MCP authentication tokens (init, show, rotate)",
+    audience: "advanced"
+  },
+  {
+    command: "status",
+    description: "At-a-glance project health dashboard",
+    audience: "advanced"
+  },
+  {
+    command: "capabilities",
+    description: "Show model capabilities matrix",
+    audience: "advanced"
+  },
+  {
+    command: "review",
+    description: "Review a GitHub PR (dogfooding helper)",
+    audience: "advanced"
+  },
+  {
+    command: "scaffold",
+    description: "Generate project files from templates",
+    audience: "advanced"
+  },
+  {
+    command: "validate",
+    description: "Run unified validation (doctor + fitness + config)",
+    audience: "advanced"
+  },
+  {
+    command: "index",
+    description: "Generate and manage codebase index",
+    audience: "advanced"
+  },
+  // ── Maintainer (hidden by default) ───────────────────────────────────────
+  {
+    command: "demo",
+    description: "API-free exploration mode (marketing/demo flow)",
+    audience: "maintainer"
+  },
+  {
+    command: "hooks",
+    description: "Claude CLI hook integration commands",
+    audience: "maintainer"
+  },
+  {
+    command: "routing-audit",
+    description: "Debug model routing decisions",
+    audience: "maintainer"
+  },
+  {
+    command: "fitness-audit",
+    description: "Run CLI orchestration fitness score audit",
+    audience: "maintainer"
+  },
+  {
+    command: "system-review",
+    description: "Automated system review (5-phase checklist)",
+    audience: "maintainer"
+  },
+  {
+    command: "sprint",
+    description: "Automated sprint planning from open issues",
+    audience: "maintainer"
+  },
+  {
+    command: "evaluate",
+    description: "Self-evaluation of codebase components",
+    audience: "maintainer"
+  },
+  {
+    command: "issue",
+    description: "Issue template validation and management",
+    audience: "maintainer"
+  },
+  {
+    command: "validation",
+    description: "Learning validation dashboard",
+    audience: "maintainer"
+  },
+  {
+    command: "learning-metrics",
+    description: "Aggregated learning metrics dashboard",
+    audience: "maintainer"
+  },
+  {
+    command: "swe-bench",
+    description: "Run SWE-bench evaluation benchmark",
+    audience: "maintainer"
+  },
+  {
+    command: "atbench",
+    description: "Run ATBench trajectory-safety evaluation",
+    audience: "maintainer"
+  },
+  {
+    command: "visualize",
+    description: "Generate Mermaid diagrams and ASCII dashboards",
+    audience: "maintainer"
+  },
+  {
+    command: "health",
+    description: "Swarm health metrics dashboard",
+    audience: "maintainer"
+  },
+  {
+    command: "release-notes",
+    description: "Generate release notes from git commits",
+    audience: "maintainer"
+  },
+  {
+    command: "release-validate",
+    description: "Run expert swarm validation for releases",
+    audience: "maintainer"
+  },
+  {
+    command: "release-announce",
+    description: "Generate release announcements (blog, social)",
+    audience: "maintainer"
+  }
+];
+function filterCatalog(showAll) {
+  if (showAll) return COMMAND_CATALOG;
+  return COMMAND_CATALOG.filter((e) => e.audience !== "maintainer");
+}
+function groupByAudience(entries) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const existing = groups.get(entry.audience) ?? [];
+    existing.push(entry);
+    groups.set(entry.audience, existing);
+  }
+  return groups;
+}
+var AUDIENCE_HEADINGS = {
+  essential: "Essential \u2014 install, configure, run",
+  advanced: "Advanced \u2014 day-to-day extras",
+  maintainer: "Maintainer \u2014 benchmarks, releases, deep diagnostics"
+};
+function renderCommandsSection(showAll) {
+  const filtered = filterCatalog(showAll);
+  const groups = groupByAudience(filtered);
+  const lines = [];
+  const order = showAll ? ["essential", "advanced", "maintainer"] : ["essential", "advanced"];
+  for (const audience of order) {
+    const entries = groups.get(audience);
+    if (entries === void 0 || entries.length === 0) continue;
+    lines.push(`  ${AUDIENCE_HEADINGS[audience]}`);
+    for (const entry of entries) {
+      lines.push(`    ${entry.command.padEnd(16)} ${entry.description}`);
+    }
+    lines.push("");
+  }
+  if (!showAll) {
+    lines.push("  Run with --all to show maintainer commands (benchmarks, release tooling).");
+  }
+  return lines.join("\n").replace(/\n+$/, "");
+}
+
 // src/cli-help-text.ts
 var HELP_TEXT = `
 nexus-agents - Intelligent orchestration platform for AI coding tools
@@ -17294,6 +17351,15 @@ EXAMPLES:
 
 For more information, visit: https://github.com/williamzujkowski/nexus-agents
 `.trim();
+var COMMANDS_BLOCK_RE = /COMMANDS:\n([\s\S]*?)\n\nOPTIONS:/;
+function renderHelp(opts) {
+  if (opts.all) return HELP_TEXT;
+  const replacement = renderCommandsSection(false);
+  return HELP_TEXT.replace(COMMANDS_BLOCK_RE, `COMMANDS:
+${replacement}
+
+OPTIONS:`);
+}
 
 // src/cli-types.ts
 var EXIT_CODES = {
@@ -17322,6 +17388,11 @@ var PARSE_ARGS_CONFIG = {
       type: "boolean",
       default: false
     },
+    // Tiered --help output (Issue #2135): `--help --all` unhides maintainer commands
+    all: {
+      type: "boolean",
+      default: false
+    },
     mode: {
       type: "string",
       short: "m",
@@ -22614,8 +22685,9 @@ async function handleValidateCommand(args) {
 }
 
 // src/cli-commands.ts
-function printHelp() {
-  process.stdout.write(HELP_TEXT + "\n");
+function printHelp(args) {
+  const all = args?.options.all ?? false;
+  process.stdout.write(renderHelp({ all }) + "\n");
 }
 function printVersion() {
   process.stdout.write(`nexus-agents v${VERSION}
@@ -22652,7 +22724,7 @@ var SYNC_COMMAND_HANDLERS = {
 };
 function handleSyncCommand(args) {
   if (args.command === "help") {
-    printHelp();
+    printHelp(args);
     process.exit(EXIT_CODES.SUCCESS);
   }
   if (args.command === "version") {
@@ -23067,6 +23139,7 @@ function buildOptions(values) {
     version: values.version,
     verbose: values.verbose,
     interactive: values.interactive,
+    all: values.all,
     mode: detectionResult.mode,
     force: values.force,
     format: values.format,