n8n-decanter 0.3.2 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,200 @@ 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
+
+- **Refreshed the scaffolded agent guide (`AGENTS.md`).** It now steers agents
+  to the `rename` and `duplicate` verbs (rename led with the command instead of
+  a hand-edit checklist, `duplicate` added to the new-workflow and command
+  taxonomies), opens with a compact "short version" of the hard invariants,
+  points at `n8n-globals.d.ts` as the authoritative globals list instead of an
+  inline copy that could drift, and drops a stale reference to a non-existent
+  `SCAFFOLD.md`.
+
+## [0.4.0] - 2026-07-20
+
+### Added
+
+- **`add` verb** — `n8n-decanter <ref> add "<Node name>" [--ts]` scaffolds a
+  Code node into a pulled workflow in one offline step: it mints the node id,
+  writes the `code/` source file (kebab-case, with the `-<id8>` collision
+  suffix), adds the node object plus its `//@file:` placeholder, and registers
+  it in `.decanter.json`, then re-checks the folder. The node lands
+  **disconnected** (wire it in the editor); `--ts` scaffolds a `.ts` source.
+  The next `push` propagates it.
+- **`duplicate` verb** — `n8n-decanter <ref> duplicate ["<new name>"]` clones an
+  already-pulled workflow into a **new workflow on the server** and pulls the
+  copy. The clone carries the repo's current content (placeholders
+  reconstituted from `code/`, `.ts` nodes compiled), is born **unpublished**,
+  and defaults its name to `"<name> (copy)"`. The source folder and the source
+  remote workflow are left untouched.
+
+### Removed
+
+- **Breaking: the `uuid` verb is gone.** Its only job was minting a node id for
+  hand-adding a Code node — now `add` does the whole scaffold (id included) in
+  one guard-checked step, so a bare id generator is redundant. Use
+  `n8n-decanter <ref> add "<Node name>"` instead.
+
+## [0.3.4] - 2026-07-20
+
+### Added
+
+- **Modification-aware template refresh.** `init` now records a copy-time
+  baseline of every template file in a git-tracked `.decanter-template.json`
+  manifest. Re-running `init` uses it to refresh files you haven't touched
+  (after a confirm), pull in files newly added to the template, and **leave
+  your local edits alone** — reporting them as drift instead of silently
+  keeping the old version. Files that changed in both the template and your
+  copy are flagged as conflicts and left untouched.
+
+### Changed
+
+- **Re-running `init` is no longer all-or-nothing.** Previously the default
+  refused to overwrite anything and `--force` clobbered every template file.
+  Now the default is modification-aware (see above); `--force` is unchanged —
+  the escape hatch that overwrites everything, now noting which files "had
+  local changes" as it goes.
+
+## [0.3.3] - 2026-07-20
+
+### Changed
+
+- **Interactive picker got a visual refresh.** Each workflow row now leads with
+  a `●` (pulled) / `○` (not pulled) status glyph and the ids line up in an
+  aligned column; each stage carries a short title (`pick a workflow` over the
+  list, the workflow name over its verb menu). The state distinction is now
+  carried by the glyph *shape*, so the per-row `(not pulled)` words are gone —
+  the key is stated once in a footer legend (`● pulled · ○ not pulled`), and
+  the output stays legible under `NO_COLOR`. Behavior (filtering, navigation,
+  verbs) is unchanged.
+
 ## [0.3.2] - 2026-07-20
 
 ### Fixed

package/README.md

