@jackwener/opencli 0.4.1 → 0.4.3

package/dist/runtime.d.ts

@@ -10,4 +10,6 @@ export declare function runWithTimeout<T>(promise: Promise<T>, opts: {
     timeout: number;
     label?: string;
 }): Promise<T>;
-export declare function browserSession<T>(BrowserFactory: new () => any, fn: (page: IPage) => Promise<T>): Promise<T>;
+export declare function browserSession<T>(BrowserFactory: new () => any, fn: (page: IPage) => Promise<T>, opts?: {
+    forceExtension?: boolean;
+}): Promise<T>;

package/dist/runtime.js

@@ -15,10 +15,10 @@ export async function runWithTimeout(promise, opts) {
             .catch((err) => { clearTimeout(timer); reject(err); });
     });
 }
-export async function browserSession(BrowserFactory, fn) {
+export async function browserSession(BrowserFactory, fn, opts) {
     const mcp = new BrowserFactory();
     try {
-        const page = await mcp.connect({ timeout: DEFAULT_BROWSER_CONNECT_TIMEOUT });
+        const page = await mcp.connect({ timeout: DEFAULT_BROWSER_CONNECT_TIMEOUT, forceExtension: opts?.forceExtension });
         return await fn(page);
     }
     finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackwener/opencli",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "publishConfig": {
     "access": "public"
   },
@@ -31,7 +31,7 @@
     "playwright"
   ],
   "author": "jackwener",
-  "license": "MIT",
+  "license": "BSD-3-Clause",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jackwener/opencli.git"

package/src/browser.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import { formatBrowserConnectError, getTokenFingerprint } from './browser.js';
+
+describe('getTokenFingerprint', () => {
+  it('returns null for empty token', () => {
+    expect(getTokenFingerprint(undefined)).toBeNull();
+  });
+
+  it('returns stable short fingerprint for token', () => {
+    expect(getTokenFingerprint('abc123')).toBe('6ca13d52');
+  });
+});
+
+describe('formatBrowserConnectError', () => {
+  it('explains missing extension token clearly', () => {
+    const err = formatBrowserConnectError({
+      kind: 'missing-token',
+      mode: 'extension',
+      timeout: 30,
+      hasExtensionToken: false,
+    });
+
+    expect(err.message).toContain('PLAYWRIGHT_MCP_EXTENSION_TOKEN is not set');
+    expect(err.message).toContain('manual approval dialog');
+  });
+
+  it('mentions token mismatch as likely cause for extension timeout', () => {
+    const err = formatBrowserConnectError({
+      kind: 'extension-timeout',
+      mode: 'extension',
+      timeout: 30,
+      hasExtensionToken: true,
+      tokenFingerprint: 'deadbeef',
+    });
+
+    expect(err.message).toContain('does not match the token currently shown by the browser extension');
+    expect(err.message).toContain('deadbeef');
+  });
+
+  it('keeps CDP timeout guidance separate', () => {
+    const err = formatBrowserConnectError({
+      kind: 'cdp-timeout',
+      mode: 'cdp',
+      timeout: 30,
+      hasExtensionToken: false,
+    });
+
+    expect(err.message).toContain('via CDP');
+    expect(err.message).toContain('chrome://inspect#remote-debugging');
+  });
+});

package/src/browser.ts

@@ -1,15 +1,81 @@
 /**
- * Browser interaction via Playwright MCP Bridge extension.
- * Connects to an existing Chrome browser through the extension's stdio JSON-RPC.
+ * Browser interaction via Chrome DevTools Protocol.
+ * Connects to an existing Chrome browser through CDP auto-discovery or extension bridge.
  */
 
 import { spawn, execSync, type ChildProcess } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import * as net from 'node:net';
 import { fileURLToPath } from 'node:url';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { formatSnapshot } from './snapshotFormatter.js';
 
