rowbound 1.0.2

package/dist/core/run-format.js

@@ -0,0 +1,201 @@
+/**
+ * Format milliseconds as a human-readable duration.
+ * Examples: "12s", "1m30s", "2h5m"
+ */
+export function formatDuration(ms) {
+    const totalSeconds = Math.floor(ms / 1000);
+    if (totalSeconds < 1) {
+        return "<1s";
+    }
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    if (hours > 0) {
+        return minutes > 0 ? `${hours}h${minutes}m` : `${hours}h`;
+    }
+    if (minutes > 0) {
+        return seconds > 0 ? `${minutes}m${seconds}s` : `${minutes}m`;
+    }
+    return `${seconds}s`;
+}
+/**
+ * Format an ISO date as a relative "age" string.
+ * Examples: "just now", "5m ago", "2h ago", "3d ago", or "running" if status is running.
+ */
+export function formatAge(isoDate, status) {
+    if (status === "running") {
+        return "running";
+    }
+    const then = new Date(isoDate).getTime();
+    const now = Date.now();
+    const diffMs = now - then;
+    const diffSeconds = Math.floor(diffMs / 1000);
+    if (diffSeconds < 60) {
+        return "just now";
+    }
+    const diffMinutes = Math.floor(diffSeconds / 60);
+    if (diffMinutes < 60) {
+        return `${diffMinutes}m ago`;
+    }
+    const diffHours = Math.floor(diffMinutes / 60);
+    if (diffHours < 24) {
+        return `${diffHours}h ago`;
+    }
+    const diffDays = Math.floor(diffHours / 24);
+    return `${diffDays}d ago`;
+}
+/** Get status icon for a run */
+function statusIcon(run) {
+    switch (run.status) {
+        case "completed":
+            return run.errors.length === 0 ? "\u2713" : "\u2717";
+        case "failed":
+            return "\u2717";
+        case "running":
+            return "\u231b";
+        case "aborted":
+            return "\u2298";
+        default:
+            return "?";
+    }
+}
+/** Get display name for a sheet */
+function sheetDisplayName(run) {
+    if (run.sheetName) {
+        return run.sheetName;
+    }
+    return run.sheetId.length > 12 ? run.sheetId.slice(0, 12) : run.sheetId;
+}
+/**
+ * Format a list of runs as a compact table.
+ *
+ * ```
+ * STATUS  RUN       SHEET        ROWS      UPDATES  ERRORS  DURATION  AGE
+ * ✓       a1b2c3    EliteCart    30/30     28       0       12s       5m ago
+ * ```
+ */
+export function formatRunList(runs) {
+    if (runs.length === 0) {
+        return "No runs found.";
+    }
+    const rows = [];
+    rows.push([
+        "STATUS",
+        "RUN",
+        "SHEET",
+        "ROWS",
+        "UPDATES",
+        "ERRORS",
+        "DURATION",
+        "AGE",
+    ]);
+    for (const run of runs) {
+        const icon = statusIcon(run);
+        const totalUpdates = run.actionSummaries.reduce((sum, s) => sum + s.success, 0);
+        const totalErrors = run.errors.length;
+        const duration = run.durationMs !== undefined ? formatDuration(run.durationMs) : "-";
+        const age = formatAge(run.startedAt, run.status);
+        const rowCount = run.totalRows > 0
+            ? `${run.processedRows}/${run.totalRows}`
+            : `${run.processedRows}`;
+        rows.push([
+            icon,
+            run.runId,
+            sheetDisplayName(run),
+            rowCount,
+            String(totalUpdates),
+            String(totalErrors),
+            duration,
+            age,
+        ]);
+    }
+    // Calculate column widths
+    const colWidths = rows[0].map((_, colIndex) => Math.max(...rows.map((row) => row[colIndex].length)));
+    // Format each row with padding
+    return rows
+        .map((row) => row.map((cell, i) => cell.padEnd(colWidths[i])).join("  "))
+        .join("\n");
+}
+/** Action status icon: ✓ (0 errors), ✗ (has errors), ⚠ (has skips but no errors) */
+function actionStatusIcon(action) {
+    if (action.errors > 0)
+        return "\u2717";
+    if (action.skipped > 0)
+        return "\u26a0";
+    return "\u2713";
+}
+/**
+ * Format a detailed view of a single run.
+ *
+ * ```
+ * ✗ Run d4e5f6 · LeadList
+ *   Sheet: 1xABC...def · Started: 2h ago · Duration: 45s
+ *
+ * ACTIONS
+ *   extract_domain    ✓ 150/150
+ *   enrich_company    ✗ 147/150 (3 errors)
+ *   find_email        ⚠ 120/147 (27 skipped)
+ *
+ * ERRORS (3)
+ *   Row 45   enrich_company   429 Too Many Requests (retries exhausted)
+ *   Row 89   enrich_company   timeout after 30s
+ *   Row 102  enrich_company   404 → wrote "not_found"
+ * ```
+ */
+export function formatRunDetail(run, errorsOnly = false) {
+    const lines = [];
+    if (!errorsOnly) {
+        // Header
+        const icon = statusIcon(run);
+        const name = sheetDisplayName(run);
+        lines.push(`${icon} Run ${run.runId} \u00b7 ${name}`);
+        const sheetLabel = run.sheetId.length > 12
+            ? `${run.sheetId.slice(0, 6)}...${run.sheetId.slice(-3)}`
+            : run.sheetId;
+        const age = formatAge(run.startedAt, run.status);
+        const duration = run.durationMs !== undefined ? formatDuration(run.durationMs) : "-";
+        lines.push(`  Sheet: ${sheetLabel} \u00b7 Started: ${age} \u00b7 Duration: ${duration}`);
+        if (run.dryRun) {
+            lines.push("  Mode: DRY RUN");
+        }
+        // Actions
+        if (run.actionSummaries.length > 0) {
+            lines.push("");
+            lines.push("ACTIONS");
+            // Calculate widths for alignment
+            const actionIdWidth = Math.max(...run.actionSummaries.map((s) => s.actionId.length));
+            for (const action of run.actionSummaries) {
+                const total = action.success + action.skipped + action.errors;
+                const icon = actionStatusIcon(action);
+                const details = [];
+                if (action.errors > 0) {
+                    details.push(`${action.errors} errors`);
+                }
+                if (action.skipped > 0) {
+                    details.push(`${action.skipped} skipped`);
+                }
+                const suffix = details.length > 0 ? ` (${details.join(", ")})` : "";
+                lines.push(`  ${action.actionId.padEnd(actionIdWidth)}  ${icon} ${action.success}/${total}${suffix}`);
+            }
+        }
+    }
+    // Errors section
+    if (run.errors.length > 0) {
+        if (!errorsOnly) {
+            lines.push("");
+        }
+        lines.push(`ERRORS (${run.errors.length})`);
+        // Calculate widths for alignment
+        const rowWidth = Math.max(...run.errors.map((e) => `Row ${e.rowIndex}`.length));
+        const actionWidth = Math.max(...run.errors.map((e) => e.actionId.length));
+        for (const error of run.errors) {
+            const rowLabel = `Row ${error.rowIndex}`.padEnd(rowWidth);
+            const actionLabel = error.actionId.padEnd(actionWidth);
+            lines.push(`  ${rowLabel}  ${actionLabel}  ${error.error}`);
+        }
+    }
+    else if (errorsOnly) {
+        lines.push("No errors.");
+    }
+    return lines.join("\n");
+}

