rowbound 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rowbound Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,258 @@
+<p align="center">
+  <img src="assets/logo.png" width="80" alt="Rowbound logo" />
+</p>
+
+<h1 align="center">Rowbound</h1>
+
+<p align="center">
+  A CLI for GTM Engineering in Google Sheets with Claude Code.
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg" alt="Node.js" /></a>
+</p>
+
+---
+
+## Demo
+
+![Rowbound demo](assets/demo.gif)
+
+## Install
+
+### Prerequisites
+
+- **Node.js 22+** — `node --version` must be >= 22.0.0
+- **gws CLI** — [Google Workspace CLI](https://github.com/googleworkspace/cli) for Sheets access
+
+```bash
+npm install -g @googleworkspace/cli
+gws auth setup   # first time: creates Cloud project, enables APIs, logs in
+gws auth login   # subsequent logins
+```
+
+### Quick install
+
+```bash
+npm install -g github:eliasstravik/rowbound
+```
+
+### Build from source
+
+```bash
+git clone https://github.com/eliasstravik/rowbound.git
+cd rowbound
+npm install
+npm run dev -- <command>
+```
+
+## Quick Start
+
+```bash
+# 1. Initialize a sheet
+rowbound init <spreadsheet-id>
+
+# 2. Add an action
+rowbound config add-action <spreadsheet-id> --json '{
+  "id": "enrich_company",
+  "type": "http",
+  "target": "company_info",
+  "method": "GET",
+  "url": "https://api.example.com/company?domain={{row.domain}}",
+  "headers": { "Authorization": "Bearer {{env.API_KEY}}" },
+  "extract": "$.name"
+}'
+
+# 3. Store API keys and run
+rowbound env set API_KEY=your_key_here
+rowbound run <spreadsheet-id>
+rowbound run <spreadsheet-id> --dry-run   # preview first
+```
+
+Column names are automatically resolved to stable IDs when you run `rowbound sync`.
+
+## Features
+
+- **HTTP actions** — call any REST API with templated URLs, headers, and bodies; extract values with JSONPath
+- **Waterfall actions** — try multiple providers in order until one returns a result (e.g., Clearbit → Apollo → Hunter)
+- **Transform actions** — compute derived values with sandboxed JavaScript expressions
+- **Exec actions** — run shell commands and capture stdout
+- **Conditional execution** — skip actions per-row with `when` expressions
+- **Smart skip** — automatically skips rows where the target cell already has a value
+- **Watch mode** — poll sheets on an interval or trigger runs via webhook
+- **Column tracking** — automatic column registry that survives header renames
+- **Rate limiting** — global token-bucket rate limiter with configurable requests/second
+- **Retry with backoff** — exponential, linear, or fixed backoff on failures
+- **Structured error handling** — per-action `onError` config maps status codes to actions (skip, write fallback)
+- **MCP server** — expose all operations as Model Context Protocol tools for Claude Desktop and other AI assistants
+- **Run history** — track pipeline executions with per-action summaries, durations, and error logs
+- **Dry run** — preview what would change without writing to the sheet
+- **BYOK** — bring your own API keys, pay only for the APIs you use
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `rowbound init <sheetId>` | Initialize a sheet with a default pipeline config |
+| `rowbound run <sheetId>` | Run the enrichment pipeline (`--dry-run`, `--rows`, `--action`) |
+| `rowbound status <sheetId>` | Show pipeline status and enrichment rates |
+| `rowbound watch <sheetId>` | Watch for changes and run continuously (`--interval`, `--port`) |
+| `rowbound sync <sheetId>` | Reconcile columns, validate config, fix issues |
+| `rowbound config show <sheetId>` | Display the pipeline config as JSON |
+| `rowbound config add-action <sheetId>` | Add an action to the pipeline |
+| `rowbound config remove-action <sheetId>` | Remove an action by ID |
+| `rowbound config update-action <sheetId>` | Update an action (merge partial JSON) |
+| `rowbound config set <sheetId>` | Update pipeline settings (concurrency, rate limit, retry) |
+| `rowbound config validate <sheetId>` | Validate the pipeline config |
+| `rowbound runs [runId]` | List recent runs or view a specific run |
+| `rowbound runs clear` | Delete all run history |
+| `rowbound env set <KEY=value>` | Store an API key globally |
+| `rowbound env remove <KEY>` | Remove a stored key |
+| `rowbound env list` | List stored keys (values masked) |
+| `rowbound mcp` | Start the MCP server (stdio) |
+
+## MCP Server
+
+Rowbound exposes all pipeline operations as MCP tools. Add this to your Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "rowbound": {
+      "command": "rowbound",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+| Tool | Description |
+|------|-------------|
+| `init_pipeline` | Initialize a sheet with a default pipeline config |
+| `run_pipeline` | Run the enrichment pipeline |
+| `add_action` / `remove_action` / `update_action` | Manage pipeline actions |
+| `update_settings` | Update pipeline settings (concurrency, rate limit, retry) |
+| `sync_columns` | Sync the column registry with the current sheet state |
+| `get_config` / `validate_config` | Read or validate the pipeline config |
+| `get_status` | Return pipeline status with enrichment rates |
+| `dry_run` | Run in dry mode (no writes) |
+| `start_watch` / `stop_watch` | Manage watch mode |
+| `preview_rows` | Read and display rows from the sheet |
+| `list_runs` / `get_run` | View pipeline run history |
+
+## Action Types
+
+Templates use `{{row.column}}` for row data and `{{env.KEY}}` for environment variables. Actions support conditional execution with `when` expressions and structured error handling with `onError`.
+
+### http
+
+Call a REST API and extract a value with JSONPath.
+
+```json
+{
+  "id": "get_company",
+  "type": "http",
+  "target": "company_name",
+  "when": "row.domain !== ''",
+  "method": "GET",
+  "url": "https://api.clearbit.com/v2/companies/find?domain={{row.domain}}",
+  "headers": { "Authorization": "Bearer {{env.CLEARBIT_API_KEY}}" },
+  "extract": "$.name",
+  "onError": { "404": "skip", "429": "skip", "default": { "write": "ERROR" } }
+}
+```
+
+### waterfall
+
+Try multiple providers in order. First non-empty result wins.
+
+```json
+{
+  "id": "find_email",
+  "type": "waterfall",
+  "target": "email",
+  "providers": [
+    {
+      "name": "hunter",
+      "method": "GET",
+      "url": "https://api.hunter.io/v2/email-finder?domain={{row.domain}}&first_name={{row.first_name}}&last_name={{row.last_name}}&api_key={{env.HUNTER_API_KEY}}",
+      "extract": "$.data.email"
+    },
+    {
+      "name": "apollo",
+      "method": "POST",
+      "url": "https://api.apollo.io/api/v1/people/match",
+      "headers": { "Content-Type": "application/json", "X-Api-Key": "{{env.APOLLO_API_KEY}}" },
+      "body": { "email": "{{row.personal_email}}", "domain": "{{row.domain}}" },
+      "extract": "$.person.email"
+    }
+  ]
+}
+```
+
+### transform
+
+Compute a value with a sandboxed JavaScript expression.
+
+```json
+{
+  "id": "full_name",
+  "type": "transform",
+  "target": "full_name",
+  "expression": "`${row.first_name} ${row.last_name}`"
+}
+```
+
+### exec
+
+Run a shell command and capture stdout. Template values are shell-escaped.
+
+```json
+{
+  "id": "whois_lookup",
+  "type": "exec",
+  "target": "registrar",
+  "command": "whois {{row.domain}} | grep 'Registrar:' | head -1 | cut -d: -f2",
+  "timeout": 10000,
+  "onError": { "default": "skip" }
+}
+```
+
+### Error handling
+
+Actions can define `onError` to map HTTP status codes (or exit codes for exec) to behaviors:
+
+| Action | Effect |
+|--------|--------|
+| `"skip"` | Skip this action for the current row |
+| `"stop_provider"` | Stop the current waterfall provider, try the next |
+| `{"write": "value"}` | Write a fallback value to the target cell |
+
+## Development
+
+```bash
+npm install
+npm run dev -- <command>
+```
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev -- <command>` | Run a CLI command in development mode |
+| `npm run build` | Type-check and build for production |
+| `npm test` | Run tests |
+| `npm run lint` | Lint with Biome |
+
+## Security
+
+- **Expression sandbox** — `when` conditions and transform expressions run in Node.js `vm.runInContext` with keyword blocking; convenience sandbox, not a security boundary
+- **Exec actions** — shell commands run locally; template values are shell-escaped but use only with trusted data
+- **SSRF protection** — HTTP requests enforce HTTPS by default and block private/internal IP ranges; set `ROWBOUND_ALLOW_HTTP=true` for local dev
+- **Webhook auth** — set `ROWBOUND_WEBHOOK_TOKEN` to require bearer token authentication; server binds to localhost by default
+- **API keys** — stored in `~/.config/rowbound/.env` with `600` permissions; `.gitignore` excludes `.env`
+- **Env filtering** — only `ROWBOUND_*`, `NODE_ENV`, `PATH`, and explicitly referenced vars are exposed to actions
+- **MCP permissions** — the MCP server inherits the authenticated `gws` CLI session permissions
+
+## License
+
+[MIT](LICENSE)

package/dist/adapters/adapter.d.ts

@@ -0,0 +1 @@
+export type { Adapter } from "../core/types.js";

package/dist/adapters/adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/adapters/sheets/sheets-adapter.d.ts

@@ -0,0 +1,66 @@
+import type { Adapter, CellUpdate, PipelineConfig, Row, SheetRef } from "../../core/types.js";
+/**
+ * Convert a 0-indexed column number to a spreadsheet column letter.
+ * 0 = A, 1 = B, ..., 25 = Z, 26 = AA, 27 = AB, ...
+ */
+export declare function columnIndexToLetter(index: number): string;
+/**
+ * Run the gws CLI with the given arguments.
+ * Uses execFile (not exec) to avoid shell injection.
+ */
+export declare function runGws(args: string[]): Promise<string>;
+/**
+ * Google Sheets adapter using the gws CLI tool.
+ */
+export declare class SheetsAdapter implements Adapter {
+    private headerCache;
+    private headerCacheTimes;
+    private headerPending;
+    private readonly HEADER_CACHE_TTL_MS;
+    private escapeSheetName;
+    private cacheKey;
+    private sheetName;
+    /**
+     * Look up a column name in the headers and return its letter (A, B, ..., AA, etc.).
+     */
+    private columnNameToLetter;
+    readRows(ref: SheetRef, range?: string): Promise<Row[]>;
+    writeCell(ref: SheetRef, update: CellUpdate): Promise<void>;
+    writeBatch(ref: SheetRef, updates: CellUpdate[]): Promise<void>;
+    readConfig(ref: SheetRef): Promise<PipelineConfig | null>;
+    writeConfig(ref: SheetRef, config: PipelineConfig): Promise<void>;
+    getHeaders(ref: SheetRef): Promise<string[]>;
+    /**
+     * Clear the header cache. Useful when headers are known to have changed.
+     */
+    clearCache(): void;
+    /**
+     * List all sheets (tabs) in the spreadsheet with their GIDs and names.
+     */
+    listSheets(spreadsheetId: string): Promise<Array<{
+        gid: number;
+        name: string;
+    }>>;
+    /**
+     * Get the numeric sheet ID (GID) for a sheet.
+     * Needed for named range creation.
+     */
+    getSheetGid(ref: SheetRef): Promise<number>;
+    /**
+     * Create a named range pointing to a specific column.
+     * Name format: _rowbound_{actionId}
+     * Range: entire column (no row bounds).
+     */
+    createColumnRange(ref: SheetRef, actionId: string, columnIndex: number): Promise<void>;
+    /**
+     * Read all Rowbound named ranges for a sheet.
+     * Returns a map of actionId -> column index (0-based).
+     * When sheetGid is provided, only returns ranges belonging to that tab.
+     */
+    readColumnRanges(ref: SheetRef, sheetGid?: number): Promise<Map<string, number>>;
+    /**
+     * Delete a named range by action ID.
+     */
+    deleteColumnRange(ref: SheetRef, actionId: string): Promise<void>;
+    private fetchHeaders;
+}