@agentrhq/webcmd 0.2.5 → 0.3.1

package/dist/src/serialization.js

@@ -4,78 +4,28 @@
  * Used by the `list` command, Commander --help, and build-manifest.
  * Separated from registry.ts to keep the registry focused on types + registration.
  */
-import { fullName, strategyLabel } from './registry.js';
-import { CLI_COMMAND } from './brand.js';
+import { commandListRows, formatArgumentSummary, formatPresentableCommandExample, serializePresentableArg, toPresentableCommand, } from './command-presentation.js';
 /** Stable arg schema — every field is always present (no sparse objects). */
 export function serializeArg(a) {
-    return {
-        name: a.name,
-        type: a.type ?? 'string',
-        required: !!a.required,
-        valueRequired: !!a.valueRequired,
-        positional: !!a.positional,
-        choices: a.choices ?? [],
-        default: a.default ?? null,
-        help: a.help ?? '',
-    };
+    return serializePresentableArg(a);
 }
 /** Full command metadata for structured output (json/yaml). */
 export function serializeCommand(cmd) {
-    return {
-        command: fullName(cmd),
-        site: cmd.site,
-        name: cmd.name,
-        aliases: cmd.aliases ?? [],
-        description: cmd.description,
-        access: cmd.access,
-        strategy: strategyLabel(cmd),
-        browser: !!cmd.browser,
-        args: cmd.args.map(serializeArg),
-        columns: cmd.columns ?? [],
-        domain: cmd.domain ?? null,
-        example: formatCommandExample(cmd),
-        defaultFormat: cmd.defaultFormat ?? null,
-        siteSession: cmd.siteSession ?? null,
-    };
+    return commandListRows([toPresentableCommand(cmd)], true)[0];
 }
 // ── Formatting ──────────────────────────────────────────────────────────────
 /** Human-readable arg summary: `<required> [optional]` style. */
 export function formatArgSummary(args) {
-    return args
-        .map(a => {
-        if (a.positional)
-            return a.required ? `<${a.name}>` : `[${a.name}]`;
-        return a.required ? `--${a.name}` : `[--${a.name}]`;
-    })
-        .join(' ');
+    return formatArgumentSummary(args);
 }
 function summarizeChoices(choices) {
     if (choices.length <= 4)
         return choices.join(', ');
     return `${choices.slice(0, 4).join(', ')}, ... (+${choices.length - 4} more)`;
 }
