n8n-decanter 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,130 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-07-21
+
+### Changed
+
+- **Breaking: verb-first grammar.** The verb now comes first —
+  `n8n-decanter <verb> [workflow…]`. Verb-last (`n8n-decanter wf123 push`) is no
+  longer accepted and errors with *unknown verb*. Because everything after the
+  verb is an argument, a workflow named like a verb needs no special handling:
+  `n8n-decanter status push` runs `status` on the workflow named `push`. Flags
+  may still appear in any position.
+- **Breaking: node operations moved under a `node` namespace.** `add` →
+  `node create <workflow> "<Node name>"`, the two-name node rename →
+  `node rename <workflow> "<old node>" "<new node>"`, and `run <node-file>` →
+  `node run <node-file>`.
+- New workflow folders are **kebab-case** (`Order Sync` → `workflows/order-sync/`)
+  instead of keeping spaces and capitals. **Existing folders are left untouched**
+  and still resolve as refs — no migration, no churn.
+- A workflow folder **no longer follows a remote rename**. The folder is a stable
+  local slug; the always-current display name lives in `.decanter.json` (see
+  Added). Renaming a workflow (locally or on the server) never moves your folder.
+
+### Added
+
+- **`data-tables` verb** — a read-only fetch of n8n **data-table** schemas and
+  rows (the built-in project-scoped tables, n8n ≥ 2.x) into a top-level,
+  gitignored `data-tables/<table>/{meta,columns,rows}.json` dir, for developing
+  and debugging against real table contents offline. `--filter '<json>'`,
+  `--search`, and `--sort` pull only a slice of a large table server-side (the
+  applied filter is recorded in each table's `meta.json`); `--limit`/`--all`
+  control page size and exhaustion. It never writes a data table.
+  `data-tables clean` removes the dir (offline). Gated by the new **`dataTables`**
+  config key (default `true`); when off, the fetch refuses and the recommended
+  key needn't carry the data-table read scopes (`dataTable:list`,
+  `dataTable:read`, `dataTableColumn:read`, `dataTableRow:read`).
+- `.decanter.json` now caches the workflow's display **`name`** (refreshed on
+  every pull), so the picker, `list`, and ref-resolution show the real name even
+  though the folder is a kebab slug — and keep working if `workflow.json` is
+  missing or corrupt.
+- **`list --json`** emits `[{ name, id, dir }]` for tooling (remote-only
+  workflows under `--remote` have `dir: null`).
+- **No-ref → picker.** A ref-taking verb given no workflow, on a terminal, opens
+  the interactive picker to choose one and runs the verb on it. Piped/non-TTY
+  runs keep the config-default / error behavior, so scripts and CI never block.
+- **`simulate` now replays single-iteration loops.** A workflow whose only
+  repeated node is a `splitInBatches` ("Loop Over Items") driver that ran a
+  single batch — it runs twice (one batch pass + the final "done" pass) while
+  every other node ran once — no longer hard-errors. The loop driver executes
+  for real to reproduce the loop, and each node's one captured run pins exactly.
+  Multi-batch loops (any node ran more than once) stay out of scope, since
+  first-run-only pinning can't feed later iterations.
+
+### Removed
+
+- **Breaking: `rename --workflow` flag.** Workflow rename is now the single
+  top-level form `rename <workflow> "<new name>"`; node rename lives under
+  `node rename`.
+
+## [0.4.5] - 2026-07-21
+
+### Added
+
+- **`simulate` in the interactive picker.** The verb menu for a pulled workflow
+  now offers `simulate` alongside status/pull/push/watch/check/executions; it
+  runs against the workflow's newest capture.
+- **Open a simulation run in the n8n webapp.** In an interactive terminal,
+  `simulate` prints a **URL** to the run in a kept-alive local n8n (plus the
+  throwaway instance's login) — pure nodes' real output and the pinned nodes,
+  node-by-node in the actual execution inspector. No flag, no extra step; a
+  fresh viewer replaces the previous one each run (`docker rm -f
+  decanter-sim-viewer` to stop it). Scripts, `--json`, and `--network-none`
+  runs stay headless and print no URL, so CI is unaffected.
+
+### Changed
+
+- **`simulate` no longer requires `--execution`.** With the flag omitted it
+  defaults to the **newest capture** in the workflow's `executions/` dir, so
+  `n8n-decanter <ref> simulate` works right after an `executions` fetch (and
+  lets the picker offer it). Pass `--execution <id>` to pick a specific one.
+
+## [0.4.4] - 2026-07-21
+
+### Changed
+
+- **The generated `.claude/settings.local.json` pre-approves more safe verbs.**
+  `rename`, `list`, `executions` (incl. `executions clean`), `completion`, and
+  `help` — plus a bare `status` — now run without a permission prompt, matching
+  the "offline, safe" and "reads remote, no writes" tiers documented in the
+  sync-dir `AGENTS.md`. Mutating/destructive verbs (`push`, `pull`, `watch`,
+  `publish`, `unpublish`, `create`, `duplicate`, `simulate`, `delete`) still
+  prompt, and `delete --force` is now hard-denied alongside `push --force`.
+
+## [0.4.3] - 2026-07-21
+
+### Changed
+
+- **`$('Node').item` in the type shim (`n8n-globals.d.ts`) is no longer typed
+  `| undefined`.** Accessing `$('Node').item.json` no longer raises a spurious
+  "Object is possibly 'undefined'" (TS2532) — the value is non-undefined, like
+  `$input.item`, since a missing paired item throws at runtime rather than
+  yielding `undefined`. Use `itemMatching(i)`, `first()`, or `last()` when you
+  want an index-checked lookup instead.
+
+## [0.4.2] - 2026-07-20
+
+### Added
+
+- **`simulate` verb** — `n8n-decanter <ref> simulate --execution <id>` replays
+  a whole workflow through a **real n8n engine** (Docker) using a captured
+  execution as the mock: side-effect-free nodes (Set, IF, Code, …) execute for
+  real, every network/side-effectful node is pinned to its captured output,
+  credentials are stripped, and no outbound-capable node survives — a dry,
+  engine-true regression check. It diffs each executed node's output against the
+  capture and **exits `1` on divergence** (CI-gateable). `--network-none` adds
+  an enforced outbound cutoff; `--json` emits the report for tooling.
+- **`simulate --pin <id>`** — copy a capture's network-node outputs into
+  committed, provenance-stamped `workflows/<Name>/fixtures/<node>.json`, making
+  replays reproducible and committable (prints a PII-review warning).
+- **`n8nVersion` config field** (`decanter.config.json`) — pins the n8n version
+  the `simulate` engine runs, so "engine-true" matches your instance;
+  `--n8n-version <tag>` overrides it per run. Defaults to the project's pinned
+  version with a hint when unset.
+- **`npm run test:sim`** — opt-in engine simulation suite (needs Docker; never
+  part of `npm test`); skips cleanly when no Docker daemon is available.
+
 ## [0.4.1] - 2026-07-20
 
 ### Changed

package/README.md

@@ -26,14 +26,19 @@ editable in your IDE or by your agent, and pushed back through the n8n API.
 - **TypeScript or typed JS** — write nodes in TS (compiled on push); n8n
   globals (`$input`, `$('…')`, …) are typed in both.
 - **Agent-native** — `init` scaffolds Claude Code / Cursor / Codex configs
-  and verification hooks; offline `check` and `run` give agents a
+  and verification hooks; offline `check` and `node run` give agents a
   credential-free feedback loop.
 - **Guardrails** — a compliance guard and typecheck gate block broken
   pushes; a drift guard keeps you from clobbering remote edits.
 - **Real execution data on tap** — `executions` fetches recent run JSON into
   a gitignored temp dir, so agents see actual payload shapes (and build
-  accurate `run` fixtures) instead of guessing; `executions clean` removes
+  accurate `node run` fixtures) instead of guessing; `executions clean` removes
   it when done.
