@agentrhq/webcmd 0.1.1 → 0.1.2

package/dist/src/commanderAdapter.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Commander adapter: bridges Registry commands to Commander subcommands.
+ *
+ * This is a THIN adapter — it only handles:
+ * 1. Commander arg/option registration
+ * 2. Collecting kwargs from Commander's action args
+ * 3. Calling executeCommand (which handles browser sessions, validation, etc.)
+ * 4. Rendering output and errors
+ *
+ * All execution logic lives in execution.ts.
+ */
+import { Command } from 'commander';
+import { type CliCommand } from './registry.js';
+/**
+ * Register a single CliCommand as a Commander subcommand.
+ */
+export declare function registerCommandToProgram(siteCmd: Command, cmd: CliCommand): void;
+/**
+ * Register all commands from the registry onto a Commander program.
+ */
+export declare function registerAllCommands(program: Command, siteGroups: Map<string, Command>): string[];

package/dist/src/commanderAdapter.js

@@ -0,0 +1,208 @@
+/**
+ * Commander adapter: bridges Registry commands to Commander subcommands.
+ *
+ * This is a THIN adapter — it only handles:
+ * 1. Commander arg/option registration
+ * 2. Collecting kwargs from Commander's action args
+ * 3. Calling executeCommand (which handles browser sessions, validation, etc.)
+ * 4. Rendering output and errors
+ *
+ * All execution logic lives in execution.ts.
+ */
+import { log } from './logger.js';
+import yaml from 'js-yaml';
+import { fullName, getRegistry } from './registry.js';
+import { render as renderOutput } from './output.js';
+import { executeCommand, prepareCommandArgs } from './execution.js';
+import { commandHelpData, formatCommandHelpText, formatCommandListTerm, formatSiteCommandDescription, formatSiteHelpText, getRequestedHelpFormat, renderStructuredHelp, siteHelpData, } from './help.js';
+import { CliError, EXIT_CODES, toEnvelope, } from './errors.js';
+/**
+ * Register a single CliCommand as a Commander subcommand.
+ */
+export function registerCommandToProgram(siteCmd, cmd) {
+    if (siteCmd.commands.some((c) => c.name() === cmd.name))
+        return;
+    const subCmd = siteCmd.command(cmd.name).description(formatSiteCommandDescription(cmd));
+    if (cmd.aliases?.length)
+        subCmd.aliases(cmd.aliases);
+    // Register positional args first, then named options
+    const positionalArgs = [];
+    for (const arg of cmd.args) {
+        if (arg.positional) {
+            const bracket = arg.required ? `<${arg.name}>` : `[${arg.name}]`;
+            subCmd.argument(bracket, arg.help ?? '');
+            positionalArgs.push(arg);
+        }
+        else {
+            const expectsValue = arg.required || arg.valueRequired;
+            const flag = expectsValue ? `--${arg.name} <value>` : `--${arg.name} [value]`;
+            if (arg.required)
+                subCmd.requiredOption(flag, arg.help ?? '');
+            else if (arg.default != null)
+                subCmd.option(flag, arg.help ?? '', String(arg.default));
+            else
+                subCmd.option(flag, arg.help ?? '');
+        }
+    }
+    subCmd
+        .option('-f, --format <fmt>', 'Output format: table, plain, json, yaml, md, csv', 'table')
+        .option('--trace <mode>', 'Trace capture: off, on, retain-on-failure', 'off')
+        .option('-v, --verbose', 'Debug output', false);
+    if (cmd.browser) {
+        subCmd
+            .option('--window <mode>', 'Browser window mode: foreground or background')
+            .option('--site-session <mode>', 'Adapter site session lifecycle: ephemeral or persistent')
+            .option('--keep-tab <bool>', 'Keep the browser tab lease after the command finishes');
+    }
+    const originalHelpInformation = subCmd.helpInformation.bind(subCmd);
+    subCmd.helpInformation = ((contextOptions) => {
+        const format = getRequestedHelpFormat();
+        if (format)
+            return renderStructuredHelp(commandHelpData(cmd), format);
+        // Keep a fallback reference so future Commander upgrades still initialize
+        // internal help state before we render the cleaner grouped command help.
+        void originalHelpInformation(contextOptions);
+        return formatCommandHelpText(cmd);
+    });
+    subCmd.action(async (...actionArgs) => {
+        const actionOpts = actionArgs[positionalArgs.length] ?? {};
+        const optionsRecord = typeof actionOpts === 'object' && actionOpts !== null ? actionOpts : {};
+        const startTime = Date.now();
+        // ── Execute + render ────────────────────────────────────────────────
+        try {
+            // ── Collect kwargs ────────────────────────────────────────────────
+            const rawKwargs = {};
+            for (let i = 0; i < positionalArgs.length; i++) {
+                const v = actionArgs[i];
+                if (v !== undefined)
+                    rawKwargs[positionalArgs[i].name] = v;
+            }
+            for (const arg of cmd.args) {
+                if (arg.positional)
+                    continue;
+                const camelName = arg.name.replace(/-([a-z])/g, (_m, ch) => ch.toUpperCase());
+                const v = optionsRecord[arg.name] ?? optionsRecord[camelName];
+                if (v !== undefined)
+                    rawKwargs[arg.name] = v;
+            }
+            const optionSources = {};
+            for (const arg of cmd.args) {
+                if (arg.positional)
+                    continue;
+                const camelName = arg.name.replace(/-([a-z])/g, (_m, ch) => ch.toUpperCase());
+                const source = subCmd.getOptionValueSource(camelName) ?? subCmd.getOptionValueSource(arg.name);
+                if (source === 'cli')
+                    optionSources[arg.name] = source;
+            }
+            if (Object.keys(optionSources).length > 0) {
+                rawKwargs.__webcmdOptionSources = optionSources;
+            }
+            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';
+            if (verbose)
+                process.env.WEBCMD_VERBOSE = '1';
+            const globals = typeof subCmd.optsWithGlobals === 'function' ? subCmd.optsWithGlobals() : {};
+            const result = await executeCommand(cmd, kwargs, verbose, {
+                prepared: true,
+                ...(typeof globals.profile === 'string' && globals.profile.trim() ? { profile: globals.profile.trim() } : {}),
+                ...(typeof optionsRecord.trace === 'string' && optionsRecord.trace !== 'off' ? { trace: optionsRecord.trace } : {}),
+                ...(cmd.browser && typeof optionsRecord.window === 'string' ? { windowMode: optionsRecord.window } : {}),
+                ...(cmd.browser && typeof optionsRecord.siteSession === 'string' ? { siteSession: optionsRecord.siteSession } : {}),
+                ...(cmd.browser && typeof optionsRecord.keepTab === 'string' ? { keepTab: optionsRecord.keepTab } : {}),
+            });
+            if (result === null || result === undefined) {
+                return;
+            }
+            const resolved = getRegistry().get(fullName(cmd)) ?? cmd;
+            if (!formatExplicit && format === 'table' && resolved.defaultFormat) {
+                format = resolved.defaultFormat;
+            }
+            if (verbose && (!result || (Array.isArray(result) && result.length === 0))) {
+                log.warn('Command returned an empty result.');
+            }
+            renderOutput(result, {
+                fmt: format,
+                fmtExplicit: formatExplicit,
+                columns: resolved.columns,
+                title: `${resolved.site}/${resolved.name}`,
+                elapsed: (Date.now() - startTime) / 1000,
+                source: fullName(resolved),
+                footerExtra: resolved.footerExtra?.(kwargs),
+            });
+        }
+        catch (err) {
+            renderError(err, fullName(cmd), optionsRecord.verbose === true, optionsRecord.trace);
+            process.exitCode = resolveExitCode(err);
+        }
+    });
+}
+// ── Exit code resolution ─────────────────────────────────────────────────────
+function resolveExitCode(err) {
+    if (err instanceof CliError)
+        return err.exitCode;
+    return EXIT_CODES.GENERIC_ERROR;
+}
+// ── Error rendering ─────────────────────────────────────────────────────────
+/** Emit AutoFix hint for repairable adapter errors (skipped if trace already exported). */
+function emitAutoFixHint(envelope, cmdName, traceMode) {
+    if (traceMode === 'on' || traceMode === 'retain-on-failure')
+        return envelope;
+    const runnable = cmdName.replace('/', ' ');
+    return envelope
+        + `# AutoFix: re-run with --trace=retain-on-failure for trace artifact\n`
+        + `# webcmd ${runnable} --trace retain-on-failure\n`;
+}
+function renderError(err, cmdName, verbose, traceMode) {
+    const envelope = toEnvelope(err);
+    // In verbose mode, include stack trace for debugging
+    if (verbose && err instanceof Error && err.stack) {
+        envelope.error.stack = err.stack;
+    }
+    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, traceMode);
+    }
+    process.stderr.write(output);
+}
+/**
+ * Register all commands from the registry onto a Commander program.
+ */
+export function registerAllCommands(program, siteGroups) {
+    const seen = new Set();
+    const commandsBySite = new Map();
+    for (const [, cmd] of getRegistry()) {
+        if (seen.has(cmd))
+            continue;
+        seen.add(cmd);
+        const commands = commandsBySite.get(cmd.site) ?? [];
+        commands.push(cmd);
+        commandsBySite.set(cmd.site, commands);
+    }
+    for (const [site, commands] of commandsBySite) {
+        let siteCmd = siteGroups.get(site);
+        if (!siteCmd) {
+            siteCmd = program.command(site);
+            siteGroups.set(site, siteCmd);
+        }
+        for (const cmd of commands) {
+            registerCommandToProgram(siteCmd, cmd);
+        }
+        const commandTerms = new Map(commands.map(cmd => [cmd.name, formatCommandListTerm(cmd)]));
+        siteCmd.configureHelp({
+            subcommandTerm: command => commandTerms.get(command.name()) ?? command.name(),
+        });
+        const originalSiteHelpInformation = siteCmd.helpInformation.bind(siteCmd);
+        siteCmd.helpInformation = ((contextOptions) => {
+            const format = getRequestedHelpFormat();
+            if (format)
+                return renderStructuredHelp(siteHelpData(site, commands), format);
+            void originalSiteHelpInformation(contextOptions);
+            return formatSiteHelpText(site, commands);
+        });
+    }
+    return [...commandsBySite.keys()].sort((a, b) => a.localeCompare(b));
+}

