n8n-decanter 0.3.0

package/README.md

@@ -0,0 +1,318 @@
+# n8n-decanter
+
+[![CI](https://github.com/buttjer/n8n-decanter/actions/workflows/ci.yml/badge.svg)](https://github.com/buttjer/n8n-decanter/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/n8n-decanter)](https://www.npmjs.com/package/n8n-decanter)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Work on n8n like a codebase — built for AI coding agents.**
+
+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.
+
+- **Real version control** — meaningful diffs, PRs, blame; every push and
+  pull is auto-committed.
+- **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
+  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
+  it when done.
+- **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
+  from `shared/` and opted-in npm packages; push bundles them into
+  self-contained nodes that run anywhere, n8n Cloud included.
+- **Built for n8n 2.x** — the draft/publish model is a first-class citizen
+  (push tells you whether code went live or stayed a draft), and every
+  behavior that touches the API is verified against a real n8n 2.x instance
+  by an automated integration suite.
+
+![VS Code Screenshot](./docs/screenshot.webp)
+
+## Setup
+
+Requires Node >= 22.18 — the CLI is TypeScript (`.mts`), executed natively
+via Node's type stripping; there is no build step. **On older Node the CLI
+fails at startup with a confusing `SyntaxError`** rather than a clean version
+message: npm's `engines` field only *warns* at install time (unless you set
+`engine-strict`). If you see a syntax error pointing into a `.mts` file,
+check `node --version` first.
+
+```sh
+npm install -g n8n-decanter
+n8n-decanter init [dir]   # prompts for host + API key, writes .env,
+                          # copies template/, scaffolds config + .gitignore
+```
+
+From a git checkout instead: `npm link` (run `npm run build` once first — the
+installed bin is the compiled `dist/`), or invoke `node n8n-decanter.mts …`
+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
+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`:
+
+```json
+{ "root": "./workflows", "workflows": ["0cXNQKKzmO0pXiCq"] }
+```
+
+**Prefer a scoped API key.** In n8n (Settings → n8n API → Create) create a key
+limited to the permissions the CLI actually uses rather than a full-access one,
+so a leaked `.env` has a small blast radius:
+
+- `workflow:read`, `workflow:list`, `workflow:update` — `pull` / `status` / `push`
+- `execution:read`, `execution:list` — the `executions` verb
+
+A full-access key also works if your n8n version predates scoped keys.
+
+After every successful push **and pull**, the workflow's folder is
+git-committed automatically (scoped to that folder; outside a git repo it
+just warns). Set `"commitOnPush": false` / `"commitOnPull": false` to turn
+that off.
+
+`init` also scaffolds the TypeScript tooling a sync dir needs to type-check and
+run nodes locally — `package.json` (with a `typecheck` script + the `typescript`
+devDep), `tsconfig.json`, and `n8n-globals.d.ts` — plus a Claude Code
+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
+offline (no credentials, no network).
+
+## Commands
+
+```sh
+n8n-decanter                        # interactive picker (terminal, inited
+                                    #   project): filter workflows by typing —
+                                    #   pulled green, unpulled remote yellow —
+                                    #   then run verbs (unpulled: Enter pulls);
+                                    #   stays in the workflow's menu between
+                                    #   verbs, Esc backs out, Esc Esc quits
+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
+                                    #   (+ browser live-reload, opt-in)
+n8n-decanter [ref...] executions [--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
+```
+
+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
+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.
+
+Output is styled (color, `✓`/`!`/`✗` glyphs, progress) **only when writing to
+a terminal** and respects `NO_COLOR`/`FORCE_COLOR`; piped or redirected output
+is plain line-oriented text, safe for scripts and LLM harnesses. The
+interactive picker follows the same rule: it exists only on a terminal —
+a piped bare `n8n-decanter` prints plain usage text. For shell tab
+completion of verbs, flags, and workflow names, append
+`eval "$(n8n-decanter completion zsh)"` (or `bash`) to your shell rc.
+
+`status` exits 1 when a pull is needed or a push would clobber remote work
+(CONFLICT, remote-only changes, not pulled yet); local-only pending edits
+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
+context including `$getWorkflowStaticData`, seeded from `workflow.json` and
+overridable per fixture. Like n8n's own scoped `$env`, `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.
+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.
+
+## How it compares
+
+n8n-decanter is **Code-node-first**: it optimizes the loop of writing, typing,
+testing, and shipping the JavaScript/TypeScript *inside* your workflows. Here's
+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.
+
+| 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 |
+| **Shared code in Code nodes** | ❌ self-host `NODE_FUNCTION_ALLOW_*` only; no libraries | ❌ not part of its model | ✅ `shared/*.ts` + npm bundled into self-contained nodes (Cloud-safe) |
+| **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 |
+| **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`) |
+| **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) |
+
+Legend: ✅ first-class · 🟡 partial or indirect · ❌ not supported.
+
+**Bottom line:** reach for n8n-decanter when your workflows live or die by their
+Code nodes — TypeScript, shared libraries, offline tests, and real git diffs.
+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
+
+- **Pushing to a *published* workflow republishes it immediately.** n8n 2.x
+  splits each workflow into a draft and a published version — in the editor,
+  *Save* updates the draft and *Publish* makes it live. The public API has no
+  such split: `PUT /workflows/:id` hardcodes `publishIfActive: true`, so a push
+  to an already-published workflow **goes live at once — there is no draft-only
+  update through the API** (pushing to an *unpublished* workflow only updates
+  its draft). This is an n8n API limitation, not decanter's; decanter surfaces
+  the outcome — push prints `published: code is live now` vs `unpublished:
+  draft only`, and `status`/`watch` show the state. For a staged rollout,
+  unpublish → push → publish (triggers are down in between), or push to a
+  staging-copy workflow.
+- **n8n's optimistic locking isn't reachable through the API.** That same `PUT`
+  also forces `forceSave: true` and exposes no version checksum, so the server
+  won't reject a stale write. Decanter's **drift guard** is the only thing
+  protecting remote edits from being clobbered — so always `pull` (or check
+  `status`) before pushing. `--force` deliberately bypasses only this guard,
+  never the compliance guard.
+
+## How node files work
+
+Node sources live in a `code/` subdir inside the workflow folder, named in
+kebab-case after their node (`Parse Order` → `code/parse-order.js`).
+Layouts from older versions (files at the folder root) migrate automatically
+on the next `pull`.
+
+- `code/<node>.js` — lossless: pulled/pushed byte-identical. Type-checked via
+  JSDoc + `checkJs`. **No `import`s** — yes, `import` is standard JavaScript,
+  but a `.js` node is pushed verbatim into n8n, where Code nodes cannot load
+  modules; `check` rejects it. Imports are a `.ts`-only feature (bundled on
+  push, next bullets).
+- `code/<node>.ts` — one-way: local file is the source of truth. `push`
+  compiles it (esbuild, comments stripped) and appends a
+  `// @ts-n8n sha256:...` marker line; `pull` never touches the `.ts`.
+  To convert a node, replace `code/<node>.js` with `code/<node>.ts` and change
+  its `//@file:` placeholder in `workflow.json` to the `.ts` name.
+- `shared/*.ts` — helpers and types **imported by `.ts` nodes** (values and
+  types); push bundles the imports into the compiled node, so the pushed
+  code is self-contained and runs anywhere — n8n Cloud included, no
+  `NODE_FUNCTION_ALLOW_*` setup. Small npm packages bundle the same way:
+  install them in the sync dir and list them under `"bundleDependencies"`
+  in `decanter.config.json` (pure JS only; builtins and unlisted packages
+  are compile errors, imports must sit at the top of the file). `.js` nodes
+  stay import-free — that tier is byte-lossless by contract.
+- `code/<node>.remote.js` — written by `pull` when the remote code changed in
+  ways it can't merge (UI edit of a TS-managed node, conflict, missing local
+  `.ts`). Port the changes manually, then push; the file is removed on the
+  next in-sync pull.
+- `.decanter.json` — per-folder state (node-id → file map, sync hashes).
+  Commit it; don't edit it.
+
+Push refuses to overwrite remote changes made since the last sync
+(`pull first`, or `--force`). Pulling records the remote state as the new
+sync base — after a warned pull, push *will* overwrite the surfaced remote
+edits, with `.remote.js` + git as the safety net.
+
+Push also runs a **compliance guard** first (standalone: `check`, which needs
+no credentials): inline code without a `//@file:` placeholder, placeholders
+pointing at missing/`.remote.js`/non-`.js`/`.ts` files or at files outside
+`code/`, an `@ts-n8n` marker inside a `.js` file, dangling connection
+sources/targets, duplicate node names or ids, orphan `.js`/`.ts` files
+nothing references, and dangling literal `$('…')` references (in node source
+and in expression parameters) all abort the push — `--force` does not bypass
+these, only the drift guard. Unresolved `.remote.js` leftovers warn without
+blocking. The typecheck runs as a blocking push gate too (`--no-typecheck` to
+skip; auto-skipped when no `tsconfig.json` is found).
+
+**Renaming a node** by hand means touching four places at once (name,
+connections, `$('…')` references, filename) — use
+`rename <id> "<old>" "<new>"` instead: it rewrites all of them atomically,
+refuses colliding names, and re-validates the folder afterwards. It works
+offline; `push` propagates the rename to n8n.
+
+## Browser live-reload (watch)
+
+Tired of ⌘R'ing the n8n editor after every push? Add `"browserReload":
+"proxy"` to `decanter.config.json` and `watch` boots a transparent dev proxy
+on `127.0.0.1:5679` (override with `"proxyPort"`):
+
+```json
+{ "root": "./workflows", "workflows": ["…"], "browserReload": "proxy" }
+```
+
+Open the n8n editor through the **proxy URL** (`http://localhost:5679`) instead
+of the real port. The proxy pipes everything to your n8n host untouched — login,
+assets, and n8n's native `/rest/push` WebSocket — and injects a tiny reload
+client into the editor page. Every successful `watch` push then refreshes the
+tab for you, **unless the editor has unsaved changes** (it declines the reload
+and logs a console warning so nothing in-browser is clobbered). If the port is
+taken, `watch` warns and keeps syncing without live reload.
+
+Built on native Node (no extra deps). It's designed for a **local http** n8n
+(`http://localhost:5678`); pointing it at an https/remote host is best-effort —
+Secure cookies don't survive the plain-http hop, so auth may not carry through.
+
+## Type checking
+
+n8n Code node source is a function body (top-level `return`/`await`), which
+plain `tsc` rejects in `.ts` files (TS1108). `npm run typecheck` therefore
+runs [scripts/typecheck.mts](scripts/typecheck.mts), which wraps node files in
+an `async function` in memory (a `.decanter.json` next to the file — or in the
+parent of its `code/` dir — marks it as a node file) and maps diagnostics back
+to real line numbers. The IDE's own tsserver doesn't apply the wrapper, so on
+its own it would flag top-level `return`/`await` (TS1108/TS1375/TS1378) —
+which is why `init` also scaffolds `decanter-ts-plugin/`, a language-service
+plugin that suppresses exactly those codes on node files while every other
+diagnostic stays live. It loads after `npm install` in the sync dir, via the
+workspace TypeScript (VS Code prompts *Use Workspace Version* once; JetBrains
+IDEs use the project TypeScript by default).
+
+The CLI's own `.mts` sources are checked separately by `tsc -p
+tsconfig.cli.json` (strict; the first half of `npm run typecheck`). That
+config is not the root `tsconfig.json`, which belongs to the workflow node
+files above.
+
+*Not affiliated with or endorsed by n8n GmbH.*

package/dist/lib/api.mjs

@@ -0,0 +1,79 @@
+export class N8nApi {
+    #host;
+    #apiKey;
+    #timeoutMs;
+    constructor({ host, apiKey, requestTimeoutMs = 30_000 }) {
+        this.#host = host;
+        this.#apiKey = apiKey;
+        this.#timeoutMs = requestTimeoutMs;
+    }
+    async getWorkflow(id) {
+        return this.#request("GET", `/api/v1/workflows/${encodeURIComponent(id)}`);
+    }
+    /**
+     * All workflows, cursor-paginated. Name matching stays client-side — the
+     * server-side `name` filter is exact-match only, which defeats prefix
+     * resolution.
+     */
+    async listWorkflows() {
+        const all = [];
+        let cursor;
+        do {
+            const query = new URLSearchParams({ limit: "100", ...(cursor !== undefined && { cursor }) });
+            const page = (await this.#request("GET", `/api/v1/workflows?${query}`));
+            all.push(...page.data);
+            cursor = page.nextCursor ?? undefined;
+        } while (cursor !== undefined);
+        return all;
+    }
+    /**
+     * Recent executions with full run data, newest first. Read-only by design —
+     * the executions API is never written through. `limit` caps the single page
+     * (the API allows up to 250); no pagination on purpose, "recent" is the use
+     * case.
+     */
+    async listExecutions({ workflowId, status, limit = 5 }) {
+        const query = new URLSearchParams({
+            includeData: "true",
+            limit: String(limit),
+            ...(workflowId !== undefined && { workflowId }),
+            ...(status !== undefined && { status }),
+        });
+        const page = (await this.#request("GET", `/api/v1/executions?${query}`));
+        return page.data;
+    }
+    async getExecution(id) {
+        return this.#request("GET", `/api/v1/executions/${encodeURIComponent(id)}?includeData=true`);
+    }
+    async updateWorkflow(id, body) {
+        return this.#request("PUT", `/api/v1/workflows/${encodeURIComponent(id)}`, body);
+    }
+    async #request(method, pathname, body) {
+        try {
+            // The signal also covers body consumption, so a stalled response
+            // stream can't hang the CLI either.
+            const res = await fetch(this.#host + pathname, {
+                method,
+                headers: {
+                    "X-N8N-API-KEY": this.#apiKey,
+                    accept: "application/json",
+                    ...(body !== undefined && { "content-type": "application/json" }),
+                },
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: AbortSignal.timeout(this.#timeoutMs),
+            });
+            const text = await res.text();
+            if (!res.ok) {
+                throw new Error(`${method} ${pathname} failed: ${res.status} ${res.statusText}\n${text.slice(0, 2000)}`);
+            }
+            return text ? JSON.parse(text) : undefined;
+        }
+        catch (err) {
+            const name = err.name;
+            if (name === "TimeoutError" || name === "AbortError") {
+                throw new Error(`${method} ${pathname} timed out after ${this.#timeoutMs / 1000}s — n8n did not respond (raise "requestTimeoutMs" in decanter.config.json for a slow instance)`);
+            }
+            throw err;
+        }
+    }
+}