+- **Engine-true simulation** — `simulate` replays a whole workflow through a
+  real n8n engine using a captured execution as the mock: pure nodes run for
+  real, network nodes pinned, credentials stripped. It diffs each node against
+  the capture (exits 1 on divergence — a CI-gateable regression check) and, in
+  a terminal, prints a URL to open the run in the n8n webapp.
 - **Live editing** — `watch` pushes on save and auto-reloads the n8n editor
   tab via a local proxy.
 - **Shared code and small libraries** — `.ts` nodes import helpers/types
@@ -90,6 +95,8 @@ so a leaked `.env` has a small blast radius:
 - `workflow:create`, `workflow:delete` — `create` / `delete`
 - `workflow:activate`, `workflow:deactivate` — `publish` / `unpublish`
 - `execution:read`, `execution:list` — the `executions` verb
+- `dataTable:list`, `dataTable:read`, `dataTableColumn:read`, `dataTableRow:read`
+  — the `data-tables` verb (only needed while `"dataTables"` is on, its default)
 
 A full-access key also works if your n8n version predates scoped keys.
 
@@ -105,7 +112,7 @@ PostToolUse hook that runs `check` after node edits. Verification routes through
 the CLI, so `n8n-decanter` must be on the sync dir's PATH: install it globally
 (`npm i -g n8n-decanter`), add it to the sync dir's `devDependencies`, or
 `npm link` a git checkout (build it first — Node won't type-strip `.mts`
-under `node_modules`). The verbs `check`, `run`, `rename`, and `add` are fully
+under `node_modules`). The verbs `check`, `node run`, `rename`, and `node create` are fully
 offline (no credentials, no network).
 
 ## Commands
