@jackwener/opencli 1.7.12 → 1.7.13

package/dist/src/pipeline/registry.js

@@ -3,7 +3,7 @@
  * Allows core and third-party plugins to register custom YAML operations.
  */
 // Import core steps
-import { stepNavigate, stepClick, stepType, stepWait, stepPress, stepSnapshot, stepEvaluate } from './steps/browser.js';
+import { stepNavigate, stepClick, stepType, stepFill, stepWait, stepPress, stepSnapshot, stepEvaluate } from './steps/browser.js';
 import { stepFetch } from './steps/fetch.js';
 import { stepSelect, stepMap, stepFilter, stepSort, stepLimit } from './steps/transform.js';
 import { stepIntercept } from './steps/intercept.js';
@@ -16,6 +16,17 @@ const _stepRegistry = new Map();
 export function getStep(name) {
     return _stepRegistry.get(name);
 }
+/**
+ * List all currently registered step names. Used by `validate.ts` to allowlist
+ * step names without maintaining a parallel hand-coded list.
+ *
+ * Note: this depends on registerStep() side effects below already having run.
+ * Importing this module triggers all core registrations at the bottom of the
+ * file, so the returned array reflects every core + plugin step at call time.
+ */
+export function getRegisteredStepNames() {
+    return [..._stepRegistry.keys()];
+}
 /**
  * Register a new custom step handler for the YAML pipeline.
  */
@@ -32,6 +43,7 @@ registerStep('evaluate', stepEvaluate);
 registerStep('snapshot', stepSnapshot);
 registerStep('click', stepClick);
 registerStep('type', stepType);
+registerStep('fill', stepFill);
 registerStep('wait', stepWait);
 registerStep('press', stepPress);
 registerStep('map', stepMap);

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

