@agentrhq/webcmd 0.2.5 → 0.3.1

package/dist/src/browser/target-resolver.test.js

@@ -1,5 +1,145 @@
 import { describe, expect, it } from 'vitest';
-import { resolveTargetJs } from './target-resolver.js';
+import { boundingRectResolvedJs, resolveTargetJs } from './target-resolver.js';
+/**
+ * Build a fake element usable by the generated boundingRectResolvedJs. Rects are
+ * {left,top,width,height}; getBoundingClientRect derives right/bottom.
+ */
+function makeEl(opts) {
+    const attrs = opts.attrs ?? {};
+    const el = {
+        nodeType: 1,
+        tagName: opts.tag.toUpperCase(),
+        _cursor: opts.cursor ?? 'auto',
+        onclick: opts.onclick ? () => { } : null,
+        parentElement: null,
+        children: [],
+        scrollIntoView() { },
+        getBoundingClientRect() {
+            const r = opts.rect;
+            return { left: r.left, top: r.top, width: r.width, height: r.height, right: r.left + r.width, bottom: r.top + r.height };
+        },
+        getAttribute(k) { return k === 'role' ? (opts.role ?? null) : (attrs[k] ?? null); },
+        hasAttribute(k) { return k === 'role' ? opts.role != null : k in attrs; },
+        contains(other) {
+            if (other === el)
+                return true;
+            for (const c of el.children) {
+                if (c === other || (c.contains && c.contains(other)))
+                    return true;
+            }
+            return false;
+        },
+    };
+    return el;
+}
+/** Resolve computed cursor with CSS inheritance, so the fake DOM matches the
+ * browser: a child with no own cursor inherits its ancestors' pointer cursor. */
+function inheritedCursor(node) {
+    let n = node;
+    while (n) {
+        if (n._cursor && n._cursor !== 'auto')
+            return n._cursor;
+        n = n.parentElement;
+    }
+    return 'auto';
+}
+/** Run the generated boundingRectResolvedJs against a fake DOM. */
+function runRect(resolved, elementAt) {
+    const fakeWindow = { __resolved: resolved, getComputedStyle: (n) => ({ cursor: inheritedCursor(n) }) };
+    const fakeDoc = { elementFromPoint: (x, y) => elementAt(x, y) };
+    const js = boundingRectResolvedJs({ skipScroll: true, forClick: true });
+    // js is an IIFE expression `(() => {...})()`; arrow captures window/document
+    // params. Wrap in parens so ASI doesn't turn `return\n(` into `return;`.
+    return new Function('window', 'document', 'return (' + js + ')')(fakeWindow, fakeDoc);
+}
+describe('boundingRectResolvedJs runtime behavior', () => {
+    it('reports hit=target and no retarget when the centre lands on the element', () => {
+        const btn = makeEl({ tag: 'button', rect: { left: 0, top: 0, width: 100, height: 40 } });
+        const out = runRect(btn, () => btn);
+        expect(out.visible).toBe(true);
+        expect(out.hit).toBe('target');
+        expect(out.retargeted).toBe(false);
+        expect(out.x).toBe(50);
+        expect(out.y).toBe(20);
+    });
+    it('retargets an <svg> icon to its clickable <div> ancestor (#2071)', () => {
+        const div = makeEl({ tag: 'div', rect: { left: 0, top: 0, width: 80, height: 80 }, cursor: 'pointer' });
+        const svg = makeEl({ tag: 'svg', rect: { left: 20, top: 20, width: 40, height: 40 } });
+        svg.parentElement = div;
+        div.children = [svg];
+        // elementFromPoint at the div centre returns the svg (topmost paint), which
+        // is contained by div → hit=target on the retargeted element.
+        const out = runRect(svg, () => svg);
+        expect(out.retargeted).toBe(true);
+        expect(out.hit).toBe('target');
+        // measured rect is the div's (80x80 → centre 40,40), not the svg's
+        expect(out.w).toBe(80);
+        expect(out.x).toBe(40);
+        expect(out.y).toBe(40);
+    });
+    it('retargets to an ancestor that owns an onclick handler even without cursor:pointer (#2071)', () => {
+        const div = makeEl({ tag: 'div', rect: { left: 0, top: 0, width: 60, height: 60 }, onclick: true });
+        const svg = makeEl({ tag: 'svg', rect: { left: 10, top: 10, width: 40, height: 40 } });
+        svg.parentElement = div;
+        div.children = [svg];
+        const out = runRect(svg, () => svg);
+        expect(out.retargeted).toBe(true);
+        expect(out.w).toBe(60);
+    });
+    it('does not retarget when no ancestor is clickable', () => {
+        const wrap = makeEl({ tag: 'div', rect: { left: 0, top: 0, width: 60, height: 60 } });
+        const span = makeEl({ tag: 'span', rect: { left: 10, top: 10, width: 40, height: 40 } });
+        span.parentElement = wrap;
+        wrap.children = [span];
+        const out = runRect(span, () => span);
+        expect(out.retargeted).toBe(false);
+        expect(out.w).toBe(40);
+    });
+    it('treats an ancestor hit as trustworthy (open shadow-DOM host / own wrapper) and keeps the centre', () => {
+        // elementFromPoint returns a light-DOM ancestor (e.g. the shadow host) that
+        // contains the target — CDP pierces to the target, so this must NOT fall back.
+        const host = makeEl({ tag: 'div', rect: { left: 0, top: 0, width: 120, height: 60 } });
+        const btn = makeEl({ tag: 'button', rect: { left: 10, top: 10, width: 100, height: 40 } });
+        btn.parentElement = host;
+        host.children = [btn];
+        const out = runRect(btn, () => host); // topmost at every point is the host (ancestor)
+        expect(out.hit).toBe('ancestor');
+        expect(out.retargeted).toBe(false);
+        // centre kept — no wasted probing when the hit is already trustworthy
+        expect(out.x).toBe(60);
+        expect(out.y).toBe(30);
+    });
+    it('hover/dblClick mode (forClick omitted) returns the plain element centre with no hit-test', () => {
+        const div = makeEl({ tag: 'div', rect: { left: 0, top: 0, width: 80, height: 80 }, cursor: 'pointer' });
+        const svg = makeEl({ tag: 'svg', rect: { left: 20, top: 20, width: 40, height: 40 } });
+        svg.parentElement = div;
+        div.children = [svg];
+        const js = boundingRectResolvedJs({ skipScroll: true }); // no forClick
+        const out = new Function('window', 'document', 'return (' + js + ')')({ __resolved: svg, getComputedStyle: () => ({ cursor: 'pointer' }) }, { elementFromPoint: () => div });
+        // no retarget, no hit field — svg's own centre (40,40), unchanged behavior
+        expect(out.hit).toBeUndefined();
+        expect(out.retargeted).toBeUndefined();
+        expect(out.x).toBe(40);
+        expect(out.y).toBe(40);
+        expect(out.w).toBe(40);
+    });
+    it('reports hit=other when an overlay covers the element and no probe point lands (#2076)', () => {
+        const btn = makeEl({ tag: 'button', rect: { left: 0, top: 0, width: 100, height: 40 } });
+        const overlay = makeEl({ tag: 'div', rect: { left: 0, top: 0, width: 1000, height: 1000 } });
+        const out = runRect(btn, () => overlay); // every point hits the overlay
+        expect(out.hit).toBe('other');
+        expect(out.retargeted).toBe(false);
+    });
+    it('recovers a hitting point by probing when the centre is occluded but a corner is clear (#2076)', () => {
+        const btn = makeEl({ tag: 'button', rect: { left: 0, top: 0, width: 100, height: 40 } });
+        const overlay = makeEl({ tag: 'div', rect: { left: 40, top: 15, width: 20, height: 10 } });
+        // Centre (50,20) is covered by the overlay; the top-left inset (3,3) is clear.
+        const out = runRect(btn, (x, y) => (x === 50 && y === 20 ? overlay : btn));
+        expect(out.hit).toBe('target');
+        // the returned point moved off the occluded centre (50,20)
+        expect(out.x === 50 && out.y === 20).toBe(false);
+    });
+});
 /**
  * Tests for the target resolver JS generator.
  *

package/dist/src/build-manifest.d.ts

@@ -22,6 +22,7 @@
  *     amount) to confirm an intentional removal.
  */
 import type { ManifestEntry } from './manifest-types.js';
