@jackwener/opencli 1.1.1 → 1.2.0

package/dist/browser/dom-snapshot.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Tests for dom-snapshot.ts: DOM snapshot engine.
+ *
+ * Since the engine generates JavaScript strings for in-page evaluation,
+ * these tests validate:
+ * 1. The generated code is syntactically valid JS
+ * 2. Options are correctly embedded
+ * 3. The output structure matches expected format
+ * 4. All features are present (Shadow DOM, iframe, table, diff, etc.)
+ */
+export {};

package/dist/browser/dom-snapshot.test.js

@@ -0,0 +1,212 @@
+/**
+ * Tests for dom-snapshot.ts: DOM snapshot engine.
+ *
+ * Since the engine generates JavaScript strings for in-page evaluation,
+ * these tests validate:
+ * 1. The generated code is syntactically valid JS
+ * 2. Options are correctly embedded
+ * 3. The output structure matches expected format
+ * 4. All features are present (Shadow DOM, iframe, table, diff, etc.)
+ */
+import { describe, it, expect } from 'vitest';
+import { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
+describe('generateSnapshotJs', () => {
+    it('returns a non-empty string', () => {
+        const js = generateSnapshotJs();
+        expect(typeof js).toBe('string');
+        expect(js.length).toBeGreaterThan(100);
+    });
+    it('generates syntactically valid JS (can be parsed)', () => {
+        const js = generateSnapshotJs();
+        expect(() => new Function(js)).not.toThrow();
+    });
+    it('embeds default options correctly', () => {
+        const js = generateSnapshotJs();
+        expect(js).toContain('VIEWPORT_EXPAND = 800');
+        expect(js).toContain('MAX_DEPTH = 50');
+        expect(js).toContain('INTERACTIVE_ONLY = false');
+        expect(js).toContain('MAX_TEXT_LEN = 120');
+        expect(js).toContain('INCLUDE_SCROLL_INFO = true');
+        expect(js).toContain('BBOX_DEDUP = true');
+        expect(js).toContain('INCLUDE_SHADOW_DOM = true');
+        expect(js).toContain('INCLUDE_IFRAMES = true');
+        expect(js).toContain('PAINT_ORDER_CHECK = true');
+        expect(js).toContain('ANNOTATE_REFS = true');
+        expect(js).toContain('REPORT_HIDDEN = true');
+        expect(js).toContain('FILTER_ADS = true');
+        expect(js).toContain('MARKDOWN_TABLES = true');
+        expect(js).toContain('PREV_HASHES = null');
+    });
+    it('embeds custom options correctly', () => {
+        const js = generateSnapshotJs({
+            viewportExpand: 2000,
+            maxDepth: 30,
+            interactiveOnly: true,
+            maxTextLength: 200,
+            includeScrollInfo: false,
+            bboxDedup: false,
+            includeShadowDom: false,
+            includeIframes: false,
+            maxIframes: 3,
+            paintOrderCheck: false,
+            annotateRefs: false,
+            reportHidden: false,
+            filterAds: false,
+            markdownTables: false,
+        });
+        expect(js).toContain('VIEWPORT_EXPAND = 2000');
+        expect(js).toContain('MAX_DEPTH = 30');
+        expect(js).toContain('INTERACTIVE_ONLY = true');
+        expect(js).toContain('MAX_TEXT_LEN = 200');
+        expect(js).toContain('INCLUDE_SCROLL_INFO = false');
+        expect(js).toContain('BBOX_DEDUP = false');
+        expect(js).toContain('INCLUDE_SHADOW_DOM = false');
+        expect(js).toContain('INCLUDE_IFRAMES = false');
+        expect(js).toContain('MAX_IFRAMES = 3');
+        expect(js).toContain('PAINT_ORDER_CHECK = false');
+        expect(js).toContain('ANNOTATE_REFS = false');
+        expect(js).toContain('REPORT_HIDDEN = false');
+        expect(js).toContain('FILTER_ADS = false');
+        expect(js).toContain('MARKDOWN_TABLES = false');
+    });
+    it('clamps maxDepth between 1 and 200', () => {
+        expect(generateSnapshotJs({ maxDepth: -5 })).toContain('MAX_DEPTH = 1');
+        expect(generateSnapshotJs({ maxDepth: 999 })).toContain('MAX_DEPTH = 200');
+        expect(generateSnapshotJs({ maxDepth: 75 })).toContain('MAX_DEPTH = 75');
+    });
+    it('wraps output as an IIFE', () => {
+        const js = generateSnapshotJs();
+        expect(js.startsWith('(() =>')).toBe(true);
+        expect(js.trimEnd().endsWith(')()')).toBe(true);
+    });
+    it('embeds previousHashes for incremental diff', () => {
+        const hashes = JSON.stringify(['12345', '67890']);
+        const js = generateSnapshotJs({ previousHashes: hashes });
+        expect(js).toContain('new Set(["12345","67890"])');
+    });
+    it('includes all core features in generated code', () => {
+        const js = generateSnapshotJs();
+        // Tag filtering
+        expect(js).toContain('SKIP_TAGS');
+        expect(js).toContain("'script'");
+        expect(js).toContain("'style'");
+        // SVG collapsing
+        expect(js).toContain('SVG_CHILDREN');
+        // Interactive detection
+        expect(js).toContain('INTERACTIVE_TAGS');
+        expect(js).toContain('INTERACTIVE_ROLES');
+        expect(js).toContain('isInteractive');
+        // Visibility
+        expect(js).toContain('isVisibleByCSS');
+        expect(js).toContain('isInExpandedViewport');
+        // BBox dedup
+        expect(js).toContain('isContainedBy');
+        expect(js).toContain('PROPAGATING_TAGS');
+        // Shadow DOM
+        expect(js).toContain('shadowRoot');
+        expect(js).toContain('|shadow|');
+        // iframe
+        expect(js).toContain('walkIframe');
+        expect(js).toContain('|iframe|');
+        // Paint order
+        expect(js).toContain('isOccludedByOverlay');
+        expect(js).toContain('elementFromPoint');
+        // Ad filtering
+        expect(js).toContain('isAdElement');
+        expect(js).toContain('AD_PATTERNS');
+        // data-ref annotation
+        expect(js).toContain('data-opencli-ref');
+        // Hidden elements report
+        expect(js).toContain('hiddenInteractives');
+        expect(js).toContain('hidden_interactive');
+        // Incremental diff
+        expect(js).toContain('hashElement');
+        expect(js).toContain('currentHashes');
+        expect(js).toContain('__opencli_prev_hashes');
+        // Table serialization
+        expect(js).toContain('serializeTable');
+        expect(js).toContain('|table|');
+        // Synthetic attributes
+        expect(js).toContain("'YYYY-MM-DD'");
+        expect(js).toContain('value=••••');
+        // Page metadata
+        expect(js).toContain('location.href');
+        expect(js).toContain('document.title');
+    });
+    it('contains proper attribute whitelist', () => {
+        const js = generateSnapshotJs();
+        const expectedAttrs = [
+            'aria-label', 'aria-expanded', 'aria-checked', 'aria-selected',
+            'placeholder', 'href', 'role', 'data-testid', 'autocomplete',
+        ];
+        for (const attr of expectedAttrs) {
+            expect(js).toContain(`'${attr}'`);
+        }
+    });
+    it('includes scroll info formatting', () => {
+        const js = generateSnapshotJs();
+        expect(js).toContain('scrollHeight');
+        expect(js).toContain('scrollTop');
+        expect(js).toContain('|scroll|');
+        expect(js).toContain('page_scroll');
+    });
+});
+describe('scrollToRefJs', () => {
+    it('generates valid JS', () => {
+        const js = scrollToRefJs('42');
+        expect(() => new Function(js)).not.toThrow();
+    });
+    it('targets data-opencli-ref', () => {
+        const js = scrollToRefJs('7');
+        expect(js).toContain('data-opencli-ref');
+        expect(js).toContain('scrollIntoView');
+        expect(js).toContain('"7"');
+    });
+    it('falls back to data-ref', () => {
+        const js = scrollToRefJs('3');
+        expect(js).toContain('data-ref');
+    });
+    it('returns scrolled info', () => {
+        const js = scrollToRefJs('1');
+        expect(js).toContain('scrolled: true');
+        expect(js).toContain('tag:');
+    });
+});
+describe('getFormStateJs', () => {
+    it('generates valid JS', () => {
+        const js = getFormStateJs();
+        expect(() => new Function(js)).not.toThrow();
+    });
+    it('collects form elements', () => {
+        const js = getFormStateJs();
+        expect(js).toContain('document.forms');
+        expect(js).toContain('form.elements');
+    });
+    it('collects orphan fields', () => {
+        const js = getFormStateJs();
+        expect(js).toContain('orphanFields');
+        expect(js).toContain('el.form');
+    });
+    it('handles different input types', () => {
+        const js = getFormStateJs();
+        expect(js).toContain('checkbox');
+        expect(js).toContain('radio');
+        expect(js).toContain('password');
+        expect(js).toContain('contenteditable');
+    });
+    it('extracts labels', () => {
+        const js = getFormStateJs();
+        expect(js).toContain('aria-label');
+        expect(js).toContain('label[for=');
+        expect(js).toContain('closest');
+        expect(js).toContain('placeholder');
+    });
+    it('masks passwords', () => {
+        const js = getFormStateJs();
+        expect(js).toContain('••••');
+    });
+    it('includes data-opencli-ref in output', () => {
+        const js = getFormStateJs();
+        expect(js).toContain('data-opencli-ref');
+    });
+});

package/dist/browser/index.d.ts

@@ -8,6 +8,8 @@ export { Page } from './page.js';
 export { BrowserBridge, BrowserBridge as PlaywrightMCP } from './mcp.js';
 export { CDPBridge } from './cdp.js';
 export { isDaemonRunning } from './daemon-client.js';
+export { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
+export type { SnapshotOptions } from './dom-snapshot.js';
 import { extractTabEntries, diffTabIndexes, appendLimited } from './tabs.js';
 import { withTimeoutMs } from '../runtime.js';
 export declare const __test__: {

package/dist/browser/index.js

@@ -8,6 +8,7 @@ export { Page } from './page.js';
 export { BrowserBridge, BrowserBridge as PlaywrightMCP } from './mcp.js';
 export { CDPBridge } from './cdp.js';
 export { isDaemonRunning } from './daemon-client.js';
+export { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
 import { extractTabEntries, diffTabIndexes, appendLimited } from './tabs.js';
 import { __test__ as cdpTest } from './cdp.js';
 import { withTimeoutMs } from '../runtime.js';

package/dist/browser/page.d.ts

@@ -9,7 +9,7 @@
  * where resolveTabId() in the extension picks a chrome:// or
  * chrome-extension:// tab that can't be debugged.
  */
-import type { IPage } from '../types.js';
+import type { BrowserCookie, IPage, ScreenshotOptions, SnapshotOptions, WaitOptions } from '../types.js';
 /**
  * Page — implements IPage by talking to the daemon via HTTP.
  */
@@ -27,36 +27,31 @@ export declare class Page implements IPage {
     }): Promise<void>;
     /** Close the automation window in the extension */
     closeWindow(): Promise<void>;
-    evaluate(js: string): Promise<any>;
+    evaluate(js: string): Promise<unknown>;
     getCookies(opts?: {
         domain?: string;
         url?: string;
-    }): Promise<any[]>;
-    snapshot(opts?: {
-        interactive?: boolean;
-        compact?: boolean;
-        maxDepth?: number;
-        raw?: boolean;
-    }): Promise<any>;
+    }): Promise<BrowserCookie[]>;
+    snapshot(opts?: SnapshotOptions): Promise<unknown>;
+    /** Fallback basic snapshot — original buildTree approach */
+    private _basicSnapshot;
     click(ref: string): Promise<void>;
     typeText(ref: string, text: string): Promise<void>;
     pressKey(key: string): Promise<void>;
-    wait(options: number | {
-        text?: string;
-        time?: number;
-        timeout?: number;
-    }): Promise<void>;
-    tabs(): Promise<any>;
+    scrollTo(ref: string): Promise<unknown>;
+    getFormState(): Promise<Record<string, unknown>>;
+    wait(options: number | WaitOptions): Promise<void>;
+    tabs(): Promise<unknown[]>;
     closeTab(index?: number): Promise<void>;
     newTab(): Promise<void>;
     selectTab(index: number): Promise<void>;
-    networkRequests(includeStatic?: boolean): Promise<any>;
+    networkRequests(includeStatic?: boolean): Promise<unknown[]>;
     /**
      * Console messages are not available in lightweight daemon mode.
      * Would require CDP Runtime.consoleAPICalled event listener.
      * @returns Always returns empty array.
      */
-    consoleMessages(_level?: string): Promise<any>;
+    consoleMessages(_level?: string): Promise<unknown[]>;
     /**
      * Capture a screenshot via CDP Page.captureScreenshot.
      * @param options.format - 'png' (default) or 'jpeg'
@@ -64,17 +59,12 @@ export declare class Page implements IPage {
      * @param options.fullPage - capture full scrollable page
      * @param options.path - save to file path (returns base64 if omitted)
      */
-    screenshot(options?: {
-        format?: 'png' | 'jpeg';
-        quality?: number;
-        fullPage?: boolean;
-        path?: string;
-    }): Promise<string>;
+    screenshot(options?: ScreenshotOptions): Promise<string>;
     scroll(direction?: string, amount?: number): Promise<void>;
     autoScroll(options?: {
         times?: number;
         delayMs?: number;
     }): Promise<void>;
     installInterceptor(pattern: string): Promise<void>;
-    getInterceptedRequests(): Promise<any[]>;
+    getInterceptedRequests(): Promise<unknown[]>;
 }

