@agentrhq/webcmd 0.1.1 → 0.1.2

package/dist/src/cli-argv-preprocess.js

@@ -0,0 +1,303 @@
+/**
+ * argv preprocessing: rewrite `webcmd browser <session> <subcommand> ...`
+ * into `webcmd browser --session <session> <subcommand> ...` so commander
+ * (which can't combine a parent positional with subcommand dispatch) can parse it.
+ *
+ * The user-facing form is positional; the internal form uses --session. Help text
+ * for the `browser` command is overridden to advertise the positional form.
+ */
+/**
+ * Browser subcommand names. If `<session>` would collide with one of these,
+ * we treat it as a missing-positional error and leave argv alone so commander
+ * reports a usable diagnostic.
+ *
+ * Keep in sync with the subcommands declared on the `browser` command in cli.ts.
+ */
+const BROWSER_SUBCOMMAND_NAMES = new Set([
+    'analyze',
+    'back',
+    'bind',
+    'check',
+    'click',
+    'close',
+    'console',
+    'dblclick',
+    'dialog',
+    'drag',
+    'eval',
+    'extract',
+    'fill',
+    'find',
+    'focus',
+    'frames',
+    'get',
+    'help',
+    'hover',
+    'init',
+    'keys',
+    'network',
+    'open',
+    'screenshot',
+    'scroll',
+    'select',
+    'state',
+    'tab',
+    'type',
+    'unbind',
+    'uncheck',
+    'upload',
+    'verify',
+    'wait',
+]);
+/**
+ * Root program options that consume the following token as their value. Used by
+ * the preprocessor to identify which token is the root command name (so e.g.
+ * `webcmd --profile work browser foo state` is recognised as the `browser`
+ * command with `<session>=foo`, not the value of --profile).
+ *
+ * Keep in sync with `program.option(...)` calls in cli.ts.
+ */
+const ROOT_VALUE_FLAGS = new Set(['--profile']);
+/**
+ * Returns the set of reserved subcommand names (exposed for tests so they stay
+ * synced with the actual registrations in cli.ts).
+ */
+export function getBrowserSubcommandNames() {
+    return BROWSER_SUBCOMMAND_NAMES;
+}
+/**
+ * Rewrite `argv` to convert the positional `<session>` after `browser`
+ * into the internal `--session <name>` flag form.
+ *
+ * Only acts when `browser` is the root command (i.e. the first non-flag token
+ * after any leading root options), so it can't mis-interpret occurrences of
+ * the literal word `browser` deeper in the argv (e.g. `webcmd adapter init
+ * browser/x`, or a URL value containing `browser`).
+ *
+ * Leaves argv unchanged when:
+ *   - root command is not `browser`
+ *   - the token after `browser` is a flag (e.g. `--help`)
+ *   - the token after `browser` is a known subcommand name (session was
+ *     omitted; commander will surface its own required-flag error)
+ */
+export function rewriteBrowserArgv(argv) {
+    const result = [...argv];
+    // Walk past leading root flags + their values to find the root command token.
+    let i = 0;
+    while (i < result.length) {
+        const tok = result[i];
+        if (!tok.startsWith('-'))
+            break;
+        // `--flag=value` consumes one slot regardless of whether the flag expects a value.
+        if (tok.includes('=')) {
+            i += 1;
+            continue;
+        }
+        if (ROOT_VALUE_FLAGS.has(tok) && i + 1 < result.length) {
+            i += 2;
+        }
+        else {
+            i += 1;
+        }
+    }
+    if (result[i] !== 'browser')
+        return result;
+    const sessionIdx = i + 1;
+    const next = result[sessionIdx];
+    if (next === undefined)
+        return result;
+    // The retired `--session` flag must not be a working public entrance.
+    if (next === '--session' || next === '--session=' || next.startsWith('--session=')) {
+        throw new BrowserSessionArgvError('The `--session` flag is no longer a public option. Use the positional form: webcmd browser <session> <command>');
+    }
+    if (next.startsWith('-'))
+        return result;
+    if (BROWSER_SUBCOMMAND_NAMES.has(next))
+        return result;
+    // Splice in --session <name> in place of the positional.
+    result.splice(sessionIdx, 1, '--session', next);
+    // `--window` is a browser namespace option, so commander accepts it before the
+    // leaf command. Users naturally put it at the end:
+    // `browser work open https://x.com --window background`. Hoist that public
+    // form into the namespace-option slot instead of mirroring the option onto
+    // every browser leaf command.
+    hoistBrowserWindowOption(result, sessionIdx + 2);
+    return result;
+}
+/**
+ * Move one trailing `--window <mode>` / `--window=<mode>` from after the browser
+ * subcommand to just before it. Stops at `--` so literal browser arguments are
+ * untouched. Mutates `argv` in place.
+ */
+function hoistBrowserWindowOption(argv, fromIndex) {
+    const subcommandIdx = argv.findIndex((tok, idx) => idx >= fromIndex && BROWSER_SUBCOMMAND_NAMES.has(tok));
+    if (subcommandIdx === -1)
+        return;
+    for (let i = subcommandIdx + 1; i < argv.length; i += 1) {
+        const tok = argv[i];
+        if (tok === '--')
+            return;
+        if (tok.startsWith('--window=')) {
+            const removed = argv.splice(i, 1);
+            argv.splice(subcommandIdx, 0, ...removed);
+            return;
+        }
+        if (tok === '--window') {
+            const value = argv[i + 1];
+            if (value === undefined || value === '--')
+                return;
+            const removed = argv.splice(i, 2);
+            argv.splice(subcommandIdx, 0, ...removed);
+            return;
+        }
+    }
+}
+/**
+ * Thrown by the preprocessor when user argv uses a retired/old form that we
+ * intentionally refuse to accept. main.ts catches this and exits with a
+ * usage error so it does not bubble up as an internal stacktrace.
+ */
+export class BrowserSessionArgvError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BrowserSessionArgvError';
+    }
+}
+function knownCommandOptions(cmd) {
+    const options = new Map([
+        ['-h', 'none'],
+        ['--help', 'none'],
+        ['-v', 'none'],
+        ['--verbose', 'none'],
+        ['-f', 'required'],
+        ['--format', 'required'],
+        ['--trace', 'required'],
+    ]);
+    if (cmd.browser) {
+        options.set('--window', 'required');
+        options.set('--site-session', 'required');
+        options.set('--keep-tab', 'required');
+    }
+    for (const arg of cmd.args ?? []) {
+        if (arg.positional)
+            continue;
+        // Keep in sync with commanderAdapter.ts:
+        // required/valueRequired -> `<value>`; otherwise -> `[value]`.
+        options.set(`--${arg.name}`, arg.required || arg.valueRequired ? 'required' : 'optional');
+    }
+    return options;
+}
+function consumeKnownOption(argv, index, options) {
+    const token = argv[index];
+    if (!token || token === '--')
+        return null;
+    const eq = token.indexOf('=');
+    const key = eq === -1 ? token : token.slice(0, eq);
+    const mode = options.get(key);
+    if (!mode && eq === -1 && token.startsWith('-') && !token.startsWith('--') && token.length > 2) {
+        const shortKey = token.slice(0, 2);
+        const shortMode = options.get(shortKey);
+        if (shortMode === 'required') {
+            return { values: [token], nextIndex: index + 1 };
+        }
+    }
+    if (!mode)
+        return null;
+    if (eq !== -1 || mode === 'none')
+        return { values: [token], nextIndex: index + 1 };
+    const next = argv[index + 1];
+    if (mode === 'required') {
+        return next === undefined
+            ? { values: [token], nextIndex: index + 1 }
+            : { values: [token, next], nextIndex: index + 2 };
+    }
+    if (next !== undefined && !next.startsWith('-')) {
+        return { values: [token, next], nextIndex: index + 2 };
+    }
+    return { values: [token], nextIndex: index + 1 };
+}
+/**
+ * `webcmd boss detail -abc123def` fails because commander parses
+ * `-abc123def` as an unknown option rather than the required
+ * `<security-id>` positional. BOSS 直聘 securityId tokens are opaque
+ * strings that can legitimately start with `-` (issue #1160), and the
+ * same shape can show up in any adapter that takes an opaque-id
+ * positional. Insert a `--` separator so commander treats the next
+ * token as the positional value.
+ */
+export function escapeLeadingDashPositional(argv, manifest) {
+    const result = [...argv];
+    const requiredFirstPositional = new Map();
+    for (const cmd of manifest) {
+        const first = cmd.args?.find((a) => a.positional);
+        if (first?.required)
+            requiredFirstPositional.set(cmd.site + '/' + cmd.name, cmd);
+    }
+    let i = 0;
+    while (i < result.length) {
+        const tok = result[i];
+        if (!tok.startsWith('-'))
+            break;
+        if (tok.includes('=')) {
+            i += 1;
+            continue;
+        }
+        if (ROOT_VALUE_FLAGS.has(tok) && i + 1 < result.length) {
+            i += 2;
+        }
+        else {
+            i += 1;
+        }
+    }
+    const site = result[i];
+    const cmd = result[i + 1];
+    const positionalIdx = i + 2;
+    if (!site || !cmd || positionalIdx >= result.length)
+        return result;
+    const entry = requiredFirstPositional.get(site + '/' + cmd);
+    if (!entry)
+        return result;
+    const options = knownCommandOptions(entry);
+    const beforePositional = [];
+    let j = positionalIdx;
+    while (j < result.length) {
+        const token = result[j];
+        if (token === '--')
+            return result;
+        const consumed = consumeKnownOption(result, j, options);
+        if (consumed) {
+            beforePositional.push(...consumed.values);
+            j = consumed.nextIndex;
+            continue;
+        }
+        if (!token.startsWith('-'))
+            return result;
+        if (token.startsWith('--'))
+            return result;
+        break;
+    }
+    if (j >= result.length)
+        return result;
+    const positional = result[j];
+    const trailingOptions = [];
+    const trailingRest = [];
+    j += 1;
+    while (j < result.length) {
+        const consumed = consumeKnownOption(result, j, options);
+        if (consumed) {
+            trailingOptions.push(...consumed.values);
+            j = consumed.nextIndex;
+            continue;
+        }
+        trailingRest.push(result[j]);
+        j += 1;
+    }
+    return [
+        ...result.slice(0, positionalIdx),
+        ...beforePositional,
+        ...trailingOptions,
+        '--',
+        positional,
+        ...trailingRest,
+    ];
+}