package/dist/src/commanderAdapter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/commanderAdapter.test.js

@@ -0,0 +1,352 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { Command } from 'commander';
+import { attachTraceReceipt, EmptyResultError, selectorError } from './errors.js';
+const { mockExecuteCommand, mockRenderOutput } = vi.hoisted(() => ({
+    mockExecuteCommand: vi.fn(),
+    mockRenderOutput: vi.fn(),
+}));
+vi.mock('./execution.js', async () => {
+    const actual = await vi.importActual('./execution.js');
+    return {
+        ...actual,
+        executeCommand: mockExecuteCommand,
+    };
+});
+vi.mock('./output.js', () => ({
+    render: mockRenderOutput,
+}));
+import { registerCommandToProgram } from './commanderAdapter.js';
+describe('commanderAdapter arg passing', () => {
+    const cmd = {
+        site: 'paperreview',
+        name: 'submit', access: 'read',
+        description: 'Submit a PDF',
+        browser: false,
+        args: [
+            { name: 'pdf', positional: true, required: true, help: 'Path to the paper PDF' },
+            { name: 'dry-run', type: 'bool', default: false, help: 'Validate only' },
+            { name: 'prepare-only', type: 'bool', default: false, help: 'Prepare only' },
+        ],
+        func: vi.fn(),
+    };
+    beforeEach(() => {
+        mockExecuteCommand.mockReset();
+        mockExecuteCommand.mockResolvedValue([]);
+        mockRenderOutput.mockReset();
+        delete process.env.WEBCMD_VERBOSE;
+        process.exitCode = undefined;
+    });
+    it('passes bool flag values through to executeCommand for coercion', async () => {
+        const program = new Command();
+        const siteCmd = program.command('paperreview');
+        registerCommandToProgram(siteCmd, cmd);
+        await program.parseAsync(['node', 'webcmd', 'paperreview', 'submit', './paper.pdf', '--dry-run', 'false']);
+        expect(mockExecuteCommand).toHaveBeenCalled();
+        const kwargs = mockExecuteCommand.mock.calls[0][1];
+        expect(kwargs.pdf).toBe('./paper.pdf');
+        expect(kwargs).toHaveProperty('dry-run');
+    });
+    it('passes valueless bool flags as true to executeCommand', async () => {
+        const program = new Command();
+        const siteCmd = program.command('paperreview');
+        registerCommandToProgram(siteCmd, cmd);
+        await program.parseAsync(['node', 'webcmd', 'paperreview', 'submit', './paper.pdf', '--prepare-only']);
+        expect(mockExecuteCommand).toHaveBeenCalled();
+        const kwargs = mockExecuteCommand.mock.calls[0][1];
+        expect(kwargs.pdf).toBe('./paper.pdf');
+        expect(kwargs['prepare-only']).toBe(true);
+    });
+    it('passes option value sources through for adapters that need explicit-vs-default semantics', async () => {
+        const program = new Command();
+        const siteCmd = program.command('paperreview');
+        registerCommandToProgram(siteCmd, cmd);
+        await program.parseAsync(['node', 'webcmd', 'paperreview', 'submit', './paper.pdf', '--prepare-only']);
+        expect(mockExecuteCommand).toHaveBeenCalled();
+        const kwargs = mockExecuteCommand.mock.calls[0][1];
+        expect(kwargs.__webcmdOptionSources).toMatchObject({
+            'prepare-only': 'cli',
+        });
+    });
+    it('passes explicit trace mode to executeCommand', async () => {
+        const program = new Command();
+        const siteCmd = program.command('paperreview');
+        registerCommandToProgram(siteCmd, cmd);
+        await program.parseAsync(['node', 'webcmd', 'paperreview', 'submit', './paper.pdf', '--trace', 'retain-on-failure']);
+        expect(mockExecuteCommand).toHaveBeenCalledWith(expect.objectContaining({ site: 'paperreview', name: 'submit' }), expect.objectContaining({ pdf: './paper.pdf' }), false, { prepared: true, trace: 'retain-on-failure' });
+    });
+    it('rejects invalid bool values before calling executeCommand', async () => {
+        const program = new Command();
+        const siteCmd = program.command('paperreview');
+        registerCommandToProgram(siteCmd, cmd);
+        await program.parseAsync(['node', 'webcmd', 'paperreview', 'submit', './paper.pdf', '--dry-run', 'maybe']);
+        // prepareCommandArgs validates bools before dispatch; executeCommand should not be reached
+        expect(mockExecuteCommand).not.toHaveBeenCalled();
+    });
+});
+describe('commanderAdapter boolean alias support', () => {
+    const cmd = {
+        site: 'reddit',
+        name: 'save', access: 'read',
+        description: 'Save a post',
+        browser: false,
+        args: [
+            { name: 'post-id', positional: true, required: true, help: 'Post ID' },
+            { name: 'undo', type: 'boolean', default: false, help: 'Unsave instead of save' },
+        ],
+        func: vi.fn(),
+    };
+    beforeEach(() => {
+        mockExecuteCommand.mockReset();
+        mockExecuteCommand.mockResolvedValue([]);
+        mockRenderOutput.mockReset();
+        delete process.env.WEBCMD_VERBOSE;
+        process.exitCode = undefined;
+    });
+    it('coerces default false for boolean args to a real boolean', async () => {
+        const program = new Command();
+        const siteCmd = program.command('reddit');
+        registerCommandToProgram(siteCmd, cmd);
+        await program.parseAsync(['node', 'webcmd', 'reddit', 'save', 't3_abc123']);
+        expect(mockExecuteCommand).toHaveBeenCalled();
+        const kwargs = mockExecuteCommand.mock.calls[0][1];
+        expect(kwargs['post-id']).toBe('t3_abc123');
+        expect(kwargs.undo).toBe(false);
+    });
+    it('coerces explicit false for boolean args to a real boolean', async () => {
+        const program = new Command();
+        const siteCmd = program.command('reddit');
+        registerCommandToProgram(siteCmd, cmd);
+        await program.parseAsync(['node', 'webcmd', 'reddit', 'save', 't3_abc123', '--undo', 'false']);
+        expect(mockExecuteCommand).toHaveBeenCalled();
+        const kwargs = mockExecuteCommand.mock.calls[0][1];
+        expect(kwargs.undo).toBe(false);
+    });
+});
+describe('commanderAdapter value-required optional options', () => {
+    const cmd = {
+        site: 'instagram',
+        name: 'post', access: 'read',
+        description: 'Post to Instagram',
+        browser: true,
+        args: [
+            { name: 'image', valueRequired: true, help: 'Single image path' },
+            { name: 'images', valueRequired: true, help: 'Comma-separated image paths' },
+            { name: 'content', positional: true, required: false, help: 'Caption text' },
+        ],
+        validateArgs: (kwargs) => {
+            if (!kwargs.image && !kwargs.images) {
+                throw new Error('media required');
+            }
+        },
+        func: vi.fn(),
+    };
+    beforeEach(() => {
+        mockExecuteCommand.mockReset();
+        mockExecuteCommand.mockResolvedValue([]);
+        mockRenderOutput.mockReset();
+        delete process.env.WEBCMD_VERBOSE;
+        process.exitCode = undefined;
+    });
+    it('requires a value when --image is present', async () => {
+        const program = new Command();
+        program.exitOverride();
+        const siteCmd = program.command('instagram');
+        registerCommandToProgram(siteCmd, cmd);
+        await expect(program.parseAsync(['node', 'webcmd', 'instagram', 'post', '--image'])).rejects.toMatchObject({ code: 'commander.optionMissingArgument' });
+        expect(mockExecuteCommand).not.toHaveBeenCalled();
+    });
+    it('runs validateArgs before executeCommand so missing media does not dispatch the browser command', async () => {
+        const program = new Command();
+        const siteCmd = program.command('instagram');
+        registerCommandToProgram(siteCmd, cmd);
+        await program.parseAsync(['node', 'webcmd', 'instagram', 'post', 'caption only']);
+        expect(mockExecuteCommand).not.toHaveBeenCalled();
+        expect(process.exitCode).toBeDefined();
+    });
+});
+describe('commanderAdapter command aliases', () => {
+    const cmd = {
+        site: 'notebooklm',
+        name: 'get',
+        access: 'read',
+        aliases: ['metadata'],
+        description: 'Get notebook metadata',
+        browser: false,
+        args: [],
+        func: vi.fn(),
+    };
+    beforeEach(() => {
+        mockExecuteCommand.mockReset();
+        mockExecuteCommand.mockResolvedValue([]);
+        mockRenderOutput.mockReset();
+        delete process.env.WEBCMD_VERBOSE;
+        process.exitCode = undefined;
+    });
+    it('registers aliases with Commander so compatibility names execute the same command', async () => {
+        const program = new Command();
+        const siteCmd = program.command('notebooklm');
+        registerCommandToProgram(siteCmd, cmd);
+        await program.parseAsync(['node', 'webcmd', 'notebooklm', 'metadata']);
+        expect(mockExecuteCommand).toHaveBeenCalledWith(cmd, {}, false, { prepared: true });
+    });
+});
+describe('commanderAdapter validation preparation', () => {
+    beforeEach(() => {
+        mockExecuteCommand.mockReset();
+        mockExecuteCommand.mockResolvedValue([]);
+        mockRenderOutput.mockReset();
+        delete process.env.WEBCMD_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', access: 'read',
+            description: 'Run test command',
+            browser: false,
+            args: [{ name: 'count', default: '1', help: 'Count' }],
+            validateArgs,
+            func: vi.fn(),
+        });
+        await program.parseAsync(['node', 'webcmd', 'test', 'run']);
+        expect(validateArgs).toHaveBeenCalledTimes(1);
+        expect(mockExecuteCommand).toHaveBeenCalledWith(expect.objectContaining({ site: 'test', name: 'run' }), { count: '1' }, false, { prepared: true });
+    });
+});
+describe('commanderAdapter default formats', () => {
+    const cmd = {
+        site: 'gemini',
+        name: 'ask', access: 'read',
+        description: 'Ask Gemini',
+        browser: false,
+        args: [],
+        columns: ['response'],
+        defaultFormat: 'plain',
+        func: vi.fn(),
+    };
+    beforeEach(() => {
+        mockExecuteCommand.mockReset();
+        mockExecuteCommand.mockResolvedValue([{ response: 'hello' }]);
+        mockRenderOutput.mockReset();
+        delete process.env.WEBCMD_VERBOSE;
+        process.exitCode = undefined;
+    });
+    it('uses the command defaultFormat when the user keeps the default table format', async () => {
+        const program = new Command();
+        const siteCmd = program.command('gemini');
+        registerCommandToProgram(siteCmd, cmd);
+        await program.parseAsync(['node', 'webcmd', 'gemini', 'ask']);
+        expect(mockRenderOutput).toHaveBeenCalledWith([{ response: 'hello' }], expect.objectContaining({ fmt: 'plain' }));
+    });
+    it('respects an explicit user format over the command defaultFormat', async () => {
+        const program = new Command();
+        const siteCmd = program.command('gemini');
+        registerCommandToProgram(siteCmd, cmd);
+        await program.parseAsync(['node', 'webcmd', 'gemini', 'ask', '--format', 'json']);
+        expect(mockRenderOutput).toHaveBeenCalledWith([{ response: 'hello' }], expect.objectContaining({ fmt: 'json' }));
+    });
+});
+describe('commanderAdapter error envelope output', () => {
+    const cmd = {
+        site: 'xiaohongshu',
+        name: 'note', access: 'read',
+        description: 'Read one note',
+        browser: false,
+        args: [
+            { name: 'note-id', positional: true, required: true, help: 'Note ID' },
+        ],
+        func: vi.fn(),
+    };
+    beforeEach(() => {
+        mockExecuteCommand.mockReset();
+        mockRenderOutput.mockReset();
+        delete process.env.WEBCMD_VERBOSE;
+        process.exitCode = undefined;
+    });
+    it('outputs YAML error envelope with adapter hint to stderr', async () => {
+        const program = new Command();
+        const siteCmd = program.command('xiaohongshu');
+        registerCommandToProgram(siteCmd, cmd);
+        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', 'webcmd', 'xiaohongshu', 'note', '69ca3927000000001a020fd5']);
+        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).toContain('--trace=retain-on-failure');
+        expect(output).toContain('webcmd xiaohongshu note --trace retain-on-failure');
+        stderrSpy.mockRestore();
+    });
+    it('outputs YAML error envelope for selector errors', async () => {
+        const program = new Command();
+        const siteCmd = program.command('xiaohongshu');
+        registerCommandToProgram(siteCmd, cmd);
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        mockExecuteCommand.mockRejectedValueOnce(selectorError('.note-title', 'The note title selector no longer matches the current page.'));
+        await program.parseAsync(['node', 'webcmd', 'xiaohongshu', 'note', '69ca3927000000001a020fd5']);
+        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).toContain('--trace=retain-on-failure');
+        stderrSpy.mockRestore();
+    });
+    it('does not add an AutoFix rerun hint when trace is already enabled', async () => {
+        const program = new Command();
+        const siteCmd = program.command('xiaohongshu');
+        registerCommandToProgram(siteCmd, cmd);
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        mockExecuteCommand.mockRejectedValueOnce(selectorError('.note-title'));
+        await program.parseAsync([
+            'node',
+            'webcmd',
+            'xiaohongshu',
+            'note',
+            '69ca3927000000001a020fd5',
+            '--trace',
+            'retain-on-failure',
+        ]);
+        const output = stderrSpy.mock.calls.map(c => String(c[0])).join('');
+        expect(output).toContain('code: SELECTOR');
+        expect(output).not.toContain('AutoFix: re-run');
+        stderrSpy.mockRestore();
+    });
+    it('includes trace metadata from the error envelope when execution attached it', async () => {
+        const program = new Command();
+        const siteCmd = program.command('xiaohongshu');
+        registerCommandToProgram(siteCmd, cmd);
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        const err = selectorError('.note-title');
+        attachTraceReceipt(err, {
+            schemaVersion: 1,
+            webcmdVersion: '1.7.8',
+            traceId: 'trace-1',
+            traceDir: '/tmp/webcmd/profiles/default/traces/trace-1',
+            summaryPath: '/tmp/webcmd/profiles/default/traces/trace-1/summary.md',
+            receiptPath: '/tmp/webcmd/profiles/default/traces/trace-1/receipt.json',
+            status: 'failure',
+            createdAt: '2026-05-03T00:00:00.000Z',
+            error: { code: 'SELECTOR', message: 'Could not find element: .note-title' },
+        });
+        mockExecuteCommand.mockRejectedValueOnce(err);
+        await program.parseAsync([
+            'node',
+            'webcmd',
+            'xiaohongshu',
+            'note',
+            '69ca3927000000001a020fd5',
+            '--trace',
+            'retain-on-failure',
+        ]);
+        const output = stderrSpy.mock.calls.map(c => String(c[0])).join('');
+        expect(output).toContain('trace:');
+        expect(output).toContain('dir: /tmp/webcmd/profiles/default/traces/trace-1');
+        expect(output).toContain('summaryPath: /tmp/webcmd/profiles/default/traces/trace-1/summary.md');
+        expect(output).toContain('receiptPath: /tmp/webcmd/profiles/default/traces/trace-1/receipt.json');
+        stderrSpy.mockRestore();
+    });
+});

