@jackwener/opencli 1.1.0 → 1.1.1

package/docs/developer/architecture.md

@@ -34,8 +34,14 @@ OpenCLI is built on a **Dual-Engine Architecture** that supports both declarativ
 ### Registry (`src/registry.ts`)
 Central command registry. All adapters register their commands via the `cli()` function with metadata: site, name, description, domain, strategy, args, columns.
 
-### Engine (`src/engine.ts`)
-Command discovery and execution engine. Discovers commands from the registry, parses arguments, executes the appropriate adapter, and routes output through the formatter.
+### Discovery (`src/discovery.ts`)
+CLI discovery and manifest loading. Discovers commands from YAML and TypeScript adapter files, parses YAML pipelines, and registers them into the central registry.
+
+### Execution (`src/execution.ts`)
+Command execution: argument validation, lazy loading of adapter modules, and executing the appropriate handler function.
+
+### Commander Adapter (`src/commanderAdapter.ts`)
+Bridges the Registry commands to Commander.js subcommands. Handles positional args, named options, browser session wiring, and output formatting. Isolates all Commander-specific logic so the core is framework-agnostic.
 
 ### Browser (`src/browser.ts`)
 Manages connections to Chrome via the Browser Bridge WebSocket daemon. Handles JSON-RPC messaging, tab management, and extension/standalone mode switching.
@@ -60,15 +66,22 @@ OpenCLI uses a 3-tier authentication strategy:
 | `public` | Direct HTTP fetch, no auth | Public APIs (HackerNews, BBC) |
 | `cookie` | Reuse Chrome cookies via Browser Bridge | Logged-in sites (Bilibili, Zhihu) |
 | `header` | Custom auth headers | API-key based services |