-function formatValuePlaceholder(name) {
-    return `<${name}>`;
-}
 /** Agent-facing canonical invocation. Adapter authors may override with `example`. */
 export function formatCommandExample(cmd) {
-    if (cmd.example?.trim())
-        return cmd.example.trim();
-    const parts = [CLI_COMMAND, cmd.site, cmd.name];
-    for (const arg of cmd.args) {
-        if (arg.positional && arg.required) {
-            parts.push(formatValuePlaceholder(arg.name));
-        }
-    }
-    for (const arg of cmd.args) {
-        if (arg.positional || !arg.required)
-            continue;
-        parts.push(`--${arg.name}`);
-        if (arg.type !== 'bool' && arg.type !== 'boolean')
-            parts.push(formatValuePlaceholder(arg.name));
-    }
-    parts.push('-f', 'yaml');
-    return parts.join(' ');
+    return formatPresentableCommandExample(toPresentableCommand(cmd));
 }
 /** Generate the --help appendix showing registry metadata not exposed by Commander. */
 export function formatRegistryHelpText(cmd) {

package/dist/src/stream-write.d.ts

@@ -0,0 +1,12 @@
+/** A write failure that must not be mistaken for a command/runtime failure. */
+export declare class StreamWriteError extends Error {
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
+/**
+ * Write one complete chunk without taking ownership of the stream.
+ *
+ * Resolution requires both the write callback and, when write() reports
+ * backpressure, the matching drain event. The stream is never ended.
+ */
+export declare function writeToStream(stream: NodeJS.WritableStream, chunk: string | Uint8Array): Promise<void>;

package/dist/src/stream-write.js

@@ -0,0 +1,91 @@
+/** A write failure that must not be mistaken for a command/runtime failure. */
+export class StreamWriteError extends Error {
+    cause;
+    constructor(cause) {
+        super(cause instanceof Error ? cause.message : String(cause));
+        this.name = 'StreamWriteError';
+        this.cause = cause;
+    }
+}
+/**
+ * Write one complete chunk without taking ownership of the stream.
+ *
+ * Resolution requires both the write callback and, when write() reports
+ * backpressure, the matching drain event. The stream is never ended.
+ */
+export function writeToStream(stream, chunk) {
+    return new Promise((resolve, reject) => {
+        const prematureCloseError = new Error('Writable stream closed before the write completed');
+        const streamState = stream;
+        if (streamState.closed || streamState.destroyed) {
+            reject(new StreamWriteError(prematureCloseError));
+            return;
+        }
+        let writeReturned = false;
+        let callbackComplete = false;
+        let requiresDrain = false;
+        let drainSeen = false;
+        let settled = false;
+        let pendingCallbackError;
+        let pendingCallbackFailure;
+        const cleanup = () => {
+            stream.removeListener('error', onError);
+            stream.removeListener('drain', onDrain);
+            stream.removeListener('close', onClose);
+            if (pendingCallbackFailure) {
+                clearImmediate(pendingCallbackFailure);
+                pendingCallbackFailure = undefined;
+            }
+        };
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error instanceof StreamWriteError ? error : new StreamWriteError(error));
+        };
+        const failFromCallback = (error) => {
+            if (settled)
+                return;
+            pendingCallbackError ??= error;
+            // A real Node Writable reports an _write callback failure to the public
+            // write callback and then emits `error`. Keep the error listener until
+            // that paired event has had a chance to arrive, while still bounding
+            // non-standard streams that only invoke the callback.
+            pendingCallbackFailure ??= setImmediate(() => fail(pendingCallbackError));
+        };
+        const finish = () => {
+            if (settled || !writeReturned || !callbackComplete || (requiresDrain && !drainSeen))
+                return;
+            settled = true;
+            cleanup();
+            resolve();
+        };
+        const onError = (error) => fail(error);
+        const onClose = () => fail(pendingCallbackError ?? prematureCloseError);
+        const onDrain = () => {
+            drainSeen = true;
+            finish();
+        };
+        stream.once('error', onError);
+        stream.once('drain', onDrain);
+        stream.once('close', onClose);
+        try {
+            requiresDrain = stream.write(chunk, (error) => {
+                if (error) {
+                    failFromCallback(error);
+                    return;
+                }
+                callbackComplete = true;
+                finish();
+            }) === false;
+            writeReturned = true;
+            if (!requiresDrain)
+                stream.removeListener('drain', onDrain);
+            finish();
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+}

package/dist/src/stream-write.test.d.ts

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

package/dist/src/stream-write.test.js

@@ -0,0 +1,186 @@
+import { EventEmitter } from 'node:events';
+import { Writable } from 'node:stream';
+import { describe, expect, it, vi } from 'vitest';
+import { writeToStream } from './stream-write.js';
+class ManualWritable extends Writable {
+    chunks = [];
+    callbacks = [];
+    constructor() {
+        super({ highWaterMark: 1 });
+    }
+    _write(chunk, _encoding, callback) {
+        this.chunks.push(Buffer.from(chunk));
+        this.callbacks.push(callback);
+    }
+    release(error) {
+        const callback = this.callbacks.shift();
+        if (!callback)
+            throw new Error('No manual write callback is pending');
+        callback(error);
+    }
+}
+class SyntheticBackpressureStream extends EventEmitter {
+    callback;
+    end = vi.fn();
+    write(_chunk, callback) {
+        this.callback = callback;
+        return false;
+    }
+}
+class SyntheticBackpressureWritable extends Writable {
+    callback;
+    write(_chunk, encodingOrCallback, callback) {
+        this.callback = typeof encodingOrCallback === 'function' ? encodingOrCallback : callback;
+        return false;
+    }
+    _write(_chunk, _encoding, callback) {
+        callback();
+    }
+}
+async function within(promise, milliseconds = 500) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error(`promise did not settle within ${milliseconds}ms`)), milliseconds);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+describe('writeToStream', () => {
+    it('waits for both the write callback and backpressure drain', async () => {
+        const stream = new SyntheticBackpressureStream();
+        let settled = false;
+        const write = writeToStream(stream, 'payload').then(() => {
+            settled = true;
+        });
+        stream.callback?.();
+        await Promise.resolve();
+        expect(settled).toBe(false);
+        stream.emit('drain');
+        await write;
+        expect(settled).toBe(true);
+        expect(stream.end).not.toHaveBeenCalled();
+    });
+    it('preserves ordering across multiple awaited writes', async () => {
+        const stream = new ManualWritable();
+        let settled = false;
+        const writes = (async () => {
+            await writeToStream(stream, 'first');
+            await writeToStream(stream, 'second');
+            settled = true;
+        })();
+        expect(stream.callbacks).toHaveLength(1);
+        stream.release();
+        await new Promise(resolve => setImmediate(resolve));
+        expect(stream.callbacks).toHaveLength(1);
+        expect(Buffer.concat(stream.chunks).toString('utf8')).toBe('firstsecond');
+        expect(settled).toBe(false);
+        stream.release();
+        await writes;
+        expect(settled).toBe(true);
+    });
+    it('writes and drains a value larger than one MiB', async () => {
+        const stream = new ManualWritable();
+        const payload = Buffer.alloc(1024 * 1024 + 17, 0x61);
+        const write = writeToStream(stream, payload);
+        expect(stream.chunks[0]).toHaveLength(payload.length);
+        stream.release();
+        await write;
+        expect(Buffer.concat(stream.chunks).equals(payload)).toBe(true);
+    });
+    it('rejects an error emitted before drain without hanging', async () => {
+        const stream = new SyntheticBackpressureStream();
+        const write = writeToStream(stream, 'payload');
+        stream.emit('error', new Error('stream failed before drain'));
+        await expect(write).rejects.toThrow('stream failed before drain');
+    });
+    it('rejects a real Writable callback error without an uncaught error event', async () => {
+        const stream = new ManualWritable();
+        const write = writeToStream(stream, 'payload');
+        stream.release(new Error('real writable callback failed'));
+        await expect(write).rejects.toThrow('real writable callback failed');
+        await new Promise(resolve => setImmediate(resolve));
+    });
+    it('rejects a callback error delivered after drain without double resolution', async () => {
+        const stream = new SyntheticBackpressureStream();
+        const write = writeToStream(stream, 'payload');
+        stream.emit('drain');
+        stream.callback?.(new Error('stream failed after drain'));
+        await expect(write).rejects.toThrow('stream failed after drain');
+    });
+    it('rejects when a real Writable is destroyed before its write callback', async () => {
+        const stream = new ManualWritable();
+        const write = writeToStream(stream, 'payload');
+        stream.destroy();
+        await expect(within(write)).rejects.toThrow('closed before the write completed');
+        expect(stream.listenerCount('close')).toBe(0);
+        expect(stream.listenerCount('drain')).toBe(0);
+        expect(stream.listenerCount('error')).toBe(0);
+    });
+    it('rejects when close occurs after callback but before required drain', async () => {
+        const stream = new SyntheticBackpressureWritable();
+        const write = writeToStream(stream, 'payload');
+        stream.callback?.();
+        stream.destroy();
+        await expect(within(write)).rejects.toThrow('closed before the write completed');
+        expect(stream.listenerCount('close')).toBe(0);
+        expect(stream.listenerCount('drain')).toBe(0);
+        expect(stream.listenerCount('error')).toBe(0);
+    });
+    it('rejects an already-destroyed Writable without attempting a write', async () => {
+        const stream = new ManualWritable();
+        stream.destroy();
+        await new Promise(resolve => stream.once('close', resolve));
+        await expect(within(writeToStream(stream, 'payload'))).rejects.toThrow('closed before the write completed');
+        expect(stream.chunks).toHaveLength(0);
+        expect(stream.listenerCount('close')).toBe(0);
+        expect(stream.listenerCount('drain')).toBe(0);
+        expect(stream.listenerCount('error')).toBe(0);
+    });
+    it('ignores a late callback after close has already rejected the write', async () => {
+        const stream = new ManualWritable();
+        const write = writeToStream(stream, 'payload');
+        stream.destroy();
+        await expect(within(write)).rejects.toThrow('closed before the write completed');
+        expect(() => {
+            stream.emit('drain');
+            stream.release(new Error('late callback failure'));
+        }).not.toThrow();
+        await new Promise(resolve => setImmediate(resolve));
+        expect(stream.listenerCount('close')).toBe(0);
+        expect(stream.listenerCount('drain')).toBe(0);
+        expect(stream.listenerCount('error')).toBe(0);
+    });
+    it('settles once with the original error when error and close race', async () => {
+        const stream = new ManualWritable();
+        const write = writeToStream(stream, 'payload');
+        stream.destroy(new Error('destroy race failed'));
+        await expect(within(write)).rejects.toThrow('destroy race failed');
+        await new Promise(resolve => setImmediate(resolve));
+        expect(stream.listenerCount('close')).toBe(0);
+        expect(stream.listenerCount('drain')).toBe(0);
+        expect(stream.listenerCount('error')).toBe(0);
+    });
+    it('does not let close after success change the resolved result', async () => {
+        const stream = new SyntheticBackpressureWritable();
+        const end = vi.spyOn(stream, 'end');
+        const destroy = vi.spyOn(stream, 'destroy');
+        const write = writeToStream(stream, 'payload');
+        stream.emit('drain');
+        stream.callback?.();
+        await expect(within(write)).resolves.toBeUndefined();
+        expect(end).not.toHaveBeenCalled();
+        expect(destroy).not.toHaveBeenCalled();
+        stream.destroy();
+        await new Promise(resolve => setImmediate(resolve));
+        expect(stream.listenerCount('close')).toBe(0);
+        expect(stream.listenerCount('drain')).toBe(0);
+        expect(stream.listenerCount('error')).toBe(0);
+    });
+});

package/dist/src/types.d.ts

@@ -87,6 +87,9 @@ export interface IPage {
     }): Promise<{
         matches_n: number;
         match_level: 'exact' | 'stable' | 'reidentified';
+        click_method?: 'cdp' | 'js' | 'ax';
+        hit?: 'target' | 'ancestor' | 'other' | 'none';
+        retargeted?: boolean;
     }>;
     dblClick?(ref: string, opts?: {
         nth?: number;
@@ -178,6 +181,8 @@ export interface IPage {
     }): Promise<any>;
     getFormState(): Promise<any>;
     wait(options: number | WaitOptions): Promise<void>;
+    /** Pure client-side sleep (bare setTimeout, no page evaluation). */
+    sleep(seconds: number): Promise<void>;
     waitForDownload?(pattern?: string, timeoutMs?: number): Promise<BrowserDownloadWaitResult>;
     tabs(): Promise<any>;
     closeTab?(target?: number | string): Promise<void>;

package/dist/src/utils.d.ts

@@ -54,4 +54,4 @@ export declare function parseJsonOrThrowLoginWall(response: Response, opts?: {
  *     return res;
  *
  * The Node side then calls `throwIfLoginWall(res, { url })` on the result. */
-export declare const BROWSER_JSON_SNIFF_FN = "\nasync function fetchJsonOrLoginWall(input, init) {\n  const r = await fetch(input, init);\n  const contentType = r.headers.get('content-type') || '';\n  const text = await r.text();\n  const trimmed = text.replace(/^\\s+/, '');\n  const looksLikeHtml =\n    contentType.toLowerCase().includes('text/html')\n    || trimmed.startsWith('<!DOCTYPE')\n    || trimmed.startsWith('<!doctype')\n    || trimmed.startsWith('<html')\n    || trimmed.startsWith('<HTML');\n  if (looksLikeHtml) {\n    return {\n      __loginWall: true,\n      status: r.status,\n      url: r.url || (typeof input === 'string' ? input : ''),\n      contentType,\n      bodyPreview: trimmed.slice(0, 100),\n    };\n  }\n  if (!r.ok) {\n    return { error: r.status };\n  }\n  try {\n    return JSON.parse(text);\n  } catch (err) {\n    throw new Error(\n      'JSON parse failed (status=' + r.status + ', body[0..50]=' + JSON.stringify(trimmed.slice(0, 50)) + '): '\n      + (err && err.message ? err.message : String(err))\n    );\n  }\n}\n";
+export declare const BROWSER_JSON_SNIFF_FN = "\nasync function fetchJsonOrLoginWall(input, init) {\n  const r = await fetch(input, init);\n  const contentType = r.headers.get('content-type') || '';\n  const text = await r.text();\n  const trimmed = text.replace(/^\\s+/, '');\n  const looksLikeHtml =\n    contentType.toLowerCase().includes('text/html')\n    || /^<(?:!doctype|html|head|body|title)(?:[\\s>/]|$)/i.test(trimmed);\n  if (looksLikeHtml) {\n    return {\n      __loginWall: true,\n      status: r.status,\n      url: r.url || (typeof input === 'string' ? input : ''),\n      contentType,\n      bodyPreview: trimmed.slice(0, 100),\n    };\n  }\n  if (!r.ok) {\n    return { error: r.status };\n  }\n  try {\n    return JSON.parse(text);\n  } catch (err) {\n    throw new Error(\n      'JSON parse failed (status=' + r.status + ', body[0..50]=' + JSON.stringify(trimmed.slice(0, 50)) + '): '\n      + (err && err.message ? err.message : String(err))\n    );\n  }\n}\n";

package/dist/src/utils.js

@@ -85,10 +85,7 @@ export async function parseJsonOrThrowLoginWall(response, opts = {}) {
     const text = await response.text();
     const trimmed = text.trimStart();
     const looksLikeHtml = contentType.toLowerCase().includes('text/html')
-        || trimmed.startsWith('<!DOCTYPE')
-        || trimmed.startsWith('<!doctype')
-        || trimmed.startsWith('<html')
-        || trimmed.startsWith('<HTML');
+        || /^<(?:!doctype|html|head|body|title)(?:[\s>/]|$)/i.test(trimmed);
     if (looksLikeHtml) {
         throw new LoginWallError(`Server returned HTML instead of JSON (status=${response.status}). `
             + `Likely a login wall, rate limit, or WAF challenge.`, response.status, opts.url || response.url || '', trimmed.slice(0, 100));
@@ -124,10 +121,7 @@ async function fetchJsonOrLoginWall(input, init) {
   const trimmed = text.replace(/^\\s+/, '');
   const looksLikeHtml =
     contentType.toLowerCase().includes('text/html')
-    || trimmed.startsWith('<!DOCTYPE')
-    || trimmed.startsWith('<!doctype')
-    || trimmed.startsWith('<html')
-    || trimmed.startsWith('<HTML');
+    || /^<(?:!doctype|html|head|body|title)(?:[\\s>/]|$)/i.test(trimmed);
   if (looksLikeHtml) {
     return {
       __loginWall: true,

package/dist/src/utils.test.js

@@ -51,6 +51,29 @@ describe('parseJsonOrThrowLoginWall', () => {
         });
         await expect(parseJsonOrThrowLoginWall(res)).rejects.toBeInstanceOf(LoginWallError);
     });
+    it('detects mixed-case HTML tags when content-type claims JSON', async () => {
+        const res = new Response('<HtMl lang="en"><body>nope</body></HtMl>', {
+            status: 403,
+            headers: { 'content-type': 'application/json' },
+        });
+        await expect(parseJsonOrThrowLoginWall(res)).rejects.toBeInstanceOf(LoginWallError);
+    });
+    it('detects mixed-case HTML fragments without a top-level html tag', async () => {
+        for (const html of ['<BoDy>blocked</BoDy>', '<TiTlE>login</TiTlE>']) {
+            const res = new Response(html, {
+                status: 403,
+                headers: { 'content-type': 'application/json' },
+            });
+            await expect(parseJsonOrThrowLoginWall(res)).rejects.toBeInstanceOf(LoginWallError);
+        }
+    });
+    it('does not treat arbitrary angle-prefixed non-HTML text as a login wall', async () => {
+        const res = new Response('<htmlish', {
+            status: 200,
+            headers: { 'content-type': 'application/json' },
+        });
+        await expect(parseJsonOrThrowLoginWall(res)).rejects.not.toBeInstanceOf(LoginWallError);
+    });
     it('throws LoginWallError when body has leading whitespace before <!DOCTYPE', async () => {
         const res = new Response('   \n\n<!DOCTYPE html><html></html>', {
             status: 200,
@@ -152,4 +175,31 @@ describe('BROWSER_JSON_SNIFF_FN', () => {
         // we CAN confirm the fragment parses cleanly when embedded inside an async IIFE.
         expect(() => new Function(`(async () => { ${BROWSER_JSON_SNIFF_FN} })`)).not.toThrow();
     });
+    it('detects mixed-case HTML tags in browser-side responses', async () => {
+        const fetchJsonOrLoginWall = new Function('fetch', `${BROWSER_JSON_SNIFF_FN}; return fetchJsonOrLoginWall;`)(async () => new Response('<HtMl><body>login</body></HtMl>', {
+            status: 403,
+            headers: { 'content-type': 'application/json' },
+        }));
+        await expect(fetchJsonOrLoginWall('/api')).resolves.toMatchObject({
+            __loginWall: true,
+            status: 403,
+        });
+    });
+    it('detects mixed-case HTML fragments in browser-side responses', async () => {
+        const fetchJsonOrLoginWall = new Function('fetch', `${BROWSER_JSON_SNIFF_FN}; return fetchJsonOrLoginWall;`)(async () => new Response('<BoDy>login</BoDy>', {
+            status: 403,
+            headers: { 'content-type': 'application/json' },
+        }));
+        await expect(fetchJsonOrLoginWall('/api')).resolves.toMatchObject({
+            __loginWall: true,
+            status: 403,
+        });
+    });
+    it('does not flag browser-side non-HTML angle-prefixed text', async () => {
+        const fetchJsonOrLoginWall = new Function('fetch', `${BROWSER_JSON_SNIFF_FN}; return fetchJsonOrLoginWall;`)(async () => new Response('<htmlish', {
+            status: 200,
+            headers: { 'content-type': 'application/json' },
+        }));
+        await expect(fetchJsonOrLoginWall('/api')).rejects.toThrow('JSON parse failed');
+    });
 });