rowbound 1.0.2

package/dist/core/engine.js

@@ -0,0 +1,234 @@
+import vm from "node:vm";
+import { evaluateCondition, preCheckExpression } from "./condition.js";
+import { executeExecAction } from "./exec.js";
+import { extractValue } from "./extractor.js";
+import { httpRequest } from "./http-client.js";
+import { RateLimiter } from "./rate-limiter.js";
+import { resolveObject, resolveTemplate, } from "./template.js";
+import { executeWaterfall } from "./waterfall.js";
+/**
+ * Evaluate a JavaScript expression in a sandboxed context, returning the result as a string.
+ *
+ * WARNING: Node.js vm module is NOT a security boundary. The pre-check
+ * and Object.create(null) sandbox are defense-in-depth measures only.
+ * Do not rely on this for untrusted code execution.
+ *
+ * Unlike evaluateCondition (which coerces to boolean), this returns the raw value
+ * stringified — used for transform action expressions.
+ */
+export function evaluateExpression(expression, context) {
+    preCheckExpression(expression);
+    const rawSandbox = Object.create(null);
+    rawSandbox.row = { ...context.row };
+    rawSandbox.env = context.env;
+    rawSandbox.results = context.results ?? {};
+    const sandbox = vm.createContext(rawSandbox);
+    const result = vm.runInContext(expression, sandbox, { timeout: 100 });
+    if (result === undefined || result === null) {
+        return "";
+    }
+    if (typeof result === "object") {
+        return JSON.stringify(result);
+    }
+    return String(result);
+}
+/**
+ * Parse a range string like "2:50" into start/end indices (0-based data row indices).
+ * Range uses sheet row numbers (1-indexed, row 1 = headers, row 2 = first data row).
+ * So range "2:50" means data rows 0..48.
+ */
+function parseRange(range, totalRows) {
+    if (!range) {
+        return { start: 0, end: totalRows };
+    }
+    const parts = range.split(":");
+    if (parts.length !== 2) {
+        throw new Error(`Invalid range "${range}": expected format "start:end" (e.g. "2:50")`);
+    }
+    const sheetStart = parseInt(parts[0], 10);
+    const sheetEnd = parseInt(parts[1], 10);
+    if (Number.isNaN(sheetStart) || Number.isNaN(sheetEnd)) {
+        throw new Error(`Invalid range "${range}": start and end must be numbers`);
+    }
+    if (sheetStart < 1) {
+        throw new Error(`Invalid range "${range}": start must be >= 1 (got ${sheetStart})`);
+    }
+    if (sheetStart > sheetEnd) {
+        throw new Error(`Invalid range "${range}": start (${sheetStart}) must be <= end (${sheetEnd})`);
+    }
+    // Sheet row 2 = data row 0, sheet row 3 = data row 1, etc.
+    const start = Math.max(0, sheetStart - 2);
+    const end = Math.min(totalRows, sheetEnd - 1);
+    return { start, end };
+}
+/**
+ * Execute an HTTP action: resolve templates, make request, extract value.
+ */
+async function executeHttpAction(action, context, rateLimiter, retryAttempts, signal, retryBackoff, onMissing) {
+    const resolvedUrl = resolveTemplate(action.url, context, onMissing);
+    const resolvedHeaders = action.headers
+        ? resolveObject(action.headers, context, onMissing)
+        : undefined;
+    const resolvedBody = action.body !== undefined
+        ? resolveObject(action.body, context, onMissing)
+        : undefined;
+    const response = await httpRequest({
+        method: action.method,
+        url: resolvedUrl,
+        headers: resolvedHeaders,
+        body: resolvedBody,
+        retryAttempts,
+        retryBackoff,
+        onError: action.onError,
+        rateLimiter,
+        signal,
+    });
+    if (response === null) {
+        return null;
+    }
+    const value = extractValue(response.data, action.extract);
+    return value !== "" ? value : null;
+}
+/**
+ * Run the full pipeline: read rows, process each through actions, write results back.
+ *
+ * Execution flow per row:
+ * 1. Read row data (header -> value map)
+ * 2. For each action: evaluate condition, execute, update in-memory row state
+ * 3. Batch-write all cell updates for the row
+ * 4. Fire progress callbacks
+ */
+export async function runPipeline(options) {
+    const { adapter, ref, config, env, range, actionFilter, dryRun = false, signal, } = options;
+    // Read all rows from the sheet
+    const rows = await adapter.readRows(ref);
+    // Create rate limiter if configured
+    const rateLimiter = config.settings.rateLimit > 0
+        ? new RateLimiter(config.settings.rateLimit)
+        : undefined;
+    const retryAttempts = config.settings.retryAttempts ?? 0;
+    const retryBackoff = config.settings.retryBackoff;
+    // Deduplicate missing-variable warnings (warn once per unique source.key)
+    const warnedMissing = new Set();
+    const onMissing = (source, key) => {
+        const tag = `${source}.${key}`;
+        if (!warnedMissing.has(tag)) {
+            warnedMissing.add(tag);
+            console.warn(`Warning: template variable {{${tag}}} resolved to empty string (not found in context)`);
+        }
+    };
+    // Determine which actions to run
+    const actions = actionFilter
+        ? config.actions.filter((s) => s.id === actionFilter)
+        : config.actions;
+    // Parse range
+    const { start, end } = parseRange(range, rows.length);
+    // Notify caller of total rows to process (for progress display)
+    options.onTotalRows?.(end - start);
+    const result = {
+        totalRows: rows.length,
+        processedRows: 0,
+        skippedRows: 0,
+        errors: [],
+        updates: 0,
+    };
+    // Warn if concurrency > 1 since it's not yet implemented
+    if (config.settings.concurrency > 1) {
+        console.warn(`Warning: concurrency is set to ${config.settings.concurrency} but parallel row processing is not yet implemented. All rows will be processed sequentially (concurrency=1).`);
+    }
+    for (let i = start; i < end; i++) {
+        // Check abort signal between rows
+        if (signal?.aborted) {
+            break;
+        }
+        // Build ID-keyed row from name-keyed sheet data
+        const nameKeyedRow = rows[i];
+        const row = {};
+        if (options.columnMap) {
+            for (const [id, name] of Object.entries(options.columnMap)) {
+                if (nameKeyedRow[name] !== undefined) {
+                    row[id] = nameKeyedRow[name];
+                }
+            }
+        }
+        else {
+            // No column map — use name-keyed row directly (legacy/testing)
+            Object.assign(row, nameKeyedRow);
+        }
+        const rowUpdates = [];
+        options.onRowStart?.(i, row);
+        const context = { row, env };
+        for (const action of actions) {
+            // Check abort between actions (not just between rows)
+            if (signal?.aborted)
+                break;
+            try {
+                // Skip if target cell already has a value
+                if (row[action.target] !== undefined && row[action.target] !== "") {
+                    options.onActionComplete?.(i, action.id, null);
+                    continue;
+                }
+                // Evaluate `when` condition
+                if (!evaluateCondition(action.when, context)) {
+                    options.onActionComplete?.(i, action.id, null);
+                    continue;
+                }
+                let value = null;
+                if (action.type === "transform") {
+                    value = evaluateExpression(action.expression, context);
+                }
+                else if (action.type === "http") {
+                    value = await executeHttpAction(action, context, rateLimiter, retryAttempts, signal, retryBackoff, onMissing);
+                }
+                else if (action.type === "waterfall") {
+                    const waterfallResult = await executeWaterfall(action, context, {
+                        rateLimiter,
+                        retryAttempts,
+                        retryBackoff,
+                        signal,
+                        onMissing,
+                    });
+                    value = waterfallResult?.value ?? null;
+                }
+                else if (action.type === "exec") {
+                    value = await executeExecAction(action, context, {
+                        signal,
+                    });
+                }
+                if (value !== null) {
+                    // Update in-memory row so subsequent actions see new values (ID-keyed)
+                    row[action.target] = value;
+                    // Resolve target ID to column name for sheet write
+                    const columnName = options.columnMap?.[action.target] ?? action.target;
+                    // Sheet row = data index + 2 (row 1 is headers)
+                    rowUpdates.push({
+                        row: i + 2,
+                        column: columnName,
+                        value,
+                    });
+                }
+                options.onActionComplete?.(i, action.id, value);
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                result.errors.push({
+                    rowIndex: i,
+                    actionId: action.id,
+                    error: err.message,
+                });
+                options.onError?.(i, action.id, err);
+                options.onActionComplete?.(i, action.id, null);
+            }
+        }
+        // Write batch for this row
+        if (rowUpdates.length > 0 && !dryRun) {
+            await adapter.writeBatch(ref, rowUpdates);
+        }
+        result.updates += rowUpdates.length;
+        result.processedRows++;
+        options.onRowComplete?.(i, rowUpdates);
+    }
+    // Count skipped rows (rows outside the range)
+    result.skippedRows = rows.length - result.processedRows;
+    return result;
+}