package/dist/browser/page.js

@@ -12,6 +12,7 @@
 import { formatSnapshot } from '../snapshotFormatter.js';
 import { sendCommand } from './daemon-client.js';
 import { wrapForEval } from './utils.js';
+import { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
 import { clickJs, typeTextJs, pressKeyJs, waitForTextJs, scrollJs, autoScrollJs, networkRequestsJs, } from './dom-helpers.js';
 /**
  * Page — implements IPage by talking to the daemon via HTTP.
@@ -65,6 +66,28 @@ export class Page {
         return Array.isArray(result) ? result : [];
     }
     async snapshot(opts = {}) {
+        // Primary: use the advanced DOM snapshot engine with multi-layer pruning
+        const snapshotJs = generateSnapshotJs({
+            viewportExpand: opts.viewportExpand ?? 800,
+            maxDepth: Math.max(1, Math.min(Number(opts.maxDepth) || 50, 200)),
+            interactiveOnly: opts.interactive ?? false,
+            maxTextLength: opts.maxTextLength ?? 120,
+            includeScrollInfo: true,
+            bboxDedup: true,
+        });
+        try {
+            const result = await sendCommand('exec', { code: snapshotJs, ...this._workspaceOpt(), ...this._tabOpt() });
+            // The advanced engine already produces a clean, pruned, LLM-friendly output.
+            // Do NOT pass through formatSnapshot — its format is incompatible.
+            return result;
+        }
+        catch {
+            // Fallback: basic DOM snapshot (original implementation)
+            return this._basicSnapshot(opts);
+        }
+    }
+    /** Fallback basic snapshot — original buildTree approach */
+    async _basicSnapshot(opts = {}) {
         const maxDepth = Math.max(1, Math.min(Number(opts.maxDepth) || 50, 200));
         const code = `
       (async () => {
@@ -78,7 +101,7 @@ export class Page {
 
           let indent = '  '.repeat(depth);
           let line = indent + role;
-          if (name) line += ' "' + name.replace(/"/g, '\\\\"') + '"';
+          if (name) line += ' "' + name.replace(/"/g, '\\\\\\"') + '"';
           if (node.tagName?.toLowerCase() === 'a' && node.href) line += ' [' + node.href + ']';
           if (node.tagName?.toLowerCase() === 'input') line += ' [' + (node.type || 'text') + ']';
 
@@ -112,6 +135,14 @@ export class Page {
         const code = pressKeyJs(key);
         await sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() });
     }
+    async scrollTo(ref) {
+        const code = scrollToRefJs(ref);
+        return sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() });
+    }
+    async getFormState() {
+        const code = getFormStateJs();
+        return (await sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() }));
+    }
     async wait(options) {
         if (typeof options === 'number') {
             await new Promise(resolve => setTimeout(resolve, options * 1000));
@@ -128,7 +159,8 @@ export class Page {
         }
     }
     async tabs() {
-        return sendCommand('tabs', { op: 'list', ...this._workspaceOpt() });
+        const result = await sendCommand('tabs', { op: 'list', ...this._workspaceOpt() });
+        return Array.isArray(result) ? result : [];
     }
     async closeTab(index) {
         await sendCommand('tabs', { op: 'close', ...this._workspaceOpt(), ...(index !== undefined ? { index } : {}) });
@@ -141,7 +173,8 @@ export class Page {
     }
     async networkRequests(includeStatic = false) {
         const code = networkRequestsJs(includeStatic);
-        return sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() });
+        const result = await sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() });
+        return Array.isArray(result) ? result : [];
     }
     /**
      * Console messages are not available in lightweight daemon mode.
@@ -198,7 +231,7 @@ export class Page {
         const { generateReadInterceptedJs } = await import('../interceptor.js');
         // Same as installInterceptor: must go through evaluate() for IIFE wrapping
         const result = await this.evaluate(generateReadInterceptedJs('__opencli_xhr'));
-        return result || [];
+        return Array.isArray(result) ? result : [];
     }
 }
 // (End of file)

package/dist/build-manifest.d.ts

@@ -8,7 +8,7 @@
  * Usage: npx tsx src/build-manifest.ts
  * Output: dist/cli-manifest.json
  */
-interface ManifestEntry {
+export interface ManifestEntry {
     site: string;
     name: string;
     description: string;
@@ -18,20 +18,27 @@ interface ManifestEntry {
     args: Array<{
         name: string;
         type?: string;
-        default?: any;
+        default?: unknown;
         required?: boolean;
         positional?: boolean;
         help?: string;
         choices?: string[];
     }>;
     columns?: string[];
-    pipeline?: any[];
+    pipeline?: Record<string, unknown>[];
     timeout?: number;
     /** 'yaml' or 'ts' — determines how executeCommand loads the handler */
     type: 'yaml' | 'ts';
     /** Relative path from clis/ dir, e.g. 'bilibili/hot.yaml' or 'bilibili/search.js' */
     modulePath?: string;
+    /** Pre-navigation control — see CliCommand.navigateBefore */
+    navigateBefore?: boolean | string;
 }
 export declare function parseTsArgsBlock(argsBlock: string): ManifestEntry['args'];
+export declare function scanTs(filePath: string, site: string): ManifestEntry | null;
+/**
+ * When both YAML and TS adapters exist for the same site/name,
+ * prefer the TS version (it self-registers and typically has richer logic).
+ */
+export declare function shouldReplaceManifestEntry(current: ManifestEntry, next: ManifestEntry): boolean;
 export declare function buildManifest(): ManifestEntry[];
-export {};

package/dist/build-manifest.js

@@ -15,6 +15,12 @@ import yaml from 'js-yaml';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CLIS_DIR = path.resolve(__dirname, 'clis');
 const OUTPUT = path.resolve(__dirname, '..', 'dist', 'cli-manifest.json');
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 function extractBalancedBlock(source, startIndex, openChar, closeChar) {
     let depth = 0;
     let quote = null;
@@ -116,44 +122,47 @@ function scanYaml(filePath, site) {
     try {
         const raw = fs.readFileSync(filePath, 'utf-8');
         const def = yaml.load(raw);
-        if (!def || typeof def !== 'object')
+        if (!isRecord(def))
             return null;
-        const strategyStr = def.strategy ?? (def.browser === false ? 'public' : 'cookie');
+        const cliDef = def;
+        const strategyStr = cliDef.strategy ?? (cliDef.browser === false ? 'public' : 'cookie');
         const strategy = strategyStr.toUpperCase();
-        const browser = def.browser ?? (strategy !== 'PUBLIC');
+        const browser = cliDef.browser ?? (strategy !== 'PUBLIC');
         const args = [];
-        if (def.args && typeof def.args === 'object') {
-            for (const [argName, argDef] of Object.entries(def.args)) {
+        if (cliDef.args && typeof cliDef.args === 'object') {
+            for (const [argName, argDef] of Object.entries(cliDef.args)) {
                 args.push({
                     name: argName,
                     type: argDef?.type ?? 'str',
                     default: argDef?.default,
                     required: argDef?.required ?? false,
+                    positional: argDef?.positional === true || undefined,
                     help: argDef?.description ?? argDef?.help ?? '',
                     choices: argDef?.choices,
                 });
             }
         }
         return {
-            site: def.site ?? site,
-            name: def.name ?? path.basename(filePath, path.extname(filePath)),
-            description: def.description ?? '',
-            domain: def.domain,
+            site: cliDef.site ?? site,
+            name: cliDef.name ?? path.basename(filePath, path.extname(filePath)),
+            description: cliDef.description ?? '',
+            domain: cliDef.domain,
             strategy: strategy.toLowerCase(),
             browser,
             args,
-            columns: def.columns,
-            pipeline: def.pipeline,
-            timeout: def.timeout,
+            columns: cliDef.columns,
+            pipeline: cliDef.pipeline,
+            timeout: cliDef.timeout,
             type: 'yaml',
+            navigateBefore: cliDef.navigateBefore,
         };
     }
     catch (err) {
-        process.stderr.write(`Warning: failed to parse ${filePath}: ${err.message}\n`);
+        process.stderr.write(`Warning: failed to parse ${filePath}: ${getErrorMessage(err)}\n`);
         return null;
     }
 }
-function scanTs(filePath, site) {
+export function scanTs(filePath, site) {
     // TS adapters self-register via cli() at import time.
     // We statically parse the source to extract metadata for the manifest stub.
     const baseName = path.basename(filePath, path.extname(filePath));
@@ -201,16 +210,29 @@ function scanTs(filePath, site) {
         if (argsBlock) {
             entry.args = parseTsArgsBlock(argsBlock);
         }
+        // Extract navigateBefore: false
+        const navMatch = src.match(/navigateBefore\s*:\s*(true|false)/);
+        if (navMatch)
+            entry.navigateBefore = navMatch[1] === 'true' ? true : false;
         return entry;
     }
     catch (err) {
         // If parsing fails, log a warning (matching scanYaml behaviour) and skip the entry.
-        process.stderr.write(`Warning: failed to scan ${filePath}: ${err.message}\n`);
+        process.stderr.write(`Warning: failed to scan ${filePath}: ${getErrorMessage(err)}\n`);
         return null;
     }
 }
+/**
+ * When both YAML and TS adapters exist for the same site/name,
+ * prefer the TS version (it self-registers and typically has richer logic).
+ */
+export function shouldReplaceManifestEntry(current, next) {
+    if (current.type === next.type)
+        return true;
+    return current.type === 'yaml' && next.type === 'ts';
+}
 export function buildManifest() {
-    const manifest = [];
+    const manifest = new Map();
     if (fs.existsSync(CLIS_DIR)) {
         for (const site of fs.readdirSync(CLIS_DIR)) {
             const siteDir = path.join(CLIS_DIR, site);
@@ -220,19 +242,35 @@ export function buildManifest() {
                 const filePath = path.join(siteDir, file);
                 if (file.endsWith('.yaml') || file.endsWith('.yml')) {
                     const entry = scanYaml(filePath, site);
-                    if (entry)
-                        manifest.push(entry);
+                    if (entry) {
+                        const key = `${entry.site}/${entry.name}`;
+                        const existing = manifest.get(key);
+                        if (!existing || shouldReplaceManifestEntry(existing, entry)) {
+                            if (existing && existing.type !== entry.type) {
+                                process.stderr.write(`⚠️  Duplicate adapter ${key}: ${existing.type} superseded by ${entry.type}\n`);
+                            }
+                            manifest.set(key, entry);
+                        }
+                    }
                 }
                 else if ((file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts') && file !== 'index.ts') ||
                     (file.endsWith('.js') && !file.endsWith('.d.js') && !file.endsWith('.test.js') && file !== 'index.js')) {
                     const entry = scanTs(filePath, site);
-                    if (entry)
-                        manifest.push(entry);
+                    if (entry) {
+                        const key = `${entry.site}/${entry.name}`;
+                        const existing = manifest.get(key);
+                        if (!existing || shouldReplaceManifestEntry(existing, entry)) {
+                            if (existing && existing.type !== entry.type) {
+                                process.stderr.write(`⚠️  Duplicate adapter ${key}: ${existing.type} superseded by ${entry.type}\n`);
+                            }
+                            manifest.set(key, entry);
+                        }
+                    }
                 }
             }
         }
     }
-    return manifest;
+    return [...manifest.values()];
 }
 function main() {
     const manifest = buildManifest();

package/dist/build-manifest.test.js

@@ -1,5 +1,8 @@
-import { describe, expect, it } from 'vitest';
-import { parseTsArgsBlock } from './build-manifest.js';
+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 { parseTsArgsBlock, scanTs, shouldReplaceManifestEntry } from './build-manifest.js';
 describe('parseTsArgsBlock', () => {
     it('keeps args with nested choices arrays', () => {
         const args = parseTsArgsBlock(`
@@ -58,3 +61,56 @@ describe('parseTsArgsBlock', () => {
         ]);
     });
 });