package/dist/lib/compile.mjs

@@ -0,0 +1,220 @@
+import { existsSync, readFileSync } from "node:fs";
+import { builtinModules } from "node:module";
+import path from "node:path";
+import { build, transform } from "esbuild";
+// Bundling (plans/14): a Code-node body may import from shared/ (and from
+// bundleDependencies-allowlisted npm packages); the imports are inlined into
+// the pushed artifact, which stays a legal *function body*. Mechanism —
+// esbuild rejects any top-level `import` next to a top-level `return`, so:
+// hoist the import block, wrap the body in an async arrow, bundle as an
+// iife, then re-enter with a top-level `return` footer.
+const GLOBAL_NAME = "__n8n_node";
+const SIZE_WARN_BYTES = 100_000;
+const BUILTINS = new Set(builtinModules);
+/**
+ * Split a node file into its leading top-level import block and the body.
+ * Dependency-free and line-precise: the imports-at-top rule means only the
+ * file head needs scanning — anything after the first non-import statement
+ * is body (a stray later import fails at bundle time with esbuild's own
+ * error). Dynamic `import(…)` and `import.meta` are not declarations and
+ * terminate the scan.
+ */
+export function scanNodeImports(source) {
+    const len = source.length;
+    let pos = 0;
+    let end = 0;
+    const specifiers = [];
+    scan: for (;;) {
+        while (pos < len) {
+            const ch = source[pos];
+            if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r")
+                pos++;
+            else if (ch === "/" && source[pos + 1] === "/") {
+                const nl = source.indexOf("\n", pos);
+                pos = nl === -1 ? len : nl + 1;
+            }
+            else if (ch === "/" && source[pos + 1] === "*") {
+                const close = source.indexOf("*/", pos + 2);
+                pos = close === -1 ? len : close + 2;
+            }
+            else
+                break;
+        }
+        if (!source.startsWith("import", pos))
+            break;
+        const boundary = source[pos + 6];
+        if (boundary !== undefined && /[A-Za-z0-9_$]/.test(boundary))
+            break; // an identifier like `importantThing`
+        let cursor = pos + 6;
+        while (cursor < len && /\s/.test(source[cursor]))
+            cursor++;
+        if (source[cursor] === "(" || source[cursor] === ".")
+            break; // dynamic import / import.meta
+        // the specifier is the first string literal in an import declaration
+        let quote = -1;
+        for (let i = cursor; i < len; i++) {
+            if (source[i] === '"' || source[i] === "'") {
+                quote = i;
+                break;
+            }
+            if (source[i] === ";")
+                break scan; // malformed — let the compiler complain
+        }
+        if (quote === -1)
+            break;
+        const closing = source.indexOf(source[quote], quote + 1);
+        if (closing === -1)
+            break;
+        specifiers.push(source.slice(quote + 1, closing));
+        let stmtEnd = closing + 1;
+        while (stmtEnd < len && (source[stmtEnd] === " " || source[stmtEnd] === "\t"))
+            stmtEnd++;
+        if (source[stmtEnd] === ";")
+            stmtEnd++;
+        pos = stmtEnd;
+        end = stmtEnd;
+    }
+    const importBlock = source.slice(0, end);
+    return {
+        importBlock,
+        specifiers,
+        body: source.slice(end),
+        importLines: importBlock.length === 0 ? 0 : importBlock.split("\n").length - (importBlock.endsWith("\n") ? 1 : 0),
+    };
+}
+/**
+ * Compile-time context: nearest decanter.config.json upward from `fromDir`.
+ * Reads only `bundleDependencies` — no credentials or env involved, so
+ * config-free verbs (`run` on a bare file) stay config-free.
+ */
+export function findBundleContext(fromDir) {
+    let dir = path.resolve(fromDir);
+    for (;;) {
+        const file = path.join(dir, "decanter.config.json");
+        if (existsSync(file)) {
+            let deps;
+            try {
+                deps = JSON.parse(readFileSync(file, "utf8")).bundleDependencies;
+            }
+            catch (err) {
+                throw new Error(`${file}: invalid JSON (${err.message})`);
+            }
+            return {
+                syncRoot: dir,
+                bundleDependencies: Array.isArray(deps) ? deps.filter((d) => typeof d === "string") : [],
+            };
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return { syncRoot: null, bundleDependencies: [] };
+        dir = parent;
+    }
+}
+/** Package name of a bare specifier (`@scope/pkg/sub` → `@scope/pkg`). */
+function packageName(spec) {
+    return spec.startsWith("@") ? spec.split("/").slice(0, 2).join("/") : spec.split("/")[0];
+}
+/**
+ * Offline import rules for a node file (plans/14): relative imports stay
+ * inside the sync dir, bare specifiers need a `bundleDependencies` opt-in,
+ * builtins can never be bundled. Shared by the compliance guard and the
+ * compiler, so `check` and `push` disagree on nothing.
+ */
+export function checkNodeImports(file, specifiers, ctx) {
+    const problems = [];
+    for (const spec of specifiers) {
+        if (spec.startsWith("node:") || BUILTINS.has(packageName(spec))) {
+            problems.push(`imports the Node builtin "${spec}" — builtins cannot be bundled into a Code node (whether n8n allows them at runtime is the instance's NODE_FUNCTION_ALLOW_BUILTIN policy); inline the logic instead`);
+        }
+        else if (spec.startsWith("./") || spec.startsWith("../")) {
+            if (ctx.syncRoot !== null) {
+                const resolved = path.resolve(path.dirname(file), spec);
+                if (resolved !== ctx.syncRoot && !resolved.startsWith(ctx.syncRoot + path.sep)) {
+                    problems.push(`imports "${spec}", which resolves outside the sync dir (${ctx.syncRoot}) — shared code must live inside it`);
+                }
+            }
+        }
+        else if (path.isAbsolute(spec)) {
+            problems.push(`imports the absolute path "${spec}" — use a relative import inside the sync dir`);
+        }
+        else if (!ctx.bundleDependencies.includes(packageName(spec))) {
+            problems.push(`imports the npm package "${packageName(spec)}" without opting it in — add it to "bundleDependencies" in decanter.config.json to bundle it into the pushed node`);
+        }
+    }
+    return problems;
+}
+/**
+ * One-way compile of a .ts node file to the JS that runs inside n8n.
+ * Without imports this is a plain esbuild transform — byte-identical to the
+ * pre-bundling compiler, so existing nodes never change shape or hash. With
+ * imports, the file is bundled self-contained (see the header comment); the
+ * output is still a function body ending in a top-level `return`.
+ */
+export async function compileTs(file, log) {
+    const source = readFileSync(file, "utf8");
+    const { importBlock, specifiers, body } = scanNodeImports(source);
+    if (specifiers.length === 0) {
+        const result = await transform(source, {
+            loader: "ts",
+            format: "cjs",
+            target: "node18",
+            sourcefile: file,
+        });
+        return result.code.endsWith("\n") ? result.code : result.code + "\n";
+    }
+    const ctx = findBundleContext(path.dirname(file));
+    const problems = checkNodeImports(file, specifiers, ctx);
+    if (problems.length > 0) {
+        throw new Error(`${file}:\n${problems.map((p) => `  ${p}`).join("\n")}`);
+    }
+    const workingDir = ctx.syncRoot ?? path.dirname(file);
+    // The entry must contain NO `export` syntax: n8n's task-runner sandbox
+    // neuters getter property descriptors (Object.defineProperty with `get`
+    // reads back undefined), and esbuild lowers module exports to exactly such
+    // getters. A plain assignment onto a free identifier sidesteps the entire
+    // export machinery — esbuild inlines ESM imports directly into the iife
+    // scope, getter-free.
+    const entry = importBlock +
+        (importBlock.endsWith("\n") ? "" : "\n") +
+        `${GLOBAL_NAME}.default = async () => {\n` +
+        body +
+        "\n};\n";
+    let bundled;
+    try {
+        const result = await build({
+            stdin: {
+                contents: entry,
+                loader: "ts",
+                resolveDir: path.dirname(file),
+                sourcefile: path.basename(file),
+            },
+            bundle: true,
+            format: "iife",
+            platform: "node",
+            target: "node18",
+            write: false,
+            // sync-root-relative module comments -> machine-independent hashes
+            absWorkingDir: workingDir,
+            logLevel: "silent",
+        });
+        bundled = result.outputFiles[0].text;
+    }
+    catch (err) {
+        const e = err;
+        const messages = e.errors?.map((m) => (m.location?.file ? `${m.location.file}:${m.location.line}: ${m.text}` : m.text)) ?? [err.message];
+        throw new Error(`${file}: bundling failed\n${messages.map((m) => `  ${m}`).join("\n")}`);
+    }
+    // Same sandbox constraint, second front: esbuild's CJS-interop helper
+    // (__copyProps, used by __toESM for npm packages) copies properties as
+    // getters. Rewrite it to eager data assignment — snapshot-at-require is
+    // normal CommonJS behavior, and our bundles have no live-binding needs.
+    bundled = bundled.replace(/__defProp\(to, key, \{ get: \(\) => from\[key\], enumerable: [^}]+\}\);/, "to[key] = from[key];");
+    if (/\b__export\(/.test(bundled)) {
+        log?.warn(`${file}: the bundle contains lazily-wrapped modules (import cycle or top-level await in shared code?) — these rely on getter exports, which n8n's Code-node sandbox does not support; restructure the shared imports`);
+    }
+    const code = `var ${GLOBAL_NAME} = {};\n${bundled}return ${GLOBAL_NAME}.default();\n`;
+    if (code.length > SIZE_WARN_BYTES && log) {
+        log.warn(`${file}: compiled node is ${Math.round(code.length / 1024)} KB after bundling — large nodes bloat the workflow JSON; consider trimming imports`);
+    }
+    return code;
+}