+import { type HostedBrowserCommandContract } from './hosted/contract.js';
 export type { ManifestEntry } from './manifest-types.js';
 /**
  * Thrown by `loadManifestEntries` when an adapter file looks like a CLI
@@ -66,6 +67,11 @@ export declare function loadManifestEntries(filePath: string, site: string, impo
 export declare function scanClisDir(clisDir: string, importer?: (moduleHref: string) => Promise<unknown>): Promise<BuildManifestResult>;
 export declare function buildManifest(): Promise<BuildManifestResult>;
 export declare function serializeManifest(manifest: ManifestEntry[]): string;
+export interface BuildManifestArtifacts {
+    manifestJson: string;
+    hostedContractJson: string;
+}
+export declare function buildManifestArtifacts(entries: ManifestEntry[], packageVersion: string, browserCatalog: readonly HostedBrowserCommandContract[]): BuildManifestArtifacts;
 /**
  * Metadata audit: every positional arg must carry a non-empty `help` string.
  *

package/dist/src/build-manifest.js

@@ -28,10 +28,12 @@ import { getErrorMessage } from './errors.js';
 import { fullName, getRegistry } from './registry.js';
 import { findPackageRoot, getCliManifestPath } from './package-paths.js';
 import { isRecord } from './utils.js';
+import { buildHostedContract, serializeHostedContract, } from './hosted/contract.js';
 const PACKAGE_ROOT = findPackageRoot(fileURLToPath(import.meta.url));
 const CLIS_DIR = path.join(PACKAGE_ROOT, 'clis');
 // Write manifest next to clis/ so both dev and installed runtime can find it.
 const OUTPUT = getCliManifestPath(CLIS_DIR);
+const HOSTED_CONTRACT_OUTPUT = path.join(PACKAGE_ROOT, 'hosted-contract.json');
 // Module is treated as a CLI command source if it either:
 //   1. Calls `cli(...)` directly (the common case), or
 //   2. Calls a factory `make<Pascal>Command(...)` from clis/_shared/ that
@@ -64,6 +66,7 @@ function toManifestArgs(args) {
         positional: arg.positional || undefined,
         help: arg.help ?? '',
         choices: arg.choices,
+        file: arg.file,
     }));
 }
 function toModulePath(filePath, site) {
@@ -211,6 +214,12 @@ export async function buildManifest() {
 export function serializeManifest(manifest) {
     return `${JSON.stringify(manifest, null, 2)}\n`;
 }
+export function buildManifestArtifacts(entries, packageVersion, browserCatalog) {
+    return {
+        manifestJson: serializeManifest(entries),
+        hostedContractJson: serializeHostedContract(buildHostedContract(entries, browserCatalog, packageVersion)),
+    };
+}
 export function findManifestMetadataIssues(entries) {
     const issues = [];
     for (const entry of entries) {
@@ -330,9 +339,17 @@ async function main() {
             process.exit(1);
         }
     }
+    const packagePath = path.resolve(PACKAGE_ROOT, 'package.json');
+    const packageMetadata = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+    if (typeof packageMetadata.name !== 'string' || typeof packageMetadata.version !== 'string') {
+        throw new Error(`Package name and version are required in ${packagePath}`);
+    }
+    const artifacts = buildManifestArtifacts(entries, packageMetadata.version, []);
     fs.mkdirSync(path.dirname(OUTPUT), { recursive: true });
-    fs.writeFileSync(OUTPUT, serializeManifest(entries));
+    fs.writeFileSync(OUTPUT, artifacts.manifestJson);
+    fs.writeFileSync(HOSTED_CONTRACT_OUTPUT, artifacts.hostedContractJson);
     console.log(`✅ Manifest compiled: ${entries.length} entries → ${OUTPUT}`);
+    console.log(`✅ Hosted contract compiled: ${packageMetadata.name}@${packageMetadata.version} → ${HOSTED_CONTRACT_OUTPUT}`);
     // Restore executable permissions on bin entries.
     // tsc does not preserve the +x bit, so after a clean rebuild the CLI
     // entry-point loses its executable permission, causing "Permission denied".

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

@@ -3,7 +3,7 @@ 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';
+import { ManifestImportError, buildManifestArtifacts, diffRemovedEntries, findManifestMetadataIssues, loadManifestEntries, normalizeManifestPath, parseBuildManifestArgs, scanClisDir, serializeManifest, } from './build-manifest.js';
 describe('manifest helper rules', () => {
     const tempDirs = [];
     afterEach(() => {
@@ -81,6 +81,62 @@ describe('manifest helper rules', () => {
         expect(entries[0].sourceFile).not.toContain('\\');
         getRegistry().delete(key);
     });
+    it('preserves file metadata and builds both artifacts from one normalized snapshot', async () => {
+        const site = `manifest-files-${Date.now()}`;
+        const key = `${site}/upload`;
+        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: 'upload', access: 'write' });`);
+        const entries = await loadManifestEntries(file, site, async () => ({
+            command: cli({
+                site,
+                name: 'upload',
+                access: 'write',
+                description: 'upload a document',
+                strategy: Strategy.PUBLIC,
+                browser: false,
+                args: [{
+                        name: 'path',
+                        type: 'str',
+                        positional: true,
+                        required: true,
+                        help: 'Document path',
+                        file: {
+                            direction: 'input',
+                            pathKind: 'file',
+                            contentTypes: ['application/pdf'],
+                            maxBytes: 5_000_000,
+                        },
+                    }],
+            }),
+        }));
+        expect(entries[0].args[0].file).toEqual({
+            direction: 'input',
+            pathKind: 'file',
+            contentTypes: ['application/pdf'],
+            maxBytes: 5_000_000,
+        });
+        const artifacts = buildManifestArtifacts(entries, '7.6.5', []);
+        expect(JSON.parse(artifacts.manifestJson)).toEqual(entries);
+        expect(JSON.parse(artifacts.hostedContractJson)).toMatchObject({
+            schemaVersion: 1,
+            webcmdVersion: '7.6.5',
+            commands: [{
+                    command: `${site}/upload`,
+                    fileArguments: [{
+                            name: 'path',
+                            direction: 'input',
+                            pathKind: 'file',
+                            multiple: false,
+                            required: true,
+                            contentTypes: ['application/pdf'],
+                            maxBytes: 5_000_000,
+                        }],
+                }],
+        });
+        getRegistry().delete(key);
+    });
     it('serializes freshPage for persistent browser commands', async () => {
         const site = `manifest-fresh-page-${Date.now()}`;
         const key = `${site}/checkout`;

package/dist/src/builtin-command-surface.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from 'commander';
+export declare const LIST_COMMAND_DESCRIPTION = "List all available CLI commands";
+export declare const LIST_FORMAT_DESCRIPTION = "Output format: table, json, yaml, md, csv";
+export declare const COMPLETION_COMMAND_DESCRIPTION = "Output shell completion script";
+export declare const COMPLETION_SHELL_DESCRIPTION = "Shell type: bash, zsh, or fish";
+/** Configure built-in grammar shared by the local and hosted runtimes. */
+export declare function configureListCommandSurface(command: Command): Command;
+/** Configure completion grammar shared by the local and hosted runtimes. */
+export declare function configureCompletionCommandSurface(command: Command): Command;

