@jackwener/opencli 1.1.0 → 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.
  */
@@ -21,39 +21,37 @@ export declare class Page implements IPage {
     /** Helper: spread tabId into command params if we have one */
     private _tabOpt;
     private _workspaceOpt;
-    goto(url: string): Promise<void>;
+    goto(url: string, options?: {
+        waitUntil?: 'load' | 'none';
+        settleMs?: number;
+    }): 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'
@@ -61,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.
@@ -30,7 +31,7 @@ export class Page {
     _workspaceOpt() {
         return { workspace: this.workspace };
     }
-    async goto(url) {
+    async goto(url, options) {
         const result = await sendCommand('navigate', {
             url,
             ...this._workspaceOpt(),
@@ -40,6 +41,12 @@ export class Page {
         if (result?.tabId) {
             this._tabId = result.tabId;
         }
+        // Post-load settle: the extension already waits for tab.status === 'complete',
+        // but SPA frameworks (React/Vue) need extra time to render after DOM load.
+        if (options?.waitUntil !== 'none') {
+            const settleMs = options?.settleMs ?? 1000;
+            await new Promise(resolve => setTimeout(resolve, settleMs));
+        }
     }
     /** Close the automation window in the extension */
     async closeWindow() {
@@ -59,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 () => {
@@ -72,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') + ']';
 
@@ -106,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));
@@ -122,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 } : {}) });
@@ -135,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.
@@ -192,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,60 +122,66 @@ 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));
     const relativePath = `${site}/${baseName}.js`;
-    const entry = {
-        site,
-        name: baseName,
-        description: '',
-        strategy: 'cookie',
-        browser: true,
-        args: [],
-        type: 'ts',
-        modulePath: relativePath,
-    };
     try {
         const src = fs.readFileSync(filePath, 'utf-8');
+        // Helper/test modules should not appear as CLI commands in the manifest.
+        if (!/\bcli\s*\(/.test(src))
+            return null;
+        const entry = {
+            site,
+            name: baseName,
+            description: '',
+            strategy: 'cookie',
+            browser: true,
+            args: [],
+            type: 'ts',
+            modulePath: relativePath,
+        };
         // Extract description
         const descMatch = src.match(/description\s*:\s*['"`]([^'"`]*)['"`]/);
         if (descMatch)
@@ -198,14 +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 {
-        // If parsing fails, fall back to empty metadata — module will self-register at runtime
+    catch (err) {
+        // If parsing fails, log a warning (matching scanYaml behaviour) and skip the entry.
+        process.stderr.write(`Warning: failed to scan ${filePath}: ${getErrorMessage(err)}\n`);
+        return null;
     }
-    return entry;
+}
+/**
+ * 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);
@@ -215,17 +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 !== 'index.ts') ||
-                    (file.endsWith('.js') && !file.endsWith('.d.js') && file !== 'index.js')) {
-                    manifest.push(scanTs(filePath, site));
+                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) {
+                        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();