fix(cli): suggest the real command instead of a plugin that does not exist

src/cli.test.ts

@@ -1191,7 +1191,8 @@ name: 'search',
 
       errors.length = 0;
       createProgram('', '').parse(['browser', 'nonsense'], { from: 'user' });
-      expect(errors.join('\n')).toBe("error: unknown command 'nonsense'");
+      expect(errors.join('\n')).toContain("error: unknown command 'nonsense'");
+      expect(errors.join('\n')).toContain('Valid webcmd browser commands:');
     } finally {
       spy.mockRestore();
       process.exitCode = previousExitCode;

src/cli.ts

@@ -54,7 +54,8 @@ import type { BrowserWindowMode } from './runtime.js';
 import { configureRootCommandSurface } from './root-command-surface.js';
 import { validateRawBrowserSession } from './hosted/browser-args.js';
 import { LocalBrowserSessionStore, requireSessionIdShape, type BrowserSessionListRow } from './browser/sessions.js';
-import { missingPluginGuidance, PLUGINS_DIR } from './discovery.js';
+import { PLUGINS_DIR } from './discovery.js';
+import { unknownRootCommandMessage, unknownSubcommandMessage } from './command-suggest.js';
 import { loadBrowserRunSource } from './browser/run/input.js';
 import { BrowserRunError } from './browser/run/types.js';
 import { classifyCommandOrigin, formatCommandOrigin } from './command-origin.js';
@@ -83,22 +84,6 @@ function parseSessionListLimit(value: string): number {
   return parsed;
 }
 
-function rootCommandSuggestion(name: string): string | undefined {
-  const canonical: Record<string, string> = {
-    catalog: `${CLI_COMMAND} plugin catalog list`,
-    catalogs: `${CLI_COMMAND} plugin catalog list`,
-    command: `${CLI_COMMAND} list`,
-    commands: `${CLI_COMMAND} list`,
-    cmds: `${CLI_COMMAND} list`,
-    ls: `${CLI_COMMAND} list`,
-    marketplace: `${CLI_COMMAND} plugin search <query>`,
-    plugins: `${CLI_COMMAND} plugin list`,
-    pluginlist: `${CLI_COMMAND} plugin list`,
-    search: `${CLI_COMMAND} plugin search <query>`,
-  };
-  return canonical[name.toLowerCase()];
-}
-
 type BrowserNetworkItem = {
   url: string;
   method: string;
@@ -954,20 +939,8 @@ export function createProgram(BUILTIN_CLIS: string, USER_CLIS: string, pluginsDi
     .description('Run Playwright programs against an explicit browser Session');
   const originalBrowserDescription = browser.description();
 
-  // Retired browser subcommands. `fork` was a duplicate of `adapter override`
-  // that never appeared in the docs; commander's bare "unknown command" leaves
-  // the caller with no way to find the replacement, so name it.
-  const RETIRED_BROWSER_SUBCOMMANDS: Record<string, string> = {
-    fork: `${CLI_COMMAND} adapter override <site>/<command>`,
-  };
-  browser.on('command:*', (operands: string[]) => {
-    const name = operands[0]!;
-    const replacement = RETIRED_BROWSER_SUBCOMMANDS[name];
-    console.error(replacement
-      ? `error: '${CLI_COMMAND} browser ${name}' was removed. Use: ${replacement}`
-      : `error: unknown command '${name}'`);
-    process.exitCode = EXIT_CODES.USAGE_ERROR;
-  });
+  // Unknown `browser` subcommands (including the retired `fork`) are handled by
+  // the shared namespace handler installed at the end of createProgram.
 
   // ── Init (adapter scaffolding) ──
 
@@ -2231,19 +2204,28 @@ cli({
   // Security: do NOT auto-discover and register arbitrary system binaries.
   // Only explicitly registered external CLIs are allowed.
 
+  // Error output goes to stderr only. `outputHelp()` used to dump the whole root
+  // help to stdout here, which with `--json` in argv looked like a successful
+  // JSON response to anything parsing stdout.
   program.on('command:*', (operands: string[]) => {
-    const binary = operands[0]!;
-    const suggestion = rootCommandSuggestion(binary);
-    if (suggestion) {
-      console.error(`Unknown command "${binary}".\nDid you mean: ${suggestion}`);
-      process.exitCode = EXIT_CODES.USAGE_ERROR;
-      return;
-    }
-    console.error(missingPluginGuidance(binary));
-    program.outputHelp();
+    console.error(unknownRootCommandMessage(program, operands[0]!));
     process.exitCode = EXIT_CODES.USAGE_ERROR;
   });
 
+  // Same treatment one level down, for the built-in namespaces. Site adapter
+  // groups are left on Commander's own suggestion path so hosted mode, which
+  // has no Command tree to match against, stays byte-compatible with local.
+  const SUGGEST_NAMESPACES = new Set([
+    'adapter', 'plugin', 'session', 'profile', 'daemon', 'external', 'browser', 'site', 'auth', 'skills',
+  ]);
+  for (const namespace of program.commands) {
+    if (namespace.commands.length === 0 || !SUGGEST_NAMESPACES.has(namespace.name())) continue;
+    namespace.on('command:*', (operands: string[]) => {
+      console.error(unknownSubcommandMessage(namespace, operands[0]!));
+      process.exitCode = EXIT_CODES.USAGE_ERROR;
+    });
+  }
+
   return program;
 }
 

src/command-suggest.test.ts

@@ -0,0 +1,117 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { describe, expect, it, vi } from 'vitest';
+import { createProgram } from './cli.js';
+import { editDistance, unknownRootCommandMessage, unknownSubcommandMessage } from './command-suggest.js';
+
+function namespaceOf(program: ReturnType<typeof createProgram>, name: string) {
+  return program.commands.find(command => command.name() === name)!;
+}
+
+describe('editDistance', () => {
+  it('counts single edits', () => {
+    expect(editDistance('adapters', 'adapter')).toBe(1);
+    expect(editDistance('fetch', 'fetch')).toBe(0);
+    expect(editDistance('kitten', 'sitting')).toBe(3);
+  });
+});
+
+describe('unknown root command', () => {
+  it('suggests the real command instead of a plugin hunt for a near miss', () => {
+    const message = unknownRootCommandMessage(createProgram('', ''), 'adapters');
+
+    expect(message).toContain('Unknown command "adapters".');
+    expect(message).toContain('webcmd adapter');
+    expect(message).not.toContain('plugin search');
+  });
+
+  it('reaches subcommand leaves so a bare verb finds its namespace', () => {
+    const message = unknownRootCommandMessage(createProgram('', ''), 'fetch');
+
+    expect(message).toContain('Did you mean: webcmd web fetch');
+  });
+
+  it('keeps the hardcoded intent overrides ahead of edit distance', () => {
+    const message = unknownRootCommandMessage(createProgram('', ''), 'marketplace');
+
+    expect(message).toContain('Did you mean: webcmd plugin search <query>');
+  });
+
+  it('still guides a genuinely unknown token to plugin search', () => {
+    const message = unknownRootCommandMessage(createProgram('', ''), 'zzzqqqwww');
+
+    expect(message).toContain('Site "zzzqqqwww" is not installed.');
+    expect(message).toContain('webcmd plugin search zzzqqqwww');
+  });
+
+  it('says the adapter failed to load when its directory is on disk', () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-suggest-'));
+    const installed = path.join(root, 'zzzqqqwww');
+    fs.mkdirSync(installed);
+    try {
+      const message = unknownRootCommandMessage(createProgram('', ''), 'zzzqqqwww', [root]);
+
+      expect(message).toContain(`Site "zzzqqqwww" is installed at ${installed}`);
+      expect(message).toContain('failed to load');
+      expect(message).not.toContain('is not installed');
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('unknown namespace subcommand', () => {
+  it('suggests adapter status and lists the valid subcommands', () => {
+    const message = unknownSubcommandMessage(namespaceOf(createProgram('', ''), 'adapter'), 'list');
+
+    expect(message).toContain("error: unknown command 'list'");
+    expect(message).toContain('Did you mean: webcmd adapter status');
+    expect(message).toContain('Valid webcmd adapter commands: override, path, reset, source, status');
+  });
+
+  it('lists valid subcommands even when nothing is close enough to suggest', () => {
+    const message = unknownSubcommandMessage(namespaceOf(createProgram('', ''), 'plugin'), 'zzzqqqwww');
+
+    expect(message).toContain('Valid webcmd plugin commands: catalog, create, install, list, search, uninstall, update');
+  });
+
+  it('names the replacement for a retired subcommand', () => {
+    const message = unknownSubcommandMessage(namespaceOf(createProgram('', ''), 'browser'), 'fork');
+
+    expect(message).toContain('webcmd adapter override <site>/<command>');
+  });
+});
+
+describe('error paths write nothing to stdout', () => {
+  async function captureStdout(argv: string[]): Promise<{ stdout: string; exitCode: unknown }> {
+    const program = createProgram('', '');
+    const previousExitCode = process.exitCode;
+    let stdout = '';
+    const write = vi.spyOn(process.stdout, 'write').mockImplementation((chunk: any) => {
+      stdout += String(chunk);
+      return true;
+    });
+    const log = vi.spyOn(console, 'log').mockImplementation((...args: unknown[]) => {
+      stdout += args.join(' ');
+    });
+    const stderr = vi.spyOn(console, 'error').mockImplementation(() => {});
+    try {
+      await program.parseAsync(argv, { from: 'user' });
+      return { stdout, exitCode: process.exitCode };
+    } finally {
+      process.exitCode = previousExitCode;
+      write.mockRestore();
+      log.mockRestore();
+      stderr.mockRestore();
+    }
+  }
+
+  it('does not print root help to stdout for an unknown root command', async () => {
+    expect(await captureStdout(['adapters', '--json'])).toEqual({ stdout: '', exitCode: 2 });
+  });
+
+  it('does not print help to stdout for an unknown subcommand', async () => {
+    expect(await captureStdout(['adapter', 'list', 'rest'])).toEqual({ stdout: '', exitCode: 2 });
+  });
+});

src/command-suggest.ts

@@ -0,0 +1,170 @@
+/**
+ * "Did you mean" engine for unknown commands.
+ *
+ * A mistyped token used to fall straight through to `missingPluginGuidance`,
+ * telling the caller to search a plugin marketplace for a plugin that cannot
+ * exist (`webcmd adapters` → "Search: webcmd plugin search adapters"). Agents
+ * burned turns on those hunts. Everything registered on the program — built-in
+ * namespaces, their leaves, installed site adapters, external CLIs — is already
+ * in memory when the miss happens, so match against it instead.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { Command } from 'commander';
+import { CLI_COMMAND } from './brand.js';
+import { missingPluginGuidance, PLUGINS_DIR, USER_CLIS_DIR } from './discovery.js';
+
+/**
+ * High-priority overrides: intent that edit distance cannot infer.
+ * `marketplace` is nowhere near `plugin search`, but it is what people type.
+ */
+const CANONICAL_ROOT: Record<string, string> = {
+  catalog: `${CLI_COMMAND} plugin catalog list`,
+  catalogs: `${CLI_COMMAND} plugin catalog list`,
+  command: `${CLI_COMMAND} list`,
+  commands: `${CLI_COMMAND} list`,
+  cmds: `${CLI_COMMAND} list`,
+  ls: `${CLI_COMMAND} list`,
+  marketplace: `${CLI_COMMAND} plugin search <query>`,
+  plugins: `${CLI_COMMAND} plugin list`,
+  pluginlist: `${CLI_COMMAND} plugin list`,
+  search: `${CLI_COMMAND} plugin search <query>`,
+};
+
+/** Subcommands that were removed and whose replacement lives elsewhere. */
+const RETIRED_SUBCOMMANDS: Record<string, string> = {
+  'browser fork': `${CLI_COMMAND} adapter override <site>/<command>`,
+};
+
+/** Same idea as CANONICAL_ROOT, one level down: intent, not spelling. */
+const CANONICAL_SUB: Record<string, string> = {
+  'adapter list': `${CLI_COMMAND} adapter status`,
+  'adapter ls': `${CLI_COMMAND} adapter status`,
+  'plugin ls': `${CLI_COMMAND} plugin list`,
+  'session ls': `${CLI_COMMAND} session list`,
+  'profile ls': `${CLI_COMMAND} profile list`,
+  'external ls': `${CLI_COMMAND} external list`,
+};
+
+/** Levenshtein distance, two-row variant. */
+export function editDistance(a: string, b: string): number {
+  if (a === b) return 0;
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i];
+    for (let j = 1; j <= b.length; j++) {
+      row[j] = Math.min(
+        prev[j]! + 1,
+        row[j - 1]! + 1,
+        prev[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    prev = row;
+  }
+  return prev[b.length]!;
+}
+
+/** A command the user could have meant: the token they'd type, and its full path. */
+type Candidate = { token: string; commandPath: string };
+
+function collect(parent: Command, prefix: string, depth: number, out: Candidate[]): void {
+  for (const child of parent.commands) {
+    const name = child.name();
+    const commandPath = prefix ? `${prefix} ${name}` : name;
+    out.push({ token: name, commandPath });
+    for (const alias of child.aliases()) out.push({ token: alias, commandPath });
+    if (depth > 0) collect(child, commandPath, depth - 1, out);
+  }
+}
+
+export function commandCandidates(root: Command, prefix = ''): Candidate[] {
+  const out: Candidate[] = [];
+  collect(root, prefix, 2, out);
+  return out;
+}
+
+/**
+ * Best matches for `token`, closest first, at most 3.
+ * Only long tokens tolerate two edits: at distance 2 a short token matches half
+ * the command surface, and a confidently wrong suggestion costs more than none.
+ */
+export function suggestCommands(token: string, candidates: Candidate[]): string[] {
+  const needle = token.toLowerCase();
+  const threshold = needle.length >= 8 ? 2 : 1;
+  const best = new Map<string, number>();
+  for (const candidate of candidates) {
+    const distance = editDistance(needle, candidate.token.toLowerCase());
+    if (distance > threshold) continue;
+    const existing = best.get(candidate.commandPath);
+    if (existing === undefined || distance < existing) best.set(candidate.commandPath, distance);
+  }
+  return [...best.entries()]
+    .sort((a, b) => a[1] - b[1] || a[0].length - b[0].length || a[0].localeCompare(b[0]))
+    .slice(0, 3)
+    .map(([commandPath]) => commandPath);
+}
+
+function formatSuggestions(paths: string[]): string {
+  if (paths.length === 1) return `Did you mean: ${CLI_COMMAND} ${paths[0]}`;
+  return [`Did you mean one of:`, ...paths.map(p => `  ${CLI_COMMAND} ${p}`)].join('\n');
+}
+
+/**
+ * `~/.webcmd/clis/<site>` or `~/.webcmd/plugins/<site>` exists, so "not
+ * installed" would be a lie — the adapter is on disk and failed to register.
+ */
+function installedDirFor(site: string, dirs: string[]): string | undefined {
+  if (!/^[a-zA-Z0-9_.-]+$/.test(site) || site.startsWith('.')) return undefined;
+  for (const dir of dirs) {
+    const candidate = path.join(dir, site);
+    try {
+      if (fs.statSync(candidate).isDirectory()) return candidate;
+    } catch { /* not there */ }
+  }
+  return undefined;
+}
+
+/** Message for an unknown root token. Caller writes it to stderr. */
+export function unknownRootCommandMessage(
+  program: Command,
+  name: string,
+  installDirs: string[] = [PLUGINS_DIR, USER_CLIS_DIR],
+): string {
+  const canonical = CANONICAL_ROOT[name.toLowerCase()];
+  if (canonical) return `Unknown command "${name}".\nDid you mean: ${canonical}`;
+
+  const suggestions = suggestCommands(name, commandCandidates(program));
+  if (suggestions.length > 0) return `Unknown command "${name}".\n${formatSuggestions(suggestions)}`;
+
+  const installedDir = installedDirFor(name, installDirs);
+  if (installedDir) {
+    return [
+      `Site "${name}" is installed at ${installedDir} but registered no commands.`,
+      'The adapter failed to load; this is not a missing plugin.',
+      `Re-run with WEBCMD_VERBOSE=1 to see the load error, then: ${CLI_COMMAND} plugin update ${name}`,
+    ].join('\n');
+  }
+  return missingPluginGuidance(name);
+}
+
+/** Message for an unknown subcommand inside a namespace. Caller writes it to stderr. */
+export function unknownSubcommandMessage(namespace: Command, name: string): string {
+  const nsPath = namespace.name();
+  const key = `${nsPath} ${name.toLowerCase()}`;
+  const retired = RETIRED_SUBCOMMANDS[key];
+  const lines = [retired
+    ? `error: '${CLI_COMMAND} ${nsPath} ${name}' was removed. Use: ${retired}`
+    : `error: unknown command '${name}'`];
+  if (!retired) {
+    const canonical = CANONICAL_SUB[key];
+    if (canonical) lines.push(`Did you mean: ${canonical}`);
+    else {
+      const suggestions = suggestCommands(name, commandCandidates(namespace, nsPath));
+      if (suggestions.length > 0) lines.push(formatSuggestions(suggestions));
+    }
+  }
+  const valid = [...new Set(namespace.commands.map(child => child.name()))].sort();
+  if (valid.length > 0) lines.push(`Valid ${CLI_COMMAND} ${nsPath} commands: ${valid.join(', ')}`);
+  return lines.join('\n');
+}