n8n-decanter 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -7,6 +7,465 @@ 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
+
+- **`check` now warns when local work has not been registered with n8n** — a
+  node whose `//@file:` placeholder has moved off what `.decanter.json` records
+  (the shape of a `.js`→`.ts` conversion), or whose recorded file is gone from
+  disk. It stays a *warning*, not an error: `push` reconciles the file map, and
+  the compliance guard runs before that reconcile, so failing here would refuse
+  the one command that fixes it.
+
+- **`n8n-decanter --version` prints the installed version** (`-v` too), the way
+  every CLI is expected to. It answers before any config load or verb dispatch,
+  so it works from anywhere — including outside a sync dir. Passed *alongside* a
+  verb it is a hard error naming the flag you meant, so a stray `--version`
+  can't quietly swallow a command.
+
+- **A first `init` points at n8n's official skills pack.** Setup now closes by
+  naming [n8n-io/skills](https://github.com/n8n-io/skills) — the knowledge layer
+  that makes agentic workflow building work — and printing the install commands
+  for **Claude Code**, **Codex**, and **skills.sh**, with the agent it detects
+  from your environment listed first and the activation step each one still
+  needs. It prints; it does not install: that would mean spawning a third-party
+  CLI to mutate agent state outside the sync dir, and a plugin installed
+  mid-session isn't active until the agent reloads. Said once per sync dir (no
+  re-init repeats it), on every path including piped and `--host`-driven runs,
+  and it consumes no input — no existing script's stdin changes. *(Plan 55.)*
+
+- **`init` can run non-interactively via `--host` / `--token` / `--api-key`.**
+  Passing any of them drives setup purely from the flags plus any existing
+  `.env` and issues **no prompt** — so a script or coding agent can bootstrap a
+  sync dir without the interactive stdin dance (the field-test agents needed
+  20+ tries to drive the old prompt path). `--host` is required in this mode
+  (a scheme-less local host is normalized to `http://`, like a typed one) and
+  wins over an existing `.env` value; `--token` sets `N8N_MCP_TOKEN` (headless
+  OAuth is still terminal-only); `--api-key` sets the optional `N8N_API_KEY`.
+  The flag-less path (interactive, or piped answers) is unchanged. *(Plan 35
+  field-test finding.)*
+
+- **`node run` now emulates `$jmespath`.** A Code node that calls
+  `$jmespath(data, expr)` (or the `$jmesPath` alias) runs offline, matching
+  n8n's result (backed by `jmespath@0.16.0`, the version n8n pins). It also
+  fills in `$items()`/`$node` (views over the fixture's `nodes`), `$vars`/
+  `$secrets` (new fixture fields), and `$nodeId`/`$nodeVersion`/`$webhookId`.
+
+- **`node run` fixtures gained `vars` and `secrets`** to pin the instance-scoped
+  `$vars`/`$secrets` when a node reads them.
+
+### Changed
+
+- **Breaking:** the scaffolded Claude Code settings moved from
+  **`.claude/settings.local.json` to `.claude/settings.json`**, and `init` now
+  migrates existing sync dirs. The file holds *project policy* — decanter's verb
+  permissions plus the `verify.mjs` and `mcp-route-check.mjs` hooks — with
+  nothing machine-specific in it; it was already being committed and tracked in
+  the shared `.decanter-template.json`, so `local` was the wrong scope, and it
+  squatted the one file Claude Code reserves for **your** own overrides. The
+  local slot is now yours: permission lists merge across the two files and a
+  `deny` beats an `allow`, so a local file can add to the policy but cannot
+  unblock what the project denies. On re-init, an untouched copy is moved for
+  you; a copy you edited is left exactly where it is and the new file is **not**
+  written (both would register their hooks) — `init` says what to move, and
+  `--force` resolves it by removing the old file. A `settings.local.json` that
+  `init` never wrote is never touched. *(Plan 56.)*
+
+- **Breaking: `backup restore` takes the backup as an argument, not a flag —
+  `backup restore <workflow> [<backup>]`.** `--version <id>` and `--at <ts>`
+  are gone. The argument is a **backup ref** resolved by shape, exactly like a
+  `<workflow>` ref: paste a timestamp (or a prefix — a bare date is enough) or a
+  `versionId` (short or full), whichever column of `backup list` you have to
+  hand. `backup restore order-sync 2026-07-24` and `backup restore order-sync
+  a1b2c3d4` both just work; a ref that matches nothing is an error, never a
+  silent fall back to the latest. The retired flags fail loudly with the
+  replacement. This also un-squats `--version`, which no CLI can spend on a
+  verb-scoped meaning (see Added).
+
+- **`check`'s success line now states its scope** —
+  `OK (local layout — status compares with n8n)` instead of a bare `OK`. `check`
+  is offline by definition, so green means "well-formed", never "live in n8n".
+  The agent guide gained the matching rule, and the `.js`→`.ts` recipe now ends
+  at `push` rather than `check` — it previously told you to stop one step short
+  of the conversion actually reaching the instance. *(Surfaced by the Plan 35
+  blind field test: three separate sessions authored code, read a green `check`
+  as "done", and never pushed.)*
+
+- **`scenario create` / `scenario check` with no workflow now open the picker on
+  a terminal**, like every other ref-taking verb (`pull`, `push`, `backup …`, …).
+  They previously hard-errored with a usage line even on a TTY, which made them
+  the odd ones out. Piped / non-TTY runs are unchanged — still the usage error —
+  so scripts and agent harnesses never block on a prompt. *(Surfaced by the Plan
+  35 blind field test, where an agent tripped the inconsistency twice.)*
+
+- **`node run` signposts instead of crashing on instance-scoped globals.** A
+  global whose value lives on the running instance (`$vars`/`$secrets` when
+  unpinned, `$evaluateExpression`) now throws a friendly message that names the
+  global and points to `test` (or the fixture field) — never a bare
+  `ReferenceError`. `docs/cli/node-run.md` documents the covered / partial /
+  unsupported boundary.
+
+### Fixed
+
+- **The documented Claude Code skills-install commands are no longer
+  copy-paste-broken.** `/plugin marketplace add` / `/plugin install` are
+  in-session slash commands, but the docs and the scaffolded `AGENTS.md`
+  presented them as shell commands. Both now show the in-session form and the
+  real shell equivalents (`claude plugin marketplace add …` /
+  `claude plugin install …`) separately, plus the post-install activation step
+  each agent needs.
+
+- **A `.js`→`.ts` conversion is no longer reverted by a pull that fires before
+  the first TS push.** Re-pointing a node's `//@file:` placeholder to a `.ts`
+  file and swapping the source is the sanctioned way to convert a node, but a
+  `pull` landing in the window before the first TS `push` — notably the
+  on-by-default live-mirror background refresh after a structure edit — rewrote
+  the placeholder back to `.js` and left `.decanter.json` pointing at the
+  deleted `.js` file, so the next push failed with `referenced node file
+  missing`. Pull now honors the re-pointed placeholder exactly as push does
+  (they share one reconcile step). *(Plan 35 field-test finding.)*
+
+- **`init` no longer breaks local `http` instances.** A scheme-less host typed
+  at the `n8n host:` prompt now defaults to `http://` for local addresses
+  (`localhost`, loopback, private LAN ranges, `*.local`) and `https://`
+  otherwise. Previously every scheme-less host got `https://`, so a local n8n
+  (plain http) was written to `.env` as a TLS URL and every sync/guard call
+  failed with `fetch failed`. A scheme you type is still kept as-is.
+
+- **`n8n-globals.d.ts` no longer over-declares `$if`/`$min`/`$max`.** Those are
+  n8n *expression-language* helpers (`{{ }}` only), not Code-node globals — they
+  throw in a real Code node too — so declaring them wrongly type-checked broken
+  code. The declared surface now matches what a Code node actually sees, and is
+  single-sourced (init copies the one root file — no duplicate template copy).
+
+- The scaffolded agent permission allowlist (`.claude/settings.json` — see the
+  move under Changed) now
+  pre-approves the read-only **`preflight`** gate, so an agent following the
+  template's recommended `edit → check → preflight → push` loop no longer stalls
+  on a permission prompt at the gate itself. Also dropped the obsolete
+  `*.remote.js` deny rule — those artifacts were removed in the Plan 32 MCP pivot.
+
 ## [0.6.0] - 2026-07-23
 
 ### 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`,
@@ -105,29 +110,31 @@ through [`mcp connect`](docs/cli/mcp-connect.md), a guard that forwards
 everything except writes to a Code node's `jsCode` — those redirect back to
 the repo (edit the file, `push`). No secret to manage.
 
+**A first [`init`](docs/cli/init.md) prints the install commands** for Claude
+Code, Codex, or any skills.sh-supported agent, listing the one it detects first.
+
 **Full guide: [Using n8n's official skills](docs/agents/n8n-skills.md).**
 
 ## 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).
 
 | Verb | What it does |
 |---|---|
-| `init [dir]` | Interactive bootstrap — OAuth, template, config, agent tooling |
+| `init [dir]` | Bootstrap a sync dir — OAuth/token, template, config, agent tooling (`--host`/`--token`/`--api-key` drive it non-interactively) |
 | `completion zsh\|bash` | Print a shell completion script |
 | `pull [workflow…]` | Code + structure snapshot → `workflows/<kebab>/` |
 | `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) |
@@ -167,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/backup.mjs

@@ -156,17 +156,17 @@ async function assembleForRestore(dir, backup, log) {
     return { body, nodes };
 }
 /**
- * `backup restore` — git → instance. Select a backup (latest by default;
- * `--version`/`--at`, or a TTY chooser), re-inline the Code-node source,
+ * `backup restore` — git → instance. Select a backup (latest by default; a
+ * positional backup ref, or a TTY chooser), re-inline the Code-node source,
  * compliance-guard the assembly, and REST-POST a NEW, unpublished workflow
  * (new workflow id; node ids preserved). Prints credential-rebind hints + the
  * editor URL; publish is the operator's next step.
  */
-export async function backupRestore(api, dir, { host, version, at, interactive = false }, log) {
+export async function backupRestore(api, dir, { host, ref, interactive = false }, log) {
     const backups = listBackups(dir);
     if (backups.length === 0)
         throw new Error(`no backups in ${path.basename(dir)}/${BACKUPS_DIR}/ — run \`backup create\` first`);
-    const selected = await selectBackup(backups, { version, at, interactive }, log);
+    const selected = await selectBackup(backups, { ref, interactive }, log);
     if (selected === null)
         return null; // user quit the chooser
     const backup = JSON.parse(readFileSync(selected.file, "utf8"));
@@ -187,28 +187,38 @@ export async function backupRestore(api, dir, { host, version, at, interactive =
     log.info(style.dim("it landed unpublished — review, rebind credentials, then publish to go live"));
     return { id: created.id };
 }
-/** Pick which backup to restore: explicit flags, else a TTY chooser, else latest. */
-async function selectBackup(backups, { version, at, interactive }, log) {
-    if (version !== undefined) {
-        // match against the full inner versionId or the short one in the name
-        const hit = backups.find((b) => {
-            if (b.versionId === version || version.startsWith(b.versionId))
-                return true;
-            try {
-                return JSON.parse(readFileSync(b.file, "utf8")).versionId === version;
-            }
-            catch {
-                return false;
-            }
-        });
-        if (!hit)
-            throw new Error(`no backup with versionId "${version}" — see \`backup list\``);
-        return hit;
+/**
+ * A **backup ref** resolves like a workflow ref does — untyped, by shape, over
+ * the two keys `backup list` prints. Both are in the filename
+ * (`<timestamp>.<shortVersionId>.json`), so one positional covers both without
+ * the caller having to say which it meant:
+ *
+ * - **timestamp** — exact, or any prefix of the filename (a bare date works)
+ * - **versionId** — the short one in the filename, the full one the user pastes
+ *   from n8n (a prefix of which the short id is the head), or the full one
+ *   stored *inside* the backup
+ *
+ * The two key spaces don't collide in practice (timestamps lead with a date,
+ * versionIds are uuids), so first-match-wins needs no tie-break.
+ */
+function matchesBackupRef(b, ref) {
+    if (b.timestamp === ref || b.name.startsWith(ref))
+        return true;
+    if (b.versionId === ref || ref.startsWith(b.versionId))
+        return true;
+    try {
+        return JSON.parse(readFileSync(b.file, "utf8")).versionId === ref;
+    }
+    catch {
+        return false;
     }
-    if (at !== undefined) {
-        const hit = backups.find((b) => b.timestamp === at || b.name.startsWith(at));
+}
+/** Pick which backup to restore: an explicit ref, else a TTY chooser, else latest. */
+async function selectBackup(backups, { ref, interactive }, log) {
+    if (ref !== undefined) {
+        const hit = backups.find((b) => matchesBackupRef(b, ref));
         if (!hit)
-            throw new Error(`no backup at "${at}" — see \`backup list\``);
+            throw new Error(`no backup matching "${ref}" in ${BACKUPS_DIR}/ — pass a timestamp or versionId from \`backup list\``);
         return hit;
     }
     const latest = backups.at(-1);