@jackwener/opencli 1.7.11 → 1.7.13

package/dist/src/execution.test.js

@@ -3,44 +3,353 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { executeCommand, prepareCommandArgs } from './execution.js';
-import { TimeoutError, toEnvelope } from './errors.js';
+import { ArgumentError, TimeoutError, toEnvelope } from './errors.js';
 import { cli, Strategy } from './registry.js';
-import { withTimeoutMs } from './runtime.js';
 import * as runtime from './runtime.js';
 import * as capRouting from './capabilityRouting.js';
 describe('executeCommand — non-browser timeout', () => {
-    it('applies timeoutSeconds to non-browser commands', async () => {
+    it('applies the user --timeout arg as the ceiling for non-browser commands', async () => {
+        const runWithTimeoutSpy = vi.spyOn(runtime, 'runWithTimeout');
         const cmd = cli({
             site: 'test-execution',
-            name: 'non-browser-timeout',
-            description: 'test non-browser timeout',
+            name: 'non-browser-timeout', access: 'read',
+            description: 'test non-browser --timeout enforcement',
             browser: false,
             strategy: Strategy.PUBLIC,
-            timeoutSeconds: 0.01,
+            args: [
+                { name: 'timeout', type: 'int', required: false, default: 5, help: 'Max seconds' },
+            ],
+            func: async () => [{ ok: true }],
+        });
+        await executeCommand(cmd, {});
+        expect(runWithTimeoutSpy).toHaveBeenCalledTimes(1);
+        // Ceiling = user-supplied/default timeout + 30s padding (adapter return room).
+        expect(runWithTimeoutSpy.mock.calls[0]?.[1]).toMatchObject({
+            timeout: 35,
+            label: 'test-execution/non-browser-timeout',
+        });
+        vi.restoreAllMocks();
+    });
+    it('fires a TimeoutError when the inner adapter exceeds the --timeout ceiling', async () => {
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'non-browser-timeout-fires', access: 'read',
+            description: 'test that the ceiling actually cancels the adapter',
+            browser: false,
+            strategy: Strategy.PUBLIC,
+            args: [
+                { name: 'timeout', type: 'int', required: false, default: 1, help: 'Max seconds' },
+            ],
             func: () => new Promise(() => { }),
         });
-        // Sentinel timeout at 200ms — if the inner 10ms timeout fires first,
-        // the error will be a TimeoutError with the command label, not 'sentinel'.
-        const error = await withTimeoutMs(executeCommand(cmd, {}), 200, 'sentinel timeout')
-            .catch((err) => err);
+        // Spy on runWithTimeout to intercept and pass a tiny ceiling so the test
+        // doesn't have to wait the real (1+30)s. We still verify the TimeoutError
+        // surface — code, label, hint — that users see.
+        vi.spyOn(runtime, 'runWithTimeout').mockImplementation(async (promise, opts) => {
+            return runtime.withTimeoutMs(promise, 50, () => new TimeoutError(opts.label ?? 'op', opts.timeout, opts.hint));
+        });
+        const error = await executeCommand(cmd, {}).catch((err) => err);
         expect(error).toBeInstanceOf(TimeoutError);
         expect(error).toMatchObject({
             code: 'TIMEOUT',
-            message: 'test-execution/non-browser-timeout timed out after 0.01s',
+            hint: 'Pass a higher --timeout value (currently 1s)',
         });
+        vi.restoreAllMocks();
     });
-    it('skips timeout when timeoutSeconds is 0', async () => {
+    it('runs non-browser commands without a ceiling when no --timeout arg is declared', async () => {
+        const runWithTimeoutSpy = vi.spyOn(runtime, 'runWithTimeout');
         const cmd = cli({
             site: 'test-execution',
-            name: 'non-browser-zero-timeout',
-            description: 'test zero timeout bypasses wrapping',
+            name: 'non-browser-no-timeout', access: 'read',
+            description: 'test that omitting --timeout means no ceiling',
             browser: false,
             strategy: Strategy.PUBLIC,
-            timeoutSeconds: 0,
-            func: () => new Promise(() => { }),
+            func: async () => [{ ok: true }],
+        });
+        await executeCommand(cmd, {});
+        expect(runWithTimeoutSpy).not.toHaveBeenCalled();
+        vi.restoreAllMocks();
+    });
+    it('rejects invalid --timeout values instead of silently disabling the non-browser ceiling', async () => {
+        const runWithTimeoutSpy = vi.spyOn(runtime, 'runWithTimeout');
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'non-browser-invalid-timeout', access: 'read',
+            description: 'test invalid --timeout fails upfront',
+            browser: false,
+            strategy: Strategy.PUBLIC,
+            args: [
+                { name: 'timeout', type: 'int', required: false, default: 5, help: 'Max seconds' },
+            ],
+            func: async () => [{ ok: true }],
+        });
+        await expect(executeCommand(cmd, { timeout: 0 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(executeCommand(cmd, { timeout: -1 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(executeCommand(cmd, { timeout: 1.5 })).rejects.toBeInstanceOf(ArgumentError);
+        expect(runWithTimeoutSpy).not.toHaveBeenCalled();
+        vi.restoreAllMocks();
+    });
+    it('applies the user --timeout arg as the ceiling for browser commands (with +30s padding)', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const mockPage = { closeWindow };
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+        const runWithTimeoutSpy = vi.spyOn(runtime, 'runWithTimeout');
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'browser-with-timeout', access: 'read',
+            description: 'test browser --timeout enforcement',
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            args: [
+                { name: 'timeout', type: 'int', required: false, default: 5, help: 'Max seconds' },
+            ],
+            func: async () => [{ ok: true }],
+        });
+        await executeCommand(cmd, {});
+        expect(runWithTimeoutSpy).toHaveBeenCalledTimes(1);
+        expect(runWithTimeoutSpy.mock.calls[0]?.[1]).toMatchObject({
+            timeout: 35,
+            label: 'test-execution/browser-with-timeout',
+        });
+        vi.restoreAllMocks();
+    });
+    it('falls back to DEFAULT_BROWSER_COMMAND_TIMEOUT for browser commands without a --timeout arg', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const mockPage = { closeWindow };
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+        const runWithTimeoutSpy = vi.spyOn(runtime, 'runWithTimeout');
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'browser-no-timeout', access: 'read',
+            description: 'test browser fallback to global default',
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            func: async () => [{ ok: true }],
+        });
+        await executeCommand(cmd, {});
+        expect(runWithTimeoutSpy).toHaveBeenCalledTimes(1);
+        expect(runWithTimeoutSpy.mock.calls[0]?.[1]).toMatchObject({
+            timeout: runtime.DEFAULT_BROWSER_COMMAND_TIMEOUT,
+            label: 'test-execution/browser-no-timeout',
+        });
+        vi.restoreAllMocks();
+    });
+    it('reuses a site-scoped browser workspace and keeps the tab lease open', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const mockPage = { closeWindow };
+        const sessionOpts = [];
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn, opts) => {
+            sessionOpts.push(opts ?? {});
+            return fn(mockPage);
+        });
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'browser-reuse-site', access: 'read',
+            description: 'test site-scoped browser reuse',
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            browserSession: { reuse: 'site' },
+            func: async () => [{ ok: true }],
         });