package/dist/src/builtin-command-surface.js

@@ -0,0 +1,16 @@
+export const LIST_COMMAND_DESCRIPTION = 'List all available CLI commands';
+export const LIST_FORMAT_DESCRIPTION = 'Output format: table, json, yaml, md, csv';
+export const COMPLETION_COMMAND_DESCRIPTION = 'Output shell completion script';
+export const COMPLETION_SHELL_DESCRIPTION = 'Shell type: bash, zsh, or fish';
+/** Configure built-in grammar shared by the local and hosted runtimes. */
+export function configureListCommandSurface(command) {
+    return command
+        .description(LIST_COMMAND_DESCRIPTION)
+        .option('-f, --format <fmt>', LIST_FORMAT_DESCRIPTION, 'table');
+}
+/** Configure completion grammar shared by the local and hosted runtimes. */
+export function configureCompletionCommandSurface(command) {
+    return command
+        .description(COMPLETION_COMMAND_DESCRIPTION)
+        .argument('<shell>', COMPLETION_SHELL_DESCRIPTION);
+}

package/dist/src/check-hosted-contract.test.d.ts

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

package/dist/src/check-hosted-contract.test.js

@@ -0,0 +1,56 @@
+import { createHash } from 'node:crypto';
+import { copyFileSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { afterEach, describe, expect, it } from 'vitest';
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const checkerPath = path.join(packageRoot, 'scripts/check-hosted-contract.mjs');
+const committedArtifactNames = ['cli-manifest.json'];
+const fixtureRoots = [];
+afterEach(() => {
+    for (const fixtureRoot of fixtureRoots.splice(0)) {
+        rmSync(fixtureRoot, { recursive: true, force: true });
+    }
+});
+function createCommittedArtifactFixture() {
+    const fixtureRoot = mkdtempSync(path.join(tmpdir(), 'webcmd-contract-committed-'));
+    fixtureRoots.push(fixtureRoot);
+    for (const artifactName of committedArtifactNames) {
+        copyFileSync(path.join(packageRoot, artifactName), path.join(fixtureRoot, artifactName));
+    }
+    return fixtureRoot;
+}
+function rootArtifactHashes() {
+    return Object.fromEntries(committedArtifactNames.map((artifactName) => [
+        artifactName,
+        createHash('sha256').update(readFileSync(path.join(packageRoot, artifactName))).digest('hex'),
+    ]));
+}
+function runChecker(committedRoot) {
+    return spawnSync(process.execPath, [checkerPath], {
+        cwd: packageRoot,
+        encoding: 'utf8',
+        env: { ...process.env, WEBCMD_CONTRACT_COMMITTED_ROOT: committedRoot },
+    });
+}
+describe('hosted contract reproducibility checker', () => {
+    it('accepts a byte-identical committed manifest and generates the package contract', () => {
+        const result = runChecker(createCommittedArtifactFixture());
+        expect(result.status).toBe(0);
+        expect(result.stdout).toContain('hosted-contract.json generated successfully.');
+    }, 10_000);
+    it('rejects one stale byte without mutating root artifacts', () => {
+        const before = rootArtifactHashes();
+        const fixtureRoot = createCommittedArtifactFixture();
+        const stalePath = path.join(fixtureRoot, 'cli-manifest.json');
+        const staleBytes = readFileSync(stalePath);
+        staleBytes[0] ^= 1;
+        writeFileSync(stalePath, staleBytes);
+        const result = runChecker(fixtureRoot);
+        expect(result.status).toBe(1);
+        expect(result.stderr).toContain('cli-manifest.json');
+        expect(rootArtifactHashes()).toEqual(before);
+    }, 10_000);
+});