@@ -117,45 +124,65 @@ n8n-decanter                        # interactive picker (terminal, inited
                                     #   then run verbs (unpulled: Enter pulls);
                                     #   stays in the workflow's menu between
                                     #   verbs, Esc backs out, Esc Esc quits
+# Setup
 n8n-decanter init [dir]             # interactive bootstrap (see Setup)
-n8n-decanter [ref...] pull          # remote -> workflows/<Name>/
-n8n-decanter [ref...] push [--force] [--no-typecheck]
-n8n-decanter [ref...] status [--diff]   # drift report (--diff: line diffs);
-                                    #   exits 1 on conflict/remote drift
-n8n-decanter [ref...] check         # offline layout-compliance + typecheck
-n8n-decanter <ref> rename "<old node>" "<new node>"   # rename a node everywhere
-n8n-decanter <ref> rename --workflow "<new name>"     # rename the workflow
-n8n-decanter <ref> add "<Node name>" [--ts]           # scaffold a Code node (offline)
-n8n-decanter [ref] watch            # push a workflow's nodes on save
+n8n-decanter completion zsh|bash    # print a shell completion script
+
+# Sync
+n8n-decanter pull [workflow…]       # remote -> workflows/<kebab>/
+n8n-decanter push [workflow…] [--force] [--no-typecheck]
+n8n-decanter watch [workflow]       # push a workflow's nodes on save
                                     #   (+ browser live-reload, opt-in)
-n8n-decanter [ref...] publish       # take the draft(s) live
-n8n-decanter [ref...] unpublish     #   (unpublish returns to draft-only)
-n8n-decanter create "<name>"        # create a blank workflow, then pull it
-n8n-decanter <ref> duplicate ["<new name>"]   # clone a workflow, then pull it
-n8n-decanter <ref> delete [--force]   # delete a workflow from the server
-                                    #   (y/N confirm; --force skips it; the
-                                    #   local folder is left untouched)
-n8n-decanter [ref...] executions [--status=success|error|waiting] [--limit=N]
+n8n-decanter publish [workflow…]    # take the draft(s) live
+n8n-decanter unpublish [workflow…]  #   (unpublish returns to draft-only)
+
+# Workflow lifecycle
+n8n-decanter create "<name>"                 # create a blank workflow, then pull it
+n8n-decanter duplicate <workflow> ["<name>"] # clone a workflow, then pull it
+n8n-decanter delete <workflow> [--force]     # delete from the server (folder kept)
+n8n-decanter rename <workflow> "<new name>"  # rename the workflow (offline; folder stays)
+
+# Inspect & test
+n8n-decanter status [workflow…] [--diff]   # drift report (--diff: line diffs);
+                                    #   exits 1 on conflict/remote drift
+n8n-decanter check [workflow…]      # offline layout-compliance + typecheck
+n8n-decanter executions [workflow…] [--status=success|error|waiting] [--limit=N]
                                     # fetch recent execution data (run JSON)