+/**
+ * Chrome 144+ auto-discovery: read DevToolsActivePort file to get CDP endpoint.
+ *
+ * Starting with Chrome 144, users can enable remote debugging from
+ * chrome://inspect#remote-debugging without any command-line flags.
+ * Chrome writes the active port and browser GUID to a DevToolsActivePort file
+ * in the user data directory, which we read to construct the WebSocket endpoint.
+ *
+ * Priority: OPENCLI_CDP_ENDPOINT env > DevToolsActivePort auto-discovery > --extension fallback
+ */
+
+/** Quick TCP port probe to verify Chrome is actually listening */
+function isPortReachable(port: number, host = '127.0.0.1', timeoutMs = 800): Promise<boolean> {
+  return new Promise(resolve => {
+    const sock = net.createConnection({ port, host });
+    sock.setTimeout(timeoutMs);
+    sock.on('connect', () => { sock.destroy(); resolve(true); });
+    sock.on('error', () => resolve(false));
+    sock.on('timeout', () => { sock.destroy(); resolve(false); });
+  });
+}
+
+export async function discoverChromeEndpoint(): Promise<string | null> {
+  const candidates: string[] = [];
+
+  // User-specified Chrome data dir takes highest priority
+  if (process.env.CHROME_USER_DATA_DIR) {
+    candidates.push(path.join(process.env.CHROME_USER_DATA_DIR, 'DevToolsActivePort'));
+  }
+
+  // Standard Chrome/Edge user data dirs per platform
+  if (process.platform === 'win32') {
+    const localAppData = process.env.LOCALAPPDATA ?? path.join(os.homedir(), 'AppData', 'Local');
+    candidates.push(path.join(localAppData, 'Google', 'Chrome', 'User Data', 'DevToolsActivePort'));
+    candidates.push(path.join(localAppData, 'Microsoft', 'Edge', 'User Data', 'DevToolsActivePort'));
+  } else if (process.platform === 'darwin') {
+    candidates.push(path.join(os.homedir(), 'Library', 'Application Support', 'Google', 'Chrome', 'DevToolsActivePort'));
+    candidates.push(path.join(os.homedir(), 'Library', 'Application Support', 'Microsoft Edge', 'DevToolsActivePort'));
+  } else {
+    candidates.push(path.join(os.homedir(), '.config', 'google-chrome', 'DevToolsActivePort'));
+    candidates.push(path.join(os.homedir(), '.config', 'chromium', 'DevToolsActivePort'));
+    candidates.push(path.join(os.homedir(), '.config', 'microsoft-edge', 'DevToolsActivePort'));
+  }
+
+  for (const filePath of candidates) {
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8').trim();
+      const lines = content.split('\n');
+      if (lines.length >= 2) {
+        const port = parseInt(lines[0], 10);
+        const browserPath = lines[1]; // e.g. /devtools/browser/<GUID>
+        if (port > 0 && browserPath.startsWith('/devtools/browser/')) {
+          const endpoint = `ws://127.0.0.1:${port}${browserPath}`;
+          // Verify the port is actually reachable (Chrome may have closed, leaving a stale file)
+          if (await isPortReachable(port)) {
+            return endpoint;
+          }
+        }
+      }
+    } catch {}
+  }
+  return null;
+}
+
 // Read version from package.json (single source of truth)
 const __browser_dirname = path.dirname(fileURLToPath(import.meta.url));
 const PKG_VERSION = (() => { try { return JSON.parse(fs.readFileSync(path.resolve(__browser_dirname, '..', 'package.json'), 'utf-8')).version; } catch { return '0.0.0'; } })();
@@ -19,6 +85,106 @@ const EXTENSION_LOCK_POLL = parseInt(process.env.OPENCLI_EXTENSION_LOCK_POLL_INT
 const CONNECT_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_CONNECT_TIMEOUT ?? '30', 10);
 const LOCK_DIR = path.join(os.tmpdir(), 'opencli-mcp-lock');
 
