publishport-opencli 1.8.4-pp.1

package/dist/src/pipeline/template.js

@@ -0,0 +1,338 @@
+/**
+ * Pipeline template engine: ${{ ... }} expression rendering.
+ */
+import vm from 'node:vm';
+import { isRecord } from '../utils.js';
+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 = 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 = trimmed.match(/^\$\{\{\s*([\s\S]*?)\s*\}\}$/);
+    if (singleExpr) {
+        // Verify it's truly a single expression (no other ${{ inside)
+        const inner = singleExpr[1];
+        if (!inner.includes('${{'))
+            return evalExpr(inner.trim(), ctx);
+    }
+    return template.replace(/\$\{\{\s*(.*?)\s*\}\}/g, (_m, expr) => String(evalExpr(expr.trim(), ctx)));
+}
+export function evalExpr(expr, ctx) {
+    const args = ctx.args ?? {};
+    const item = ctx.item ?? {};
+    const data = ctx.data;
+    const root = ctx.root;
+    const index = ctx.index ?? 0;
+    // ── Pipe filters: expr | filter1(arg) | filter2 ──
+    // Split on single | (not ||) so "item.a || item.b | upper" works correctly.
+    const pipeSegments = expr.split(/(?<!\|)\|(?!\|)/).map(s => s.trim());
+    if (pipeSegments.length > 1) {
+        let result = evalExpr(pipeSegments[0], ctx);
+        for (let i = 1; i < pipeSegments.length; i++) {
+            result = applyFilter(pipeSegments[i], result);
+        }
+        return result;
+    }
+    // Fast path: quoted string literal — skip VM overhead
+    const strLit = expr.match(/^(['"])(.*)\1$/);
+    if (strLit)
+        return strLit[2];
+    // Fast path: numeric literal
+    if (/^\d+(\.\d+)?$/.test(expr))
+        return Number(expr);
+    // Try resolving as a simple dotted path (item.foo.bar, args.limit, index)
+    const resolved = resolvePath(expr, { args, item, data, root, index });
+    if (resolved !== null && resolved !== undefined)
+        return resolved;
+    // Fallback: evaluate as JS in a sandboxed VM.
+    // Handles ||, ??, arithmetic, ternary, method calls, etc. natively.
+    return evalJsExpr(expr, { args, item, data, root, index });
+}
+/**
+ * Apply a named filter to a value.
+ * Supported filters:
+ *   default(val), join(sep), upper, lower, truncate(n), trim,
+ *   replace(old,new), keys, length, first, last, json
+ */
+function applyFilter(filterExpr, value) {
+    const match = filterExpr.match(/^(\w+)(?:\((.+)\))?$/);
+    if (!match)
+        return value;
+    const [, name, rawArgs] = match;
+    const filterArg = rawArgs?.replace(/^['"]|['"]$/g, '') ?? '';
+    switch (name) {
+        case 'default': {
+            if (value === null || value === undefined || value === '') {
+                const intVal = parseInt(filterArg, 10);
+                if (!Number.isNaN(intVal) && String(intVal) === filterArg.trim())
+                    return intVal;
+                return filterArg;
+            }
+            return value;
+        }
+        case 'join':
+            return Array.isArray(value) ? value.join(filterArg || ', ') : value;
+        case 'upper':
+            return typeof value === 'string' ? value.toUpperCase() : value;
+        case 'lower':
+            return typeof value === 'string' ? value.toLowerCase() : value;
+        case 'trim':
+            return typeof value === 'string' ? value.trim() : value;
+        case 'truncate': {
+            const n = parseInt(filterArg, 10) || 50;
+            return typeof value === 'string' && value.length > n ? `${value.slice(0, n)}...` : value;
+        }
+        case 'replace': {
+            if (typeof value !== 'string')
+                return value;
+            const parts = rawArgs?.split(',').map(s => s.trim().replace(/^['"]|['"]$/g, '')) ?? [];
+            return parts.length >= 2 ? value.replaceAll(parts[0], parts[1]) : value;
+        }
+        case 'keys':
+            return value && typeof value === 'object' ? Object.keys(value) : value;
+        case 'length':
+            return Array.isArray(value) ? value.length : typeof value === 'string' ? value.length : value;
+        case 'first':
+            return Array.isArray(value) ? value[0] : value;
+        case 'last':
+            return Array.isArray(value) ? value[value.length - 1] : value;
+        case 'json':
+            return JSON.stringify(value ?? null);
+        case 'slugify':
+            // Convert to URL-safe slug
+            return typeof value === 'string'
+                ? value
+                    .toLowerCase()
+                    .replace(/[^\p{L}\p{N}]+/gu, '-')
+                    .replace(/^-|-$/g, '')
+                : value;
+        case 'sanitize':
+            // Remove invalid filename characters
+            return typeof value === 'string'
+                // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional - strips C0 control chars from filenames
+                ? value.replace(/[<>:"/\\|?*\x00-\x1f]/g, '_')
+                : value;
+        case 'ext': {
+            // Extract file extension from URL or path
+            if (typeof value !== 'string')
+                return value;
+            const lastDot = value.lastIndexOf('.');
+            const lastSlash = Math.max(value.lastIndexOf('/'), value.lastIndexOf('\\'));
+            return lastDot > lastSlash ? value.slice(lastDot) : '';
+        }
+        case 'basename': {
+            // Extract filename from URL or path
+            if (typeof value !== 'string')
+                return 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;
+    }
+}
+export function resolvePath(pathStr, ctx) {
+    const args = ctx.args ?? {};
+    const item = ctx.item ?? {};
+    const data = ctx.data;
+    const root = ctx.root;
+    const index = ctx.index ?? 0;
+    const parts = pathStr.split('.');
+    const rootName = parts[0];
+    let obj;
+    let rest;
+    if (rootName === 'args') {
+        obj = args;
+        rest = parts.slice(1);
+    }
+    else if (rootName === 'item') {
+        obj = item;
+        rest = parts.slice(1);
+    }
+    else if (rootName === 'data') {
+        obj = data;
+        rest = parts.slice(1);
+    }
+    else if (rootName === 'root') {
+        obj = root;
+        rest = parts.slice(1);
+    }
+    else if (rootName === 'index')
+        return index;
+    else {
+        obj = item;
+        rest = parts;
+    }
+    for (const part of rest) {
+        if (isRecord(obj))
+            obj = obj[part];
+        else if (Array.isArray(obj) && /^\d+$/.test(part))
+            obj = obj[parseInt(part, 10)];
+        else
+            return null;
+    }
+    return obj;
+}
+/**
+ * Evaluate arbitrary JS expressions as a last-resort fallback.
+ * Runs inside a `node:vm` sandbox with dynamic code generation disabled.
+ *
+ * Compiled functions are cached by expression string to avoid re-creating
+ * VM contexts on every invocation — critical for loops where the same
+ * expression is evaluated hundreds of times.
+ */
+const FORBIDDEN_EXPR_PATTERNS = /\b(constructor|__proto__|prototype|globalThis|process|require|import|eval)\b/;
+/**
+ * Deep-copy plain data to sever prototype chains, preventing sandbox escape
+ * via `args.constructor.constructor('return process')()` etc.
+ *
+ * Uses a WeakMap cache keyed by object reference: when the same object
+ * (e.g. `args` or `data`) is passed repeatedly across loop iterations,
+ * the expensive JSON round-trip is performed only once. The WeakMap
+ * lets entries be GC'd when the source object is no longer referenced.
+ */
+/**
+ * Cache serialized JSON strings (not parsed objects) by source reference.
+ * Caching the parsed object would be unsafe: the VM sandbox could mutate it,
+ * and the polluted version would leak to subsequent calls. By caching the
+ * string and returning a fresh JSON.parse() each time, every evaluation gets
+ * its own clean deep-copy while still avoiding redundant JSON.stringify()
+ * for the same unchanged source object across loop iterations.
+ */
+const _sanitizeCache = new WeakMap();
+function sanitizeContext(obj) {
+    if (obj === null || obj === undefined)
+        return obj;
+    if (typeof obj !== 'object' && typeof obj !== 'function')
+        return obj;
+    const objRef = obj;
+    const cached = _sanitizeCache.get(objRef);
+    if (cached !== undefined)
+        return JSON.parse(cached);
+    try {
+        const jsonStr = JSON.stringify(obj);
+        _sanitizeCache.set(objRef, jsonStr);
+        return JSON.parse(jsonStr);
+    }
+    catch {
+        return {};
+    }
+}
+/** LRU-bounded cache for compiled VM scripts — prevents unbounded memory growth. */
+const MAX_VM_CACHE_SIZE = 256;
+const _vmCache = new Map();
+function getOrCompileScript(expr) {
+    let script = _vmCache.get(expr);
+    if (script)
+        return script;
+    // Evict oldest entry when cache is full
+    if (_vmCache.size >= MAX_VM_CACHE_SIZE) {
+        const firstKey = _vmCache.keys().next().value;
+        if (firstKey !== undefined)
+            _vmCache.delete(firstKey);
+    }
+    script = new vm.Script(`(${expr})`);
+    _vmCache.set(expr, script);
+    return script;
+}
+/**
+ * Reusable VM sandbox context.
+ *
+ * vm.createContext() is expensive (~0.3ms per call) because it creates a new
+ * V8 context with its own global object. In pipeline loops (map/filter over
+ * hundreds of items), this adds up to significant overhead.
+ *
+ * Instead, we create the context once and mutate the sandbox properties
+ * before each evaluation. This is safe because:
+ *   1. Sandbox properties are sanitized (deep-copied) before assignment
+ *   2. Scripts run with a 50ms timeout
+ *   3. codeGeneration is disabled (no eval/Function inside the sandbox)
+ */
+let _reusableSandbox = null;
+let _reusableContext = null;
+function getReusableContext() {
+    if (_reusableSandbox && _reusableContext) {
+        return { sandbox: _reusableSandbox, context: _reusableContext };
+    }
+    _reusableSandbox = {
+        args: {},
+        item: {},
+        data: null,
+        root: null,
+        index: 0,
+        encodeURIComponent,
+        decodeURIComponent,
+        JSON,
+        Math,
+        Number,
+        String,
+        Boolean,
+        Array,
+        Date,
+    };
+    _reusableContext = vm.createContext(_reusableSandbox, {
+        codeGeneration: { strings: false, wasm: false },
+    });
+    return { sandbox: _reusableSandbox, context: _reusableContext };
+}
+/** Properties that are part of the sandbox's initial shape and safe to keep. */
+const SANDBOX_WHITELIST = new Set([
+    'args', 'item', 'data', 'root', 'index',
+    'encodeURIComponent', 'decodeURIComponent',
+    'JSON', 'Math', 'Number', 'String', 'Boolean', 'Array', 'Date',
+]);
+function evalJsExpr(expr, ctx) {
+    // Guard against absurdly long expressions that could indicate injection.
+    if (expr.length > 2000)
+        return undefined;
+    // Block obvious sandbox escape attempts.
+    if (FORBIDDEN_EXPR_PATTERNS.test(expr))
+        return undefined;
+    try {
+        const script = getOrCompileScript(expr);
+        const { sandbox, context } = getReusableContext();
+        // Clean non-whitelisted properties that a previous script may have added.
+        // Without this, `${{ x = 42 }}` would leak `x` into subsequent evaluations.
+        for (const key of Object.keys(sandbox)) {
+            if (!SANDBOX_WHITELIST.has(key)) {
+                delete sandbox[key];
+            }
+        }
+        // Update mutable sandbox properties — sanitizeContext severs prototype chains.
+        sandbox.args = sanitizeContext(ctx.args ?? {});
+        sandbox.item = sanitizeContext(ctx.item ?? {});
+        sandbox.data = sanitizeContext(ctx.data);
+        sandbox.root = sanitizeContext(ctx.root);
+        sandbox.index = ctx.index ?? 0;
+        return script.runInContext(context, { timeout: 50 });
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Normalize JavaScript source for browser evaluate() calls.
+ */
+export function normalizeEvaluateSource(source) {
+    const stripped = source.trim();
+    if (!stripped)
+        return '() => undefined';
+    if (stripped.startsWith('(') && stripped.endsWith(')()'))
+        return `() => (${stripped})`;
+    if (/^(async\s+)?\([^)]*\)\s*=>/.test(stripped))
+        return stripped;
+    if (/^(async\s+)?[A-Za-z_][A-Za-z0-9_]*\s*=>/.test(stripped))
+        return stripped;
+    if (stripped.startsWith('function ') || stripped.startsWith('async function '))
+        return stripped;
+    return `() => (${stripped})`;
+}

package/dist/src/pipeline/template.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for the pipeline template engine: render, evalExpr, resolvePath.
+ */
+export {};

package/dist/src/pipeline/template.test.js

@@ -0,0 +1,175 @@
+/**
+ * Tests for the pipeline template engine: render, evalExpr, resolvePath.
+ */
+import { describe, it, expect } from 'vitest';
+import { render, evalExpr, resolvePath, normalizeEvaluateSource } from './template.js';
+describe('resolvePath', () => {
+    it('resolves args path', () => {
+        expect(resolvePath('args.limit', { args: { limit: 20 } })).toBe(20);
+    });
+    it('resolves nested args path', () => {
+        expect(resolvePath('args.query.keyword', { args: { query: { keyword: 'test' } } })).toBe('test');
+    });
+    it('resolves item path', () => {
+        expect(resolvePath('item.title', { item: { title: 'Hello' } })).toBe('Hello');
+    });
+    it('resolves implicit item path (no prefix)', () => {
+        expect(resolvePath('title', { item: { title: 'World' } })).toBe('World');
+    });
+    it('resolves index', () => {
+        expect(resolvePath('index', { index: 5 })).toBe(5);
+    });
+    it('resolves data path', () => {
+        expect(resolvePath('data.items', { data: { items: [1, 2, 3] } })).toEqual([1, 2, 3]);
+    });
+    it('resolves root path', () => {
+        expect(resolvePath('root.items', { root: { items: [1, 2, 3] } })).toEqual([1, 2, 3]);
+    });
+    it('returns null for missing path', () => {
+        expect(resolvePath('args.missing', { args: {} })).toBeUndefined();
+    });
+    it('resolves array index', () => {
+        expect(resolvePath('data.0', { data: ['a', 'b'] })).toBe('a');
+    });
+});
+describe('evalExpr', () => {
+    it('evaluates default filter', () => {
+        expect(evalExpr('args.limit | default(20)', { args: {} })).toBe(20);
+    });
+    it('uses actual value over default', () => {
+        expect(evalExpr('args.limit | default(20)', { args: { limit: 10 } })).toBe(10);
+    });
+    it('evaluates string default', () => {
+        expect(evalExpr("args.name | default('unknown')", { args: {} })).toBe('unknown');
+    });
+    it('evaluates arithmetic: index + 1', () => {
+        expect(evalExpr('index + 1', { index: 0 })).toBe(1);
+    });
+    it('evaluates arithmetic: index * 2', () => {
+        expect(evalExpr('index * 2', { index: 5 })).toBe(10);
+    });
+    it('evaluates || fallback', () => {
+        expect(evalExpr("item.name || 'N/A'", { item: {} })).toBe('N/A');
+    });
+    it('evaluates || with truthy left', () => {
+        expect(evalExpr("item.name || 'N/A'", { item: { name: 'Alice' } })).toBe('Alice');
+    });
+    it('evaluates chained || fallback (issue #303)', () => {
+        // When first two are falsy, should evaluate through to the string literal
+        expect(evalExpr("item.a || item.b || 'default'", { item: {} })).toBe('default');
+    });
+    it('evaluates chained || with middle value truthy', () => {
+        expect(evalExpr("item.a || item.b || 'default'", { item: { b: 'middle' } })).toBe('middle');
+    });
+    it('evaluates chained || with first value truthy', () => {
+        expect(evalExpr("item.a || item.b || 'default'", { item: { a: 'first', b: 'middle' } })).toBe('first');
+    });
+    it('evaluates || with 0 as falsy left (JS semantics)', () => {
+        expect(evalExpr("item.count || 'N/A'", { item: { count: 0 } })).toBe('N/A');
+    });
+    it('evaluates || with empty string as falsy left', () => {
+        expect(evalExpr("item.name || 'unknown'", { item: { name: '' } })).toBe('unknown');
+    });
+    it('evaluates || with numeric fallback returning number type', () => {
+        expect(evalExpr('item.a || 42', { item: {} })).toBe(42);
+    });
+    it('evaluates 4-way chained ||', () => {
+        expect(evalExpr("item.a || item.b || item.c || 'last'", { item: { c: 'third' } })).toBe('third');
+    });
+    it('handles || combined with pipe filter', () => {
+        expect(evalExpr("item.a || item.b | upper", { item: { b: 'hello' } })).toBe('HELLO');
+    });
+    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('rejects constructor-based sandbox escapes', () => {
+        expect(evalExpr("args['cons' + 'tructor']['constructor']('return process')()", { args: {} })).toBeUndefined();
+    });
+    it('applies join filter', () => {
+        expect(evalExpr('item.tags | join(,)', { item: { tags: ['a', 'b', 'c'] } })).toBe('a,b,c');
+    });
+    it('applies upper filter', () => {
+        expect(evalExpr('item.name | upper', { item: { name: 'hello' } })).toBe('HELLO');
+    });
+    it('applies lower filter', () => {
+        expect(evalExpr('item.name | lower', { item: { name: 'HELLO' } })).toBe('hello');
+    });
+    it('applies truncate filter', () => {
+        expect(evalExpr('item.text | truncate(5)', { item: { text: 'Hello World!' } })).toBe('Hello...');
+    });
+    it('chains filters', () => {
+        expect(evalExpr('item.name | upper | truncate(3)', { item: { name: 'hello' } })).toBe('HEL...');
+    });
+    it('applies length filter', () => {
+        expect(evalExpr('item.items | length', { item: { items: [1, 2, 3] } })).toBe(3);
+    });
+    it('applies json filter to strings with quotes', () => {
+        expect(evalExpr('args.keyword | json', { args: { keyword: "O'Reilly" } })).toBe('"O\'Reilly"');
+    });
+    it('applies json filter to nullish values', () => {
+        expect(evalExpr('args.keyword | json', { args: {} })).toBe('null');
+    });
+});
+describe('render', () => {
+    it('renders full expression', () => {
+        expect(render('${{ args.limit }}', { args: { limit: 30 } })).toBe(30);
+    });
+    it('renders inline expression in string', () => {
+        expect(render('Hello ${{ item.name }}!', { item: { name: 'World' } })).toBe('Hello World!');
+    });
+    it('renders multiple inline expressions', () => {
+        expect(render('${{ item.first }}-${{ item.second }}', { item: { first: 'X', second: 'Y' } })).toBe('X-Y');
+    });
+    it('returns non-string values as-is', () => {
+        expect(render(42, {})).toBe(42);
+        expect(render(null, {})).toBeNull();
+        expect(render(undefined, {})).toBeUndefined();
+    });
+    it('returns full expression result as native type', () => {
+        expect(render('${{ args.list }}', { args: { list: [1, 2, 3] } })).toEqual([1, 2, 3]);
+    });
+    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', () => {
+        expect(normalizeEvaluateSource('document.title')).toBe('() => (document.title)');
+    });
+    it('passes through arrow function', () => {
+        expect(normalizeEvaluateSource('() => 42')).toBe('() => 42');
+    });
+    it('passes through async arrow function', () => {
+        const src = 'async () => { return 1; }';
+        expect(normalizeEvaluateSource(src)).toBe(src);
+    });
+    it('passes through named function', () => {
+        const src = 'function foo() { return 1; }';
+        expect(normalizeEvaluateSource(src)).toBe(src);
+    });
+    it('wraps IIFE pattern', () => {
+        const src = '(async () => { return 1; })()';
+        expect(normalizeEvaluateSource(src)).toBe(`() => (${src})`);
+    });
+    it('handles empty string', () => {
+        expect(normalizeEvaluateSource('')).toBe('() => undefined');
+    });
+});

package/dist/src/pipeline/transform.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for pipeline transform steps: select, map, filter, sort, limit.
+ */
+export {};

package/dist/src/pipeline/transform.test.js

@@ -0,0 +1,133 @@
+/**
+ * Tests for pipeline transform steps: select, map, filter, sort, limit.
+ */
+import { describe, it, expect } from 'vitest';
+import { stepSelect, stepMap, stepFilter, stepSort, stepLimit } from './steps/transform.js';
+const SAMPLE_DATA = [
+    { title: 'Alpha', score: 10, author: 'Alice' },
+    { title: 'Beta', score: 30, author: 'Bob' },
+    { title: 'Gamma', score: 20, author: 'Charlie' },
+];
+describe('stepSelect', () => {
+    it('selects nested path', async () => {
+        const data = { result: { items: [1, 2, 3] } };
+        const result = await stepSelect(null, 'result.items', data, {});
+        expect(result).toEqual([1, 2, 3]);
+    });
+    it('selects array by index', async () => {
+        const data = { list: ['a', 'b', 'c'] };
+        const result = await stepSelect(null, 'list.1', data, {});
+        expect(result).toBe('b');
+    });
+    it('returns null for missing path', async () => {
+        const result = await stepSelect(null, 'missing.path', { foo: 1 }, {});
+        expect(result).toBeNull();
+    });
+    it('returns data as-is for non-object', async () => {
+        const result = await stepSelect(null, 'foo', 'string-data', {});
+        expect(result).toBe('string-data');
+    });
+});
+describe('stepMap', () => {
+    it('maps array items', async () => {
+        const result = await stepMap(null, {
+            name: '${{ item.title }}',
+            rank: '${{ index + 1 }}',
+        }, SAMPLE_DATA, {});
+        expect(result).toEqual([
+            { name: 'Alpha', rank: 1 },
+            { name: 'Beta', rank: 2 },
+            { name: 'Gamma', rank: 3 },
+        ]);
+    });
+    it('handles single object', async () => {
+        const result = await stepMap(null, {
+            name: '${{ item.title }}',
+        }, { title: 'Solo' }, {});
+        expect(result).toEqual([{ name: 'Solo' }]);
+    });
+    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 },
+        ]);
+    });
+    it('keeps data bound to the selected source and exposes root separately', async () => {
+        const result = await stepMap(null, {
+            select: 'bids',
+            bid_price: '${{ data[index][0] }}',
+            ask_price: '${{ root.asks[index][0] }}',
+        }, {
+            bids: [['100', '2'], ['99', '3']],
+            asks: [['101', '1'], ['102', '4']],
+        }, {});
+        expect(result).toEqual([
+            { bid_price: '100', ask_price: '101' },
+            { bid_price: '99', ask_price: '102' },
+        ]);
+    });
+});
+describe('stepFilter', () => {
+    it('filters by expression', async () => {
+        const result = await stepFilter(null, 'item.score', SAMPLE_DATA, {});
+        expect(result).toHaveLength(3); // all truthy
+    });
+    it('returns non-array as-is', async () => {
+        const result = await stepFilter(null, 'item.x', 'not-array', {});
+        expect(result).toBe('not-array');
+    });
+});
+describe('stepSort', () => {
+    it('sorts ascending by key', async () => {
+        const result = await stepSort(null, 'score', SAMPLE_DATA, {});
+        expect(result.map((r) => r.title)).toEqual(['Alpha', 'Gamma', 'Beta']);
+    });
+    it('sorts descending', async () => {
+        const result = await stepSort(null, { by: 'score', order: 'desc' }, SAMPLE_DATA, {});
+        expect(result.map((r) => r.title)).toEqual(['Beta', 'Gamma', 'Alpha']);
+    });
+    it('does not mutate original', async () => {
+        const original = [...SAMPLE_DATA];
+        await stepSort(null, 'score', SAMPLE_DATA, {});
+        expect(SAMPLE_DATA).toEqual(original);
+    });
+    it('sorts string-encoded numbers naturally by default', async () => {
+        const data = [
+            { name: 'A', volume: '99' },
+            { name: 'B', volume: '1000' },
+            { name: 'C', volume: '250' },
+        ];
+        const result = await stepSort(null, { by: 'volume', order: 'desc' }, data, {});
+        expect(result.map((r) => r.name)).toEqual(['B', 'C', 'A']);
+    });
+    it('handles missing fields gracefully', async () => {
+        const data = [
+            { name: 'A', value: '10' },
+            { name: 'B' },
+            { name: 'C', value: '5' },
+        ];
+        const result = await stepSort(null, { by: 'value', order: 'asc' }, data, {});
+        expect(result.map((r) => r.name)).toEqual(['B', 'C', 'A']);
+    });
+});
+describe('stepLimit', () => {
+    it('limits array to N items', async () => {
+        const result = await stepLimit(null, '2', SAMPLE_DATA, {});
+        expect(result).toHaveLength(2);
+    });
+    it('limits using template expression', async () => {
+        const result = await stepLimit(null, '${{ args.limit }}', SAMPLE_DATA, { limit: 1 });
+        expect(result).toHaveLength(1);
+    });
+    it('returns non-array as-is', async () => {
+        expect(await stepLimit(null, '5', 'string', {})).toBe('string');
+    });
+});