rowbound 1.0.2

package/dist/cli/run.js

@@ -0,0 +1,212 @@
+import { SheetsAdapter } from "../adapters/sheets/sheets-adapter.js";
+import { runPipeline } from "../core/engine.js";
+import { buildSafeEnv } from "../core/env.js";
+import { reconcile } from "../core/reconcile.js";
+import { createRunState } from "../core/run-state.js";
+import { createRunTracker } from "../core/run-tracker.js";
+import { bold, dim, error, success, warn } from "./format.js";
+export function registerRun(program) {
+    program
+        .command("run")
+        .description("Run the enrichment pipeline")
+        .argument("<sheetId>", "Google Sheets spreadsheet ID")
+        .option("--tab <name>", "Sheet tab name", "Sheet1")
+        .option("--rows <range>", "Row range to process (e.g. 2-50)")
+        .option("--action <id>", "Run only a specific action")
+        .option("--dry-run", "Dry run — compute but do not write back", false)
+        .option("--json", "Output result as JSON")
+        .option("-q, --quiet", "Suppress per-row output, show only final summary")
+        .action(async (sheetId, opts) => {
+        const adapter = new SheetsAdapter();
+        const ref = { spreadsheetId: sheetId, sheetName: opts.tab };
+        const jsonMode = opts.json ?? false;
+        const quietMode = opts.quiet ?? false;
+        /** Log only when not in --json mode */
+        const log = (msg) => {
+            if (!jsonMode)
+                console.log(msg);
+        };
+        const logErr = (msg) => {
+            if (!jsonMode)
+                console.error(msg);
+        };
+        try {
+            const config = await adapter.readConfig(ref);
+            if (!config) {
+                logErr(error("No Rowbound config found.") +
+                    " Run 'rowbound init <sheetId>' first.");
+                process.exitCode = 1;
+                return;
+            }
+            // Reconcile column registry (detect renames, track new columns, migrate v1→v2)
+            const reconciled = await reconcile(adapter, ref, config);
+            if (reconciled.messages.length > 0) {
+                log(dim("\u21BB Reconciling columns..."));
+                for (const msg of reconciled.messages) {
+                    log(`  ${dim(msg)}`);
+                }
+                log("");
+            }
+            if (reconciled.configChanged) {
+                await adapter.writeConfig(ref, reconciled.config);
+            }
+            const tabConfig = reconciled.tabConfig;
+            if (tabConfig.actions.length === 0) {
+                logErr(error("No actions configured.") +
+                    " Add actions with 'rowbound config add-action'.");
+                process.exitCode = 1;
+                return;
+            }
+            if (opts.rows && !/^\d+-\d+$/.test(opts.rows)) {
+                logErr(`${error("Invalid --rows format.")} Expected e.g. 2-50.`);
+                process.exitCode = 1;
+                return;
+            }
+            if (opts.rows) {
+                const [startStr, endStr] = opts.rows.split("-");
+                const start = parseInt(startStr, 10);
+                const end = parseInt(endStr, 10);
+                if (start > end) {
+                    logErr(`${error("Invalid --rows range.")} Start (${start}) must be <= end (${end}).`);
+                    process.exitCode = 1;
+                    return;
+                }
+            }
+            if (opts.action &&
+                !tabConfig.actions.some((s) => s.id === opts.action)) {
+                logErr(error(`Action "${opts.action}" not found.`) +
+                    ` Available: ${tabConfig.actions.map((s) => s.id).join(", ")}`);
+                process.exitCode = 1;
+                return;
+            }
+            const resolvedConfig = {
+                ...reconciled.config,
+                actions: tabConfig.actions,
+            };
+            // Convert CLI range format (2-50) to engine format (2:50)
+            const range = opts.rows ? opts.rows.replace("-", ":") : undefined;
+            // Build filtered env (only ROWBOUND_*, referenced {{env.X}}, NODE_ENV, PATH)
+            const env = buildSafeEnv(resolvedConfig);
+            // Set up abort controller for graceful shutdown
+            const controller = new AbortController();
+            const shutdown = () => {
+                if (controller.signal.aborted) {
+                    log(warn("\nForce quitting..."));
+                    process.exit(130);
+                }
+                log(warn("\nShutting down gracefully (Ctrl+C again to force quit)..."));
+                controller.abort();
+            };
+            process.on("SIGINT", shutdown);
+            process.on("SIGTERM", shutdown);
+            // Create run state for tracking
+            const state = createRunState({
+                sheetId,
+                sheetName: opts.tab,
+                config: resolvedConfig,
+                totalRows: 0, // Will be set after runPipeline returns
+                dryRun: opts.dryRun,
+                range,
+                actionFilter: opts.action,
+            });
+            const tracker = createRunTracker(state);
+            if (opts.dryRun) {
+                log(warn("DRY RUN — no writes will be made\n"));
+            }
+            log(`Running pipeline on sheet ${dim(sheetId)}...`);
+            if (opts.action) {
+                log(`Filtering to action: ${bold(opts.action)}`);
+            }
+            if (opts.rows) {
+                log(`Row range: ${bold(opts.rows)}`);
+            }
+            log("");
+            // Track total rows for progress display
+            let totalRowsToProcess = 0;
+            let currentRow = 0;
+            const result = await runPipeline({
+                adapter,
+                ref,
+                config: resolvedConfig,
+                env,
+                range,
+                actionFilter: opts.action,
+                dryRun: opts.dryRun,
+                signal: controller.signal,
+                columnMap: tabConfig.columns,
+                onTotalRows: (total) => {
+                    totalRowsToProcess = total;
+                },
+                onRowStart: (rowIndex, row) => {
+                    tracker.onRowStart(rowIndex, row);
+                    currentRow++;
+                    if (!quietMode) {
+                        const progress = totalRowsToProcess > 0
+                            ? `Processing row ${currentRow} of ${totalRowsToProcess}...`
+                            : `Processing row ${rowIndex + 2}...`;
+                        log(progress);
+                    }
+                },
+                onActionComplete: (rowIndex, actionId, value) => {
+                    tracker.onActionComplete(rowIndex, actionId, value);
+                    if (!quietMode) {
+                        if (value !== null) {
+                            log(`  ${success("\u2713")} ${actionId}: ${value}`);
+                        }
+                        else {
+                            log(`  ${dim("-")} ${actionId}: ${warn("skipped")}`);
+                        }
+                    }
+                },
+                onError: (rowIndex, actionId, err) => {
+                    tracker.onError(rowIndex, actionId, err);
+                    if (!quietMode) {
+                        log(`  ${error("\u2717")} ${actionId}: ${error(err.message)}`);
+                    }
+                },
+                onRowComplete: (rowIndex, updates) => {
+                    tracker.onRowComplete(rowIndex, updates);
+                },
+            });
+            // Finalize run tracking
+            state.totalRows = result.totalRows;
+            await tracker.finalize(controller.signal.aborted);
+            if (controller.signal.aborted) {
+                process.exitCode = 130;
+            }
+            if (jsonMode) {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                // Print summary
+                console.log(`\n${bold("--- Summary ---")}`);
+                console.log(`Run ID:         ${dim(state.runId)}`);
+                console.log(`Rows processed: ${bold(String(result.processedRows))}`);
+                console.log(`Cell updates:   ${bold(String(result.updates))}`);
+                console.log(`Errors:         ${result.errors.length > 0 ? error(String(result.errors.length)) : success(String(result.errors.length))}`);
+                if (result.skippedRows > 0) {
+                    console.log(`Rows skipped:   ${warn(String(result.skippedRows))}`);
+                }
+                if (result.errors.length > 0) {
+                    console.log(`\n${error("Errors:")}`);
+                    for (const err of result.errors) {
+                        console.log(`  Row ${err.rowIndex + 2}, action "${err.actionId}": ${error(err.error)}`);
+                    }
+                }
+            }
+            // Clean up signal handlers
+            process.removeListener("SIGINT", shutdown);
+            process.removeListener("SIGTERM", shutdown);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (jsonMode) {
+                console.log(JSON.stringify({ error: msg }, null, 2));
+            }
+            else {
+                console.error(error("Pipeline failed:"), msg);
+            }
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/runs.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerRuns(program: Command): void;

package/dist/cli/runs.js

@@ -0,0 +1,108 @@
+import fs from "node:fs/promises";
+import { formatRunDetail, formatRunList } from "../core/run-format.js";
+import { getRunsDir, listRuns, readRunState } from "../core/run-state.js";
+import { dim, error, success, warn } from "./format.js";
+/**
+ * Colorize status icons in run format output.
+ * ✓ -> green, ✗ -> red, ⚠ -> yellow, ⊘ -> dim, ⏳ -> dim
+ */
+function colorizeRunOutput(text) {
+    return text
+        .replace(/✓/g, success("✓"))
+        .replace(/✗/g, error("✗"))
+        .replace(/⚠/g, warn("⚠"))
+        .replace(/⊘/g, dim("⊘"))
+        .replace(/⏳/g, dim("⏳"));
+}
+export function registerRuns(program) {
+    const runsCmd = program
+        .command("runs")
+        .description("List and inspect pipeline runs")
+        .option("--sheet <id>", "Filter by sheet ID")
+        .option("--limit <n>", "Number of runs to show", "20")
+        .option("--json", "Output as JSON instead of table")
+        .option("--last", "Show detail view of the most recent run")
+        .option("--errors", "Show only errors (use with --last or a run ID)")
+        .argument("[runId]", "Show detail view of a specific run")
+        .action(async (runId, opts) => {
+        // Detail view: specific run by ID
+        if (runId) {
+            const run = await readRunState(runId);
+            if (!run) {
+                console.error(`Run "${runId}" not found.`);
+                process.exitCode = 1;
+                return;
+            }
+            console.log(colorizeRunOutput(formatRunDetail(run, opts.errors ?? false)));
+            return;
+        }
+        // Detail view: most recent run (--last)
+        if (opts.last) {
+            const runs = await listRuns({ limit: 1 });
+            if (runs.length === 0) {
+                console.error("No runs found.");
+                process.exitCode = 1;
+                return;
+            }
+            console.log(colorizeRunOutput(formatRunDetail(runs[0], opts.errors ?? false)));
+            return;
+        }
+        // List view (default)
+        const limit = parseInt(opts.limit, 10);
+        if (Number.isNaN(limit) || limit < 1) {
+            console.error("Invalid --limit value. Must be a positive integer.");
+            process.exitCode = 1;
+            return;
+        }
+        const runs = await listRuns({ sheetId: opts.sheet, limit });
+        if (opts.json) {
+            console.log(JSON.stringify(runs, null, 2));
+            return;
+        }
+        console.log(colorizeRunOutput(formatRunList(runs)));
+    });
+    // Subcommand: rowbound runs clear
+    runsCmd
+        .command("clear")
+        .description("Delete all run history")
+        .option("-f, --force", "Skip confirmation prompt")
+        .action(async (opts) => {
+        const dir = await getRunsDir();
+        let files;
+        try {
+            files = (await fs.readdir(dir)).filter((f) => f.endsWith(".json"));
+        }
+        catch {
+            console.log("Deleted 0 runs.");
+            return;
+        }
+        if (files.length === 0) {
+            console.log("Deleted 0 runs.");
+            return;
+        }
+        if (!opts.force) {
+            const readline = await import("node:readline/promises");
+            const rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            const answer = await rl.question(`Delete ${files.length} run(s)? [y/N] `);
+            rl.close();
+            if (answer.toLowerCase() !== "y") {
+                console.log("Cancelled.");
+                return;
+            }
+        }
+        let deleted = 0;
+        for (const file of files) {
+            try {
+                await fs.unlink(`${dir}/${file}`);
+                deleted++;
+            }
+            catch {
+                // Ignore deletion errors
+            }
+        }
+        console.log(`Deleted ${deleted} run${deleted !== 1 ? "s" : ""}.`);
+    });
+}

package/dist/cli/status.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerStatus(program: Command): void;

package/dist/cli/status.js

@@ -0,0 +1,108 @@
+import { SheetsAdapter } from "../adapters/sheets/sheets-adapter.js";
+import { getTabConfig } from "../core/tab-resolver.js";
+import { bold, dim, error, success, warn } from "./format.js";
+export function registerStatus(program) {
+    program
+        .command("status")
+        .description("Show pipeline status overview")
+        .argument("<sheetId>", "Google Sheets spreadsheet ID")
+        .option("--tab <name>", "Sheet tab name")
+        .option("--json", "Output as JSON")
+        .action(async (sheetId, opts) => {
+        const adapter = new SheetsAdapter();
+        const tabName = opts.tab ?? "Sheet1";
+        const ref = { spreadsheetId: sheetId, sheetName: tabName };
+        try {
+            const config = await adapter.readConfig(ref);
+            if (!config) {
+                console.error(error("No Rowbound config found. Run 'rowbound init <sheetId>' first."));
+                process.exitCode = 1;
+                return;
+            }
+            // Resolve actions from tab config (v2) or top-level (v1)
+            let actions;
+            if (config.tabs) {
+                try {
+                    const { tab } = getTabConfig(config, opts.tab);
+                    actions = tab.actions;
+                }
+                catch (e) {
+                    console.error(error(e instanceof Error ? e.message : String(e)));
+                    process.exitCode = 1;
+                    return;
+                }
+            }
+            else {
+                actions = config.actions;
+            }
+            // Read rows to build enrichment status
+            const enrichment = [];
+            let rowCount = 0;
+            try {
+                const rows = await adapter.readRows(ref);
+                rowCount = rows.length;
+                const targetColumns = [...new Set(actions.map((s) => s.target))];
+                if (targetColumns.length > 0 && rows.length > 0) {
+                    for (const target of targetColumns) {
+                        const filled = rows.filter((row) => row[target] !== undefined && row[target] !== "").length;
+                        const pct = rows.length > 0 ? Math.round((filled / rows.length) * 100) : 0;
+                        enrichment.push({ target, filled, total: rows.length, pct });
+                    }
+                }
+            }
+            catch (readErr) {
+                const readMsg = readErr instanceof Error ? readErr.message : String(readErr);
+                console.log(warn(`Could not read sheet data: ${readMsg}`));
+            }
+            if (opts.json) {
+                const data = {
+                    actions: actions.map((s) => ({
+                        id: s.id,
+                        type: s.type,
+                        target: s.target,
+                    })),
+                    settings: config.settings,
+                    rows: rowCount,
+                    enrichment,
+                };
+                console.log(JSON.stringify(data, null, 2));
+                return;
+            }
+            console.log(bold("Pipeline Status"));
+            console.log("===============\n");
+            // Action summary
+            console.log(`Actions: ${bold(String(actions.length))}`);
+            if (actions.length > 0) {
+                console.log();
+                for (const action of actions) {
+                    console.log(`  ${bold(action.id)} ${dim(`(${action.type})`)} -> ${action.target}`);
+                }
+            }
+            // Settings
+            console.log(dim("\nSettings:"));
+            console.log(`  Concurrency:   ${config.settings.concurrency}`);
+            console.log(`  Rate limit:    ${config.settings.rateLimit}/s`);
+            console.log(`  Retry:         ${config.settings.retryAttempts} attempts (${config.settings.retryBackoff})`);
+            console.log(`\nData: ${bold(String(rowCount))} rows`);
+            if (enrichment.length > 0) {
+                console.log("\nEnrichment status:");
+                for (const e of enrichment) {
+                    const colorPct = e.pct >= 80
+                        ? success(`${e.pct}%`)
+                        : e.pct >= 50
+                            ? warn(`${e.pct}%`)
+                            : error(`${e.pct}%`);
+                    console.log(`  ${e.target}: ${e.filled}/${e.total} filled (${colorPct})`);
+                }
+            }
+            else if (rowCount === 0) {
+                console.log(dim("\n(Could not read sheet data for enrichment status)"));
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(error("Failed to get status:"), msg);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/sync.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerSync(program: Command): void;

package/dist/cli/sync.js

@@ -0,0 +1,84 @@
+import { SheetsAdapter } from "../adapters/sheets/sheets-adapter.js";
+import { reconcile } from "../core/reconcile.js";
+import { validateConfig } from "../core/validator.js";
+import { dim, error, success, warn } from "./format.js";
+export function registerSync(program) {
+    program
+        .command("sync")
+        .description("Sync pipeline config with the sheet — reconcile columns, migrate action targets, validate, and fix issues")
+        .argument("<sheetId>", "Google Sheets spreadsheet ID")
+        .option("--tab <name>", "Sheet tab name", "Sheet1")
+        .action(async (sheetId, opts) => {
+        const adapter = new SheetsAdapter();
+        const ref = { spreadsheetId: sheetId, sheetName: opts.tab };
+        try {
+            const config = await adapter.readConfig(ref);
+            if (!config) {
+                console.error(error("No Rowbound config found.") +
+                    " Run 'rowbound init <sheetId>' first.");
+                process.exitCode = 1;
+                return;
+            }
+            // --- 1. Reconcile columns (and migrate v1→v2 if needed) ---
+            const reconciled = await reconcile(adapter, ref, config);
+            const tabConfig = reconciled.tabConfig;
+            if (reconciled.messages.length > 0) {
+                console.log(dim("\u21BB Reconciling columns..."));
+                for (const msg of reconciled.messages) {
+                    console.log(`  ${dim(msg)}`);
+                }
+            }
+            else {
+                console.log(`${success("\u2713")} Columns in sync`);
+            }
+            // --- 2. Check for orphaned action targets ---
+            const columns = tabConfig.columns;
+            const warnings = [];
+            for (const action of tabConfig.actions) {
+                if (!columns[action.target]) {
+                    warnings.push(`Action "${action.id}" targets "${action.target}" which is not a known column ID`);
+                }
+            }
+            // --- 3. Check for unreferenced columns (info, not a problem) ---
+            const targetedIds = new Set(tabConfig.actions.map((s) => s.target));
+            const _untargeted = Object.entries(columns)
+                .filter(([id]) => !targetedIds.has(id))
+                .map(([id, name]) => `${name} (${id})`);
+            // --- 4. Validate config ---
+            const validationConfig = {
+                ...reconciled.config,
+                actions: tabConfig.actions,
+            };
+            const validation = validateConfig(validationConfig);
+            if (validation.errors.length > 0) {
+                console.error(`\n${error("\u2717")} Validation errors:`);
+                for (const e of validation.errors) {
+                    console.error(`  ${error("-")} ${e}`);
+                }
+            }
+            if (validation.warnings.length > 0 || warnings.length > 0) {
+                console.log(`\n${warn("\u26A0")} Warnings:`);
+                for (const w of [...warnings, ...validation.warnings]) {
+                    console.log(`  ${warn("-")} ${w}`);
+                }
+            }
+            // --- 5. Save if anything changed ---
+            if (reconciled.configChanged) {
+                await adapter.writeConfig(ref, reconciled.config);
+                console.log(`\n${success("\u2713")} Config saved`);
+            }
+            // --- 6. Summary ---
+            const cols = Object.keys(columns).length;
+            const actions = tabConfig.actions.length;
+            console.log(`\n${cols} columns tracked, ${actions} actions configured`);
+            if (validation.errors.length > 0 || warnings.length > 0) {
+                process.exitCode = 1;
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(error("Sync failed:"), msg);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/watch.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerWatch(program: Command): void;