@@ -6,6 +6,7 @@ import type { IPage } from '../../types.js';
 export declare function stepNavigate(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown>;
 export declare function stepClick(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown>;
 export declare function stepType(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown>;
+export declare function stepFill(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown>;
 export declare function stepWait(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown>;
 export declare function stepPress(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown>;
 export declare function stepSnapshot(page: IPage | null, params: unknown, _data: unknown, _args: Record<string, unknown>): Promise<unknown>;

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

@@ -29,6 +29,16 @@ export async function stepType(page, params, data, args) {
     }
     return data;
 }
+export async function stepFill(page, params, data, args) {
+    if (isRecord(params)) {
+        const ref = String(render(params.ref ?? '', { args, data })).replace(/^@/, '');
+        const text = String(render(params.text ?? '', { args, data }));
+        await page.fillText(ref, text);
+        if (params.submit)
+            await page.pressKey('Enter');
+    }
+    return data;
+}
 export async function stepWait(page, params, data, args) {
     if (typeof params === 'number')
         await page.wait(params);

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

@@ -25,6 +25,7 @@ function createMockPage(getCookies) {
         snapshot: vi.fn().mockResolvedValue(''),
         click: vi.fn(),
         typeText: vi.fn(),
+        fillText: vi.fn(),
         pressKey: vi.fn(),
         scrollTo: vi.fn(),
         getFormState: vi.fn().mockResolvedValue({}),

package/dist/src/registry-api.d.ts

@@ -7,7 +7,7 @@
  * plugins are dynamically imported during discoverPlugins().
  */
 export { cli, Strategy, getRegistry, fullName, registerCommand } from './registry.js';
-export type { CliCommand, Arg, CliOptions, CommandArgs } from './registry.js';
+export type { CliCommand, Arg, CliOptions, CommandArgs, BrowserSessionOptions, BrowserSessionReuse } from './registry.js';
 export type { IPage } from './types.js';
 export { onStartup, onBeforeExecute, onAfterExecute } from './hooks.js';
 export type { HookFn, HookContext, HookName } from './hooks.js';

package/dist/src/registry.d.ts

@@ -6,7 +6,6 @@ export declare enum Strategy {
     PUBLIC = "public",
     LOCAL = "local",
     COOKIE = "cookie",
-    HEADER = "header",
     INTERCEPT = "intercept",
     UI = "ui"
 }
@@ -20,14 +19,20 @@ export interface Arg {
     help?: string;
     choices?: string[];
 }
-export interface RequiredEnv {
-    name: string;
-    help?: string;
-}
 export type CommandArgs = Record<string, any>;
 export type BrowserCommandFunc = (page: IPage, kwargs: CommandArgs, debug?: boolean) => Promise<unknown>;
 export type NonBrowserCommandFunc = (kwargs: CommandArgs, debug?: boolean) => Promise<unknown>;
 export type CommandAccess = 'read' | 'write';
+export type BrowserSessionReuse = 'none' | 'site';
+export interface BrowserSessionOptions {
+    /**
+     * Control whether browser-backed adapter commands reuse a stable tab lease.
+     *
+     * - `none`: one-shot workspace per command execution (default)
+     * - `site`: all commands for this site share `site:<site>` until idle expiry
+     */
+    reuse?: BrowserSessionReuse;
+}
 interface BaseCliCommand {
     site: string;
     name: string;
@@ -41,16 +46,10 @@ interface BaseCliCommand {
     args: Arg[];
     columns?: string[];
     pipeline?: Record<string, unknown>[];
-    timeoutSeconds?: number;
     /** Origin of this command: 'yaml', 'ts', or plugin name. */
     source?: string;
     footerExtra?: (kwargs: CommandArgs) => string | undefined;
-    requiredEnv?: RequiredEnv[];
     validateArgs?: (kwargs: CommandArgs) => void;
-    /** Deprecation note shown in help / execution warnings. */
-    deprecated?: boolean | string;
-    /** Preferred replacement command, if any. */
-    replacedBy?: string;
     /**
      * Control pre-navigation and browser-session requirement.
      *
@@ -67,6 +66,8 @@ interface BaseCliCommand {
      * Adapter authors can set this explicitly to override the strategy-based default.
      */
     navigateBefore?: boolean | string;
+    /** Browser session lifecycle defaults for adapter commands. */
+    browserSession?: BrowserSessionOptions;
     /** Override the default CLI output format when the user does not pass -f/--format. */
     defaultFormat?: 'table' | 'plain' | 'json' | 'yaml' | 'yml' | 'md' | 'markdown' | 'csv';
 }

package/dist/src/registry.js

@@ -6,7 +6,6 @@ export var Strategy;
     Strategy["PUBLIC"] = "public";
     Strategy["LOCAL"] = "local";
     Strategy["COOKIE"] = "cookie";
-    Strategy["HEADER"] = "header";
     Strategy["INTERCEPT"] = "intercept";
     Strategy["UI"] = "ui";
 })(Strategy || (Strategy = {}));
@@ -18,6 +17,7 @@ export function cli(opts) {
         aliases: opts.aliases,
         description: opts.description ?? '',
         access: opts.access,
+        example: opts.example,
         domain: opts.domain,
         strategy: opts.strategy,
         browser: opts.browser,
@@ -25,12 +25,9 @@ export function cli(opts) {
         columns: opts.columns,
         func: opts.func,
         pipeline: opts.pipeline,
-        timeoutSeconds: opts.timeoutSeconds,
         footerExtra: opts.footerExtra,
-        requiredEnv: opts.requiredEnv,
-        deprecated: opts.deprecated,
-        replacedBy: opts.replacedBy,
         navigateBefore: opts.navigateBefore,
+        browserSession: opts.browserSession,
         defaultFormat: opts.defaultFormat,
     };
     registerCommand(cmd);
@@ -60,11 +57,12 @@ export function strategyLabel(cmd) {
  */
 function normalizeCommand(cmd) {
     assertCommandAccess(cmd);
+    assertBrowserSessionOptions(cmd);
     const strategy = cmd.strategy ?? (cmd.browser === false ? Strategy.PUBLIC : Strategy.COOKIE);
     const browser = cmd.browser ?? (strategy !== Strategy.PUBLIC && strategy !== Strategy.LOCAL);
     let navigateBefore = cmd.navigateBefore;
     if (navigateBefore === undefined) {
-        if ((strategy === Strategy.COOKIE || strategy === Strategy.HEADER) && cmd.domain) {
+        if (strategy === Strategy.COOKIE && cmd.domain) {
             navigateBefore = `https://${cmd.domain}`;
         }
         else if (strategy !== Strategy.PUBLIC && strategy !== Strategy.LOCAL) {
@@ -84,6 +82,18 @@ function assertCommandAccess(cmd) {
     const key = `${cmd.site}/${cmd.name}`;
     throw new Error(`Command ${key} must declare access: 'read' | 'write'`);
 }
+function assertBrowserSessionOptions(cmd) {
+    if (cmd.browserSession === undefined)
+        return;
+    const key = `${cmd.site}/${cmd.name}`;
+    if (cmd.browserSession === null || typeof cmd.browserSession !== 'object' || Array.isArray(cmd.browserSession)) {
+        throw new Error(`Command ${key} browserSession must be an object`);
+    }
+    const reuse = cmd.browserSession.reuse;
+    if (reuse !== undefined && reuse !== 'none' && reuse !== 'site') {
+        throw new Error(`Command ${key} browserSession.reuse must be one of: none, site`);
+    }
+}
 export function registerCommand(cmd) {
     const normalized = normalizeCommand(cmd);
     const canonicalKey = fullName(normalized);

package/dist/src/registry.test.js

@@ -121,12 +121,12 @@ describe('registerCommand', () => {
             name: 'direct-reg', access: 'read',
             description: 'directly registered',
             args: [],
-            strategy: Strategy.HEADER,
+            strategy: Strategy.COOKIE,
             browser: true,
         };
         registerCommand(cmd);
         const reg = getRegistry();
-        expect(reg.get('test-registry/direct-reg')?.strategy).toBe(Strategy.HEADER);
+        expect(reg.get('test-registry/direct-reg')?.strategy).toBe(Strategy.COOKIE);
     });
 });
 describe('normalizeCommand (via registerCommand)', () => {

package/dist/src/runtime.d.ts

@@ -6,7 +6,6 @@ import type { IPage } from './types.js';
 export declare function getBrowserFactory(site?: string): new () => IBrowserFactory;
 export declare const DEFAULT_BROWSER_CONNECT_TIMEOUT: number;
 export declare const DEFAULT_BROWSER_COMMAND_TIMEOUT: number;
-export declare const DEFAULT_BROWSER_EXPLORE_TIMEOUT: number;
 /**
  * Timeout with seconds unit. Used for high-level command timeouts.
  */
@@ -28,6 +27,7 @@ export interface IBrowserFactory {
         workspace?: string;
         cdpEndpoint?: string;
         contextId?: string;
+        idleTimeout?: number;
     }): Promise<IPage>;
     close(): Promise<void>;
 }
@@ -35,4 +35,5 @@ export declare function browserSession<T>(BrowserFactory: new () => IBrowserFact
     workspace?: string;
     cdpEndpoint?: string;
     contextId?: string;
+    idleTimeout?: number;
 }): Promise<T>;

package/dist/src/runtime.js

@@ -24,7 +24,6 @@ function parseEnvTimeout(envVar, fallback) {
 }
 export const DEFAULT_BROWSER_CONNECT_TIMEOUT = parseEnvTimeout('OPENCLI_BROWSER_CONNECT_TIMEOUT', 30);
 export const DEFAULT_BROWSER_COMMAND_TIMEOUT = parseEnvTimeout('OPENCLI_BROWSER_COMMAND_TIMEOUT', 60);
-export const DEFAULT_BROWSER_EXPLORE_TIMEOUT = parseEnvTimeout('OPENCLI_BROWSER_EXPLORE_TIMEOUT', 120);
 /**
  * Timeout with seconds unit. Used for high-level command timeouts.
  */
@@ -54,6 +53,7 @@ export async function browserSession(BrowserFactory, fn, opts = {}) {
             workspace: opts.workspace,
             cdpEndpoint: opts.cdpEndpoint,
             contextId: opts.contextId,
+            idleTimeout: opts.idleTimeout,
         });
         return await fn(page);
     }

package/dist/src/serialization.d.ts

@@ -31,8 +31,8 @@ export declare function serializeCommand(cmd: CliCommand): {
     columns: string[];
     domain: string | null;
     example: string;
-    deprecated: string | boolean | null;
-    replacedBy: string | null;
+    defaultFormat: "table" | "plain" | "json" | "yaml" | "yml" | "md" | "markdown" | "csv" | null;
+    browserSession: import("./registry.js").BrowserSessionOptions | null;
 };
 /** Human-readable arg summary: `<required> [optional]` style. */
 export declare function formatArgSummary(args: Arg[]): string;

package/dist/src/serialization.js

@@ -33,8 +33,8 @@ export function serializeCommand(cmd) {
         columns: cmd.columns ?? [],
         domain: cmd.domain ?? null,
         example: formatCommandExample(cmd),
-        deprecated: cmd.deprecated ?? null,
-        replacedBy: cmd.replacedBy ?? null,
+        defaultFormat: cmd.defaultFormat ?? null,
+        browserSession: cmd.browserSession ?? null,
     };
 }
 // ── Formatting ──────────────────────────────────────────────────────────────
@@ -90,10 +90,8 @@ export function formatRegistryHelpText(cmd) {
     meta.push(`Browser: ${cmd.browser ? 'yes' : 'no'}`);
     if (cmd.domain)
         meta.push(`Domain: ${cmd.domain}`);
-    if (cmd.deprecated)
-        meta.push(`Deprecated: ${typeof cmd.deprecated === 'string' ? cmd.deprecated : 'yes'}`);
-    if (cmd.replacedBy)
-        meta.push(`Use instead: ${cmd.replacedBy}`);
+    if (cmd.defaultFormat)
+        meta.push(`Default format: ${cmd.defaultFormat}`);
     if (cmd.aliases?.length)
         meta.push(`Aliases: ${cmd.aliases.join(', ')}`);
     lines.push(meta.join(' | '));

package/dist/src/serialization.test.js

@@ -58,4 +58,21 @@ describe('formatRegistryHelpText', () => {
         expect(formatRegistryHelpText(cmd)).toContain('Example: opencli bilibili hot -f yaml');
         expect(formatRegistryHelpText(cmd)).not.toContain('Strategy:');
     });
+    it('surfaces command default output format in structured serialization and help text', () => {
+        const cmd = {
+            site: 'gemini',
+            name: 'ask',
+            access: 'read',
+            description: 'Ask Gemini',
+            strategy: Strategy.COOKIE,
+            browser: true,
+            args: [],
+            defaultFormat: 'plain',
+        };
+        expect(serializeCommand(cmd)).toMatchObject({
+            command: 'gemini/ask',
+            defaultFormat: 'plain',
+        });
+        expect(formatRegistryHelpText(cmd)).toContain('Default format: plain');
+    });
 });

package/dist/src/types.d.ts

@@ -31,6 +31,10 @@ export interface ScreenshotOptions {
     format?: 'png' | 'jpeg';
     quality?: number;
     fullPage?: boolean;
+    /** Override viewport width in CSS pixels for the screenshot only (cleared after). */
+    width?: number;
+    /** Override viewport height in CSS pixels for the screenshot only (ignored when fullPage). */
+    height?: number;
     path?: string;
 }
 export interface FetchJsonOptions {
@@ -87,6 +91,19 @@ export interface IPage {
         matches_n: number;
         match_level: 'exact' | 'stable' | 'reidentified';
     }>;
+    fillText(ref: string, text: string, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        filled: boolean;
+        verified: boolean;
+        expected: string;
+        actual: string;
+        length: number;
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+        mode?: 'input' | 'textarea' | 'contenteditable';
+    }>;
     pressKey(key: string): Promise<void>;
     scrollTo(ref: string, opts?: {
         nth?: number;

package/dist/src/validate.js

@@ -1,12 +1,15 @@
 /** Validate CLI definitions from the registry (JS-first). */
 import { getRegistry, fullName } from './registry.js';
-/** All recognized pipeline step names */
-const KNOWN_STEP_NAMES = new Set([
-    'navigate', 'click', 'type', 'wait', 'press', 'snapshot',
-    'fetch', 'evaluate',
-    'select', 'map', 'filter', 'sort', 'limit',
-    'intercept', 'tap', 'download',
-]);
+import { getRegisteredStepNames } from './pipeline/registry.js';
+/**
+ * Pipeline step names — derived from the live pipeline registry on each
+ * validate call so a new step registered in src/pipeline/registry.ts (or by
+ * a plugin at runtime) is automatically allowlisted here (no parallel
+ * hand-maintained list, no stale-snapshot drift).
+ */
+function getKnownStepNames() {
+    return new Set(getRegisteredStepNames());
+}
 /**
  * Validate registered CLI commands from the in-memory registry.
  *
@@ -66,18 +69,19 @@ function validateCommand(cmd) {
     const warnings = [];
     if (!cmd.description)
         warnings.push('Missing description');
-    // Browser commands should specify a domain for cookie/header context
+    // Browser commands should specify a domain for authenticated browser context
     if (cmd.browser && !cmd.domain) {
-        warnings.push('Browser command without "domain" — cookie/header context may not work');
+        warnings.push('Browser command without "domain" — authenticated browser context may not work');
     }
     // Pipeline validation: check step names for typos
     if (Array.isArray(cmd.pipeline)) {
+        const knownStepNames = getKnownStepNames();
         for (let i = 0; i < cmd.pipeline.length; i++) {
             const step = cmd.pipeline[i];
             if (step && typeof step === 'object') {
                 for (const key of Object.keys(step)) {
-                    if (!KNOWN_STEP_NAMES.has(key)) {
-                        warnings.push(`Pipeline step ${i}: unknown step name "${key}" (did you mean one of: ${[...KNOWN_STEP_NAMES].join(', ')}?)`);
+                    if (!knownStepNames.has(key)) {
+                        warnings.push(`Pipeline step ${i}: unknown step name "${key}" (did you mean one of: ${[...knownStepNames].join(', ')}?)`);
                     }
                 }
             }

package/dist/src/validate.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Tests for src/validate.ts.
+ *
+ * Focus: regression guards for the "single source of truth" link between
+ * pipeline step registry (src/pipeline/registry.ts) and validate.ts step
+ * allowlist. A new step registered via `registerStep()` must automatically
+ * be allowlisted by `opencli validate` — no parallel hand-maintained list.
+ */
+export {};

package/dist/src/validate.test.js

@@ -0,0 +1,90 @@
+/**
+ * Tests for src/validate.ts.
+ *
+ * Focus: regression guards for the "single source of truth" link between
+ * pipeline step registry (src/pipeline/registry.ts) and validate.ts step
+ * allowlist. A new step registered via `registerStep()` must automatically
+ * be allowlisted by `opencli validate` — no parallel hand-maintained list.
+ */
+import { describe, it, expect } from 'vitest';
+import { getRegisteredStepNames, registerStep } from './pipeline/registry.js';
+import { cli, getRegistry, Strategy } from './registry.js';
+import { validateClisWithTarget } from './validate.js';
+describe('validate.ts pipeline step allowlist', () => {
+    it('uses every step name registered in pipeline/registry.ts', () => {
+        const registered = getRegisteredStepNames();
+        expect(registered).toContain('navigate');
+        expect(registered).toContain('click');
+        expect(registered).toContain('type');
+        expect(registered).toContain('fill');
+        expect(registered).toContain('fetch');
+        expect(registered.length).toBeGreaterThanOrEqual(15);
+    });
+    it('does not warn for any step name currently registered in the pipeline registry', () => {
+        // Snapshot the registry before mutating it for the test.
+        const reg = getRegistry();
+        const original = reg.get('validate-allowlist-test/all-steps');
+        if (original)
+            reg.delete('validate-allowlist-test/all-steps');
+        const allRegisteredSteps = getRegisteredStepNames();
+        cli({
+            site: 'validate-allowlist-test',
+            name: 'all-steps',
+            access: 'read',
+            browser: false,
+            strategy: Strategy.PUBLIC,
+            args: [],
+            pipeline: allRegisteredSteps.map(stepName => ({ [stepName]: {} })),
+            func: async () => [],
+        });
+        try {
+            const report = validateClisWithTarget([], 'validate-allowlist-test/all-steps');
+            const r = report.results[0];
+            const unknownStepWarning = r.warnings.find(w => w.startsWith('Pipeline step '));
+            expect(unknownStepWarning).toBeUndefined();
+        }
+        finally {
+            reg.delete('validate-allowlist-test/all-steps');
+            if (original)
+                reg.set('validate-allowlist-test/all-steps', original);
+        }
+    });
+    it('newly registered step automatically appears in validator allowlist', () => {
+        const customStep = '__test_custom_step__';
+        expect(getRegisteredStepNames()).not.toContain(customStep);
+        registerStep(customStep, async (_p, _params, data) => data);
+        try {
+            expect(getRegisteredStepNames()).toContain(customStep);
+            const reg = getRegistry();
+            const original = reg.get('validate-dynamic-test/uses-custom');
+            if (original)
+                reg.delete('validate-dynamic-test/uses-custom');
+            cli({
+                site: 'validate-dynamic-test',
+                name: 'uses-custom',
+                access: 'read',
+                browser: false,
+                strategy: Strategy.PUBLIC,
+                args: [],
+                pipeline: [{ [customStep]: {} }],
+                func: async () => [],
+            });
+            try {
+                const report = validateClisWithTarget([], 'validate-dynamic-test/uses-custom');
+                const r = report.results[0];
+                const unknownStepWarning = r.warnings.find(w => w.includes(customStep));
+                expect(unknownStepWarning).toBeUndefined();
+            }
+            finally {
+                reg.delete('validate-dynamic-test/uses-custom');
+                if (original)
+                    reg.set('validate-dynamic-test/uses-custom', original);
+            }
+        }
+        finally {
+            // Best-effort cleanup of the test step. There is no `unregisterStep` —
+            // leaving it registered is harmless because the test step name is
+            // namespaced and never used outside this file.
+        }
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackwener/opencli",
-  "version": "1.7.12",
+  "version": "1.7.13",
   "publishConfig": {
     "access": "public"
   },

package/scripts/fetch-adapters.js

@@ -188,7 +188,7 @@ export function fetchAdapters() {
 
   // 3b. Clean up stale .yaml/.yml adapter files left by older versions (pre-1.7.0)
   // Older versions shipped adapters as YAML; current versions use .js only.
-  // These cause "Ignoring YAML adapter" warnings on every run (issue #953).
+  // These are no longer discoverable and can shadow the current .js adapter layout.
   let yamlCleaned = 0;
   for (const relPath of walkFiles(USER_CLIS_DIR)) {
     if (relPath.endsWith('.yaml') || relPath.endsWith('.yml')) {