@@ -4,12 +4,17 @@
 [![npm](https://img.shields.io/npm/v/n8n-decanter)](https://www.npmjs.com/package/n8n-decanter)
 [![Docs](https://img.shields.io/badge/docs-website-blue.svg)](https://buttjer.github.io/n8n-decanter/)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![vibe coded](https://img.shields.io/badge/vibe%20coded-with%20Claude%20Code-8A2BE2)](https://claude.com/claude-code)
 
 **Work on n8n like a codebase — built for AI coding agents.**
 
 **Pre-1.0 — breaking changes to the data model or CLI may ship in minor
 versions until v1.0.**
 
+> **Built with AI agents.** Much of this codebase was written by Claude Code
+> under human review. It's tested (CI + a real-n8n integration suite) and used
+> in earnest, but treat pre-1.0 the way the version implies.
+
 n8n-decanter syncs your n8n instance into a git-friendly, folder-per-workflow
 layout: every Code node's source becomes its own `.js` or `.ts` file,
 editable in your IDE or by your agent, and pushed back through the n8n API.
@@ -21,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
@@ -64,9 +74,11 @@ directly, no build needed.
 
 `init` copies everything in [template/](template/); files named `X.example`
 land as `X` (the suffix keeps agent configs inert in this repo, live in the
-target). It never overwrites existing files (safe to re-run) unless you pass
-`--force`, which re-copies template files over existing ones (`.env` is never
-touched by it). When `.env` already holds both values, init skips the
+target). Re-running `init` is safe and **modification-aware**: it refreshes
+template files you haven't edited (after a confirm), leaves your local changes
+alone (reporting them as drift), and picks up files new to the template —
+tracked via a `.decanter-template.json` baseline. `--force` is the escape hatch
+that overwrites everything (`.env` is never touched). When `.env` already holds both values, init skips the
 prompts and reuses them — edit or delete `.env` to change credentials. It
 also does a best-effort credential check. Alternatively set up manually: `cp .env.example .env` and
 fill it in. Then add workflow ids to `decanter.config.json`:
@@ -83,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.
 
@@ -98,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`, and `uuid` are fully
+under `node_modules`). The verbs `check`, `node run`, `rename`, and `node create` are fully
 offline (no credentials, no network).
 
 ## Commands
@@ -110,44 +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] 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> 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
-n8n-decanter uuid [count]           # lowercase v4 UUID(s) for new node ids
+                                    #   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
@@ -163,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
 
@@ -191,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 |
@@ -198,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) |
 
@@ -213,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/add.mjs

@@ -0,0 +1,91 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { findWorkflowDir, readState, writeState } from "./state.mjs";
+import { CODE_DIR, CODE_NODE_TYPE, FILE_PLACEHOLDER_PREFIX, kebabCase, stableWorkflowJson } from "./util.mjs";
+import { validateWorkflowDir } from "./validate.mjs";
+/**
+ * Starter source for a freshly scaffolded Code node: valid, self-contained
+ * (no `$('…')` references, so it lands compliant), and it typechecks under the
+ * n8n ambient globals — the same body for `.js` and `.ts`.
+ */
+const DEFAULT_SOURCE = `// New Code node — runs once for all items. Edit me, then push.
+// See https://docs.n8n.io/code/ for the Code node API.
+for (const item of $input.all()) {
+  item.json.myNewField = 1;
+}
+
+return $input.all();
+`;
+/** Rightmost node's x + a step, so a scaffolded node doesn't stack on another. */
+function nextPosition(nodes) {
+    let maxX = 0;
+    for (const node of nodes) {
+        const pos = node.position;
+        if (Array.isArray(pos) && typeof pos[0] === "number")
+            maxX = Math.max(maxX, pos[0]);
+    }
+    return [maxX + 220, 0];
+}
+/**
+ * Scaffold a `n8n-nodes-base.code` node into a pulled workflow in one atomic,
+ * guard-checked step (offline; `push` propagates). Mints a v4 uuid, writes the
+ * kebab-case source file under `code/` (sharing pull/rename's `-<id8>` collision
+ * suffix), appends the node object (default parameters, `mode:
+ * runOnceForAllItems`, a `//@file:` placeholder) to `workflow.json`, and
+ * registers it in `.decanter.json`. **No connections are wired** — the node
+ * lands disconnected but compliant; wiring stays in the editor. Re-validates
+ * afterwards and fails loudly on any violation, exactly like `rename`.
+ */
+export function addCodeNode(root, id, nodeName, { ts = false } = {}, log) {
+    nodeName = nodeName.trim();
+    if (!nodeName)
+        throw new Error("node name must not be empty");
+    const dir = findWorkflowDir(root, id, log);
+    if (!dir)
+        throw new Error(`workflow ${id} not found under ${root} — pull it first`);
+    const wfFile = path.join(dir, "workflow.json");
+    if (!existsSync(wfFile))
+        throw new Error(`missing workflow.json in ${dir} — pull first`);
+    let wf;
+    try {
+        wf = JSON.parse(readFileSync(wfFile, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`${wfFile}: invalid JSON (${err.message})`);
+    }
+    if (wf.nodes.some((n) => n.name === nodeName))
+        throw new Error(`a node named "${nodeName}" already exists in "${wf.name}"`);
+    const nodeId = randomUUID();
+    const ext = ts ? ".ts" : ".js";
+    mkdirSync(path.join(dir, CODE_DIR), { recursive: true });
+    let base = kebabCase(nodeName);
+    if (existsSync(path.join(dir, CODE_DIR, `${base}${ext}`))) {
+        base = `${base}-${nodeId.slice(0, 8)}`;
+        if (existsSync(path.join(dir, CODE_DIR, `${base}${ext}`))) {
+            throw new Error(`cannot add "${nodeName}": both kebab-case targets exist (${CODE_DIR}/${base}${ext})`);
+        }
+    }
+    const file = `${CODE_DIR}/${base}${ext}`;
+    writeFileSync(path.join(dir, file), DEFAULT_SOURCE);
+    const node = {
+        id: nodeId,
+        name: nodeName,
+        type: CODE_NODE_TYPE,
+        typeVersion: 2,
+        position: nextPosition(wf.nodes),
+        parameters: { mode: "runOnceForAllItems", jsCode: FILE_PLACEHOLDER_PREFIX + file },
+    };
+    wf.nodes.push(node);
+    writeFileSync(wfFile, stableWorkflowJson(wf));
+    const state = readState(dir);
+    if (state) {
+        state.nodes[nodeId] = { file };
+        writeState(dir, state);
+    }
+    log.info(`added Code node "${nodeName}" (${nodeId}) -> ${file} — disconnected; wire it in the editor, then push to propagate`);
+    const { errors } = validateWorkflowDir(dir);
+    if (errors.length > 0) {
+        throw new Error(`add left the workflow non-compliant — files were written, inspect (git diff) and fix:\n${errors.map((e) => `  ${e}`).join("\n")}`);
+    }
+}

package/dist/lib/api.mjs

@@ -45,18 +45,62 @@ 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);
     }
     /**
-     * Create a blank draft on the server (n8n 2.x `POST /workflows`). The minimal
-     * accepted body is name + empty nodes/connections/settings (verified against
-     * 2.30.7 — name-only is rejected). Born **unpublished** (`active:false`); the
-     * caller pulls the returned id so the folder + state land. `createWorkflow` is
-     * the shared entry point Plan 21's `duplicate` reuses.
+     * Create a workflow on the server (n8n 2.x `POST /workflows`). The required
+     * fields are name + nodes/connections/settings (verified against 2.30.7 —
+     * name-only is rejected), so `create` posts empty collections while
+     * `duplicate` posts the cloned nodes/connections. Born **unpublished**
+     * (`active:false`); the caller pulls the returned id so the folder + state
+     * land. Shared by `create` (blank) and `duplicate` (Plan 21).
      */
-    async createWorkflow(name) {
-        return this.#request("POST", "/api/v1/workflows", { name, nodes: [], connections: {}, settings: {} });
+    async createWorkflow(body) {
+        return this.#request("POST", "/api/v1/workflows", body);
     }
     /** Take the draft live (n8n 2.x publish). Idempotent server-side; returns the workflow. */
     async activateWorkflow(id) {

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,
             };