rowbound 1.0.2

package/dist/cli/config.js

@@ -0,0 +1,397 @@
+import { SheetsAdapter } from "../adapters/sheets/sheets-adapter.js";
+import { getTabConfig, resolveTabGid } from "../core/tab-resolver.js";
+import { validateConfig } from "../core/validator.js";
+import { error, warn } from "./format.js";
+export function registerConfig(program) {
+    const configCmd = program
+        .command("config")
+        .description("Manage pipeline configuration")
+        .action(() => {
+        configCmd.help();
+    });
+    // rowbound config show <sheetId> [--tab <name>]
+    configCmd
+        .command("show")
+        .description("Display pipeline config as formatted JSON")
+        .argument("<sheetId>", "Google Sheets spreadsheet ID")
+        .option("--tab <name>", "Sheet tab name")
+        .action(async (sheetId, opts) => {
+        const adapter = new SheetsAdapter();
+        const ref = { spreadsheetId: sheetId, sheetName: opts.tab || "Sheet1" };
+        try {
+            const existing = await adapter.readConfig(ref);
+            if (!existing) {
+                console.error(error("No Rowbound config found for this sheet."));
+                process.exitCode = 1;
+                return;
+            }
+            if (opts.tab && !existing.tabs) {
+                console.warn(warn("Note: Config is v1 format (single-tab). Run 'rowbound sync' to migrate to v2."));
+            }
+            if (opts.tab && existing.tabs) {
+                // Show just the specified tab's config
+                const resolved = resolveTabGid(existing, opts.tab);
+                if (!resolved) {
+                    console.error(error(`Tab "${opts.tab}" not found. Available: ${Object.values(existing.tabs)
+                        .map((t) => t.name)
+                        .join(", ")}`));
+                    process.exitCode = 1;
+                    return;
+                }
+                console.log(JSON.stringify({ gid: resolved.gid, ...resolved.tab }, null, 2));
+            }
+            else {
+                console.log(JSON.stringify(existing, null, 2));
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(error("Failed to read config:"), msg);
+            process.exitCode = 1;
+        }
+    });
+    // rowbound config add-action <sheetId> --json '<action JSON>' [--tab <name>]
+    configCmd
+        .command("add-action")
+        .description("Add an action to the pipeline config")
+        .argument("<sheetId>", "Google Sheets spreadsheet ID")
+        .requiredOption("--json <actionJson>", "Action definition as JSON string")
+        .option("--tab <name>", "Sheet tab name")
+        .action(async (sheetId, opts) => {
+        const adapter = new SheetsAdapter();
+        const ref = { spreadsheetId: sheetId, sheetName: opts.tab || "Sheet1" };
+        try {
+            let action;
+            try {
+                action = JSON.parse(opts.json);
+            }
+            catch {
+                console.error(error("Invalid JSON for action definition."));
+                process.exitCode = 1;
+                return;
+            }
+            if (!action.id || !action.type || !action.target) {
+                console.error(error("Action must have at least 'id', 'type', and 'target' fields."));
+                process.exitCode = 1;
+                return;
+            }
+            const existing = await adapter.readConfig(ref);
+            if (!existing) {
+                console.error(error("No Rowbound config found. Run 'rowbound init <sheetId>' first."));
+                process.exitCode = 1;
+                return;
+            }
+            if (existing.tabs) {
+                // v2: add to the specific tab
+                const { gid, tab } = getTabConfig(existing, opts.tab);
+                if (tab.actions.some((s) => s.id === action.id)) {
+                    console.error(error(`Action with id "${action.id}" already exists.`));
+                    process.exitCode = 1;
+                    return;
+                }
+                tab.actions.push(action);
+                existing.tabs[gid] = tab;
+            }
+            else {
+                // v1 fallback
+                if (existing.actions.some((s) => s.id === action.id)) {
+                    console.error(error(`Action with id "${action.id}" already exists.`));
+                    process.exitCode = 1;
+                    return;
+                }
+                existing.actions.push(action);
+            }
+            await adapter.writeConfig(ref, existing);
+            console.log(`Added action "${action.id}" (${action.type} -> ${action.target})`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(error("Failed to add action:"), msg);
+            process.exitCode = 1;
+        }
+    });
+    // rowbound config remove-action <sheetId> --action <id> [--tab <name>]
+    configCmd
+        .command("remove-action")
+        .description("Remove an action from the pipeline config")
+        .argument("<sheetId>", "Google Sheets spreadsheet ID")
+        .requiredOption("--action <id>", "Action ID to remove")
+        .option("--tab <name>", "Sheet tab name")
+        .action(async (sheetId, opts) => {
+        const adapter = new SheetsAdapter();
+        const ref = { spreadsheetId: sheetId, sheetName: opts.tab || "Sheet1" };
+        try {
+            const existing = await adapter.readConfig(ref);
+            if (!existing) {
+                console.error(error("No Rowbound config found. Run 'rowbound init <sheetId>' first."));
+                process.exitCode = 1;
+                return;
+            }
+            if (existing.tabs) {
+                const { gid, tab } = getTabConfig(existing, opts.tab);
+                const originalLength = tab.actions.length;
+                tab.actions = tab.actions.filter((s) => s.id !== opts.action);
+                if (tab.actions.length === originalLength) {
+                    console.error(error(`Action "${opts.action}" not found in config.`));
+                    process.exitCode = 1;
+                    return;
+                }
+                existing.tabs[gid] = tab;
+            }
+            else {
+                const originalLength = existing.actions.length;
+                existing.actions = existing.actions.filter((s) => s.id !== opts.action);
+                if (existing.actions.length === originalLength) {
+                    console.error(error(`Action "${opts.action}" not found in config.`));
+                    process.exitCode = 1;
+                    return;
+                }
+            }
+            await adapter.writeConfig(ref, existing);
+            console.log(`Removed action "${opts.action}".`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(error("Failed to remove action:"), msg);
+            process.exitCode = 1;
+        }
+    });
+    // rowbound config update-action <sheetId> --action <id> --json '<partial JSON>' [--tab <name>]
+    configCmd
+        .command("update-action")
+        .description("Update an action in the pipeline config (merge partial JSON)")
+        .argument("<sheetId>", "Google Sheets spreadsheet ID")
+        .requiredOption("--action <id>", "Action ID to update")
+        .requiredOption("--json <partialJson>", "Partial action definition to merge")
+        .option("--tab <name>", "Sheet tab name")
+        .action(async (sheetId, opts) => {
+        const adapter = new SheetsAdapter();
+        const ref = { spreadsheetId: sheetId, sheetName: opts.tab || "Sheet1" };
+        try {
+            let patch;
+            try {
+                patch = JSON.parse(opts.json);
+            }
+            catch {
+                console.error(error("Invalid JSON for action update."));
+                process.exitCode = 1;
+                return;
+            }
+            const existing = await adapter.readConfig(ref);
+            if (!existing) {
+                console.error(error("No Rowbound config found. Run 'rowbound init <sheetId>' first."));
+                process.exitCode = 1;
+                return;
+            }
+            let actions;
+            let gid;
+            if (existing.tabs) {
+                const resolved = getTabConfig(existing, opts.tab);
+                gid = resolved.gid;
+                actions = resolved.tab.actions;
+            }
+            else {
+                actions = existing.actions;
+            }
+            const actionIndex = actions.findIndex((s) => s.id === opts.action);
+            if (actionIndex === -1) {
+                console.error(error(`Action "${opts.action}" not found in config.`));
+                process.exitCode = 1;
+                return;
+            }
+            // If renaming the ID, check for duplicates
+            if (patch.id && patch.id !== opts.action) {
+                if (actions.some((s) => s.id === patch.id)) {
+                    console.error(error(`Action with id "${patch.id}" already exists.`));
+                    process.exitCode = 1;
+                    return;
+                }
+            }
+            actions[actionIndex] = {
+                ...actions[actionIndex],
+                ...patch,
+            };
+            if (existing.tabs && gid) {
+                existing.tabs[gid].actions = actions;
+            }
+            else {
+                existing.actions = actions;
+            }
+            await adapter.writeConfig(ref, existing);
+            console.log(`Updated action "${opts.action}"${patch.id && patch.id !== opts.action ? ` → "${patch.id}"` : ""}`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(error("Failed to update action:"), msg);
+            process.exitCode = 1;
+        }
+    });
+    // rowbound config set <sheetId> [--concurrency <n>] [--rate-limit <n>] [--retry-attempts <n>] [--retry-backoff <strategy>] [--tab <name>]
+    configCmd
+        .command("set")
+        .description("Update pipeline settings")
+        .argument("<sheetId>", "Google Sheets spreadsheet ID")
+        .option("--concurrency <n>", "Max concurrent rows")
+        .option("--rate-limit <n>", "Max requests per second")
+        .option("--retry-attempts <n>", "Number of retry attempts")
+        .option("--retry-backoff <strategy>", "Backoff strategy (exponential, linear, fixed)")
+        .option("--tab <name>", "Sheet tab name")
+        .action(async (sheetId, opts) => {
+        const adapter = new SheetsAdapter();
+        const ref = { spreadsheetId: sheetId, sheetName: opts.tab || "Sheet1" };
+        try {
+            const existing = await adapter.readConfig(ref);
+            if (!existing) {
+                console.error(error("No Rowbound config found. Run 'rowbound init <sheetId>' first."));
+                process.exitCode = 1;
+                return;
+            }
+            const changes = [];
+            if (opts.concurrency !== undefined) {
+                const val = parseInt(opts.concurrency, 10);
+                if (Number.isNaN(val) || val <= 0) {
+                    console.error(error("--concurrency must be a positive integer."));
+                    process.exitCode = 1;
+                    return;
+                }
+                existing.settings.concurrency = val;
+                changes.push(`concurrency=${val}`);
+            }
+            if (opts.rateLimit !== undefined) {
+                const val = parseInt(opts.rateLimit, 10);
+                if (Number.isNaN(val) || val <= 0) {
+                    console.error(error("--rate-limit must be a positive integer."));
+                    process.exitCode = 1;
+                    return;
+                }
+                existing.settings.rateLimit = val;
+                changes.push(`rateLimit=${val}`);
+            }
+            if (opts.retryAttempts !== undefined) {
+                const val = parseInt(opts.retryAttempts, 10);
+                if (Number.isNaN(val) || val < 0) {
+                    console.error(error("--retry-attempts must be a non-negative integer."));
+                    process.exitCode = 1;
+                    return;
+                }
+                existing.settings.retryAttempts = val;
+                changes.push(`retryAttempts=${val}`);
+            }
+            if (opts.retryBackoff !== undefined) {
+                const validStrategies = ["exponential", "linear", "fixed"];
+                if (!validStrategies.includes(opts.retryBackoff)) {
+                    console.error(error(`Invalid --retry-backoff value "${opts.retryBackoff}". Must be one of: ${validStrategies.join(", ")}`));
+                    process.exitCode = 1;
+                    return;
+                }
+                existing.settings.retryBackoff = opts.retryBackoff;
+                changes.push(`retryBackoff=${opts.retryBackoff}`);
+            }
+            if (changes.length === 0) {
+                console.error(error("No settings specified. Use --concurrency, --rate-limit, --retry-attempts, or --retry-backoff."));
+                process.exitCode = 1;
+                return;
+            }
+            await adapter.writeConfig(ref, existing);
+            console.log(`Updated settings: ${changes.join(", ")}`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(error("Failed to update settings:"), msg);
+            process.exitCode = 1;
+        }
+    });
+    // rowbound config validate <sheetId> [--tab <name>] [--json]
+    configCmd
+        .command("validate")
+        .description("Validate the pipeline config")
+        .argument("<sheetId>", "Google Sheets spreadsheet ID")
+        .option("--tab <name>", "Sheet tab name")
+        .option("--json", "Output validation result as JSON")
+        .action(async (sheetId, opts) => {
+        const adapter = new SheetsAdapter();
+        const ref = { spreadsheetId: sheetId, sheetName: opts.tab || "Sheet1" };
+        try {
+            const existing = await adapter.readConfig(ref);
+            if (!existing) {
+                if (opts.json) {
+                    console.log(JSON.stringify({
+                        valid: false,
+                        errors: ["No Rowbound config found for this sheet."],
+                        warnings: [],
+                    }, null, 2));
+                }
+                else {
+                    console.error(error("No Rowbound config found for this sheet."));
+                }
+                process.exitCode = 1;
+                return;
+            }
+            // For v2, validate per-tab
+            let result;
+            let tabName;
+            let actionCount;
+            if (existing.tabs) {
+                const { tab } = getTabConfig(existing, opts.tab);
+                tabName = tab.name;
+                actionCount = tab.actions.length;
+                const tabValidationConfig = {
+                    ...existing,
+                    actions: tab.actions,
+                };
+                result = validateConfig(tabValidationConfig);
+            }
+            else {
+                actionCount = existing.actions.length;
+                result = validateConfig(existing);
+            }
+            if (opts.json) {
+                console.log(JSON.stringify(result, null, 2));
+                if (!result.valid) {
+                    process.exitCode = 1;
+                }
+                return;
+            }
+            if (result.valid) {
+                if (result.warnings.length > 0) {
+                    console.log(warn(`Config is valid with ${result.warnings.length} warning(s):`));
+                    for (const w of result.warnings) {
+                        console.warn(warn(`  - ${w}`));
+                    }
+                }
+                else {
+                    console.log("Config is valid.");
+                }
+                console.log(`  Version: ${existing.version}`);
+                if (tabName) {
+                    console.log(`  Tab:     ${tabName}`);
+                }
+                console.log(`  Actions: ${actionCount}`);
+                console.log(`  Settings: concurrency=${existing.settings.concurrency}, rateLimit=${existing.settings.rateLimit}/s`);
+            }
+            else {
+                console.error(error("Config validation failed:"));
+                for (const e of result.errors) {
+                    console.error(error(`  - ${e}`));
+                }
+                process.exitCode = 1;
+                if (result.warnings.length > 0) {
+                    console.warn(warn("Warnings:"));
+                    for (const w of result.warnings) {
+                        console.warn(warn(`  - ${w}`));
+                    }
+                }
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (opts.json) {
+                console.log(JSON.stringify({ valid: false, errors: [msg], warnings: [] }, null, 2));
+            }
+            else {
+                console.error(error("Failed to validate config:"), msg);
+            }
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/env.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+export declare function getGlobalEnvPath(): string;
+export declare function registerEnv(program: Command): void;

package/dist/cli/env.js

@@ -0,0 +1,103 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import pc from "picocolors";
+const CONFIG_DIR = join(homedir(), ".config", "rowbound");
+const ENV_FILE = join(CONFIG_DIR, ".env");
+export function getGlobalEnvPath() {
+    return ENV_FILE;
+}
+function ensureConfigDir() {
+    if (!existsSync(CONFIG_DIR)) {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+}
+function readEnvFile() {
+    const entries = new Map();
+    if (!existsSync(ENV_FILE))
+        return entries;
+    const content = readFileSync(ENV_FILE, "utf-8");
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eqIndex = trimmed.indexOf("=");
+        if (eqIndex === -1)
+            continue;
+        const key = trimmed.slice(0, eqIndex).trim();
+        const value = trimmed.slice(eqIndex + 1).trim();
+        entries.set(key, value);
+    }
+    return entries;
+}
+function writeEnvFile(entries) {
+    ensureConfigDir();
+    const lines = Array.from(entries.entries()).map(([key, value]) => `${key}=${value}`);
+    writeFileSync(ENV_FILE, `${lines.join("\n")}\n`, { mode: 0o600 });
+}
+function maskValue(value) {
+    if (value.length <= 8)
+        return "****";
+    return `${value.slice(0, 4)}****${value.slice(-4)}`;
+}
+export function registerEnv(program) {
+    const env = program
+        .command("env")
+        .description("Manage API keys stored in ~/.config/rowbound/.env");
+    env
+        .command("set <key=value>")
+        .description("Set an environment variable")
+        .action((pair) => {
+        const eqIndex = pair.indexOf("=");
+        if (eqIndex === -1) {
+            console.error(pc.red("Invalid format. Use: rowbound env set KEY=value"));
+            process.exit(1);
+        }
+        const key = pair.slice(0, eqIndex).trim();
+        const value = pair.slice(eqIndex + 1).trim();
+        if (!key) {
+            console.error(pc.red("Key cannot be empty."));
+            process.exit(1);
+        }
+        const entries = readEnvFile();
+        const isUpdate = entries.has(key);
+        entries.set(key, value);
+        writeEnvFile(entries);
+        console.log(isUpdate
+            ? `${pc.green("Updated")} ${pc.bold(key)}`
+            : `${pc.green("Set")} ${pc.bold(key)}`);
+    });
+    env
+        .command("remove <key>")
+        .description("Remove an environment variable")
+        .action((key) => {
+        const entries = readEnvFile();
+        if (!entries.has(key)) {
+            console.error(pc.yellow(`${key} not found.`));
+            process.exit(1);
+        }
+        entries.delete(key);
+        writeEnvFile(entries);
+        console.log(`${pc.green("Removed")} ${pc.bold(key)}`);
+    });
+    env
+        .command("list")
+        .description("List all stored environment variables (values masked)")
+        .action(() => {
+        const entries = readEnvFile();
+        if (entries.size === 0) {
+            console.log(pc.dim("No environment variables configured."));
+            console.log(pc.dim(`Run: rowbound env set API_KEY=your_key`));
+            return;
+        }
+        for (const [key, value] of entries) {
+            console.log(`${pc.bold(key)}=${pc.dim(maskValue(value))}`);
+        }
+    });
+    env
+        .command("path")
+        .description("Print the path to the global env file")
+        .action(() => {
+        console.log(ENV_FILE);
+    });
+}

package/dist/cli/format.d.ts

@@ -0,0 +1,5 @@
+export declare const success: (s: string) => string;
+export declare const error: (s: string) => string;
+export declare const warn: (s: string) => string;
+export declare const dim: (s: string) => string;
+export declare const bold: (s: string) => string;

package/dist/cli/format.js

@@ -0,0 +1,6 @@
+import pc from "picocolors";
+export const success = (s) => pc.green(s);
+export const error = (s) => pc.red(s);
+export const warn = (s) => pc.yellow(s);
+export const dim = (s) => pc.dim(s);
+export const bold = (s) => pc.bold(s);

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { Command } from "commander";
+import dotenv from "dotenv";
+import { registerConfig } from "./config.js";
+import { getGlobalEnvPath, registerEnv } from "./env.js";
+import { registerInit } from "./init.js";
+import { registerRun } from "./run.js";
+import { registerRuns } from "./runs.js";
+import { registerStatus } from "./status.js";
+import { registerSync } from "./sync.js";
+import { registerWatch } from "./watch.js";
+// Load local .env first (higher priority), then global ~/.config/rowbound/.env
+// dotenv never overwrites existing process.env, so shell vars always win
+dotenv.config();
+dotenv.config({ path: getGlobalEnvPath() });
+const require = createRequire(import.meta.url);
+const pkg = require("../../package.json");
+const program = new Command();
+program
+    .name("rowbound")
+    .description("Open-source CLI for Google Sheets enrichment — waterfalls, conditions, HTTP API integrations")
+    .version(pkg.version);
+registerInit(program);
+registerRun(program);
+registerConfig(program);
+registerStatus(program);
+registerWatch(program);
+registerRuns(program);
+registerSync(program);
+registerEnv(program);
+program
+    .command("mcp")
+    .description("Start MCP server (stdio)")
+    .action(async () => {
+    const { startMcpServer } = await import("../mcp/server.js");
+    await startMcpServer();
+});
+program.parse(process.argv);

package/dist/cli/init.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from "commander";
+/**
+ * Extract spreadsheet ID from a full Google Sheets URL, or return the input as-is
+ * if it's already a plain ID.
+ *
+ * Google Sheets URLs look like:
+ *   https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit...
+ */
+export declare function extractSheetId(input: string): string;
+export declare function registerInit(program: Command): void;

package/dist/cli/init.js

@@ -0,0 +1,72 @@
+import { SheetsAdapter } from "../adapters/sheets/sheets-adapter.js";
+import { defaultSettings } from "../core/defaults.js";
+import { dim, error, success, warn } from "./format.js";
+/**
+ * Extract spreadsheet ID from a full Google Sheets URL, or return the input as-is
+ * if it's already a plain ID.
+ *
+ * Google Sheets URLs look like:
+ *   https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit...
+ */
+export function extractSheetId(input) {
+    const match = input.match(/^https?:\/\/docs\.google\.com\/spreadsheets\/d\/([a-zA-Z0-9_-]+)/);
+    if (match) {
+        return match[1];
+    }
+    return input;
+}
+export function registerInit(program) {
+    program
+        .command("init")
+        .description("Initialize a sheet with a default Rowbound config")
+        .argument("<sheetId>", "Google Sheets spreadsheet ID or URL")
+        .option("--tab <name>", "Sheet tab name", "Sheet1")
+        .action(async (rawSheetId, opts) => {
+        const sheetId = extractSheetId(rawSheetId);
+        if (sheetId !== rawSheetId) {
+            console.log(warn(`Extracted spreadsheet ID from URL: ${sheetId}`));
+        }
+        const adapter = new SheetsAdapter();
+        const ref = { spreadsheetId: sheetId, sheetName: opts.tab };
+        try {
+            const existing = await adapter.readConfig(ref);
+            if (existing) {
+                console.error(error("Config already exists for this sheet.") +
+                    " Remove it first or use 'rowbound config show' to inspect.");
+                process.exitCode = 1;
+                return;
+            }
+            // Get the tab's GID for v2 config
+            const sheets = await adapter.listSheets(sheetId);
+            const targetSheet = sheets.find((s) => s.name === opts.tab);
+            if (!targetSheet) {
+                console.error(error(`Tab "${opts.tab}" not found`) +
+                    ` in spreadsheet ${dim(sheetId)}. Available: ${sheets.map((s) => s.name).join(", ")}`);
+                process.exitCode = 1;
+                return;
+            }
+            const gid = String(targetSheet.gid);
+            const defaultConfig = {
+                version: "2",
+                tabs: {
+                    [gid]: {
+                        name: opts.tab,
+                        columns: {},
+                        actions: [],
+                    },
+                },
+                actions: [],
+                settings: defaultSettings,
+            };
+            await adapter.writeConfig(ref, defaultConfig);
+            console.log(success("Initialized Rowbound config for sheet:"), dim(sheetId));
+            console.log("Tab:", opts.tab, dim(`(GID: ${gid})`));
+            console.log("\nNext steps:\n  rowbound config add-action <sheetId> --json '<action>'\n  rowbound run <sheetId>");
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(error("Failed to initialize:"), msg);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/run.d.ts

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