n8n-decanter 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -7,6 +7,145 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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

@@ -105,6 +105,9 @@ 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
@@ -115,7 +118,7 @@ Full flag reference: `n8n-decanter --help`, or the
 
 | 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** |

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);

package/dist/lib/init.mjs

@@ -1,13 +1,30 @@
-import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseEnvFile } from "./config.mjs";
 import { AUTH_FILE, McpClient, openBrowserCommand, readAuthFile, runOAuthConsent, searchWorkflows, writeAuthFile, } from "./mcp.mjs";
 import { PROXY_STATE_FILE } from "./mcpserve.mjs";
 import { createPrompt } from "./prompt.mjs";
+import { detectAgent, printSkillsRecommendation } from "./skills.mjs";
 import { style } from "./style.mjs";
 import { classifyTemplateFile, MANIFEST_FILE, readManifest, writeManifest } from "./template.mjs";
 import { sha256 } from "./util.mjs";
+/**
+ * Normalize a user-entered n8n host into a full origin. A scheme the user typed
+ * is kept as-is; a scheme-less host gets `http://` when it is a LOCAL address
+ * (localhost, loopback, private LAN ranges, `*.local`) and `https://` otherwise.
+ * A local n8n almost always serves plain http, so blindly defaulting to https
+ * left `.env` pointing at a TLS endpoint that doesn't exist — every sync/guard
+ * fetch then failed with `fetch failed` (Plan 35 field-test finding). Trailing
+ * slashes are stripped.
+ */
+export function normalizeHostInput(raw) {
+    const host = raw.trim();
+    if (/^https?:\/\//i.test(host))
+        return host.replace(/\/+$/, "");
+    const isLocal = /^(localhost|0\.0\.0\.0|127\.\d{1,3}\.\d{1,3}\.\d{1,3}|10\.\d{1,3}\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3}|172\.(1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}|\[::1\]|::1|[a-z0-9-]+\.local)(:\d+)?$/i.test(host);
+    return ((isLocal ? "http://" : "https://") + host).replace(/\/+$/, "");
+}
 /** Like readAuthFile, but a corrupt file only warns — init re-mints it. */
 function readAuthFileTolerant(dir, log) {
     try {
@@ -38,8 +55,8 @@ export function packageRootFrom(startDir) {
 }
 const PACKAGE_ROOT = packageRootFrom(path.dirname(fileURLToPath(import.meta.url)));
 const TEMPLATE_DIR = path.join(PACKAGE_ROOT, "template");
-/** Own package version (banner); tolerant of an unreadable package.json. */
-function cliVersion() {
+/** Own package version (banner, `--version`); tolerant of an unreadable package.json. */
+export function cliVersion() {
     try {
         return JSON.parse(readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8")).version ?? "0.0.0";
     }
@@ -68,10 +85,31 @@ export function printBanner(log) {
 }
 /**
  * Classify every template file against the target dir and the copy-time
- * baseline manifest. Pure scan — no files are written.
+ * baseline manifest. Pure scan — no files are written. `extraSources` folds in
+ * files authored *outside* `template/` that init still materializes into the
+ * sync dir (Plan 43: `n8n-globals.d.ts` is sourced from the single root file,
+ * not a byte-identical `template/*.example` duplicate) — they flow through the
+ * identical pristine/drift/manifest logic, keyed by their materialized rel path.
  */
-function scanTemplate(srcDir, destDir, manifest, protect) {
+function scanTemplate(srcDir, destDir, manifest, protect, extraSources = []) {
     const entries = [];
+    const classify = (srcPath, materializedRel) => {
+        const destPath = path.join(destDir, materializedRel);
+        if (protect.has(destPath))
+            return; // .env: written separately, never manifest-tracked
+        const templateHash = sha256(readFileSync(srcPath, "utf8"));
+        const exists = existsSync(destPath);
+        const targetHash = exists ? sha256(readFileSync(destPath, "utf8")) : undefined;
+        const manifestHash = manifest[materializedRel];
+        entries.push({
+            rel: materializedRel,
+            srcPath,
+            destPath,
+            templateHash,
+            targetHash,
+            outcome: classifyTemplateFile({ exists, targetHash, templateHash, manifestHash }),
+        });
+    };
     const walk = (src, rel) => {
         for (const entry of readdirSync(src, { withFileTypes: true })) {
             const srcPath = path.join(src, entry.name);
@@ -82,31 +120,97 @@ function scanTemplate(srcDir, destDir, manifest, protect) {
             const name = entry.name.endsWith(".example") && entry.name !== ".example"
                 ? entry.name.slice(0, -".example".length)
                 : entry.name;
-            const materializedRel = path.join(rel, name);
-            const destPath = path.join(destDir, materializedRel);
-            if (protect.has(destPath))
-                continue; // .env: written separately, never manifest-tracked
-            const templateHash = sha256(readFileSync(srcPath, "utf8"));
-            const exists = existsSync(destPath);
-            const targetHash = exists ? sha256(readFileSync(destPath, "utf8")) : undefined;
-            const manifestHash = manifest[materializedRel];
-            entries.push({
-                rel: materializedRel,
-                srcPath,
-                destPath,
-                templateHash,
-                targetHash,
-                outcome: classifyTemplateFile({ exists, targetHash, templateHash, manifestHash }),
-            });
+            classify(srcPath, path.join(rel, name));
         }
     };
     walk(srcDir, "");
+    for (const s of extraSources)
+        classify(s.srcPath, s.rel);
     return entries;
 }
 function copyEntry(entry) {
     mkdirSync(path.dirname(entry.destPath), { recursive: true });
     copyFileSync(entry.srcPath, entry.destPath);
 }
+/**
+ * Template files that changed NAME between CLI versions, as materialized rel
+ * paths. The manifest is keyed by path, so without this a rename reads as
+ * "delete one file, add another" and the two copies coexist — which for a
+ * settings file means the stale one silently keeps applying.
+ *
+ * Plan 56: `.claude/settings.local.json` → `.claude/settings.json`. The file
+ * holds *project policy* (decanter's verb permissions, the `verify.mjs` and
+ * `mcp-route-check.mjs` hooks) — nothing machine-specific — and it was already
+ * being committed (init's `.gitignore` never covered it) and tracked in the
+ * shared `.decanter-template.json`. Scaffolding it into the `local` slot both
+ * mislabeled it and squatted the one file Claude Code reserves for the *user's*
+ * own machine-specific overrides.
+ */
+const TEMPLATE_RENAMES = [
+    { from: path.join(".claude", "settings.local.json"), to: path.join(".claude", "settings.json") },
+];
+/**
+ * Resolve each rename against a target dir, before the template scan runs.
+ * Returns the destination paths the scan must NOT write this run, plus manifest
+ * entries to carry over — a deferred migration has to stay tracked, or the next
+ * re-init (whose manifest is rebuilt from scanned template files, and so has
+ * forgotten the old name) can no longer tell decanter's leftover file from one
+ * the user wrote, and gives up on it forever.
+ *
+ * Deliberately file-driven rather than manifest-driven: a rename does not
+ * change the file's *contents*, so "is this decanter's copy, untouched?" is
+ * answerable by hashing — which also works for dirs that pre-date manifests.
+ *
+ * - The old file is not ours (no manifest entry, contents ≠ the template) →
+ *   leave it completely alone. It is the user's own personal settings file, and
+ *   the new project-scoped one is scaffolded alongside it as normal.
+ * - Ours and pristine → delete it; the scan then lands the new name.
+ * - Ours but locally edited → keep it and **skip scaffolding the new name**.
+ *   Writing both would double-register the PostToolUse/SessionStart hooks, so
+ *   the user is told to move their file instead. The next init picks up where
+ *   they left off, because this check reads the filesystem, not a flag.
+ * - Both names already present → touch nothing, just report the shadowing.
+ *
+ * `--force` keeps its documented meaning (reset every template file to its
+ * template version): it removes the old name even when edited, rather than
+ * leaving a stale file to shadow the reset copy.
+ */
+function migrateRenamedTemplateFiles(srcDir, destDir, manifest, force, log) {
+    const skip = new Set();
+    const keep = {};
+    for (const { from, to } of TEMPLATE_RENAMES) {
+        const oldPath = path.join(destDir, from);
+        if (!existsSync(oldPath))
+            continue;
+        const newPath = path.join(destDir, to);
+        const oldHash = sha256(readFileSync(oldPath, "utf8"));
+        const templateSrc = path.join(srcDir, `${to}.example`);
+        const templateHash = existsSync(templateSrc) ? sha256(readFileSync(templateSrc, "utf8")) : "";
+        // Never touch a file decanter did not put there.
+        if (manifest[from] === undefined && oldHash !== templateHash)
+            continue;
+        if (existsSync(newPath) && !force) {
+            keep[from] = manifest[from] ?? oldHash;
+            log.warn(`${from} and ${to} both exist — the old file still applies (and its hooks fire twice); merge it into ${to} and delete it`);
+            continue;
+        }
+        if (force && oldHash !== templateHash) {
+            rmSync(oldPath);
+            log.warn(`--force: removed ${from} (had local changes) — its content now lives at ${to}`);
+        }
+        else if (oldHash === templateHash || oldHash === manifest[from]) {
+            rmSync(oldPath);
+            log.info(`renamed ${from} -> ${to} — it holds shared project policy, so the local slot is yours again`);
+        }
+        else {
+            skip.add(newPath);
+            // stay tracked: this is still decanter's file until the user resolves it
+            keep[from] = manifest[from] ?? oldHash;
+            log.warn(`${from} has local edits, so ${to} was NOT scaffolded (both files' hooks would fire) — move your copy to ${to}, or delete it, then re-run init`);
+        }
+    }
+    return { skip, keep };
+}
 /**
  * Modification-aware template refresh (dpkg conffile-style). First init copies
  * everything and records a baseline manifest. Re-init copies files new to the
@@ -114,11 +218,16 @@ function copyEntry(entry) {
  * leaves locally-modified files alone while reporting the drift. `--force` is
  * the escape hatch: it overwrites every template file regardless.
  */
-async function refreshTemplate(srcDir, destDir, { force, protect, version }, log) {
+async function refreshTemplate(srcDir, destDir, { force, protect, version, extraSources }, log) {
     const manifest = readManifest(destDir);
     const firstInit = !existsSync(path.join(destDir, MANIFEST_FILE));
-    const entries = scanTemplate(srcDir, destDir, manifest.files, protect);
-    const nextFiles = {};
+    // Renames first: a file the migration deletes must look absent to the scan
+    // (so the new name is simply "added"), and one it defers must look protected.
+    const { skip: renameSkips, keep: renameKeep } = migrateRenamedTemplateFiles(srcDir, destDir, manifest.files, force, log);
+    const entries = scanTemplate(srcDir, destDir, manifest.files, new Set([...protect, ...renameSkips]), extraSources);
+    // A pending rename stays in the baseline; everything else is rebuilt from the
+    // scan, which is what retires the old key once the migration completes.
+    const nextFiles = { ...renameKeep };
     if (force) {
         let anyExisting = false;
         for (const e of entries) {
@@ -213,21 +322,39 @@ async function refreshTemplate(srcDir, destDir, { force, protect, version }, log
         log.info(`template up to date (${uptodate} unchanged${added.length ? `, ${added.length} added` : ""})`);
 }
 /**
- * Interactive bootstrap (Plan 32: OAuth-first): prompt for the host, run the
- * browser OAuth consent for MCP (the sync backend) with a paste-a-bearer
- * fallback, offer the OPTIONAL public API key (executions / data-tables /
- * backup only), write .env + .decanter-auth.json, copy template/.
+ * Bootstrap a sync dir (Plan 32: OAuth-first). Interactive by default: prompt
+ * for the host, run the browser OAuth consent for MCP (the sync backend) with a
+ * paste-a-bearer fallback, offer the OPTIONAL public API key (executions /
+ * data-tables / backup only), write .env + .decanter-auth.json, copy template/.
+ *
+ * Passing any of `--host`/`--token`/`--api-key` (Plan 35 field-test finding —
+ * init was undrivable headless) switches to a fully **non-interactive** mode:
+ * values come from the flags + the existing .env, and NOT ONE prompt is issued
+ * (a missing MCP token just warns, a missing API key is skipped). The flag-less
+ * invocation is unchanged (interactive, or answers piped over stdin).
+ *
+ * Plan 55: a first init closes by pointing at n8n's official skills pack — a
+ * printed recommendation, never a prompt, so no run's stdin changes.
  */
-export async function init(targetDir, { force = false } = {}, log) {
+export async function init(targetDir, { force = false, host: hostFlag, token: tokenFlag, apiKey: apiKeyFlag } = {}, log) {
     printBanner(log);
     const dir = path.resolve(targetDir ?? ".");
     mkdirSync(dir, { recursive: true });
     const envFile = path.join(dir, ".env");
     const existing = parseEnvFile(envFile);
-    let host = existing.N8N_HOST ?? "";
-    let apiKey = existing.N8N_API_KEY ?? "";
-    let mcpToken = existing.N8N_MCP_TOKEN ?? "";
+    // Precedence: an explicit flag wins over the existing .env, which wins over a
+    // prompt. A flag host is normalized the same way a typed one is.
+    let host = hostFlag !== undefined ? normalizeHostInput(hostFlag) : (existing.N8N_HOST ?? "");
+    let apiKey = apiKeyFlag ?? existing.N8N_API_KEY ?? "";
+    let mcpToken = tokenFlag ?? existing.N8N_MCP_TOKEN ?? "";
     const interactive = process.stdin.isTTY === true;
+    // Any setup flag → non-interactive: drive init purely from flags + existing
+    // .env, issuing no prompts (and no OAuth-fallback token prompt either).
+    const flagDriven = hostFlag !== undefined || tokenFlag !== undefined || apiKeyFlag !== undefined;
+    // Plan 55: point at the official skills pack once, on a FIRST init (= no
+    // baseline manifest yet). Printed, never asked — every run's stdin stays
+    // exactly as it was.
+    const firstInit = !existsSync(path.join(dir, MANIFEST_FILE));
     // ONE shared prompt session for every question: a second createPrompt()
     // would lose piped answers the first one already buffered, so the session
     // opens lazily on the first question and closes once at the end.
@@ -239,22 +366,24 @@ export async function init(targetDir, { force = false } = {}, log) {
     try {
         // --- host (prompted over stdin even when piped — init stays scriptable)
         if (host !== "") {
-            log.info(`using existing .env host (${host})`);
+            log.info(hostFlag !== undefined ? `using --host ${host}` : `using existing .env host (${host})`);
+        }
+        else if (flagDriven) {
+            throw new Error("host is required — pass --host <url> (e.g. --host http://localhost:5678)");
         }
         else {
             host = await ask("n8n host: ");
             if (!host)
                 throw new Error("host is required");
-            if (!/^https?:\/\//.test(host))
-                host = "https://" + host;
-            host = host.replace(/\/+$/, "");
+            host = normalizeHostInput(host);
         }
         // --- MCP credentials (the sync backend): existing → OAuth consent (TTY) →
         // paste-a-token fallback. Only the browser consent itself is TTY-gated;
         // piped runs go straight to the token prompt so init stays scriptable.
+        // --token / any setup flag suppresses every prompt (non-interactive mode).
         const auth = readAuthFileTolerant(dir, log);
         if (mcpToken !== "") {
-            log.info("using existing MCP token from .env (N8N_MCP_TOKEN)");
+            log.info(tokenFlag !== undefined ? "using MCP token from --token" : "using existing MCP token from .env (N8N_MCP_TOKEN)");
         }
         else if (auth !== null && auth.host === host) {
             log.info(`using existing MCP OAuth credentials (${AUTH_FILE})`);
@@ -267,17 +396,18 @@ export async function init(targetDir, { force = false } = {}, log) {
             }
             catch (err) {
                 log.warn(`OAuth consent did not complete (${err.message})`);
-                mcpToken = await ask("paste an n8n MCP token (n8n → Settings → MCP → API key) [Enter to skip]: ");
+                if (!flagDriven)
+                    mcpToken = await ask("paste an n8n MCP token (n8n → Settings → MCP → API key) [Enter to skip]: ");
             }
         }
-        else {
+        else if (!flagDriven) {
             mcpToken = await ask("n8n MCP token (n8n → Settings → MCP → API key) [Enter to skip]: ");
         }
         if (mcpToken === "" && !(auth !== null && auth.host === host)) {
             log.warn("no MCP credentials yet — sync verbs (pull/push/watch/…) will not work until you re-run init or set N8N_MCP_TOKEN");
         }
         // --- optional public API key (the REST-only surfaces)
-        if (apiKey === "") {
+        if (apiKey === "" && !flagDriven) {
             apiKey = await ask("n8n public API key (optional — executions/data-tables/backup) [Enter to skip]: ");
         }
     }
@@ -302,7 +432,11 @@ export async function init(targetDir, { force = false } = {}, log) {
     // is protected (just written with real credentials) and never tracked.
     // Files named `X.example` are inert in this repo (so agent tooling ignores
     // them while working on the CLI itself) and materialize as `X` in the target.
-    await refreshTemplate(TEMPLATE_DIR, dir, { force, protect: new Set([envFile]), version: cliVersion() }, log);
+    // `n8n-globals.d.ts` is the exception: it's sourced from the single root file
+    // (Plan 43 — no `template/*.example` duplicate to drift) but materialized and
+    // tracked exactly like a template file.
+    const extraSources = [{ rel: "n8n-globals.d.ts", srcPath: path.join(PACKAGE_ROOT, "n8n-globals.d.ts") }];
+    await refreshTemplate(TEMPLATE_DIR, dir, { force, protect: new Set([envFile]), version: cliVersion(), extraSources }, log);
     const configFile = path.join(dir, "decanter.config.json");
     if (!existsSync(configFile)) {
         writeFileSync(configFile, JSON.stringify({ root: "./workflows", workflows: [] }, null, 2) + "\n");
@@ -371,4 +505,9 @@ export async function init(targetDir, { force = false } = {}, log) {
             log.warn(`could not reach ${host} (${reason}) — .env written anyway`);
         }
     }
+    // --- the official n8n skills pack (Plan 55). Dead last, and output-only:
+    // decanter names the pack and prints the commands for the detected agent,
+    // but installs nothing (see lib/skills.mts for why).
+    if (firstInit)
+        printSkillsRecommendation(detectAgent(), log);
 }

package/dist/lib/pull.mjs

@@ -3,7 +3,7 @@ import path from "node:path";
 import { compileTs } from "./compile.mjs";
 import { commitWorkflowDir } from "./git.mjs";
 import { getWorkflowDetails } from "./mcp.mjs";
-import { findWorkflowDir, readState, renameNodeFilePair, writeState } from "./state.mjs";
+import { findWorkflowDir, readState, reconcileFileMapFromSnapshot, renameNodeFilePair, writeState } from "./state.mjs";
 import { CODE_DIR, FILE_PLACEHOLDER_PREFIX, isJsCodeNode, kebabCase, sha256, splitMarker, stableWorkflowJson, } from "./util.mjs";
 function writeIfChanged(file, content) {
     if (existsSync(file) && readFileSync(file, "utf8") === content)
@@ -72,6 +72,12 @@ export async function pullWorkflow(mcp, root, id, { commitOnPull = false } = {},
     state.nodes ??= {};
     // structural hashing died with Plan 32 — scrub the legacy field on rewrite
     delete state.lastPulledWorkflowHash;
+    // Honor a re-pointed //@file: placeholder (e.g. an `.js`→`.ts` conversion the
+    // agent just made) before deriving files from node names — otherwise this
+    // pull would treat the stale `.js` map entry as authoritative and rewrite the
+    // placeholder back to `.js` (Plan 35 field-test finding). Same reconcile push
+    // runs, so the two stay symmetric.
+    reconcileFileMapFromSnapshot(dir, state);
     const usedNames = new Set();
     const placeholders = new Map(); // node id -> file name
     for (const node of wf.nodes) {
@@ -107,8 +113,11 @@ export async function pullWorkflow(mcp, root, id, { commitOnPull = false } = {},
         }
         else if (nodeState.file?.endsWith(".ts") || existsSync(path.join(dir, CODE_DIR, base + ".ts"))) {
             // Local .ts exists but remote carries no marker: never clobber TS source
-            // and don't drop a competing .js next to it.
-            const tsFile = nodeState.file ?? `${CODE_DIR}/${base}.ts`;
+            // and don't drop a competing .js next to it. Pick the actual `.ts` path —
+            // a `nodeState.file` still ending in `.js` is a not-yet-reconciled
+            // pre-conversion entry, so fall to the detected `<base>.ts` instead of
+            // parroting the deleted `.js` (Plan 35 field-test finding).
+            const tsFile = nodeState.file?.endsWith(".ts") ? nodeState.file : `${CODE_DIR}/${base}.ts`;
             log.warn(`${wf.name} / ${node.name}: local ${tsFile} exists but remote code has no @ts-n8n marker (not pushed from TS yet?) — keeping your .ts; the next push overwrites the remote code`);
             placeholders.set(node.id, tsFile);
             state.nodes[node.id] = { ...nodeState, file: tsFile, lastPushedHash: remoteHash, name: node.name };