n8n-decanter 0.3.0

package/template/.claude/settings.local.json.example

@@ -0,0 +1,35 @@
+{
+  "permissions": {
+    "allow": [
+      "Edit(workflows/**)",
+      "Edit(shared/**)",
+      "Bash(n8n-decanter check)",
+      "Bash(n8n-decanter check:*)",
+      "Bash(n8n-decanter run:*)",
+      "Bash(n8n-decanter uuid:*)",
+      "Bash(n8n-decanter status:*)",
+      "Bash(npm run typecheck)",
+      "Bash(npm run check)"
+    ],
+    "deny": [
+      "Edit(**/.decanter.json)",
+      "Edit(**/*.remote.js)",
+      "Read(.env)",
+      "Edit(.env)",
+      "Bash(n8n-decanter push --force)",
+      "Bash(n8n-decanter push --force:*)",
+      "Bash(node n8n-decanter.mts push --force)",
+      "Bash(node n8n-decanter.mts push --force:*)"
+    ]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          { "type": "command", "command": "node .claude/hooks/verify.mjs" }
+        ]
+      }
+    ]
+  }
+}

package/template/.cursor/rules/n8n-decanter.mdc.example

@@ -0,0 +1,21 @@
+---
+description: n8n-decanter repo — how to treat decanted workflow files
+alwaysApply: true
+---
+
+This repository is managed by **n8n-decanter**. The authoritative contract is
+`AGENTS.md` at the repo root — read it in full before editing workflow files.
+
+Hard rules (violating any of these corrupts sync state):
+
+- `jsCode` in any `workflow.json` is only a `//@file:code/<name>` placeholder. Never
+  inline code there — edit the referenced source file in the folder's `code/` subdir.
+- Never edit `.decanter.json` (machine state) or any `*.remote.js` (incoming-change
+  artifact — port its change into the matching `.ts`, then delete it).
+- Never write a `// @ts-n8n sha256:` line — the tool appends it on push.
+- Code nodes run as a function body with a top-level `return`, no `import`/`require`.
+- Run `npm run typecheck` after editing node source. `push` is a deploy — only when asked,
+  and never `--force` without an explicit instruction.
+
+Cursor applies this as guidance only; the n8n-decanter CLI enforces the same invariants
+at `push` regardless of which tool made the edit.

package/template/.env.example

@@ -0,0 +1,10 @@
+# Copy to .env and fill in. .env is gitignored.
+N8N_HOST=https://your-n8n.example.com
+
+# Prefer a SCOPED API key (n8n → Settings → n8n API → Create) limited to the
+# permissions this tool actually uses, not a full-access key — smaller blast
+# radius if .env leaks:
+#   workflow:read  workflow:list  workflow:update    (pull / status / push)
+#   execution:read  execution:list                   (executions)
+# A full-access key also works.
+N8N_API_KEY=n8n_api_...

package/template/.mcp.json.example

@@ -0,0 +1,16 @@
+{
+  "mcpServers": {
+    "n8n-mcp": {
+      "command": "sh",
+      "args": [
+        "-c",
+        "set -a; [ -f ./.env ] && . ./.env; set +a; if [ -n \"$N8N_HOST\" ]; then N8N_API_URL=\"$N8N_HOST\"; export N8N_API_URL; fi; exec npx n8n-mcp"
+      ],
+      "env": {
+        "MCP_MODE": "stdio",
+        "LOG_LEVEL": "error",
+        "DISABLE_CONSOLE_OUTPUT": "true"
+      }
+    }
+  }
+}

package/template/.vscode/settings.json.example

@@ -0,0 +1,6 @@
+{
+  // Use the workspace TypeScript (devDependency) so tsserver can load
+  // decanter-ts-plugin from node_modules — VS Code asks once ("Use Workspace
+  // Version"). The bundled tsserver cannot see workspace plugins.
+  "typescript.tsdk": "node_modules/typescript/lib"
+}

package/template/AGENTS.md.example

