@agentrhq/webcmd 0.1.1 → 0.2.0

package/dist/src/external-clis.yaml

@@ -37,34 +37,6 @@
   install:
     default: "npm install -g @larksuite/cli"
 
-- name: longbridge
-  binary: longbridge
-  description: "Longbridge CLI — AI-native market data, account management and trading commands for Longbridge OpenAPI"
-  homepage: "https://open.longbridge.com/zh-CN/docs/cli/"
-  tags: [longbridge, finance, trading, market-data, openapi, ai-agent]
-  install:
-    mac: "brew install --cask longbridge/tap/longbridge-terminal"
-    windows: "scoop install https://open.longbridge.com/longbridge/longbridge-terminal/longbridge.json"
-
-- name: dws
-  binary: dws
-  package: DingTalk Workspace
-  description: "DingTalk Workspace CLI — messages, docs, calendar, contacts and more for humans and AI agents"
-  homepage: "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli"
-  tags: [dingtalk, collaboration, productivity, ai-agent]
-  install:
-    mac: "npm install -g dingtalk-workspace-cli"
-    linux: "npm install -g dingtalk-workspace-cli"
-
-- name: wecom-cli
-  binary: wecom-cli
-  package: 企业微信
-  description: "WeCom/企业微信 CLI — contacts, todos, meetings, messages, calendar, docs and smart sheets for AI agents"
-  homepage: "https://github.com/WecomTeam/wecom-cli"
-  tags: [wecom, wechat-work, collaboration, productivity, ai-agent]
-  install:
-    default: "npm install -g @wecom/cli"
-
 - name: vercel
   binary: vercel
   description: "Vercel CLI — deploy projects, manage domains, env vars, logs and serverless functions"
@@ -91,15 +63,6 @@
   install:
     default: "uv tool install kabi-discord-cli"
 
-- name: wx
-  binary: wx
-  package: wx-cli
-  description: "WeChat local data CLI — sessions, messages, search, contacts, export for AI agents"
-  homepage: "https://github.com/jackwener/wx-cli"
-  tags: [wechat, messaging, search, export, ai-agent]
-  install:
-    default: "npm install -g @jackwener/wx-cli"
-
 - name: wrangler
   binary: wrangler
   description: "Cloudflare Wrangler — deploy Workers, manage R2/D1/KV, publish Pages"

package/dist/src/external.d.ts

@@ -0,0 +1,49 @@
+export interface ExternalCliInstall {
+    mac?: string;
+    linux?: string;
+    windows?: string;
+    default?: string;
+}
+export interface ExternalCliConfig {
+    /** User-facing Webcmd subcommand and, by default, the executable name. */
+    name: string;
+    binary: string;
+    /**
+     * Display alias rendered alongside `name` in help/listing as `name(package)`.
+     * Use either the upstream distribution/project name (e.g. `tg-cli`, `discord-cli`)
+     * or a human-readable brand label (e.g. `notion`, `linear`) when the bare
+     * executable name is ambiguous.
+     */
+    package?: string;
+    description?: string;
+    homepage?: string;
+    tags?: string[];
+    install?: ExternalCliInstall;
+}
+export declare function loadExternalClis(): ExternalCliConfig[];
+export declare function isBinaryInstalled(binary: string): boolean;
+export declare function getInstallCmd(installConfig?: ExternalCliInstall): string | null;
+export declare function formatExternalCliLabel(cli: ExternalCliConfig): string;
+/**
+ * Safely parses a command string into a binary and argument list.
+ * Rejects commands containing shell operators (&&, ||, |, ;, >, <, `) that
+ * cannot be safely expressed as execFileSync arguments.
+ *
+ * Args:
+ *   cmd: Raw command string from YAML config (e.g. "brew install gh")
+ *
+ * Returns:
+ *   Object with `binary` and `args` fields, or throws on unsafe input.
+ */
+export declare function parseCommand(cmd: string): {
+    binary: string;
+    args: string[];
+};
+export declare function installExternalCli(cli: ExternalCliConfig): boolean;
+export declare function executeExternalCli(name: string, args: string[], preloaded?: ExternalCliConfig[]): void;
+export interface RegisterOptions {
+    binary?: string;
+    install?: string;
+    description?: string;
+}
+export declare function registerExternalCli(name: string, opts?: RegisterOptions): void;