-                                    #   into workflows/<Name>/executions/
-                                    #   (gitignored temp files; a numeric arg
-                                    #   fetches that one execution by id)
-n8n-decanter [ref...] executions clean   # delete fetched execution data (offline)
-n8n-decanter list [--remote]        # pulled workflows: name, id, folder
-                                    #   (--remote adds unpulled ones)
-n8n-decanter completion zsh|bash    # print a shell completion script
-n8n-decanter <node-file> run [fixture.json] [--allow-env]   # run a node offline, print items
+                                    #   into workflows/<folder>/executions/
+                                    #   (gitignored; numeric arg = one by id)
+n8n-decanter executions [workflow…] clean   # delete fetched execution data (offline)
+n8n-decanter data-tables [table…] [--filter='<json>'] [--search=…] [--sort=col:asc|desc] [--limit=N] [--all]
+                                    # fetch data-table schema + rows (read-only)
+                                    #   into a gitignored top-level data-tables/;
+                                    #   filter/search/sort pull a slice server-side
+n8n-decanter data-tables [table…] clean     # delete fetched data-table data (offline)
+n8n-decanter simulate <workflow> [--execution <execution-id>] [--network-none] [--json]
+                                    # replay the whole workflow through a real
+                                    #   n8n engine (Docker): pure nodes run for
+                                    #   real, network nodes pinned from a capture,
+                                    #   credentials stripped; diffs each node vs
+                                    #   the capture, exits 1 on divergence. In a
+                                    #   terminal, prints a URL to open the run in
+                                    #   n8n. Defaults to the newest capture.
+n8n-decanter simulate <workflow> --pin <execution-id>   # save a capture's outputs as fixtures/
+n8n-decanter list [--remote] [--json]   # pulled workflows: name, id, folder
+                                    #   (--remote adds unpulled ones; --json for tooling)
+
+# Node
+n8n-decanter node create <workflow> "<Node name>" [--ts]        # scaffold a Code node (offline)
+n8n-decanter node rename <workflow> "<old node>" "<new node>"   # rename a node everywhere (offline)
+n8n-decanter node run <node-file> [fixture.json] [--allow-env]  # run a node offline, print items
 ```
 
-A workflow `<ref>` is its **id, its workflow/folder name, or a unique name
-prefix** — `n8n-decanter "Order Sync" push` and `n8n-decanter order push` both
+A `<workflow>` is its **id, its workflow/folder name, or a unique name
+prefix** — `n8n-decanter push "Order Sync"` and `n8n-decanter push order` both
 work. Matching is case-insensitive and never prompts: an ambiguous or unknown
 name errors with the candidate list. `pull` resolves not-yet-pulled names
-against the server's workflow list; a workflow literally named like a verb
-must be addressed by id. Without refs, all workflows from the config are
-processed. The verb may sit anywhere among the arguments (`push wf123` ==
-`wf123 push`) — the first token matching a known verb is the command; flags
-may appear in any position too.
+against the server's workflow list. Without a workflow argument, all workflows
+from the config are processed (or, on a terminal, the picker opens). **The verb
+comes first** (`n8n-decanter push wf123`); everything after it is an argument,
+so a workflow named like a verb needs no special rule and verb-last errors with
+*unknown verb*. Flags may still appear in any position.
 
 Output is styled (color, `✓`/`!`/`✗` glyphs, progress) **only when writing to
 a terminal** and respects `NO_COLOR`/`FORCE_COLOR`; piped or redirected output
@@ -171,25 +198,32 @@ exit 0 — scripts and CI can gate on it like on `check`. `status --diff`
 shows the actual line diff under each drifted node, so you see what a push
 would overwrite before running it. API requests time out after 30 s (set
 `"requestTimeoutMs"` in `decanter.config.json` for slow instances), and
-`DEBUG=1` prints full stack traces on errors. `run` fakes the full Code-node
+`DEBUG=1` prints full stack traces on errors. `node run` fakes the full Code-node
 context including `$getWorkflowStaticData`, seeded from `workflow.json` and
-overridable per fixture. Like n8n's own scoped `$env`, `run`'s `$env` is
+overridable per fixture. Like n8n's own scoped `$env`, `node run`'s `$env` is
 **empty by default** — set it explicitly with the fixture's `"env"` field, or
 pass `--allow-env` to inherit the CLI process's environment (which may include
 `N8N_API_KEY` and other secrets), so a node that prints `$env` never leaks the
 host environment by accident.
 
 `executions` is read-only against the API and writes each execution as
-`workflows/<Name>/executions/<execId>.json` — real run data (the items every
-node produced), meant as temporary reference for building `run` fixtures.
+`workflows/<folder>/executions/<execution-id>.json` — real run data (the items every
+node produced), meant as temporary reference for building `node run` fixtures.
 The dir is written self-gitignored (run data can contain credentials/PII and
 must never land in git); executions reflect the *published* workflow version
 (n8n 2.x), so treat them as convenience data, not ground truth, and remove
 them with `executions clean` when done.
 
-<!--
-"How it compares" is temporarily hidden pending the n8n-as-code maintainer's
-sign-off on the comparison scorings (asked 2026-07-20). Uncomment to restore.
+`data-tables` is the data-table analogue: also read-only against the API, it
+fetches each n8n data table's schema (`columns.json`) and rows (`rows.json`)
+into a **top-level, gitignored** `data-tables/<table>/` dir (data tables are
+project-scoped, not owned by a workflow) so you can develop and debug against
+real table contents. `--filter='<json>'`, `--search`, and `--sort` pull only a
+slice of a large table server-side (the applied filter is recorded in each
+table's `meta.json`); `--limit`/`--all` control page size and exhaustion. It
+never writes a data table. It's gated by the `"dataTables"` config key
+(default on); `data-tables clean` removes the dir (offline). Data tables need
+n8n ≥ 2.x.
 
 ## How it compares
 
@@ -199,6 +233,16 @@ how that focus stacks up against the native editor and against
 [n8n-as-code](https://github.com/EtienneLescot/n8n-as-code) — a broader,
 whole-workflow authoring toolkit.
 
+> **Choose [n8n-as-code](https://github.com/EtienneLescot/n8n-as-code) if you…**
+> need an enterprise-ready automation framework — where AI agents assemble
+> complete workflows, multi-environment Dev → Prod pipelines automatically handle
+> credential governance, and full TypeScript GitOps ensures strict auditability
+> across your team.
+>
+> **Choose n8n-decanter if you…** focus on developer experience inside the Code
+> node — enabling typed TypeScript, shared utility libraries, and live
+> hot-reloading DX directly between VS Code and your n8n canvas (even on Cloud).
+
 | Capability | Native n8n (browser) | n8n-as-code | n8n-decanter |
 |---|---|---|---|
 | **TypeScript for Code nodes** | ❌ JavaScript or Python only | ❌ TS is at workflow level, not node logic | ✅ Code nodes as `.ts`, compiled on push, typed n8n globals |
@@ -206,10 +250,10 @@ whole-workflow authoring toolkit.
 | **Code as individual files** | ❌ no source files (JSON blob) | 🟡 one `.workflow.ts` per workflow | ✅ folder per workflow; each Code node its own `.js`/`.ts` |
 | **Versioning** | 🟡 in-app history (DB snapshots, tiered retention); Git source control is Enterprise-only | ✅ GitOps sync of workflow source | ✅ real git — diffs, PRs, blame; auto-commit each push/pull |
 | **Live editing** | ✅ the canvas (baseline) | 🟡 explicit pull/push, no auto-watch | ✅ `watch`: push on save + auto-reload the editor tab |
-| **Offline testing on historic executions** | 🟡 re-run past executions / pin data, but online in-editor | 🟡 inspect executions against a live env | ✅ fetch real run JSON → offline `run` fixtures, no creds/network |
-| **Agent-native tooling** | 🟡 n8n's own canvas AI, not your agent on the codebase | ✅ Agent Workbench, skills, MCP, Claude/editor plugins | ✅ scaffolds Claude Code / Cursor / Codex configs + MCP; offline `check`/`run` loop; guardrails |
+| **Offline testing on historic executions** | 🟡 re-run past executions / pin data, but online in-editor | 🟡 inspect executions against a live env | ✅ fetch real run JSON → offline `node run` fixtures, no creds/network |
+| **Agent-native tooling** | 🟡 n8n's own canvas AI, not your agent on the codebase | ✅ Agent Workbench, skills, MCP, Claude/editor plugins | ✅ scaffolds Claude Code / Cursor / Codex configs + MCP; offline `check`/`node run` loop; guardrails |
 | **Model ownership** | ❌ locked to n8n's own hosted AI; can't use your Claude subscription | 🟡 beta Claude Code plugin uses your subscription; flagship Workbench needs an Anthropic key for Claude | ✅ never calls an LLM itself — your agent/subscription does 100%, no key or model config ever |
-| **Agentic workflow creation** | 🟡 AI Workflow Builder (natural language), but Cloud / plan-gated — credits, self-host needs setup | ✅ 537 node schemas + 7,700+ templates + skills | 🟡 today via scaffolded n8n-mcp; first-party repo-authored creation planned (`add` + `push --create`) |
+| **Agentic workflow creation** | 🟡 AI Workflow Builder (natural language), but Cloud / plan-gated — credits, self-host needs setup | ✅ 537 node schemas + 7,700+ templates + skills | 🟡 today via scaffolded n8n-mcp; first-party repo-authored creation planned (`node create` + `push --create`) |
 | **Whole-workflow TypeScript authoring** | ❌ | ✅ `.workflow.ts` decorator classes (structure + links) | ❌ keeps `workflow.json`; extracts Code-node source only |
 | **Multi-environment promotion** | 🟡 Enterprise source control / environments | ✅ `promote` remaps creds + refs Dev→Prod | 🟡 separate sync dir per instance, but no `promote` (IDs/creds/refs not remapped) |
 
@@ -221,7 +265,6 @@ n8n-as-code shines for whole-workflow authoring/generation and multi-environment
 ops; the native editor stays the live visual canvas everything syncs back to. And
 decanter makes no LLM calls of its own — you drive it with the coding agent you
 already run, so Claude Code on a Claude subscription needs no extra API tokens.
--->
 
 ## Caveats
 

package/dist/lib/api.mjs

@@ -45,6 +45,49 @@ export class N8nApi {
     async getExecution(id) {
         return this.#request("GET", `/api/v1/executions/${encodeURIComponent(id)}?includeData=true`);
     }
+    /**
+     * All data tables (n8n ≥ 2.x built-in project tables), cursor-paginated like
+     * `listWorkflows`. Read-only by design — the data-table API is never written
+     * through (see lib/datatables.mts). On pre-2.x instances the endpoint 404s;
+     * the caller surfaces that as a friendly hint.
+     */
+    async listDataTables() {
+        const all = [];
+        let cursor;
+        do {
+            const query = new URLSearchParams({ limit: "100", ...(cursor !== undefined && { cursor }) });
+            const page = (await this.#request("GET", `/api/v1/data-tables?${query}`));
+            all.push(...page.data);
+            cursor = page.nextCursor ?? undefined;
+        } while (cursor !== undefined);
+        return all;
+    }
+    /**
+     * A data table's columns (its schema). Tolerates both a bare array and a
+     * `{ data: [...] }` envelope so a shape difference between n8n versions
+     * doesn't break the fetch. Read-only.
+     */
+    async getDataTableColumns(id) {
+        const res = (await this.#request("GET", `/api/v1/data-tables/${encodeURIComponent(id)}/columns`));
+        return Array.isArray(res) ? res : res.data;
+    }
+    /**
+     * One page of a data table's rows. The server-side `filter` (a JSON string of
+     * conditions), `search` (free text over string columns), and `sortBy`
+     * (`col:asc|desc`) narrow the result so callers pull only the rows they need
+     * from a potentially huge table; `limit` (default 100, API cap 250) + `cursor`
+     * paginate. Returns the page plus `nextCursor`. Read-only.
+     */
+    async getDataTableRows(id, { limit = 100, cursor, filter, search, sortBy } = {}) {
+        const query = new URLSearchParams({
+            limit: String(limit),
+            ...(cursor !== undefined && { cursor }),
+            ...(filter !== undefined && { filter }),
+            ...(search !== undefined && { search }),
+            ...(sortBy !== undefined && { sortBy }),
+        });
+        return (await this.#request("GET", `/api/v1/data-tables/${encodeURIComponent(id)}/rows?${query}`));
+    }
     async updateWorkflow(id, body) {
         return this.#request("PUT", `/api/v1/workflows/${encodeURIComponent(id)}`, body);
     }

package/dist/lib/config.mjs

@@ -49,6 +49,8 @@ export function loadConfig(cwd = process.cwd(), { requireCredentials = true } =
                 browserReload: cfg.browserReload === "proxy" ? "proxy" : "off",
                 proxyPort: typeof cfg.proxyPort === "number" ? cfg.proxyPort : 5679,
                 requestTimeoutMs: typeof cfg.requestTimeoutMs === "number" && cfg.requestTimeoutMs > 0 ? cfg.requestTimeoutMs : 30_000,
+                n8nVersion: typeof cfg.n8nVersion === "string" && cfg.n8nVersion !== "" ? cfg.n8nVersion : undefined,
+                dataTables: cfg.dataTables !== false,
                 host,
                 apiKey,
             };

package/dist/lib/datatables.mjs

@@ -0,0 +1,124 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { kebabCase } from "./util.mjs";
+/** Top-level dir (next to decanter.config.json) holding fetched data tables. */
+export const DATA_TABLES_DIR = "data-tables";
+/** Default rows fetched per page — the API caps a page at 250. */
+export const DEFAULT_ROW_LIMIT = 100;
+/**
+ * Folder slug for a fetched table: the kebab of its name with the id appended
+ * (data-table names aren't guaranteed unique, so the id disambiguates). The id
+ * is stripped of anything non-alphanumeric to stay filesystem-safe.
+ */
+export function dataTableSlug(id, name) {
+    const safeId = String(id).replace(/[^A-Za-z0-9]+/g, "") || "id";
+    return `${kebabCase(name)}-${safeId}`;
+}
+/** Pick the tables named by `tableRefs` (id or exact name); empty = all. */
+function selectTables(tables, tableRefs) {
+    if (tableRefs.length === 0)
+        return tables;
+    const picked = new Map();
+    for (const ref of tableRefs) {
+        const lc = ref.toLowerCase();
+        const hits = tables.filter((t) => String(t.id) === ref || t.name.toLowerCase() === lc);
+        if (hits.length === 0) {
+            const known = tables.map((t) => `"${t.name}" (${t.id})`).join(", ");
+            throw new Error(`no data table matches "${ref}"${known ? ` — tables: ${known}` : " — no data tables on the server"}`);
+        }
+        for (const t of hits)
+            picked.set(String(t.id), t);
+    }
+    return [...picked.values()];
+}
+/** Human summary fragment naming the applied server-side filter, or "". */
+function filterSummary(opts) {
+    const parts = [];
+    if (opts.filter !== undefined)
+        parts.push(`filter ${opts.filter}`);
+    if (opts.search !== undefined)
+        parts.push(`search "${opts.search}"`);
+    if (opts.sortBy !== undefined)
+        parts.push(`sort ${opts.sortBy}`);
+    return parts.length > 0 ? ` [${parts.join(", ")}]` : "";
+}
+/**
+ * Fetch data-table schemas + (filtered) rows into a single top-level,
+ * self-ignored `data-tables/` dir — mirrors `executions` (read-only, temp,
+ * gitignored). Data tables are project-scoped (not owned by a workflow), so
+ * they land next to `decanter.config.json`, not under a workflow folder. Each
+ * table becomes `data-tables/<slug>/{meta,columns,rows}.json`; `meta.json`
+ * records the applied filter/search/sort/limit and the row count so a filtered
+ * `rows.json` is self-describing. The CLI never writes any data-table endpoint.
+ */
+export async function fetchDataTables(api, configDir, opts, log) {
+    let tables;
+    try {
+        tables = await api.listDataTables();
+    }
+    catch (err) {
+        const msg = err.message;
+        if (/\b404\b/.test(msg)) {
+            throw new Error(`the n8n data-tables API is not available (404) — data tables need n8n ≥ 2.x; a full-access key still works if your instance predates them\n${msg}`);
+        }
+        throw err;
+    }
+    const selected = selectTables(tables, opts.tableRefs ?? []);
+    if (selected.length === 0) {
+        log.info("no data tables on the server");
+        return;
+    }
+    const outRoot = path.join(configDir, DATA_TABLES_DIR);
+    mkdirSync(outRoot, { recursive: true });
+    // Self-ignoring dir: data tables can hold PII — same reasoning as executions/.
+    writeFileSync(path.join(outRoot, ".gitignore"), "*\n");
+    const rel = (p) => path.relative(process.cwd(), p);
+    const filterDesc = filterSummary(opts);
+    for (const table of selected) {
+        const dir = path.join(outRoot, dataTableSlug(table.id, table.name));
+        mkdirSync(dir, { recursive: true });
+        const columns = await api.getDataTableColumns(String(table.id));
+        const rows = [];
+        let cursor;
+        do {
+            const page = await api.getDataTableRows(String(table.id), {
+                limit: opts.limit ?? DEFAULT_ROW_LIMIT,
+                cursor,
+                filter: opts.filter,
+                search: opts.search,
+                sortBy: opts.sortBy,
+            });
+            rows.push(...page.data);
+            cursor = opts.all ? (page.nextCursor ?? undefined) : undefined;
+        } while (cursor !== undefined);
+        const meta = {
+            id: table.id,
+            name: table.name,
+            projectId: table.projectId ?? null,
+            fetchedAt: new Date().toISOString(),
+            rowCount: rows.length,
+            // A filtered rows.json is a slice, never the whole table — record what
+            // produced it so it can't be mistaken for a full export.
+            filter: opts.filter ?? null,
+            search: opts.search ?? null,
+            sortBy: opts.sortBy ?? null,
+            limit: opts.limit ?? DEFAULT_ROW_LIMIT,
+            all: Boolean(opts.all),
+        };
+        writeFileSync(path.join(dir, "meta.json"), JSON.stringify(meta, null, 2) + "\n");
+        writeFileSync(path.join(dir, "columns.json"), JSON.stringify(columns, null, 2) + "\n");
+        writeFileSync(path.join(dir, "rows.json"), JSON.stringify(rows, null, 2) + "\n");
+        log.info(`wrote ${rel(dir)}/{meta,columns,rows}.json (${columns.length} column${columns.length === 1 ? "" : "s"}, ${rows.length} row${rows.length === 1 ? "" : "s"})`);
+    }
+    log.ok(`${selected.length} data table${selected.length === 1 ? "" : "s"}${filterDesc} -> ${rel(outRoot)} (gitignored — temp data, "data-tables clean" removes it)`);
+}
+/** Offline delete of the local `data-tables/` dir (mirrors cleanExecutions). */
+export function cleanDataTables(configDir, log) {
+    const outRoot = path.join(configDir, DATA_TABLES_DIR);
+    if (!existsSync(outRoot)) {
+        log.info("no data-tables/ dir to clean");
+        return;
+    }
+    rmSync(outRoot, { recursive: true, force: true });
+    log.ok(`removed ${path.relative(process.cwd(), outRoot)}`);
+}