n8n-decanter 0.3.0

package/dist/lib/util.mjs

@@ -0,0 +1,201 @@
+import { createHash } from "node:crypto";
+export const CODE_NODE_TYPE = "n8n-nodes-base.code";
+export const FILE_PLACEHOLDER_PREFIX = "//@file:";
+/** Subdir inside a workflow folder that holds the node source files. */
+export const CODE_DIR = "code";
+const MARKER_PREFIX = "// @ts-n8n ";
+/** True for Code nodes whose source is JavaScript (the only kind we extract). */
+export function isJsCodeNode(node) {
+    return (node?.type === CODE_NODE_TYPE &&
+        typeof node.parameters?.jsCode === "string" &&
+        (node.parameters.language === undefined || node.parameters.language === "javaScript"));
+}
+export function sha256(text) {
+    return "sha256:" + createHash("sha256").update(text, "utf8").digest("hex");
+}
+/**
+ * Split trailing `// @ts-n8n sha256:<hex>` marker off a jsCode string.
+ * The marker must be the last non-blank line. `body` keeps everything up to
+ * the marker line byte-exactly (including the newline before it), so
+ * hash(body) matches the hash computed at push time.
+ */
+export function splitMarker(code) {
+    const m = code.match(/(?:^|\n)(\/\/ @ts-n8n (sha256:[0-9a-f]{64}))[ \t]*\n?[ \t\n]*$/);
+    if (!m)
+        return { body: code, marker: null, markerHash: null };
+    const start = m.index + (m[0].startsWith("\n") ? 1 : 0);
+    return { body: code.slice(0, start), marker: m[1], markerHash: m[2] };
+}
+/** Build the jsCode payload for a TS-managed node from compiled JS. */
+export function withMarker(compiledJs) {
+    const body = compiledJs.endsWith("\n") ? compiledJs : compiledJs + "\n";
+    return { jsCode: body + MARKER_PREFIX + sha256(body), hash: sha256(body) };
+}
+/** File a `//@file:` placeholder points at, or null for inline code. */
+export function placeholderFile(node) {
+    const jsCode = node.parameters.jsCode;
+    if (!jsCode.startsWith(FILE_PLACEHOLDER_PREFIX))
+        return null;
+    return jsCode.slice(FILE_PLACEHOLDER_PREFIX.length).trim();
+}
+/**
+ * Walk every `{ node: … }` target in a connections object (the four-level
+ * source → type → group → target nesting), calling `cb` for each target
+ * object. Non-object levels are skipped defensively.
+ */
+export function forEachConnectionTarget(connections, cb) {
+    for (const [source, byType] of Object.entries(connections)) {
+        if (!byType || typeof byType !== "object")
+            continue;
+        for (const [type, groups] of Object.entries(byType)) {
+            if (!Array.isArray(groups))
+                continue;
+            for (const group of groups) {
+                if (!Array.isArray(group))
+                    continue;
+                for (const target of group) {
+                    if (target && typeof target === "object")
+                        cb(target, source, type);
+                }
+            }
+        }
+    }
+}
+/** Sanitize a workflow/node name for use as a file or folder name. */
+export function sanitizeFilename(name) {
+    const cleaned = name
+        .replace(/[/\\:*?"<>|]/g, "-")
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\x00-\x1f]/g, "")
+        .trim()
+        .replace(/\.+$/, "");
+    return cleaned || "unnamed";
+}
+/**
+ * Literal single-argument `$('Name')` / `$("Name")` / `$(`Name`)` calls.
+ * Heuristic on purpose (no parse): non-literal args like `$(var)`, multi-arg
+ * calls, template literals with `${…}`, and the legacy `$node["Name"]` form
+ * don't match and are left alone.
+ */
+const NODE_REF_RE = /\$\(\s*(['"`])((?:\\.|(?!\1)[^\\\n])*)\1\s*\)/g;
+const unescapeRef = (raw) => raw.replace(/\\(.)/g, "$1");
+/** Distinct node names referenced via literal `$('…')` in a piece of source. */
+export function findNodeRefs(source) {
+    const names = new Set();
+    for (const m of source.matchAll(NODE_REF_RE)) {
+        const name = unescapeRef(m[2]);
+        if (!name.includes("${"))
+            names.add(name);
+    }
+    return [...names];
+}
+/** Rewrite literal `$('old')` references to the new name, keeping each call's quote style. */
+export function renameNodeRefs(source, oldName, newName) {
+    return source.replace(NODE_REF_RE, (whole, quote, raw) => {
+        if (unescapeRef(raw) !== oldName)
+            return whole;
+        const escaped = newName.replace(/\\/g, "\\\\").replaceAll(quote, `\\${quote}`);
+        return `$(${quote}${escaped}${quote})`;
+    });
+}
+/** Kebab-case node-file name from a node name ("Parse Order" -> "parse-order"). */
+export function kebabCase(name) {
+    const kebab = sanitizeFilename(name)
+        .replace(/([\p{Ll}\p{N}])(\p{Lu})/gu, "$1-$2")
+        .replace(/(\p{Lu}+)(\p{Lu}\p{Ll})/gu, "$1-$2")
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, "-")
+        .replace(/^-+|-+$/g, "");
+    return kebab || "unnamed";
+}
+const TOP_LEVEL_ORDER = [
+    "id", "name", "active", "isArchived", "createdAt", "updatedAt",
+    "nodes", "connections", "settings", "staticData", "meta", "pinData",
+    "tags", "versionId",
+];
+const NODE_ORDER = [
+    "id", "name", "type", "typeVersion", "position", "disabled",
+    "parameters", "credentials",
+];
+function sortKeys(obj, preferred = []) {
+    const keys = Object.keys(obj);
+    keys.sort((a, b) => {
+        const ia = preferred.indexOf(a);
+        const ib = preferred.indexOf(b);
+        if (ia !== -1 || ib !== -1) {
+            if (ia === -1)
+                return 1;
+            if (ib === -1)
+                return -1;
+            return ia - ib;
+        }
+        return a < b ? -1 : a > b ? 1 : 0;
+    });
+    return keys;
+}
+function orderDeep(value, preferred = []) {
+    if (Array.isArray(value))
+        return value.map((v) => orderDeep(v));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const k of sortKeys(value, preferred))
+            out[k] = orderDeep(value[k]);
+        return out;
+    }
+    return value;
+}
+/** Deterministic pretty JSON for a workflow: stable key order, clean diffs. */
+export function stableWorkflowJson(wf) {
+    const ordered = {};
+    for (const k of sortKeys(wf, TOP_LEVEL_ORDER)) {
+        ordered[k] = k === "nodes"
+            ? wf.nodes.map((n) => orderDeep(n, NODE_ORDER))
+            : orderDeep(wf[k]);
+    }
+    return JSON.stringify(ordered, null, 2) + "\n";
+}
+const SETTINGS_WHITELIST = [
+    "saveExecutionProgress", "saveManualExecutions", "saveDataErrorExecution",
+    "saveDataSuccessExecution", "executionTimeout", "timezone", "errorWorkflow",
+];
+/** Reduce a workflow to the fields the PUT endpoint accepts. */
+export function sanitizeForPut(wf) {
+    const settings = {};
+    for (const k of SETTINGS_WHITELIST) {
+        if (wf.settings && wf.settings[k] !== undefined)
+            settings[k] = wf.settings[k];
+    }
+    const out = {
+        name: wf.name,
+        nodes: wf.nodes,
+        connections: wf.connections,
+        settings,
+    };
+    if (wf.staticData !== undefined && wf.staticData !== null)
+        out.staticData = wf.staticData;
+    return out;
+}
+/**
+ * Publication state from an API workflow response. n8n's public API
+ * auto-publishes updates to a *published* workflow (publishIfActive is
+ * hardcoded server-side), so pushes there go live immediately; on an
+ * unpublished workflow they only update the draft. Undefined when the
+ * server doesn't report `active`.
+ */
+export function publicationState(wf) {
+    if (typeof wf?.active !== "boolean")
+        return undefined;
+    return wf.active ? "published" : "unpublished";
+}
+/**
+ * Hash of the sanitized, code-stripped workflow — detects structural edits
+ * (nodes added/moved/reconnected, settings changed) independent of code edits.
+ */
+export function workflowStructureHash(wf) {
+    const clone = structuredClone(sanitizeForPut(wf));
+    for (const node of clone.nodes ?? []) {
+        if (isJsCodeNode(node))
+            node.parameters.jsCode = "";
+    }
+    return sha256(JSON.stringify(orderDeep(clone)));
+}

