@agentrhq/webcmd 0.1.1 → 0.2.0

package/dist/src/build-manifest.test.js

@@ -0,0 +1,341 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { cli, getRegistry, Strategy } from './registry.js';
+import { ManifestImportError, diffRemovedEntries, findManifestMetadataIssues, loadManifestEntries, normalizeManifestPath, parseBuildManifestArgs, scanClisDir, serializeManifest, } from './build-manifest.js';
+describe('manifest helper rules', () => {
+    const tempDirs = [];
+    afterEach(() => {
+        for (const dir of tempDirs.splice(0)) {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('skips TS files that do not register a cli', () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-manifest-'));
+        tempDirs.push(dir);
+        const file = path.join(dir, 'utils.ts');
+        fs.writeFileSync(file, `export function helper() { return 'noop'; }`);
+        return expect(loadManifestEntries(file, 'demo', async () => ({}))).resolves.toEqual([]);
+    });
+    it('builds TS manifest entries from exported runtime commands', async () => {
+        const site = `manifest-hydrate-${Date.now()}`;
+        const key = `${site}/dynamic`;
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-manifest-'));
+        tempDirs.push(dir);
+        const file = path.join(dir, `${site}.ts`);
+        fs.writeFileSync(file, `export const command = cli({ site: '${site}', name: 'dynamic', access: 'read' });`);
+        const entries = await loadManifestEntries(file, site, async () => ({
+            command: cli({
+                site,
+                name: 'dynamic',
+                access: 'read',
+                description: 'dynamic command',
+                strategy: Strategy.PUBLIC,
+                browser: false,
+                aliases: ['metadata'],
+                args: [
+                    {
+                        name: 'model',
+                        required: true,
+                        positional: true,
+                        help: 'Choose a model',
+                        choices: ['auto', 'thinking'],
+                        default: '30',
+                    },
+                ],
+                domain: 'localhost',
+                navigateBefore: 'https://example.com/session',
+                defaultFormat: 'plain',
+            }),
+        }));
+        expect(entries).toMatchObject([
+            {
+                site,
+                name: 'dynamic',
+                access: 'read',
+                description: 'dynamic command',
+                domain: 'localhost',
+                strategy: 'public',
+                browser: false,
+                aliases: ['metadata'],
+                args: [
+                    expect.objectContaining({
+                        name: 'model',
+                        type: 'str',
+                        required: true,
+                        positional: true,
+                        help: 'Choose a model',
+                        choices: ['auto', 'thinking'],
+                        default: '30',
+                    }),
+                ],
+                type: 'js',
+                modulePath: `${site}/${site}.js`,
+                navigateBefore: 'https://example.com/session',
+                defaultFormat: 'plain',
+            },
+        ]);
+        // Verify sourceFile is included and stable for manifest consumers.
+        expect(entries[0].sourceFile).toBeDefined();
+        expect(entries[0].sourceFile).not.toContain('\\');
+        getRegistry().delete(key);
+    });
+    it('falls back to registry delta for side-effect-only cli modules', async () => {
+        const site = `manifest-side-effect-${Date.now()}`;
+        const key = `${site}/legacy`;
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-manifest-'));
+        tempDirs.push(dir);
+        const file = path.join(dir, `${site}.ts`);
+        fs.writeFileSync(file, `cli({ site: '${site}', name: 'legacy', access: 'read' });`);
+        const entries = await loadManifestEntries(file, site, async () => {
+            cli({
+                site,
+                name: 'legacy',
+                access: 'read',
+                description: 'legacy command',
+            });
+            return {};
+        });
+        expect(entries).toMatchObject([
+            {
+                site,
+                name: 'legacy',
+                access: 'read',
+                description: 'legacy command',
+                strategy: 'cookie',
+                browser: true,
+                args: [],
+                type: 'js',
+                modulePath: `${site}/${site}.js`,
+            },
+        ]);
+        // Verify sourceFile is included
+        expect(entries[0].sourceFile).toBeDefined();
+        getRegistry().delete(key);
+    });
+    it('keeps every command a module exports instead of guessing by site', async () => {
+        const site = `manifest-multi-${Date.now()}`;
+        const screenKey = `${site}/screen`;
+        const statusKey = `${site}/status`;
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-manifest-'));
+        tempDirs.push(dir);
+        const file = path.join(dir, `${site}.ts`);
+        fs.writeFileSync(file, `export const screen = cli({ site: '${site}', name: 'screen', access: 'read' });`);
+        const entries = await loadManifestEntries(file, site, async () => ({
+            screen: cli({
+                site,
+                name: 'screen',
+                access: 'read',
+                description: 'capture screen',
+            }),
+            status: cli({
+                site,
+                name: 'status',
+                access: 'read',
+                description: 'show status',
+            }),
+        }));
+        expect(entries.map(entry => entry.name)).toEqual(['screen', 'status']);
+        getRegistry().delete(screenKey);
+        getRegistry().delete(statusKey);
+    });
+    it('normalizes manifest paths to POSIX separators', () => {
+        expect(normalizeManifestPath('demo\\status.js')).toBe('demo/status.js');
+        expect(normalizeManifestPath('demo/status.js')).toBe('demo/status.js');
+    });
+    it('serializes manifest json with a trailing newline', () => {
+        const serialized = serializeManifest([{
+                site: 'demo',
+                name: 'status', access: 'read',
+                description: '',
+                strategy: 'public',
+                browser: false,
+                args: [],
+                type: 'js',
+            }]);
+        expect(serialized.endsWith('\n')).toBe(true);
+        expect(serialized).toContain('\n]');
+    });
+    it('throws ManifestImportError when an adapter looks like a CLI module but fails to import', async () => {
+        // Reproduces the "stale dist drops adapters silently" incident: the file
+        // matches the cli() pattern (so it's not just a helper), but the importer
+        // throws — we want the failure surfaced, not swallowed.
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-manifest-fail-'));
+        tempDirs.push(dir);
+        const file = path.join(dir, 'broken.ts');
+        fs.writeFileSync(file, `export const command = cli({ site: 'demo', name: 'broken', access: 'read' });`);
+        const importer = async () => { throw new Error('boom: stale dist'); };
+        await expect(loadManifestEntries(file, 'demo', importer))
+            .rejects.toBeInstanceOf(ManifestImportError);
+        try {
+            await loadManifestEntries(file, 'demo', importer);
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(ManifestImportError);
+            const e = err;
+            expect(e.filePath).toBe(file);
+            expect(e.message).toContain('boom: stale dist');
+        }
+    });
+    it('still silently skips files that do not call cli() even if the importer would have thrown', async () => {
+        // The cli() pattern check happens before importing — we don't even ask
+        // the importer about helper modules, so a thrown import does not turn
+        // them into failures.
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-manifest-helper-'));
+        tempDirs.push(dir);
+        const file = path.join(dir, 'helper.ts');
+        fs.writeFileSync(file, `export const helper = () => 42;`);
+        const importer = async () => { throw new Error('should never be called'); };
+        await expect(loadManifestEntries(file, 'demo', importer)).resolves.toEqual([]);
+    });
+    it('scanClisDir aggregates per-adapter import failures instead of silently dropping them', async () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-clis-'));
+        tempDirs.push(root);
+        const siteDir = path.join(root, 'demo');
+        fs.mkdirSync(siteDir);
+        fs.writeFileSync(path.join(siteDir, 'good.js'), `export const cmd = cli({ site: 'demo', name: 'good', access: 'read' });`);
+        fs.writeFileSync(path.join(siteDir, 'broken.js'), `export const cmd = cli({ site: 'demo', name: 'broken', access: 'read' });`);
+        const importer = async (href) => {
+            if (href.endsWith('broken.js'))
+                throw new Error('stale dist drops broken');
+            return { cmd: cli({ site: 'demo', name: 'good', access: 'read', description: 'ok' }) };
+        };
+        const result = await scanClisDir(root, importer);
+        expect(result.failures).toHaveLength(1);
+        expect(result.failures[0]).toBeInstanceOf(ManifestImportError);
+        expect(result.failures[0].filePath).toMatch(/broken\.js$/);
+        expect(result.failures[0].message).toContain('stale dist drops broken');
+        expect(result.entries.map(e => e.name)).toEqual(['good']);
+        getRegistry().delete('demo/good');
+    });
+    it('diffRemovedEntries returns site/name keys present only in prev', () => {
+        const prev = [
+            { site: 'a', name: '1', access: 'read', description: '', strategy: 'public', browser: false, args: [], type: 'js' },
+            { site: 'a', name: '2', access: 'read', description: '', strategy: 'public', browser: false, args: [], type: 'js' },
+            { site: 'b', name: '3', access: 'read', description: '', strategy: 'public', browser: false, args: [], type: 'js' },
+        ];
+        const next = [
+            { site: 'a', name: '1', access: 'read', description: '', strategy: 'public', browser: false, args: [], type: 'js' },
+        ];
+        expect(diffRemovedEntries(prev, next)).toEqual(['a/2', 'b/3']);
+        expect(diffRemovedEntries(prev, prev)).toEqual([]);
+        expect(diffRemovedEntries([], next)).toEqual([]);
+    });
+    it('findManifestMetadataIssues flags positionals with empty/missing help', () => {
+        // The build-time hard gate. A positional with `help: ''` or no `help` at
+        // all renders `Arguments:\n  <name>` with a blank trailing column —
+        // unrecoverable for both humans and agents reading help. Failing closed
+        // here is the only way to keep help text trustworthy as adapters land.
+        //
+        // Semantic quality (e.g. what does an *optional* positional mean when
+        // omitted?) is intentionally NOT enforced — that belongs to the planned
+        // Arg metadata v2 advisory pass.
+        const entries = [
+            // Positional with usable help — clean.
+            {
+                site: 'demo',
+                name: 'ok',
+                access: 'read',
+                description: '',
+                strategy: 'public',
+                browser: false,
+                args: [
+                    { name: 'q', positional: true, required: true, help: 'Search query' },
+                ],
+                type: 'js',
+                sourceFile: 'demo/ok.js',
+            },
+            // Positional with empty help string — must flag.
+            {
+                site: 'demo',
+                name: 'empty-help',
+                access: 'read',
+                description: '',
+                strategy: 'public',
+                browser: false,
+                args: [
+                    { name: 'user', positional: true, required: false, help: '' },
+                ],
+                type: 'js',
+                sourceFile: 'demo/empty.js',
+            },
+            // Positional with whitespace-only help — must flag.
+            {
+                site: 'demo',
+                name: 'whitespace-help',
+                access: 'read',
+                description: '',
+                strategy: 'public',
+                browser: false,
+                args: [
+                    { name: 'id', positional: true, required: true, help: '   ' },
+                ],
+                type: 'js',
+            },
+            // Positional with no help field at all — must flag.
+            {
+                site: 'demo',
+                name: 'missing-help',
+                access: 'read',
+                description: '',
+                strategy: 'public',
+                browser: false,
+                args: [
+                    { name: 'name', positional: true, required: true },
+                ],
+                type: 'js',
+            },
+            // NON-positional flag with empty help — must NOT flag (gate is
+            // intentionally scoped to positionals; named flags carry the flag
+            // name itself in the help line).
+            {
+                site: 'demo',
+                name: 'flag-only',
+                access: 'read',
+                description: '',
+                strategy: 'public',
+                browser: false,
+                args: [
+                    { name: 'limit', required: false, help: '' },
+                ],
+                type: 'js',
+            },
+        ];
+        const issues = findManifestMetadataIssues(entries);
+        expect(issues).toHaveLength(3);
+        expect(issues.map(i => `${i.site}/${i.command}/${i.arg}`).sort()).toEqual([
+            'demo/empty-help/user',
+            'demo/missing-help/name',
+            'demo/whitespace-help/id',
+        ]);
+        // sourceFile flows through when present so the build error points at the
+        // exact file to fix.
+        const emptyHelp = issues.find(i => i.command === 'empty-help');
+        expect(emptyHelp?.sourceFile).toBe('demo/empty.js');
+    });
+    it('findManifestMetadataIssues returns [] for fully-documented entries', () => {
+        expect(findManifestMetadataIssues([])).toEqual([]);
+        expect(findManifestMetadataIssues([
+            {
+                site: 'demo',
+                name: 'no-args',
+                access: 'read',
+                description: '',
+                strategy: 'public',
+                browser: false,
+                args: [],
+                type: 'js',
+            },
+        ])).toEqual([]);
+    });
+    it('parseBuildManifestArgs reads --allow-removals[=N]', () => {
+        expect(parseBuildManifestArgs([]).allowRemovals).toBe(0);
+        expect(parseBuildManifestArgs(['--allow-removals=5']).allowRemovals).toBe(5);
+        expect(parseBuildManifestArgs(['--allow-removals=0']).allowRemovals).toBe(0);
+        // Bare flag is the explicit "I know what I'm doing" escape hatch.
+        expect(parseBuildManifestArgs(['--allow-removals']).allowRemovals).toBe(Number.POSITIVE_INFINITY);
+        // Unknown flags are ignored.
+        expect(parseBuildManifestArgs(['--something-else']).allowRemovals).toBe(0);
+    });
+});

package/dist/src/capabilityRouting.d.ts

@@ -0,0 +1,19 @@
+import type { CliCommand } from './registry.js';
+/**
+ * Pipeline steps that require a live browser session.
+ *
+ * Note: this is the *subset* of registered pipeline steps that need a page;
+ * non-browser steps (fetch, select, map, filter, sort, limit, download)
+ * deliberately stay out. The full registered-step list lives in
+ * `src/pipeline/registry.ts` and is re-derived elsewhere via
+ * `getRegisteredStepNames()` (e.g. in `validate.ts`). When you add a new
+ * pipeline step, decide whether it belongs here based on whether its handler
+ * touches the IPage object — and `src/capabilityRouting.test.ts` verifies the
+ * subset relationship is intact.
+ */
+export declare const BROWSER_ONLY_STEPS: Set<string>;
+/** Internal helper: ensure BROWSER_ONLY_STEPS is a subset of registered pipeline steps. */
+export declare function _validateBrowserOnlyStepsAgainstRegistry(): {
+    extras: string[];
+};
+export declare function shouldUseBrowserSession(cmd: CliCommand): boolean;

package/dist/src/capabilityRouting.js

@@ -0,0 +1,56 @@
+import { getRegisteredStepNames } from './pipeline/registry.js';
+/**
+ * Pipeline steps that require a live browser session.
+ *
+ * Note: this is the *subset* of registered pipeline steps that need a page;
+ * non-browser steps (fetch, select, map, filter, sort, limit, download)
+ * deliberately stay out. The full registered-step list lives in
+ * `src/pipeline/registry.ts` and is re-derived elsewhere via
+ * `getRegisteredStepNames()` (e.g. in `validate.ts`). When you add a new
+ * pipeline step, decide whether it belongs here based on whether its handler
+ * touches the IPage object — and `src/capabilityRouting.test.ts` verifies the
+ * subset relationship is intact.
+ */
+export const BROWSER_ONLY_STEPS = new Set([
+    'navigate',
+    'click',
+    'type',
+    'fill',
+    'wait',
+    'press',
+    'snapshot',
+    'evaluate',
+    'intercept',
+    'tap',
+]);
+/** Internal helper: ensure BROWSER_ONLY_STEPS is a subset of registered pipeline steps. */
+export function _validateBrowserOnlyStepsAgainstRegistry() {
+    const registered = new Set(getRegisteredStepNames());
+    const extras = [];
+    for (const step of BROWSER_ONLY_STEPS) {
+        if (!registered.has(step))
+            extras.push(step);
+    }
+    return { extras };
+}
+function pipelineNeedsBrowserSession(pipeline) {
+    return pipeline.some((step) => {
+        if (!step || typeof step !== 'object')
+            return false;
+        return Object.keys(step).some((op) => BROWSER_ONLY_STEPS.has(op));
+    });
+}
+export function shouldUseBrowserSession(cmd) {
+    if (!cmd.browser)
+        return false;
+    if (cmd.func)
+        return true;
+    if (!cmd.pipeline || cmd.pipeline.length === 0)
+        return true;
+    // normalizeCommand sets navigateBefore to a URL string (needs pre-nav) or
+    // boolean true (needs authenticated context, no specific URL). Either way
+    // the pipeline requires a browser session even if no step is browser-only.
+    if (cmd.navigateBefore)
+        return true;
+    return pipelineNeedsBrowserSession(cmd.pipeline);
+}

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

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

package/dist/src/capabilityRouting.test.js

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import { Strategy } from './registry.js';
+import { BROWSER_ONLY_STEPS, _validateBrowserOnlyStepsAgainstRegistry, shouldUseBrowserSession } from './capabilityRouting.js';
+import { getRegisteredStepNames } from './pipeline/registry.js';
+function makeCmd(partial) {
+    return {
+        site: 'test',
+        name: 'command', access: 'read',
+        description: '',
+        args: [],
+        ...partial,
+    };
+}
+describe('shouldUseBrowserSession', () => {
+    it('skips browser session for public fetch-only pipelines', () => {
+        expect(shouldUseBrowserSession(makeCmd({
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            pipeline: [{ fetch: 'https://example.com/api' }, { select: 'items' }],
+        }))).toBe(false);
+    });
+    it('keeps browser session for public pipelines with browser-only steps', () => {
+        expect(shouldUseBrowserSession(makeCmd({
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            pipeline: [{ navigate: 'https://example.com' }, { evaluate: '() => []' }],
+        }))).toBe(true);
+    });
+    it('keeps browser session for non-public strategies (via normalized navigateBefore)', () => {
+        // After normalizeCommand, COOKIE strategy without domain sets navigateBefore: true
+        // (signals "needs authenticated browser context" without a specific pre-nav URL).
+        expect(shouldUseBrowserSession(makeCmd({
+            browser: true,
+            strategy: Strategy.COOKIE,
+            navigateBefore: true,
+            pipeline: [{ fetch: 'https://example.com/api' }],
+        }))).toBe(true);
+    });
+    it('keeps browser session for function adapters', () => {
+        expect(shouldUseBrowserSession(makeCmd({
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            func: async () => [],
+        }))).toBe(true);
+    });
+    it('routes pipelines containing the fill step into a browser session', () => {
+        expect(shouldUseBrowserSession(makeCmd({
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            pipeline: [{ navigate: 'https://example.com' }, { fill: { ref: '#q', text: 'hello' } }],
+        }))).toBe(true);
+    });
+});
+describe('BROWSER_ONLY_STEPS / pipeline registry alignment', () => {
+    it('is a subset of registered pipeline step names', () => {
+        const { extras } = _validateBrowserOnlyStepsAgainstRegistry();
+        expect(extras).toEqual([]);
+    });
+    it('includes fill (DOM-touching step added in PR #1222)', () => {
+        expect(BROWSER_ONLY_STEPS.has('fill')).toBe(true);
+        expect(getRegisteredStepNames()).toContain('fill');
+    });
+});

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

@@ -0,0 +1,63 @@
+/**
+ * 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.
+ */
+/**
+ * Returns the set of reserved subcommand names (exposed for tests so they stay
+ * synced with the actual registrations in cli.ts).
+ */
+export declare function getBrowserSubcommandNames(): ReadonlySet<string>;
+/**
+ * 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 declare function rewriteBrowserArgv(argv: readonly string[]): string[];
+/**
+ * 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 declare class BrowserSessionArgvError extends Error {
+    constructor(message: string);
+}
+/**
+ * Minimal manifest shape consumed by escapeLeadingDashPositional. Imported
+ * lazily by main.ts so this module stays dependency-free.
+ */
+export interface DashPositionalManifestEntry {
+    site: string;
+    name: string;
+    args?: Array<{
+        name: string;
+        positional?: boolean;
+        required?: boolean;
+        valueRequired?: boolean;
+        default?: unknown;
+    }>;
+    browser?: boolean;
+}
+/**
+ * `webcmd openreview paper -abc123def` fails because commander parses
+ * `-abc123def` as an unknown option rather than the required
+ * `<id>` positional. Some adapter identifiers 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 declare function escapeLeadingDashPositional(argv: readonly string[], manifest: readonly DashPositionalManifestEntry[]): string[];