@jackwener/opencli 1.1.0 → 1.2.0

package/src/explore.ts

@@ -9,10 +9,12 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { DEFAULT_BROWSER_EXPLORE_TIMEOUT, browserSession, runWithTimeout } from './runtime.js';
+import type { IBrowserFactory } from './runtime.js';
 import { VOLATILE_PARAMS, SEARCH_PARAMS, PAGINATION_PARAMS, LIMIT_PARAMS, FIELD_ROLES } from './constants.js';
 import { detectFramework } from './scripts/framework.js';
 import { discoverStores } from './scripts/store.js';
 import { interactFuzz } from './scripts/interact.js';
+import type { IPage } from './types.js';
 
 // ── Site name detection ────────────────────────────────────────────────────
 
@@ -68,7 +70,61 @@ interface InferredCapability {
   name: string; description: string; strategy: string; confidence: number;
   endpoint: string; itemPath: string | null;
   recommendedColumns: string[];
-  recommendedArgs: Array<{ name: string; type: string; required: boolean; default?: any }>;
+  recommendedArgs: Array<{ name: string; type: string; required: boolean; default?: unknown }>;
+  storeHint?: { store: string; action: string };
+}
+
+export interface ExploreManifest {
+  site: string;
+  target_url: string;
+  final_url: string;
+  title: string;
+  framework: Record<string, boolean>;
+  stores: Array<{ type: DiscoveredStore['type']; id: string; actions: string[] }>;
+  top_strategy: string;
+  explored_at?: string;
+}
+
+export interface ExploreAuthSummary {
+  top_strategy: string;
+  indicators: string[];
+  framework: Record<string, boolean>;
+}
+
+export interface ExploreEndpointArtifact {
+  pattern: string;
+  method: string;
+  url: string;
+  status: number | null;
+  contentType: string;
+  score: number;
+  queryParams: string[];
+  itemPath: string | null;
+  itemCount: number;
+  detectedFields: Record<string, string>;
+  authIndicators: string[];
+}
+
+export interface ExploreResult {
+  site: string;
+  target_url: string;
+  final_url: string;
+  title: string;
+  framework: Record<string, boolean>;
+  stores: DiscoveredStore[];
+  top_strategy: string;
+  endpoint_count: number;
+  api_endpoint_count: number;
+  capabilities: InferredCapability[];
+  auth_indicators: string[];
+  out_dir: string;
+}
+
+export interface ExploreBundle {
+  manifest: ExploreManifest;
+  endpoints: ExploreEndpointArtifact[];
+  capabilities: InferredCapability[];
+  auth: ExploreAuthSummary;
 }
 
 /**
@@ -167,7 +223,11 @@ function flattenFields(obj: unknown, prefix: string, maxDepth: number): string[]
   return names;
 }
 
-function scoreEndpoint(ep: { contentType: string; responseAnalysis: any; pattern: string; status: number | null; hasSearchParam: boolean; hasPaginationParam: boolean; hasLimitParam: boolean }): number {
+function isBooleanRecord(value: unknown): value is Record<string, boolean> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function scoreEndpoint(ep: { contentType: string; responseAnalysis: AnalyzedEndpoint['responseAnalysis']; pattern: string; status: number | null; hasSearchParam: boolean; hasPaginationParam: boolean; hasLimitParam: boolean }): number {
   let s = 0;
   if (ep.contentType.includes('json')) s += 10;
   if (ep.responseAnalysis) { s += 5; s += Math.min(ep.responseAnalysis.itemCount, 10); s += Object.keys(ep.responseAnalysis.detectedFields).length * 2; }
@@ -223,17 +283,143 @@ export interface DiscoveredStore {
 
 const INTERACT_FUZZ_JS = interactFuzz.toString();
 
+// ── Analysis helpers (extracted from exploreUrl) ───────────────────────────
+
+/** Filter, deduplicate, and score network endpoints. */
+function analyzeEndpoints(networkEntries: NetworkEntry[]): { analyzed: AnalyzedEndpoint[]; totalCount: number } {
+  const seen = new Map<string, AnalyzedEndpoint>();
+  for (const entry of networkEntries) {
+    if (!entry.url) continue;
+    const ct = entry.contentType.toLowerCase();
+    if (ct.includes('image/') || ct.includes('font/') || ct.includes('css') || ct.includes('javascript') || ct.includes('wasm')) continue;
+    if (entry.status && entry.status >= 400) continue;
+
+    const pattern = urlToPattern(entry.url);
+    const key = `${entry.method}:${pattern}`;
+    if (seen.has(key)) continue;
+
+    const qp: string[] = [];
+    try { new URL(entry.url).searchParams.forEach((_v, k) => { if (!VOLATILE_PARAMS.has(k)) qp.push(k); }); } catch {}
+
+    const ep: AnalyzedEndpoint = {
+      pattern, method: entry.method, url: entry.url, status: entry.status, contentType: ct,
+      queryParams: qp, hasSearchParam: qp.some(p => SEARCH_PARAMS.has(p)),
+      hasPaginationParam: qp.some(p => PAGINATION_PARAMS.has(p)),
+      hasLimitParam: qp.some(p => LIMIT_PARAMS.has(p)),
+      authIndicators: detectAuthIndicators(entry.requestHeaders),
+      responseAnalysis: entry.responseBody ? analyzeResponseBody(entry.responseBody) : null,
+      score: 0,
+    };
+    ep.score = scoreEndpoint(ep);
+    seen.set(key, ep);
+  }
+
+  const analyzed = [...seen.values()].filter(ep => ep.score >= 5).sort((a, b) => b.score - a.score);
+  return { analyzed, totalCount: seen.size };
+}
+
+/** Infer CLI capabilities from analyzed endpoints. */
+function inferCapabilitiesFromEndpoints(
+  endpoints: AnalyzedEndpoint[],
+  stores: DiscoveredStore[],
+  opts: { site?: string; goal?: string; url: string },
+): { capabilities: InferredCapability[]; topStrategy: string; authIndicators: string[] } {
+  const capabilities: InferredCapability[] = [];
+  const usedNames = new Set<string>();
+
+  for (const ep of endpoints.slice(0, 8)) {
+    let capName = inferCapabilityName(ep.url, opts.goal);
+    if (usedNames.has(capName)) {
+      const suffix = ep.pattern.split('/').filter(s => s && !s.startsWith('{') && !s.includes('.')).pop();
+      capName = suffix ? `${capName}_${suffix}` : `${capName}_${usedNames.size}`;
+    }
+    usedNames.add(capName);
+
+    const cols: string[] = [];
+    if (ep.responseAnalysis) {
+      for (const role of ['title', 'url', 'author', 'score', 'time']) {
+        if (ep.responseAnalysis.detectedFields[role]) cols.push(role);
+      }
+    }
+
+    const args: InferredCapability['recommendedArgs'] = [];
+    if (ep.hasSearchParam) args.push({ name: 'keyword', type: 'str', required: true });
+    args.push({ name: 'limit', type: 'int', required: false, default: 20 });
+    if (ep.hasPaginationParam) args.push({ name: 'page', type: 'int', required: false, default: 1 });
+
+    const epStrategy = inferStrategy(ep.authIndicators);
+    let storeHint: { store: string; action: string } | undefined;
+    if ((epStrategy === 'intercept' || ep.authIndicators.includes('signature')) && stores.length > 0) {
+      for (const s of stores) {
+        const matchingAction = s.actions.find(a =>
+          capName.split('_').some(part => a.toLowerCase().includes(part)) ||
+          a.toLowerCase().includes('fetch') || a.toLowerCase().includes('get')
+        );
+        if (matchingAction) { storeHint = { store: s.id, action: matchingAction }; break; }
+      }
+    }
+
+    capabilities.push({
+      name: capName, description: `${opts.site ?? detectSiteName(opts.url)} ${capName}`,
+      strategy: storeHint ? 'store-action' : epStrategy,
+      confidence: Math.min(ep.score / 20, 1.0), endpoint: ep.pattern,
+      itemPath: ep.responseAnalysis?.itemPath ?? null,
+      recommendedColumns: cols.length ? cols : ['title', 'url'],
+      recommendedArgs: args,
+      ...(storeHint ? { storeHint } : {}),
+    });
+  }
+
+  const allAuth = new Set(endpoints.flatMap(ep => ep.authIndicators));
+  const topStrategy = allAuth.has('signature') ? 'intercept'
+    : allAuth.has('bearer') || allAuth.has('csrf') ? 'header'
+    : allAuth.size === 0 ? 'public' : 'cookie';
+
+  return { capabilities, topStrategy, authIndicators: [...allAuth] };
+}
+
+/** Write explore artifacts (manifest, endpoints, capabilities, auth, stores) to disk. */
+async function writeExploreArtifacts(
+  targetDir: string,
+  result: Omit<ExploreResult, 'out_dir'>,
+  analyzedEndpoints: AnalyzedEndpoint[],
+  stores: DiscoveredStore[],
+): Promise<void> {
+  await fs.promises.mkdir(targetDir, { recursive: true });
+  const tasks = [
+    fs.promises.writeFile(path.join(targetDir, 'manifest.json'), JSON.stringify({
+      site: result.site, target_url: result.target_url, final_url: result.final_url, title: result.title,
+      framework: result.framework, stores: stores.map(s => ({ type: s.type, id: s.id, actions: s.actions })),
+      top_strategy: result.top_strategy, explored_at: new Date().toISOString(),
+    }, null, 2)),
+    fs.promises.writeFile(path.join(targetDir, 'endpoints.json'), JSON.stringify(analyzedEndpoints.map(ep => ({
+      pattern: ep.pattern, method: ep.method, url: ep.url, status: ep.status,
+      contentType: ep.contentType, score: ep.score, queryParams: ep.queryParams,
+      itemPath: ep.responseAnalysis?.itemPath ?? null, itemCount: ep.responseAnalysis?.itemCount ?? 0,
+      detectedFields: ep.responseAnalysis?.detectedFields ?? {}, authIndicators: ep.authIndicators,
+    })), null, 2)),
+    fs.promises.writeFile(path.join(targetDir, 'capabilities.json'), JSON.stringify(result.capabilities, null, 2)),
+    fs.promises.writeFile(path.join(targetDir, 'auth.json'), JSON.stringify({
+      top_strategy: result.top_strategy, indicators: result.auth_indicators, framework: result.framework,
+    }, null, 2)),
+  ];
+  if (stores.length > 0) {
+    tasks.push(fs.promises.writeFile(path.join(targetDir, 'stores.json'), JSON.stringify(stores, null, 2)));
+  }
+  await Promise.all(tasks);
+}
+
 // ── Main explore function ──────────────────────────────────────────────────
 
 export async function exploreUrl(
   url: string,
   opts: {
-    BrowserFactory: new () => any;
+    BrowserFactory: new () => IBrowserFactory;
     site?: string; goal?: string; authenticated?: boolean;
     outDir?: string; waitSeconds?: number; query?: string;
     clickLabels?: string[]; auto?: boolean; workspace?: string;
   },
-): Promise<Record<string, any>> {
+): Promise<ExploreResult> {
   const waitSeconds = opts.waitSeconds ?? 3.0;
   const exploreTimeout = Math.max(DEFAULT_BROWSER_EXPLORE_TIMEOUT, 45.0 + waitSeconds * 8.0);
 
@@ -306,7 +492,10 @@ export async function exploreUrl(
 
       // Step 6: Detect framework
       let framework: Record<string, boolean> = {};
-      try { const fw = await page.evaluate(FRAMEWORK_DETECT_JS); if (fw && typeof fw === 'object') framework = fw; } catch {}
+      try {
+        const fw = await page.evaluate(FRAMEWORK_DETECT_JS);
+        if (isBooleanRecord(fw)) framework = fw;
+      } catch {}
 
       // Step 6.5: Discover stores (Pinia / Vuex)
       let stores: DiscoveredStore[] = [];
@@ -317,131 +506,31 @@ export async function exploreUrl(
         } catch {}
       }
 
-      // Step 7: Analyze endpoints
-      const seen = new Map<string, AnalyzedEndpoint>();
-      for (const entry of networkEntries) {
-        if (!entry.url) continue;
-        const ct = entry.contentType.toLowerCase();
-        if (ct.includes('image/') || ct.includes('font/') || ct.includes('css') || ct.includes('javascript') || ct.includes('wasm')) continue;
-        if (entry.status && entry.status >= 400) continue;
-
-        const pattern = urlToPattern(entry.url);
-        const key = `${entry.method}:${pattern}`;
-        if (seen.has(key)) continue;
-
-        const qp: string[] = [];
-        try { new URL(entry.url).searchParams.forEach((_v, k) => { if (!VOLATILE_PARAMS.has(k)) qp.push(k); }); } catch {}
-
-        const ep: AnalyzedEndpoint = {
-          pattern, method: entry.method, url: entry.url, status: entry.status, contentType: ct,
-          queryParams: qp, hasSearchParam: qp.some(p => SEARCH_PARAMS.has(p)),
-          hasPaginationParam: qp.some(p => PAGINATION_PARAMS.has(p)),
-          hasLimitParam: qp.some(p => LIMIT_PARAMS.has(p)),
-          authIndicators: detectAuthIndicators(entry.requestHeaders),
-          responseAnalysis: entry.responseBody ? analyzeResponseBody(entry.responseBody) : null,
-          score: 0,
-        };
-        ep.score = scoreEndpoint(ep);
-        seen.set(key, ep);
-      }
-
-      const analyzedEndpoints = [...seen.values()].filter(ep => ep.score >= 5).sort((a, b) => b.score - a.score);
-
-      // Step 8: Infer capabilities
-      const capabilities: InferredCapability[] = [];
-      const usedNames = new Set<string>();
-      for (const ep of analyzedEndpoints.slice(0, 8)) {
-        let capName = inferCapabilityName(ep.url, opts.goal);
-        if (usedNames.has(capName)) {
-          const suffix = ep.pattern.split('/').filter(s => s && !s.startsWith('{') && !s.includes('.')).pop();
-          capName = suffix ? `${capName}_${suffix}` : `${capName}_${usedNames.size}`;
-        }
-        usedNames.add(capName);
-
-        const cols: string[] = [];
-        if (ep.responseAnalysis) {
-          for (const role of ['title', 'url', 'author', 'score', 'time']) {
-            if (ep.responseAnalysis.detectedFields[role]) cols.push(role);
-          }
-        }
-
-        const args: InferredCapability['recommendedArgs'] = [];
-        if (ep.hasSearchParam) args.push({ name: 'keyword', type: 'str', required: true });
-        args.push({ name: 'limit', type: 'int', required: false, default: 20 });
-        if (ep.hasPaginationParam) args.push({ name: 'page', type: 'int', required: false, default: 1 });
-
-        // Link store actions to capabilities when store-action strategy is recommended
-        const epStrategy = inferStrategy(ep.authIndicators);
-        let storeHint: { store: string; action: string } | undefined;
-        if ((epStrategy === 'intercept' || ep.authIndicators.includes('signature')) && stores.length > 0) {
-          // Try to find a store/action that matches this endpoint's purpose
-          for (const s of stores) {
-            const matchingAction = s.actions.find(a =>
-              capName.split('_').some(part => a.toLowerCase().includes(part)) ||
-              a.toLowerCase().includes('fetch') || a.toLowerCase().includes('get')
-            );
-            if (matchingAction) {
-              storeHint = { store: s.id, action: matchingAction };
-              break;
-            }
-          }
-        }
-
-        capabilities.push({
-          name: capName, description: `${opts.site ?? detectSiteName(url)} ${capName}`,
-          strategy: storeHint ? 'store-action' : epStrategy,
-          confidence: Math.min(ep.score / 20, 1.0), endpoint: ep.pattern,
-          itemPath: ep.responseAnalysis?.itemPath ?? null,
-          recommendedColumns: cols.length ? cols : ['title', 'url'],
-          recommendedArgs: args,
-          ...(storeHint ? { storeHint } : {}),
-        });
-      }
-
-      // Step 9: Determine overall auth strategy
-      const allAuth = new Set(analyzedEndpoints.flatMap(ep => ep.authIndicators));
-      const topStrategy = allAuth.has('signature') ? 'intercept' : allAuth.has('bearer') || allAuth.has('csrf') ? 'header' : allAuth.size === 0 ? 'public' : 'cookie';
+      // Step 7+8: Analyze endpoints and infer capabilities
+      const { analyzed: analyzedEndpoints, totalCount } = analyzeEndpoints(networkEntries);
+      const { capabilities, topStrategy, authIndicators } = inferCapabilitiesFromEndpoints(
+        analyzedEndpoints, stores, { site: opts.site, goal: opts.goal, url },
+      );
 
+      // Step 9: Assemble result and write artifacts
       const siteName = opts.site ?? detectSiteName(metadata.url || url);
       const targetDir = opts.outDir ?? path.join('.opencli', 'explore', siteName);
-      await fs.promises.mkdir(targetDir, { recursive: true });
 
       const result = {
         site: siteName, target_url: url, final_url: metadata.url, title: metadata.title,
         framework, stores, top_strategy: topStrategy,
-        endpoint_count: analyzedEndpoints.length + [...seen.values()].filter(ep => ep.score < 5).length,
+        endpoint_count: totalCount,
         api_endpoint_count: analyzedEndpoints.length,
-        capabilities, auth_indicators: [...allAuth],
+        capabilities, auth_indicators: authIndicators,
       };
 
-      // Write artifacts
-      const writeTasks = [];
-      writeTasks.push(fs.promises.writeFile(path.join(targetDir, 'manifest.json'), JSON.stringify({
-        site: siteName, target_url: url, final_url: metadata.url, title: metadata.title,
-        framework, stores: stores.map(s => ({ type: s.type, id: s.id, actions: s.actions })),
-        top_strategy: topStrategy, explored_at: new Date().toISOString(),
-      }, null, 2)));
-      writeTasks.push(fs.promises.writeFile(path.join(targetDir, 'endpoints.json'), JSON.stringify(analyzedEndpoints.map(ep => ({
-        pattern: ep.pattern, method: ep.method, url: ep.url, status: ep.status,
-        contentType: ep.contentType, score: ep.score, queryParams: ep.queryParams,
-        itemPath: ep.responseAnalysis?.itemPath ?? null, itemCount: ep.responseAnalysis?.itemCount ?? 0,
-        detectedFields: ep.responseAnalysis?.detectedFields ?? {}, authIndicators: ep.authIndicators,
-      })), null, 2)));
-      writeTasks.push(fs.promises.writeFile(path.join(targetDir, 'capabilities.json'), JSON.stringify(capabilities, null, 2)));
-      writeTasks.push(fs.promises.writeFile(path.join(targetDir, 'auth.json'), JSON.stringify({
-        top_strategy: topStrategy, indicators: [...allAuth], framework,
-      }, null, 2)));
-      if (stores.length > 0) {
-        writeTasks.push(fs.promises.writeFile(path.join(targetDir, 'stores.json'), JSON.stringify(stores, null, 2)));
-      }
-      await Promise.all(writeTasks);
-
+      await writeExploreArtifacts(targetDir, result, analyzedEndpoints, stores);
       return { ...result, out_dir: targetDir };
     })(), { timeout: exploreTimeout, label: `Explore ${url}` });
   }, { workspace: opts.workspace });
 }
 