+describe('manifest helper rules', () => {
+    const tempDirs = [];
+    afterEach(() => {
+        for (const dir of tempDirs.splice(0)) {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('prefers TS adapters over duplicate YAML adapters', () => {
+        expect(shouldReplaceManifestEntry({
+            site: 'demo',
+            name: 'search',
+            description: 'yaml',
+            strategy: 'public',
+            browser: false,
+            args: [],
+            type: 'yaml',
+        }, {
+            site: 'demo',
+            name: 'search',
+            description: 'ts',
+            strategy: 'public',
+            browser: false,
+            args: [],
+            type: 'ts',
+            modulePath: 'demo/search.js',
+        })).toBe(true);
+        expect(shouldReplaceManifestEntry({
+            site: 'demo',
+            name: 'search',
+            description: 'ts',
+            strategy: 'public',
+            browser: false,
+            args: [],
+            type: 'ts',
+            modulePath: 'demo/search.js',
+        }, {
+            site: 'demo',
+            name: 'search',
+            description: 'yaml',
+            strategy: 'public',
+            browser: false,
+            args: [],
+            type: 'yaml',
+        })).toBe(false);
+    });
+    it('skips TS files that do not register a cli', () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-manifest-'));
+        tempDirs.push(dir);
+        const file = path.join(dir, 'utils.ts');
+        fs.writeFileSync(file, `export function helper() { return 'noop'; }`);
+        expect(scanTs(file, 'demo')).toBeNull();
+    });
+});