@jackwener/opencli 1.7.0 → 1.7.2

package/dist/src/commanderAdapter.js

@@ -9,13 +9,13 @@
  *
  * All execution logic lives in execution.ts.
  */
-import chalk from 'chalk';
+import { log } from './logger.js';
+import yaml from 'js-yaml';
 import { fullName, getRegistry } from './registry.js';
 import { formatRegistryHelpText } from './serialization.js';
 import { render as renderOutput } from './output.js';
-import { executeCommand } from './execution.js';
-import { CliError, EXIT_CODES, ERROR_ICONS, getErrorMessage, BrowserConnectError, AuthRequiredError, TimeoutError, SelectorError, EmptyResultError, ArgumentError, AdapterLoadError, CommandExecutionError, } from './errors.js';
-import { getDaemonHealth } from './browser/daemon-client.js';
+import { executeCommand, prepareCommandArgs } from './execution.js';
+import { CliError, EXIT_CODES, ArgumentError, toEnvelope, } from './errors.js';
 import { isDiagnosticEnabled } from './diagnostic.js';
 export function normalizeArgValue(argType, value, name) {
     if (argType !== 'bool' && argType !== 'boolean')
@@ -71,11 +71,11 @@ export function registerCommandToProgram(siteCmd, cmd) {
         // ── Execute + render ────────────────────────────────────────────────
         try {
             // ── Collect kwargs ────────────────────────────────────────────────
-            const kwargs = {};
+            const rawKwargs = {};
             for (let i = 0; i < positionalArgs.length; i++) {
                 const v = actionArgs[i];
                 if (v !== undefined)
-                    kwargs[positionalArgs[i].name] = v;
+                    rawKwargs[positionalArgs[i].name] = v;
             }
             for (const arg of cmd.args) {
                 if (arg.positional)
@@ -83,9 +83,9 @@ export function registerCommandToProgram(siteCmd, cmd) {
                 const camelName = arg.name.replace(/-([a-z])/g, (_m, ch) => ch.toUpperCase());
                 const v = optionsRecord[arg.name] ?? optionsRecord[camelName];
                 if (v !== undefined)
-                    kwargs[arg.name] = normalizeArgValue(arg.type, v, arg.name);
+                    rawKwargs[arg.name] = normalizeArgValue(arg.type, v, arg.name);
             }
-            cmd.validateArgs?.(kwargs);
+            const kwargs = prepareCommandArgs(cmd, rawKwargs);
             const verbose = optionsRecord.verbose === true;
             let format = typeof optionsRecord.format === 'string' ? optionsRecord.format : 'table';
             const formatExplicit = subCmd.getOptionValueSource('format') === 'cli';
@@ -94,9 +94,9 @@ export function registerCommandToProgram(siteCmd, cmd) {
             if (cmd.deprecated) {
                 const message = typeof cmd.deprecated === 'string' ? cmd.deprecated : `${fullName(cmd)} is deprecated.`;
                 const replacement = cmd.replacedBy ? ` Use ${cmd.replacedBy} instead.` : '';
-                console.error(chalk.yellow(`Deprecated: ${message}${replacement}`));
+                log.warn(`Deprecated: ${message}${replacement}`);
             }
-            const result = await executeCommand(cmd, kwargs, verbose);
+            const result = await executeCommand(cmd, kwargs, verbose, { prepared: true });
             if (result === null || result === undefined) {
                 return;
             }
@@ -105,7 +105,7 @@ export function registerCommandToProgram(siteCmd, cmd) {
                 format = resolved.defaultFormat;
             }
             if (verbose && (!result || (Array.isArray(result) && result.length === 0))) {
-                console.error(chalk.yellow('[Verbose] Warning: Command returned an empty result.'));
+                log.warn('Command returned an empty result.');
             }
             renderOutput(result, {
                 fmt: format,
@@ -118,162 +118,37 @@ export function registerCommandToProgram(siteCmd, cmd) {
             });
         }
         catch (err) {
-            await renderError(err, fullName(cmd), optionsRecord.verbose === true);
+            renderError(err, fullName(cmd), optionsRecord.verbose === true);
             process.exitCode = resolveExitCode(err);
         }
     });
 }
-// ── Error classification ─────────────────────────────────────────────────────
-const ISSUES_URL = 'https://github.com/jackwener/opencli/issues';
-const GENERIC_ERROR_MAP = {
-    auth: { icon: '🔒', exitCode: EXIT_CODES.NOPERM, hint: 'Open Chrome or Chromium, log in to the target site, then retry.' },
-    http: { icon: '🌐', exitCode: EXIT_CODES.GENERIC_ERROR, hint: 'Check your login status, or the site may be temporarily unavailable.' },
-    'not-found': { icon: '📭', exitCode: EXIT_CODES.EMPTY_RESULT, hint: 'The resource was not found. The adapter or page structure may have changed.' },
-    other: { icon: '💥', exitCode: EXIT_CODES.GENERIC_ERROR, hint: '' },
-};
-/** Pattern-based classifier for untyped errors thrown by adapters. */
-function classifyGenericError(msg) {
-    const m = msg.toLowerCase();
-    let kind = 'other';
-    if (/not logged in|login required|please log in|未登录|请先登录|authentication required|cookie expired/.test(m))
-        kind = 'auth';
-    else if (/\b(status[: ]+)?[45]\d{2}\b|http[/ ][45]\d{2}/.test(m))
-        kind = 'http';
-    else if (/not found|未找到|could not find|no .+ found/.test(m))
-        kind = 'not-found';
-    return { kind, ...GENERIC_ERROR_MAP[kind] };
-}
 // ── Exit code resolution ─────────────────────────────────────────────────────
 function resolveExitCode(err) {
     if (err instanceof CliError)
         return err.exitCode;
-    return classifyGenericError(getErrorMessage(err)).exitCode;
-}
-/** Render a status line for BrowserConnectError based on real-time or kind-derived state. */
-function renderBridgeStatus(running, extensionConnected) {
-    const ok = chalk.green('✓');
-    const fail = chalk.red('✗');
-    console.error(`  Daemon    ${running ? ok : fail} ${running ? 'running' : 'not running'}`);
-    console.error(`  Extension ${extensionConnected ? ok : fail} ${extensionConnected ? 'connected' : 'not connected'}`);
-    console.error();
-    if (!running) {
-        console.error(chalk.yellow('  Run the command again — daemon should auto-start.'));
-        console.error(chalk.dim('  Still failing? Run: opencli doctor'));
-    }
-    else if (!extensionConnected) {
-        console.error(chalk.yellow('  Install the Browser Bridge extension to continue:'));
-        console.error(chalk.dim('    1. Download from github.com/jackwener/opencli/releases'));
-        console.error(chalk.dim('    2. chrome://extensions → Enable Developer Mode → Load unpacked'));
-    }
-    else {
-        console.error(chalk.yellow('  Connection failed despite extension being active.'));
-        console.error(chalk.dim('  Try reloading the extension, or run: opencli doctor'));
-    }
+    return EXIT_CODES.GENERIC_ERROR;
 }
+// ── Error rendering ─────────────────────────────────────────────────────────
 /** Emit AutoFix hint for repairable adapter errors (skipped if already in diagnostic mode). */
-function emitAutoFixHint(cmdName) {
+function emitAutoFixHint(envelope, cmdName) {
     if (isDiagnosticEnabled())
-        return; // Already collecting diagnostics, don't repeat
-    console.error();
-    console.error(chalk.cyan('💡 AutoFix: re-run with OPENCLI_DIAGNOSTIC=1 for repair context.'));
-    console.error(chalk.dim(`    OPENCLI_DIAGNOSTIC=1 ${cmdName}`));
+        return envelope;
+    return envelope + `# AutoFix: re-run with OPENCLI_DIAGNOSTIC=1 for repair context\n# OPENCLI_DIAGNOSTIC=1 ${cmdName}\n`;
 }
-async function renderError(err, cmdName, verbose) {
-    // ── BrowserConnectError: real-time diagnosis, kind as fallback ────────
-    if (err instanceof BrowserConnectError) {
-        console.error(chalk.red(`🔌 ${err.message}`));
-        if (err.hint)
-            console.error(chalk.yellow(`→ ${err.hint}`));
-        console.error();
-        try {
-            const health = await getDaemonHealth({ timeout: 300 });
-            renderBridgeStatus(health.state !== 'stopped', health.state === 'ready');
-        }
-        catch (_statusErr) {
-            // getDaemonHealth itself failed — derive best-guess state from kind.
-            const running = err.kind !== 'daemon-not-running';
-            const extensionConnected = err.kind === 'command-failed';
-            renderBridgeStatus(running, extensionConnected);
-        }
-        return;
-    }
-    // ── AuthRequiredError ─────────────────────────────────────────────────
-    if (err instanceof AuthRequiredError) {
-        console.error(chalk.red(`🔒 Not logged in to ${err.domain}`));
-        // Respect custom hints set by the adapter; fall back to generic guidance.
-        console.error(chalk.yellow(`→ ${err.hint ?? `Open Chrome or Chromium and log in to https://${err.domain}, then retry.`}`));
-        return;
-    }
-    // ── TimeoutError ──────────────────────────────────────────────────────
-    if (err instanceof TimeoutError) {
-        console.error(chalk.red(`⏱  ${err.message}`));
-        console.error(chalk.yellow('→ Try again, or raise the limit:'));
-        console.error(chalk.dim(`    OPENCLI_BROWSER_COMMAND_TIMEOUT=60 ${cmdName}`));
-        return;
-    }
-    // ── SelectorError / EmptyResultError: likely outdated adapter ─────────
-    if (err instanceof SelectorError || err instanceof EmptyResultError) {
-        const icon = ERROR_ICONS[err.code] ?? '⚠️';
-        console.error(chalk.red(`${icon} ${err.message}`));
-        console.error(chalk.yellow(`→ ${err.hint ?? 'The page structure may have changed — this adapter may be outdated.'}`));
-        console.error(chalk.dim(`  Debug:  ${cmdName} --verbose`));
-        console.error(chalk.dim(`  Report: ${ISSUES_URL}`));
-        emitAutoFixHint(cmdName);
-        return;
-    }
-    // ── ArgumentError ─────────────────────────────────────────────────────
-    if (err instanceof ArgumentError) {
-        console.error(chalk.red(`❌ ${err.message}`));
-        if (err.hint)
-            console.error(chalk.yellow(`→ ${err.hint}`));
-        return;
-    }
-    // ── AdapterLoadError ──────────────────────────────────────────────────
-    if (err instanceof AdapterLoadError) {
-        console.error(chalk.red(`📦 ${err.message}`));
-        if (err.hint)
-            console.error(chalk.yellow(`→ ${err.hint}`));
-        return;
-    }
-    // ── CommandExecutionError ─────────────────────────────────────────────
-    if (err instanceof CommandExecutionError) {
-        console.error(chalk.red(`💥 ${err.message}`));
-        if (err.hint) {
-            console.error(chalk.yellow(`→ ${err.hint}`));
-        }
-        else {
-            console.error(chalk.dim(`  Add --verbose for details, or report: ${ISSUES_URL}`));
-        }
-        return;
-    }
-    // ── Other typed CliError (fallback for future codes) ──────────────────
-    if (err instanceof CliError) {
-        const icon = ERROR_ICONS[err.code] ?? '⚠️';
-        console.error(chalk.red(`${icon} ${err.message}`));
-        if (err.hint)
-            console.error(chalk.yellow(`→ ${err.hint}`));
-        return;
-    }
-    // ── Generic Error from adapters: classify by message pattern ──────────
-    const msg = getErrorMessage(err);
-    const classified = classifyGenericError(msg);
-    if (classified.kind !== 'other') {
-        console.error(chalk.red(`${classified.icon} ${msg}`));
-        console.error(chalk.yellow(`→ ${classified.hint}`));
-        if (classified.kind === 'not-found')
-            console.error(chalk.dim(`  Report: ${ISSUES_URL}`));
-        if (classified.kind === 'not-found')
-            emitAutoFixHint(cmdName);
-        return;
-    }
-    // ── Unknown error: show stack in verbose mode ─────────────────────────
+function renderError(err, cmdName, verbose) {
+    const envelope = toEnvelope(err);
+    // In verbose mode, include stack trace for debugging
     if (verbose && err instanceof Error && err.stack) {
-        console.error(chalk.red(err.stack));
+        envelope.error.stack = err.stack;
     }
-    else {
-        console.error(chalk.red(`💥 Unexpected error: ${msg}`));
-        console.error(chalk.dim(`  Run with --verbose for details, or report: ${ISSUES_URL}`));
+    let output = yaml.dump(envelope, { sortKeys: false, lineWidth: 120, noRefs: true });
+    // Append AutoFix hint for repairable errors
+    const code = envelope.error.code;
+    if (code === 'SELECTOR' || code === 'EMPTY_RESULT' || code === 'ADAPTER_LOAD' || code === 'UNKNOWN') {
+        output = emitAutoFixHint(output, cmdName);
     }
+    process.stderr.write(output);
 }
 /**
  * Register all commands from the registry onto a Commander program.

package/dist/src/commanderAdapter.test.js

@@ -5,9 +5,13 @@ const { mockExecuteCommand, mockRenderOutput } = vi.hoisted(() => ({
     mockExecuteCommand: vi.fn(),
     mockRenderOutput: vi.fn(),
 }));
-vi.mock('./execution.js', () => ({
-    executeCommand: mockExecuteCommand,
-}));
+vi.mock('./execution.js', async () => {
+    const actual = await vi.importActual('./execution.js');
+    return {
+        ...actual,
+        executeCommand: mockExecuteCommand,
+    };
+});
 vi.mock('./output.js', () => ({
     render: mockRenderOutput,
 }));
@@ -164,7 +168,33 @@ describe('commanderAdapter command aliases', () => {
         const siteCmd = program.command('notebooklm');
         registerCommandToProgram(siteCmd, cmd);
         await program.parseAsync(['node', 'opencli', 'notebooklm', 'metadata']);
-        expect(mockExecuteCommand).toHaveBeenCalledWith(cmd, {}, false);
+        expect(mockExecuteCommand).toHaveBeenCalledWith(cmd, {}, false, { prepared: true });
+    });
+});
+describe('commanderAdapter validation preparation', () => {
+    beforeEach(() => {
+        mockExecuteCommand.mockReset();
+        mockExecuteCommand.mockResolvedValue([]);
+        mockRenderOutput.mockReset();
+        delete process.env.OPENCLI_VERBOSE;
+        process.exitCode = undefined;
+    });
+    it('prepares args once before dispatching to executeCommand', async () => {
+        const validateArgs = vi.fn();
+        const program = new Command();
+        const siteCmd = program.command('test');
+        registerCommandToProgram(siteCmd, {
+            site: 'test',
+            name: 'run',
+            description: 'Run test command',
+            browser: false,
+            args: [{ name: 'count', default: '1', help: 'Count' }],
+            validateArgs,
+            func: vi.fn(),
+        });
+        await program.parseAsync(['node', 'opencli', 'test', 'run']);
+        expect(validateArgs).toHaveBeenCalledTimes(1);
+        expect(mockExecuteCommand).toHaveBeenCalledWith(expect.objectContaining({ site: 'test', name: 'run' }), { count: '1' }, false, { prepared: true });
     });
 });
 describe('commanderAdapter default formats', () => {
@@ -200,7 +230,7 @@ describe('commanderAdapter default formats', () => {
         expect(mockRenderOutput).toHaveBeenCalledWith([{ response: 'hello' }], expect.objectContaining({ fmt: 'json' }));
     });
 });
-describe('commanderAdapter empty result hints', () => {
+describe('commanderAdapter error envelope output', () => {
     const cmd = {
         site: 'xiaohongshu',
         name: 'note',
@@ -217,28 +247,30 @@ describe('commanderAdapter empty result hints', () => {
         delete process.env.OPENCLI_VERBOSE;
         process.exitCode = undefined;
     });
-    it('prints the adapter hint instead of the generic outdated-adapter message', async () => {
+    it('outputs YAML error envelope with adapter hint to stderr', async () => {
         const program = new Command();
         const siteCmd = program.command('xiaohongshu');
         registerCommandToProgram(siteCmd, cmd);
-        const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
         mockExecuteCommand.mockRejectedValueOnce(new EmptyResultError('xiaohongshu/note', 'Pass the full search_result URL with xsec_token instead of a bare note ID.'));
         await program.parseAsync(['node', 'opencli', 'xiaohongshu', 'note', '69ca3927000000001a020fd5']);
-        const output = errorSpy.mock.calls.flat().join('\n');
+        const output = stderrSpy.mock.calls.map(c => String(c[0])).join('');
+        expect(output).toContain('ok: false');
+        expect(output).toContain('code: EMPTY_RESULT');
         expect(output).toContain('xsec_token');
-        expect(output).not.toContain('this adapter may be outdated');
-        errorSpy.mockRestore();
+        stderrSpy.mockRestore();
     });
-    it('prints selector-specific hints too', async () => {
+    it('outputs YAML error envelope for selector errors', async () => {
         const program = new Command();
         const siteCmd = program.command('xiaohongshu');
         registerCommandToProgram(siteCmd, cmd);
-        const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
         mockExecuteCommand.mockRejectedValueOnce(new SelectorError('.note-title', 'The note title selector no longer matches the current page.'));
         await program.parseAsync(['node', 'opencli', 'xiaohongshu', 'note', '69ca3927000000001a020fd5']);
-        const output = errorSpy.mock.calls.flat().join('\n');
+        const output = stderrSpy.mock.calls.map(c => String(c[0])).join('');
+        expect(output).toContain('ok: false');
+        expect(output).toContain('code: SELECTOR');
         expect(output).toContain('selector no longer matches');
-        expect(output).not.toContain('this adapter may be outdated');
-        errorSpy.mockRestore();
+        stderrSpy.mockRestore();
     });
 });

package/dist/src/commands/daemon.js

@@ -2,20 +2,20 @@
  * CLI command for daemon lifecycle:
  *   opencli daemon stop — graceful shutdown
  */
-import chalk from 'chalk';
 import { fetchDaemonStatus, requestDaemonShutdown } from '../browser/daemon-client.js';
+import { log } from '../logger.js';
 export async function daemonStop() {
     const status = await fetchDaemonStatus();
     if (!status) {
-        console.log(chalk.dim('Daemon is not running.'));
+        log.info('Daemon is not running.');
         return;
     }
     const ok = await requestDaemonShutdown();
     if (ok) {
-        console.log(chalk.green('Daemon stopped.'));
+        log.success('Daemon stopped.');
     }
     else {
-        console.error(chalk.red('Failed to stop daemon.'));
+        log.error('Failed to stop daemon.');
         process.exitCode = 1;
     }
 }

package/dist/src/commands/daemon.test.js

@@ -3,24 +3,15 @@ const { fetchDaemonStatusMock, requestDaemonShutdownMock, } = vi.hoisted(() => (
     fetchDaemonStatusMock: vi.fn(),
     requestDaemonShutdownMock: vi.fn(),
 }));
-vi.mock('chalk', () => ({
-    default: {
-        green: (s) => s,
-        red: (s) => s,
-        dim: (s) => s,
-    },
-}));
 vi.mock('../browser/daemon-client.js', () => ({
     fetchDaemonStatus: fetchDaemonStatusMock,
     requestDaemonShutdown: requestDaemonShutdownMock,
 }));
 import { daemonStop } from './daemon.js';
 describe('daemonStop', () => {
-    let logSpy;
-    let errorSpy;
+    let stderrSpy;
     beforeEach(() => {
-        logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
-        errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
         fetchDaemonStatusMock.mockReset();
         requestDaemonShutdownMock.mockReset();
     });
@@ -30,7 +21,7 @@ describe('daemonStop', () => {
     it('reports "not running" when daemon is unreachable', async () => {
         fetchDaemonStatusMock.mockResolvedValue(null);
         await daemonStop();
-        expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('not running'));
+        expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('not running'));
     });
     it('sends shutdown and reports success', async () => {
         fetchDaemonStatusMock.mockResolvedValue({
@@ -45,7 +36,7 @@ describe('daemonStop', () => {
         requestDaemonShutdownMock.mockResolvedValue(true);
         await daemonStop();
         expect(requestDaemonShutdownMock).toHaveBeenCalledTimes(1);
-        expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Daemon stopped'));
+        expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('Daemon stopped'));
     });
     it('reports failure when shutdown request fails', async () => {
         fetchDaemonStatusMock.mockResolvedValue({
@@ -59,6 +50,6 @@ describe('daemonStop', () => {
         });
         requestDaemonShutdownMock.mockResolvedValue(false);
         await daemonStop();
-        expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Failed to stop daemon'));
+        expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('Failed to stop daemon'));
     });
 });

package/dist/src/completion-fast.d.ts

@@ -16,9 +16,6 @@ export declare function hasAllManifests(manifestPaths: string[]): boolean;
  * bypassing full CLI discovery and adapter loading.
  */
 export declare function getCompletionsFromManifest(words: string[], cursor: number, manifestPaths: string[]): string[];
-export declare function bashCompletionScript(): string;
-export declare function zshCompletionScript(): string;
-export declare function fishCompletionScript(): string;
 /**
  * Print completion script for the given shell. Returns true if handled, false if unknown shell.
  */

package/dist/src/completion-fast.js

@@ -5,21 +5,7 @@
  * It only reads pre-compiled cli-manifest.json files synchronously.
  */
 import * as fs from 'node:fs';
-const BUILTIN_COMMANDS = [
-    'list',
-    'validate',
-    'verify',
-    'explore',
-    'probe',
-    'synthesize',
-    'generate',
-    'cascade',
-    'doctor',
-    'plugin',
-    'install',
-    'register',
-    'completion',
-];
+import { BUILTIN_COMMANDS, bashCompletionScript, zshCompletionScript, fishCompletionScript, } from './completion-shared.js';
 /**
  * Returns true only if ALL manifest files exist and are readable.
  * If any source lacks a manifest (e.g. user adapters without a compiled manifest),
@@ -70,45 +56,7 @@ export function getCompletionsFromManifest(words, cursor, manifestPaths) {
     }
     return [];
 }
-// ── Shell script generators (pure strings, no registry dependency) ───────
-export function bashCompletionScript() {
-    return `# Bash completion for opencli
-# Add to ~/.bashrc:  eval "$(opencli completion bash)"
-_opencli_completions() {
-  local cur words cword
-  _get_comp_words_by_ref -n : cur words cword
-
-  local completions
-  completions=$(opencli --get-completions --cursor "$cword" "\${words[@]:1}" 2>/dev/null)
-
-  COMPREPLY=( $(compgen -W "$completions" -- "$cur") )
-  __ltrim_colon_completions "$cur"
-}
-complete -F _opencli_completions opencli
-`;
-}
-export function zshCompletionScript() {
-    return `# Zsh completion for opencli
-# Add to ~/.zshrc:  eval "$(opencli completion zsh)"
-_opencli() {
-  local -a completions
-  local cword=$((CURRENT - 1))
-  completions=(\${(f)"$(opencli --get-completions --cursor "$cword" "\${words[@]:1}" 2>/dev/null)"})
-  compadd -a completions
-}
-compdef _opencli opencli
-`;
-}
-export function fishCompletionScript() {
-    return `# Fish completion for opencli
-# Add to ~/.config/fish/config.fish:  opencli completion fish | source
-complete -c opencli -f -a '(
-  set -l tokens (commandline -cop)
-  set -l cursor (count (commandline -cop))
-  opencli --get-completions --cursor $cursor $tokens[2..] 2>/dev/null
-)'
-`;
-}
+// ── Shell script generators (re-exported from shared, no registry dependency) ───────
 const SHELL_SCRIPTS = {
     bash: bashCompletionScript,
     zsh: zshCompletionScript,

package/dist/src/completion-shared.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared constants and shell script generators for tab-completion.
+ *
+ * This module MUST remain lightweight (no registry, no discovery imports).
+ * Both completion.ts (full path) and completion-fast.ts (manifest path) import from here.
+ */
+/**
+ * Built-in (non-dynamic) top-level commands.
+ */
+export declare const BUILTIN_COMMANDS: string[];
+export declare function bashCompletionScript(): string;
+export declare function zshCompletionScript(): string;
+export declare function fishCompletionScript(): string;

package/dist/src/completion-shared.js

@@ -0,0 +1,63 @@
+/**
+ * Shared constants and shell script generators for tab-completion.
+ *
+ * This module MUST remain lightweight (no registry, no discovery imports).
+ * Both completion.ts (full path) and completion-fast.ts (manifest path) import from here.
+ */
+/**
+ * Built-in (non-dynamic) top-level commands.
+ */
+export const BUILTIN_COMMANDS = [
+    'list',
+    'validate',
+    'verify',
+    'explore',
+    'probe', // alias for explore
+    'synthesize',
+    'generate',
+    'cascade',
+    'doctor',
+    'plugin',
+    'install',
+    'register',
+    'completion',
+];
+// ── Shell script generators ────────────────────────────────────────────────
+export function bashCompletionScript() {
+    return `# Bash completion for opencli
+# Add to ~/.bashrc:  eval "$(opencli completion bash)"
+_opencli_completions() {
+  local cur words cword
+  _get_comp_words_by_ref -n : cur words cword
+
+  local completions
+  completions=$(opencli --get-completions --cursor "$cword" "\${words[@]:1}" 2>/dev/null)
+
+  COMPREPLY=( $(compgen -W "$completions" -- "$cur") )
+  __ltrim_colon_completions "$cur"
+}
+complete -F _opencli_completions opencli
+`;
+}
+export function zshCompletionScript() {
+    return `# Zsh completion for opencli
+# Add to ~/.zshrc:  eval "$(opencli completion zsh)"
+_opencli() {
+  local -a completions
+  local cword=$((CURRENT - 1))
+  completions=(\${(f)"$(opencli --get-completions --cursor "$cword" "\${words[@]:1}" 2>/dev/null)"})
+  compadd -a completions
+}
+compdef _opencli opencli
+`;
+}
+export function fishCompletionScript() {
+    return `# Fish completion for opencli
+# Add to ~/.config/fish/config.fish:  opencli completion fish | source
+complete -c opencli -f -a '(
+  set -l tokens (commandline -cop)
+  set -l cursor (count (commandline -cop))
+  opencli --get-completions --cursor $cursor $tokens[2..] 2>/dev/null
+)'
+`;
+}

package/dist/src/completion.d.ts

@@ -5,6 +5,8 @@
  *  - Shell script generators for bash, zsh, and fish
  *  - Dynamic completion logic that returns candidates for the current cursor position
  */
+import { bashCompletionScript, zshCompletionScript, fishCompletionScript } from './completion-shared.js';
+export { bashCompletionScript, zshCompletionScript, fishCompletionScript };
 /**
  * Return completion candidates given the current command-line words and cursor index.
  * Requires full CLI discovery to have been run (uses getRegistry()).
@@ -13,9 +15,6 @@
  * @param cursor - 1-based position of the word being completed (1 = first arg)
  */
 export declare function getCompletions(words: string[], cursor: number): string[];
-export declare function bashCompletionScript(): string;
-export declare function zshCompletionScript(): string;
-export declare function fishCompletionScript(): string;
 /**
  * Print the completion script for the requested shell.
  */