+type ConnectFailureKind = 'missing-token' | 'extension-timeout' | 'extension-not-installed' | 'cdp-timeout' | 'mcp-init' | 'process-exit' | 'unknown';
+
+type ConnectFailureInput = {
+  kind: ConnectFailureKind;
+  mode: 'extension' | 'cdp';
+  timeout: number;
+  hasExtensionToken: boolean;
+  tokenFingerprint?: string | null;
+  stderr?: string;
+  exitCode?: number | null;
+  rawMessage?: string;
+};
+
+export function getTokenFingerprint(token: string | undefined): string | null {
+  if (!token) return null;
+  return createHash('sha256').update(token).digest('hex').slice(0, 8);
+}
+
+export function formatBrowserConnectError(input: ConnectFailureInput): Error {
+  const stderr = input.stderr?.trim();
+  const suffix = stderr ? `\n\nMCP stderr:\n${stderr}` : '';
+  const tokenHint = input.tokenFingerprint ? ` Token fingerprint: ${input.tokenFingerprint}.` : '';
+
+  if (input.mode === 'extension') {
+    if (input.kind === 'missing-token') {
+      return new Error(
+        'Failed to connect to Playwright MCP Bridge: PLAYWRIGHT_MCP_EXTENSION_TOKEN is not set.\n\n' +
+        'Without this token, Chrome will show a manual approval dialog for every new MCP connection. ' +
+        'Copy the token from the Playwright MCP Bridge extension and set it in BOTH your shell environment and MCP client config.' +
+        suffix,
+      );
+    }
+
+    if (input.kind === 'extension-not-installed') {
+      return new Error(
+        'Failed to connect to Playwright MCP Bridge: the browser extension did not attach.\n\n' +
+        'Make sure Chrome is running and the "Playwright MCP Bridge" extension is installed and enabled. ' +
+        'If Chrome shows an approval dialog, click Allow.' +
+        suffix,
+      );
+    }
+
+    if (input.kind === 'extension-timeout') {
+      const likelyCause = input.hasExtensionToken
+        ? `The most likely cause is that PLAYWRIGHT_MCP_EXTENSION_TOKEN does not match the token currently shown by the browser extension.${tokenHint} Re-copy the token from the extension and update BOTH your shell environment and MCP client config.`
+        : 'PLAYWRIGHT_MCP_EXTENSION_TOKEN is not configured, so the extension may be waiting for manual approval.';
+      return new Error(
+        `Timed out connecting to Playwright MCP Bridge (${input.timeout}s).\n\n` +
+        `${likelyCause} If a browser prompt is visible, click Allow. You can also switch to Chrome remote debugging mode with OPENCLI_USE_CDP=1 as a fallback.` +
+        suffix,
+      );
+    }
+  }
+
+  if (input.mode === 'cdp' && input.kind === 'cdp-timeout') {
+    return new Error(
+      `Timed out connecting to browser via CDP (${input.timeout}s).\n\n` +
+      'Make sure Chrome is running and remote debugging is enabled at chrome://inspect#remote-debugging, or set OPENCLI_CDP_ENDPOINT explicitly.' +
+      suffix,
+    );
+  }
+
+  if (input.kind === 'mcp-init') {
+    return new Error(`Failed to initialize Playwright MCP: ${input.rawMessage ?? 'unknown error'}${suffix}`);
+  }
+
+  if (input.kind === 'process-exit') {
+    return new Error(
+      `Playwright MCP process exited before the browser connection was established${input.exitCode == null ? '' : ` (code ${input.exitCode})`}.` +
+      suffix,
+    );
+  }
+
+  return new Error(input.rawMessage ?? 'Failed to connect to browser');
+}
+
+function inferConnectFailureKind(args: {
+  mode: 'extension' | 'cdp';
+  hasExtensionToken: boolean;
+  stderr: string;
+  rawMessage?: string;
+  exited?: boolean;
+}): ConnectFailureKind {
+  const haystack = `${args.rawMessage ?? ''}\n${args.stderr}`.toLowerCase();
+
+  if (args.mode === 'extension' && !args.hasExtensionToken)
+    return 'missing-token';
+  if (haystack.includes('extension connection timeout') || haystack.includes('playwright mcp bridge'))
+    return 'extension-not-installed';
+  if (args.rawMessage?.startsWith('MCP init failed:'))
+    return 'mcp-init';
+  if (args.exited)
+    return 'process-exit';
+  if (args.mode === 'extension')
+    return 'extension-timeout';
+  if (args.mode === 'cdp')
+    return 'cdp-timeout';
+  return 'unknown';
+}
+
 // JSON-RPC helpers
 let _nextId = 1;
 function jsonRpcRequest(method: string, params: Record<string, any> = {}): string {
@@ -231,6 +397,28 @@ export class Page implements IPage {
  * Playwright MCP process manager.
  */
 export class PlaywrightMCP {
+  private static _activeInsts: Set<PlaywrightMCP> = new Set();
+  private static _cleanupRegistered = false;
+
+  private static _registerGlobalCleanup() {
+    if (this._cleanupRegistered) return;
+    this._cleanupRegistered = true;
+    const cleanup = () => {
+      for (const inst of this._activeInsts) {
+        if (inst._lockAcquired) {
+          try { fs.rmdirSync(LOCK_DIR); } catch {}
+          inst._lockAcquired = false;
+        }
+        if (inst._proc && !inst._proc.killed) {
+          try { inst._proc.kill('SIGKILL'); } catch {}
+        }
+      }
+    };
+    process.on('exit', cleanup);
+    process.on('SIGINT', () => { cleanup(); process.exit(130); });
+    process.on('SIGTERM', () => { cleanup(); process.exit(143); });
+  }
+
   private _proc: ChildProcess | null = null;
   private _buffer = '';
   private _waiters: Array<(data: any) => void> = [];
@@ -239,24 +427,89 @@ export class PlaywrightMCP {
 
   private _page: Page | null = null;
 
-  async connect(opts: { timeout?: number } = {}): Promise<Page> {
+  async connect(opts: { timeout?: number; forceExtension?: boolean } = {}): Promise<Page> {
     await this._acquireLock();
     const timeout = opts.timeout ?? CONNECT_TIMEOUT;
     const mcpPath = findMcpServerPath();
     if (!mcpPath) throw new Error('Playwright MCP server not found. Install: npm install -D @playwright/mcp');
 
-    return new Promise<Page>((resolve, reject) => {
-      const timer = setTimeout(() => reject(new Error(`Timed out connecting to browser (${timeout}s)`)), timeout * 1000);
-
-      const mcpArgs = [mcpPath, '--extension'];
-    if (process.env.OPENCLI_BROWSER_EXECUTABLE_PATH) {
-      mcpArgs.push('--executablePath', process.env.OPENCLI_BROWSER_EXECUTABLE_PATH);
+    // Connection priority:
+    // 1. OPENCLI_CDP_ENDPOINT env var → explicit CDP endpoint
+    // 2. OPENCLI_USE_CDP=1 → auto-discover via DevToolsActivePort
+    // 3. Default → --extension mode (Playwright MCP Bridge)
+    // Some anti-bot sites (e.g. BOSS Zhipin) detect CDP — use forceExtension to bypass.
+    const forceExt = opts.forceExtension || process.env.OPENCLI_FORCE_EXTENSION === '1';
+    let cdpEndpoint: string | null = null;
+    if (!forceExt) {
+      if (process.env.OPENCLI_CDP_ENDPOINT) {
+        cdpEndpoint = process.env.OPENCLI_CDP_ENDPOINT;
+      } else if (process.env.OPENCLI_USE_CDP === '1') {
+        cdpEndpoint = await discoverChromeEndpoint();
+      }
     }
 
-    this._proc = spawn('node', mcpArgs, {
-      stdio: ['pipe', 'pipe', 'pipe'],
-      env: { ...process.env, ...(process.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN ? { PLAYWRIGHT_MCP_EXTENSION_TOKEN: process.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN } : {}) },
-    });
+    return new Promise<Page>((resolve, reject) => {
+      const isDebug = process.env.DEBUG?.includes('opencli:mcp');
+      const debugLog = (msg: string) => isDebug && console.error(`[opencli:mcp] ${msg}`);
+      const mode: 'extension' | 'cdp' = cdpEndpoint ? 'cdp' : 'extension';
+      const extensionToken = process.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN;
+      const tokenFingerprint = getTokenFingerprint(extensionToken);
+      let stderrBuffer = '';
+      let settled = false;
+
+      const settleError = (kind: ConnectFailureKind, extra: { rawMessage?: string; exitCode?: number | null } = {}) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        reject(formatBrowserConnectError({
+          kind,
+          mode,
+          timeout,
+          hasExtensionToken: !!extensionToken,
+          tokenFingerprint,
+          stderr: stderrBuffer,
+          exitCode: extra.exitCode,
+          rawMessage: extra.rawMessage,
+        }));
+      };
+
+      const settleSuccess = (pageToResolve: Page) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(pageToResolve);
+      };
+
+      const timer = setTimeout(() => {
+        debugLog('Connection timed out');
+        settleError(inferConnectFailureKind({
+          mode,
+          hasExtensionToken: !!extensionToken,
+          stderr: stderrBuffer,
+        }));
+      }, timeout * 1000);
+
+      const mcpArgs: string[] = [mcpPath];
+      if (cdpEndpoint) {
+        mcpArgs.push('--cdp-endpoint', cdpEndpoint);
+      } else {
+        mcpArgs.push('--extension');
+      }
+      if (process.env.OPENCLI_VERBOSE) {
+        console.error(`[opencli] CDP mode: ${cdpEndpoint ? `auto-discovered ${cdpEndpoint}` : 'fallback to --extension'}`);
+        if (mode === 'extension') {
+          console.error(`[opencli] Extension token: ${extensionToken ? `configured (fingerprint ${tokenFingerprint})` : 'missing'}`);
+        }
+      }
+      if (process.env.OPENCLI_BROWSER_EXECUTABLE_PATH) {
+        mcpArgs.push('--executablePath', process.env.OPENCLI_BROWSER_EXECUTABLE_PATH);
+      }
+      debugLog(`Spawning node ${mcpArgs.join(' ')}`);
+
+      this._proc = spawn('node', mcpArgs, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env },
+      });
 
       // Increase max listeners to avoid warnings
       this._proc.setMaxListeners(20);
@@ -274,16 +527,37 @@ export class PlaywrightMCP {
         this._buffer = lines.pop() ?? '';
         for (const line of lines) {
           if (!line.trim()) continue;
+          debugLog(`RECV: ${line}`);
           try {
             const parsed = JSON.parse(line);
             const waiter = this._waiters.shift();
             if (waiter) waiter(parsed);
-          } catch {}
+          } catch (e) {
+            debugLog(`Parse error: ${e}`);
+          }
         }
       });
 
-      this._proc.stderr?.on('data', () => {});
-      this._proc.on('error', (err) => { clearTimeout(timer); reject(err); });
+      this._proc.stderr?.on('data', (chunk: Buffer) => {
+        const text = chunk.toString();
+        stderrBuffer += text;
+        debugLog(`STDERR: ${text}`);
+      });
+      this._proc.on('error', (err) => {
+        debugLog(`Subprocess error: ${err.message}`);
+        settleError('process-exit', { rawMessage: err.message });
+      });
+      this._proc.on('close', (code) => {
+        debugLog(`Subprocess closed with code ${code}`);
+        if (!settled) {
+          settleError(inferConnectFailureKind({
+            mode,
+            hasExtensionToken: !!extensionToken,
+            stderr: stderrBuffer,
+            exited: true,
+          }), { exitCode: code });
+        }
+      });
 
       // Initialize: send initialize request
       const initMsg = jsonRpcRequest('initialize', {
@@ -291,25 +565,46 @@ export class PlaywrightMCP {
         capabilities: {},
         clientInfo: { name: 'opencli', version: PKG_VERSION },
       });
+      debugLog(`SEND: ${initMsg.trim()}`);
       this._proc.stdin?.write(initMsg);
 
       // Wait for initialize response, then send initialized notification
       const origRecv = () => new Promise<any>((res) => { this._waiters.push(res); });
+      debugLog('Waiting for initialize response...');
       origRecv().then((resp) => {
-        if (resp.error) { clearTimeout(timer); reject(new Error(`MCP init failed: ${resp.error.message}`)); return; }
-        this._proc?.stdin?.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n');
+        debugLog('Got initialize response');
+        if (resp.error) {
+          settleError(inferConnectFailureKind({
+            mode,
+            hasExtensionToken: !!extensionToken,
+            stderr: stderrBuffer,
+            rawMessage: `MCP init failed: ${resp.error.message}`,
+          }), { rawMessage: resp.error.message });
+          return;
+        }
+        
+        const initializedMsg = JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n';
+        debugLog(`SEND: ${initializedMsg.trim()}`);
+        this._proc?.stdin?.write(initializedMsg);
 
         // Get initial tab count for cleanup
+        debugLog('Fetching initial tabs count...');
         page.tabs().then((tabs: any) => {
+          debugLog(`Tabs response: ${typeof tabs === 'string' ? tabs : JSON.stringify(tabs)}`);
           if (typeof tabs === 'string') {
             this._initialTabCount = (tabs.match(/Tab \d+/g) || []).length;
           } else if (Array.isArray(tabs)) {
             this._initialTabCount = tabs.length;
           }
-          clearTimeout(timer);
-          resolve(page);
-        }).catch(() => { clearTimeout(timer); resolve(page); });
-      }).catch((err) => { clearTimeout(timer); reject(err); });
+          settleSuccess(page);
+        }).catch((err) => {
+          debugLog(`Tabs fetch error: ${err.message}`);
+          settleSuccess(page);
+        });
+      }).catch((err) => {
+        debugLog(`Init promise rejected: ${err.message}`);
+        settleError('mcp-init', { rawMessage: err.message });
+      });
     });
   }
 
