@jackwener/opencli 1.1.1 → 1.2.0

package/dist/plugin.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Plugin management: install, uninstall, and list plugins.
+ *
+ * Plugins live in ~/.opencli/plugins/<name>/.
+ * Install source format: "github:user/repo"
+ */
+export interface PluginInfo {
+    name: string;
+    path: string;
+    commands: string[];
+    source?: string;
+}
+/**
+ * Install a plugin from a source.
+ * Currently supports "github:user/repo" format (git clone wrapper).
+ */
+export declare function installPlugin(source: string): string;
+/**
+ * Uninstall a plugin by name.
+ */
+export declare function uninstallPlugin(name: string): void;
+/**
+ * List all installed plugins.
+ */
+export declare function listPlugins(): PluginInfo[];
+/** Parse a plugin source string into clone URL and name */
+declare function parseSource(source: string): {
+    cloneUrl: string;
+    name: string;
+} | null;
+export { parseSource as _parseSource };

package/dist/plugin.js

@@ -0,0 +1,216 @@
+/**
+ * Plugin management: install, uninstall, and list plugins.
+ *
+ * Plugins live in ~/.opencli/plugins/<name>/.
+ * Install source format: "github:user/repo"
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execSync, execFileSync } from 'node:child_process';
+import { PLUGINS_DIR } from './discovery.js';
+import { log } from './logger.js';
+/**
+ * Install a plugin from a source.
+ * Currently supports "github:user/repo" format (git clone wrapper).
+ */
+export function installPlugin(source) {
+    const parsed = parseSource(source);
+    if (!parsed) {
+        throw new Error(`Invalid plugin source: "${source}"\n` +
+            `Supported formats:\n` +
+            `  github:user/repo\n` +
+            `  https://github.com/user/repo`);
+    }
+    const { cloneUrl, name } = parsed;
+    const targetDir = path.join(PLUGINS_DIR, name);
+    if (fs.existsSync(targetDir)) {
+        throw new Error(`Plugin "${name}" is already installed at ${targetDir}`);
+    }
+    // Ensure plugins directory exists
+    fs.mkdirSync(PLUGINS_DIR, { recursive: true });
+    try {
+        execFileSync('git', ['clone', '--depth', '1', cloneUrl, targetDir], {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        throw new Error(`Failed to clone plugin: ${err.message}`);
+    }
+    // If the plugin has a package.json, run npm install for regular deps,
+    // then symlink the host opencli into node_modules for peerDep resolution.
+    const pkgJsonPath = path.join(targetDir, 'package.json');
+    if (fs.existsSync(pkgJsonPath)) {
+        try {
+            execFileSync('npm', ['install', '--omit=dev'], {
+                cwd: targetDir,
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        catch {
+            // Non-fatal: npm install may fail if no real deps
+        }
+        // Symlink host opencli into plugin's node_modules so TS plugins
+        // can resolve '@jackwener/opencli/registry' against the running host.
+        // This is more reliable than depending on the npm-published version
+        // which may lag behind the local installation.
+        linkHostOpencli(targetDir);
+        // Transpile TS plugin files to JS so they work in production mode
+        // (node cannot load .ts files directly without tsx).
+        transpilePluginTs(targetDir);
+    }
+    return name;
+}
+/**
+ * Uninstall a plugin by name.
+ */
+export function uninstallPlugin(name) {
+    const targetDir = path.join(PLUGINS_DIR, name);
+    if (!fs.existsSync(targetDir)) {
+        throw new Error(`Plugin "${name}" is not installed.`);
+    }
+    fs.rmSync(targetDir, { recursive: true, force: true });
+}
+/**
+ * List all installed plugins.
+ */
+export function listPlugins() {
+    if (!fs.existsSync(PLUGINS_DIR))
+        return [];
+    const entries = fs.readdirSync(PLUGINS_DIR, { withFileTypes: true });
+    const plugins = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const pluginDir = path.join(PLUGINS_DIR, entry.name);
+        const commands = scanPluginCommands(pluginDir);
+        const source = getPluginSource(pluginDir);
+        plugins.push({
+            name: entry.name,
+            path: pluginDir,
+            commands,
+            source,
+        });
+    }
+    return plugins;
+}
+/** Scan a plugin directory for command files */
+function scanPluginCommands(dir) {
+    try {
+        const files = fs.readdirSync(dir);
+        const names = new Set(files
+            .filter(f => f.endsWith('.yaml') || f.endsWith('.yml') ||
+            (f.endsWith('.ts') && !f.endsWith('.d.ts') && !f.endsWith('.test.ts')) ||
+            (f.endsWith('.js') && !f.endsWith('.d.js')))
+            .map(f => path.basename(f, path.extname(f))));
+        return [...names];
+    }
+    catch {
+        return [];
+    }
+}
+/** Get git remote origin URL */
+function getPluginSource(dir) {
+    try {
+        return execSync('git config --get remote.origin.url', {
+            cwd: dir,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Parse a plugin source string into clone URL and name */
+function parseSource(source) {
+    // github:user/repo
+    const githubMatch = source.match(/^github:([\w.-]+)\/([\w.-]+)$/);
+    if (githubMatch) {
+        const [, user, repo] = githubMatch;
+        const name = repo.replace(/^opencli-plugin-/, '');
+        return {
+            cloneUrl: `https://github.com/${user}/${repo}.git`,
+            name,
+        };
+    }
+    // https://github.com/user/repo (or .git)
+    const urlMatch = source.match(/^https?:\/\/github\.com\/([\w.-]+)\/([\w.-]+?)(?:\.git)?$/);
+    if (urlMatch) {
+        const [, user, repo] = urlMatch;
+        const name = repo.replace(/^opencli-plugin-/, '');
+        return {
+            cloneUrl: `https://github.com/${user}/${repo}.git`,
+            name,
+        };
+    }
+    return null;
+}
+/**
+ * Symlink the host opencli package into a plugin's node_modules.
+ * This ensures TS plugins resolve '@jackwener/opencli/registry' against
+ * the running host installation rather than a stale npm-published version.
+ */
+function linkHostOpencli(pluginDir) {
+    try {
+        // Determine the host opencli package root from this module's location.
+        // Both dev (tsx src/plugin.ts) and prod (node dist/plugin.js) are one level
+        // deep, so path.dirname + '..' always gives us the package root.
+        const thisFile = new URL(import.meta.url).pathname;
+        const hostRoot = path.resolve(path.dirname(thisFile), '..');
+        const targetLink = path.join(pluginDir, 'node_modules', '@jackwener', 'opencli');
+        // Remove existing (npm-installed copy or stale symlink)
+        if (fs.existsSync(targetLink)) {
+            fs.rmSync(targetLink, { recursive: true, force: true });
+        }
+        // Ensure parent directory exists
+        fs.mkdirSync(path.dirname(targetLink), { recursive: true });
+        // Create symlink
+        fs.symlinkSync(hostRoot, targetLink, 'dir');
+        log.debug(`Linked host opencli into plugin: ${targetLink} → ${hostRoot}`);
+    }
+    catch (err) {
+        log.warn(`Failed to link host opencli into plugin: ${err.message}`);
+    }
+}
+/**
+ * Transpile TS plugin files to JS so they work in production mode.
+ * Uses esbuild from the host opencli's node_modules for fast single-file transpilation.
+ */
+function transpilePluginTs(pluginDir) {
+    try {
+        // Resolve esbuild binary from the host opencli's node_modules
+        const thisFile = new URL(import.meta.url).pathname;
+        const hostRoot = path.resolve(path.dirname(thisFile), '..');
+        const esbuildBin = path.join(hostRoot, 'node_modules', '.bin', 'esbuild');
+        if (!fs.existsSync(esbuildBin)) {
+            log.debug('esbuild not found in host node_modules, skipping TS transpilation');
+            return;
+        }
+        const files = fs.readdirSync(pluginDir);
+        const tsFiles = files.filter(f => f.endsWith('.ts') && !f.endsWith('.d.ts') && !f.endsWith('.test.ts'));
+        for (const tsFile of tsFiles) {
+            const jsFile = tsFile.replace(/\.ts$/, '.js');
+            const jsPath = path.join(pluginDir, jsFile);
+            // Skip if .js already exists (plugin may ship pre-compiled)
+            if (fs.existsSync(jsPath))
+                continue;
+            try {
+                execFileSync(esbuildBin, [tsFile, `--outfile=${jsFile}`, '--format=esm', '--platform=node'], {
+                    cwd: pluginDir,
+                    encoding: 'utf-8',
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+                log.debug(`Transpiled plugin file: ${tsFile} → ${jsFile}`);
+            }
+            catch (err) {
+                log.warn(`Failed to transpile ${tsFile}: ${err.message}`);
+            }
+        }
+    }
+    catch {
+        // Non-fatal: skip transpilation if anything goes wrong
+    }
+}
+export { parseSource as _parseSource };

package/dist/plugin.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for plugin management: install, uninstall, list.
+ */
+export {};

package/dist/plugin.test.js

@@ -0,0 +1,76 @@
+/**
+ * Tests for plugin management: install, uninstall, list.
+ */
+import { describe, it, expect, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { PLUGINS_DIR } from './discovery.js';
+import { listPlugins, uninstallPlugin, _parseSource } from './plugin.js';
+describe('parseSource', () => {
+    it('parses github:user/repo format', () => {
+        const result = _parseSource('github:ByteYue/opencli-plugin-github-trending');
+        expect(result).toEqual({
+            cloneUrl: 'https://github.com/ByteYue/opencli-plugin-github-trending.git',
+            name: 'github-trending',
+        });
+    });
+    it('parses https URL format', () => {
+        const result = _parseSource('https://github.com/ByteYue/opencli-plugin-hot-digest');
+        expect(result).toEqual({
+            cloneUrl: 'https://github.com/ByteYue/opencli-plugin-hot-digest.git',
+            name: 'hot-digest',
+        });
+    });
+    it('strips opencli-plugin- prefix from name', () => {
+        const result = _parseSource('github:user/opencli-plugin-my-tool');
+        expect(result.name).toBe('my-tool');
+    });
+    it('keeps name without prefix', () => {
+        const result = _parseSource('github:user/awesome-cli');
+        expect(result.name).toBe('awesome-cli');
+    });
+    it('returns null for invalid source', () => {
+        expect(_parseSource('invalid')).toBeNull();
+        expect(_parseSource('npm:some-package')).toBeNull();
+    });
+});
+describe('listPlugins', () => {
+    const testDir = path.join(PLUGINS_DIR, '__test-list-plugin__');
+    afterEach(() => {
+        try {
+            fs.rmSync(testDir, { recursive: true });
+        }
+        catch { }
+    });
+    it('lists installed plugins', () => {
+        fs.mkdirSync(testDir, { recursive: true });
+        fs.writeFileSync(path.join(testDir, 'hello.yaml'), 'site: test\nname: hello\n');
+        const plugins = listPlugins();
+        const found = plugins.find(p => p.name === '__test-list-plugin__');
+        expect(found).toBeDefined();
+        expect(found.commands).toContain('hello');
+    });
+    it('returns empty array when no plugins dir', () => {
+        // listPlugins should handle missing dir gracefully
+        const plugins = listPlugins();
+        expect(Array.isArray(plugins)).toBe(true);
+    });
+});
+describe('uninstallPlugin', () => {
+    const testDir = path.join(PLUGINS_DIR, '__test-uninstall__');
+    afterEach(() => {
+        try {
+            fs.rmSync(testDir, { recursive: true });
+        }
+        catch { }
+    });
+    it('removes plugin directory', () => {
+        fs.mkdirSync(testDir, { recursive: true });
+        fs.writeFileSync(path.join(testDir, 'test.yaml'), 'site: test');
+        uninstallPlugin('__test-uninstall__');
+        expect(fs.existsSync(testDir)).toBe(false);
+    });
+    it('throws for non-existent plugin', () => {
+        expect(() => uninstallPlugin('__nonexistent__')).toThrow('not installed');
+    });
+});

package/dist/registry-api.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Public API for opencli plugins.
+ *
+ * TS plugins should import from '@jackwener/opencli/registry' which resolves to
+ * this file. It re-exports ONLY the core registration API — no serialization,
+ * no transitive side-effects — to avoid circular dependency deadlocks when
+ * plugins are dynamically imported during discoverPlugins().
+ */
+export { cli, Strategy, getRegistry, fullName, registerCommand } from './registry.js';
+export type { CliCommand, Arg, CliOptions } from './registry.js';
+export type { IPage } from './types.js';

package/dist/registry-api.js

@@ -0,0 +1,9 @@
+/**
+ * Public API for opencli plugins.
+ *
+ * TS plugins should import from '@jackwener/opencli/registry' which resolves to
+ * this file. It re-exports ONLY the core registration API — no serialization,
+ * no transitive side-effects — to avoid circular dependency deadlocks when
+ * plugins are dynamically imported during discoverPlugins().
+ */
+export { cli, Strategy, getRegistry, fullName, registerCommand } from './registry.js';

package/dist/registry.d.ts

@@ -32,6 +32,17 @@ export interface CliCommand {
     timeoutSeconds?: number;
     source?: string;
     footerExtra?: (kwargs: Record<string, any>) => string | undefined;
+    /**
+     * Control pre-navigation for cookie/header context before command execution.
+     *
+     * Browser adapters using COOKIE/HEADER strategy need the page to be on the
+     * target domain so that `fetch(url, { credentials: 'include' })` carries cookies.
+     *
+     * - `undefined` / `true`: navigate to `https://${domain}` (default)
+     * - `false`: skip — adapter handles its own navigation (e.g. boss common.ts)
+     * - `string`: navigate to this specific URL instead of the domain root
+     */
+    navigateBefore?: boolean | string;
 }
 /** Internal extension for lazy-loaded TS modules (not exposed in public API) */
 export interface InternalCliCommand extends CliCommand {

package/dist/registry.js

@@ -9,7 +9,11 @@ export var Strategy;
     Strategy["INTERCEPT"] = "intercept";
     Strategy["UI"] = "ui";
 })(Strategy || (Strategy = {}));
-const _registry = new Map();
+// Use globalThis to ensure a single shared registry across all module instances.
+// This is critical for TS plugins loaded via npm link / peerDependency — without
+// this, the plugin's import creates a separate module instance with its own Map.
+const REGISTRY_KEY = '__opencli_registry__';
+const _registry = globalThis[REGISTRY_KEY] ??= new Map();
 export function cli(opts) {
     const strategy = opts.strategy ?? (opts.browser === false ? Strategy.PUBLIC : Strategy.COOKIE);
     const browser = opts.browser ?? (strategy !== Strategy.PUBLIC);
@@ -26,6 +30,7 @@ export function cli(opts) {
         pipeline: opts.pipeline,
         timeoutSeconds: opts.timeoutSeconds,
         footerExtra: opts.footerExtra,
+        navigateBefore: opts.navigateBefore,
     };
     const key = fullName(cmd);
     _registry.set(key, cmd);

package/dist/synthesize.d.ts

@@ -2,12 +2,102 @@
  * Synthesize candidate CLIs from explore artifacts.
  * Generates evaluate-based YAML pipelines (matching hand-written adapter patterns).
  */
+import type { ExploreAuthSummary, ExploreEndpointArtifact, ExploreManifest } from './explore.js';
+interface RecommendedArg {
+    name: string;
+    type?: string;
+    required?: boolean;
+    default?: unknown;
+}
+interface StoreHint {
+    store: string;
+    action: string;
+}
+export interface SynthesizeCapability {
+    name: string;
+    description: string;
+    strategy: string;
+    confidence?: number;
+    endpoint?: string;
+    itemPath?: string | null;
+    recommendedColumns?: string[];
+    recommendedArgs?: RecommendedArg[];
+    recommended_args?: RecommendedArg[];
+    recommendedColumnsLegacy?: string[];
+    recommended_columns?: string[];
+    storeHint?: StoreHint;
+}
+export interface GeneratedArgDefinition {
+    type: string;
+    required?: boolean;
+    default?: unknown;
+    description?: string;
+}
+type CandidatePipelineStep = {
+    navigate: string;
+} | {
+    wait: number;
+} | {
+    evaluate: string;
+} | {
+    select: string;
+} | {
+    map: Record<string, string>;
+} | {
+    limit: string;
+} | {
+    fetch: {
+        url: string;
+    };
+} | {
+    tap: {
+        store: string;
+        action: string;
+        timeout: number;
+        capture?: string;
+        select?: string | null;
+    };
+};
+export interface CandidateYaml {
+    site: string;
+    name: string;
+    description: string;
+    domain: string;
+    strategy: string;
+    browser: boolean;
+    args: Record<string, GeneratedArgDefinition>;
+    pipeline: CandidatePipelineStep[];
+    columns: string[];
+}
+export interface SynthesizeCandidateSummary {
+    name: string;
+    path: string;
+    strategy: string;
+    confidence?: number;
+}
+export interface SynthesizeResult {
+    site: string;
+    explore_dir: string;
+    out_dir: string;
+    candidate_count: number;
+    candidates: SynthesizeCandidateSummary[];
+}
+interface LoadedExploreBundle {
+    manifest: ExploreManifest;
+    endpoints: ExploreEndpointArtifact[];
+    capabilities: SynthesizeCapability[];
+    auth: ExploreAuthSummary;
+}
 export declare function synthesizeFromExplore(target: string, opts?: {
     outDir?: string;
     top?: number;
-}): Record<string, any>;
-export declare function renderSynthesizeSummary(result: Record<string, any>): string;
+}): SynthesizeResult;
+export declare function renderSynthesizeSummary(result: SynthesizeResult): string;
 export declare function resolveExploreDir(target: string): string;
-export declare function loadExploreBundle(exploreDir: string): Record<string, any>;
+export declare function loadExploreBundle(exploreDir: string): LoadedExploreBundle;
 /** Backward-compatible export for scaffold.ts */
-export declare function buildCandidate(site: string, targetUrl: string, cap: any, endpoint: any): any;
+export declare function buildCandidate(site: string, targetUrl: string, cap: SynthesizeCapability, endpoint: ExploreEndpointArtifact): {
+    name: string;
+    yaml: CandidateYaml;
+};
+export {};

package/dist/synthesize.js

@@ -60,11 +60,12 @@ function chooseEndpoint(cap, endpoints) {
         return null;
     // Match by endpoint pattern from capability
     if (cap.endpoint) {
-        const match = endpoints.find((e) => e.pattern === cap.endpoint || e.url?.includes(cap.endpoint));
+        const endpointPattern = cap.endpoint;
+        const match = endpoints.find((endpoint) => endpoint.pattern === endpointPattern || endpoint.url?.includes(endpointPattern));
         if (match)
             return match;
     }
-    return endpoints.sort((a, b) => (b.score ?? 0) - (a.score ?? 0))[0];
+    return [...endpoints].sort((a, b) => (b.score ?? 0) - (a.score ?? 0))[0];
 }
 // ── URL templating ─────────────────────────────────────────────────────────
 function buildTemplatedUrl(rawUrl, cap, _endpoint) {
@@ -72,7 +73,7 @@ function buildTemplatedUrl(rawUrl, cap, _endpoint) {
         const u = new URL(rawUrl);
         const base = `${u.protocol}//${u.host}${u.pathname}`;
         const params = [];
-        const hasKeyword = cap.recommendedArgs?.some((a) => a.name === 'keyword');
+        const hasKeyword = cap.recommendedArgs?.some((arg) => arg.name === 'keyword');
         u.searchParams.forEach((v, k) => {
             if (VOLATILE_PARAMS.has(k))
                 return;
@@ -166,7 +167,7 @@ function buildCandidateYaml(site, manifest, cap, endpoint) {
     // Map fields
     const mapStep = {};
     const columns = cap.recommendedColumns ?? ['title', 'url'];
-    if (!cap.recommendedArgs?.some((a) => a.name === 'keyword'))
+    if (!cap.recommendedArgs?.some((arg) => arg.name === 'keyword'))
         mapStep['rank'] = '${{ index + 1 }}';
     const detectedFields = endpoint?.detectedFields ?? {};
     for (const col of columns) {

package/dist/types.d.ts

@@ -4,6 +4,39 @@
  * All pipeline steps and CLI adapters should use this interface
  * instead of `any` for browser interactions.
  */
+export interface BrowserCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    expirationDate?: number;
+}
+export interface SnapshotOptions {
+    interactive?: boolean;
+    compact?: boolean;
+    maxDepth?: number;
+    raw?: boolean;
+    viewportExpand?: number;
+    maxTextLength?: number;
+}
+export interface WaitOptions {
+    text?: string;
+    time?: number;
+    timeout?: number;
+}
+export interface ScreenshotOptions {
+    format?: 'png' | 'jpeg';
+    quality?: number;
+    fullPage?: boolean;
+    path?: string;
+}
+export interface BrowserSessionInfo {
+    workspace?: string;
+    connected?: boolean;
+    [key: string]: unknown;
+}
 export interface IPage {
     goto(url: string, options?: {
         waitUntil?: 'load' | 'none';
@@ -13,29 +46,14 @@ export interface IPage {
     getCookies(opts?: {
         domain?: string;
         url?: string;
-    }): Promise<Array<{
-        name: string;
-        value: string;
-        domain: string;
-        path?: string;
-        secure?: boolean;
-        httpOnly?: boolean;
-        expirationDate?: number;
-    }>>;
-    snapshot(opts?: {
-        interactive?: boolean;
-        compact?: boolean;
-        maxDepth?: number;
-        raw?: boolean;
-    }): Promise<any>;
+    }): Promise<BrowserCookie[]>;
+    snapshot(opts?: SnapshotOptions): Promise<any>;
     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>;
+    scrollTo(ref: string): Promise<any>;
+    getFormState(): Promise<any>;
+    wait(options: number | WaitOptions): Promise<void>;
     tabs(): Promise<any>;
     closeTab(index?: number): Promise<void>;
     newTab(): Promise<void>;
@@ -49,10 +67,5 @@ export interface IPage {
     }): Promise<void>;
     installInterceptor(pattern: string): Promise<void>;
     getInterceptedRequests(): Promise<any[]>;
-    screenshot(options?: {
-        format?: 'png' | 'jpeg';
-        quality?: number;
-        fullPage?: boolean;
-        path?: string;
-    }): Promise<string>;
+    screenshot(options?: ScreenshotOptions): Promise<string>;
 }

package/dist/validate.js

@@ -9,6 +9,12 @@ const KNOWN_STEP_NAMES = new Set([
     'select', 'map', 'filter', 'sort', 'limit',
     'intercept', 'tap',
 ]);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 export function validateClisWithTarget(dirs, target) {
     const results = [];
     let errors = 0;
@@ -45,7 +51,7 @@ function validateYamlFile(filePath) {
     try {
         const raw = fs.readFileSync(filePath, 'utf-8');
         const def = yaml.load(raw);
-        if (!def || typeof def !== 'object') {
+        if (!isRecord(def)) {
             errors.push('Not a valid YAML object');
             return { path: filePath, errors, warnings };
         }
@@ -75,7 +81,7 @@ function validateYamlFile(filePath) {
         }
     }
     catch (e) {
-        errors.push(`YAML parse error: ${e.message}`);
+        errors.push(`YAML parse error: ${getErrorMessage(e)}`);
     }
     return { path: filePath, errors, warnings };
 }