+| `intercept` | Network request interception | GraphQL/XHR capture (Twitter) |
+| `ui` | DOM interaction via accessibility snapshot | Desktop apps, write operations |
 
 ## Directory Structure
 
 ```
 src/
 ├── main.ts              # Entry point
-├── engine.ts            # Command execution engine
+├── cli.ts               # Commander.js CLI setup + built-in commands
+├── commanderAdapter.ts  # Registry → Commander bridge
+├── discovery.ts         # CLI discovery, manifest loading, YAML parsing
+├── execution.ts         # Arg validation, command execution
 ├── registry.ts          # Command registry
-├── browser.ts           # Browser Bridge connection
+├── serialization.ts     # Command serialization helpers
+├── runtime.ts           # Browser session & timeout management
+├── browser/             # Browser Bridge connection
 ├── output.ts            # Output formatting
 ├── doctor.ts            # Diagnostic tool
 ├── pipeline/            # YAML pipeline engine

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackwener/opencli",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "publishConfig": {
     "access": "public"
   },

package/scripts/check-doc-coverage.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# check-doc-coverage.sh — Verify every adapter in src/clis/ has a doc page.
+#
+# Exit codes:
+#   0 — all adapters have docs
+#   1 — at least one adapter is missing documentation
+#
+# Usage:
+#   bash scripts/check-doc-coverage.sh          # report only
+#   bash scripts/check-doc-coverage.sh --strict  # exit 1 on missing docs
+
+set -euo pipefail
+
+STRICT=false
+if [[ "${1:-}" == "--strict" ]]; then
+  STRICT=true
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+SRC_DIR="$ROOT_DIR/src/clis"
+DOCS_DIR="$ROOT_DIR/docs/adapters"
+
+missing=()
+covered=0
+total=0
+
+for adapter_dir in "$SRC_DIR"/*/; do
+  adapter_name="$(basename "$adapter_dir")"
+  total=$((total + 1))
+
+  # Check if doc exists in browser/ or desktop/ subdirectories
+  if [[ -f "$DOCS_DIR/browser/$adapter_name.md" ]] || \
+     [[ -f "$DOCS_DIR/desktop/$adapter_name.md" ]]; then
+    covered=$((covered + 1))
+  else
+    # Handle directory name mismatches (e.g., discord-app -> discord)
+    alt_name="${adapter_name%-app}"
+    if [[ "$alt_name" != "$adapter_name" ]] && \
+       { [[ -f "$DOCS_DIR/browser/$alt_name.md" ]] || \
+         [[ -f "$DOCS_DIR/desktop/$alt_name.md" ]]; }; then
+      covered=$((covered + 1))
+    else
+      missing+=("$adapter_name")
+    fi
+  fi
+done
+
+echo "📊 Doc Coverage: $covered/$total adapters documented"
+echo ""
+
+if [[ ${#missing[@]} -gt 0 ]]; then
+  echo "⚠️  Missing docs for ${#missing[@]} adapter(s):"
+  for name in "${missing[@]}"; do
+    echo "   - $name  →  create docs/adapters/browser/$name.md or docs/adapters/desktop/$name.md"
+  done
+  echo ""
+  if $STRICT; then
+    echo "❌ Doc check failed (--strict mode)."
+    exit 1
+  else
+    echo "💡 Run with --strict to fail CI on missing docs."
+    exit 0
+  fi
+else
+  echo "✅ All adapters have documentation."
+  exit 0
+fi

package/scripts/copy-yaml.cjs

@@ -19,3 +19,10 @@ function walk(src, dst) {
 }
 
 walk('src/clis', 'dist/clis');
+
+// Copy external CLI registry to dist/
+const extSrc = 'src/external-clis.yaml';
+if (existsSync(extSrc)) {
+  mkdirSync('dist', { recursive: true });
+  copyFileSync(extSrc, 'dist/external-clis.yaml');
+}

package/src/browser/cdp.ts

@@ -158,12 +158,17 @@ class CDPPage implements IPage {
   constructor(private bridge: CDPBridge) {}
 
   /** Navigate with proper load event waiting (P1 fix #3) */
-  async goto(url: string): Promise<void> {
+  async goto(url: string, options?: { waitUntil?: 'load' | 'none'; settleMs?: number }): Promise<void> {
     await this.bridge.send('Page.enable');
     const loadPromise = this.bridge.waitForEvent('Page.loadEventFired', 30_000)
       .catch(() => {}); // Don't fail if event times out
     await this.bridge.send('Page.navigate', { url });
     await loadPromise;
+    // Post-load settle: SPA frameworks need extra time to render after load event
+    if (options?.waitUntil !== 'none') {
+      const settleMs = options?.settleMs ?? 1000;
+      await new Promise(resolve => setTimeout(resolve, settleMs));
+    }
   }
 
   async evaluate(js: string): Promise<any> {

package/src/browser/page.ts

@@ -42,7 +42,7 @@ export class Page implements IPage {
     return { workspace: this.workspace };
   }
 
-  async goto(url: string): Promise<void> {
+  async goto(url: string, options?: { waitUntil?: 'load' | 'none'; settleMs?: number }): Promise<void> {
     const result = await sendCommand('navigate', {
       url,
       ...this._workspaceOpt(),
@@ -52,6 +52,12 @@ export class Page implements IPage {
     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 */

package/src/build-manifest.ts

@@ -196,26 +196,29 @@ function scanYaml(filePath: string, site: string): ManifestEntry | null {
   }
 }
 
-function scanTs(filePath: string, site: string): ManifestEntry {
+function scanTs(filePath: string, site: string): ManifestEntry | null {
   // 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: ManifestEntry = {
-    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: ManifestEntry = {
+      site,
+      name: baseName,
+      description: '',
+      strategy: 'cookie',
+      browser: true,
+      args: [],
+      type: 'ts',
+      modulePath: relativePath,
+    };
+
     // Extract description
     const descMatch = src.match(/description\s*:\s*['"`]([^'"`]*)['"`]/);
     if (descMatch) entry.description = descMatch[1];
@@ -244,11 +247,13 @@ function scanTs(filePath: string, site: string): ManifestEntry {
     if (argsBlock) {
       entry.args = parseTsArgsBlock(argsBlock);
     }
-  } catch {
-    // If parsing fails, fall back to empty metadata — module will self-register at runtime
-  }
 
-  return entry;
+    return entry;
+  } catch (err: any) {
+    // If parsing fails, log a warning (matching scanYaml behaviour) and skip the entry.
+    process.stderr.write(`Warning: failed to scan ${filePath}: ${err.message}\n`);
+    return null;
+  }
 }
 
 export function buildManifest(): ManifestEntry[] {
@@ -264,10 +269,11 @@ export function buildManifest(): ManifestEntry[] {
           const entry = scanYaml(filePath, site);
           if (entry) manifest.push(entry);
         } else if (
-          (file.endsWith('.ts') && !file.endsWith('.d.ts') && file !== 'index.ts') ||
-          (file.endsWith('.js') && !file.endsWith('.d.js') && file !== 'index.js')
+          (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')
         ) {
-          manifest.push(scanTs(filePath, site));
+          const entry = scanTs(filePath, site);
+          if (entry) manifest.push(entry);
         }
       }
     }