@@ -339,6 +634,7 @@ export class PlaywrightMCP {
     } finally {
       this._page = null;
       this._releaseLock();
+      PlaywrightMCP._activeInsts.delete(this);
     }
   }
 

package/src/build-manifest.ts

@@ -87,10 +87,11 @@ function scanYaml(filePath: string, site: string): ManifestEntry | null {
 
 function scanTs(filePath: string, site: string): ManifestEntry {
   // TS adapters self-register via cli() at import time.
-  // We record their module path for lazy dynamic import.
+  // 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`;
-  return {
+
+  const entry: ManifestEntry = {
     site,
     name: baseName,
     description: '',
@@ -100,6 +101,70 @@ function scanTs(filePath: string, site: string): ManifestEntry {
     type: 'ts',
     modulePath: relativePath,
   };
+
+  try {
+    const src = fs.readFileSync(filePath, 'utf-8');
+
+    // Extract description
+    const descMatch = src.match(/description\s*:\s*['"`]([^'"`]*)['"`]/);
+    if (descMatch) entry.description = descMatch[1];
+
+    // Extract domain
+    const domainMatch = src.match(/domain\s*:\s*['"`]([^'"`]*)['"`]/);
+    if (domainMatch) entry.domain = domainMatch[1];
+
+    // Extract strategy
+    const stratMatch = src.match(/strategy\s*:\s*Strategy\.(\w+)/);
+    if (stratMatch) entry.strategy = stratMatch[1].toLowerCase();
+
+    // Extract browser: false (some adapters bypass browser entirely)
+    const browserMatch = src.match(/browser\s*:\s*(true|false)/);
+    if (browserMatch) entry.browser = browserMatch[1] === 'true';
+
+    // Extract columns
+    const colMatch = src.match(/columns\s*:\s*\[([^\]]*)\]/);
+    if (colMatch) {
+      entry.columns = colMatch[1].split(',').map(s => s.trim().replace(/^['"`]|['"`]$/g, '')).filter(Boolean);
+    }
+
+    // Extract args array items: { name: '...', ... }
+    const argsBlockMatch = src.match(/args\s*:\s*\[([\s\S]*?)\]\s*,/);
+    if (argsBlockMatch) {
+      const argsBlock = argsBlockMatch[1];
+      const argRegex = /\{\s*name\s*:\s*['"`](\w+)['"`]([^}]*)\}/g;
+      let m;
+      while ((m = argRegex.exec(argsBlock)) !== null) {
+        const argName = m[1];
+        const body = m[2];
+        const typeMatch = body.match(/type\s*:\s*['"`](\w+)['"`]/);
+        const defaultMatch = body.match(/default\s*:\s*([^,}]+)/);
+        const requiredMatch = body.match(/required\s*:\s*(true|false)/);
+        const helpMatch = body.match(/help\s*:\s*['"`]([^'"`]*)['"`]/);
+
+        let defaultVal: any = undefined;
+        if (defaultMatch) {
+          const raw = defaultMatch[1].trim();
+          if (raw === 'true') defaultVal = true;
+          else if (raw === 'false') defaultVal = false;
+          else if (/^\d+$/.test(raw)) defaultVal = parseInt(raw, 10);
+          else if (/^\d+\.\d+$/.test(raw)) defaultVal = parseFloat(raw);
+          else defaultVal = raw.replace(/^['"`]|['"`]$/g, '');
+        }
+
+        entry.args.push({
+          name: argName,
+          type: typeMatch?.[1] ?? 'str',
+          default: defaultVal,
+          required: requiredMatch?.[1] === 'true',
+          help: helpMatch?.[1] ?? '',
+        });
+      }
+    }
+  } catch {
+    // If parsing fails, fall back to empty metadata — module will self-register at runtime
+  }
+
+  return entry;
 }
 
 // Main