@@ -0,0 +1,302 @@
+# n8n-decanter — guide for coding agents
+
+This is the **source of truth** for working in this repository, and it is written to
+be tool-agnostic. Codex and opencode read this file natively; Claude Code reads it
+through a one-line `@AGENTS.md` import in `CLAUDE.md`; other agents can be pointed at
+it (see `SCAFFOLD.md`). Keep project-specific rules here so every agent stays in sync.
+
+This repo holds n8n workflows *decanted* into git-friendly form: one folder per
+workflow containing `workflow.json` plus a `code/` subdir with one source file
+per Code node. The
+`n8n-decanter` CLI moves content between here and the live n8n instance
+(`pull` / `push`). This document is the contract for creating and editing these files.
+
+## How this differs from standard n8n editing — read this first
+
+Your general n8n knowledge (docs, n8n MCP tools, training data) is **valid** for:
+node types and parameters, expression syntax, connection semantics, the Code-node
+runtime. It is **wrong** about how code is stored here. The deviations:
+
+1. **`jsCode` in `workflow.json` never contains code.** Its entire value is a
+   placeholder: `//@file:code/<filename>`
+   (e.g. `"jsCode": "//@file:code/amazon-feed.ts"`).
+   Never inline JavaScript into `workflow.json`; edit the referenced file.
+2. **Code node sources live in the folder's `code/` subdir**, named after the
+   node in kebab-case (`Amazon Feed` → `code/amazon-feed.ts`). `.js` files are
+   pushed verbatim (what you write is exactly what runs in n8n). `.ts` files
+   are compiled on push; the local `.ts` is the only source of truth — n8n
+   holds compiled output.
+3. **Never write a `// @ts-n8n sha256:…` line.** That marker is appended by the
+   tool to *compiled* output on push. It must not appear in any repo file.
+4. **`.decanter.json` is machine state** (node-id → filename map, drift-detection
+   hashes). Never edit it by hand; never "fix" a hash.
+5. **`code/<node>.remote.js` is an incoming-change artifact** written by `pull` when
+   someone edited a TS-managed node in the n8n UI. Handle it like an incoming
+   diff: port the change into the `.ts`, delete the `.remote.js`, then the user
+   pushes. Never edit `.remote.js` itself; never push while one exists.
+6. **Renames have no UI magic here.** The n8n editor auto-updates references on
+   rename; raw JSON editing does not. See the rename checklist below.
+7. **New workflows are born in n8n, not here.** The tool has no create. To add a
+   workflow: create it (even empty) in the n8n UI, add its id to
+   `decanter.config.json`, then the user runs `pull`.
+
+> **Enforcement.** Rules 1, 3, 4, 5 are *hard invariants* — violating them corrupts
+> sync state. They are enforced by the CLI at `push` time regardless of who made the
+> edit (any agent, or a human). On Claude Code and opencode they are additionally
+> guarded before the write happens (see `.claude/settings.json` and `opencode.json`).
+> If a write is blocked with a `decanter-guard` reason, the edit broke a hard rule —
+> fix the edit, don't work around the guard.
+
+## File ownership
+
+| File | Written by | May the agent edit it? |
+|---|---|---|
+| `workflow.json` | pull + you | Yes — structure, parameters, connections. Placeholders stay placeholders. |
+| `code/<node>.js` | pull + you | Yes — this is live node code, verbatim. |
+| `code/<node>.ts` | you only | Yes — pull never touches it. |
+| `code/<node>.remote.js` | pull only | No — read, port into the `.ts`, delete. |
+| `.decanter.json` | tool only | No. |
+| `decanter.config.json` | you | Yes — add/remove workflow ids. |
+| `n8n-globals.d.ts` | you | Yes — extend when node code uses a global it doesn't cover yet. |
+
+## Editing `workflow.json`
+
+Pretty-printed, 2-space indent, keep the existing key order (clean diffs are the
+point of this repo).
+
+A node object:
+
+```json
+{
+  "id": "a1b2c3d4-…",            // UUID v4 — `n8n-decanter uuid` to generate; NEVER change an existing id
+  "name": "Amazon Feed",          // unique per workflow — connections + $('…') reference it
+  "type": "n8n-nodes-base.code",
+  "typeVersion": 2,
+  "position": [880, 300],
+  "parameters": {
+    "mode": "runOnceForAllItems", // or "runOnceForEachItem"
+    "jsCode": "//@file:code/amazon-feed.ts"
+  }
+}
+```
+
+Connections are keyed by **node name**, not id:
+
+```json
+"connections": {
+  "Fetch Products": { "main": [[{ "node": "Amazon Feed", "type": "main", "index": 0 }]] }
+}
+```
+
+Rules:
+
+- **Expressions** in parameters keep their `=` prefix: `"={{ $json.sku }}"`.
+  A value without `=` is a literal string.
+- **Credentials** are referenced as `{ "id": "…", "name": "…" }` and must already
+  exist in n8n — never invent credential ids.
+- **Not synced / don't add:** `active`, `tags`, `pinData`, `shared`, timestamps.
+  The push endpoint only accepts `name`, `nodes`, `connections`, `settings`
+  (whitelisted keys), `staticData`. Activation is managed in the n8n UI.
+- **Position:** keep a sensible grid; new nodes roughly +200 x from their input.
+
+### Renaming a node — checklist (all four, atomically)
+
+1. `name` in the node object.
+2. Every reference in `connections` (keys *and* target `"node"` values).
+3. Every `$('Old Name')` in **all** code files of the workflow.
+4. The source file name and its `//@file:` placeholder (keep the kebab-case
+   name-file convention, file stays in `code/`). The tool re-maps by node id
+   on the next pull, but the repo must be self-consistent immediately.
+
+Renaming a **workflow**: change `name` in `workflow.json`; folder rename happens
+on the next pull (or do it yourself, folder names are cosmetic — the id inside
+`workflow.json` is authoritative).
+
+### Adding a Code node
+
+1. Add the node object — generate its `id` with `n8n-decanter uuid` (a lowercase
+   v4 UUID), placeholder `jsCode`, position, connections.
+2. Create the source file it points at in `code/` (`.js` or `.ts`, see below).
+3. Verify: `n8n-decanter run <file> [fixture.json]` to execute it, then
+   `n8n-decanter check` (typecheck + layout).
+
+## Writing Code node code
+
+The runtime contract (identical for `.js` and `.ts` — types are erased):
+
+- Code runs as a function body, **top-level `return` required**.
+  - `runOnceForAllItems`: return an array of items: `[{ json: {…} }, …]`.
+    Always wrap in `{ json: … }` explicitly.
+  - `runOnceForEachItem`: return a single `{ json: {…} }`.
+  - Editors squiggle that top-level `return`/`await` (TS1108/TS1375/TS1378) —
+    a **false positive** from the editor's own tsserver; ignore it, and never
+    "fix" it by wrapping the file in a function. `n8n-decanter check` wraps
+    node bodies in memory before typechecking and is authoritative.
+    The bundled `decanter-ts-plugin/` suppresses exactly these three codes on
+    node files (all other diagnostics stay live) once tsserver runs the
+    workspace TypeScript: `npm install`, then in VS Code accept
+    *Use Workspace Version* (offered via `.vscode/settings.json`'s
+    `typescript.tsdk`; JetBrains uses the project TypeScript by default).
+- Available globals (extend `n8n-globals.d.ts` when you use one it lacks):
+  `$input.all()/.first()/.last()/.item` · `$('Node Name').all()/.first()/.item/.itemMatching(i)` ·
+  `$json`, `$binary`, `$itemIndex` (each-item mode) ·
+  `DateTime`, `Duration`, `Interval` (Luxon), `$now`, `$today` ·
+  `$jmespath()` · `$workflow`, `$execution`, `$prevNode`, `$runIndex` ·
+  `$getWorkflowStaticData('global' | 'node')`.
+- **Imports**: `.js` nodes — none at all (they run verbatim; assume the
+  instance allows no external or built-in modules). `.ts` nodes — imports
+  from inside this repo (`shared/`, relative paths) and from npm packages
+  listed in `decanter.config.json`'s `"bundleDependencies"` are **bundled
+  into the compiled node on push** (self-contained output, works on any
+  instance incl. n8n Cloud). Rules: imports at the **top of the file** only;
+  relative paths must stay inside this repo; unlisted npm packages and Node
+  builtins (`node:*`, `fs`, `crypto`, …) are compile errors. Never
+  `require()`.
+- `console.log` is available for debugging (visible in the execution view).
+- `$('Node Name')` takes the node's **name** — see the rename checklist.
+
+### `.js` nodes (default — lossless)
+
+What you write is byte-for-byte what runs and what round-trips back on pull.
+Type-safety via JSDoc:
+
+```js
+// @ts-check
+
+/** @typedef {{ sku: string, qty: number }} StockLine */
+
+/** @type {StockLine[]} */
+const lines = [];
+for (const item of $input.all()) {
+  // …
+}
+return lines.map((l) => ({ json: l }));
+```
+
+- First line is `// @ts-check`.
+- Prefer `@typedef` for shapes, inline casts `/** @type {Foo} */ (x)` where
+  narrowing is needed. `@template`, `@satisfies` are available.
+- Comments are fine and encouraged — they survive into n8n and document the
+  node in place.
+
+### `.ts` nodes (one-way)
+
+Choose `.ts` when the type surface is heavy (large interfaces, generics,
+discriminated unions). Costs, so you can weigh them:
+
+- esbuild compiles on push: **comments are stripped** and **line numbers shift**
+  — n8n error line numbers won't match the source, and the node code in the
+  n8n UI is undocumented output. Documentation belongs in the `.ts`.
+- UI edits can't be merged back automatically (they arrive as `.remote.js`).
+
+Rules: full TS is fine (interfaces, type aliases, enums, generics); still
+ends in a top-level `return`. Never commit compiled output; never add the
+marker line.
+
+**Shared code (`shared/`)**: put helpers and types used by several nodes in
+`shared/*.ts` and import them from `.ts` nodes — types *and* functions:
+
+```ts
+import { total, type OrderLine } from "../../shared/money";
+
+const lines: OrderLine[] = $input.all().map((i) => i.json as OrderLine);
+return [{ json: { total: total(lines) } }];
+```
+
+Push inlines the imported code into the compiled node (each importing node
+carries its own copy — keep helpers small). Editing a shared file makes every
+importing node show up as "push pending" in `status`; push to propagate.
+Small npm libraries work the same way once installed here (`npm i zod`) and
+opted in via `"bundleDependencies": ["zod"]` in `decanter.config.json` —
+pure-JS packages only (no native addons, no builtins). `.js` nodes cannot
+import; give them JSDoc `@typedef`s or convert to `.ts`.
+
+### Switching a node `.js` → `.ts` (or back)
+
+1. Rename the file, convert JSDoc ↔ annotations.
+2. Update the `//@file:` placeholder in `workflow.json`.
+3. `n8n-decanter check`. The tool picks up the new extension on next push;
+   direction of sync changes accordingly (`.ts` = one-way).
+
+## Verification
+
+Two offline tools, always available (no credentials, no network, no live n8n):
+
+- **`n8n-decanter check`** — runs the layout-compliance guard *and* the
+  typecheck (the same wrapper that maps top-level-`return` node bodies back to
+  real line numbers). Run it after editing any code file or `n8n-globals.d.ts`;
+  treat a failure as a blocker. `npm run typecheck` is an alias for it.
+- **`n8n-decanter run <file> [fixture.json]`** — actually executes a node's body
+  against a faked n8n context (`$input`, `$json`, `$('Node')`, `DateTime`, …) and
+  prints the items it returns. Prefer this over hand-rolling a throwaway test
+  script.
+  - The optional fixture JSON supplies the context; every field is optional:
+
+    ```json
+    {
+      "input":  [{ "json": { "sku": "A1" } }],
+      "nodes":  { "Fetch Products": [{ "json": { "id": 1 } }] },
+      "env":    { "REGION": "eu" },
+      "staticData": { "global": { "cursor": 42 } }
+    }
+    ```
+
+    `input` feeds `$input`/`$json`; `nodes` backs `$('Node Name')`; without a
+    fixture the input defaults to a single empty item. `env` backs `$env`,
+    which is **empty by default** (like n8n's scoped `$env`) — set it here, or
+    pass `--allow-env` to inherit the process environment (may include
+    `N8N_API_KEY`; never `run --allow-env` an untrusted node).
+    `$getWorkflowStaticData` is seeded from `workflow.json`'s `staticData`
+    (`global` and this node's `node:` slice); a fixture `staticData` replaces
+    the matching slice (`"node"` = the node being run). Mutations are visible
+    during the run but never persisted — `run` is offline.
+  - Run mode (`runOnceForAllItems` / `runOnceForEachItem`) is read from the node
+    in `workflow.json`, so each-item nodes are looped once per input item.
+- JSON validity of `workflow.json` after every structural edit.
+
+## Real execution data (`executions/` — temporary, gitignored)
+
+When you need to see what data actually flows through a workflow — to write an
+accurate `run` fixture, or to debug a node against real payloads — fetch recent
+executions from the instance instead of guessing shapes:
+
+```sh
+n8n-decanter "<workflow>" executions                    # 5 most recent, full run data
+n8n-decanter "<workflow>" executions --status=error --limit=3
+n8n-decanter executions 4711                            # one execution by its id
+```
+
+Each execution lands as `workflows/<Name>/executions/<execId>.json`. The items
+a node produced are under
+`data.resultData.runData["<Node Name>"][0].data.main[0][]` — each entry's
+`.json` is one item, exactly what `$('<Node Name>')` (and the downstream node's
+`$input`) sees at runtime. Copy real item shapes from here into `run` fixtures.
+
+Rules:
+
+- **Temporary working data, never committed.** The tool writes the dir
+  self-ignoring (`executions/.gitignore` containing `*`) because run data can
+  hold credentials and PII — never weaken that, and never copy secrets from it
+  into code or fixtures.
+- **Clean up when the task that needed it is done:**
+  `n8n-decanter executions clean` (offline; removes every `executions/` dir,
+  or pass a workflow ref to scope it).
+- **Convenience, not ground truth.** Executions run the *published* workflow
+  version (n8n 2.x), which may be older than the local draft, and payloads
+  change over time — re-fetch rather than trusting stale files.
+
+## Commands — who runs what
+
+- **Offline, safe — run freely:** `n8n-decanter check` (or `npm run typecheck`),
+  `n8n-decanter run <file> [fixture]`, `n8n-decanter uuid [n]`,
+  `n8n-decanter executions clean`. These never touch the network.
+- **Reads remote, no writes:** `n8n-decanter status` (`--diff` shows the line
+  diffs; exits 1 on conflict/remote drift) and `n8n-decanter <ref> executions`
+  (fetches execution data, read-only) — safe to run, but they do contact the
+  instance.
+- **Live n8n instance — only when the user explicitly asks:** `n8n-decanter
+  pull` / `push` / `watch` read/write the real instance and `push` deploys.
+  Otherwise finish edits, verify with `check` + `run`, and report that the
+  change is ready to push.
+- Never use `--force` on push without the user's explicit instruction — it
+  overrides the drift guard that protects edits made in the n8n UI.

package/template/CLAUDE.md.example

@@ -0,0 +1,20 @@
+@AGENTS.md
+
+## Claude Code specifics
+
+The contract above (from `AGENTS.md`) is authoritative. A few Claude-only notes:
+
+- **File-level invariants are enforced by `.claude/settings.local.json`.** Its
+  permission deny-list blocks edits to `.decanter.json` and `*.remote.js`, reads/edits
+  of `.env`, and `push --force`. If an `Edit`/`Write` is blocked, it broke a hard rule —
+  fix the edit, don't route around the guard. The content-level invariants (jsCode
+  placeholder integrity, the `@ts-n8n` marker) are the CLI's wall at `push`/`check`.
+- **After editing a node source (`.ts`/`.js`), a PostToolUse hook runs
+  `n8n-decanter check`** (layout compliance + typecheck) via `.claude/hooks/verify.mjs`
+  and feeds any failure back to you. Treat a failure as a blocker to finishing the task.
+  The hook is a quiet no-op until the CLI is on your PATH (install it globally or
+  `npm link` it) — until then run `n8n-decanter check` / `n8n-decanter run` yourself.
+- **Renames must be atomic** (all four steps in the AGENTS.md rename checklist land in
+  one change). Use plan mode for multi-node renames so nothing is left half-updated.
+- **`push --force` is blocked from the agent by design.** It overrides the drift guard;
+  if it is genuinely needed, ask the user to run it themselves in the terminal.

package/template/decanter-ts-plugin/index.js.example

@@ -0,0 +1,58 @@
+// decanter-ts-plugin — TypeScript language-service plugin that hides the
+// editor-only false positives on n8n Code node files. Node source is a
+// *function body* (top-level `return` / `await` is legal), but the editor's
+// tsserver reads the raw file and reports TS1108 / TS1375 / TS1378.
+// `n8n-decanter check` wraps node bodies in memory and stays authoritative;
+// this plugin only filters those three codes in the editor, for node files
+// only — every other diagnostic and every other file passes through.
+//
+// CommonJS on purpose: tsserver loads plugins via require(). Loaded through
+// the tsconfig "plugins" entry; resolves from node_modules via the
+// `file:./decanter-ts-plugin` devDependency (VS Code needs the workspace
+// TypeScript version for that — see AGENTS.md).
+const FILTERED = new Set([
+  1108, // A 'return' statement can only be used within a function body.
+  1375, // 'await' expressions are only allowed at the top level of a module …
+  1378, // Top-level 'await' expressions require module es2022+ …
+]);
+
+function init({ typescript: ts }) {
+  function create(info) {
+    const ls = info.languageService;
+    const fileExists = (p) =>
+      info.languageServiceHost.fileExists
+        ? info.languageServiceHost.fileExists(p)
+        : ts.sys.fileExists(p);
+
+    // Mirrors isNodeFile in n8n-decanter's scripts/typecheck.mts — keep the
+    // two in sync: .ts/.js, not *.d.ts / *.remote.js, with a .decanter.json
+    // sibling directly or (code/ layout) in the parent of the code/ dir.
+    function isNodeFile(fileName) {
+      const file = fileName.replace(/\\/g, "/");
+      if (file.endsWith(".d.ts") || file.endsWith(".remote.js")) return false;
+      if (!/\.(ts|js)$/.test(file)) return false;
+      const cut = file.lastIndexOf("/");
+      if (cut < 0) return false;
+      const dir = file.slice(0, cut);
+      if (fileExists(dir + "/.decanter.json")) return true;
+      return dir.endsWith("/code") && fileExists(dir.slice(0, -"/code".length) + "/.decanter.json");
+    }
+
+    const proxy = Object.create(null);
+    for (const k of Object.keys(ls)) {
+      proxy[k] = (...args) => ls[k].apply(ls, args);
+    }
+    const filtered = (fileName, diags) =>
+      isNodeFile(fileName) ? diags.filter((d) => !FILTERED.has(d.code)) : diags;
+    // Both channels: grammar errors like 1108 are raised in the checker
+    // (semantic) on current TS, but cover syntactic too in case a TS version
+    // moves them.
+    proxy.getSemanticDiagnostics = (fileName) => filtered(fileName, ls.getSemanticDiagnostics(fileName));
+    proxy.getSyntacticDiagnostics = (fileName) => filtered(fileName, ls.getSyntacticDiagnostics(fileName));
+    return proxy;
+  }
+
+  return { create };
+}
+
+module.exports = init;

package/template/decanter-ts-plugin/package.json.example

@@ -0,0 +1,7 @@
+{
+  "name": "decanter-ts-plugin",
+  "private": true,
+  "version": "0.0.0",
+  "description": "tsserver plugin: suppress false TS1108/TS1375/TS1378 on n8n Code node files",
+  "main": "index.js"
+}

package/template/n8n-globals.d.ts.example

@@ -0,0 +1,190 @@
+// Ambient globals available inside n8n Code nodes ("Run Once for All Items" /
+// "Run Once for Each Item"). Pragmatic subset — loose where n8n is dynamic.
+
+interface N8nBinaryData {
+  data: string;
+  mimeType: string;
+  fileName?: string;
+  fileExtension?: string;
+  fileSize?: string;
+  directory?: string;
+  id?: string;
+  [key: string]: unknown;
+}
+
+interface N8nItem {
+  json: Record<string, any>;
+  binary?: Record<string, N8nBinaryData>;
+  pairedItem?: number | { item: number; input?: number };
+  error?: Error;
+}
+
+interface N8nInput {
+  all(branchIndex?: number, runIndex?: number): N8nItem[];
+  first(branchIndex?: number, runIndex?: number): N8nItem;
+  last(branchIndex?: number, runIndex?: number): N8nItem;
+  /** Only in "Run Once for Each Item" mode. */
+  item: N8nItem;
+  params?: Record<string, any>;
+}
+
+interface N8nNodeRef {
+  all(branchIndex?: number, runIndex?: number): N8nItem[];
+  first(branchIndex?: number, runIndex?: number): N8nItem;
+  last(branchIndex?: number, runIndex?: number): N8nItem;
+  item: N8nItem | undefined;
+  itemMatching(itemIndex: number): N8nItem;
+  params: Record<string, any>;
+  context: Record<string, any>;
+  isExecuted: boolean;
+}
+
+/** Access output of an earlier node: `$("Node Name").all()` */
+declare function $(nodeName: string): N8nNodeRef;
+
+declare const $input: N8nInput;
+/** Shorthand for the current item's json ("Run Once for Each Item" mode). */
+declare const $json: Record<string, any>;
+declare const $binary: Record<string, N8nBinaryData>;
+declare const $env: Record<string, string | undefined>;
+
+declare const $execution: {
+  id: string;
+  mode: "test" | "production";
+  resumeUrl?: string;
+  resumeFormUrl?: string;
+  customData?: {
+    set(key: string, value: string): void;
+    get(key: string): string | undefined;
+    setAll(values: Record<string, string>): void;
+    getAll(): Record<string, string>;
+  };
+};
+
+declare const $workflow: { id: string; name: string; active: boolean };
+declare const $prevNode: { name: string; outputIndex: number; runIndex: number };
+declare const $runIndex: number;
+declare const $itemIndex: number;
+declare const $nodeVersion: number;
+declare const $nodeId: string;
+declare const $webhookId: string | undefined;
+
+/** Per-workflow / per-node persisted store. */
+declare function $getWorkflowStaticData(type: "global" | "node"): Record<string, any>;
+
+declare function $jmespath(data: unknown, expression: string): any;
+declare function $evaluateExpression(expression: string, itemIndex?: number): any;
+declare function $if<T, F>(condition: boolean, valueIfTrue: T, valueIfFalse: F): T | F;
+declare function $min(...numbers: number[]): number;
+declare function $max(...numbers: number[]): number;
+
+/** Legacy helpers */
+declare function $items(nodeName?: string, outputIndex?: number, runIndex?: number): N8nItem[];
+declare const $node: Record<string, N8nNodeRef>;
+
+/** Luxon DateTime (subset). */
+declare class DateTime {
+  static now(): DateTime;
+  static fromISO(text: string, opts?: object): DateTime;
+  static fromMillis(ms: number, opts?: object): DateTime;
+  static fromSeconds(seconds: number, opts?: object): DateTime;
+  static fromJSDate(date: Date, opts?: object): DateTime;
+  static fromFormat(text: string, format: string, opts?: object): DateTime;
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  second: number;
+  millisecond: number;
+  weekday: number;
+  zoneName: string;
+  isValid: boolean;
+  plus(duration: object | number): DateTime;
+  minus(duration: object | number): DateTime;
+  startOf(unit: string): DateTime;
+  endOf(unit: string): DateTime;
+  set(values: object): DateTime;
+  setZone(zone: string, opts?: object): DateTime;
+  setLocale(locale: string): DateTime;
+  diff(other: DateTime, unit?: string | string[], opts?: object): any;
+  diffNow(unit?: string | string[], opts?: object): any;
+  hasSame(other: DateTime, unit: string): boolean;
+  toISO(opts?: object): string | null;
+  toISODate(): string | null;
+  toISOTime(opts?: object): string | null;
+  toFormat(format: string, opts?: object): string;
+  toLocaleString(opts?: object): string;
+  toMillis(): number;
+  toSeconds(): number;
+  toJSDate(): Date;
+  toUTC(offset?: number, opts?: object): DateTime;
+  valueOf(): number;
+}
+
+/** Luxon Duration (subset). */
+declare class Duration {
+  static fromObject(values: object, opts?: object): Duration;
+  static fromMillis(ms: number, opts?: object): Duration;
+  static fromISO(text: string, opts?: object): Duration;
+  years: number;
+  quarters: number;
+  months: number;
+  weeks: number;
+  days: number;
+  hours: number;
+  minutes: number;
+  seconds: number;
+  milliseconds: number;
+  isValid: boolean;
+  as(unit: string): number;
+  get(unit: string): number;
+  plus(duration: Duration | object | number): Duration;
+  minus(duration: Duration | object | number): Duration;
+  negate(): Duration;
+  normalize(): Duration;
+  shiftTo(...units: string[]): Duration;
+  set(values: object): Duration;
+  toObject(): Record<string, number>;
+  toISO(opts?: object): string | null;
+  toFormat(format: string, opts?: object): string;
+  toHuman(opts?: object): string;
+  toMillis(): number;
+  valueOf(): number;
+}
+
+/** Luxon Interval (subset). */
+declare class Interval {
+  static fromDateTimes(start: DateTime | Date, end: DateTime | Date): Interval;
+  static after(start: DateTime | Date, duration: Duration | object | number): Interval;
+  static before(end: DateTime | Date, duration: Duration | object | number): Interval;
+  static fromISO(text: string, opts?: object): Interval;
+  start: DateTime | null;
+  end: DateTime | null;
+  isValid: boolean;
+  length(unit?: string): number;
+  count(unit?: string): number;
+  contains(dateTime: DateTime): boolean;
+  overlaps(other: Interval): boolean;
+  engulfs(other: Interval): boolean;
+  isBefore(dateTime: DateTime): boolean;
+  isAfter(dateTime: DateTime): boolean;
+  set(values: object): Interval;
+  splitAt(...dateTimes: DateTime[]): Interval[];
+  splitBy(duration: Duration | object | number): Interval[];
+  toDuration(unit?: string | string[], opts?: object): Duration;
+  toISO(opts?: object): string;
+  toFormat(format: string, opts?: object): string;
+}
+
+declare const $now: DateTime;
+declare const $today: DateTime;
+
+/** Debug logging — surfaces in the n8n execution view. */
+declare const console: {
+  log(...args: any[]): void;
+  error(...args: any[]): void;
+  warn(...args: any[]): void;
+  info(...args: any[]): void;
+  debug(...args: any[]): void;
+};