package/dist/core/run-state.d.ts

@@ -0,0 +1,64 @@
+import type { PipelineConfig } from "./types.js";
+export interface ActionSummary {
+    actionId: string;
+    type: string;
+    target: string;
+    success: number;
+    skipped: number;
+    errors: number;
+}
+export interface RunError {
+    rowIndex: number;
+    actionId: string;
+    error: string;
+}
+export interface RunState {
+    runId: string;
+    sheetId: string;
+    sheetName?: string;
+    status: "running" | "completed" | "failed" | "aborted";
+    startedAt: string;
+    completedAt?: string;
+    durationMs?: number;
+    dryRun: boolean;
+    totalRows: number;
+    processedRows: number;
+    actionSummaries: ActionSummary[];
+    errors: RunError[];
+    settings: {
+        range?: string;
+        actionFilter?: string;
+        rateLimit: number;
+        retryAttempts: number;
+    };
+}
+/**
+ * Override the runs directory (for testing).
+ * Pass undefined to reset to default.
+ */
+export declare function setRunsDir(dir: string | undefined): void;
+/** Get the runs directory path, creating it if needed */
+export declare function getRunsDir(): Promise<string>;
+/** Generate a short run ID (8 chars, random hex) */
+export declare function generateRunId(): string;
+/** Write run state to disk */
+export declare function writeRunState(state: RunState): Promise<void>;
+/** Read a specific run state */
+export declare function readRunState(runId: string): Promise<RunState | null>;
+/** List all runs, sorted by startedAt descending (most recent first) */
+export declare function listRuns(options?: {
+    sheetId?: string;
+    limit?: number;
+}): Promise<RunState[]>;
+/** Delete old runs, keeping the most recent N. Returns number deleted. */
+export declare function pruneRuns(keep: number): Promise<number>;
+/** Create a fresh RunState for a new pipeline run */
+export declare function createRunState(options: {
+    sheetId: string;
+    sheetName?: string;
+    config: PipelineConfig;
+    totalRows: number;
+    dryRun: boolean;
+    range?: string;
+    actionFilter?: string;
+}): RunState;

