n8n-decanter 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -7,6 +7,326 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-07-27
+
+### Added
+
+- **The interactive picker offers a `--force` retry when a `push` hits the drift
+  guard.** Previously the error was printed and you were dropped back at the
+  menu, having to leave the picker and re-run `push --force` by hand — even
+  though the CLI had just told you `--force` would fix it. Now it asks:
+
+  ```
+  ✗ remote code changed since last sync — pull first (or repeat with --force to overwrite the draft)
+  retry with --force and overwrite the remote draft? [y/N]
+  ```
+
+  The default is **No**: a bare `Enter`, or anything other than `y`/`yes`,
+  returns to the menu exactly as before. Answering `y` re-runs the same menu row
+  (flags included) with `--force`, overwriting the n8n **draft** only — the
+  published version is untouched.
+
+  **It only appears for failures `--force` can actually fix.** A layout
+  compliance error never prompts, because forcing does not bypass it. And this
+  is the interactive picker session only: piped and non-interactive runs never
+  prompt — they print the `--force` hint and exit non-zero, unchanged.
+
+- **`diff` — the new verb for "show me the actual changed lines".** It is the
+  promoted half of `status --diff`: per-node unified line diffs of your local
+  code against the n8n draft, `.ts` compiled first (bundling `shared/*`, so a
+  helper edit shows every importing node). Nodes that are in sync are omitted
+  entirely, and a clean tree says so in one line. Multi-ref like `pull`/`push`;
+  no workflow on a terminal opens the picker.
+
+  **It always exits 0.** `diff` is an inspection view, like `git diff` — the
+  gate is `preflight`. See the migration note under Removed.
+
+- **`preflight --viewer`** (with `--simulate`): leaves a browsable throwaway
+  n8n running so you can open the replayed run in the UI — the interactive half
+  of the old `simulate` verb, now explicit instead of implied by a TTY. It does
+  **not** relax preflight's safety contract: the graded run stays headless with
+  `--network-none`, and the viewer is a second, separate container. A workflow
+  with a multi-batch loop reports `simulate` as **skipped** under `--viewer`
+  ("a preview, not a pass/fail check"), never as a pass.
+
+- **`preflight --no-typecheck`** skips the `types` check — the escape hatch the
+  retired `check` verb had.
+
+- **The agent guard now logs a startup line and an audit trail** (`mcp connect`
+  and `mcp serve` alike, on stderr):
+
+  ```
+  guard: connected to <host> — forwarding all n8n MCP tools, blocking jsCode writes in update_workflow
+  guard: forwarded search_workflows
+  ```
+
+  Previously the guard spoke **only** when it blocked something, so an empty log
+  meant either "ran, blocked nothing" or "never started" — indistinguishable,
+  and opposite in meaning. The startup line settles that; the per-call lines
+  make the guard the one place that can answer *what did an agent actually do
+  to my n8n instance?*, since every MCP call passes through it.
+
+  **Tool names only — arguments are never logged**, so the log stays safe to
+  attach to a bug report.
+
+- **Every `preflight` finding can now carry `details[]`** — the full list behind
+  the one-line message: *every* layout violation, *every* `tsc` error, the
+  drifted node names, the viewer URL. Printed indented under the check line,
+  and present in `--json`. This is how the information `check` printed in full
+  survives its removal; without it, folding `check` into `preflight` would have
+  truncated a 12-violation layout failure to its first line.
+
+### Changed
+
+- **The picker lists pulled workflows newest-synced first**, instead of the
+  folder's alphabetical order — the workflow you last pulled or pushed is under
+  the cursor when the picker opens. Unpulled remote rows keep their place after
+  the local ones. The signal is each workflow folder's sync timestamp, so it is
+  *local activity*, not committed history: right after a fresh `git clone`
+  everything looks equally recent and the list falls back to alphabetical until
+  your first pull or push. Scripted `list` output is deliberately unchanged.
+
+- **The CLI banner's `n8n` wordmark now uses the brand orange, matching the
+  website** (`#E18528`, derived from the site's accent color) rather than ANSI
+  red. It degrades gracefully — a 256-color terminal gets the nearest orange, a
+  16-color one keeps the old red — and piped output and `NO_COLOR` stay plain,
+  exactly as before.
+
+- **Breaking: `preflight`'s profiles are replaced by two orthogonal flags.**
+  `--full` and the `Profile` model are gone. Depth is now `--simulate`
+  (**additive** — appends the local-engine run of your code) and `--offline`
+  (**subtractive** — drops the instance-reads tier), and they compose:
+
+  ```
+  preflight                       static + instance reads            (the default gate)
+  preflight --simulate            + a local-engine run of your code
+  preflight --offline             static only — no instance contact
+  preflight --offline --simulate  static + local engine, no instance
+  ```
+
+  **Migration:** `--full` → `--simulate`. And read the next entry carefully —
+  `--offline` still exists but means something narrower.
+
+- **Breaking: `preflight --offline` no longer runs the local-engine replay.**
+  It used to mean "static + engine, no instance"; it now means "static only".
+  The flag name is unchanged, so **nothing will error** — an air-gapped CI job
+  on `preflight --offline` simply stops running the engine and quietly loses
+  that coverage. **Migration:** `preflight --offline --simulate` is the old
+  `--offline`. (This narrowing is also what makes `--offline` fast enough for
+  the per-edit hook: it now spawns no Docker container.)
+
+- **Breaking: `preflight --json` replaces `profile` with `flags`.** Where the
+  report carried `"profile": "default" | "full" | "offline"` it now carries
+  `"flags": {"simulate": false, "offline": false}`. Agents key on this. Every
+  other field is unchanged, and each entry in `checks[]` gains an optional
+  `details: string[]`.
+
+- **`preflight` with no workflow and an empty `"workflows"` config now checks
+  every *pulled* workflow** instead of erroring with "no workflow ids" — the
+  behaviour the `check` verb had, kept now that `preflight` absorbs it.
+
+- **A workflow folder with an unreadable `.decanter.json` no longer fails your
+  gate.** `check` scanned *folders*, so a corrupt state file anywhere under
+  `workflows/` was a hard error for the whole run. `preflight` grades resolved
+  *workflows*, and a folder whose state won't parse can't resolve to one — so
+  it is named in a warning (`corrupt .decanter.json (…) — skipping this
+  folder`) and skipped, while every healthy workflow is still graded. The fact
+  is still reported; it just no longer blocks work on unrelated workflows.
+
+- **`preflight --simulate` accepts multiple workflows.** The old `simulate`
+  verb took exactly one; preflight loops, so a multi-ref run spins one engine
+  container per workflow, serially.
+
+- **The scaffolded template now runs `preflight --offline` where it ran
+  `check`** — the PostToolUse verify hook, both `package.json` scripts, and the
+  agent-facing prose in `AGENTS.md` / `CLAUDE.md`. *Existing sync dirs keep
+  their files*: re-run `n8n-decanter init` to be offered the refresh, and note
+  that init leaves locally-modified files alone, so a hand-edited hook or
+  `package.json` still invokes a removed verb until you update it yourself.
+
+- The scaffolded agent permission allowlist swaps its `check`/`status`/
+  `simulate` rules for a `diff` pair (both the bare and `npx` shapes);
+  `preflight --simulate` is already covered by the existing `preflight:*` rule.
+
+- The interactive picker's action menu is now `preflight`, `preflight
+  --simulate`, `diff`, `pull`, `push`, `watch`, `executions` — a menu row may
+  carry flags, which is how the browsable local-engine run survives the fold.
+
+- **The scaffolded agent contract now treats `push` as part of finishing the
+  work, and reserves "ask the user first" for `publish`.** A push lands on the
+  workflow's **draft** and never changes what is running; only `publish` /
+  `push --publish` / `unpublish` do. The old rule gated both behind "only when
+  the user asks", so an agent handed "build me an hourly job that tags orders"
+  would build the structure in n8n, write and verify all the Code, and then
+  **stop** — leaving every Code node empty on the instance and the real code in
+  the repo, reporting "ready to push". Correct by the old rule, and not what
+  anybody asked for. Agents are now told to push once offline checks pass, to
+  say what landed, and to still ask first when the workflow is published/active
+  or a teammate is editing it. Going live remains a deliberate, user-requested
+  step. Affects `template/AGENTS.md.example` (copied into new sync dirs by
+  `init`) and the `/docs/agents` surfaces. *(Surfaced by the Plan 35 blind field
+  test, where the "failing" agent was following the old contract exactly.)*
+
+- **The scaffolded agent contract now follows the `preflight → push → test →
+  publish` flow.** `preflight` is local-only (it no longer runs on the instance),
+  so `test` — which runs the workflow's **draft** — is only meaningful *after* a
+  push. The old contract framed `test` as a pre-push runtime check and ended its
+  loop at `preflight → push`; both are now reconciled to the new order. Affects
+  `template/AGENTS.md.example` and the `/docs/agents` surfaces. *(Same surface
+  the Plan 60 verb reorder changed — kept in lockstep so the blind field test
+  grades agents against a contract that matches the tool.)*
+
+- **Breaking: `preflight` no longer runs the instance-side `test` stage.** It
+  ran `test_workflow` against n8n's **draft**, while every other stage graded
+  your **local files** — so whenever a push was pending, one score described
+  two different versions of the workflow, flagged only by a `-10` parity warn.
+  A report could read *caution, 90/100* while its runtime evidence was about
+  code you weren't shipping. `preflight` now grades local code only; the
+  instance is read for sync facts and never executed.
+
+  The documented flow is **`preflight` → `push` → `test` → `publish`**: verify
+  local code, make it the draft, run what you actually pushed, then go live.
+  Nothing was removed from the toolbox — the instance run moved to where it
+  means something.
+
+  **Migration:** a CI job that gates on a plain `preflight` no
+  longer gets an instance run inside that gate — the draft is never executed by
+  preflight. To keep instance-run coverage, add `n8n-decanter test` as its own
+  step **after** your push step (`--require=test` users get a hard error with
+  this guidance; default-profile users get this note).
+
+- **Breaking: `preflight --require=test` is rejected**, with a message pointing
+  at the new flow rather than a bare "unknown check". The `test` id is gone
+  from `--require`, from `--json` `checks[]`, and from `coverage`.
+
+- **`preflight` auto-fetches a capture only under `--simulate`** — the flag
+  that adds the one stage which consumes a capture. Without it there is no
+  runtime stage, so preflight no longer fetches, and a missing or stale capture
+  is reported as `info` rather than `warn` — nothing would consume one
+  (`--offline` never reaches the instance to fetch either way).
+
+- The `parity` warn is reworded. It was a caveat about the runtime tier
+  grading the wrong artifact; that's no longer possible, so it is now the plain
+  next step: *"local code differs from the draft in N node(s) — push to make it
+  the draft, then test"*.
+
+- **The local-engine replay is the sole runtime stage** (`preflight --simulate`)
+  and needs Docker. For runtime evidence without Docker, push and then run
+  `test`.
+
+- **Node-file type checking moved off TypeScript's legacy `node10` module
+  resolution** to `moduleResolution: "bundler"` (with `module: "preserve"`), in
+  the scaffolded `tsconfig.json`. This matches what push actually does — `.ts`
+  nodes are compiled with esbuild in bundling mode — and keeps the documented
+  extensionless import style working (`import { total } from
+  "../../shared/money"`). It also unblocks TypeScript 6, which turns `node10`
+  into a hard error (`TS5107`), and TypeScript 7, which removes it outright.
+  `node16`/`nodenext` were **not** chosen: they reject extensionless relative
+  imports (`TS2835`) and would force every node file to be rewritten with `.js`
+  extensions. No change to which Node.js versions are supported. *Existing sync
+  dirs keep their current `tsconfig.json`* — re-run `n8n-decanter init` to be
+  offered the refresh; if you have hand-edited yours (or created it before
+  template baselines existed), init reports it and leaves it alone, so apply
+  the two-line change yourself when you move to TypeScript 6+.
+
+### Removed
+
+- **Breaking: the `check`, `status`, and `simulate` verbs.** All three were
+  variations on "check my thing", and telling them apart was the single most
+  confusing part of the surface. They fold into two:
+
+  | You used to run | Now run |
+  | --- | --- |
+  | `check [workflow…]` | `preflight --offline [workflow…]` |
+  | `check --no-typecheck` | `preflight --offline --no-typecheck` |
+  | `status [workflow…]` | `preflight [workflow…]` (the scored summary) |
+  | `status --diff` | `diff [workflow…]` (the changed lines) |
+  | `simulate <workflow>` | `preflight <workflow> --offline --simulate` |
+  | `simulate --network-none` | `preflight --simulate` (always network-none) |
+
+  Each removed verb exits non-zero naming its replacement, so a stale script
+  fails loudly rather than silently. **Note the `simulate` row:** the verb
+  needed no credentials, and a bare `preflight --simulate` still runs the
+  instance tier — add `--offline` for the credential-free equivalent.
+
+  Nothing was lost with the verbs. The compliance guard still gates every push
+  and watch save (only the standalone *view* is gone, and preflight's `layout`
+  finding now lists every violation); the publish state, live-lags-draft note
+  and snapshot-stale hint are preflight's `lifecycle` and `snapshot` findings.
+
+- **Breaking: `status`'s CI exit codes.** `status` exited 1 on a code conflict
+  or remote drift, and pipelines gated on that. `diff` always exits 0.
+  **Migration:** gate on `preflight`, whose `drift` check **fails** on a
+  CONFLICT and warns on remote drift (add `--fail-on=warn` to gate on the warn
+  too).
+
+- **`simulate --network-none`.** `preflight` always runs the graded engine
+  replay with no network, so the flag had nothing left to turn off.
+
+- **Breaking: the `preflight --quick` profile.** With the `test` stage gone it
+  was byte-identical to the default profile, and rather than redefine it into a
+  meaning users would have to learn and then unlearn, it is gone. Static-only
+  checking is now `preflight --offline`; the local-engine replay is
+  `preflight --simulate` (see the profile→flags entry above, which retired
+  `--full` and the whole profile vocabulary in the same release).
+
+  **Neither `--quick` nor `--full` is recognized any more — they are simply
+  gone, not rejected with a migration.** The CLI ignores flags it does not
+  know, so `preflight --full` now runs the *default* gate (no engine) and
+  `preflight --quick` runs it too, both exiting 0. **If you have either in a CI
+  job, update it in the same step as this upgrade** — nothing will tell you at
+  runtime. `--full` → `--simulate`; `--quick` → `--offline`.
+- **Breaking: `preflight --trigger <node>`.** It existed only to feed the
+  removed instance `test` stage; since that stage's removal it parsed and did
+  nothing. `test --trigger <node>` (the post-push instance run) keeps the flag
+  — that is where trigger selection acts.
+
+### Fixed
+
+- **Renaming a `.ts` node in n8n no longer leaves it stuck on "push pending".**
+  A `.ts` node that imports from `shared/` (or an opted-in npm package) is
+  compiled with esbuild's bundler, and esbuild labels every bundled module with
+  a `// <path>` comment. That label used the node's **own filename**, so it
+  landed inside the compiled bytes — and inside the `@ts-n8n sha256:` marker.
+  Rename the node in n8n, `pull` renames `compute.ts` → `ümläut-nödé.ts`, and
+  the artifact changed even though **not one line of your source did**: `diff`
+  reported a difference that was purely the comment line, and the node read
+  "local changes — push pending" until you pushed a no-op. The entry label is
+  now a fixed name, so a pure rename round-trip is byte-stable and comes back
+  clean.
+
+  **One-time effect when you upgrade:** because the compiled bytes changed, the
+  first `diff`/`pull` after upgrading reports **"modified, not yet pushed"** for
+  every `.ts` node **that has imports** — a comment-line difference only. One
+  `push` per workflow clears it, and it is a plain push, not a conflict: the
+  remote code is untouched, so the drift guard does not trip and `--force` is
+  not needed. `.ts` nodes **without** imports compile through a different path
+  that never embedded the name, and `.js` nodes are unaffected.
+
+- **The scaffolded MCP guard now starts under a *local* install, not only a
+  global one.** `init`'s `.mcp.json` / `opencode.json` spawned the guard as a
+  bare `n8n-decanter mcp connect`, which only resolves when the CLI is on the
+  agent's `PATH` — i.e. a **global** install. With decanter installed as a
+  **local** project dependency the command silently failed to start, so the
+  agent got no guarded route and fell back to whatever other n8n MCP it had,
+  unguarded. The scaffolded command is now `npx --no-install n8n-decanter mcp
+  connect`, which resolves the local `node_modules` bin **and** a global
+  install; `--no-install` never downloads from npm, so a genuinely missing
+  install fails loudly instead of silently. (Plan 58.)
+
+- **The scaffolded agent permissions now cover `npx n8n-decanter …` — including
+  the `push --force` denial.** The same local-install gap applies to the CLI
+  calls an agent makes in a shell: under a local (devDependency) install a bare
+  `n8n-decanter <verb>` is not on `PATH`, so the working form is
+  `npx n8n-decanter <verb>`. The permission matcher keys on the command prefix,
+  so that form previously matched **neither** the allow rules (every safe call
+  would stop to ask) **nor the `push --force` deny rule** — meaning the
+  force-push guard rail could be sidestepped simply by invoking through `npx`.
+  Both lists now carry the `npx` forms (Claude Code `settings.json` and
+  opencode), and the scaffolded `AGENTS.md` tells agents to add the prefix when
+  the bare command is not found. Installing globally is **not** required — a
+  per-sync-dir devDependency remains fully supported. (Plan 58.)
+
 ## [0.7.0] - 2026-07-24
 
 ### Added

package/README.md

@@ -35,17 +35,22 @@ clean git diffs.
 - **TypeScript or typed JS** — write nodes in TS (compiled on push) or plain
   JS; n8n globals (`$input`, `$('…')`, …) are typed in both.
 - **Agent-native** — `init` scaffolds Claude Code / Cursor / Codex configs;
-  offline `check` and `node run` give agents a credential-free feedback loop.
-- **Guardrails & preflights** — a compliance guard, typecheck gate, and
-  per-node drift guard gate every push; `check` (offline), `simulate`
-  (offline engine replay, Docker), and `test` (instance-side) each diff every
-  node against a real captured execution and exit 1 on divergence — and
-  `preflight` runs the whole ladder as one **scored, read-only, CI-gateable
-  verdict** (never mutates), the single gate an agent runs before `push`.
+  the offline `preflight --offline` / `node run` loop gives agents a
+  credential-free feedback loop.
+- **One gate, two depth flags** — a compliance guard, typecheck gate, and
+  per-node drift guard gate every push; `preflight` folds layout, types and
+  instance sync facts into a single **read-only, CI-gateable verdict** (never
+  writes, never runs on your instance). `--simulate` *adds* an offline engine
+  replay (Docker), `--offline` *drops* the instance reads — and both that
+  replay and instance-side `test` diff every node against a real captured
+  execution and exit 1 on divergence. The flow is **`preflight` → `push` →
+  `test` → `publish`**: verify local, make it the draft, run what you pushed,
+  go live.
 - **Committed, schema-scaffolded scenarios** — `scenario create` turns a
   captured execution and/or the workflow's own output schemas
   (`--scaffold`, no LLM API) into a reviewable, git-tracked pin-data set that
-  `test`/`simulate` replay — the durable counterpart to an agent's ephemeral
+  `test` and `preflight --simulate` replay — the durable counterpart to an
+  agent's ephemeral
   in-session pin flow.
 - **Live editing** — `watch` pushes on save; the open n8n editor tab reflects
   each push live (n8n's own draft-edit refresh, no proxy needed).
@@ -87,7 +92,7 @@ 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).
 (`decanter.config.json`'s optional `"workflows"` array just sets the default
-set a bare `pull`/`push`/`status` acts on.)
+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`,
@@ -112,7 +117,8 @@ Code, Codex, or any skills.sh-supported agent, listing the one it detects first.
 
 ## Commands
 
-Bare `n8n-decanter` (no verb) opens an interactive picker on a terminal.
+Bare `n8n-decanter` (no verb) opens an interactive picker on a terminal —
+newest-synced workflow first.
 Full flag reference: `n8n-decanter --help`, or the
 [command overview](docs/cli/overview.md).
 
@@ -124,13 +130,11 @@ Full flag reference: `n8n-decanter --help`, or the
 | `push [workflow…]` | Push Code-node source to the workflow's **draft** |
 | `watch [workflow]` | Push on save (draft-only); editor updates live |
 | `publish` / `unpublish [workflow…]` | Take the draft live / back to draft-only |
-| `status [workflow…]` | Drift report — exits 1 on conflict or remote drift |
-| `check [workflow…]` | Offline layout-compliance check + typecheck |
+| `diff [workflow…]` | Per-node line diff of local code vs the n8n draft — an inspection view, always exits 0 |
 | `executions [workflow…]` | Fetch recent execution data (read-only) |
 | `data-tables [table…]` | Fetch data-table schema + rows (read-only) |
 | `test <workflow>` | Pinned run **on the instance** (draft); diffs vs a capture |
-| `simulate <workflow>` | Offline engine replay (Docker); diffs vs a capture |
-| `preflight [workflow…]` | The whole verification ladder as one scored, read-only gate (exits 1 on *not ready*) |
+| `preflight [workflow…]` | The one local gate — layout, types, instance sync facts, optional local-engine replay — scored and read-only; run before `push` (exits 1 on *not ready*) |
 | `scenario create` / `scenario check` | Build / validate a committed scenario (captured and/or schema-scaffolded) |
 | `backup create` / `restore` / `list` | Git-native disaster recovery — capture / redeploy / list versioned full-export backups |
 | `list [--remote]` | Pulled workflows (`--remote` adds unpulled ones) |
@@ -170,13 +174,13 @@ whole-workflow authoring toolkit.
 | **Shared types & helpers 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` |
 | **Code-level git versioning** | 🟡 in-app history (DB snapshots, tiered retention); Git source control is Enterprise-only | ✅ GitOps sync of workflow source | ✅ real git — diffs, PRs, blame per Code node; auto-commit each sync (+ read-only structure snapshot) |
-| **Preflights** (`check` / `simulate` / `test` / `preflight`) | 🟡 re-run past executions / pin data, but online in-editor | 🟡 inspect executions against a live env | ✅ offline `check` + `simulate`, instance-side `test`; each diffs every node vs a real capture, exits 1 on divergence — and `preflight` scores the whole ladder into one read-only, CI-gateable verdict |
+| **Preflights** (`preflight`, then `test`) | 🟡 re-run past executions / pin data, but online in-editor | 🟡 inspect executions against a live env | ✅ `preflight` scores your **local** code (layout, types, instance reads, optional offline `--simulate` engine replay) into one read-only, CI-gateable verdict *before* the push — then instance-side `test` runs the pushed draft; each runtime check diffs every node vs a real capture, exits 1 on divergence |
 | **Draft-first code sync** | ✅ editor *Save* vs *Publish* (manual, in-browser) | 🟡 API sync republishes on push (no draft-only) | ✅ pushes land on the **draft**; `publish` is the deliberate go-live (over MCP) |
 | **Live editing** | ✅ the canvas (baseline) | 🟡 explicit pull/push, no auto-watch | ✅ `watch`: push on save; the open editor tab reflects each push live (n8n-native) |
-| **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 incl. a pre-wired `mcp connect` guard holding the credentials; offline `check`/`node run` loop |
+| **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 incl. a pre-wired `mcp connect` guard holding the credentials; offline `preflight --offline`/`node run` loop |
 | **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 | ✅ your agent builds structure over n8n's MCP (through the pre-wired `mcp connect` guard); decanter owns the Code-node source (files + `push`) |
-| **Whole-workflow authoring** | ❌ | ✅ `.workflow.ts` decorator classes (structure + links) | ❌ not as repo code — Code-node source only; your agent builds structure live over MCP (row above), mirrored to a read-only `workflow.json` |
+| **Whole-workflow authoring** | ❌ | ✅ `.workflow.ts` decorator classes (structure + links) | 🟡 Code-node source only; your agent builds structure live over MCP (row above), mirrored to a read-only `workflow.json` |
 | **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.

package/dist/lib/compile.mjs

@@ -11,6 +11,15 @@ import { build, transform } from "esbuild";
 const GLOBAL_NAME = "__n8n_node";
 const SIZE_WARN_BYTES = 100_000;
 const BUILTINS = new Set(builtinModules);
+// esbuild labels every bundled module with a `// <path>` comment, so whatever
+// we call the stdin entry lands *inside* the compiled bytes — and therefore
+// inside the `@ts-n8n sha256:` marker. Using the node's own filename made a
+// pure remote rename change the artifact: `pull` renames `compute.ts` ->
+// `ümläut-nödé.ts`, the comment follows, and the node reads "push pending"
+// forever on a comment-only diff. A fixed name keeps the entry label stable
+// across renames; the surrounding dir still comes from `resolveDir`, which is
+// sticky (a workflow folder never follows a remote rename — Plan 27).
+const ENTRY_SOURCEFILE = "node.ts";
 /**
  * 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
@@ -118,7 +127,7 @@ function packageName(spec) {
  * 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.
+ * compiler, so preflight's `layout` check and `push` disagree on nothing.
  */
 export function checkNodeImports(file, specifiers, ctx) {
     const problems = [];
@@ -186,7 +195,7 @@ export async function compileTs(file, log) {
                 contents: entry,
                 loader: "ts",
                 resolveDir: path.dirname(file),
-                sourcefile: path.basename(file),
+                sourcefile: ENTRY_SOURCEFILE,
             },
             bundle: true,
             format: "iife",

package/dist/lib/diff.mjs

@@ -1,6 +1,17 @@
-// Minimal unified line diff for `status --diff` (plans/3 B). Zero deps by
-// design (Plan 11's rule); classic LCS backtracking is plenty at Code-node
-// scale, with a size cutoff instead of a fancier algorithm.
+// The `diff` verb (Plan 59) and the minimal unified line diff behind it
+// (plans/3 B). Zero deps by design (Plan 11's rule); classic LCS backtracking
+// is plenty at Code-node scale, with a size cutoff instead of a fancier
+// algorithm.
+//
+// `diff` is the `git diff` half of the old `status` verb: it shows the actual
+// changed LINES for every node that differs from the draft, and nothing else.
+// The summary half (`git status`) is `preflight`. Like `git diff` it is an
+// inspection view, not a gate — it always exits 0.
+import path from "node:path";
+import { getWorkflowDetails } from "./mcp.mjs";
+import { findWorkflowDir } from "./state.mjs";
+import { computeSyncFacts } from "./status.mjs";
+import { style } from "./style.mjs";
 function toLines(s) {
     if (s === "")
         return [];
@@ -72,3 +83,64 @@ export function unifiedDiff(a, b, context = 2) {
     }
     return out;
 }
+/** A node whose local build differs from the draft — the only thing `diff` prints. */
+function isDifferent(node) {
+    return node.state !== "in-sync";
+}
+/** One node's state headline; the line diff (when there is one) follows it. */
+function headline(node) {
+    switch (node.state) {
+        case "unknown-locally":
+            return { level: "warn", text: "remote code node unknown locally — pull" };
+        case "local-missing":
+            return { level: "warn", text: `local file ${node.file} missing` };
+        case "changed-remotely":
+            return { level: "warn", text: "changed remotely — pull" };
+        case "conflict":
+            return { level: "error", text: "CONFLICT — changed both locally and remotely" };
+        default:
+            return { level: "info", text: `local changes in ${node.file} — push pending` };
+    }
+}
+/**
+ * Print the per-node line diffs between local code and the n8n draft. For `.ts`
+ * nodes the local side is the **compiled** JS — the exact bytes `push` would
+ * send, and the same bodies the sync hashes compare.
+ *
+ * Always exits 0 (the caller sets no exit code): this is `git diff`, not a
+ * gate. `preflight` is the gate.
+ */
+export async function diffWorkflow(mcp, root, id, log) {
+    const remote = await getWorkflowDetails(mcp, id);
+    const dir = findWorkflowDir(root, id, log);
+    if (!dir) {
+        log.warn(`${remote.name} (${id}): not pulled yet — n8n-decanter pull ${id}`);
+        return;
+    }
+    log.info(`${remote.name} (${id})  [${path.relative(process.cwd(), dir)}]`);
+    const facts = await computeSyncFacts(remote, dir);
+    const changed = facts.nodes.filter(isDifferent);
+    if (changed.length === 0 && facts.deleted.length === 0) {
+        log.info(style.dim("  no differences — every tracked node matches the draft"));
+        return;
+    }
+    for (const node of changed) {
+        // Replay this node's captured compileTs warnings before its line — they are
+        // about the very build being diffed.
+        for (const w of node.warnings ?? [])
+            log.warn(w);
+        const { level, text } = headline(node);
+        log[level](`  ${node.name}: ${text}`);
+        if (node.remoteBody === undefined || node.localBody === undefined || node.localBody === null || node.file === undefined)
+            continue;
+        log.info(`    ${style.dim("--- remote (n8n)")}`);
+        log.info(`    ${style.dim(`+++ local (${node.file})`)}`);
+        for (const line of unifiedDiff(node.remoteBody, node.localBody)) {
+            const styled = line.startsWith("+") ? style.green(line) : line.startsWith("-") ? style.red(line) : style.dim(line);
+            log.info(`    ${styled}`);
+        }
+    }
+    for (const node of facts.deleted) {
+        log.warn(`  ${node.file}: node ${node.id} deleted remotely`);
+    }
+}

package/dist/lib/engine.mjs

@@ -1,4 +1,5 @@
-// Plan 7 — the engine backend for `simulate`. Runs a transformed simulation
+// Plan 7 — the engine backend for preflight's `--simulate` stage. Runs a
+// transformed simulation
 // workflow through a *real* n8n via route B (validated by the Plan 7 spike):
 // `n8n import:workflow` + `n8n execute --id --rawOutput` in a throwaway
 // container, no server and no credentials, output scraped from the result JSON.
@@ -21,7 +22,7 @@ export const DEFAULT_N8N_VERSION = "2.30.7";
 const SIM_WORKFLOW_ID = "decantersim0000";
 const EXEC_MARKER = "---DECANTER-EXEC---";
 const docker = (args, opts = {}) => execFile("docker", args, { encoding: "utf8", maxBuffer: 128 * 1024 * 1024, timeout: opts.timeoutMs ?? 120_000 });
-/** True when a Docker daemon is reachable — lets `simulate`/`test:sim` skip cleanly. */
+/** True when a Docker daemon is reachable — lets the simulate stage / `test:sim` skip cleanly. */
 export async function dockerAvailable() {
     try {
         await docker(["version", "--format", "{{.Server.Version}}"], { timeoutMs: 10_000 });

package/dist/lib/errors.mjs

@@ -0,0 +1,20 @@
+/**
+ * Typed CLI errors — the ones a *caller* has to branch on, not just print.
+ */
+/**
+ * A gate `--force` really can bypass (Plan 29). Today that is exactly one: the
+ * per-node code-drift guard in `push` (`assertNoDrift`). The compliance guard
+ * throws a plain `Error` on purpose — `--force` does **not** bypass a layout
+ * violation, so offering a force-retry there would be a lie.
+ *
+ * The interactive picker loop keys on this type to offer "retry with --force?"
+ * after a failure. Message-string sniffing was the alternative and is brittle;
+ * marking the error is explicit, and any future forceable gate opts in by
+ * throwing this instead of `Error`.
+ */
+export class ForceableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ForceableError";
+    }
+}

package/dist/lib/executions.mjs

@@ -8,12 +8,12 @@ export const EXECUTIONS_DIR = "executions";
  * captured execution (or scaffolded from the workflow's schemas), with any gap
  * nodes flagged for filling. Tracked in git (unlike gitignored `executions/`),
  * so replays are reproducible for teammates and CI. Selected explicitly by slug
- * (`simulate --scenario <slug>`), not auto-preferred.
+ * (`preflight --simulate --scenario <slug>`), not auto-preferred.
  */
 export const SCENARIOS_DIR = "scenarios";
 /** Pre-Plan-37 dir name for scenarios; auto-migrated to `scenarios/` on any verb that touches it. */
 export const LEGACY_MOCKS_DIR = "mocks";
-/** Retired per-node pin dir (`simulate --pin`); a leftover one is now a hard error naming the replacement. */
+/** Retired per-node pin dir (the old `--pin` flag); a leftover one is now a hard error naming the replacement. */
 export const LEGACY_FIXTURES_DIR = "fixtures";
 /**
  * Auto-migrate a workflow folder's pre-Plan-37 `mocks/` dir to `scenarios/`
@@ -36,7 +36,7 @@ export function migrateScenariosDir(dir, log) {
 }
 /**
  * Hard-error on a leftover `fixtures/` dir (Plan 37 fold decision 1: no
- * deprecation read-path). `simulate --pin` and per-node `fixtures/` are removed;
+ * deprecation read-path). The old `--pin` flag and per-node `fixtures/` are removed;
  * their role is absorbed by self-contained scenarios. Names the replacement.
  * No-op when there's no `fixtures/` dir with `.json` files in it.
  */
@@ -46,14 +46,14 @@ export function assertNoLegacyFixtures(dir) {
         return;
     if (!readdirSync(fx).some((e) => e.endsWith(".json")))
         return;
-    throw new Error(`legacy ${LEGACY_FIXTURES_DIR}/ dir found in ${path.relative(process.cwd(), dir)} — per-node fixtures and \`simulate --pin\` were removed (Plan 37). ` +
+    throw new Error(`legacy ${LEGACY_FIXTURES_DIR}/ dir found in ${path.relative(process.cwd(), dir)} — per-node fixtures and the old \`--pin\` flag were removed (Plan 37). ` +
         `Recreate the data as a committed scenario (\`n8n-decanter scenario create <workflow> --execution <id>\`), then delete ${LEGACY_FIXTURES_DIR}/.`);
 }
 /**
  * The newest captured execution id in a workflow folder's `executions/` dir, or
  * null when none are captured. n8n execution ids are incrementing integers, so
  * "newest" is the highest numeric filename; non-numeric files are ignored. Lets
- * `simulate`/`scenario create` (and the picker, which can't supply an id) default
+ * preflight's simulate stage / `scenario create` (and the picker, which can't supply an id) default
  * to the latest capture. Scenarios are slug-named, not "latest"-ordered, so
  * they're chosen explicitly and don't participate here.
  */

package/dist/lib/init.mjs

@@ -66,7 +66,8 @@ export function cliVersion() {
 }
 // Wordmark in the 2×2 quadrant-block minifont (Block Elements). The top row's
 // leading offset is load-bearing (ascenders of 8/d/t) — keep it verbatim.
-// Columns 0-5 are the "n8n" part (brand red on a TTY), the rest "decanter".
+// Columns 0-5 are the "n8n" part (brand orange on a TTY — the website's accent,
+// see style.brand), the rest "decanter".
 const LOGO_ROWS = [
     "  ▄▖     ▌        ▗",
     "▛▌▙▌▛▌  ▛▌█▌▛▘▀▌▛▌▜▘█▌▛▘",
@@ -80,7 +81,7 @@ export function printBanner(log) {
         return;
     }
     for (const row of LOGO_ROWS)
-        console.log(style.red(row.slice(0, 6)) + style.bold(row.slice(6)));
+        console.log(style.brand(row.slice(0, 6)) + style.bold(row.slice(6)));
     console.log(style.dim(`n8n workflows ⇄ agentic code · v${version}`));
 }
 /**