n8n-decanter 0.3.0

package/dist/lib/proxy.mjs

@@ -0,0 +1,204 @@
+import http from "node:http";
+import https from "node:https";
+import net from "node:net";
+import tls from "node:tls";
+/**
+ * Transparent development proxy for `watch` (Plan 5): pipes every request to the
+ * upstream n8n instance untouched (auth, assets, native `/rest/push` WebSocket),
+ * but injects a tiny live-reload client into HTML responses. On a successful
+ * local push the client refreshes the editor tab — unless it has unsaved edits.
+ *
+ * Native `node:http`/`net`/`tls` only, matching the project's no-extra-deps rule.
+ * Supported cleanly for a *local http* upstream (`http://localhost:5678`);
+ * https/remote upstreams are best-effort — Secure cookies won't survive the
+ * plain-http hop, breaking auth (see PLAN.md / plans/5).
+ */
+const CLIENT_PATH = "/__decanter/client.js";
+const EVENTS_PATH = "/__decanter/events";
+const INJECT_TAG = `<script src="${CLIENT_PATH}" defer></script>`;
+/** The browser-side live-reload client, served at CLIENT_PATH and injected into HTML. */
+const CLIENT_SCRIPT = `(function () {
+  "use strict";
+  var LOG = "[decanter] ";
+  // Best-effort, framework-agnostic dirty probe: dispatch a synthetic
+  // beforeunload and see whether any handler tries to block navigation — n8n
+  // installs such a guard only when the open workflow has unsaved changes.
+  // Fails safe toward NOT reloading when we can detect dirtiness; a missed
+  // detection (older/newer n8n) would reload over UI edits, so treat this as a
+  // heuristic, not a guarantee.
+  function editorIsDirty() {
+    try {
+      if (typeof window.onbeforeunload === "function") return true;
+      var ev = new Event("beforeunload", { cancelable: true });
+      window.dispatchEvent(ev);
+      return ev.defaultPrevented || ev.returnValue === false;
+    } catch (err) {
+      return false;
+    }
+  }
+  function openWorkflowId() {
+    var m = location.pathname.match(/\\/workflow\\/([^/?#]+)/);
+    return m ? m[1] : null;
+  }
+  function connect() {
+    var es = new EventSource(${JSON.stringify(EVENTS_PATH)});
+    es.addEventListener("pushed", function (e) {
+      var data = {};
+      try { data = JSON.parse(e.data || "{}"); } catch (_) {}
+      var open = openWorkflowId();
+      if (data.workflowId && open && open !== data.workflowId) return; // a different workflow is open
+      if (editorIsDirty()) {
+        console.warn(LOG + "push received but the editor has unsaved changes — not reloading. Save or discard, then refresh manually.");
+        return;
+      }
+      console.info(LOG + "reloading after push");
+      location.reload();
+    });
+    es.onerror = function () { /* EventSource reconnects on its own */ };
+  }
+  connect();
+})();
+`;
+/** The one proxy a `watch` process runs, if any — the target of notifyPushed. */
+let activeProxy = null;
+/**
+ * Signal any browser tabs connected to a running dev proxy to reload after a
+ * push. No-op when no proxy is active (plain `push`, or watch without the
+ * proxy) — this is why push code can call it unconditionally.
+ */
+export function notifyPushed(workflowId) {
+    activeProxy?.broadcast("pushed", { workflowId });
+}
+/**
+ * Boot the reverse proxy on 127.0.0.1:port, forwarding to `upstream`.
+ * Resolves to a handle, or `null` if the port can't be bound (caller keeps
+ * running without live reload — the acceptance "graceful fallback").
+ */
+export async function startProxy({ upstream, port }, log) {
+    const target = new URL(upstream);
+    const secure = target.protocol === "https:";
+    const upstreamPort = target.port ? Number(target.port) : secure ? 443 : 80;
+    const clients = new Set();
+    const server = http.createServer((req, res) => {
+        const url = req.url ?? "/";
+        if (url === CLIENT_PATH)
+            return serveClient(res);
+        if (url === EVENTS_PATH)
+            return serveEvents(req, res, clients);
+        proxyHttp(req, res, { target, upstreamPort, secure }, log);
+    });
+    server.on("upgrade", (req, socket, head) => proxyUpgrade(req, socket, head, { target, upstreamPort, secure }, log));
+    const ping = setInterval(() => {
+        for (const res of clients)
+            res.write(": ping\n\n");
+    }, 25_000);
+    ping.unref();
+    try {
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(port, "127.0.0.1", () => resolve());
+        });
+    }
+    catch (err) {
+        clearInterval(ping);
+        const e = err;
+        log.warn(`browser-reload proxy: could not bind 127.0.0.1:${port} (${e.code ?? e.message}) — continuing without live reload`);
+        return null;
+    }
+    const boundPort = server.address().port;
+    const handle = {
+        port: boundPort,
+        broadcast(event, data) {
+            const payload = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+            for (const res of clients)
+                res.write(payload);
+        },
+        async close() {
+            clearInterval(ping);
+            for (const res of clients)
+                res.end();
+            clients.clear();
+            await new Promise((resolve) => server.close(() => resolve()));
+            if (activeProxy === handle)
+                activeProxy = null;
+        },
+    };
+    activeProxy = handle;
+    log.info(`browser-reload proxy: http://127.0.0.1:${boundPort} -> ${upstream} — open the n8n editor via the proxy URL`);
+    return handle;
+}
+function serveClient(res) {
+    res.writeHead(200, { "content-type": "application/javascript; charset=utf-8", "cache-control": "no-store" });
+    res.end(CLIENT_SCRIPT);
+}
+function serveEvents(req, res, clients) {
+    res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store", connection: "keep-alive" });
+    res.write(": connected\n\n");
+    clients.add(res);
+    req.on("close", () => clients.delete(res));
+}
+function proxyHttp(req, res, { target, upstreamPort, secure }, log) {
+    const headers = { ...req.headers, host: target.host };
+    // Force an uncompressed body so HTML can be string-injected without decoding.
+    delete headers["accept-encoding"];
+    const request = secure ? https.request : http.request;
+    const upstreamReq = request({ hostname: target.hostname, port: upstreamPort, method: req.method, path: req.url, headers }, (upstreamRes) => {
+        // HEAD carries no body to inject into — pass it straight through.
+        const isHtml = req.method !== "HEAD" && /text\/html/i.test(String(upstreamRes.headers["content-type"] ?? ""));
+        if (!isHtml) {
+            res.writeHead(upstreamRes.statusCode ?? 502, upstreamRes.headers);
+            upstreamRes.pipe(res);
+            return;
+        }
+        const chunks = [];
+        upstreamRes.on("data", (c) => chunks.push(c));
+        upstreamRes.on("end", () => {
+            const body = Buffer.from(injectClient(Buffer.concat(chunks).toString("utf8")), "utf8");
+            const outHeaders = { ...upstreamRes.headers };
+            delete outHeaders["content-length"];
+            delete outHeaders["transfer-encoding"];
+            res.writeHead(upstreamRes.statusCode ?? 200, { ...outHeaders, "content-length": String(body.byteLength) });
+            res.end(body);
+        });
+    });
+    upstreamReq.on("error", (err) => {
+        log.error(`browser-reload proxy: upstream request failed (${err.message})`);
+        if (!res.headersSent)
+            res.writeHead(502, { "content-type": "text/plain" });
+        res.end("decanter proxy: upstream error");
+    });
+    req.pipe(upstreamReq);
+}
+/** Inject the client bootstrapper right before </body> (append if there is none). */
+function injectClient(html) {
+    const idx = html.toLowerCase().lastIndexOf("</body>");
+    return idx === -1 ? html + INJECT_TAG : html.slice(0, idx) + INJECT_TAG + html.slice(idx);
+}
+/** Pipe a raw WebSocket/Upgrade through to the upstream (n8n's native /rest/push). */
+function proxyUpgrade(req, clientSocket, head, { target, upstreamPort, secure }, log) {
+    const onConnect = () => {
+        const lines = [`${req.method} ${req.url} HTTP/1.1`];
+        const headers = { ...req.headers, host: target.host };
+        for (const [key, value] of Object.entries(headers)) {
+            if (value === undefined)
+                continue;
+            for (const v of Array.isArray(value) ? value : [value])
+                lines.push(`${key}: ${v}`);
+        }
+        upstreamSocket.write(lines.join("\r\n") + "\r\n\r\n");
+        if (head?.length)
+            upstreamSocket.write(head);
+        upstreamSocket.pipe(clientSocket);
+        clientSocket.pipe(upstreamSocket);
+    };
+    const upstreamSocket = secure
+        ? tls.connect({ host: target.hostname, port: upstreamPort, servername: target.hostname }, onConnect)
+        : net.connect({ host: target.hostname, port: upstreamPort }, onConnect);
+    const onError = (err) => {
+        log.error(`browser-reload proxy: websocket upstream failed (${err.message})`);
+        clientSocket.destroy();
+        upstreamSocket.destroy();
+    };
+    upstreamSocket.on("error", onError);
+    clientSocket.on("error", onError);
+}