package/dist/core/env.d.ts

@@ -0,0 +1,13 @@
+import type { PipelineConfig } from "./types.js";
+/**
+ * Build a filtered environment object that only includes safe variables.
+ *
+ * Instead of leaking all of process.env into the pipeline context, this
+ * function constructs a minimal env by:
+ * 1. Including all ROWBOUND_* prefixed vars
+ * 2. Scanning config template strings for {{env.X}} references and
+ *    including those specific keys from process.env
+ * 3. Including NODE_ENV if set
+ * 4. Including PATH so child processes can find executables
+ */
+export declare function buildSafeEnv(config?: PipelineConfig): Record<string, string>;

package/dist/core/env.js

@@ -0,0 +1,72 @@
+/**
+ * Build a filtered environment object that only includes safe variables.
+ *
+ * Instead of leaking all of process.env into the pipeline context, this
+ * function constructs a minimal env by:
+ * 1. Including all ROWBOUND_* prefixed vars
+ * 2. Scanning config template strings for {{env.X}} references and
+ *    including those specific keys from process.env
+ * 3. Including NODE_ENV if set
+ * 4. Including PATH so child processes can find executables
+ */
+export function buildSafeEnv(config) {
+    const env = {};
+    // 1. ROWBOUND_* prefixed vars
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value !== undefined && key.startsWith("ROWBOUND_")) {
+            env[key] = value;
+        }
+    }
+    // 2. NODE_ENV
+    if (process.env.NODE_ENV !== undefined) {
+        env.NODE_ENV = process.env.NODE_ENV;
+    }
+    // 3. PATH so child processes can find executables
+    if (process.env.PATH !== undefined) {
+        env.PATH = process.env.PATH;
+    }
+    // 4. Scan config templates for {{env.X}} references
+    if (config) {
+        const referencedKeys = extractEnvReferences(config);
+        for (const key of referencedKeys) {
+            if (process.env[key] !== undefined) {
+                env[key] = process.env[key];
+            }
+        }
+    }
+    return env;
+}
+/**
+ * Scan all template strings in a PipelineConfig for {{env.X}} patterns
+ * and return the set of referenced env var names.
+ */
+function extractEnvReferences(config) {
+    const keys = new Set();
+    const ENV_REGEX = /\{\{env\.([^}]+)\}\}/g;
+    function scanValue(value) {
+        if (typeof value === "string") {
+            for (const match of value.matchAll(ENV_REGEX)) {
+                keys.add(match[1]);
+            }
+        }
+        else if (Array.isArray(value)) {
+            for (const item of value) {
+                scanValue(item);
+            }
+        }
+        else if (value !== null && typeof value === "object") {
+            for (const v of Object.values(value)) {
+                scanValue(v);
+            }
+        }
+    }
+    // Scan top-level actions
+    scanValue(config.actions);
+    // Scan per-tab actions
+    if (config.tabs) {
+        for (const tab of Object.values(config.tabs)) {
+            scanValue(tab.actions);
+        }
+    }
+    return keys;
+}