package/dist/lib/validate.mjs

@@ -0,0 +1,225 @@
+import { execFile as execFileCb } from "node:child_process";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { checkNodeImports, findBundleContext, scanNodeImports } from "./compile.mjs";
+import { readState } from "./state.mjs";
+import { CODE_DIR, FILE_PLACEHOLDER_PREFIX, findNodeRefs, forEachConnectionTarget, isJsCodeNode, placeholderFile, splitMarker } from "./util.mjs";
+const execFile = promisify(execFileCb);
+/** Compliance checks for one referenced node file. */
+export function validateNodeFile(dir, file, label = file) {
+    const errors = [];
+    const warnings = [];
+    if (file.endsWith(".remote.js")) {
+        errors.push(`${label}: placeholder references the conflict artifact ${file} — resolve it into the real node file instead`);
+        return { errors, warnings };
+    }
+    if (!/\.(ts|js)$/.test(file)) {
+        errors.push(`${label}: referenced file ${file} must be .js or .ts`);
+        return { errors, warnings };
+    }
+    if (!file.startsWith(CODE_DIR + "/") || file.slice(CODE_DIR.length + 1).includes("/")) {
+        errors.push(`${label}: node file ${file} sits outside ${CODE_DIR}/ — node sources live directly in the ${CODE_DIR}/ subdir (a fresh pull migrates old layouts)`);
+    }
+    const filePath = path.join(dir, file);
+    if (!existsSync(filePath)) {
+        errors.push(`${label}: referenced file ${file} is missing`);
+        return { errors, warnings };
+    }
+    if (file.endsWith(".js")) {
+        const jsSource = readFileSync(filePath, "utf8");
+        if (splitMarker(jsSource).marker) {
+            errors.push(`${label}: ${file} ends with an @ts-n8n marker — that line is reserved for compiled TS pushes and would make the node look TS-managed on the next pull; remove it`);
+        }
+        // .js is pushed verbatim — an import would reach n8n unbundled and fail
+        // at runtime (imports are a .ts feature, bundled on push; plans/14)
+        if (scanNodeImports(jsSource).specifiers.length > 0) {
+            errors.push(`${label}: ${file} has an import — .js nodes run verbatim in n8n, where import/require fail; convert the node to .ts (imports are bundled on push) or inline the code`);
+        }
+    }
+    if (file.endsWith(".ts")) {
+        // bundling rules (plans/14), offline lexical subset: same checker the
+        // compiler runs, so check and push can't disagree
+        const { specifiers, body } = scanNodeImports(readFileSync(filePath, "utf8"));
+        if (specifiers.length > 0) {
+            for (const p of checkNodeImports(filePath, specifiers, findBundleContext(dir))) {
+                errors.push(`${label}: ${p}`);
+            }
+        }
+        if (/^import[ \t]/m.test(body)) {
+            warnings.push(`${label}: ${file} has an import below the first statement — only imports at the top of the file are bundled; the push compile will fail on it`);
+        }
+    }
+    const remoteSibling = file.replace(/\.(ts|js)$/, ".remote.js");
+    if (existsSync(path.join(dir, remoteSibling))) {
+        warnings.push(`${label}: unresolved remote copy ${remoteSibling} — its remote edits will be overwritten on push; port them, then delete the file`);
+    }
+    return { errors, warnings };
+}
+/** Dangling literal `$('…')` references in one string of source/expression text. */
+function danglingRefs(text, nodeNames) {
+    return findNodeRefs(text).filter((name) => !nodeNames.has(name));
+}
+/** Every string inside a node's parameters, skipping the jsCode placeholder. */
+function parameterStrings(value, skipKey) {
+    if (typeof value === "string")
+        return [value];
+    if (Array.isArray(value))
+        return value.flatMap((v) => parameterStrings(v));
+    if (value && typeof value === "object") {
+        return Object.entries(value).flatMap(([k, v]) => (k === skipKey ? [] : parameterStrings(v)));
+    }
+    return [];
+}
+/**
+ * Validate a pulled workflow folder against the decanter layout:
+ * every Code node behind a //@file: placeholder, referenced files present and
+ * well-formed, no marker inside .js files, unique node names/ids, connection
+ * integrity, no orphan code files, no dangling literal $('…') references;
+ * warn on *.remote.js / workflow.remote.json leftovers.
+ */
+export function validateWorkflowDir(dir) {
+    const errors = [];
+    const warnings = [];
+    try {
+        if (!readState(dir))
+            errors.push("missing .decanter.json — pull first");
+    }
+    catch (err) {
+        errors.push(err.message); // "corrupt .decanter.json (…)"
+    }
+    const wfFile = path.join(dir, "workflow.json");
+    if (!existsSync(wfFile)) {
+        errors.push("missing workflow.json — pull first");
+        return { errors, warnings };
+    }
+    let wf;
+    try {
+        wf = JSON.parse(readFileSync(wfFile, "utf8"));
+    }
+    catch (err) {
+        errors.push(`workflow.json: invalid JSON (${err.message})`);
+        return { errors, warnings };
+    }
+    const nodes = wf.nodes ?? [];
+    const nodeNames = new Set(nodes.map((n) => n.name));
+    // Uniqueness: duplicate names corrupt connections and $('…') resolution,
+    // duplicate ids corrupt the id→file map.
+    for (const key of ["name", "id"]) {
+        const seen = new Set();
+        for (const node of nodes) {
+            const value = node[key];
+            if (seen.has(value))
+                errors.push(`duplicate node ${key} "${value}" — node ${key}s must be unique`);
+            seen.add(value);
+        }
+    }
+    // Connection integrity: every source key and every target must be a real node.
+    const connectionErrors = new Set();
+    for (const source of Object.keys(wf.connections ?? {})) {
+        if (!nodeNames.has(source))
+            connectionErrors.add(`connections: source "${source}" is not a node in this workflow`);
+    }
+    forEachConnectionTarget(wf.connections ?? {}, (target, source, type) => {
+        if (typeof target.node === "string" && !nodeNames.has(target.node)) {
+            connectionErrors.add(`connections: "${source}" (${type}) targets missing node "${target.node}"`);
+        }
+    });
+    errors.push(...connectionErrors);
+    const referencedFiles = new Set();
+    const coveredRemoteFiles = new Set();
+    for (const node of nodes) {
+        if (!isJsCodeNode(node))
+            continue;
+        const file = placeholderFile(node);
+        if (file === null) {
+            errors.push(`node "${node.name}": inline code in workflow.json — node code belongs in its own file behind a ${FILE_PLACEHOLDER_PREFIX} placeholder (a fresh pull extracts it)`);
+            continue;
+        }
+        const result = validateNodeFile(dir, file, `node "${node.name}"`);
+        errors.push(...result.errors);
+        warnings.push(...result.warnings);
+        referencedFiles.add(file);
+        coveredRemoteFiles.add(file.replace(/\.(ts|js)$/, ".remote.js"));
+        // Dangling $('…') in the node's source (marker line can't contain a ref).
+        const filePath = path.join(dir, file);
+        if (existsSync(filePath)) {
+            for (const name of danglingRefs(readFileSync(filePath, "utf8"), nodeNames)) {
+                errors.push(`node "${node.name}": ${file} references $('${name}') — no node by that name`);
+            }
+        }
+    }
+    // Dangling $('…') inside expression parameters of any node (the n8n UI
+    // rewrites these on rename; a dangling one breaks at run time).
+    for (const node of nodes) {
+        const texts = parameterStrings(node.parameters, "jsCode");
+        const dangling = new Set(texts.flatMap((t) => danglingRefs(t, nodeNames)));
+        for (const name of dangling) {
+            errors.push(`node "${node.name}": a parameter references $('${name}') — no node by that name`);
+        }
+    }
+    // Orphans and strays. Only the folder root and code/ are scanned: other
+    // subdirs are reserved for future artifacts (executions/, fixtures/ — see
+    // plans 3 and 7) and must not trip the guard.
+    const codeDir = path.join(dir, CODE_DIR);
+    const entries = readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isFile())
+        .map((e) => e.name);
+    if (existsSync(codeDir)) {
+        entries.push(...readdirSync(codeDir, { withFileTypes: true }).filter((e) => e.isFile()).map((e) => `${CODE_DIR}/${e.name}`));
+    }
+    for (const entry of entries) {
+        if (entry.endsWith(".remote.js")) {
+            if (!coveredRemoteFiles.has(entry)) {
+                warnings.push(`stray remote copy ${entry} — no placeholder references its node; port or delete it`);
+            }
+        }
+        else if (/\.(ts|js)$/.test(entry) && !entry.endsWith(".d.ts") && !referencedFiles.has(entry)) {
+            errors.push(`orphan code file ${entry} — no ${FILE_PLACEHOLDER_PREFIX} placeholder references it; delete it or point a Code node at it`);
+        }
+    }
+    if (existsSync(path.join(dir, "workflow.remote.json"))) {
+        warnings.push("unresolved structural conflict workflow.remote.json — reconcile into workflow.json, then delete it");
+    }
+    return { errors, warnings };
+}
+/**
+ * Run scripts/typecheck.mts against the nearest tsconfig.json at or above
+ * startDir. Missing tsconfig (e.g. an init'ed sync dir without one) is an
+ * info-level skip, not an error. Throws on type errors. `scopeDirs` limits
+ * which files' diagnostics are reported (the whole project still compiles).
+ */
+export async function runTypecheck(startDir, log, scopeDirs) {
+    let dir = path.resolve(startDir);
+    let tsconfigDir = null;
+    for (;;) {
+        if (existsSync(path.join(dir, "tsconfig.json"))) {
+            tsconfigDir = dir;
+            break;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    if (!tsconfigDir) {
+        log.info("no tsconfig.json found — skipping typecheck");
+        return;
+    }
+    // dev runs the .mts sources directly; the published package ships compiled
+    // .mjs (Node won't type-strip under node_modules), so mirror our own extension
+    const ext = import.meta.url.endsWith(".mjs") ? ".mjs" : ".mts";
+    const script = fileURLToPath(new URL(`../scripts/typecheck${ext}`, import.meta.url));
+    // absolute paths: the script resolves its arguments against tsconfigDir's cwd
+    const scopeArgs = (scopeDirs ?? []).map((d) => path.resolve(d));
+    try {
+        await execFile(process.execPath, [script, ...scopeArgs], { cwd: tsconfigDir, encoding: "utf8" });
+        log.ok("typecheck OK");
+    }
+    catch (err) {
+        const e = err;
+        const output = ((e.stdout ?? "") + (e.stderr ?? "")).trim();
+        throw new Error(`typecheck failed:\n${output}`);
+    }
+}