@jackwener/opencli 1.1.0 → 1.2.0

package/src/plugin.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Tests for plugin management: install, uninstall, list.
+ */
+
+import { describe, it, expect, beforeEach, 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/src/plugin.ts

@@ -0,0 +1,254 @@
+/**
+ * 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';
+
+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 function installPlugin(source: string): string {
+  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: any) {
+    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: string): void {
+  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(): PluginInfo[] {
+  if (!fs.existsSync(PLUGINS_DIR)) return [];
+
+  const entries = fs.readdirSync(PLUGINS_DIR, { withFileTypes: true });
+  const plugins: PluginInfo[] = [];
+
+  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: string): string[] {
+  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: string): string | undefined {
+  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: string): { cloneUrl: string; name: string } | null {
+  // 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: string): void {
+  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: any) {
+    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: string): void {
+  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: any) {
+        log.warn(`Failed to transpile ${tsFile}: ${err.message}`);
+      }
+    }
+  } catch {
+    // Non-fatal: skip transpilation if anything goes wrong
+  }
+}
+
+export { parseSource as _parseSource };

package/src/registry-api.ts

@@ -0,0 +1,12 @@
+/**
+ * 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/src/registry.ts

@@ -36,6 +36,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) */
@@ -49,7 +60,13 @@ export interface CliOptions extends Partial<Omit<CliCommand, 'args' | 'descripti
   description?: string;
   args?: Arg[];
 }
-const _registry = new Map<string, CliCommand>();
+
+// 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: Map<string, CliCommand> =
+  (globalThis as any)[REGISTRY_KEY] ??= new Map<string, CliCommand>();
 
 export function cli(opts: CliOptions): CliCommand {
   const strategy = opts.strategy ?? (opts.browser === false ? Strategy.PUBLIC : Strategy.COOKIE);
@@ -67,6 +84,7 @@ export function cli(opts: CliOptions): CliCommand {
     pipeline: opts.pipeline,
     timeoutSeconds: opts.timeoutSeconds,
     footerExtra: opts.footerExtra,
+    navigateBefore: opts.navigateBefore,
   };
 
   const key = fullName(cmd);
@@ -89,3 +107,8 @@ export function strategyLabel(cmd: CliCommand): string {
 export function registerCommand(cmd: CliCommand): void {
   _registry.set(fullName(cmd), cmd);
 }
+
+// Re-export serialization helpers from their dedicated module
+export { serializeArg, serializeCommand, formatArgSummary, formatRegistryHelpText } from './serialization.js';
+export type { SerializedArg } from './serialization.js';
+

package/src/runtime.ts

@@ -1,5 +1,14 @@
+import { BrowserBridge, CDPBridge } from './browser/index.js';
 import type { IPage } from './types.js';
 
+/**
+ * Returns the appropriate browser factory based on environment config.
+ * Uses CDPBridge when OPENCLI_CDP_ENDPOINT is set, otherwise BrowserBridge.
+ */
+export function getBrowserFactory(): new () => IBrowserFactory {
+  return (process.env.OPENCLI_CDP_ENDPOINT ? CDPBridge : BrowserBridge) as any;
+}
+
 export const DEFAULT_BROWSER_CONNECT_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_CONNECT_TIMEOUT ?? '30', 10);
 export const DEFAULT_BROWSER_COMMAND_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_COMMAND_TIMEOUT ?? '60', 10);
 export const DEFAULT_BROWSER_EXPLORE_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_EXPLORE_TIMEOUT ?? '120', 10);

package/src/serialization.ts

@@ -0,0 +1,79 @@
+/**
+ * Serialization and formatting helpers for CLI commands and args.
+ *
+ * Used by the `list` command, Commander --help, and build-manifest.
+ * Separated from registry.ts to keep the registry focused on types + registration.
+ */
+
+import type { Arg, CliCommand } from './registry.js';
+import { fullName, strategyLabel } from './registry.js';
+
+// ── Serialization ───────────────────────────────────────────────────────────
+
+export type SerializedArg = {
+  name: string;
+  type: string;
+  required: boolean;
+  positional: boolean;
+  choices: string[];
+  default: unknown;
+  help: string;
+};
+
+/** Stable arg schema — every field is always present (no sparse objects). */
+export function serializeArg(a: Arg): SerializedArg {
+  return {
+    name: a.name,
+    type: a.type ?? 'string',
+    required: !!a.required,
+    positional: !!a.positional,
+    choices: a.choices ?? [],
+    default: a.default ?? null,
+    help: a.help ?? '',
+  };
+}
+
+/** Full command metadata for structured output (json/yaml). */
+export function serializeCommand(cmd: CliCommand) {
+  return {
+    command: fullName(cmd),
+    site: cmd.site,
+    name: cmd.name,
+    description: cmd.description,
+    strategy: strategyLabel(cmd),
+    browser: !!cmd.browser,
+    args: cmd.args.map(serializeArg),
+    columns: cmd.columns ?? [],
+    domain: cmd.domain ?? null,
+  };
+}
+
+// ── Formatting ──────────────────────────────────────────────────────────────
+
+/** Human-readable arg summary: `<required> [optional]` style. */
+export function formatArgSummary(args: Arg[]): string {
+  return args
+    .map(a => {
+      if (a.positional) return a.required ? `<${a.name}>` : `[${a.name}]`;
+      return a.required ? `--${a.name}` : `[--${a.name}]`;
+    })
+    .join(' ');
+}
+
+/** Generate the --help appendix showing registry metadata not exposed by Commander. */
+export function formatRegistryHelpText(cmd: CliCommand): string {
+  const lines: string[] = [];
+  const choicesArgs = cmd.args.filter(a => a.choices?.length);
+  for (const a of choicesArgs) {
+    const prefix = a.positional ? `<${a.name}>` : `--${a.name}`;
+    const def = a.default != null ? `  (default: ${a.default})` : '';
+    lines.push(`  ${prefix}: ${a.choices!.join(', ')}${def}`);
+  }
+  const meta: string[] = [];
+  meta.push(`Strategy: ${strategyLabel(cmd)}`);
+  meta.push(`Browser: ${cmd.browser ? 'yes' : 'no'}`);
+  if (cmd.domain) meta.push(`Domain: ${cmd.domain}`);
+  lines.push(meta.join(' | '));
+  if (cmd.columns?.length) lines.push(`Output columns: ${cmd.columns.join(', ')}`);
+  return '\n' + lines.join('\n') + '\n';
+}