package/dist/core/exec.d.ts

@@ -0,0 +1,24 @@
+import type { ExecAction, ExecutionContext } from "./types.js";
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/**
+ * Execute a shell command and capture its output.
+ *
+ * Uses execFile('/bin/sh', ['-c', command]) for shell features (pipes, env vars)
+ * while staying consistent with the codebase's execFile pattern.
+ */
+export declare function executeCommand(command: string, options?: {
+    timeout?: number;
+    signal?: AbortSignal;
+    env?: Record<string, string>;
+}): Promise<ExecResult>;
+/**
+ * Execute an exec action: resolve templates in the command, run it,
+ * optionally extract a value from JSON output, and handle errors.
+ */
+export declare function executeExecAction(action: ExecAction, context: ExecutionContext, options?: {
+    signal?: AbortSignal;
+}): Promise<string | null>;

package/dist/core/exec.js

@@ -0,0 +1,134 @@
+import { execFile } from "node:child_process";
+import { extractValue } from "./extractor.js";
+import { shellEscape } from "./shell-escape.js";
+import { resolveTemplateEscaped } from "./template.js";
+/**
+ * Execute a shell command and capture its output.
+ *
+ * Uses execFile('/bin/sh', ['-c', command]) for shell features (pipes, env vars)
+ * while staying consistent with the codebase's execFile pattern.
+ */
+export async function executeCommand(command, options = {}) {
+    const { timeout = 30_000, signal, env } = options;
+    return new Promise((resolve, reject) => {
+        const childEnv = env ?? {};
+        const child = execFile("/bin/sh", ["-c", command], {
+            timeout,
+            signal,
+            env: childEnv,
+            maxBuffer: 10 * 1024 * 1024, // 10MB
+        }, (error, stdout, stderr) => {
+            if (error) {
+                // Cast to access killed and code properties from ExecException
+                const execError = error;
+                // Check if it was killed by timeout or signal
+                if (execError.killed || error.message?.includes("TIMEOUT")) {
+                    reject(new Error(`Command timed out after ${timeout}ms`));
+                    return;
+                }
+                // If signal was aborted
+                if (signal?.aborted) {
+                    reject(new Error("Command aborted"));
+                    return;
+                }
+                // Non-zero exit code — resolve with the exit code and captured output
+                resolve({
+                    stdout: String(stdout ?? ""),
+                    stderr: String(stderr ?? ""),
+                    exitCode: typeof execError.code === "number" ? execError.code : 1,
+                });
+                return;
+            }
+            resolve({
+                stdout: String(stdout),
+                stderr: String(stderr),
+                exitCode: 0,
+            });
+        });
+        // Handle abort signal — kill the entire process group so grandchildren
+        // (e.g. headless Claude) are also terminated, not just the /bin/sh wrapper.
+        if (signal) {
+            signal.addEventListener("abort", () => {
+                try {
+                    if (child.pid) {
+                        process.kill(-child.pid, "SIGTERM");
+                    }
+                }
+                catch {
+                    child.kill();
+                }
+            }, { once: true });
+        }
+    });
+}
+/**
+ * Resolve the onError action for a given exit code.
+ * Checks the specific exit code first, then falls back to "default".
+ */
+function resolveErrorAction(onError, exitCode) {
+    if (!onError)
+        return undefined;
+    const codeKey = String(exitCode);
+    if (codeKey in onError) {
+        return onError[codeKey];
+    }
+    if ("default" in onError) {
+        return onError.default;
+    }
+    return undefined;
+}
+/**
+ * Apply the resolved error action, returning a fallback value or throwing.
+ */
+function applyErrorAction(action, exitCode, stderr) {
+    if (action === undefined) {
+        throw new Error(`Command failed with exit code ${exitCode}${stderr ? `: ${stderr.trim()}` : ""}`);
+    }
+    if (action === "skip") {
+        return null;
+    }
+    if (typeof action === "object" && "write" in action) {
+        return action.write;
+    }
+    // Unknown action — treat as skip
+    return null;
+}
+/**
+ * Execute an exec action: resolve templates in the command, run it,
+ * optionally extract a value from JSON output, and handle errors.
+ */
+export async function executeExecAction(action, context, options = {}) {
+    const resolvedCommand = resolveTemplateEscaped(action.command, context, shellEscape);
+    let result;
+    try {
+        result = await executeCommand(resolvedCommand, {
+            timeout: action.timeout,
+            signal: options.signal,
+            env: context.env,
+        });
+    }
+    catch (error) {
+        // Timeout or abort errors
+        const errorAction = resolveErrorAction(action.onError, 1);
+        return applyErrorAction(errorAction, 1, error instanceof Error ? error.message : String(error));
+    }
+    // Non-zero exit code
+    if (result.exitCode !== 0) {
+        const errorAction = resolveErrorAction(action.onError, result.exitCode);
+        return applyErrorAction(errorAction, result.exitCode, result.stderr);
+    }
+    // Success — extract or return raw stdout
+    if (action.extract) {
+        let parsed;
+        try {
+            parsed = JSON.parse(result.stdout);
+        }
+        catch {
+            throw new Error(`Exec action "${action.id}": output is not valid JSON for extraction`);
+        }
+        const value = extractValue(parsed, action.extract);
+        return value !== "" ? value : null;
+    }
+    const trimmed = result.stdout.trim();
+    return trimmed !== "" ? trimmed : null;
+}

