@jackwener/opencli 1.1.1 → 1.2.0

package/dist/explore.js

@@ -147,6 +147,9 @@ function flattenFields(obj, prefix, maxDepth) {
     }
     return names;
 }
+function isBooleanRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 function scoreEndpoint(ep) {
     let s = 0;
     if (ep.contentType.includes('json'))
@@ -401,7 +404,7 @@ export async function exploreUrl(url, opts) {
             let framework = {};
             try {
                 const fw = await page.evaluate(FRAMEWORK_DETECT_JS);
-                if (fw && typeof fw === 'object')
+                if (isBooleanRecord(fw))
                     framework = fw;
             }
             catch { }
@@ -458,11 +461,15 @@ export function renderExploreSummary(result) {
     lines.push(`Output: ${result.out_dir}`);
     return lines.join('\n');
 }
-async function readPageMetadata(page /* IPage */) {
+async function readPageMetadata(page) {
     try {
         const result = await page.evaluate(`() => ({ url: window.location.href, title: document.title || '' })`);
-        if (result && typeof result === 'object')
-            return { url: String(result.url ?? ''), title: String(result.title ?? '') };
+        if (result && typeof result === 'object' && !Array.isArray(result)) {
+            return {
+                url: String(result.url ?? ''),
+                title: String(result.title ?? ''),
+            };
+        }
     }
     catch { }
     return { url: '', title: '' };

package/dist/generate.d.ts

@@ -7,5 +7,44 @@
  * Includes Strategy Cascade: if the initial strategy fails,
  * automatically downgrades and retries.
  */
-export declare function generateCliFromUrl(opts: any): Promise<any>;
-export declare function renderGenerateSummary(r: any): string;
+import type { IBrowserFactory } from './runtime.js';
+import { type SynthesizeCandidateSummary } from './synthesize.js';
+interface RegisterCandidatesResult {
+    ok: boolean;
+    count: number;
+}
+export interface GenerateCliOptions {
+    url: string;
+    BrowserFactory: new () => IBrowserFactory;
+    builtinClis?: string;
+    userClis?: string;
+    goal?: string | null;
+    site?: string;
+    waitSeconds?: number;
+    top?: number;
+    register?: boolean;
+    workspace?: string;
+}
+export interface GenerateCliResult {
+    ok: boolean;
+    goal?: string | null;
+    normalized_goal?: string | null;
+    site: string;
+    selected_candidate: SynthesizeCandidateSummary | null;
+    selected_command: string;
+    explore: {
+        endpoint_count: number;
+        api_endpoint_count: number;
+        capability_count: number;
+        top_strategy: string;
+        framework: Record<string, boolean>;
+    };
+    synthesize: {
+        candidate_count: number;
+        candidates: Array<Pick<SynthesizeCandidateSummary, 'name' | 'strategy' | 'confidence'>>;
+    };
+    register: RegisterCandidatesResult | null;
+}
+export declare function generateCliFromUrl(opts: GenerateCliOptions): Promise<GenerateCliResult>;
+export declare function renderGenerateSummary(r: GenerateCliResult): string;
+export {};

package/dist/generate.js

@@ -9,8 +9,9 @@
  */
 import { exploreUrl } from './explore.js';
 import { synthesizeFromExplore } from './synthesize.js';
-// TODO: implement real CLI registration (copy candidate YAML to user clis dir)
-function registerCandidates(_opts) { return { ok: true, count: 0 }; }
+function registerCandidates(_opts) {
+    return { ok: true, count: 0 };
+}
 const CAPABILITY_ALIASES = {
     search: ['search', '搜索', '查找', 'query', 'keyword'],
     hot: ['hot', '热门', '热榜', '热搜', 'popular', 'top', 'ranking'],
@@ -58,7 +59,7 @@ export async function generateCliFromUrl(opts) {
     const exploreResult = await exploreUrl(opts.url, {
         BrowserFactory: opts.BrowserFactory,
         site: opts.site,
-        goal: normalizeGoal(opts.goal) ?? opts.goal,
+        goal: normalizeGoal(opts.goal) ?? opts.goal ?? undefined,
         waitSeconds: opts.waitSeconds ?? 3,
         workspace: opts.workspace,
     });
@@ -68,7 +69,7 @@ export async function generateCliFromUrl(opts) {
     });
     // Step 3: Select best candidate for goal
     const selected = selectCandidate(synthesizeResult.candidates ?? [], opts.goal);
-    const selectedSite = selected?.site ?? synthesizeResult.site ?? exploreResult.site;
+    const selectedSite = synthesizeResult.site ?? exploreResult.site;
     // Step 4: Register (if requested)
     let registerResult = null;
     if (opts.register !== false && synthesizeResult.candidate_count > 0) {

package/dist/main.js

@@ -5,7 +5,7 @@
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { discoverClis } from './discovery.js';
+import { discoverClis, discoverPlugins } from './discovery.js';
 import { getCompletions } from './completion.js';
 import { runCli } from './cli.js';
 const __filename = fileURLToPath(import.meta.url);
@@ -13,6 +13,7 @@ const __dirname = path.dirname(__filename);
 const BUILTIN_CLIS = path.resolve(__dirname, 'clis');
 const USER_CLIS = path.join(os.homedir(), '.opencli', 'clis');
 await discoverClis(BUILTIN_CLIS, USER_CLIS);
+await discoverPlugins();
 // ── Fast-path: handle --get-completions before commander parses ─────────
 // Usage: opencli --get-completions --cursor <N> [word1 word2 ...]
 const getCompIdx = process.argv.indexOf('--get-completions');

package/dist/pipeline/executor.d.ts

@@ -3,7 +3,7 @@
  */
 import type { IPage } from '../types.js';
 export interface PipelineContext {
-    args?: Record<string, any>;
+    args?: Record<string, unknown>;
     debug?: boolean;
 }
-export declare function executePipeline(page: IPage | null, pipeline: any[], ctx?: PipelineContext): Promise<any>;
+export declare function executePipeline(page: IPage | null, pipeline: unknown[], ctx?: PipelineContext): Promise<unknown>;

package/dist/pipeline/executor.js

@@ -3,6 +3,7 @@
  */
 import { getStep } from './registry.js';
 import { log } from '../logger.js';
+import { ConfigError } from '../errors.js';
 export async function executePipeline(page, pipeline, ctx = {}) {
     const args = ctx.args ?? {};
     const debug = ctx.debug ?? false;
@@ -20,8 +21,7 @@ export async function executePipeline(page, pipeline, ctx = {}) {
                 data = await handler(page, params, data, args);
             }
             else {
-                if (debug)
-                    log.warn(`Unknown step: ${op}`);
+                throw new ConfigError(`Unknown pipeline step "${op}" at index ${i}.`, 'Check the YAML pipeline step name or register the custom step before execution.');
             }
             if (debug)
                 debugStepResult(op, data);

package/dist/pipeline/executor.test.js

@@ -3,6 +3,7 @@
  */
 import { describe, it, expect, vi } from 'vitest';
 import { executePipeline } from './index.js';
+import { ConfigError } from '../errors.js';
 /** Create a minimal mock page for testing */
 function createMockPage(overrides = {}) {
     return {
@@ -13,6 +14,7 @@ function createMockPage(overrides = {}) {
         click: vi.fn(),
         typeText: vi.fn(),
         pressKey: vi.fn(),
+        getFormState: vi.fn().mockResolvedValue({}),
         wait: vi.fn(),
         tabs: vi.fn().mockResolvedValue([]),
         closeTab: vi.fn(),
@@ -21,6 +23,7 @@ function createMockPage(overrides = {}) {
         networkRequests: vi.fn().mockResolvedValue([]),
         consoleMessages: vi.fn().mockResolvedValue(''),
         scroll: vi.fn(),
+        scrollTo: vi.fn(),
         autoScroll: vi.fn(),
         installInterceptor: vi.fn(),
         getInterceptedRequests: vi.fn().mockResolvedValue([]),
@@ -70,6 +73,30 @@ describe('executePipeline', () => {
             { name: 'World', score: 20 },
         ]);
     });
+    it('runs inline select inside map step', async () => {
+        const page = createMockPage({
+            evaluate: vi.fn().mockResolvedValue({
+                posts: [
+                    { title: 'First', rank: 1 },
+                    { title: 'Second', rank: 2 },
+                ],
+            }),
+        });
+        const result = await executePipeline(page, [
+            { evaluate: 'test' },
+            {
+                map: {
+                    select: 'posts',
+                    title: '${{ item.title }}',
+                    rank: '${{ item.rank }}',
+                },
+            },
+        ]);
+        expect(result).toEqual([
+            { title: 'First', rank: 1 },
+            { title: 'Second', rank: 2 },
+        ]);
+    });
     it('executes limit step', async () => {
         const page = createMockPage({
             evaluate: vi.fn().mockResolvedValue([1, 2, 3, 4, 5]),
@@ -107,13 +134,13 @@ describe('executePipeline', () => {
         ]);
         expect(page.wait).toHaveBeenCalledWith(2);
     });
-    it('handles unknown steps gracefully in debug mode', async () => {
-        const stderr = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
-        await executePipeline(null, [
+    it('fails fast on unknown steps', async () => {
+        await expect(executePipeline(null, [
+            { unknownStep: 'test' },
+        ], { debug: true })).rejects.toBeInstanceOf(ConfigError);
+        await expect(executePipeline(null, [
             { unknownStep: 'test' },
-        ], { debug: true });
-        expect(stderr).toHaveBeenCalledWith(expect.stringContaining('Unknown step'));
-        stderr.mockRestore();
+        ], { debug: true })).rejects.toThrow('Unknown pipeline step "unknownStep"');
     });
     it('passes args through template rendering', async () => {
         const page = createMockPage({

package/dist/pipeline/registry.d.ts

@@ -8,7 +8,7 @@ import type { IPage } from '../types.js';
  * TData is the type of the `data` state flowing into the step.
  * TResult is the expected return type.
  */
-export type StepHandler<TData = any, TResult = any> = (page: IPage | null, params: any, data: TData, args: Record<string, any>) => Promise<TResult>;
+export type StepHandler<TData = unknown, TResult = unknown, TParams = unknown> = (page: IPage | null, params: TParams, data: TData, args: Record<string, unknown>) => Promise<TResult>;
 /**
  * Get a registered step handler by name.
  */

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

@@ -3,10 +3,10 @@
  * Browser interaction primitives.
  */
 import type { IPage } from '../../types.js';
-export declare function stepNavigate(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any>;
-export declare function stepClick(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any>;
-export declare function stepType(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any>;
-export declare function stepWait(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any>;
-export declare function stepPress(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any>;
-export declare function stepSnapshot(page: IPage | null, params: any, _data: any, _args: Record<string, any>): Promise<any>;
-export declare function stepEvaluate(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any>;
+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 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>;
+export declare function stepEvaluate(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown>;

package/dist/pipeline/steps/browser.js

@@ -3,10 +3,13 @@
  * Browser interaction primitives.
  */
 import { render } from '../template.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 export async function stepNavigate(page, params, data, args) {
-    if (typeof params === 'object' && params && 'url' in params) {
+    if (isRecord(params) && 'url' in params) {
         const url = String(render(params.url, { args, data }));
-        await page.goto(url, { waitUntil: params.waitUntil, settleMs: params.settleMs });
+        await page.goto(url, { waitUntil: params.waitUntil, settleMs: typeof params.settleMs === 'number' ? params.settleMs : undefined });
     }
     else {
         const url = render(params, { args, data });
@@ -19,7 +22,7 @@ export async function stepClick(page, params, data, args) {
     return data;
 }
 export async function stepType(page, params, data, args) {
-    if (typeof params === 'object' && params) {
+    if (isRecord(params)) {
         const ref = String(render(params.ref ?? '', { args, data })).replace(/^@/, '');
         const text = String(render(params.text ?? '', { args, data }));
         await page.typeText(ref, text);
@@ -31,11 +34,11 @@ export async function stepType(page, params, data, args) {
 export async function stepWait(page, params, data, args) {
     if (typeof params === 'number')
         await page.wait(params);
-    else if (typeof params === 'object' && params) {
+    else if (isRecord(params)) {
         if ('text' in params) {
             await page.wait({
                 text: String(render(params.text, { args, data })),
-                timeout: params.timeout
+                timeout: typeof params.timeout === 'number' ? params.timeout : undefined,
             });
         }
         else if ('time' in params)
@@ -50,8 +53,13 @@ export async function stepPress(page, params, data, args) {
     return data;
 }
 export async function stepSnapshot(page, params, _data, _args) {
-    const opts = (typeof params === 'object' && params) ? params : {};
-    return page.snapshot({ interactive: opts.interactive ?? false, compact: opts.compact ?? false, maxDepth: opts.max_depth, raw: opts.raw ?? false });
+    const opts = isRecord(params) ? params : {};
+    return page.snapshot({
+        interactive: typeof opts.interactive === 'boolean' ? opts.interactive : false,
+        compact: typeof opts.compact === 'boolean' ? opts.compact : false,
+        maxDepth: typeof opts.max_depth === 'number' ? opts.max_depth : undefined,
+        raw: typeof opts.raw === 'boolean' ? opts.raw : false,
+    });
 }
 export async function stepEvaluate(page, params, data, args) {
     const js = String(render(params, { args, data }));

package/dist/pipeline/steps/fetch.d.ts

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

package/dist/pipeline/steps/fetch.js

@@ -2,6 +2,9 @@
  * Pipeline step: fetch — HTTP API requests.
  */
 import { render } from '../template.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 /** Simple async concurrency limiter */
 async function mapConcurrent(items, limit, fn) {
     const results = new Array(items.length);
@@ -53,7 +56,7 @@ async function fetchSingle(page, url, method, queryParams, headers, args, data)
 async function fetchBatchInBrowser(page, urls, method, headers, concurrency) {
     const headersJs = JSON.stringify(headers);
     const urlsJs = JSON.stringify(urls);
-    return page.evaluate(`
+    return (await page.evaluate(`
     async () => {
       const urls = ${urlsJs};
       const method = "${method}";
@@ -79,17 +82,18 @@ async function fetchBatchInBrowser(page, urls, method, headers, concurrency) {
       await Promise.all(workers);
       return results;
     }
-  `);
+  `));
 }
 export async function stepFetch(page, params, data, args) {
-    const urlOrObj = typeof params === 'string' ? params : (params?.url ?? '');
-    const method = params?.method ?? 'GET';
-    const queryParams = params?.params ?? {};
-    const headers = params?.headers ?? {};
+    const paramObject = isRecord(params) ? params : {};
+    const urlOrObj = typeof params === 'string' ? params : (paramObject.url ?? '');
+    const method = typeof paramObject.method === 'string' ? paramObject.method : 'GET';
+    const queryParams = isRecord(paramObject.params) ? paramObject.params : {};
+    const headers = isRecord(paramObject.headers) ? paramObject.headers : {};
     const urlTemplate = String(urlOrObj);
     // Per-item fetch when data is array and URL references item
     if (Array.isArray(data) && urlTemplate.includes('item')) {
-        const concurrency = typeof params?.concurrency === 'number' ? params.concurrency : 5;
+        const concurrency = typeof paramObject.concurrency === 'number' ? paramObject.concurrency : 5;
         // Render all URLs upfront
         const renderedHeaders = {};
         for (const [k, v] of Object.entries(headers))

package/dist/pipeline/steps/transform.d.ts

@@ -1,8 +1,9 @@
 /**
  * Pipeline steps: data transforms — select, map, filter, sort, limit.
  */
-export declare function stepSelect(_page: any, params: any, data: any, args: Record<string, any>): Promise<any>;
-export declare function stepMap(_page: any, params: any, data: any, args: Record<string, any>): Promise<any>;
-export declare function stepFilter(_page: any, params: any, data: any, args: Record<string, any>): Promise<any>;
-export declare function stepSort(_page: any, params: any, data: any, _args: Record<string, any>): Promise<any>;
-export declare function stepLimit(_page: any, params: any, data: any, args: Record<string, any>): Promise<any>;
+import type { IPage } from '../../types.js';
+export declare function stepSelect(_page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown>;
+export declare function stepMap(_page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown>;
+export declare function stepFilter(_page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown>;
+export declare function stepSort(_page: IPage | null, params: unknown, data: unknown, _args: Record<string, unknown>): Promise<unknown>;
+export declare function stepLimit(_page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown>;

package/dist/pipeline/steps/transform.js

@@ -2,12 +2,15 @@
  * Pipeline steps: data transforms — select, map, filter, sort, limit.
  */
 import { render, evalExpr } from '../template.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 export async function stepSelect(_page, params, data, args) {
     const pathStr = String(render(params, { args, data }));
     if (data && typeof data === 'object') {
         let current = data;
         for (const part of pathStr.split('.')) {
-            if (current && typeof current === 'object' && !Array.isArray(current))
+            if (isRecord(current))
                 current = current[part];
             else if (Array.isArray(current) && /^\d+$/.test(part))
                 current = current[parseInt(part, 10)];
@@ -21,15 +24,26 @@ export async function stepSelect(_page, params, data, args) {
 export async function stepMap(_page, params, data, args) {
     if (!data || typeof data !== 'object')
         return data;
-    let items = Array.isArray(data) ? data : [data];
-    if (!Array.isArray(data) && typeof data === 'object' && 'data' in data)
-        items = data.data;
+    let source = data;
+    // Support inline select: { map: { select: 'path', key: '${{ item.x }}' } }
+    if (isRecord(params) && 'select' in params) {
+        source = await stepSelect(null, params.select, data, args);
+    }
+    if (!source || typeof source !== 'object')
+        return source;
+    let items = Array.isArray(source) ? source : [source];
+    if (isRecord(source) && Array.isArray(source.data))
+        items = source.data;
     const result = [];
+    const templateParams = isRecord(params) ? params : {};
     for (let i = 0; i < items.length; i++) {
         const item = items[i];
         const row = {};
-        for (const [key, template] of Object.entries(params))
-            row[key] = render(template, { args, data, item, index: i });
+        for (const [key, template] of Object.entries(templateParams)) {
+            if (key === 'select')
+                continue;
+            row[key] = render(template, { args, data: source, item, index: i });
+        }
         result.push(row);
     }
     return result;
@@ -42,9 +56,16 @@ export async function stepFilter(_page, params, data, args) {
 export async function stepSort(_page, params, data, _args) {
     if (!Array.isArray(data))
         return data;
-    const key = typeof params === 'object' ? (params.by ?? '') : String(params);
-    const reverse = typeof params === 'object' ? params.order === 'desc' : false;
-    return [...data].sort((a, b) => { const va = a[key] ?? ''; const vb = b[key] ?? ''; const cmp = va < vb ? -1 : va > vb ? 1 : 0; return reverse ? -cmp : cmp; });
+    const key = isRecord(params) ? String(params.by ?? '') : String(params);
+    const reverse = isRecord(params) ? params.order === 'desc' : false;
+    return [...data].sort((a, b) => {
+        const left = isRecord(a) ? a[key] : undefined;
+        const right = isRecord(b) ? b[key] : undefined;
+        const va = left ?? '';
+        const vb = right ?? '';
+        const cmp = va < vb ? -1 : va > vb ? 1 : 0;
+        return reverse ? -cmp : cmp;
+    });
 }
 export async function stepLimit(_page, params, data, args) {
     if (!Array.isArray(data))

package/dist/pipeline/template.d.ts

@@ -2,14 +2,14 @@
  * Pipeline template engine: ${{ ... }} expression rendering.
  */
 export interface RenderContext {
-    args?: Record<string, any>;
-    data?: any;
-    item?: any;
+    args?: Record<string, unknown>;
+    data?: unknown;
+    item?: unknown;
     index?: number;
 }
-export declare function render(template: any, ctx: RenderContext): any;
-export declare function evalExpr(expr: string, ctx: RenderContext): any;
-export declare function resolvePath(pathStr: string, ctx: RenderContext): any;
+export declare function render(template: unknown, ctx: RenderContext): unknown;
+export declare function evalExpr(expr: string, ctx: RenderContext): unknown;
+export declare function resolvePath(pathStr: string, ctx: RenderContext): unknown;
 /**
  * Normalize JavaScript source for browser evaluate() calls.
  */

package/dist/pipeline/template.js

@@ -1,16 +1,20 @@
 /**
  * Pipeline template engine: ${{ ... }} expression rendering.
  */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 export function render(template, ctx) {
     if (typeof template !== 'string')
         return template;
+    const trimmed = template.trim();
     // Full expression: entire string is a single ${{ ... }}
     // Use [^}] to prevent matching across }} boundaries (e.g. "${{ a }}-${{ b }}")
-    const fullMatch = template.match(/^\$\{\{\s*([^}]*(?:\}[^}][^}]*)*)\s*\}\}$/);
-    if (fullMatch && !template.includes('}}-') && !template.includes('}}${{'))
+    const fullMatch = trimmed.match(/^\$\{\{\s*([^}]*(?:\}[^}][^}]*)*)\s*\}\}$/);
+    if (fullMatch && !trimmed.includes('}}-') && !trimmed.includes('}}${{'))
         return evalExpr(fullMatch[1].trim(), ctx);
     // Check if the entire string is a single expression (no other text around it)
-    const singleExpr = template.match(/^\$\{\{\s*([\s\S]*?)\s*\}\}$/);
+    const singleExpr = trimmed.match(/^\$\{\{\s*([\s\S]*?)\s*\}\}$/);
     if (singleExpr) {
         // Verify it's truly a single expression (no other ${{ inside)
         const inner = singleExpr[1];
@@ -62,7 +66,10 @@ export function evalExpr(expr, ctx) {
         const right = orMatch[2].trim();
         return right.replace(/^['"]|['"]$/g, '');
     }
-    return resolvePath(expr, { args, item, data, index });
+    const resolved = resolvePath(expr, { args, item, data, index });
+    if (resolved !== null && resolved !== undefined)
+        return resolved;
+    return evalJsExpr(expr, { args, item, data, index });
 }
 /**
  * Apply a named filter to a value.
@@ -142,6 +149,10 @@ function applyFilter(filterExpr, value) {
             const parts = value.split(/[/\\]/);
             return parts[parts.length - 1] || value;
         }
+        case 'urlencode':
+            return typeof value === 'string' ? encodeURIComponent(value) : value;
+        case 'urldecode':
+            return typeof value === 'string' ? decodeURIComponent(value) : value;
         default:
             return value;
     }
@@ -174,7 +185,7 @@ export function resolvePath(pathStr, ctx) {
         rest = parts;
     }
     for (const part of rest) {
-        if (obj && typeof obj === 'object' && !Array.isArray(obj))
+        if (isRecord(obj))
             obj = obj[part];
         else if (Array.isArray(obj) && /^\d+$/.test(part))
             obj = obj[parseInt(part, 10)];
@@ -183,6 +194,33 @@ export function resolvePath(pathStr, ctx) {
     }
     return obj;
 }
+/**
+ * Evaluate arbitrary JS expressions as a last-resort fallback.
+ *
+ * ⚠️  SECURITY NOTE: Uses `new Function()` to execute the expression.
+ * This is acceptable here because:
+ *   1. YAML adapters are authored by trusted repo contributors only.
+ *   2. The expression runs in the same Node.js process (no sandbox).
+ *   3. Only a curated set of globals is exposed (no require/import/process/fs).
+ * If opencli ever loads untrusted third-party adapters, this MUST be replaced
+ * with a proper sandboxed evaluator.
+ */
+function evalJsExpr(expr, ctx) {
+    // Guard against absurdly long expressions that could indicate injection.
+    if (expr.length > 2000)
+        return undefined;
+    const args = ctx.args ?? {};
+    const item = ctx.item ?? {};
+    const data = ctx.data;
+    const index = ctx.index ?? 0;
+    try {
+        const fn = new Function('args', 'item', 'data', 'index', 'encodeURIComponent', 'decodeURIComponent', 'JSON', 'Math', 'Number', 'String', 'Boolean', 'Array', 'Object', 'Date', `"use strict"; return (${expr});`);
+        return fn(args, item, data, index, encodeURIComponent, decodeURIComponent, JSON, Math, Number, String, Boolean, Array, Object, Date);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Normalize JavaScript source for browser evaluate() calls.
  */

package/dist/pipeline/template.test.js

@@ -54,6 +54,15 @@ describe('evalExpr', () => {
     it('resolves simple path', () => {
         expect(evalExpr('item.title', { item: { title: 'Test' } })).toBe('Test');
     });
+    it('evaluates JS helper expressions', () => {
+        expect(evalExpr('encodeURIComponent(args.keyword)', { args: { keyword: 'hello world' } })).toBe('hello%20world');
+    });
+    it('evaluates ternary expressions', () => {
+        expect(evalExpr("args.kind === 'tech' ? 'technology' : args.kind", { args: { kind: 'tech' } })).toBe('technology');
+    });
+    it('evaluates method calls on values', () => {
+        expect(evalExpr("args.username.startsWith('@') ? args.username : '@' + args.username", { args: { username: 'alice' } })).toBe('@alice');
+    });
     it('applies join filter', () => {
         expect(evalExpr('item.tags | join(,)', { item: { tags: ['a', 'b', 'c'] } })).toBe('a,b,c');
     });
@@ -100,6 +109,15 @@ describe('render', () => {
     it('renders URL template', () => {
         expect(render('https://api.example.com/search?q=${{ args.keyword }}', { args: { keyword: 'test' } })).toBe('https://api.example.com/search?q=test');
     });
+    it('renders inline helper expressions', () => {
+        expect(render('https://example.com/search?q=${{ encodeURIComponent(args.keyword) }}', { args: { keyword: 'hello world' } })).toBe('https://example.com/search?q=hello%20world');
+    });
+    it('renders full multiline expressions', () => {
+        expect(render("${{\n  args.topic ? `https://medium.com/tag/${args.topic}` : 'https://medium.com/tag/technology'\n}}", { args: { topic: 'ai' } })).toBe('https://medium.com/tag/ai');
+    });
+    it('renders block expressions with surrounding whitespace', () => {
+        expect(render("\n  ${{ args.kind === 'tech' ? 'technology' : args.kind }}\n", { args: { kind: 'tech' } })).toBe('technology');
+    });
 });
 describe('normalizeEvaluateSource', () => {
     it('wraps bare expression', () => {

package/dist/pipeline/transform.test.js

@@ -49,6 +49,17 @@ describe('stepMap', () => {
     it('returns null/undefined as-is', async () => {
         expect(await stepMap(null, { x: '${{ item.x }}' }, null, {})).toBeNull();
     });
+    it('supports inline select before mapping', async () => {
+        const result = await stepMap(null, {
+            select: 'posts',
+            title: '${{ item.title }}',
+            rank: '${{ index + 1 }}',
+        }, { posts: [{ title: 'One' }, { title: 'Two' }] }, {});
+        expect(result).toEqual([
+            { title: 'One', rank: 1 },
+            { title: 'Two', rank: 2 },
+        ]);
+    });
 });
 describe('stepFilter', () => {
     it('filters by expression', async () => {