package/dist/lib/pull.mjs

@@ -0,0 +1,148 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { compileTs } from "./compile.mjs";
+import { commitWorkflowDir } from "./git.mjs";
+import { findWorkflowDir, readState, renameNodeFilePair, writeState } from "./state.mjs";
+import { CODE_DIR, FILE_PLACEHOLDER_PREFIX, isJsCodeNode, kebabCase, sanitizeFilename, sha256, splitMarker, stableWorkflowJson, workflowStructureHash, } from "./util.mjs";
+function writeIfChanged(file, content) {
+    if (existsSync(file) && readFileSync(file, "utf8") === content)
+        return false;
+    writeFileSync(file, content);
+    return true;
+}
+/** Locate/create the workflow folder, renaming it if the workflow was renamed. */
+function ensureWorkflowDir(root, wf, log) {
+    const wanted = sanitizeFilename(wf.name);
+    const existing = findWorkflowDir(root, wf.id, log);
+    if (!existing) {
+        const dir = path.join(root, wanted);
+        mkdirSync(dir, { recursive: true });
+        return { dir };
+    }
+    if (path.basename(existing) !== wanted) {
+        const target = path.join(path.dirname(existing), wanted);
+        if (existsSync(target)) {
+            log.warn(`workflow renamed to "${wf.name}" but ${target} already exists — keeping ${existing}`);
+            return { dir: existing };
+        }
+        renameSync(existing, target);
+        log.info(`renamed folder ${path.basename(existing)}/ -> ${wanted}/`);
+        return { dir: target, previousDir: existing };
+    }
+    return { dir: existing };
+}
+/**
+ * Pick/refresh the file name for a node: kebab-case under code/, renaming
+ * existing files on node rename (which also migrates pre-code/ layouts).
+ * Collision handling is per-pull (`usedNames`), deterministic across nodes
+ * that kebab to the same base.
+ */
+function resolveNodeFile(dir, nodeState, node, ext, usedNames, log) {
+    let base = kebabCase(node.name);
+    if (usedNames.has(base))
+        base = `${base}-${node.id.slice(0, 8)}`;
+    usedNames.add(base);
+    const wanted = `${CODE_DIR}/${base}${ext}`;
+    mkdirSync(path.join(dir, CODE_DIR), { recursive: true });
+    const current = nodeState.file;
+    if (current && current !== wanted)
+        renameNodeFilePair(dir, current, base, ext, log);
+    return { file: wanted, base };
+}
+export async function pullWorkflow(api, root, id, { commitOnPull = false } = {}, log) {
+    const wf = await api.getWorkflow(id);
+    const { dir, previousDir } = ensureWorkflowDir(root, wf, log);
+    const state = readState(dir) ?? { workflowId: wf.id, nodes: {} };
+    state.workflowId = wf.id;
+    state.nodes ??= {};
+    const usedNames = new Set();
+    const placeholders = new Map(); // node id -> file name
+    for (const node of wf.nodes) {
+        if (!isJsCodeNode(node))
+            continue;
+        const nodeState = state.nodes[node.id] ?? {};
+        const remote = node.parameters.jsCode;
+        const { body: remoteBody, markerHash } = splitMarker(remote);
+        const remoteHash = sha256(remoteBody);
+        const tsManaged = markerHash !== null;
+        const { file, base } = resolveNodeFile(dir, nodeState, node, tsManaged ? ".ts" : ".js", usedNames, log);
+        const filePath = path.join(dir, file);
+        const remoteRel = `${CODE_DIR}/${base}.remote.js`;
+        const remoteJsFile = path.join(dir, remoteRel);
+        if (tsManaged) {
+            if (!existsSync(filePath)) {
+                writeFileSync(remoteJsFile, remoteBody);
+                log.warn(`${wf.name} / ${node.name}: TS-managed on remote but no local ${file} — compiled code saved to ${remoteRel}`);
+            }
+            else {
+                const compiled = await compileTs(filePath, log);
+                const localHash = sha256(compiled);
+                if (localHash === remoteHash) {
+                    if (existsSync(remoteJsFile)) {
+                        rmSync(remoteJsFile);
+                        log.info(`${node.name}: in sync, removed stale ${remoteRel}`);
+                    }
+                }
+                else if (localHash === nodeState.lastPushedHash) {
+                    writeFileSync(remoteJsFile, remoteBody);
+                    log.warn(`${wf.name} / ${node.name}: edited in the n8n UI since last push — remote code saved to ${remoteRel}; port it into ${file} manually`);
+                }
+                else if (remoteHash === nodeState.lastPushedHash) {
+                    log.info(`${node.name}: local ${file} modified, not yet pushed`);
+                }
+                else {
+                    writeFileSync(remoteJsFile, remoteBody);
+                    log.warn(`${wf.name} / ${node.name}: CONFLICT — both ${file} and the remote code changed since last sync. Remote saved to ${remoteRel}; reconcile manually before pushing`);
+                }
+            }
+        }
+        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`;
+            writeFileSync(remoteJsFile, remoteBody);
+            log.warn(`${wf.name} / ${node.name}: local ${tsFile} exists but remote code has no @ts-n8n marker (not pushed from TS yet?) — remote saved to ${remoteRel}`);
+            placeholders.set(node.id, tsFile);
+            state.nodes[node.id] = { ...nodeState, file: tsFile, lastPushedHash: remoteHash };
+            continue;
+        }
+        else {
+            if (writeIfChanged(filePath, remoteBody))
+                log.info(`wrote ${path.basename(dir)}/${file}`);
+        }
+        placeholders.set(node.id, file);
+        state.nodes[node.id] = { ...nodeState, file, lastPushedHash: remoteHash };
+    }
+    // Drop state for nodes that no longer exist remotely (files stay; git is the safety net).
+    const liveIds = new Set(wf.nodes.map((n) => n.id));
+    for (const nodeId of Object.keys(state.nodes)) {
+        if (!liveIds.has(nodeId)) {
+            log.warn(`node ${nodeId} ("${state.nodes[nodeId].file}") no longer exists remotely — removing from state, delete the file manually if unwanted`);
+            delete state.nodes[nodeId];
+        }
+    }
+    const wfOut = structuredClone(wf);
+    // Keep workflow.json to the workflow itself: n8n 2.x GET responses embed a
+    // full server-side copy of the *published* version (`activeVersion`, code
+    // included) and sharing metadata (`shared`) — derived data that would
+    // duplicate every node's source in git and churn on each publish. Neither
+    // field is pushable (sanitizeForPut whitelists), so dropping them loses
+    // nothing.
+    delete wfOut.activeVersion;
+    delete wfOut.shared;
+    for (const node of wfOut.nodes) {
+        const file = placeholders.get(node.id);
+        if (file)
+            node.parameters.jsCode = FILE_PLACEHOLDER_PREFIX + file;
+    }
+    if (writeIfChanged(path.join(dir, "workflow.json"), stableWorkflowJson(wfOut))) {
+        log.info(`wrote ${path.basename(dir)}/workflow.json`);
+    }
+    state.lastPulledWorkflowHash = workflowStructureHash(wf);
+    writeState(dir, state);
+    if (commitOnPull) {
+        const extras = previousDir ? [path.relative(dir, previousDir)] : [];
+        await commitWorkflowDir(dir, `decanter: pulled "${wf.name}" (${id})`, log, extras);
+    }
+    return { dir, name: wf.name };
+}

package/dist/lib/push.mjs

@@ -0,0 +1,136 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { compileTs } from "./compile.mjs";
+import { commitWorkflowDir } from "./git.mjs";
+import { notifyPushed } from "./proxy.mjs";
+import { findWorkflowDir, readState, writeState } from "./state.mjs";
+import { isJsCodeNode, placeholderFile, publicationState, sanitizeForPut, sha256, splitMarker, withMarker, workflowStructureHash, } from "./util.mjs";
+import { validateNodeFile, validateWorkflowDir } from "./validate.mjs";
+/** Layout-compliance gate: warnings pass through, errors abort the push. */
+function assertCompliant({ errors, warnings }, log, what) {
+    for (const w of warnings)
+        log.warn(w);
+    if (errors.length === 0)
+        return;
+    for (const e of errors)
+        log.error(e);
+    throw new Error(`${what} does not comply with the decanter layout (${errors.length} problem${errors.length === 1 ? "" : "s"}) — fix the issues above, see also: n8n-decanter check`);
+}
+/** Turn a node source file into the jsCode payload (+ hash of the marker-less body). */
+export async function buildNodeCode(dir, file, log) {
+    const filePath = path.join(dir, file);
+    if (!existsSync(filePath))
+        throw new Error(`referenced node file missing: ${filePath}`);
+    if (file.endsWith(".ts")) {
+        return withMarker(await compileTs(filePath, log));
+    }
+    const jsCode = readFileSync(filePath, "utf8");
+    return { jsCode, hash: sha256(jsCode) };
+}
+/**
+ * Compare the freshly fetched remote workflow against the last-synced hashes.
+ * Returns human-readable problems; empty array means safe to push.
+ * `onlyNodeIds` restricts the per-node check (watch mode).
+ */
+export function driftProblems(remote, state, onlyNodeIds = null) {
+    const problems = [];
+    for (const node of remote.nodes) {
+        if (!isJsCodeNode(node))
+            continue;
+        if (onlyNodeIds && !onlyNodeIds.has(node.id))
+            continue;
+        const nodeState = state.nodes[node.id];
+        const { body } = splitMarker(node.parameters.jsCode);
+        if (!nodeState) {
+            problems.push(`node "${node.name}" exists remotely but is unknown locally`);
+        }
+        else if (nodeState.lastPushedHash !== sha256(body)) {
+            problems.push(`node "${node.name}": remote code changed since last sync`);
+        }
+    }
+    if (!onlyNodeIds && state.lastPulledWorkflowHash &&
+        workflowStructureHash(remote) !== state.lastPulledWorkflowHash) {
+        problems.push("workflow structure changed remotely since last sync (nodes/connections/settings)");
+    }
+    return problems;
+}
+function assertNoDrift(problems, force, log) {
+    if (problems.length === 0)
+        return;
+    for (const p of problems)
+        log[force ? "warn" : "error"](p);
+    if (!force) {
+        throw new Error("remote changed since last sync — pull first (or repeat with --force to overwrite)");
+    }
+    log.warn("--force: overwriting remote changes");
+}
+/** Publication suffix for push result lines (see publicationState in util). */
+function liveNote(wf) {
+    const state = publicationState(wf);
+    if (!state)
+        return "";
+    return state === "published" ? " — published: code is live now" : " — unpublished: draft only";
+}
+/** Update per-node + structure hashes from the workflow the server confirmed. */
+function recordSync(state, confirmed) {
+    for (const node of confirmed.nodes) {
+        if (!isJsCodeNode(node))
+            continue;
+        const nodeState = state.nodes[node.id];
+        if (nodeState)
+            nodeState.lastPushedHash = sha256(splitMarker(node.parameters.jsCode).body);
+    }
+    state.lastPulledWorkflowHash = workflowStructureHash(confirmed);
+}
+export async function pushWorkflow(api, root, id, { force = false, commitOnPush = false } = {}, log) {
+    const dir = findWorkflowDir(root, id, log);
+    if (!dir)
+        throw new Error(`workflow ${id} not found under ${root} — pull it first`);
+    assertCompliant(validateWorkflowDir(dir), log, `"${path.basename(dir)}"`);
+    const state = readState(dir);
+    const wf = JSON.parse(readFileSync(path.join(dir, "workflow.json"), "utf8"));
+    for (const node of wf.nodes) {
+        if (!isJsCodeNode(node))
+            continue;
+        const file = placeholderFile(node);
+        if (file === null)
+            continue;
+        node.parameters.jsCode = (await buildNodeCode(dir, file, log)).jsCode;
+        state.nodes[node.id] = { ...state.nodes[node.id], file };
+    }
+    const remote = await api.getWorkflow(id);
+    assertNoDrift(driftProblems(remote, state, null), force, log);
+    const confirmed = await api.updateWorkflow(id, sanitizeForPut(wf));
+    recordSync(state, confirmed ?? wf);
+    writeState(dir, state);
+    log.ok(`pushed "${wf.name}" (${id})${liveNote(confirmed ?? remote)}`);
+    notifyPushed(id);
+    if (commitOnPush)
+        await commitWorkflowDir(dir, `decanter: pushed "${wf.name}" (${id})`, log);
+    return { dir, name: wf.name };
+}
+/** Push a single node's code (watch mode): GET, swap jsCode, PUT. */
+export async function pushSingleNode(api, dir, nodeId, { force = false, commitOnPush = false } = {}, log) {
+    const state = readState(dir);
+    if (!state)
+        throw new Error(`missing .decanter.json in ${dir} — pull first`);
+    const nodeState = state.nodes[nodeId];
+    if (!nodeState)
+        throw new Error(`node ${nodeId} has no entry in ${dir}/.decanter.json — pull first`);
+    assertCompliant(validateNodeFile(dir, nodeState.file), log, nodeState.file);
+    const { jsCode } = await buildNodeCode(dir, nodeState.file, log);
+    const remote = await api.getWorkflow(state.workflowId);
+    assertNoDrift(driftProblems(remote, state, new Set([nodeId])), force, log);
+    const node = remote.nodes.find((n) => n.id === nodeId);
+    if (!node)
+        throw new Error(`node ${nodeId} no longer exists in remote workflow ${state.workflowId}`);
+    node.parameters.jsCode = jsCode;
+    const confirmed = await api.updateWorkflow(state.workflowId, sanitizeForPut(remote));
+    recordSync(state, confirmed ?? remote);
+    writeState(dir, state);
+    log.ok(`pushed node "${node.name}" -> workflow "${remote.name}"${liveNote(confirmed ?? remote)}`);
+    notifyPushed(state.workflowId);
+    if (commitOnPush) {
+        await commitWorkflowDir(dir, `decanter: pushed "${remote.name}" / node "${node.name}" (${state.workflowId})`, log);
+    }
+}

package/dist/lib/rename.mjs

@@ -0,0 +1,156 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { findWorkflowDir, readState, renameNodeFilePair, writeState } from "./state.mjs";
+import { CODE_DIR, FILE_PLACEHOLDER_PREFIX, forEachConnectionTarget, isJsCodeNode, kebabCase, placeholderFile, renameNodeRefs, stableWorkflowJson } from "./util.mjs";
+import { validateWorkflowDir } from "./validate.mjs";
+function loadWorkflow(root, id, log) {
+    const dir = findWorkflowDir(root, id, log);
+    if (!dir)
+        throw new Error(`workflow ${id} not found under ${root} — pull it first`);
+    const wfFile = path.join(dir, "workflow.json");
+    if (!existsSync(wfFile))
+        throw new Error(`missing workflow.json in ${dir} — pull first`);
+    try {
+        return { dir, wf: JSON.parse(readFileSync(wfFile, "utf8")) };
+    }
+    catch (err) {
+        throw new Error(`${wfFile}: invalid JSON (${err.message})`);
+    }
+}
+/** Rename `old` -> `new` in connection keys and every `{ node: … }` target. */
+function renameInConnections(connections, oldName, newName) {
+    let changes = 0;
+    forEachConnectionTarget(connections, (target) => {
+        if (target.node === oldName) {
+            target.node = newName;
+            changes++;
+        }
+    });
+    if (Object.hasOwn(connections, oldName)) {
+        connections[newName] = connections[oldName];
+        delete connections[oldName];
+        changes++;
+    }
+    return changes;
+}
+/** Rewrite `$('old')` in every string parameter of every node (skips the jsCode placeholder). */
+function renameInParameters(value, oldName, newName, skipKey) {
+    if (typeof value === "string") {
+        const rewritten = renameNodeRefs(value, oldName, newName);
+        return { value: rewritten, changes: rewritten === value ? 0 : 1 };
+    }
+    let changes = 0;
+    if (Array.isArray(value)) {
+        const out = value.map((v) => {
+            const r = renameInParameters(v, oldName, newName);
+            changes += r.changes;
+            return r.value;
+        });
+        return { value: out, changes };
+    }
+    if (value && typeof value === "object") {
+        for (const [k, v] of Object.entries(value)) {
+            if (k === skipKey)
+                continue;
+            const r = renameInParameters(v, oldName, newName);
+            changes += r.changes;
+            value[k] = r.value;
+        }
+    }
+    return { value, changes };
+}
+/**
+ * Move the renamed node's source file to its new kebab-case name (plus
+ * .remote.js sibling). Collision handling is against the disk (unlike pull's
+ * per-pull name set): an occupied target falls back to the `-<id8>` suffix,
+ * a double collision throws for the user to resolve.
+ */
+function renameNodeFile(dir, node, newName, log) {
+    if (!isJsCodeNode(node))
+        return;
+    const current = placeholderFile(node);
+    if (current === null)
+        return;
+    const ext = path.extname(current);
+    let base = kebabCase(newName);
+    if (`${CODE_DIR}/${base}${ext}` === current)
+        return;
+    if (existsSync(path.join(dir, `${CODE_DIR}/${base}${ext}`))) {
+        base = `${base}-${node.id.slice(0, 8)}`;
+        if (existsSync(path.join(dir, `${CODE_DIR}/${base}${ext}`))) {
+            throw new Error(`cannot rename ${current}: both kebab-case targets exist (${CODE_DIR}/${base}${ext})`);
+        }
+    }
+    const wanted = renameNodeFilePair(dir, current, base, ext, log);
+    node.parameters.jsCode = FILE_PLACEHOLDER_PREFIX + wanted;
+    const state = readState(dir);
+    if (state?.nodes[node.id]) {
+        state.nodes[node.id].file = wanted;
+        writeState(dir, state);
+    }
+}
+/**
+ * Atomically rename a node everywhere the old name is load-bearing:
+ * node.name, connection keys and targets, literal $('…') references in every
+ * code file and expression parameter, the source filename, its //@file:
+ * placeholder, and the .decanter.json entry. Offline; push propagates.
+ */
+export function renameNode(root, id, oldName, newName, log) {
+    newName = newName.trim();
+    if (!newName)
+        throw new Error("new node name must not be empty");
+    if (newName === oldName)
+        throw new Error(`node is already named "${oldName}"`);
+    const { dir, wf } = loadWorkflow(root, id, log);
+    const node = wf.nodes.find((n) => n.name === oldName);
+    if (!node)
+        throw new Error(`no node named "${oldName}" in "${wf.name}" (nodes: ${wf.nodes.map((n) => `"${n.name}"`).join(", ")})`);
+    if (wf.nodes.some((n) => n.name === newName))
+        throw new Error(`a node named "${newName}" already exists in "${wf.name}"`);
+    node.name = newName;
+    const connectionChanges = renameInConnections(wf.connections ?? {}, oldName, newName);
+    let paramChanges = 0;
+    for (const n of wf.nodes) {
+        paramChanges += renameInParameters(n.parameters, oldName, newName, "jsCode").changes;
+    }
+    // Rewrite $('…') in every node source file (referenced ones; .remote.js
+    // snapshots mirror remote code and stay untouched).
+    let fileChanges = 0;
+    for (const n of wf.nodes) {
+        if (!isJsCodeNode(n))
+            continue;
+        const file = placeholderFile(n);
+        if (file === null)
+            continue;
+        const filePath = path.join(dir, file);
+        if (!existsSync(filePath))
+            continue;
+        const source = readFileSync(filePath, "utf8");
+        const rewritten = renameNodeRefs(source, oldName, newName);
+        if (rewritten !== source) {
+            writeFileSync(filePath, rewritten);
+            fileChanges++;
+            log.info(`updated $('${oldName}') references in ${file}`);
+        }
+    }
+    renameNodeFile(dir, node, newName, log);
+    writeFileSync(path.join(dir, "workflow.json"), stableWorkflowJson(wf));
+    log.info(`renamed node "${oldName}" -> "${newName}" (${connectionChanges} connection ref${connectionChanges === 1 ? "" : "s"}, ${paramChanges} parameter ref${paramChanges === 1 ? "" : "s"}, ${fileChanges} code file${fileChanges === 1 ? "" : "s"}) — push to propagate`);
+    const { errors } = validateWorkflowDir(dir);
+    if (errors.length > 0) {
+        throw new Error(`rename left the workflow non-compliant — files were written, inspect (git diff) and fix:\n${errors.map((e) => `  ${e}`).join("\n")}`);
+    }
+}
+/** Rename the workflow itself. The folder is cosmetic and follows on the next pull. */
+export function renameWorkflow(root, id, newName, log) {
+    newName = newName.trim();
+    if (!newName)
+        throw new Error("new workflow name must not be empty");
+    const { dir, wf } = loadWorkflow(root, id, log);
+    if (wf.name === newName)
+        throw new Error(`workflow is already named "${newName}"`);
+    const oldName = wf.name;
+    wf.name = newName;
+    writeFileSync(path.join(dir, "workflow.json"), stableWorkflowJson(wf));
+    log.info(`renamed workflow "${oldName}" -> "${newName}" — push to propagate; the folder follows on the next pull`);
+}