@jackwener/opencli 1.5.0 → 1.5.1

package/src/engine.test.ts

@@ -83,9 +83,15 @@ cli({
 describe('discoverPlugins', () => {
   const testPluginDir = path.join(PLUGINS_DIR, '__test-plugin__');
   const yamlPath = path.join(testPluginDir, 'greeting.yaml');
+  const symlinkTargetDir = path.join(os.tmpdir(), '__test-plugin-symlink-target__');
+  const symlinkPluginDir = path.join(PLUGINS_DIR, '__test-plugin-symlink__');
+  const brokenSymlinkDir = path.join(PLUGINS_DIR, '__test-plugin-broken__');
 
   afterEach(async () => {
     try { await fs.promises.rm(testPluginDir, { recursive: true }); } catch {}
+    try { await fs.promises.rm(symlinkPluginDir, { recursive: true, force: true }); } catch {}
+    try { await fs.promises.rm(symlinkTargetDir, { recursive: true, force: true }); } catch {}
+    try { await fs.promises.rm(brokenSymlinkDir, { recursive: true, force: true }); } catch {}
   });
 
   it('discovers YAML plugins from ~/.opencli/plugins/', async () => {
@@ -118,6 +124,38 @@ columns: [message]
     // discoverPlugins should not throw if ~/.opencli/plugins/ does not exist
     await expect(discoverPlugins()).resolves.not.toThrow();
   });
+
+  it('discovers YAML plugins from symlinked plugin directories', async () => {
+    await fs.promises.mkdir(PLUGINS_DIR, { recursive: true });
+    await fs.promises.mkdir(symlinkTargetDir, { recursive: true });
+    await fs.promises.writeFile(path.join(symlinkTargetDir, 'hello.yaml'), `
+site: __test-plugin-symlink__
+name: hello
+description: Test plugin greeting via symlink
+strategy: public
+browser: false
+
+pipeline:
+  - evaluate: "() => [{ message: 'hello from symlink plugin' }]"
+
+columns: [message]
+`);
+    await fs.promises.symlink(symlinkTargetDir, symlinkPluginDir, 'dir');
+
+    await discoverPlugins();
+
+    const cmd = getRegistry().get('__test-plugin-symlink__/hello');
+    expect(cmd).toBeDefined();
+    expect(cmd!.description).toBe('Test plugin greeting via symlink');
+  });
+
+  it('skips broken plugin symlinks without throwing', async () => {
+    await fs.promises.mkdir(PLUGINS_DIR, { recursive: true });
+    await fs.promises.symlink(path.join(os.tmpdir(), '__missing-plugin-target__'), brokenSymlinkDir, 'dir');
+
+    await expect(discoverPlugins()).resolves.not.toThrow();
+    expect(getRegistry().get('__test-plugin-broken__/hello')).toBeUndefined();
+  });
 });
 
 describe('executeCommand', () => {

package/src/errors.ts

@@ -51,8 +51,12 @@ export class AuthRequiredError extends CliError {
 }
 
 export class TimeoutError extends CliError {
-  constructor(label: string, seconds: number) {
-    super('TIMEOUT', `${label} timed out after ${seconds}s`, 'Try again, or increase timeout with OPENCLI_BROWSER_COMMAND_TIMEOUT env var');
+  constructor(label: string, seconds: number, hint?: string) {
+    super(
+      'TIMEOUT',
+      `${label} timed out after ${seconds}s`,
+      hint ?? 'Try again, or increase timeout with OPENCLI_BROWSER_COMMAND_TIMEOUT env var',
+    );
   }
 }
 

package/src/execution.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { executeCommand } from './execution.js';
+import { TimeoutError } from './errors.js';
+import { cli, Strategy } from './registry.js';
+import { withTimeoutMs } from './runtime.js';
+
+describe('executeCommand — non-browser timeout', () => {
+  it('applies timeoutSeconds to non-browser commands', async () => {
+    const cmd = cli({
+      site: 'test-execution',
+      name: 'non-browser-timeout',
+      description: 'test non-browser timeout',
+      browser: false,
+      strategy: Strategy.PUBLIC,
+      timeoutSeconds: 0.01,
+      func: () => new Promise(() => {}),
+    });
+
+    // Sentinel timeout at 200ms — if the inner 10ms timeout fires first,
+    // the error will be a TimeoutError with the command label, not 'sentinel'.
+    const error = await withTimeoutMs(executeCommand(cmd, {}), 200, 'sentinel timeout')
+      .catch((err) => err);
+
+    expect(error).toBeInstanceOf(TimeoutError);
+    expect(error).toMatchObject({
+      code: 'TIMEOUT',
+      message: 'test-execution/non-browser-timeout timed out after 0.01s',
+    });
+  });
+
+  it('skips timeout when timeoutSeconds is 0', async () => {
+    const cmd = cli({
+      site: 'test-execution',
+      name: 'non-browser-zero-timeout',
+      description: 'test zero timeout bypasses wrapping',
+      browser: false,
+      strategy: Strategy.PUBLIC,
+      timeoutSeconds: 0,
+      func: () => new Promise(() => {}),
+    });
+
+    // With timeout guard skipped, the sentinel fires instead.
+    await expect(
+      withTimeoutMs(executeCommand(cmd, {}), 50, 'sentinel timeout'),
+    ).rejects.toThrow('sentinel timeout');
+  });
+});

package/src/execution.ts

@@ -130,6 +130,23 @@ function ensureRequiredEnv(cmd: CliCommand): void {
   );
 }
 
+/**
+ * Check if the browser is already on the target domain, avoiding redundant navigation.
+ * Returns true if current page hostname matches the pre-nav URL hostname.
+ */
+async function isAlreadyOnDomain(page: IPage, targetUrl: string): Promise<boolean> {
+  if (!page.getCurrentUrl) return false;
+  try {
+    const currentUrl = await page.getCurrentUrl();
+    if (!currentUrl) return false;
+    const currentHost = new URL(currentUrl).hostname;
+    const targetHost = new URL(targetUrl).hostname;
+    return currentHost === targetHost;
+  } catch {
+    return false;
+  }
+}
+
 export async function executeCommand(
   cmd: CliCommand,
   rawKwargs: CommandArgs,
@@ -181,11 +198,17 @@ export async function executeCommand(
       result = await browserSession(BrowserFactory, async (page) => {
         const preNavUrl = resolvePreNav(cmd);
         if (preNavUrl) {
-          try {
-            await page.goto(preNavUrl);
-            await page.wait(2);
-          } catch (err) {
-            if (debug) console.error(`[pre-nav] Failed to navigate to ${preNavUrl}: ${err instanceof Error ? err.message : err}`);
+          const skip = await isAlreadyOnDomain(page, preNavUrl);
+          if (skip) {
+            if (debug) console.error(`[pre-nav] Already on target domain, skipping navigation`);
+          } else {
+            try {
+              // goto() already includes smart DOM-settle detection (waitForDomStable).
+              // No additional fixed sleep needed.
+              await page.goto(preNavUrl);
+            } catch (err) {
+              if (debug) console.error(`[pre-nav] Failed to navigate to ${preNavUrl}: ${err instanceof Error ? err.message : err}`);
+            }
           }
         }
         return runWithTimeout(runCommand(cmd, page, kwargs, debug), {
@@ -194,7 +217,17 @@ export async function executeCommand(
         });
       }, { workspace: `site:${cmd.site}` });
     } else {
-      result = await runCommand(cmd, null, kwargs, debug);
+      // Non-browser commands: apply timeout only when explicitly configured.
+      const timeout = cmd.timeoutSeconds;
+      if (timeout !== undefined && timeout > 0) {
+        result = await runWithTimeout(runCommand(cmd, null, kwargs, debug), {
+          timeout,
+          label: fullName(cmd),
+          hint: `Increase the adapter's timeoutSeconds setting (currently ${timeout}s)`,
+        });
+      } else {
+        result = await runCommand(cmd, null, kwargs, debug);
+      }
     }
   } catch (err) {
     hookCtx.error = err;

package/src/external.ts

@@ -31,7 +31,10 @@ function getUserRegistryPath(): string {
   return path.join(home, '.opencli', 'external-clis.yaml');
 }
 
+let _cachedExternalClis: ExternalCliConfig[] | null = null;
+
 export function loadExternalClis(): ExternalCliConfig[] {
+  if (_cachedExternalClis) return _cachedExternalClis;
   const configs = new Map<string, ExternalCliConfig>();
 
   // 1. Load built-in
@@ -60,7 +63,8 @@ export function loadExternalClis(): ExternalCliConfig[] {
     log.warn(`Failed to parse user external-clis.yaml: ${getErrorMessage(err)}`);
   }
 
-  return Array.from(configs.values()).sort((a, b) => a.name.localeCompare(b.name));
+  _cachedExternalClis = Array.from(configs.values()).sort((a, b) => a.name.localeCompare(b.name));
+  return _cachedExternalClis;
 }
 
 export function isBinaryInstalled(binary: string): boolean {
@@ -237,5 +241,6 @@ export function registerExternalCli(name: string, opts?: RegisterOptions): void
 
   const dump = yaml.dump(items, { indent: 2, sortKeys: true });
   fs.writeFileSync(userPath, dump, 'utf8');
+  _cachedExternalClis = null; // Invalidate cache so next load reflects the change
   console.log(chalk.dim(userPath));
 }

package/src/main.ts

@@ -27,6 +27,7 @@ const __dirname = path.dirname(__filename);
 const BUILTIN_CLIS = path.resolve(__dirname, 'clis');
 const USER_CLIS = path.join(os.homedir(), '.opencli', 'clis');
 
+// Sequential: plugins must run after built-in discovery so they can override built-in commands.
 await discoverClis(BUILTIN_CLIS, USER_CLIS);
 await discoverPlugins();
 

package/src/plugin-scaffold.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Tests for plugin scaffold: create new plugin directories.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { createPluginScaffold } from './plugin-scaffold.js';
+
+describe('createPluginScaffold', () => {
+  const createdDirs: string[] = [];
+
+  afterEach(() => {
+    for (const dir of createdDirs) {
+      try { fs.rmSync(dir, { recursive: true, force: true }); } catch {}
+    }
+    createdDirs.length = 0;
+  });
+
+  it('creates all expected files', () => {
+    const dir = path.join(os.tmpdir(), `opencli-scaffold-${Date.now()}`);
+    createdDirs.push(dir);
+
+    const result = createPluginScaffold('my-test', { dir });
+    expect(result.name).toBe('my-test');
+    expect(result.dir).toBe(dir);
+    expect(result.files).toContain('opencli-plugin.json');
+    expect(result.files).toContain('package.json');
+    expect(result.files).toContain('hello.yaml');
+    expect(result.files).toContain('greet.ts');
+    expect(result.files).toContain('README.md');
+
+    // All files exist
+    for (const f of result.files) {
+      expect(fs.existsSync(path.join(dir, f))).toBe(true);
+    }
+  });
+
+  it('generates valid opencli-plugin.json', () => {
+    const dir = path.join(os.tmpdir(), `opencli-scaffold-${Date.now()}`);
+    createdDirs.push(dir);
+
+    createPluginScaffold('test-manifest', { dir, description: 'Test desc' });
+    const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'opencli-plugin.json'), 'utf-8'));
+    expect(manifest.name).toBe('test-manifest');
+    expect(manifest.version).toBe('0.1.0');
+    expect(manifest.description).toBe('Test desc');
+    expect(manifest.opencli).toMatch(/^>=/);
+  });
+
+  it('generates ESM package.json', () => {
+    const dir = path.join(os.tmpdir(), `opencli-scaffold-${Date.now()}`);
+    createdDirs.push(dir);
+
+    createPluginScaffold('test-pkg', { dir });
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
+    expect(pkg.type).toBe('module');
+    expect(pkg.peerDependencies?.['@jackwener/opencli']).toBeDefined();
+  });
+
+  it('generates a TS sample that matches the current plugin API', () => {
+    const dir = path.join(os.tmpdir(), `opencli-scaffold-${Date.now()}`);
+    createdDirs.push(dir);
+
+    createPluginScaffold('test-ts', { dir });
+    const tsSample = fs.readFileSync(path.join(dir, 'greet.ts'), 'utf-8');
+
+    expect(tsSample).toContain(`import { cli, Strategy } from '@jackwener/opencli/registry';`);
+    expect(tsSample).toContain(`strategy: Strategy.PUBLIC`);
+    expect(tsSample).toContain(`help: 'Name to greet'`);
+    expect(tsSample).toContain(`func: async (_page, kwargs)`);
+    expect(tsSample).not.toContain('async run(');
+  });
+
+  it('documents a supported local install flow', () => {
+    const dir = path.join(os.tmpdir(), `opencli-scaffold-${Date.now()}`);
+    createdDirs.push(dir);
+
+    createPluginScaffold('test-readme', { dir });
+    const readme = fs.readFileSync(path.join(dir, 'README.md'), 'utf-8');
+
+    expect(readme).toContain(`opencli plugin install file://${dir}`);
+  });
+
+  it('rejects invalid names', () => {
+    expect(() => createPluginScaffold('Bad_Name')).toThrow('Invalid plugin name');
+    expect(() => createPluginScaffold('123start')).toThrow('Invalid plugin name');
+  });
+
+  it('rejects non-empty directory', () => {
+    const dir = path.join(os.tmpdir(), `opencli-scaffold-${Date.now()}`);
+    createdDirs.push(dir);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'existing.txt'), 'x');
+    expect(() => createPluginScaffold('test', { dir })).toThrow('not empty');
+  });
+});

package/src/plugin-scaffold.ts

@@ -0,0 +1,170 @@
+/**
+ * Plugin scaffold: generates a ready-to-develop plugin directory.
+ *
+ * Usage: opencli plugin create <name> [--dir <path>]
+ *
+ * Creates:
+ *   <name>/
+ *     opencli-plugin.json   — manifest with name, version, description
+ *     package.json          — ESM package with opencli peer dependency
+ *     hello.yaml            — sample YAML command
+   *     greet.ts              — sample TS command using the current registry API
+ *     README.md             — basic documentation
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { PKG_VERSION } from './version.js';
+
+export interface ScaffoldOptions {
+  /** Directory to create the plugin in. Defaults to `./<name>` */
+  dir?: string;
+  /** Plugin description */
+  description?: string;
+}
+
+export interface ScaffoldResult {
+  name: string;
+  dir: string;
+  files: string[];
+}
+
+/**
+ * Create a new plugin scaffold directory.
+ */
+export function createPluginScaffold(name: string, opts: ScaffoldOptions = {}): ScaffoldResult {
+  // Validate name
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+    throw new Error(
+      `Invalid plugin name "${name}". ` +
+      `Plugin names must start with a lowercase letter and contain only lowercase letters, digits, and hyphens.`
+    );
+  }
+
+  const targetDir = opts.dir
+    ? path.resolve(opts.dir)
+    : path.resolve(name);
+
+  if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+    throw new Error(`Directory "${targetDir}" already exists and is not empty.`);
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  const files: string[] = [];
+
+  // opencli-plugin.json
+  const manifest = {
+    name,
+    version: '0.1.0',
+    description: opts.description ?? `An opencli plugin: ${name}`,
+    opencli: `>=${PKG_VERSION}`,
+  };
+  writeFile(targetDir, 'opencli-plugin.json', JSON.stringify(manifest, null, 2) + '\n');
+  files.push('opencli-plugin.json');
+
+  // package.json
+  const pkg = {
+    name: `opencli-plugin-${name}`,
+    version: '0.1.0',
+    type: 'module',
+    description: opts.description ?? `An opencli plugin: ${name}`,
+    peerDependencies: {
+      '@jackwener/opencli': `>=${PKG_VERSION}`,
+    },
+  };
+  writeFile(targetDir, 'package.json', JSON.stringify(pkg, null, 2) + '\n');
+  files.push('package.json');
+
+  // hello.yaml — sample YAML command
+  const yamlContent = `# Sample YAML command for ${name}
+# See: https://github.com/jackwener/opencli#yaml-commands
+
+site: ${name}
+name: hello
+description: "A sample YAML command"
+strategy: public
+browser: false
+
+domain: https://httpbin.org
+
+pipeline:
+  - fetch:
+      url: "https://httpbin.org/get?greeting=hello"
+      method: GET
+  - extract:
+      type: json
+      selector: "$.args"
+`;
+  writeFile(targetDir, 'hello.yaml', yamlContent);
+  files.push('hello.yaml');
+
+  // greet.ts — sample TS command using registry API
+  const tsContent = `/**
+ * Sample TypeScript command for ${name}.
+ * Demonstrates the programmatic cli() registration API.
+ */
+
+import { cli, Strategy } from '@jackwener/opencli/registry';
+
+cli({
+  site: '${name}',
+  name: 'greet',
+  description: 'Greet someone by name',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: 'name', positional: true, required: true, help: 'Name to greet' },
+  ],
+  columns: ['greeting'],
+  func: async (_page, kwargs) => [{ greeting: \`Hello, \${String(kwargs.name ?? 'World')}!\` }],
+});
+`;
+  writeFile(targetDir, 'greet.ts', tsContent);
+  files.push('greet.ts');
+
+  // README.md
+  const readme = `# opencli-plugin-${name}
+
+${opts.description ?? `An opencli plugin: ${name}`}
+
+## Install
+
+\`\`\`bash
+# From local development directory
+opencli plugin install file://${targetDir}
+
+# From GitHub (after publishing)
+opencli plugin install github:<user>/opencli-plugin-${name}
+\`\`\`
+
+## Commands
+
+| Command | Type | Description |
+|---------|------|-------------|
+| \`${name}/hello\` | YAML | Sample YAML command |
+| \`${name}/greet\` | TypeScript | Sample TS command |
+
+## Development
+
+\`\`\`bash
+# Install locally for development (symlinked, changes reflect immediately)
+opencli plugin install file://${targetDir}
+
+# Verify commands are registered
+opencli list | grep ${name}
+
+# Run a command
+opencli ${name} hello
+opencli ${name} greet --name World
+\`\`\`
+`;
+  writeFile(targetDir, 'README.md', readme);
+  files.push('README.md');
+
+  return { name, dir: targetDir, files };
+}
+
+function writeFile(dir: string, name: string, content: string): void {
+  fs.writeFileSync(path.join(dir, name), content);
+}