-        // With timeout guard skipped, the sentinel fires instead.
-        await expect(withTimeoutMs(executeCommand(cmd, {}), 50, 'sentinel timeout')).rejects.toThrow('sentinel timeout');
+        await executeCommand(cmd, {});
+        await executeCommand(cmd, {});
+        expect(sessionOpts).toHaveLength(2);
+        expect(sessionOpts[0]).toMatchObject({ workspace: 'site:test-execution', idleTimeout: 600 });
+        expect(sessionOpts[1]).toMatchObject({ workspace: 'site:test-execution', idleTimeout: 600 });
+        expect(closeWindow).not.toHaveBeenCalled();
+        vi.restoreAllMocks();
+    });
+    it('keeps default browser commands on one-shot workspaces', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const mockPage = { closeWindow };
+        const sessionOpts = [];
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn, opts) => {
+            sessionOpts.push(opts ?? {});
+            return fn(mockPage);
+        });
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'browser-reuse-default', access: 'read',
+            description: 'test default one-shot browser workspace',
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            func: async () => [{ ok: true }],
+        });
+        await executeCommand(cmd, {});
+        await executeCommand(cmd, {});
+        expect(sessionOpts).toHaveLength(2);
+        expect(sessionOpts[0]?.workspace).toMatch(/^site:test-execution:/);
+        expect(sessionOpts[1]?.workspace).toMatch(/^site:test-execution:/);
+        expect(sessionOpts[0]?.workspace).not.toBe(sessionOpts[1]?.workspace);
+        expect(sessionOpts[0]?.idleTimeout).toBeUndefined();
+        expect(sessionOpts[1]?.idleTimeout).toBeUndefined();
+        expect(closeWindow).toHaveBeenCalledTimes(2);
+        vi.restoreAllMocks();
+    });
+    it('lets user --reuse none override adapter reuse metadata', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const mockPage = { closeWindow };
+        const sessionOpts = [];
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn, opts) => {
+            sessionOpts.push(opts ?? {});
+            return fn(mockPage);
+        });
+        const prev = process.env.OPENCLI_BROWSER_REUSE;
+        process.env.OPENCLI_BROWSER_REUSE = 'none';
+        try {
+            const cmd = cli({
+                site: 'test-execution',
+                name: 'browser-reuse-override-none', access: 'read',
+                description: 'test user reuse override',
+                browser: true,
+                strategy: Strategy.PUBLIC,
+                browserSession: { reuse: 'site' },
+                func: async () => [{ ok: true }],
+            });
+            await executeCommand(cmd, {});
+            expect(sessionOpts).toHaveLength(1);
+            expect(sessionOpts[0]?.workspace).toMatch(/^site:test-execution:/);
+            expect(sessionOpts[0]?.idleTimeout).toBeUndefined();
+            expect(closeWindow).toHaveBeenCalledTimes(1);
+        }
+        finally {
+            if (prev === undefined)
+                delete process.env.OPENCLI_BROWSER_REUSE;
+            else
+                process.env.OPENCLI_BROWSER_REUSE = prev;
+            vi.restoreAllMocks();
+        }
+    });
+    it('skips repeated domain pre-navigation for site-reused browser sessions', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const goto = vi.fn().mockResolvedValue(undefined);
+        const mockPage = {
+            closeWindow,
+            goto,
+            getCurrentUrl: vi.fn().mockResolvedValue('https://grok.com/chat/abc'),
+        };
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'browser-reuse-skip-prenav', access: 'read',
+            description: 'test reused same-domain tabs do not reset conversation state',
+            browser: true,
+            strategy: Strategy.COOKIE,
+            domain: 'grok.com',
+            browserSession: { reuse: 'site' },
+            func: async () => [{ ok: true }],
+        });
+        await executeCommand(cmd, {});
+        expect(goto).not.toHaveBeenCalled();
+        expect(closeWindow).not.toHaveBeenCalled();
+        vi.restoreAllMocks();
+    });
+    it('keeps explicit path pre-navigation for site-reused browser sessions', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const goto = vi.fn().mockResolvedValue(undefined);
+        const mockPage = {
+            closeWindow,
+            goto,
+            getCurrentUrl: vi.fn().mockResolvedValue('https://example.com/other'),
+        };
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'browser-reuse-path-prenav', access: 'read',
+            description: 'test explicit path pre-navigation still runs',
+            browser: true,
+            strategy: Strategy.COOKIE,
+            domain: 'example.com',
+            navigateBefore: 'https://example.com/dashboard',
+            browserSession: { reuse: 'site' },
+            func: async () => [{ ok: true }],
+        });
+        await executeCommand(cmd, {});
+        expect(goto).toHaveBeenCalledWith('https://example.com/dashboard');
+        expect(closeWindow).not.toHaveBeenCalled();
+        vi.restoreAllMocks();
+    });
+    it('respects navigateBefore=false so adapter range validation fails before browser navigation', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const goto = vi.fn().mockResolvedValue(undefined);
+        const mockPage = {
+            closeWindow,
+            goto,
+            getCurrentUrl: vi.fn().mockResolvedValue('about:blank'),
+        };
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'browser-invalid-limit-no-prenav', access: 'read',
+            description: 'test adapter range validation can fail before pre-nav',
+            browser: true,
+            strategy: Strategy.COOKIE,
+            domain: 'www.facebook.com',
+            navigateBefore: false,
+            args: [
+                { name: 'limit', type: 'int', required: false, default: 15, help: 'Limit' },
+            ],
+            func: async (_page, args) => {
+                const limit = Number(args.limit);
+                if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+                    throw new ArgumentError('--limit must be a positive integer in [1, 100]');
+                }
+                return [{ ok: true }];
+            },
+        });
+        await expect(executeCommand(cmd, { limit: 0 })).rejects.toBeInstanceOf(ArgumentError);
+        expect(goto).not.toHaveBeenCalled();
+        vi.restoreAllMocks();
+    });
+    it('rejects invalid --timeout values instead of falling back to the browser default', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const mockPage = { closeWindow };
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+        const runWithTimeoutSpy = vi.spyOn(runtime, 'runWithTimeout');
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'browser-invalid-timeout', access: 'read',
+            description: 'test invalid browser --timeout fails upfront',
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            args: [
+                { name: 'timeout', type: 'int', required: false, default: 5, help: 'Max seconds' },
+            ],
+            func: async () => [{ ok: true }],
+        });
+        await expect(executeCommand(cmd, { timeout: 0 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(executeCommand(cmd, { timeout: -1 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(executeCommand(cmd, { timeout: 1.5 })).rejects.toBeInstanceOf(ArgumentError);
+        expect(runWithTimeoutSpy).not.toHaveBeenCalled();
+        vi.restoreAllMocks();
+    });
+    it('rejects invalid browser --timeout before opening a session or pre-navigating', async () => {
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        const browserSessionSpy = vi.spyOn(runtime, 'browserSession');
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'browser-invalid-timeout-prenav', access: 'read',
+            description: 'test invalid browser --timeout fails before session setup',
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            navigateBefore: 'https://example.com/',
+            args: [
+                { name: 'timeout', type: 'int', required: false, default: 5, help: 'Max seconds' },
+            ],
+            func: async () => [{ ok: true }],
+        });
+        await expect(executeCommand(cmd, { timeout: 0 })).rejects.toBeInstanceOf(ArgumentError);
+        expect(browserSessionSpy).not.toHaveBeenCalled();
+        vi.restoreAllMocks();
     });
     it('calls closeWindow on browser command failure', async () => {
         const closeWindow = vi.fn().mockResolvedValue(undefined);
@@ -53,7 +362,7 @@ describe('executeCommand — non-browser timeout', () => {
         });
         const cmd = cli({
             site: 'test-execution',
-            name: 'browser-close-on-error',
+            name: 'browser-close-on-error', access: 'read',
             description: 'test closeWindow on failure',
             browser: true,
             strategy: Strategy.PUBLIC,
@@ -73,7 +382,7 @@ describe('executeCommand — non-browser timeout', () => {
         try {
             const cmd = cli({
                 site: 'test-execution',
-                name: 'browser-live-success',
+                name: 'browser-live-success', access: 'read',
                 description: 'test closeWindow skipped with --live on success',
                 browser: true,
                 strategy: Strategy.PUBLIC,
@@ -100,7 +409,7 @@ describe('executeCommand — non-browser timeout', () => {
         try {
             const cmd = cli({
                 site: 'test-execution',
-                name: 'browser-live-failure',
+                name: 'browser-live-failure', access: 'read',
                 description: 'test closeWindow skipped with --live on failure',
                 browser: true,
                 strategy: Strategy.PUBLIC,
@@ -121,7 +430,7 @@ describe('executeCommand — non-browser timeout', () => {
         const validateArgs = vi.fn();
         const cmd = {
             site: 'test-execution',
-            name: 'prepared-validation',
+            name: 'prepared-validation', access: 'read',
             description: 'test prepared validation path',
             browser: false,
             strategy: Strategy.PUBLIC,
@@ -164,7 +473,7 @@ describe('executeCommand — non-browser timeout', () => {
         try {
             const cmd = cli({
                 site: 'test-execution',
-                name: 'browser-trace-failure',
+                name: 'browser-trace-failure', access: 'read',
                 description: 'test trace export',
                 browser: true,
                 strategy: Strategy.PUBLIC,
@@ -224,7 +533,7 @@ describe('executeCommand — non-browser timeout', () => {
         try {
             const cmd = cli({
                 site: 'test-execution',
-                name: 'browser-trace-success',
+                name: 'browser-trace-success', access: 'read',
                 description: 'test trace export on success',
                 browser: true,
                 strategy: Strategy.PUBLIC,
@@ -281,7 +590,7 @@ describe('executeCommand — non-browser timeout', () => {
         try {
             const cmd = cli({
                 site: 'test-execution',
-                name: 'browser-trace-export-fails',
+                name: 'browser-trace-export-fails', access: 'read',
                 description: 'test trace export failure handling',
                 browser: true,
                 strategy: Strategy.PUBLIC,

package/dist/src/help.d.ts

@@ -0,0 +1,36 @@
+import { Command } from 'commander';
+import type { CliCommand } from './registry.js';
+export type StructuredHelpFormat = 'yaml' | 'json';
+export declare function getRequestedHelpFormat(argv?: readonly string[]): StructuredHelpFormat | undefined;
+export declare function renderStructuredHelp(data: unknown, format: StructuredHelpFormat): string;
+export declare function wrapCommaList(items: readonly string[], opts?: {
+    width?: number;
+    indent?: string;
+}): string;
+/**
+ * Adapter category for help-text grouping.
+ *
+ * - `site`: web site adapter (real DNS-style domain, e.g. `www.bilibili.com`)
+ * - `app`: desktop app adapter (Electron/osascript, signaled by `domain: 'localhost'`
+ *   or other non-DNS string like `'doubao-app'`)
+ *
+ * Classification is derived from the adapter's `domain` field — no new schema
+ * required. Adapters without a `domain` field default to `site` (most are
+ * public web scrapers).
+ */
+export type AdapterKind = 'site' | 'app';
+export declare function classifyAdapter(domain: string | undefined): AdapterKind;
+export interface RootAdapterGroups {
+    /** Externally-registered CLIs (docker, gh, vercel, ...) — passthrough binaries */
+    external: readonly string[];
+    /** Desktop-app adapters (chatgpt-app, chatwise, codex, ...) */
+    apps: readonly string[];
+    /** Web-site adapters (bilibili, dianping, ...) */
+    sites: readonly string[];
+}
+export declare function formatRootAdapterHelpText(groups: RootAdapterGroups): string;
+export declare function rootHelpData(program: Command, groups: RootAdapterGroups): Record<string, unknown>;
+export declare function siteHelpData(site: string, commands: readonly CliCommand[]): Record<string, unknown>;
+export declare function commandHelpData(cmd: CliCommand): Record<string, unknown>;
+export declare function installStructuredHelp(command: Command, data: () => unknown, textSuffix?: string | (() => string)): void;
+export declare function formatSiteCommandDescription(cmd: CliCommand): string;

package/dist/src/help.js

@@ -0,0 +1,171 @@
+import yaml from 'js-yaml';
+import { fullName } from './registry.js';
+import { formatCommandExample } from './serialization.js';
+function normalizeStructuredHelpFormat(value) {
+    const normalized = value?.toLowerCase();
+    if (normalized === 'yaml' || normalized === 'yml')
+        return 'yaml';
+    if (normalized === 'json')
+        return 'json';
+    return undefined;
+}
+export function getRequestedHelpFormat(argv = process.argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '-f' || token === '--format') {
+            return normalizeStructuredHelpFormat(argv[i + 1]);
+        }
+        if (token.startsWith('--format=')) {
+            return normalizeStructuredHelpFormat(token.slice('--format='.length));
+        }
+        if (token.startsWith('-f') && token.length > 2) {
+            return normalizeStructuredHelpFormat(token.slice(2));
+        }
+    }
+    return undefined;
+}
+export function renderStructuredHelp(data, format) {
+    if (format === 'json')
+        return `${JSON.stringify(data, null, 2)}\n`;
+    return yaml.dump(data, { sortKeys: false, lineWidth: 120, noRefs: true });
+}
+export function wrapCommaList(items, opts = {}) {
+    const width = Math.max(opts.width ?? process.stdout.columns ?? 100, 40);
+    const indent = opts.indent ?? '  ';
+    const sorted = [...items].sort((a, b) => a.localeCompare(b));
+    const lines = [];
+    let line = indent;
+    sorted.forEach((item, index) => {
+        const token = `${item}${index < sorted.length - 1 ? ',' : ''}`;
+        const prefix = line === indent ? '' : ' ';
+        if (line.length + prefix.length + token.length > width && line.trim()) {
+            lines.push(line);
+            line = `${indent}${token}`;
+        }
+        else {
+            line += `${prefix}${token}`;
+        }
+    });
+    if (line.trim())
+        lines.push(line);
+    return lines.join('\n');
+}
+export function classifyAdapter(domain) {
+    if (!domain)
+        return 'site';
+    return domain.includes('.') ? 'site' : 'app';
+}
+function formatGroupSection(label, names) {
+    if (names.length === 0)
+        return [];
+    return [
+        `${label} (${names.length}):`,
+        wrapCommaList(names),
+        '',
+    ];
+}
+export function formatRootAdapterHelpText(groups) {
+    const total = groups.external.length + groups.apps.length + groups.sites.length;
+    if (total === 0)
+        return '';
+    const lines = [''];
+    lines.push(...formatGroupSection('External CLIs', groups.external));
+    lines.push(...formatGroupSection('App adapters', groups.apps));
+    lines.push(...formatGroupSection('Site adapters', groups.sites));
+    lines.push("Run 'opencli list' for full command details, or 'opencli <site> --help' to inspect one site.");
+    lines.push("Agent tip: use 'opencli <site> --help -f yaml' for structured commands, args, access, and examples.");
+    lines.push('');
+    return lines.join('\n');
+}
+function compactArg(arg) {
+    return {
+        name: arg.name,
+        ...(arg.type && arg.type !== 'string' ? { type: arg.type } : {}),
+        ...(arg.positional ? { positional: true } : {}),
+        ...(arg.required ? { required: true } : {}),
+        ...(arg.valueRequired ? { valueRequired: true } : {}),
+        ...(arg.default !== undefined ? { default: arg.default } : {}),
+        ...(arg.choices?.length ? { choices: arg.choices } : {}),
+        ...(arg.help ? { help: arg.help } : {}),
+    };
+}
+function compactCommand(cmd, opts = {}) {
+    return {
+        name: cmd.name,
+        command: `opencli ${cmd.site} ${cmd.name}`,
+        access: cmd.access,
+        description: cmd.description,
+        ...(cmd.aliases?.length ? { aliases: cmd.aliases } : {}),
+        args: cmd.args.map(compactArg),
+        example: formatCommandExample(cmd),
+        ...(cmd.browserSession ? { browserSession: cmd.browserSession } : {}),
+        ...(cmd.defaultFormat ? { defaultFormat: cmd.defaultFormat } : {}),
+        ...(opts.includeColumns && cmd.columns?.length ? { columns: cmd.columns } : {}),
+    };
+}
+export function rootHelpData(program, groups) {
+    const adapterNames = new Set([...groups.external, ...groups.apps, ...groups.sites]);
+    const commands = program.commands
+        .filter(command => !adapterNames.has(command.name()))
+        .map(command => ({
+        name: command.name(),
+        description: command.description(),
+    }));
+    const sortLocale = (a, b) => a.localeCompare(b);
+    return {
+        name: program.name(),
+        description: program.description(),
+        commands,
+        external_clis: {
+            count: groups.external.length,
+            clis: [...groups.external].sort(sortLocale),
+        },
+        app_adapters: {
+            count: groups.apps.length,
+            apps: [...groups.apps].sort(sortLocale),
+        },
+        site_adapters: {
+            count: groups.sites.length,
+            sites: [...groups.sites].sort(sortLocale),
+        },
+        next: [
+            'opencli <site> --help -f yaml',
+            'opencli list -f yaml',
+            'opencli <site> <command> -f yaml',
+        ],
+    };
+}
+export function siteHelpData(site, commands) {
+    const unique = [...new Map(commands.map(cmd => [fullName(cmd), cmd])).values()]
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        site,
+        command_count: unique.length,
+        commands: unique.map(cmd => compactCommand(cmd)),
+        next: [
+            `opencli ${site} <command> --help -f yaml`,
+            `opencli ${site} <command> -f yaml`,
+        ],
+    };
+}
+export function commandHelpData(cmd) {
+    return {
+        site: cmd.site,
+        ...compactCommand(cmd, { includeColumns: true }),
+        output_formats: ['table', 'plain', 'yaml', 'json', 'md', 'csv'],
+    };
+}
+export function installStructuredHelp(command, data, textSuffix) {
+    const original = command.helpInformation.bind(command);
+    command.helpInformation = ((contextOptions) => {
+        const format = getRequestedHelpFormat();
+        if (format)
+            return renderStructuredHelp(data(), format);
+        const suffix = typeof textSuffix === 'function' ? textSuffix() : textSuffix ?? '';
+        return original(contextOptions) + suffix;
+    });
+}
+export function formatSiteCommandDescription(cmd) {
+    const access = cmd.access === 'write' ? '[write]' : '[read]';
+    return `${access} ${cmd.description}`;
+}

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

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