n8n-decanter 0.10.0 → 0.10.2

package/CHANGELOG.md

@@ -7,6 +7,356 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.2] - 2026-08-18
+
+### Changed
+
+- **"Missing `n8n-instance` tools? Restart" is no longer the only answer we
+  give — in a nested sync dir it was a dead end.** Agent wiring loads at
+  startup *from the dir the agent was started in*, so tools declared in
+  `.mcp.json` can be absent for two reasons: the wiring is new (a restart fixes
+  it), or the wiring sits **below** the launch dir, where no restart will ever
+  load it. Every surface that taught only the first now teaches both, with the
+  discriminator you can apply yourself — *is that `.mcp.json` below the
+  directory you started the agent in?* — and the two working routes (start the
+  agent in the sync dir, or wire the root with `N8N_DECANTER_DIR` plus a
+  root-resolvable command): the scaffolded `AGENTS.md`, `init`'s own output
+  (which now prints the nested guidance **instead of** the restart line when it
+  scaffolds into a nested dir), [Working with coding
+  agents](/docs/agents/overview/), [init](/docs/cli/init/) and a new
+  [troubleshooting](/docs/faq/troubleshooting/) entry. The CLI never needed
+  that wiring, so `pull`/`push`/`preflight` keep working either way — the docs
+  now say so too.
+
+- **The oversized-scenario warning now names a remedy you can actually take.**
+  Above 1 MB `scenario create` said "Trim it before that" — but there is no
+  trim flag, so the advice pointed nowhere. It now says what is true and what
+  to do: nothing is committed yet (`scenario create` never commits — only the
+  next `pull`/`push` sweeps the folder into history), so you can still cut
+  items out of `data.resultData.runData` by hand, or re-create the scenario
+  with `--scaffold` instead of `--execution` and author the pins yourself.
+  `docs/cli/scenario.md` spells out both, including which parts of a capture
+  are unsafe to delete.
+
+- **The agent contract now says to orient *before* the first edit, not only
+  before the push.** `preflight` was always the read-only report of the
+  instance's side (`drift`, `CONFLICT`, a pending `parity`), but every surface
+  framed it as the pre-push gate — so an agent edited first and learned about a
+  colleague's UI edit afterwards. The scaffolded `AGENTS.md` and both agent doc
+  pages now open the loop with it: on drift, `pull` and carry on; on a
+  `CONFLICT`, show `diff` and ask before either side is overwritten.
+- **The scaffold stopped advertising a deny rule it no longer has.** The
+  Claude Code `settings.json` denies `.decanter.json`, `.env` and
+  `push --force` — but the scaffolded `CLAUDE.md` and `opencode.json` still
+  claimed `*.remote.js` was blocked too. Those conflict artifacts were removed
+  in the MCP pivot; both files now describe the policy that actually ships.
+- **Docs: `mcp connect` / `mcp serve` no longer read as if the guard obtained
+  credentials itself.** "decanter's own credentials", "the agent never holds an
+  n8n credential" and "no secret to manage" led readers (and agents) to believe
+  the guard handles the n8n login. It does not: it only *reads* what `init`
+  wrote to `.env` / `.decanter-auth.json`, and can at most refresh an OAuth
+  token. The mcp-connect / mcp-serve pages and the template `AGENTS.md` now say
+  so outright — obtaining credentials is exclusively `init`'s job, and a
+  "no MCP credentials" answer means run `init`, not retry.
+
+- **"decanter.config.json not found" now points at `init` — with its flags.**
+  The classic half-setup is a hand-written `.env`: an agent that cannot run the
+  browser OAuth flow asks its human to paste `N8N_MCP_TOKEN` into a file and
+  stops there, leaving no config, template, `.gitignore` or agent wiring behind.
+  The error now says the dir is not a sync dir yet, that `.env` alone is not
+  enough, and prints the prompt-free command that fixes it
+  (`n8n-decanter init . --host <host-url> --token <mcp-token>`). The docs
+  (init, configuration, troubleshooting, README) say the same thing: headless is
+  not a reason to skip `init` — it takes the same token as a flag.
+
+- **`init`'s restart reminder now covers everything it wires, not just
+  permission rules.** MCP servers (`.mcp.json` / `opencode.json` — including the
+  guarded `n8n-instance` server), permission rules and hooks are all read at
+  agent **startup**, and `init` normally runs inside the session it configures.
+  The reminder now fires when any of those files is newly scaffolded and says
+  what it means: this session is still unconfigured, restart the agent (or
+  `/reload`). README, init and the agents docs say the same, and the scaffolded
+  `AGENTS.md` tells the agent to **ask for a restart** when the `n8n-instance`
+  tools are missing instead of connecting to the instance directly.
+
+### Fixed
+
+- **The scaffolded hooks now work when your sync dir is not where the agent was
+  started.** All three found the sync dir by assuming it was the current
+  directory, which only holds for an agent launched inside it. With the sync dir
+  nested in a bigger repo — a layout the docs explicitly allow — the agent runs
+  at the repo root and every one of them misbehaved: the rename-reference guard
+  became a **silent no-op**, so `$('Old Name')` references left behind by a
+  `renameNode` went unreported until a later `push` refused them; the verify hook
+  spawned the CLI without a directory, so it **blocked every node-file edit** with
+  a "not a sync dir" error; and the MCP routing check scanned the wrong tree.
+  Each hook now locates the sync dir from its own installed path, so it behaves
+  the same wherever the agent starts.
+- **The routing check no longer misses direct-route servers in your user
+  config.** Its lookup for this project's entry in `~/.claude.json` matched the
+  current directory, but that file is keyed by the repository root — so in any
+  sync dir inside a git repo the check silently found nothing. It now matches the
+  project entry for the sync dir or any parent of it.
+- **The verify hook finds a locally installed CLI.** It only ever looked for
+  `n8n-decanter` on `PATH`, so with a local (non-global) install it stayed quiet
+  and no verification ran at all. It now prefers the sync dir's
+  `node_modules/.bin` and falls back to `PATH`.
+- **"decanter.config.json not found" no longer sends you to `init` when the sync
+  dir is simply somewhere else.** Run from *above* a perfectly good sync dir —
+  what happens whenever an agent starts at the repo root — the error read as if
+  nothing had ever been set up, and advised scaffolding a second sync dir on top
+  of the working one. It now looks below the directory it searched from, names
+  the sync dir it finds there, and prints the `--dir` / `N8N_DECANTER_DIR` form
+  that reaches it. When there really is no sync dir, the `init` advice is
+  unchanged.
+
+### Added
+
+- **The routing check also looks at parent directories, up to your repository
+  root.** Agents merge `.mcp.json` from every directory above the one they start
+  in, so a server pointing straight at your n8n instance can sit in the repo
+  root's config and still route this session. The scan stops at the repository
+  boundary, so it never reaches into unrelated parent directories, and an
+  offender found above the sync dir is named by its relative path
+  (`../.mcp.json`) so you can tell which file it means.
+
+- **`--dir <path>` (or `N8N_DECANTER_DIR`) points any verb at a sync dir that is
+  not the current directory.** The layout the docs allow but nothing supported:
+  the sync dir nested inside a bigger repo, with the agent started at the repo
+  root. The MCP entry `init` writes into the sync dir is invisible from up
+  there, and hoisting it to the repo root spawned the guard where no
+  `decanter.config.json` could be found — so the guard did not work at all. The
+  search still only walks *up*; this says where it starts. In an agent's server
+  entry the environment variable is the form to reach for
+  (`"env": { "N8N_DECANTER_DIR": "flows" }`), and relative values resolve
+  against the working directory, so a repo-relative one keeps working for
+  everyone who clones. `init` does not take `--dir` — it still takes the
+  directory to scaffold as an argument.
+
+- **`init` now tells you how to wire an agent when your sync dir is nested in a
+  bigger project.** Agents look for `.mcp.json`, `opencode.json` and
+  `.claude/settings.json` from the directory they were *started* in and never in
+  one below it, so everything `init` scaffolds is inert for an agent started at
+  the repo root above the sync dir. When init sees a project around it (a `.git` or
+  `package.json` in a parent) it prints both shapes that work: starting the
+  agent inside the sync dir — recommended, nothing further to configure — or the
+  paste-ready MCP, opencode and hooks/permissions blocks for the project root,
+  with every path and glob already prefixed. That prefixing is the point: copied
+  up verbatim, `Read(.env)` / `Edit(.env)` guard the *root's* `.env` and quietly
+  stop protecting your credentials. `init` prints this; it never writes into a
+  parent directory. Only on the run that first scaffolds the agent files, and
+  never for a standalone sync dir.
+
+## [0.10.1] - 2026-08-16
+
+### Added
+
+- **The live mirror now tells the agent when it overwrote your work.** It runs a
+  full `pull` after a structure edit, so it can replace an unpushed local code
+  edit with what is on the instance. It always warned about that — on stderr,
+  which is the one stream an MCP agent structurally cannot read, so the party
+  able to react never heard it. The warning now rides the **result of the
+  agent's next tool call**, naming the files and how to recover them from the
+  safety commit. Delivered once, never repeated.
+
+  Only on `mcp connect` (the transport `init` scaffolds). `mcp serve` pipes
+  upstream responses through untouched — including SSE — and buffering them to
+  inject an advisory line would break streaming for every response to deliver it
+  on some. On that transport the stderr warning stays the only signal.
+
+- **`init` now says that its permission rules only bind the next session.** It
+  writes `.claude/settings.json` with the deny rules that keep an agent off
+  `.decanter.json`, `.env` and `push --force` — but agents read permission config
+  at startup, not on change, and `init` is normally run *from inside* the session
+  those rules are meant to constrain. They were silently inert until a restart,
+  and the docs mentioned a restart only for the skills plugin — so the rules that
+  actually gate the agent went unmentioned. Printed once, when the file is first
+  written; a re-init in a set-up directory stays quiet.
+
+- **`node run` fixtures can pin a node's other outputs, so `$('Node').all(1)`
+  finally answers.** Give a node one items array **per output** and the branch
+  is readable offline:
+
+  ```json
+  "nodes": { "Decide": [[{ "json": { "side": "true" } }], [{ "json": { "side": "false" } }]] }
+  ```
+
+  `all(1)` / `first(1)` / `last(1)` and `$items('Decide', 1)` read output 1, and
+  an **empty** array is a real answer — that branch took no items. `input` takes
+  the same shape, indexed by the node's *input* (a Merge node's second input).
+  A plain items array still means a single output, so existing fixtures are
+  unchanged; asking for an output the fixture doesn't supply still refuses,
+  now saying how many it has. Until now every such call was refused outright,
+  because a fixture could only express one array per node.
+
+- **`preflight --simulate` now replays a pinned node's other outputs too.** The
+  stand-in decanter substitutes for a network node is a Code node, which has one
+  output — so an error output (or any second branch) captured in your execution
+  was replayed nowhere, and everything behind it sat with no input, emitted
+  nothing, and let the run pass. Each populated output now gets **its own
+  stand-in**, wired to the same input as the original and feeding exactly that
+  output's targets, so the branch really runs. Deliberately not wired to the
+  synthetic trigger: a stand-in fires only when the original would, so a replay
+  whose real nodes take a different path can't have the old branch's items
+  injected into it anyway. The `simulate` check names the splits in its details
+  (terminal and `--json`). **`test` still replays `main[0]` only** — n8n's
+  `pinData` is one flat items array per node, with no output dimension — and
+  `scenario check` now spells out which of the two you are looking at.
+
+- **`test` now reports what the run actually moved, not just that it
+  finished** — a coverage line over the nodes that executed (enabled and
+  unpinned; a pinned node's items are the input you supplied):
+  `coverage: 7/9 unpinned node(s) emitted items — 2 emitted none: Group
+  products, Write rows`. A node counts as emitting if it put an item on **any**
+  output. Some empty nodes are normal — a filter that dropped everything — so
+  the line warns and nothing more.
+
+  **But a run in which not one unpinned node emitted an item now fails
+  (exit 1), even with synthetic pins.** n8n calls such a run `success` and
+  it is: nothing errored. No data moved either, so nothing was demonstrated,
+  and reporting it as a pass was the check lying. The message names the usual
+  cause — a pin replays a node's first output only.
+
+- **`scenario check` warns about what the replay will throw away.** Both replay
+  paths (`test`'s `pinData`, `preflight --simulate`'s stand-in node) read
+  `main[0]` only, while the validator happily accepts — and `✓ valid`s — a
+  scenario carrying items on several outputs. The check now says so offline:
+  once for a node whose data populates more than one output, naming the indices
+  that get dropped, and once for a node source that reads a pinned node's
+  non-first output (`$('Enrich').all(1)`, `$items('Enrich', 1)`) — the call that
+  returns nothing and leaves the node emitting nothing. Warnings only; the
+  scenario stays valid for the outputs that do replay.
+
+### Changed
+
+- **An explicit `.ts` extension in a node file's import no longer fails the
+  typecheck.** The scaffolded `tsconfig.json` now sets
+  `allowImportingTsExtensions`, so `import { total } from
+  "../../../shared/money.ts"` type-checks — until now it was rejected
+  (TS5097) even though `push` bundles it without complaint, which made the
+  gate and the bundler disagree over a pure spelling choice. Extensionless
+  stays the recommended form (it survives a helper later becoming `.js`);
+  both spellings resolve everywhere. Existing sync dirs are offered the
+  updated `tsconfig.json` on the next `init` — a `tsconfig.json` you edited
+  yourself is reported as drift and left alone, so add the option by hand
+  there.
+- **Two of the four import rules for `.ts` nodes now warn instead of
+  blocking a push**: a relative import resolving outside the sync dir, and an
+  absolute-path import. Both only endanger the author's own portability — the
+  bundle still builds locally and fails loudly (`Could not resolve`) wherever
+  the target is genuinely absent — so blocking them was decanter making the
+  user's call. The advisory prints on every surface (`preflight`'s `layout`
+  details, `push`, `node run`) and exactly once per push;
+  `preflight --fail-on=warn` is the strict variant for CI. **Node builtins
+  and npm packages not opted into `bundleDependencies` still block** —
+  esbuild is silent about both, so without the block the failure would
+  surface at runtime on the n8n instance.
+- **The scaffolded `mcp-route-check.mjs` session hook now also inspects
+  user-level agent config for direct n8n MCP routes** — Claude Code's
+  `~/.claude.json` (including its entry for the current project), Cursor's
+  `~/.cursor/mcp.json`, the VS Code user profile, and opencode's global
+  config. Previously it read only project files, so an `n8n` server added
+  with `claude mcp add -s user` (or any other user-scoped config) bypassed
+  the decanter guard without a word — exactly the "second door" the hook
+  exists to catch. Still a warning, never a gate. Re-run `init` in an
+  existing sync dir (or re-copy the hook from the template) to pick it up.
+- **The scaffolded `tsconfig.json` now covers the whole sync dir**, not just
+  `shared/` and `workflows/` — helper code may live in any folder inside the
+  sync dir (`shared/` is only the scaffolded default), so the typecheck and
+  the editor's tsserver now own every root without a config edit. Existing
+  sync dirs keep their scaffolded file; to match, widen `include` to
+  `["n8n-globals.d.ts", "**/*.ts", "**/*.js"]` and add
+  `"**/backups/**", "**/executions/**", "decanter-ts-plugin", "dist"` to
+  `exclude`. Two consequences worth knowing: a loose node-shaped scratch file
+  (top-level `return` outside any workflow's `code/`) is now part of the
+  program and reports TS1108 — move it into a workflow or add its folder to
+  `exclude`; and when `init` scaffolds into an **existing project** that had
+  no `tsconfig.json`, the new config sweeps that project's own `.ts`/`.js`
+  into the node-file typecheck — add your app dirs to `exclude` if they
+  shouldn't gate pushes.
+
+### Fixed
+
+- **`diff` and `preflight` no longer report a `CONFLICT` for a node with no
+  recorded sync hash.** "Changed both locally and remotely" is measured against
+  the last-sync baseline in `.decanter.json`; with no baseline nothing is
+  *known* to have moved on the instance, and `push` has always treated that as
+  pushable. The two disagreed, so the report described a dead end the CLI did
+  not have — worse, its documented exit (`push --force`) is denied to agents by
+  the permission rules `init` scaffolds. Such a node now reads as
+  `push pending`, which is what `push` does with it. `pull` no longer warns
+  `CONFLICT` for the same case on `.ts` nodes.
+- **A `.js` → `.ts` conversion no longer reads as data loss.** Re-pointing a
+  node's `//@file:` placeholder is the sanctioned way to convert, and `push`
+  and `pull` both adopt it before doing anything — but `diff` and `preflight`
+  looked the file up in `.decanter.json` alone and announced `local file
+  code/<node>.js missing` for the file you had just replaced. They now read the
+  placeholder too, so a converted node reports `local changes in
+  code/<node>.ts — push pending`, identically for every converted node.
+- **`preflight` no longer prints `✓ parity local code matches the draft`
+  directly above `✗ drift CONFLICT`.** Both checks read the same facts, so
+  `parity` may claim a match only when every node is in sync; divergence that
+  `drift` owns is reported as an `info` line pointing at it.
+- **`mcp connect` survives an unreachable n8n instead of dying at the
+  handshake.** `initialize` was forwarded like any other message, so a
+  connection failure answered the *handshake* with an error: the agent's MCP
+  client got no `serverInfo` and tore the session down before a single tool
+  call could report what was wrong. The guard now completes the handshake
+  itself when n8n does not answer, and the failure surfaces on the tool call
+  that needed the instance. Once n8n is reachable, the handshake is replayed
+  upstream so the session it uses is a real one. The startup line now reads
+  `guard: ready — forwarding all n8n MCP tools to <host>` instead of
+  `connected to <host>`, which claimed a connection nothing had made yet.
+- **The scaffolded `AGENTS.md` now names the n8n-side prerequisites.** MCP
+  access is a switch per *instance* **and** one per *workflow* ("Available in
+  MCP"), and until a workflow's is on, `pull`/`push`/`diff`/`preflight`/`watch`
+  all fail for it. The CLI's error says so; the file an agent reads *before*
+  running anything did not.
+- **`preflight`'s `types` check now reports type errors in shared helper
+  files** instead of passing green while `push` fails on them. The scoped
+  typecheck dropped every diagnostic outside the graded workflow's own dir —
+  and helper code lives outside every workflow dir by definition — so a
+  workflow could grade `ready` on code `push` then rejected. Helper
+  diagnostics (under `shared/` or any other folder) now surface in every
+  workflow's `types` line, while another workflow's *node* errors stay out of
+  scope as before.
+- **The documented shared-import path was one level short** for the `code/`
+  layout: `../../shared/money` in the TypeScript-nodes docs and the scaffolded
+  `AGENTS.md` resolved to `workflows/shared/money` and failed on copy-paste.
+  The correct depth from `workflows/<folder>/code/` is `../../../shared/money`.
+- **Compiled module labels — and therefore sync hashes — are now stable when
+  the sync dir is reached through a symlinked path** (macOS `/tmp`, a
+  symlinked checkout). esbuild resolves bundled files to their realpaths, so
+  an un-realpathed label base produced machine-specific `../…`-climbing
+  labels inside the hashed bytes — nodes reading "push pending" across
+  machines with nobody touching code. The same spelling mismatch made a
+  *scoped* typecheck silently drop every node diagnostic under a symlinked
+  path; both now realpath. If a sync dir lives behind a symlink, the first
+  push after this release re-baselines the affected nodes' hashes once.
+- **The route-check hook now reads opencode's real config shape**
+  (`mcp.<name>`). It previously looked only for `mcpServers` / `mcp.servers` /
+  `servers` bags, so an `opencode.json` routing straight at the instance was
+  listed as checked but never actually flagged.
+- **A `watch` save now runs the same folder-wide compliance guard as `push`.** It
+  used to check only the saved file, which cannot see the workflow's node names —
+  so it could not catch a dangling `$('Renamed Node')` and pushed straight to the
+  draft what a manual `push` refuses outright. The break then surfaced at run time
+  in n8n instead of at save time. Four surfaces already claimed the guards were
+  the same; now they are.
+
+  **The abort is scoped, deliberately:** a save is refused when the violation is
+  in the file you just saved, and violations elsewhere in the folder are printed
+  on every save without blocking it. Repairing a rename means fixing several
+  files, and a folder-wide abort would stop every save until the last fix — which
+  would disable `watch` during exactly the job it is for.
+
+- **`liveMirror` is documented as what it is: a full `pull`.** The shipped agent
+  contract and the config reference both described it as refreshing the
+  `workflow.json` snapshot. It also rewrites the `code/` files and
+  `.decanter.json` and moves files on a rename, so it can overwrite an unpushed
+  local edit — which is worth knowing before you restructure. No behaviour change;
+  the docs now say what the code has always done.
+
 ## [0.10.0] - 2026-08-07
 
 ### Added

package/README.md

@@ -34,8 +34,9 @@ clean git diffs.
   every push and pull is auto-committed.
 - **TypeScript or typed JS** — write nodes in TS (compiled on push) or plain
   JS; n8n globals (`$input`, `$('…')`, …) are typed in both.
-- **Shared code and small libraries** — `.ts` nodes import from `shared/` and
-  opted-in npm packages, bundled on push to run anywhere, n8n Cloud included.
+- **Shared code and small libraries** — `.ts` nodes import helper files from
+  anywhere in the sync dir (`shared/` by default) and opted-in npm packages,
+  bundled on push to run anywhere, n8n Cloud included.
 - **Agent-native** — `init` scaffolds Claude Code / Cursor / Codex configs;
   `preflight --offline` and `node run` give agents a credential-free loop.
 - **Guarded agent access to n8n's MCP, wired by default** — the scaffolded
@@ -72,6 +73,13 @@ n8n-decanter init [dir]   # OAuth in your browser (or a pasted MCP token)
 n8n-decanter pull         # pick a workflow from the list → it pulls
 ```
 
+**Restart your coding agent after `init`** — the MCP servers, permission rules
+and hooks it scaffolds are read at agent startup, so the session that ran `init`
+is still unconfigured. If the sync dir is nested in a bigger repo and you start
+the agent at the repo root, a restart is *not* enough — that wiring loads only
+from the dir the agent starts in
+([which file loads from where](docs/agents/overview.md#where-the-agent-wiring-loads-from)).
+
 On a terminal, `pull` with no argument lists your n8n workflows — pick one and
 it lands in `workflows/<slug>/`. Know the id already? `n8n-decanter pull
 <id-or-name>` pulls it directly (scriptable, no TTY needed).
@@ -79,7 +87,9 @@ it lands in `workflows/<slug>/`. Know the id already? `n8n-decanter pull
 set a bare `pull`/`push`/`diff` acts on.)
 
 **Credentials:** OAuth by default (via `init`); `N8N_MCP_TOKEN` for
-headless/CI; `N8N_API_KEY` is optional, needed only for `executions`,
+headless/CI — pass it to `init --host <url> --token <mcp-token>` rather than
+hand-writing `.env`, which leaves the config, template, `.gitignore` and agent
+configs unscaffolded; `N8N_API_KEY` is optional, needed only for `executions`,
 `data-tables`, and `backup`. Details: [Installation](docs/getting-started/installation.md),
 [init](docs/cli/init.md), [Configuration](docs/concepts/configuration.md).
 
@@ -131,6 +141,17 @@ renaming, and archiving workflows — and adding or renaming nodes — are
 **n8n's acts**: do them in the editor or let your agent do it over n8n's MCP
 tools (through the guard above); the next `pull` reconciles the local mirror.
 
+**Sync dir nested in a bigger repo?** A global `--dir <path>` (or
+`N8N_DECANTER_DIR`) starts the upward `decanter.config.json` search there
+instead of in the working directory — every verb honours it except `init`,
+which takes the directory to scaffold as its argument. A coding agent launched
+at the repo root needs it too — agents look for `.mcp.json` and
+`.claude/settings.json` from where they were *started*, never in a directory
+below it, so either start the agent in the sync dir or wire the root
+explicitly:
+[Working with coding agents](docs/agents/overview.md#where-the-agent-wiring-loads-from),
+[mcp connect](docs/cli/mcp-connect.md#when-your-sync-dir-is-not-your-project-root).
+
 ## How it compares
 
 n8n-decanter is **Code-node-first**: it optimizes writing, typing, verifying and
@@ -142,7 +163,7 @@ a broader whole-workflow authoring toolkit:
 | Capability | Native n8n (browser) | n8n-as-code | n8n-decanter |
 |---|---|---|---|
 | **TypeScript for Code nodes** | ❌ JavaScript or Python only | ❌ TS at workflow level, not node logic | ✅ `.ts` nodes, compiled on push, typed n8n globals |
-| **Shared types & helpers in Code nodes** | ❌ self-host `NODE_FUNCTION_ALLOW_*` only | ❌ not part of its model | ✅ `shared/*.ts` + npm bundled into self-contained nodes (Cloud-safe) |
+| **Shared types & helpers in Code nodes** | ❌ self-host `NODE_FUNCTION_ALLOW_*` only | ❌ not part of its model | ✅ helper `.ts` anywhere in the sync dir + 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 file |
 | **Code-level git versioning** | 🟡 in-app history; Git source control is Enterprise-only | ✅ GitOps sync of workflow source | ✅ real git — diffs, PRs, blame per Code node; auto-commit each sync |
 | **Preflights** (`preflight`, then `test`) | 🟡 re-run past executions, but online in-editor | 🟡 inspect executions against a live env | ✅ one read-only, CI-gateable verdict *before* the push; then `test` runs the pushed draft — each diffs every node vs a real capture |

package/dist/lib/backup.mjs

@@ -135,7 +135,7 @@ async function assembleForRestore(dir, backup, log) {
         if (file === null)
             continue; // inline code (untracked node) — leave as-is
         try {
-            const { jsCode } = await buildNodeCode(dir, file, log);
+            const { jsCode } = await buildNodeCode(dir, file, log, { quietImportWarnings: true });
             node.parameters.jsCode = jsCode;
         }
         catch {

package/dist/lib/compile.mjs

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { builtinModules } from "node:module";
 import path from "node:path";
 import { build, transform } from "esbuild";
@@ -119,38 +119,53 @@ export function findBundleContext(fromDir) {
         dir = parent;
     }
 }
+/** realpath when resolvable, the input untouched otherwise (missing dirs). */
+function realDir(dir) {
+    try {
+        return realpathSync(dir);
+    }
+    catch {
+        return dir;
+    }
+}
 /** 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 preflight's `layout` check and `push` disagree on nothing.
+ * Offline import rules for a node file (plans/14), split by who the rule
+ * protects (Plan 79 task 7): a Node builtin or an un-opted-in npm package is
+ * **blocking** — esbuild is silent about both, so without the block the
+ * failure (a `__require` shim, a silently inlined package) surfaces at
+ * runtime on the instance. A relative import leaving the sync dir, or an
+ * absolute path, is **advisory** — it only endangers the author's own
+ * portability, and esbuild fails loudly wherever the target is genuinely
+ * absent. Shared by the compliance guard and the compiler, so preflight's
+ * `layout` check and `push` disagree on nothing.
  */
 export function checkNodeImports(file, specifiers, ctx) {
-    const problems = [];
+    const blocking = [];
+    const advisory = [];
     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`);
+            blocking.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`);
+                    advisory.push(`imports "${spec}", which resolves outside the sync dir (${ctx.syncRoot}) — it bundles, but anyone whose checkout lacks the target can't build this node`);
                 }
             }
         }
         else if (path.isAbsolute(spec)) {
-            problems.push(`imports the absolute path "${spec}" — use a relative import inside the sync dir`);
+            advisory.push(`imports the absolute path "${spec}" — it bundles on this machine only; prefer 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`);
+            blocking.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;
+    return { blocking, advisory };
 }
 /**
  * One-way compile of a .ts node file to the JS that runs inside n8n.
@@ -159,7 +174,7 @@ export function checkNodeImports(file, specifiers, ctx) {
  * 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) {
+export async function compileTs(file, log, opts) {
     const source = readFileSync(file, "utf8");
     const { importBlock, specifiers, body } = scanNodeImports(source);
     if (specifiers.length === 0) {
@@ -172,11 +187,35 @@ export async function compileTs(file, log) {
         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 { blocking, advisory } = checkNodeImports(file, specifiers, ctx);
+    if (blocking.length > 0) {
+        throw new Error(`${file}:\n${blocking.map((p) => `  ${p}`).join("\n")}`);
+    }
+    // Advisory findings warn and let the compile proceed (Plan 79 task 7). The
+    // push paths pass quietImportWarnings because their guard tier already
+    // printed the same findings — without it every violation would print twice
+    // per push, once per channel.
+    if (!opts?.quietImportWarnings) {
+        for (const p of advisory)
+            log?.warn(`${file}: ${p}`);
     }
-    const workingDir = ctx.syncRoot ?? path.dirname(file);
+    // Realpath the label base: esbuild resolves every bundled module to its
+    // realpath, so a symlink anywhere in the sync dir's own path (macOS /tmp,
+    // a symlinked checkout) would otherwise make `path.relative` climb across
+    // the symlink — machine-specific `../…` module labels inside the hashed
+    // bytes, i.e. the exact cross-machine drift the sync-root-relative labels
+    // exist to prevent (Plan 79 task 4).
+    const workingDir = realDir(ctx.syncRoot ?? path.dirname(file));
+    // resolveDir follows, but ONLY when its realpath stays inside the real sync
+    // root (the whole-tree-behind-a-symlink shape, where realpathing keeps the
+    // entry label clean). When a symlink BETWEEN the root and the node file
+    // realpaths out of the tree, keep the caller's spelling: imports must
+    // resolve exactly where checkNodeImports approved them, or the guard and
+    // the bundler disagree — approving X/shared and then bundling (or failing
+    // on) something else entirely.
+    const spelledDir = path.dirname(file);
+    const realNodeDir = realDir(spelledDir);
+    const resolveDir = realNodeDir === workingDir || realNodeDir.startsWith(workingDir + path.sep) ? realNodeDir : spelledDir;
     // 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
@@ -194,7 +233,7 @@ export async function compileTs(file, log) {
             stdin: {
                 contents: entry,
                 loader: "ts",
-                resolveDir: path.dirname(file),
+                resolveDir,
                 sourcefile: ENTRY_SOURCEFILE,
             },
             bundle: true,