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.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 RootExternalCli[];
    /** Desktop-app adapters (chatgpt-app, chatwise, codex, ...) */
    apps: readonly string[];
    /** Web-site adapters (bilibili, dianping, ...) */
    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
 * `['opencli', '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;