package/dist/core/extractor.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Extract a value from data using a JSONPath expression.
+ *
+ * - Applies the JSONPath expression to the input data
+ * - Arrays: takes the first element
+ * - Objects: JSON.stringify
+ * - Coerces the final result to string
+ * - Returns empty string if no match
+ */
+export declare function extractValue(data: unknown, expression: string): string;

package/dist/core/extractor.js

@@ -0,0 +1,33 @@
+import { JSONPath } from "jsonpath-plus";
+/**
+ * Extract a value from data using a JSONPath expression.
+ *
+ * - Applies the JSONPath expression to the input data
+ * - Arrays: takes the first element
+ * - Objects: JSON.stringify
+ * - Coerces the final result to string
+ * - Returns empty string if no match
+ */
+export function extractValue(data, expression) {
+    let result;
+    try {
+        result = JSONPath({ path: expression, json: data, eval: false });
+    }
+    catch {
+        return "";
+    }
+    // JSONPath always returns an array of matches
+    if (Array.isArray(result)) {
+        if (result.length === 0) {
+            return "";
+        }
+        result = result[0];
+    }
+    if (result === undefined || result === null) {
+        return "";
+    }
+    if (typeof result === "object") {
+        return JSON.stringify(result);
+    }
+    return String(result);
+}

package/dist/core/http-client.d.ts

@@ -0,0 +1,32 @@
+import type { RateLimiter } from "./rate-limiter.js";
+import type { OnErrorConfig } from "./types.js";
+/** Options for httpRequest */
+export interface HttpRequestOptions {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    retryAttempts?: number;
+    retryBackoff?: string;
+    onError?: OnErrorConfig;
+    rateLimiter?: RateLimiter;
+    signal?: AbortSignal;
+}
+/** Successful HTTP response */
+export interface HttpResponse {
+    status: number;
+    data: unknown;
+}
+/** Thrown when onError config specifies "stop_provider" */
+export declare class StopProviderError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Make an HTTP request with retry, rate limiting, and structured error handling.
+ *
+ * - Acquires a rate limiter token before each request attempt
+ * - Retries on 429/5xx with exponential backoff
+ * - Applies onError config for non-retryable errors or exhausted retries
+ * - Respects AbortSignal for cancellation
+ */
+export declare function httpRequest(options: HttpRequestOptions): Promise<HttpResponse | null>;