package/dist/src/commands/auth.d.ts

@@ -0,0 +1,40 @@
+import { Command } from 'commander';
+type AuthStatus = 'logged_in' | 'not_logged_in' | 'unknown' | 'error';
+type AuthStatusMode = 'quick' | 'full';
+type AuthRefreshStatus = 'refreshed' | 'touched' | 'not_logged_in' | 'skipped' | 'unsupported' | 'error';
+export interface AuthStatusRow {
+    site: string;
+    status: AuthStatus;
+    logged_in: boolean | '';
+    identity: string;
+    checked: AuthStatusMode | 'skipped';
+    error: string;
+}
+interface AuthStatusOptions {
+    sites?: string;
+    only?: string;
+    full?: boolean;
+    concurrency?: string | number;
+    timeout?: string | number;
+    profile?: string;
+}
+export interface AuthRefreshRow {
+    site: string;
+    status: AuthRefreshStatus;
+    last_touched_at: string;
+    next_refresh_at: string;
+    error: string;
+}
+interface AuthRefreshOptions {
+    sites?: string;
+    all?: boolean;
+    concurrency?: string | number;
+    timeout?: string | number;
+    profile?: string;
+    statePath?: string;
+    now?: Date;
+}
+export declare function collectAuthStatus(options: AuthStatusOptions): Promise<AuthStatusRow[]>;
+export declare function collectAuthRefresh(options: AuthRefreshOptions): Promise<AuthRefreshRow[]>;
+export declare function registerAuthCommands(program: Command): Command;
+export {};