@agentrhq/webcmd 0.1.1 → 0.1.2

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`, `企业微信`) 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,110 @@
+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();
+            }
+        }
+    });
+    it('registers Longbridge with safe package-manager installers only', () => {
+        const raw = fs.readFileSync(path.join(__dirname, 'external-clis.yaml'), 'utf8');
+        const entries = (yaml.load(raw) || []);
+        const longbridge = entries.find((entry) => entry.name === 'longbridge');
+        expect(longbridge).toMatchObject({
+            binary: 'longbridge',
+            homepage: 'https://open.longbridge.com/zh-CN/docs/cli/',
+            install: {
+                mac: 'brew install --cask longbridge/tap/longbridge-terminal',
+                windows: 'scoop install https://open.longbridge.com/longbridge/longbridge-terminal/longbridge.json',
+            },
+        });
+        expect(longbridge?.install?.linux).toBeUndefined();
+        expect(longbridge?.install?.default).toBeUndefined();
+    });
+});
+describe('formatExternalCliLabel', () => {
+    it('shows the package name when the executable name differs', () => {
+        expect(formatExternalCliLabel({ name: 'wx', binary: 'wx', package: 'wx-cli' })).toBe('wx(wx-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: 'wecom-cli', binary: 'wecom-cli', package: '企业微信' })).toBe('wecom-cli(企业微信)');
+    });
+});
+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/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.bilibili.com`)
+ * - `app`: desktop app adapter (Electron/osascript, signaled by `domain: 'localhost'`
+ *   or other non-DNS/local endpoint string like `'127.0.0.1'` / `'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
+ * `['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;