package/dist/src/external.js

@@ -0,0 +1,211 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { spawnSync, execFileSync } from 'node:child_process';
+import yaml from 'js-yaml';
+import { log } from './logger.js';
+import { EXIT_CODES, getErrorMessage } from './errors.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+function getUserRegistryPath() {
+    const home = os.homedir();
+    return path.join(home, '.webcmd', 'external-clis.yaml');
+}
+let _cachedExternalClis = null;
+export function loadExternalClis() {
+    if (_cachedExternalClis)
+        return _cachedExternalClis;
+    const configs = new Map();
+    // 1. Load built-in
+    const builtinPath = path.resolve(__dirname, 'external-clis.yaml');
+    try {
+        if (fs.existsSync(builtinPath)) {
+            const raw = fs.readFileSync(builtinPath, 'utf8');
+            const parsed = (yaml.load(raw) || []);
+            for (const item of parsed)
+                configs.set(item.name, item);
+        }
+    }
+    catch (err) {
+        log.warn(`Failed to parse built-in external-clis.yaml: ${getErrorMessage(err)}`);
+    }
+    // 2. Load user custom
+    const userPath = getUserRegistryPath();
+    try {
+        if (fs.existsSync(userPath)) {
+            const raw = fs.readFileSync(userPath, 'utf8');
+            const parsed = (yaml.load(raw) || []);
+            for (const item of parsed) {
+                configs.set(item.name, item); // Overwrite built-in if duplicated
+            }
+        }
+    }
+    catch (err) {
+        log.warn(`Failed to parse user external-clis.yaml: ${getErrorMessage(err)}`);
+    }
+    _cachedExternalClis = Array.from(configs.values()).sort((a, b) => a.name.localeCompare(b.name));
+    return _cachedExternalClis;
+}
+export function isBinaryInstalled(binary) {
+    try {
+        const isWindows = os.platform() === 'win32';
+        execFileSync(isWindows ? 'where' : 'which', [binary], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function getInstallCmd(installConfig) {
+    if (!installConfig)
+        return null;
+    const platform = os.platform();
+    if (platform === 'darwin' && installConfig.mac)
+        return installConfig.mac;
+    if (platform === 'linux' && installConfig.linux)
+        return installConfig.linux;
+    if (platform === 'win32' && installConfig.windows)
+        return installConfig.windows;
+    if (installConfig.default)
+        return installConfig.default;
+    return null;
+}
+export function formatExternalCliLabel(cli) {
+    return cli.package && cli.package !== cli.name ? `${cli.name}(${cli.package})` : cli.name;
+}
+/**
+ * Safely parses a command string into a binary and argument list.
+ * Rejects commands containing shell operators (&&, ||, |, ;, >, <, `) that
+ * cannot be safely expressed as execFileSync arguments.
+ *
+ * Args:
+ *   cmd: Raw command string from YAML config (e.g. "brew install gh")
+ *
+ * Returns:
+ *   Object with `binary` and `args` fields, or throws on unsafe input.
+ */
+export function parseCommand(cmd) {
+    const shellOperators = /&&|\|\|?|;|[><`$#\n\r]|\$\(/;
+    if (shellOperators.test(cmd)) {
+        throw new Error(`Install command contains unsafe shell operators and cannot be executed securely: "${cmd}". ` +
+            `Please install the tool manually.`);
+    }
+    // Tokenise respecting single- and double-quoted segments (no variable expansion).
+    const tokens = [];
+    const re = /(?:"([^"]*)")|(?:'([^']*)')|(\S+)/g;
+    let match;
+    while ((match = re.exec(cmd)) !== null) {
+        tokens.push(match[1] ?? match[2] ?? match[3]);
+    }
+    if (tokens.length === 0) {
+        throw new Error(`Install command is empty.`);
+    }
+    const [binary, ...args] = tokens;
+    return { binary, args };
+}
+function shouldRetryWithCmdShim(binary, err) {
+    const code = err instanceof Error ? err.code : undefined;
+    return os.platform() === 'win32' && !path.extname(binary) && code === 'ENOENT';
+}
+function runInstallCommand(cmd) {
+    const { binary, args } = parseCommand(cmd);
+    try {
+        execFileSync(binary, args, { stdio: 'inherit' });
+    }
+    catch (err) {
+        if (shouldRetryWithCmdShim(binary, err)) {
+            execFileSync(`${binary}.cmd`, args, { stdio: 'inherit' });
+            return;
+        }
+        throw err;
+    }
+}
+export function installExternalCli(cli) {
+    if (!cli.install) {
+        log.error(`No auto-install command configured for '${cli.name}'.`);
+        log.info(`Please install '${cli.binary}' manually.`);
+        return false;
+    }
+    const cmd = getInstallCmd(cli.install);
+    if (!cmd) {
+        log.error(`No install command for your platform (${os.platform()}) for '${cli.name}'.`);
+        if (cli.homepage)
+            log.info(`See: ${cli.homepage}`);
+        return false;
+    }
+    log.info(`'${cli.name}' is not installed. Auto-installing...`);
+    log.verbose(`$ ${cmd}`);
+    try {
+        runInstallCommand(cmd);
+        log.success(`Installed '${cli.name}' successfully.`);
+        return true;
+    }
+    catch (err) {
+        log.error(`Failed to install '${cli.name}': ${getErrorMessage(err)}`);
+        return false;
+    }
+}
+export function executeExternalCli(name, args, preloaded) {
+    const configs = preloaded ?? loadExternalClis();
+    const cli = configs.find((c) => c.name === name);
+    if (!cli) {
+        throw new Error(`External CLI '${name}' not found in registry.`);
+    }
+    // 1. Check if installed
+    if (!isBinaryInstalled(cli.binary)) {
+        // 2. Try to auto install
+        const success = installExternalCli(cli);
+        if (!success) {
+            process.exitCode = EXIT_CODES.SERVICE_UNAVAIL;
+            return;
+        }
+    }
+    // 3. Passthrough execution with stdio inherited
+    const result = spawnSync(cli.binary, args, { stdio: 'inherit' });
+    if (result.error) {
+        log.error(`Failed to execute '${cli.binary}': ${result.error.message}`);
+        process.exitCode = EXIT_CODES.GENERIC_ERROR;
+        return;
+    }
+    if (result.status !== null) {
+        process.exitCode = result.status;
+    }
+}
+export function registerExternalCli(name, opts) {
+    const userPath = getUserRegistryPath();
+    const configDir = path.dirname(userPath);
+    if (!fs.existsSync(configDir)) {
+        fs.mkdirSync(configDir, { recursive: true });
+    }
+    let items = [];
+    if (fs.existsSync(userPath)) {
+        try {
+            const raw = fs.readFileSync(userPath, 'utf8');
+            items = (yaml.load(raw) || []);
+        }
+        catch {
+            // Ignore
+        }
+    }
+    const existingIndex = items.findIndex((c) => c.name === name);
+    const newItem = {
+        name,
+        binary: opts?.binary || name,
+    };
+    if (opts?.description)
+        newItem.description = opts.description;
+    if (opts?.install)
+        newItem.install = { default: opts.install };
+    if (existingIndex >= 0) {
+        items[existingIndex] = { ...items[existingIndex], ...newItem };
+        log.success(`Updated '${name}' in user registry.`);
+    }
+    else {
+        items.push(newItem);
+        log.success(`Registered '${name}' in user registry.`);
+    }
+    const dump = yaml.dump(items, { indent: 2, sortKeys: true });
+    fs.writeFileSync(userPath, dump, 'utf8');
+    _cachedExternalClis = null; // Invalidate cache so next load reflects the change
+    log.verbose(userPath);
+}

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

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

package/dist/src/external.test.js

@@ -0,0 +1,95 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import yaml from 'js-yaml';
+const { mockExecFileSync, mockPlatform } = vi.hoisted(() => ({
+    mockExecFileSync: vi.fn(),
+    mockPlatform: vi.fn(() => 'darwin'),
+}));
+vi.mock('node:child_process', () => ({
+    spawnSync: vi.fn(),
+    execFileSync: mockExecFileSync,
+}));
+vi.mock('node:os', async () => {
+    const actual = await vi.importActual('node:os');
+    return {
+        ...actual,
+        platform: mockPlatform,
+    };
+});
+import { formatExternalCliLabel, installExternalCli, parseCommand } from './external.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+describe('parseCommand', () => {
+    it('splits binaries and quoted arguments without invoking a shell', () => {
+        expect(parseCommand('npm install -g "@scope/tool name"')).toEqual({
+            binary: 'npm',
+            args: ['install', '-g', '@scope/tool name'],
+        });
+    });
+    it('rejects shell operators', () => {
+        expect(() => parseCommand('brew install gh && rm -rf /')).toThrow('Install command contains unsafe shell operators');
+    });
+    it('rejects command substitution and multiline input', () => {
+        expect(() => parseCommand('brew install $(whoami)')).toThrow('Install command contains unsafe shell operators');
+        expect(() => parseCommand('brew install gh\nrm -rf /')).toThrow('Install command contains unsafe shell operators');
+    });
+    it('keeps built-in install commands compatible with the shell-free parser', () => {
+        const raw = fs.readFileSync(path.join(__dirname, 'external-clis.yaml'), 'utf8');
+        const entries = (yaml.load(raw) || []);
+        for (const entry of entries) {
+            for (const command of Object.values(entry.install ?? {})) {
+                if (command)
+                    expect(() => parseCommand(command)).not.toThrow();
+            }
+        }
+    });
+});
+describe('formatExternalCliLabel', () => {
+    it('shows the package name when the executable name differs', () => {
+        expect(formatExternalCliLabel({ name: 'tg', binary: 'tg', package: 'tg-cli' })).toBe('tg(tg-cli)');
+    });
+    it('keeps the label compact when package and name match', () => {
+        expect(formatExternalCliLabel({ name: 'docker', binary: 'docker', package: 'docker' })).toBe('docker');
+    });
+    it('renders a human-readable brand alias for ambiguous executable names', () => {
+        expect(formatExternalCliLabel({ name: 'ntn', binary: 'ntn', package: 'notion' })).toBe('ntn(notion)');
+        expect(formatExternalCliLabel({ name: 'lin', binary: 'lin', package: 'linear' })).toBe('lin(linear)');
+    });
+});
+describe('installExternalCli', () => {
+    const cli = {
+        name: 'readwise',
+        binary: 'readwise',
+        install: {
+            default: 'npm install -g @readwiseio/readwise-cli',
+        },
+    };
+    beforeEach(() => {
+        mockExecFileSync.mockReset();
+        mockPlatform.mockReturnValue('darwin');
+    });
+    it('retries with .cmd on Windows when the bare binary is unavailable', () => {
+        mockPlatform.mockReturnValue('win32');
+        mockExecFileSync
+            .mockImplementationOnce(() => {
+            const err = new Error('not found');
+            err.code = 'ENOENT';
+            throw err;
+        })
+            .mockReturnValueOnce(Buffer.from(''));
+        expect(installExternalCli(cli)).toBe(true);
+        expect(mockExecFileSync).toHaveBeenNthCalledWith(1, 'npm', ['install', '-g', '@readwiseio/readwise-cli'], { stdio: 'inherit' });
+        expect(mockExecFileSync).toHaveBeenNthCalledWith(2, 'npm.cmd', ['install', '-g', '@readwiseio/readwise-cli'], { stdio: 'inherit' });
+    });
+    it('does not mask non-ENOENT failures', () => {
+        mockPlatform.mockReturnValue('win32');
+        mockExecFileSync.mockImplementationOnce(() => {
+            const err = new Error('permission denied');
+            err.code = 'EACCES';
+            throw err;
+        });
+        expect(installExternalCli(cli)).toBe(false);
+        expect(mockExecFileSync).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/src/generate-release-notes-cli.test.d.ts

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

package/dist/src/generate-release-notes-cli.test.js

@@ -0,0 +1,140 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it, vi } from 'vitest';
+import { loadReleaseContext, runGenerateReleaseNotes } from '../scripts/generate-release-notes.js';
+function createIo() {
+    let stdout = '';
+    let stderr = '';
+    return {
+        io: {
+            writeStdout(chunk) {
+                stdout += chunk;
+            },
+            writeStderr(chunk) {
+                stderr += chunk;
+            },
+        },
+        read() {
+            return { stdout, stderr };
+        },
+    };
+}
+describe('runGenerateReleaseNotes', () => {
+    it('exits 1 with usage text when the tag argument is missing', async () => {
+        const { io, read } = createIo();
+        const exitCode = await runGenerateReleaseNotes(['node', 'script'], {}, {}, io);
+        expect(exitCode).toBe(1);
+        expect(read()).toEqual({
+            stdout: '',
+            stderr: 'Usage: generate-release-notes <tag>\n',
+        });
+    });
+    it('exits 0 and leaves stdout empty when GEMINI_API_KEY is missing', async () => {
+        const { io, read } = createIo();
+        const exitCode = await runGenerateReleaseNotes(['node', 'script', 'v0.0.0'], {}, {}, io);
+        expect(exitCode).toBe(0);
+        expect(read()).toEqual({
+            stdout: '',
+            stderr: 'GEMINI_API_KEY is not set; leaving release-please notes unchanged.\n',
+        });
+    });
+    it('normalizes generated markdown before printing it to stdout', async () => {
+        const { io, read } = createIo();
+        const context = {
+            tag: 'v1.2.3',
+            previousTag: 'v1.2.2',
+            currentRef: 'abcdef1',
+            pullRequests: [
+                {
+                    number: 42,
+                    title: 'feat: improve release notes',
+                    author: { login: 'alice' },
+                    labels: [],
+                    files: [],
+                    url: 'https://example.com/42',
+                },
+            ],
+        };
+        const loadContext = vi.fn(async () => context);
+        const generateText = vi.fn(async () => '## Highlights\n- Better summaries.');
+        const exitCode = await runGenerateReleaseNotes(['node', 'script', 'v1.2.3'], { GEMINI_API_KEY: 'test-key' }, { loadContext, generateText }, io);
+        expect(exitCode).toBe(0);
+        expect(loadContext).toHaveBeenCalledWith('v1.2.3', { GEMINI_API_KEY: 'test-key' });
+        expect(generateText).toHaveBeenCalledOnce();
+        expect(read()).toEqual({
+            stdout: [
+                '## Highlights',
+                '- Better summaries.',
+                '',
+                '## Improvements',
+                'None.',
+                '',
+                '## Fixes',
+                'None.',
+                '',
+                '## Contributors',
+                '- @alice',
+                '',
+                '## Reverts',
+                'None.',
+                '',
+            ].join('\n'),
+            stderr: '',
+        });
+    });
+    it('swallows generator errors and keeps release-please notes intact', async () => {
+        const { io, read } = createIo();
+        const loadContext = vi.fn(async () => {
+            throw new Error('gh timed out');
+        });
+        const exitCode = await runGenerateReleaseNotes(['node', 'script', 'v1.2.3'], { GEMINI_API_KEY: 'test-key' }, { loadContext }, io);
+        expect(exitCode).toBe(0);
+        expect(read()).toEqual({
+            stdout: '',
+            stderr: 'Gemini release notes failed: gh timed out\n',
+        });
+    });
+    it('loads bounded PR diffs into release context', async () => {
+        const gh = vi.fn((args) => {
+            const key = args.join(' ');
+            if (key === 'api repos/acme/webcmd/releases?per_page=100') {
+                return JSON.stringify([{ tag_name: 'v1.2.3' }, { tag_name: 'v1.2.2' }]);
+            }
+            if (key === 'api repos/acme/webcmd/compare/v1.2.2...v1.2.3') {
+                return JSON.stringify({
+                    commits: [
+                        { sha: 'abc123', commit: { message: 'feat: improve releases (#42)\n\nBody' } },
+                    ],
+                });
+            }
+            if (key === 'api repos/acme/webcmd/pulls/42') {
+                return JSON.stringify({
+                    number: 42,
+                    title: 'feat: improve releases',
+                    body: 'Release polish.',
+                    user: { login: 'alice' },
+                    labels: [{ name: 'feature' }],
+                    html_url: 'https://github.com/acme/webcmd/pull/42',
+                    merged_at: '2026-07-03T00:00:00Z',
+                });
+            }
+            if (key === 'api repos/acme/webcmd/pulls/42/files?per_page=100') {
+                return JSON.stringify([{ filename: 'src/release-notes.ts' }]);
+            }
+            if (key === 'pr diff 42 --repo acme/webcmd') {
+                return `diff --git a/src/release-notes.ts b/src/release-notes.ts\n${'x'.repeat(80)}`;
+            }
+            throw new Error(`unexpected gh call: ${key}`);
+        });
+        const context = await loadReleaseContext('v1.2.3', { GITHUB_REPOSITORY: 'acme/webcmd' }, { gh, maxDiffCharacters: 40 });
+        expect(context.pullRequests).toHaveLength(1);
+        expect(context.pullRequests[0]?.diff).toBe('diff --git a/src/release-notes.ts b/src/\n[diff truncated]');
+        expect(gh).toHaveBeenCalledWith(['pr', 'diff', '42', '--repo', 'acme/webcmd']);
+    });
+    it('keeps npm publish unblocked when enhanced release-note editing fails', () => {
+        const workflowPath = fileURLToPath(new URL('../.github/workflows/release.yml', import.meta.url));
+        const workflow = readFileSync(workflowPath, 'utf8');
+        expect(workflow).toMatch(/if gh release edit "\$\{\{ steps\.release\.outputs\.tag_name \}\}" --notes-file "\$RUNNER_TEMP\/release-notes\.md"; then/);
+        expect(workflow).toMatch(/Enhanced release notes could not be applied; keeping release-please notes\./);
+    });
+});

package/dist/src/help.d.ts

@@ -0,0 +1,88 @@
+import { Command } from 'commander';
+import type { CliCommand } from './registry.js';
+export type StructuredHelpFormat = 'yaml' | 'json';
+export interface ArgSpec {
+    name: string;
+    required?: true;
+    variadic?: true;
+    help?: string;
+    default?: unknown;
+    choices?: string[];
+}
+export interface OptionSpec {
+    name: string;
+    flags: string;
+    help?: string;
+    takes_value?: 'required' | 'optional';
+    required?: true;
+    default?: unknown;
+    choices?: string[];
+    negate?: true;
+}
+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.youtube.com`)
+ * - `app`: desktop app adapter (Electron/osascript, signaled by `domain: 'localhost'`
+ *   or other non-DNS/local endpoint string like `'127.0.0.1'` / `'custom-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 RootExternalCli[];
+    /** Desktop-app adapters (chatgpt-app, chatwise, codex, ...) */
+    apps: readonly string[];
+    /** Web-site adapters (youtube, reddit, github, ...) */
+    sites: readonly string[];
+}
+export interface RootExternalCli {
+    name: string;
+    label: string;
+}
+export declare function formatRootAdapterHelpText(groups: RootAdapterGroups): string;
+/**
+ * Extracts a positional placeholder that should appear immediately after this
+ * command's name in user-facing path strings. Reads the leading positional
+ * (e.g. `<session>`) from a `.usage()` override; commands without a positional
+ * override return `null` so the path stays as-is.
+ *
+ * Example: `browser` declares `.usage('<session> <command> [options]')`,
+ * so `commanderPath(browserClickCmd)` becomes
+ * `['webcmd', 'browser', '<session>', 'click']`.
+ */
+export declare function leadingPositionalFromUsage(command: Command): string | null;
+export declare function commanderNamespaceHelpData(namespaceRoot: Command, opts?: {
+    globalCommand?: Command;
+    description?: string;
+}): Record<string, unknown>;
+export declare function commanderCommandHelpData(namespaceRoot: Command, command: Command, opts?: {
+    globalCommand?: Command;
+}): Record<string, unknown>;
+export declare function commanderGroupHelpData(namespaceRoot: Command, groupCommand: Command, opts?: {
+    globalCommand?: Command;
+}): Record<string, unknown>;
+export declare function installCommanderNamespaceStructuredHelp(namespaceRoot: Command, opts?: {
+    globalCommand?: Command;
+    description?: string;
+}): void;
+export declare function formatCommandListTerm(cmd: CliCommand): 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 formatCommonOptionsHelpText(): string;
+export declare function formatBrowserCommonOptionsHelpText(): string;
+export declare function formatSiteHelpText(site: string, commands: readonly CliCommand[]): string;
+export declare function formatCommandHelpText(cmd: CliCommand): string;
+export declare function installStructuredHelp(command: Command, data: () => unknown, textSuffix?: string | (() => string)): void;
+export declare function formatSiteCommandDescription(cmd: CliCommand): string;