@jackwener/opencli 1.6.9 → 1.7.0

package/dist/src/generate.d.ts

@@ -5,7 +5,7 @@
  *   explore (Deep Explore) → synthesize (YAML generation + candidate ranking)
  */
 import type { IBrowserFactory } from './runtime.js';
-import { type SynthesizeCandidateSummary } from './synthesize.js';
+import { type SynthesizeCandidateSummary, type SynthesizeResult } from './synthesize.js';
 export interface GenerateCliOptions {
     url: string;
     BrowserFactory: new () => IBrowserFactory;
@@ -34,5 +34,13 @@ export interface GenerateCliResult {
         candidates: Array<Pick<SynthesizeCandidateSummary, 'name' | 'strategy'>>;
     };
 }
+/**
+ * Normalize a goal string to a standard capability name.
+ */
+export declare function normalizeGoal(goal?: string | null): string | null;
+/**
+ * Select the best candidate matching the user's goal.
+ */
+export declare function selectCandidate(candidates: SynthesizeResult['candidates'], goal?: string | null): SynthesizeCandidateSummary | null;
 export declare function generateCliFromUrl(opts: GenerateCliOptions): Promise<GenerateCliResult>;
 export declare function renderGenerateSummary(r: GenerateCliResult): string;

package/dist/src/generate.js