package/dist/core/run-state.js

@@ -0,0 +1,141 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+/** Validate that a runId is a legitimate 8-char hex string (prevents path traversal) */
+function validateRunId(runId) {
+    if (!/^[a-f0-9]{8}$/.test(runId)) {
+        throw new Error(`Invalid run ID "${runId}". Expected 8-character hex string.`);
+    }
+}
+/** Default runs directory under ~/.rowbound/runs */
+let overrideRunsDir;
+/**
+ * Override the runs directory (for testing).
+ * Pass undefined to reset to default.
+ */
+export function setRunsDir(dir) {
+    overrideRunsDir = dir;
+}
+/** Get the runs directory path, creating it if needed */
+export async function getRunsDir() {
+    const dir = overrideRunsDir ?? path.join(os.homedir(), ".rowbound", "runs");
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}
+/** Generate a short run ID (8 chars, random hex) */
+export function generateRunId() {
+    return crypto.randomBytes(4).toString("hex");
+}
+/** Write run state to disk */
+export async function writeRunState(state) {
+    validateRunId(state.runId);
+    const filePath = path.join(await getRunsDir(), `${state.runId}.json`);
+    await fs.writeFile(filePath, JSON.stringify(state, null, 2), {
+        mode: 0o600,
+    });
+}
+/** Read a specific run state */
+export async function readRunState(runId) {
+    validateRunId(runId);
+    const filePath = path.join(await getRunsDir(), `${runId}.json`);
+    try {
+        const data = await fs.readFile(filePath, "utf-8");
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+/** List all runs, sorted by startedAt descending (most recent first) */
+export async function listRuns(options) {
+    const dir = await getRunsDir();
+    const limit = options?.limit ?? 20;
+    let files;
+    try {
+        files = (await fs.readdir(dir)).filter((f) => f.endsWith(".json"));
+    }
+    catch {
+        return [];
+    }
+    const runs = [];
+    for (const file of files) {
+        try {
+            const data = await fs.readFile(path.join(dir, file), "utf-8");
+            const state = JSON.parse(data);
+            if (options?.sheetId && state.sheetId !== options.sheetId) {
+                continue;
+            }
+            runs.push(state);
+        }
+        catch {
+            // Skip corrupted files
+        }
+    }
+    runs.sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
+    return runs.slice(0, limit);
+}
+/** Delete old runs, keeping the most recent N. Returns number deleted. */
+export async function pruneRuns(keep) {
+    const dir = await getRunsDir();
+    let files;
+    try {
+        files = (await fs.readdir(dir)).filter((f) => f.endsWith(".json"));
+    }
+    catch {
+        return 0;
+    }
+    // Read and sort all runs by startedAt descending
+    const runs = [];
+    for (const file of files) {
+        try {
+            const data = await fs.readFile(path.join(dir, file), "utf-8");
+            const state = JSON.parse(data);
+            runs.push({ file, startedAt: state.startedAt });
+        }
+        catch {
+            // Corrupted files get deleted
+            runs.push({ file, startedAt: "" });
+        }
+    }
+    runs.sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
+    let deleted = 0;
+    for (let i = keep; i < runs.length; i++) {
+        try {
+            await fs.unlink(path.join(dir, runs[i].file));
+            deleted++;
+        }
+        catch {
+            // Ignore deletion errors
+        }
+    }
+    return deleted;
+}
+/** Create a fresh RunState for a new pipeline run */
+export function createRunState(options) {
+    return {
+        runId: generateRunId(),
+        sheetId: options.sheetId,
+        sheetName: options.sheetName,
+        status: "running",
+        startedAt: new Date().toISOString(),
+        dryRun: options.dryRun,
+        totalRows: options.totalRows,
+        processedRows: 0,
+        actionSummaries: options.config.actions.map((action) => ({
+            actionId: action.id,
+            type: action.type,
+            target: action.target,
+            success: 0,
+            skipped: 0,
+            errors: 0,
+        })),
+        errors: [],
+        settings: {
+            range: options.range,
+            actionFilter: options.actionFilter,
+            rateLimit: options.config.settings.rateLimit,
+            retryAttempts: options.config.settings.retryAttempts,
+        },
+    };
+}

package/dist/core/run-tracker.d.ts

@@ -0,0 +1,15 @@
+import type { RunPipelineOptions } from "./engine.js";
+import type { RunState } from "./run-state.js";
+/**
+ * Create callback hooks that track run state and write to disk.
+ *
+ * The returned callbacks should be composed with any user-provided callbacks,
+ * not replace them.
+ */
+export declare function createRunTracker(state: RunState): {
+    onRowStart: NonNullable<RunPipelineOptions["onRowStart"]>;
+    onActionComplete: NonNullable<RunPipelineOptions["onActionComplete"]>;
+    onError: NonNullable<RunPipelineOptions["onError"]>;
+    onRowComplete: NonNullable<RunPipelineOptions["onRowComplete"]>;
+    finalize: (aborted: boolean) => Promise<void>;
+};

package/dist/core/run-tracker.js

@@ -0,0 +1,57 @@
+import { pruneRuns, writeRunState } from "./run-state.js";
+/**
+ * Create callback hooks that track run state and write to disk.
+ *
+ * The returned callbacks should be composed with any user-provided callbacks,
+ * not replace them.
+ */
+export function createRunTracker(state) {
+    const startTime = Date.now();
+    return {
+        onRowStart: (_rowIndex, _row) => {
+            // No-op — reserved for future row-level tracking
+        },
+        onActionComplete: (_rowIndex, actionId, value) => {
+            const action = state.actionSummaries.find((s) => s.actionId === actionId);
+            if (!action)
+                return;
+            if (value !== null) {
+                action.success++;
+            }
+            else {
+                action.skipped++;
+            }
+        },
+        onError: (rowIndex, actionId, error) => {
+            const action = state.actionSummaries.find((s) => s.actionId === actionId);
+            if (action) {
+                action.errors++;
+            }
+            state.errors.push({
+                rowIndex: rowIndex + 2, // Convert 0-indexed data row to sheet row number
+                actionId,
+                error: error.message,
+            });
+        },
+        onRowComplete: (_rowIndex, _updates) => {
+            state.processedRows++;
+            // Fire-and-forget: checkpoint save after each row (best-effort)
+            writeRunState(state).catch(() => { });
+        },
+        finalize: async (aborted) => {
+            if (aborted) {
+                state.status = "aborted";
+            }
+            else if (state.errors.length > 0 && state.processedRows === 0) {
+                state.status = "failed";
+            }
+            else {
+                state.status = "completed";
+            }
+            state.completedAt = new Date().toISOString();
+            state.durationMs = Date.now() - startTime;
+            await writeRunState(state);
+            await pruneRuns(50);
+        },
+    };
+}

package/dist/core/safe-compare.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Constant-time string comparison to prevent timing attacks on secret tokens.
+ *
+ * Uses crypto.timingSafeEqual under the hood. When lengths differ, we still
+ * compare against a same-length dummy to avoid leaking length information
+ * through early return timing.
+ */
+export declare function safeCompare(a: string, b: string): boolean;

package/dist/core/safe-compare.js

@@ -0,0 +1,19 @@
+import { timingSafeEqual } from "node:crypto";
+/**
+ * Constant-time string comparison to prevent timing attacks on secret tokens.
+ *
+ * Uses crypto.timingSafeEqual under the hood. When lengths differ, we still
+ * compare against a same-length dummy to avoid leaking length information
+ * through early return timing.
+ */
+export function safeCompare(a, b) {
+    const bufA = Buffer.from(a, "utf-8");
+    const bufB = Buffer.from(b, "utf-8");
+    if (bufA.length !== bufB.length) {
+        // Compare bufA against itself to burn the same amount of time,
+        // then return false. This avoids leaking length information.
+        timingSafeEqual(bufA, bufA);
+        return false;
+    }
+    return timingSafeEqual(bufA, bufB);
+}

package/dist/core/shell-escape.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Escape a string for safe use in shell commands.
+ *
+ * Wraps the value in single quotes and escapes any embedded single quotes.
+ * This prevents shell injection via metacharacters like $(), backticks, ;, |, etc.
+ */
+export declare function shellEscape(value: string): string;

package/dist/core/shell-escape.js

@@ -0,0 +1,9 @@
+/**
+ * Escape a string for safe use in shell commands.
+ *
+ * Wraps the value in single quotes and escapes any embedded single quotes.
+ * This prevents shell injection via metacharacters like $(), backticks, ;, |, etc.
+ */
+export function shellEscape(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}

package/dist/core/tab-resolver.d.ts

@@ -0,0 +1,17 @@
+import type { PipelineConfig, TabConfig } from "./types.js";
+/**
+ * Resolve a tab by name in a v2 config.
+ * Returns the GID key and TabConfig, or null if not found.
+ */
+export declare function resolveTabGid(config: PipelineConfig, tabName: string): {
+    gid: string;
+    tab: TabConfig;
+} | null;
+/**
+ * Get the tab config for a given tab name, handling single-tab defaults.
+ * For v1 configs, returns a synthetic TabConfig from top-level fields.
+ */
+export declare function getTabConfig(config: PipelineConfig, tabName?: string): {
+    gid: string;
+    tab: TabConfig;
+};

package/dist/core/tab-resolver.js

@@ -0,0 +1,44 @@
+/**
+ * Resolve a tab by name in a v2 config.
+ * Returns the GID key and TabConfig, or null if not found.
+ */
+export function resolveTabGid(config, tabName) {
+    if (!config.tabs)
+        return null;
+    for (const [gid, tab] of Object.entries(config.tabs)) {
+        if (tab.name === tabName) {
+            return { gid, tab };
+        }
+    }
+    return null;
+}
+/**
+ * Get the tab config for a given tab name, handling single-tab defaults.
+ * For v1 configs, returns a synthetic TabConfig from top-level fields.
+ */
+export function getTabConfig(config, tabName) {
+    if (config.tabs) {
+        const entries = Object.entries(config.tabs);
+        if (tabName) {
+            const resolved = resolveTabGid(config, tabName);
+            if (!resolved) {
+                throw new Error(`Tab "${tabName}" not found. Available: ${entries.map(([, t]) => t.name).join(", ")}`);
+            }
+            return resolved;
+        }
+        if (entries.length === 1) {
+            const [gid, tab] = entries[0];
+            return { gid, tab };
+        }
+        throw new Error(`Multiple tabs configured. Specify tab. Available: ${entries.map(([, t]) => t.name).join(", ")}`);
+    }
+    // v1 fallback
+    return {
+        gid: "0",
+        tab: {
+            name: tabName || "Sheet1",
+            columns: config.columns ?? {},
+            actions: config.actions ?? [],
+        },
+    };
+}

package/dist/core/template.d.ts

@@ -0,0 +1,32 @@
+import type { ExecutionContext } from "./types.js";
+/**
+ * Callback invoked when a template variable resolves to undefined.
+ * @param source - "row" or "env"
+ * @param key - the variable name that was missing
+ */
+export type OnMissingCallback = (source: string, key: string) => void;
+/**
+ * Resolve template strings like {{row.email}} and {{env.API_KEY}}.
+ * Missing variables resolve to empty string.
+ *
+ * When `onMissing` is provided, it is called for every variable that
+ * resolves to `undefined` in the given context.
+ */
+export declare function resolveTemplate(template: string, context: ExecutionContext, onMissing?: OnMissingCallback): string;
+/**
+ * Resolve template strings with an escape function applied to each resolved value.
+ *
+ * Used for shell contexts where row/env values must be sanitized before
+ * interpolation (e.g., shell-escaping to prevent command injection).
+ * The escape function is applied to each resolved placeholder value,
+ * NOT to static parts of the template.
+ */
+export declare function resolveTemplateEscaped(template: string, context: ExecutionContext, escapeFn: (value: string) => string, onMissing?: OnMissingCallback): string;
+/**
+ * Recursively resolve templates in an object/array/string.
+ * - Strings: resolve template placeholders
+ * - Arrays: resolve each element
+ * - Objects: resolve each value (keys are not resolved)
+ * - Other types: pass through unchanged
+ */
+export declare function resolveObject(obj: unknown, context: ExecutionContext, onMissing?: OnMissingCallback, depth?: number): unknown;