package/dist/src/cli-argv-preprocess.test.d.ts

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

package/dist/src/cli-argv-preprocess.test.js

@@ -0,0 +1,304 @@
+import { describe, expect, it } from 'vitest';
+import { getBrowserSubcommandNames, rewriteBrowserArgv } from './cli-argv-preprocess.js';
+describe('rewriteBrowserArgv', () => {
+    it('rewrites `browser <session> <subcommand>` into `browser --session <name> <subcommand>`', () => {
+        expect(rewriteBrowserArgv(['browser', 'work', 'state'])).toEqual([
+            'browser',
+            '--session',
+            'work',
+            'state',
+        ]);
+    });
+    it('rewrites with subcommand arguments preserved', () => {
+        expect(rewriteBrowserArgv(['browser', 'mercury', 'open', 'https://x.com'])).toEqual([
+            'browser',
+            '--session',
+            'mercury',
+            'open',
+            'https://x.com',
+        ]);
+    });
+    it('rewrites `browser <session> bind`', () => {
+        expect(rewriteBrowserArgv(['browser', 'mercury', 'bind'])).toEqual([
+            'browser',
+            '--session',
+            'mercury',
+            'bind',
+        ]);
+    });
+    it('leaves argv alone when session omitted and a subcommand follows', () => {
+        // Commander surfaces the required-flag error itself.
+        expect(rewriteBrowserArgv(['browser', 'state'])).toEqual(['browser', 'state']);
+        expect(rewriteBrowserArgv(['browser', 'bind'])).toEqual(['browser', 'bind']);
+    });
+    it('leaves argv alone when the token after `browser` is a flag', () => {
+        expect(rewriteBrowserArgv(['browser', '--help'])).toEqual(['browser', '--help']);
+        expect(rewriteBrowserArgv(['browser', '-h'])).toEqual(['browser', '-h']);
+    });
+    it('refuses the retired `webcmd browser --session foo ...` user form', () => {
+        // The flag form is no longer a public entrance. Tests calling
+        // program.parseAsync directly bypass the preprocessor, so internal
+        // callers still work; but the user-facing pipeline throws.
+        expect(() => rewriteBrowserArgv(['browser', '--session', 'foo', 'state']))
+            .toThrowError(/no longer a public option/i);
+        expect(() => rewriteBrowserArgv(['browser', '--session=foo', 'state']))
+            .toThrowError(/no longer a public option/i);
+    });
+    it('leaves argv alone when `browser` is not present', () => {
+        expect(rewriteBrowserArgv(['twitter', 'tweets', '@elonmusk'])).toEqual([
+            'twitter',
+            'tweets',
+            '@elonmusk',
+        ]);
+        expect(rewriteBrowserArgv(['doctor'])).toEqual(['doctor']);
+    });
+    it('returns argv unchanged when `browser` is the last token', () => {
+        expect(rewriteBrowserArgv(['browser'])).toEqual(['browser']);
+    });
+    it('only rewrites when `browser` is the root command, not deeper in argv', () => {
+        // `webcmd adapter init browser/x` — the literal `browser` is a path argument,
+        // not the root command. Must not be touched.
+        expect(rewriteBrowserArgv(['adapter', 'init', 'browser', 'x'])).toEqual([
+            'adapter',
+            'init',
+            'browser',
+            'x',
+        ]);
+        // Same for URLs or arbitrary arg values that happen to contain `browser`.
+        expect(rewriteBrowserArgv(['twitter', 'tweets', 'https://browser.example.com'])).toEqual([
+            'twitter',
+            'tweets',
+            'https://browser.example.com',
+        ]);
+        // First-match heuristic must NOT rewrite when an earlier non-flag token
+        // already established a different root command.
+        expect(rewriteBrowserArgv(['list', 'browser', 'state'])).toEqual([
+            'list',
+            'browser',
+            'state',
+        ]);
+    });
+    it('skips leading root flags before identifying the root command', () => {
+        // `--profile` takes a value — the value is not the command.
+        expect(rewriteBrowserArgv(['--profile', 'work', 'browser', 'mercury', 'state'])).toEqual([
+            '--profile',
+            'work',
+            'browser',
+            '--session',
+            'mercury',
+            'state',
+        ]);
+        // Long form with `=` separator consumes one slot only.
+        expect(rewriteBrowserArgv(['--profile=work', 'browser', 'mercury', 'state'])).toEqual([
+            '--profile=work',
+            'browser',
+            '--session',
+            'mercury',
+            'state',
+        ]);
+        // Boolean flags don't consume values.
+        expect(rewriteBrowserArgv(['-v', 'browser', 'mercury', 'state'])).toEqual([
+            '-v',
+            'browser',
+            '--session',
+            'mercury',
+            'state',
+        ]);
+    });
+    it('hoists a trailing browser --window option to the namespace slot', () => {
+        expect(rewriteBrowserArgv(['browser', 'work', 'open', 'https://x.com', '--window', 'background'])).toEqual([
+            'browser',
+            '--session',
+            'work',
+            '--window',
+            'background',
+            'open',
+            'https://x.com',
+        ]);
+        expect(rewriteBrowserArgv(['browser', 'work', 'state', '--window', 'foreground'])).toEqual([
+            'browser',
+            '--session',
+            'work',
+            '--window',
+            'foreground',
+            'state',
+        ]);
+    });
+    it('hoists trailing browser --window after leading root options', () => {
+        expect(rewriteBrowserArgv(['--profile', 'sandbox', 'browser', 'work', 'state', '--window', 'background'])).toEqual([
+            '--profile',
+            'sandbox',
+            'browser',
+            '--session',
+            'work',
+            '--window',
+            'background',
+            'state',
+        ]);
+    });
+    it('hoists a trailing browser --window=<mode> option', () => {
+        expect(rewriteBrowserArgv(['browser', 'work', 'open', 'https://x.com', '--window=background'])).toEqual([
+            'browser',
+            '--session',
+            'work',
+            '--window=background',
+            'open',
+            'https://x.com',
+        ]);
+    });
+    it('hoists browser --window after nested browser leaf commands', () => {
+        expect(rewriteBrowserArgv(['browser', 'work', 'get', 'url', '--window', 'background'])).toEqual([
+            'browser',
+            '--session',
+            'work',
+            '--window',
+            'background',
+            'get',
+            'url',
+        ]);
+        expect(rewriteBrowserArgv(['browser', 'work', 'tab', 'close', 'abc123', '--window', 'background'])).toEqual([
+            'browser',
+            '--session',
+            'work',
+            '--window',
+            'background',
+            'tab',
+            'close',
+            'abc123',
+        ]);
+    });
+    it('leaves an already parent-slot browser --window option untouched', () => {
+        expect(rewriteBrowserArgv(['browser', 'work', '--window', 'background', 'open', 'https://x.com'])).toEqual([
+            'browser',
+            '--session',
+            'work',
+            '--window',
+            'background',
+            'open',
+            'https://x.com',
+        ]);
+    });
+    it('does not hoist browser --window after a literal -- separator', () => {
+        expect(rewriteBrowserArgv(['browser', 'work', 'eval', 'console.log(1)', '--', '--window', 'background'])).toEqual([
+            'browser',
+            '--session',
+            'work',
+            'eval',
+            'console.log(1)',
+            '--',
+            '--window',
+            'background',
+        ]);
+    });
+    it('does not hoist a bare trailing browser --window without a value', () => {
+        expect(rewriteBrowserArgv(['browser', 'work', 'open', 'https://x.com', '--window'])).toEqual([
+            'browser',
+            '--session',
+            'work',
+            'open',
+            'https://x.com',
+            '--window',
+        ]);
+    });
+    it('leaves argv alone when the root command is not `browser`, even if `browser` appears later', () => {
+        // The first browser keyword does NOT win — it must be at the root.
+        expect(rewriteBrowserArgv(['twitter', 'browser', 'work', 'state'])).toEqual([
+            'twitter',
+            'browser',
+            'work',
+            'state',
+        ]);
+    });
+    it('reserved subcommand list covers every known browser subcommand registered in cli.ts', () => {
+        const names = getBrowserSubcommandNames();
+        const required = [
+            'analyze', 'back', 'bind', 'check', 'click', 'close', 'console', 'dblclick',
+            'dialog', 'drag', 'eval', 'extract', 'fill', 'find', 'focus', 'frames',
+            'get', 'hover', 'init', 'keys', 'network', 'open', 'screenshot', 'scroll',
+            'select', 'state', 'tab', 'type', 'unbind', 'uncheck', 'upload', 'verify',
+            'wait',
+        ];
+        for (const name of required) {
+            expect(names.has(name)).toBe(true);
+        }
+    });
+});
+import { escapeLeadingDashPositional } from './cli-argv-preprocess.js';
+describe('escapeLeadingDashPositional', () => {
+    const manifest = [
+        { site: 'boss', name: 'detail', browser: true, args: [{ name: 'security-id', positional: true, required: true }, { name: 'retry', positional: false, valueRequired: true }] },
+        { site: 'boss', name: 'search', args: [{ name: 'query', positional: true, required: false }, { name: 'limit', positional: false }] },
+        { site: 'twitter', name: 'follow', args: [{ name: 'username', positional: true, required: true }] },
+        { site: 'twitter', name: 'lists', args: [{ name: 'limit', positional: false }] },
+    ];
+    it('inserts -- before a required positional starting with `-`', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', '-abc123def'], manifest))
+            .toEqual(['boss', 'detail', '--', '-abc123def']);
+    });
+    it('preserves trailing flags after the dash-leading positional', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', '-xyz', '-f', 'json'], manifest))
+            .toEqual(['boss', 'detail', '-f', 'json', '--', '-xyz']);
+    });
+    it('preserves attached short option values like commander does', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', '-fjson', '-xyz'], manifest))
+            .toEqual(['boss', 'detail', '-fjson', '--', '-xyz']);
+        expect(escapeLeadingDashPositional(['boss', 'detail', '-xyz', '-fjson'], manifest))
+            .toEqual(['boss', 'detail', '-fjson', '--', '-xyz']);
+    });
+    it('handles known options before a dash-leading positional', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', '--format', 'json', '--trace=on', '-xyz'], manifest))
+            .toEqual(['boss', 'detail', '--format', 'json', '--trace=on', '--', '-xyz']);
+    });
+    it('keeps adapter and browser options parseable when they follow the positional', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', '-xyz', '--retry', '2', '--window', 'foreground'], manifest))
+            .toEqual(['boss', 'detail', '--retry', '2', '--window', 'foreground', '--', '-xyz']);
+    });
+    it('protects negative numeric positionals too', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', '-42'], manifest))
+            .toEqual(['boss', 'detail', '--', '-42']);
+    });
+    it('leaves unknown dash options untouched instead of hiding them behind --', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', '--unknown', 'value'], manifest))
+            .toEqual(['boss', 'detail', '--unknown', 'value']);
+    });
+    it('does not touch positional values that do not start with -', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', 'normal-id'], manifest))
+            .toEqual(['boss', 'detail', 'normal-id']);
+    });
+    it('does not touch the recognised short flags -f / -v / -h', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', '-f', 'json'], manifest))
+            .toEqual(['boss', 'detail', '-f', 'json']);
+        expect(escapeLeadingDashPositional(['boss', 'detail', '-v'], manifest))
+            .toEqual(['boss', 'detail', '-v']);
+    });
+    it('does not touch long flags (--*)', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', '--format', 'json'], manifest))
+            .toEqual(['boss', 'detail', '--format', 'json']);
+    });
+    it('does not touch already-escaped --', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', '--', '-already-escaped'], manifest))
+            .toEqual(['boss', 'detail', '--', '-already-escaped']);
+    });
+    it('does not touch commands without a required positional', () => {
+        expect(escapeLeadingDashPositional(['boss', 'search', '-something'], manifest))
+            .toEqual(['boss', 'search', '-something']);
+        expect(escapeLeadingDashPositional(['twitter', 'lists', '-something'], manifest))
+            .toEqual(['twitter', 'lists', '-something']);
+    });
+    it('works when --profile or another root flag precedes the site', () => {
+        expect(escapeLeadingDashPositional(['--profile', 'work', 'boss', 'detail', '-abc'], manifest))
+            .toEqual(['--profile', 'work', 'boss', 'detail', '--', '-abc']);
+    });
+    it('works for any adapter, not just boss', () => {
+        expect(escapeLeadingDashPositional(['twitter', 'follow', '-someuser'], manifest))
+            .toEqual(['twitter', 'follow', '--', '-someuser']);
+    });
+    it('returns argv unchanged when the command is unknown', () => {
+        expect(escapeLeadingDashPositional(['unknown', 'cmd', '-arg'], manifest))
+            .toEqual(['unknown', 'cmd', '-arg']);
+    });
+    it('returns argv unchanged when argv is too short', () => {
+        expect(escapeLeadingDashPositional(['boss'], manifest)).toEqual(['boss']);
+        expect(escapeLeadingDashPositional(['boss', 'detail'], manifest)).toEqual(['boss', 'detail']);
+    });
+});