-export function renderExploreSummary(result: Record<string, any>): string {
+export function renderExploreSummary(result: ExploreResult): string {
   const lines = [
     'opencli probe: OK', `Site: ${result.site}`, `URL: ${result.target_url}`,
     `Title: ${result.title || '(none)'}`, `Strategy: ${result.top_strategy}`,
@@ -466,10 +555,15 @@ export function renderExploreSummary(result: Record<string, any>): string {
   return lines.join('\n');
 }
 
-async function readPageMetadata(page: any /* IPage */): Promise<{ url: string; title: string }> {
+async function readPageMetadata(page: IPage): Promise<{ url: string; title: string }> {
   try {
     const result = await page.evaluate(`() => ({ url: window.location.href, title: document.title || '' })`);
-    if (result && typeof result === 'object') return { url: String(result.url ?? ''), title: String(result.title ?? '') };
+    if (result && typeof result === 'object' && !Array.isArray(result)) {
+      return {
+        url: String((result as Record<string, unknown>).url ?? ''),
+        title: String((result as Record<string, unknown>).title ?? ''),
+      };
+    }
   } catch {}
   return { url: '', title: '' };
 }

package/src/external-clis.yaml

@@ -37,3 +37,12 @@
   tags: [docker, containers, devops]
   install:
     mac: "brew install --cask docker"
+
+- name: gws
+  binary: gws
+  description: "Google Workspace CLI — Docs, Sheets, Drive, Gmail, Calendar"
+  homepage: "https://github.com/nicholasgasior/gws"
+  tags: [google, docs, sheets, drive, workspace]
+  install:
+    mac: "brew install gws"
+    default: "npm install -g @nicholasgasior/gws"

package/src/external.ts

@@ -2,7 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import { fileURLToPath } from 'node:url';
-import { spawnSync, execSync } from 'node:child_process';
+import { spawnSync, execSync, execFileSync } from 'node:child_process';
 import yaml from 'js-yaml';
 import chalk from 'chalk';
 import { log } from './logger.js';
@@ -65,8 +65,7 @@ export function loadExternalClis(): ExternalCliConfig[] {
 export function isBinaryInstalled(binary: string): boolean {
   try {
     const isWindows = os.platform() === 'win32';
-    const cmd = isWindows ? 'where' : 'command -v';
-    execSync(`${cmd} ${binary}`, { stdio: 'ignore' });
+    execFileSync(isWindows ? 'where' : 'which', [binary], { stdio: 'ignore' });
     return true;
   } catch {
     return false;
@@ -109,8 +108,8 @@ export function installExternalCli(cli: ExternalCliConfig): boolean {
   }
 }
 
-export async function executeExternalCli(name: string, args: string[]): Promise<void> {
-  const configs = loadExternalClis();
+export function executeExternalCli(name: string, args: string[], preloaded?: ExternalCliConfig[]): void {
+  const configs = preloaded ?? loadExternalClis();
   const cli = configs.find((c) => c.name === name);
   if (!cli) {
     throw new Error(`External CLI '${name}' not found in registry.`);
@@ -126,8 +125,7 @@ export async function executeExternalCli(name: string, args: string[]): Promise<
     }
   }
 
-  // 3. Passthrough execution
-  // We use spawnSync to properly inherit stdio and block until completion
+  // 3. Passthrough execution with stdio inherited
   const result = spawnSync(cli.binary, args, { stdio: 'inherit' });
   if (result.error) {
     console.error(chalk.red(`Failed to execute '${cli.binary}': ${result.error.message}`));
@@ -140,7 +138,13 @@ export async function executeExternalCli(name: string, args: string[]): Promise<
   }
 }
 
-export function registerExternalCli(name: string, binary?: string, install?: string, description?: string): void {
+export interface RegisterOptions {
+  binary?: string;
+  install?: string;
+  description?: string;
+}
+
+export function registerExternalCli(name: string, opts?: RegisterOptions): void {
   const userPath = getUserRegistryPath();
   const configDir = path.dirname(userPath);
 
@@ -162,13 +166,12 @@ export function registerExternalCli(name: string, binary?: string, install?: str
   
   const newItem: ExternalCliConfig = {
     name,
-    binary: binary || name,
+    binary: opts?.binary || name,
   };
-  if (description) newItem.description = description;
-  if (install) newItem.install = { default: install };
+  if (opts?.description) newItem.description = opts.description;
+  if (opts?.install) newItem.install = { default: opts.install };
 
   if (existingIndex >= 0) {
-    // Merge
     items[existingIndex] = { ...items[existingIndex], ...newItem };
     console.log(chalk.green(`Updated '${name}' in user registry.`));
   } else {

package/src/generate.ts

@@ -9,10 +9,59 @@
  */
 
 import { exploreUrl } from './explore.js';
-import { synthesizeFromExplore } from './synthesize.js';
+import type { IBrowserFactory } from './runtime.js';
+import { synthesizeFromExplore, type SynthesizeCandidateSummary, type SynthesizeResult } from './synthesize.js';
 
 // TODO: implement real CLI registration (copy candidate YAML to user clis dir)
-function registerCandidates(_opts: any): any { return { ok: true, count: 0 }; }
+interface RegisterCandidatesOptions {
+  target: string;
+  builtinClis?: string;
+  userClis?: string;
+  name?: string;
+}
+
+interface RegisterCandidatesResult {
+  ok: boolean;
+  count: number;
+}
+
+export interface GenerateCliOptions {
+  url: string;
+  BrowserFactory: new () => IBrowserFactory;
+  builtinClis?: string;
+  userClis?: string;
+  goal?: string | null;
+  site?: string;
+  waitSeconds?: number;
+  top?: number;
+  register?: boolean;
+  workspace?: string;
+}
+
+export interface GenerateCliResult {
+  ok: boolean;
+  goal?: string | null;
+  normalized_goal?: string | null;
+  site: string;
+  selected_candidate: SynthesizeCandidateSummary | null;
+  selected_command: string;
+  explore: {
+    endpoint_count: number;
+    api_endpoint_count: number;
+    capability_count: number;
+    top_strategy: string;
+    framework: Record<string, boolean>;
+  };
+  synthesize: {
+    candidate_count: number;
+    candidates: Array<Pick<SynthesizeCandidateSummary, 'name' | 'strategy' | 'confidence'>>;
+  };
+  register: RegisterCandidatesResult | null;
+}
+
+function registerCandidates(_opts: RegisterCandidatesOptions): RegisterCandidatesResult {
+  return { ok: true, count: 0 };
+}
 
 const CAPABILITY_ALIASES: Record<string, string[]> = {
   search:    ['search', '搜索', '查找', 'query', 'keyword'],
@@ -41,7 +90,7 @@ function normalizeGoal(goal?: string | null): string | null {
 /**
  * Select the best candidate matching the user's goal.
  */
-function selectCandidate(candidates: any[], goal?: string | null): any {
+function selectCandidate(candidates: SynthesizeResult['candidates'], goal?: string | null): SynthesizeCandidateSummary | null {
   if (!candidates.length) return null;
   if (!goal) return candidates[0]; // highest confidence first
 
@@ -58,12 +107,12 @@ function selectCandidate(candidates: any[], goal?: string | null): any {
   return partial ?? candidates[0];
 }
 
-export async function generateCliFromUrl(opts: any): Promise<any> {
+export async function generateCliFromUrl(opts: GenerateCliOptions): Promise<GenerateCliResult> {
   // Step 1: Deep Explore
   const exploreResult = await exploreUrl(opts.url, {
     BrowserFactory: opts.BrowserFactory,
     site: opts.site,
-    goal: normalizeGoal(opts.goal) ?? opts.goal,
+    goal: normalizeGoal(opts.goal) ?? opts.goal ?? undefined,
     waitSeconds: opts.waitSeconds ?? 3,
     workspace: opts.workspace,
   });
@@ -75,10 +124,10 @@ export async function generateCliFromUrl(opts: any): Promise<any> {
 
   // Step 3: Select best candidate for goal
   const selected = selectCandidate(synthesizeResult.candidates ?? [], opts.goal);
-  const selectedSite = selected?.site ?? synthesizeResult.site ?? exploreResult.site;
+  const selectedSite = synthesizeResult.site ?? exploreResult.site;
 
   // Step 4: Register (if requested)
-  let registerResult: any = null;
+  let registerResult: RegisterCandidatesResult | null = null;
   if (opts.register !== false && synthesizeResult.candidate_count > 0) {
     try {
       registerResult = registerCandidates({
@@ -108,7 +157,7 @@ export async function generateCliFromUrl(opts: any): Promise<any> {
     },
     synthesize: {
       candidate_count: synthesizeResult.candidate_count,
-      candidates: (synthesizeResult.candidates ?? []).map((c: any) => ({
+      candidates: (synthesizeResult.candidates ?? []).map((c) => ({
         name: c.name,
         strategy: c.strategy,
         confidence: c.confidence,
@@ -118,7 +167,7 @@ export async function generateCliFromUrl(opts: any): Promise<any> {
   };
 }
 
-export function renderGenerateSummary(r: any): string {
+export function renderGenerateSummary(r: GenerateCliResult): string {
   const lines = [
     `opencli generate: ${r.ok ? 'OK' : 'FAIL'}`,
     `Site: ${r.site}`,

package/src/main.ts

@@ -6,7 +6,7 @@
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { discoverClis } from './engine.js';
+import { discoverClis, discoverPlugins } from './discovery.js';
 import { getCompletions } from './completion.js';
 import { runCli } from './cli.js';
 
@@ -16,6 +16,7 @@ const BUILTIN_CLIS = path.resolve(__dirname, 'clis');
 const USER_CLIS = path.join(os.homedir(), '.opencli', 'clis');
 
 await discoverClis(BUILTIN_CLIS, USER_CLIS);
+await discoverPlugins();
 
 // ── Fast-path: handle --get-completions before commander parses ─────────
 // Usage: opencli --get-completions --cursor <N> [word1 word2 ...]