@@ -20,7 +20,7 @@ const CAPABILITY_ALIASES = {
 /**
  * Normalize a goal string to a standard capability name.
  */
-function normalizeGoal(goal) {
+export function normalizeGoal(goal) {
     if (!goal)
         return null;
     const lower = goal.trim().toLowerCase();
@@ -33,7 +33,7 @@ function normalizeGoal(goal) {
 /**
  * Select the best candidate matching the user's goal.
  */
-function selectCandidate(candidates, goal) {
+export function selectCandidate(candidates, goal) {
     if (!candidates.length)
         return null;
     if (!goal)

package/dist/src/main.js

@@ -12,20 +12,75 @@ if (process.platform !== 'win32') {
         cur.add(p);
     process.env.PATH = [...cur].join(':');
 }
+import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { discoverClis, discoverPlugins, ensureUserCliCompatShims, ensureUserAdapters, USER_CLIS_DIR } from './discovery.js';
-import { getCompletions } from './completion.js';
-import { runCli } from './cli.js';
-import { emitHook } from './hooks.js';
-import { installNodeNetwork } from './node-network.js';
-import { registerUpdateNoticeOnExit, checkForUpdateBackground } from './update-check.js';
+import { getCompletionsFromManifest, hasAllManifests, printCompletionScriptFast } from './completion-fast.js';
+import { getCliManifestPath } from './package-paths.js';
+import { PKG_VERSION } from './version.js';
 import { EXIT_CODES } from './errors.js';
-installNodeNetwork();
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const BUILTIN_CLIS = path.resolve(__dirname, '..', 'clis');
-const USER_CLIS = USER_CLIS_DIR;
+const USER_CLIS = path.join(os.homedir(), '.opencli', 'clis');
+// ── Ultra-fast path: lightweight commands bypass full discovery ──────────
+// These are high-frequency or trivial paths that must not pay the startup tax.
+const argv = process.argv.slice(2);
+// Fast path: --version (only when it's the top-level intent, not passed to a subcommand)
+// e.g. `opencli --version` or `opencli -V`, but NOT `opencli gh --version`
+if (argv[0] === '--version' || argv[0] === '-V') {
+    process.stdout.write(PKG_VERSION + '\n');
+    process.exit(EXIT_CODES.SUCCESS);
+}
+// Fast path: completion <shell> — print shell script without discovery
+if (argv[0] === 'completion' && argv.length >= 2) {
+    if (printCompletionScriptFast(argv[1])) {
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    // Unknown shell — fall through to full path for proper error handling
+}
+// Fast path: --get-completions — read from manifest, skip discovery
+const getCompIdx = process.argv.indexOf('--get-completions');
+if (getCompIdx !== -1) {
+    // Only require manifest for directories that actually exist.
+    // If user clis dir doesn't exist, there are no user adapters to miss.
+    const manifestPaths = [getCliManifestPath(BUILTIN_CLIS)];
+    try {
+        fs.accessSync(USER_CLIS);
+        manifestPaths.push(getCliManifestPath(USER_CLIS));
+    }
+    catch { /* no user dir */ }
+    if (hasAllManifests(manifestPaths)) {
+        const rest = process.argv.slice(getCompIdx + 1);
+        let cursor;
+        const words = [];
+        for (let i = 0; i < rest.length; i++) {
+            if (rest[i] === '--cursor' && i + 1 < rest.length) {
+                cursor = parseInt(rest[i + 1], 10);
+                i++;
+            }
+            else {
+                words.push(rest[i]);
+            }
+        }
+        if (cursor === undefined)
+            cursor = words.length;
+        const candidates = getCompletionsFromManifest(words, cursor, manifestPaths);
+        process.stdout.write(candidates.join('\n') + '\n');
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    // No manifest — fall through to full discovery path below
+}
+// ── Full startup path ───────────────────────────────────────────────────
+// Dynamic imports: these are deferred so the fast path above never pays the cost.
+const { discoverClis, discoverPlugins, ensureUserCliCompatShims, ensureUserAdapters } = await import('./discovery.js');
+const { getCompletions } = await import('./completion.js');
+const { runCli } = await import('./cli.js');
+const { emitHook } = await import('./hooks.js');
+const { installNodeNetwork } = await import('./node-network.js');
+const { registerUpdateNoticeOnExit, checkForUpdateBackground } = await import('./update-check.js');
+installNodeNetwork();
 // Sequential: plugins must run after built-in discovery so they can override built-in commands.
 await ensureUserCliCompatShims();
 await ensureUserAdapters();
@@ -35,9 +90,7 @@ await discoverPlugins();
 registerUpdateNoticeOnExit();
 // Kick off background fetch for next run (non-blocking)
 checkForUpdateBackground();
-// ── Fast-path: handle --get-completions before commander parses ─────────
-// Usage: opencli --get-completions --cursor <N> [word1 word2 ...]
-const getCompIdx = process.argv.indexOf('--get-completions');
+// ── Fallback completion: manifest unavailable, use full registry ─────────
 if (getCompIdx !== -1) {
     const rest = process.argv.slice(getCompIdx + 1);
     let cursor;
@@ -45,7 +98,7 @@ if (getCompIdx !== -1) {
     for (let i = 0; i < rest.length; i++) {
         if (rest[i] === '--cursor' && i + 1 < rest.length) {
             cursor = parseInt(rest[i + 1], 10);
-            i++; // skip the value
+            i++;
         }
         else {
             words.push(rest[i]);

package/dist/src/pipeline/steps/download.d.ts

@@ -15,20 +15,4 @@ export interface DownloadResult {
     error?: string;
     duration?: number;
 }
-/**
- * Download step handler for YAML pipelines.
- *
- * Usage in YAML:
- * ```yaml
- * pipeline:
- *   - download:
- *       url: ${{ item.imageUrl }}
- *       dir: ./downloads
- *       filename: ${{ item.title }}.jpg
- *       concurrency: 5
- *       skip_existing: true
- *       use_ytdlp: false
- *       type: auto
- * ```
- */
-export declare function stepDownload(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any>;
+export declare function stepDownload(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown>;

package/dist/src/pipeline/steps/download.js

@@ -54,41 +54,31 @@ function dedupeCookies(cookies) {
     }
     return [...deduped.values()];
 }
-/**
- * Download step handler for YAML pipelines.
- *
- * Usage in YAML:
- * ```yaml
- * pipeline:
- *   - download:
- *       url: ${{ item.imageUrl }}
- *       dir: ./downloads
- *       filename: ${{ item.title }}.jpg
- *       concurrency: 5
- *       skip_existing: true
- *       use_ytdlp: false
- *       type: auto
- * ```
- */
 export async function stepDownload(page, params, data, args) {
     // Parse parameters with defaults
-    const urlTemplate = typeof params === 'string' ? params : (params?.url ?? '');
-    const dirTemplate = params?.dir ?? './downloads';
-    const filenameTemplate = params?.filename ?? '';
-    const concurrency = typeof params?.concurrency === 'number' ? params.concurrency : 3;
-    const skipExisting = params?.skip_existing !== false;
-    const timeout = typeof params?.timeout === 'number' ? params.timeout * 1000 : 30000;
-    const useYtdlp = params?.use_ytdlp ?? false;
-    const ytdlpArgs = Array.isArray(params?.ytdlp_args) ? params.ytdlp_args : [];
-    const contentType = params?.type ?? 'auto';
-    const showProgress = params?.progress !== false;
-    const contentTemplate = params?.content;
-    const metadataTemplate = params?.metadata;
+    const p = typeof params === 'object' && params !== null ? params : {};
+    const urlTemplate = typeof params === 'string' ? params : (p.url ?? '');
+    const dirTemplate = p.dir ?? './downloads';
+    const filenameTemplate = p.filename ?? '';
+    const concurrency = typeof p.concurrency === 'number' ? p.concurrency : 3;
+    const skipExisting = p.skip_existing !== false;
+    const timeout = typeof p.timeout === 'number' ? p.timeout * 1000 : 30000;
+    const useYtdlp = p.use_ytdlp ?? false;
+    const ytdlpArgs = Array.isArray(p.ytdlp_args)
+        ? p.ytdlp_args.map((v) => String(v))
+        : [];
+    const contentType = p.type ?? 'auto';
+    const showProgress = p.progress !== false;
+    const contentTemplate = p.content;
+    const metadataTemplate = p.metadata;
     // Resolve output directory
     const dir = String(render(dirTemplate, { args, data }));
     fs.mkdirSync(dir, { recursive: true });
-    // Normalize data to array
-    const items = Array.isArray(data) ? data : data ? [data] : [];
+    // Normalize data to array. Items are row records (string-keyed) produced by
+    // upstream steps; we treat them as Record<string, unknown> and narrow per-use.
+    const items = Array.isArray(data) ? data
+        : data ? [data]
+            : [];
     if (items.length === 0) {
         return [];
     }
@@ -128,7 +118,6 @@ export async function stepDownload(page, params, data, args) {
             }
         }
     }
-    // Process downloads with concurrency
     const results = await mapConcurrent(items, concurrency, async (item, index) => {
         const startTime = Date.now();
         // Render URL

package/dist/src/pipeline/steps/intercept.d.ts

@@ -2,4 +2,4 @@
  * Pipeline step: intercept — declarative XHR interception.
  */
 import type { IPage } from '../../types.js';
-export declare function stepIntercept(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any>;
+export declare function stepIntercept(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown>;

package/dist/src/pipeline/steps/intercept.js

@@ -3,7 +3,7 @@
  */
 import { render, normalizeEvaluateSource } from '../template.js';
 export async function stepIntercept(page, params, data, args) {
-    const cfg = typeof params === 'object' ? params : {};
+    const cfg = typeof params === 'object' && params !== null ? params : {};
     const trigger = cfg.trigger ?? '';
     const capturePattern = cfg.capture ?? '';
     const timeout = cfg.timeout ?? 8;

package/dist/src/pipeline/steps/tap.d.ts

@@ -9,4 +9,4 @@
  * 5. Returns the captured data (optionally sub-selected)
  */
 import type { IPage } from '../../types.js';
-export declare function stepTap(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any>;
+export declare function stepTap(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown>;

package/dist/src/pipeline/steps/tap.js

@@ -11,7 +11,7 @@
 import { render } from '../template.js';
 import { generateTapInterceptorJs } from '../../interceptor.js';
 export async function stepTap(page, params, data, args) {
-    const cfg = typeof params === 'object' ? params : {};
+    const cfg = typeof params === 'object' && params !== null ? params : {};
     const storeName = String(render(cfg.store ?? '', { args, data }));
     const actionName = String(render(cfg.action ?? '', { args, data }));
     const capturePattern = String(render(cfg.capture ?? '', { args, data }));

package/dist/src/plugin-scaffold.d.ts

@@ -7,8 +7,8 @@
  *   <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
+ *     hello.ts              — sample pipeline command
+ *     greet.ts              — sample TS command using func()
  *     README.md             — basic documentation
  */
 export interface ScaffoldOptions {

package/dist/src/plugin-scaffold.js

@@ -7,8 +7,8 @@
  *   <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
+ *     hello.ts              — sample pipeline command
+ *     greet.ts              — sample TS command using func()
  *     README.md             — basic documentation
  */
 import * as fs from 'node:fs';
@@ -52,26 +52,29 @@ export function createPluginScaffold(name, opts = {}) {
     };
     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
+    // hello.ts — sample pipeline command
+    const helloContent = `/**
+ * Sample pipeline command for ${name}.
+ * Demonstrates the declarative pipeline API.
+ */
 
-domain: https://httpbin.org
+import { cli, Strategy } from '@jackwener/opencli/registry';
 
-pipeline:
-  - fetch:
-      url: "https://httpbin.org/get?greeting=hello"
-      method: GET
-  - select: "args"
+cli({
+  site: '${name}',
+  name: 'hello',
+  description: 'A sample pipeline command',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  columns: ['greeting'],
+  pipeline: [
+    { fetch: { url: 'https://httpbin.org/get?greeting=hello' } },
+    { select: 'args' },
+  ],
+});
 `;
-    writeFile(targetDir, 'hello.yaml', yamlContent);
-    files.push('hello.yaml');
+    writeFile(targetDir, 'hello.ts', helloContent);
+    files.push('hello.ts');
     // greet.ts — sample TS command using registry API
     const tsContent = `/**
  * Sample TypeScript command for ${name}.
@@ -114,8 +117,8 @@ opencli plugin install github:<user>/opencli-plugin-${name}
 
 | Command | Type | Description |
 |---------|------|-------------|
-| \`${name}/hello\` | YAML | Sample YAML command |
-| \`${name}/greet\` | TypeScript | Sample TS command |
+| \`${name}/hello\` | Pipeline | Sample pipeline command |
+| \`${name}/greet\` | TypeScript | Sample TS command with func() |
 
 ## Development
 

package/dist/src/plugin-scaffold.test.js

@@ -25,7 +25,7 @@ describe('createPluginScaffold', () => {
         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('hello.ts');
         expect(result.files).toContain('greet.ts');
         expect(result.files).toContain('README.md');
         // All files exist

package/dist/src/plugin.d.ts

@@ -80,7 +80,7 @@ export declare function writeLockFile(lock: Record<string, LockEntry>): void;
 export declare function getCommitHash(dir: string): string | undefined;
 /**
  * Validate that a downloaded plugin directory is a structurally valid plugin.
- * Checks for at least one command file (.yaml, .yml, .ts, .js) and a valid
+ * Checks for at least one command file (.ts, .js) and a valid
  * package.json if it contains .ts files.
  */
 export declare function validatePluginStructure(pluginDir: string): ValidationResult;

package/dist/src/plugin.js

@@ -453,7 +453,7 @@ export function getCommitHash(dir) {
 }
 /**
  * Validate that a downloaded plugin directory is a structurally valid plugin.
- * Checks for at least one command file (.yaml, .yml, .ts, .js) and a valid
+ * Checks for at least one command file (.ts, .js) and a valid
  * package.json if it contains .ts files.
  */
 export function validatePluginStructure(pluginDir) {
@@ -462,11 +462,10 @@ export function validatePluginStructure(pluginDir) {
         return { valid: false, errors: ['Plugin directory does not exist'] };
     }
     const files = fs.readdirSync(pluginDir);
-    const hasYaml = files.some(f => f.endsWith('.yaml') || f.endsWith('.yml'));
     const hasTs = files.some(f => f.endsWith('.ts') && !f.endsWith('.d.ts') && !f.endsWith('.test.ts'));
     const hasJs = files.some(f => f.endsWith('.js') && !f.endsWith('.d.js'));
-    if (!hasYaml && !hasTs && !hasJs) {
-        errors.push('No command files found in plugin directory. A plugin must contain at least one .yaml, .ts, or .js command file.');
+    if (!hasTs && !hasJs) {
+        errors.push('No command files found in plugin directory. A plugin must contain at least one .ts or .js command file.');
     }
     if (hasTs) {
         const pkgJsonPath = path.join(pluginDir, 'package.json');
@@ -981,8 +980,7 @@ 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')) ||
+            .filter(f => (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];