@agentrhq/webcmd 0.1.1 → 0.2.0

package/dist/src/hooks.js

@@ -0,0 +1,58 @@
+/**
+ * Plugin lifecycle hooks: allows plugins to tap into webcmd's execution lifecycle.
+ *
+ * Hooks use globalThis (like the command registry) to guarantee a single shared
+ * instance across all module copies — critical when TS plugins are loaded via
+ * npm link / peerDependency symlinks.
+ *
+ * Available hooks:
+ *   onStartup        — fired once after all commands & plugins are discovered
+ *   onBeforeExecute  — fired before every command execution
+ *   onAfterExecute   — fired after every command execution (receives result)
+ */
+import { log } from './logger.js';
+const _hooks = globalThis.__webcmd_hooks__ ??= new Map();
+// ── Registration API (used by plugins) ─────────────────────────────────────
+function addHook(name, fn) {
+    const list = _hooks.get(name) ?? [];
+    if (list.includes(fn))
+        return;
+    list.push(fn);
+    _hooks.set(name, list);
+}
+/** Register a hook that fires once after all plugins are discovered. */
+export function onStartup(fn) {
+    addHook('onStartup', fn);
+}
+/** Register a hook that fires before every command execution. */
+export function onBeforeExecute(fn) {
+    addHook('onBeforeExecute', fn);
+}
+/** Register a hook that fires after every command execution with the result. */
+export function onAfterExecute(fn) {
+    addHook('onAfterExecute', fn);
+}
+// ── Emit API (used internally by webcmd core) ─────────────────────────────
+/**
+ * Trigger all registered handlers for a hook.
+ * Each handler is wrapped in try/catch — a failing hook never blocks command execution.
+ */
+export async function emitHook(name, ctx, result) {
+    const handlers = _hooks.get(name);
+    if (!handlers || handlers.length === 0)
+        return;
+    for (const fn of handlers) {
+        try {
+            await fn(ctx, result);
+        }
+        catch (err) {
+            log.warn(`Hook ${name} handler failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+/**
+ * Remove all registered hooks. Intended for testing only.
+ */
+export function clearAllHooks() {
+    _hooks.clear();
+}

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

@@ -0,0 +1,4 @@
+/**
+ * Tests for the plugin lifecycle hooks system.
+ */
+export {};

package/dist/src/hooks.test.js

@@ -0,0 +1,92 @@
+/**
+ * Tests for the plugin lifecycle hooks system.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { onStartup, onBeforeExecute, onAfterExecute, emitHook, clearAllHooks, } from './hooks.js';
+beforeEach(() => {
+    clearAllHooks();
+});
+describe('hook registration and emission', () => {
+    it('onBeforeExecute hook is called with context', async () => {
+        const calls = [];
+        onBeforeExecute((ctx) => { calls.push({ ...ctx }); });
+        await emitHook('onBeforeExecute', { command: 'test/cmd', args: { limit: 5 }, startedAt: 100 });
+        expect(calls).toHaveLength(1);
+        expect(calls[0].command).toBe('test/cmd');
+        expect(calls[0].args).toEqual({ limit: 5 });
+        expect(calls[0].startedAt).toBe(100);
+    });
+    it('onAfterExecute hook receives result', async () => {
+        const results = [];
+        onAfterExecute((_ctx, result) => { results.push(result); });
+        const mockResult = [{ title: 'item1' }, { title: 'item2' }];
+        await emitHook('onAfterExecute', { command: 'test/cmd', args: {} }, mockResult);
+        expect(results).toHaveLength(1);
+        expect(results[0]).toEqual(mockResult);
+    });
+    it('onStartup hook fires', async () => {
+        let fired = false;
+        onStartup(() => { fired = true; });
+        await emitHook('onStartup', { command: '__startup__', args: {} });
+        expect(fired).toBe(true);
+    });
+    it('multiple hooks on the same event fire in order', async () => {
+        const order = [];
+        onBeforeExecute(() => { order.push(1); });
+        onBeforeExecute(() => { order.push(2); });
+        onBeforeExecute(() => { order.push(3); });
+        await emitHook('onBeforeExecute', { command: 'test/cmd', args: {} });
+        expect(order).toEqual([1, 2, 3]);
+    });
+    it('async hooks are awaited', async () => {
+        const order = [];
+        onBeforeExecute(async () => {
+            await new Promise((r) => setTimeout(r, 10));
+            order.push('async-done');
+        });
+        onBeforeExecute(() => { order.push('sync'); });
+        await emitHook('onBeforeExecute', { command: 'test/cmd', args: {} });
+        expect(order).toEqual(['async-done', 'sync']);
+    });
+});
+describe('hook error isolation', () => {
+    it('failing hook does not prevent other hooks from running', async () => {
+        const calls = [];
+        onBeforeExecute(() => { calls.push('first'); });
+        onBeforeExecute(() => { throw new Error('boom'); });
+        onBeforeExecute(() => { calls.push('third'); });
+        await emitHook('onBeforeExecute', { command: 'test/cmd', args: {} });
+        // First and third should still run despite the second throwing
+        expect(calls).toEqual(['first', 'third']);
+    });
+    it('async hook rejection does not prevent other hooks', async () => {
+        const calls = [];
+        onAfterExecute(() => { calls.push('before-reject'); });
+        onAfterExecute(async () => { throw new Error('async boom'); });
+        onAfterExecute(() => { calls.push('after-reject'); });
+        await emitHook('onAfterExecute', { command: 'test/cmd', args: {} }, null);
+        expect(calls).toEqual(['before-reject', 'after-reject']);
+    });
+});
+describe('no-op when no hooks registered', () => {
+    it('emitHook with no registered hooks does nothing', async () => {
+        // Should not throw
+        await emitHook('onBeforeExecute', { command: 'test/cmd', args: {} });
+        await emitHook('onAfterExecute', { command: 'test/cmd', args: {} }, []);
+        await emitHook('onStartup', { command: '__startup__', args: {} });
+    });
+});
+describe('clearAllHooks', () => {
+    it('removes all hooks', async () => {
+        let called = false;
+        onStartup(() => { called = true; });
+        clearAllHooks();
+        await emitHook('onStartup', { command: '__startup__', args: {} });
+        expect(called).toBe(false);
+    });
+});
+describe('globalThis singleton', () => {
+    it('uses globalThis.__webcmd_hooks__ for shared state', () => {
+        expect(globalThis.__webcmd_hooks__).toBeInstanceOf(Map);
+    });
+});

package/dist/src/interceptor.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared XHR/Fetch interceptor JavaScript generators.
+ *
+ * Provides a single source of truth for monkey-patching browser
+ * fetch() and XMLHttpRequest to capture API responses matching
+ * a URL pattern. Used by:
+ *   - Page.installInterceptor()  (browser.ts)
+ *   - stepIntercept              (pipeline/steps/intercept.ts)
+ *   - stepTap                    (pipeline/steps/tap.ts)
+ */
+/**
+ * Generate JavaScript source that installs a fetch/XHR interceptor.
+ * Captured responses are pushed to `window.__webcmd_intercepted`.
+ *
+ * @param patternExpr - JS expression resolving to a URL substring to match (e.g. a JSON.stringify'd string)
+ * @param opts.arrayName - Global array name for captured data (default: '__webcmd_intercepted')
+ * @param opts.patchGuard - Global boolean name to prevent double-patching (default: '__webcmd_interceptor_patched')
+ */
+export declare function generateInterceptorJs(patternExpr: string, opts?: {
+    arrayName?: string;
+    patchGuard?: string;
+}): string;
+/**
+ * Generate JavaScript source to read and clear intercepted data.
+ */
+export declare function generateReadInterceptedJs(arrayName?: string): string;
+/**
+ * Generate a self-contained tap interceptor for store-action bridge.
+ * Unlike the global interceptor, this one:
+ * - Installs temporarily, restores originals in finally block
+ * - Resolves a promise on first capture (for immediate await)
+ * - Returns captured data directly
+ *
+ * Reuses the shared DISGUISE_FN for consistent toString() disguising.
+ */
+export declare function generateTapInterceptorJs(patternExpr: string): {
+    setupVar: string;
+    capturedVar: string;
+    promiseVar: string;
+    resolveVar: string;
+    fetchPatch: string;
+    xhrPatch: string;
+    restorePatch: string;
+};

package/dist/src/interceptor.js

@@ -0,0 +1,183 @@
+/**
+ * Shared XHR/Fetch interceptor JavaScript generators.
+ *
+ * Provides a single source of truth for monkey-patching browser
+ * fetch() and XMLHttpRequest to capture API responses matching
+ * a URL pattern. Used by:
+ *   - Page.installInterceptor()  (browser.ts)
+ *   - stepIntercept              (pipeline/steps/intercept.ts)
+ *   - stepTap                    (pipeline/steps/tap.ts)
+ */
+/**
+ * Helper: define a non-enumerable property on window.
+ * Avoids detection via Object.keys(window) or for..in loops.
+ */
+const DEFINE_HIDDEN = `
+      function __defHidden(obj, key, val) {
+        try {
+          Object.defineProperty(obj, key, { value: val, writable: true, enumerable: false, configurable: true });
+        } catch { obj[key] = val; }
+      }`;
+/**
+ * Helper: disguise a patched function so toString() returns native code signature.
+ */
+const DISGUISE_FN = `
+      function __disguise(fn, name) {
+        const nativeStr = 'function ' + name + '() { [native code] }';
+        // Override toString on the instance AND patch Function.prototype.toString
+        // to handle Function.prototype.toString.call(fn) bypasses.
+        const _origToString = Function.prototype.toString;
+        const _patchedFns = window.__dFns || (function() {
+          const m = new Map();
+          Object.defineProperty(window, '__dFns', { value: m, enumerable: false, configurable: true });
+          // Patch Function.prototype.toString once to consult the map
+          Object.defineProperty(Function.prototype, 'toString', {
+            value: function() {
+              const override = m.get(this);
+              return override !== undefined ? override : _origToString.call(this);
+            },
+            writable: true, configurable: true
+          });
+          return m;
+        })();
+        _patchedFns.set(fn, nativeStr);
+        try { Object.defineProperty(fn, 'name', { value: name, configurable: true }); } catch {}
+        return fn;
+      }`;
+/**
+ * Generate JavaScript source that installs a fetch/XHR interceptor.
+ * Captured responses are pushed to `window.__webcmd_intercepted`.
+ *
+ * @param patternExpr - JS expression resolving to a URL substring to match (e.g. a JSON.stringify'd string)
+ * @param opts.arrayName - Global array name for captured data (default: '__webcmd_intercepted')
+ * @param opts.patchGuard - Global boolean name to prevent double-patching (default: '__webcmd_interceptor_patched')
+ */
+export function generateInterceptorJs(patternExpr, opts = {}) {
+    const arr = opts.arrayName ?? '__webcmd_intercepted';
+    const guard = opts.patchGuard ?? '__webcmd_interceptor_patched';
+    // Store the current pattern in a separate global so it can be updated
+    // without re-patching fetch/XHR (the patchGuard only prevents double-patching).
+    const patternVar = `${guard}_pattern`;
+    return `
+    () => {
+      ${DEFINE_HIDDEN}
+      ${DISGUISE_FN}
+
+      if (!window.${arr}) __defHidden(window, '${arr}', []);
+      if (!window.${arr}_errors) __defHidden(window, '${arr}_errors', []);
+      __defHidden(window, '${patternVar}', ${patternExpr});
+      const __checkMatch = (url) => window.${patternVar} && url.includes(window.${patternVar});
+
+      if (!window.${guard}) {
+        // ── Patch fetch ──
+        const __origFetch = window.fetch;
+        window.fetch = __disguise(async function(...args) {
+          const reqUrl = typeof args[0] === 'string' ? args[0]
+            : (args[0] && args[0].url) || '';
+          const response = await __origFetch.apply(this, args);
+          if (__checkMatch(reqUrl)) {
+            try {
+              const clone = response.clone();
+              const json = await clone.json();
+              window.${arr}.push(json);
+            } catch(e) { window.${arr}_errors.push({ url: reqUrl, error: String(e) }); }
+          }
+          return response;
+        }, 'fetch');
+
+        // ── Patch XMLHttpRequest ──
+        const __XHR = XMLHttpRequest.prototype;
+        const __origOpen = __XHR.open;
+        const __origSend = __XHR.send;
+        __XHR.open = __disguise(function(method, url) {
+          Object.defineProperty(this, '__iurl', { value: String(url), writable: true, enumerable: false, configurable: true });
+          return __origOpen.apply(this, arguments);
+        }, 'open');
+        __XHR.send = __disguise(function() {
+          if (__checkMatch(this.__iurl)) {
+            this.addEventListener('load', function() {
+              try {
+                window.${arr}.push(JSON.parse(this.responseText));
+              } catch(e) { window.${arr}_errors.push({ url: this.__iurl, error: String(e) }); }
+            });
+          }
+          return __origSend.apply(this, arguments);
+        }, 'send');
+
+        __defHidden(window, '${guard}', true);
+      }
+    }
+  `;
+}
+/**
+ * Generate JavaScript source to read and clear intercepted data.
+ */
+export function generateReadInterceptedJs(arrayName = '__webcmd_intercepted') {
+    return `
+    () => {
+      const data = window.${arrayName} || [];
+      window.${arrayName} = [];
+      return data;
+    }
+  `;
+}
+/**
+ * Generate a self-contained tap interceptor for store-action bridge.
+ * Unlike the global interceptor, this one:
+ * - Installs temporarily, restores originals in finally block
+ * - Resolves a promise on first capture (for immediate await)
+ * - Returns captured data directly
+ *
+ * Reuses the shared DISGUISE_FN for consistent toString() disguising.
+ */
+export function generateTapInterceptorJs(patternExpr) {
+    return {
+        setupVar: `
+      let captured = null;
+      let captureResolve;
+      const capturePromise = new Promise(r => { captureResolve = r; });
+      const capturePattern = ${patternExpr};
+      ${DISGUISE_FN}
+    `,
+        capturedVar: 'captured',
+        promiseVar: 'capturePromise',
+        resolveVar: 'captureResolve',
+        fetchPatch: `
+      const origFetch = window.fetch;
+      window.fetch = __disguise(async function(...fetchArgs) {
+        const resp = await origFetch.apply(this, fetchArgs);
+        try {
+          const url = typeof fetchArgs[0] === 'string' ? fetchArgs[0]
+            : fetchArgs[0] instanceof Request ? fetchArgs[0].url : String(fetchArgs[0]);
+          if (capturePattern && url.includes(capturePattern) && !captured) {
+            try { captured = await resp.clone().json(); captureResolve(); } catch {}
+          }
+        } catch {}
+        return resp;
+      }, 'fetch');
+    `,
+        xhrPatch: `
+      const origXhrOpen = XMLHttpRequest.prototype.open;
+      const origXhrSend = XMLHttpRequest.prototype.send;
+      XMLHttpRequest.prototype.open = __disguise(function(method, url) {
+        Object.defineProperty(this, '__iurl', { value: String(url), writable: true, enumerable: false, configurable: true });
+        return origXhrOpen.apply(this, arguments);
+      }, 'open');
+      XMLHttpRequest.prototype.send = __disguise(function(body) {
+        if (capturePattern && this.__iurl?.includes(capturePattern)) {
+          this.addEventListener('load', function() {
+            if (!captured) {
+              try { captured = JSON.parse(this.responseText); captureResolve(); } catch {}
+            }
+          });
+        }
+        return origXhrSend.apply(this, arguments);
+      }, 'send');
+    `,
+        restorePatch: `
+      window.fetch = origFetch;
+      XMLHttpRequest.prototype.open = origXhrOpen;
+      XMLHttpRequest.prototype.send = origXhrSend;
+    `,
+    };
+}

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

@@ -0,0 +1,4 @@
+/**
+ * Tests for interceptor.ts: JavaScript code generators for XHR/Fetch interception.
+ */
+export {};

package/dist/src/interceptor.test.js

@@ -0,0 +1,81 @@
+/**
+ * Tests for interceptor.ts: JavaScript code generators for XHR/Fetch interception.
+ */
+import { describe, it, expect } from 'vitest';
+import { generateInterceptorJs, generateReadInterceptedJs, generateTapInterceptorJs } from './interceptor.js';
+describe('generateInterceptorJs', () => {
+    it('generates valid JavaScript function source', () => {
+        const js = generateInterceptorJs('"api/search"');
+        expect(js).toContain('window.fetch');
+        expect(js).toContain('XMLHttpRequest');
+        expect(js).toContain('"api/search"');
+        // Should be a function expression wrapping
+        expect(js.trim()).toMatch(/^\(\)\s*=>/);
+    });
+    it('uses default array name and patch guard', () => {
+        const js = generateInterceptorJs('"test"');
+        expect(js).toContain('__webcmd_intercepted');
+        expect(js).toContain('__webcmd_interceptor_patched');
+    });
+    it('uses custom array name and patch guard', () => {
+        const js = generateInterceptorJs('"test"', {
+            arrayName: '__my_data',
+            patchGuard: '__my_guard',
+        });
+        expect(js).toContain('__my_data');
+        expect(js).toContain('__my_guard');
+        expect(js).not.toContain('__webcmd_intercepted');
+    });
+    it('includes fetch clone and json parsing', () => {
+        const js = generateInterceptorJs('"api"');
+        expect(js).toContain('response.clone()');
+        expect(js).toContain('clone.json()');
+    });
+    it('includes XHR open and send patching', () => {
+        const js = generateInterceptorJs('"api"');
+        expect(js).toContain('XMLHttpRequest.prototype');
+        expect(js).toContain('__origOpen');
+        expect(js).toContain('__origSend');
+    });
+});
+describe('generateReadInterceptedJs', () => {
+    it('generates valid JavaScript to read and clear data', () => {
+        const js = generateReadInterceptedJs();
+        expect(js).toContain('__webcmd_intercepted');
+        // Should clear the array after reading
+        expect(js).toContain('= []');
+    });
+    it('uses custom array name', () => {
+        const js = generateReadInterceptedJs('__custom_arr');
+        expect(js).toContain('__custom_arr');
+        expect(js).not.toContain('__webcmd_intercepted');
+    });
+});
+describe('generateTapInterceptorJs', () => {
+    it('returns all required fields', () => {
+        const tap = generateTapInterceptorJs('"api/data"');
+        expect(tap.setupVar).toBeDefined();
+        expect(tap.capturedVar).toBe('captured');
+        expect(tap.promiseVar).toBe('capturePromise');
+        expect(tap.resolveVar).toBe('captureResolve');
+        expect(tap.fetchPatch).toBeDefined();
+        expect(tap.xhrPatch).toBeDefined();
+        expect(tap.restorePatch).toBeDefined();
+    });
+    it('contains the capture pattern in setup', () => {
+        const tap = generateTapInterceptorJs('"my-pattern"');
+        expect(tap.setupVar).toContain('"my-pattern"');
+    });
+    it('restores original fetch and XHR in restorePatch', () => {
+        const tap = generateTapInterceptorJs('"test"');
+        expect(tap.restorePatch).toContain('origFetch');
+        expect(tap.restorePatch).toContain('origXhrOpen');
+        expect(tap.restorePatch).toContain('origXhrSend');
+    });
+    it('uses first-match capture (only first response)', () => {
+        const tap = generateTapInterceptorJs('"test"');
+        // Both fetch and xhr patches should check !captured before storing
+        expect(tap.fetchPatch).toContain('!captured');
+        expect(tap.xhrPatch).toContain('!captured');
+    });
+});

package/dist/src/launcher.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Electron app launcher — auto-detect, confirm, launch, and connect.
+ *
+ * Flow:
+ * 1. Probe CDP port → already running with debug? connect directly
+ * 2. Detect process → running without CDP? prompt to restart
+ * 3. Discover app path → not installed? error
+ * 4. Launch with --remote-debugging-port
+ * 5. Poll /json until ready
+ */
+import type { ElectronAppEntry } from './electron-apps.js';
+/**
+ * Probe whether a CDP endpoint is listening on the given port.
+ * Returns true if http://127.0.0.1:{port}/json responds successfully.
+ */
+export declare function probeCDP(port: number, timeoutMs?: number): Promise<boolean>;
+/**
+ * Check if a process with the given name is running.
+ * Uses pgrep on macOS/Linux.
+ */
+export declare function detectProcess(processName: string): boolean;
+/**
+ * Kill a process by name. Sends SIGTERM first, then SIGKILL after grace period.
+ */
+export declare function killProcess(processName: string): Promise<void>;
+/**
+ * Discover the app installation path on macOS.
+ * Uses osascript to resolve the app name to a POSIX path.
+ * Returns null if the app is not installed.
+ */
+export declare function discoverAppPath(displayName: string): string | null;
+export declare function resolveExecutableCandidates(appPath: string, app: ElectronAppEntry): string[];
+export declare function launchDetachedApp(executable: string, args: string[], label: string): Promise<void>;
+export declare function launchElectronApp(appPath: string, app: ElectronAppEntry, args: string[], label: string): Promise<void>;
+export declare function electronLaunchArgs(port: number, extraArgs?: string[]): string[];
+/**
+ * Main entry point: resolve an Electron app to a CDP endpoint URL.
+ *
+ * Returns the endpoint URL: http://127.0.0.1:{port}
+ */
+export declare function resolveElectronEndpoint(site: string): Promise<string>;