n8n-decanter 0.3.0

package/dist/lib/run.mjs

@@ -0,0 +1,208 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { compileTs } from "./compile.mjs";
+import { nodeFileContextDir } from "./state.mjs";
+import { isJsCodeNode, placeholderFile, splitMarker } from "./util.mjs";
+const AsyncFunction = Object.getPrototypeOf(async function () { }).constructor;
+/**
+ * Locate the node whose //@file: placeholder points at the given file (for
+ * its run mode) plus the workflow's staticData. workflow.json sits next to
+ * the file, or — code/ layout — one level up. `node` is null when there is
+ * no workflow.json or no matching node (a bare file can still be run).
+ */
+function findNodeContext(resolved) {
+    const dir = nodeFileContextDir(resolved, "workflow.json");
+    if (dir === null)
+        return { node: null, staticData: undefined };
+    const wfFile = path.join(dir, "workflow.json");
+    let wf;
+    try {
+        wf = JSON.parse(readFileSync(wfFile, "utf8"));
+    }
+    catch {
+        return { node: null, staticData: undefined };
+    }
+    const ref = path.relative(dir, resolved).split(path.sep).join("/");
+    const node = (wf.nodes ?? []).find((n) => isJsCodeNode(n) && placeholderFile(n) === ref) ?? null;
+    return { node, staticData: wf.staticData };
+}
+/**
+ * The two staticData slices a node can see. Workflow JSON stores them as
+ * `{ global: …, "node:<node name>": … }` (n8n's own key scheme); a fixture's
+ * `staticData.global` / `staticData.node` replaces the matching slice whole.
+ * The returned objects are mutable during the run — like in n8n — but `run`
+ * never persists them (offline by design).
+ */
+function staticDataSlices(raw, nodeName, fixture) {
+    let parsed = raw;
+    if (typeof parsed === "string") {
+        // the API may deliver staticData in its DB-serialized string form
+        try {
+            parsed = JSON.parse(parsed);
+        }
+        catch {
+            parsed = undefined;
+        }
+    }
+    const seed = (parsed && typeof parsed === "object" ? parsed : {});
+    const slice = (v) => (v && typeof v === "object" ? v : {});
+    return {
+        global: slice(fixture.staticData?.global ?? seed.global),
+        node: slice(fixture.staticData?.node ?? (nodeName === undefined ? undefined : seed[`node:${nodeName}`])),
+    };
+}
+/** Load and shape a fixture file; every field is optional. */
+function loadFixture(fixturePath, log) {
+    if (!fixturePath)
+        return {};
+    const resolved = path.resolve(fixturePath);
+    if (!existsSync(resolved))
+        throw new Error(`fixture not found: ${fixturePath}`);
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(resolved, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`fixture is not valid JSON (${err.message})`);
+    }
+    return raw;
+}
+/** Normalize a value into an n8n item ({ json, binary? }). */
+function asItem(value) {
+    if (value && typeof value === "object" && "json" in value)
+        return value;
+    return { json: value ?? {} };
+}
+function makeNodeRef(items) {
+    const list = items.map(asItem);
+    return {
+        all: () => list,
+        first: () => list[0],
+        last: () => list[list.length - 1],
+        item: list[0],
+        itemMatching: (i) => list[i],
+        params: {},
+        context: {},
+        isExecuted: true,
+    };
+}
+/**
+ * Build the globals an n8n Code node sees. `perItem` overrides the each-item
+ * fields ($json, $binary, $itemIndex, $input.item) for "Run Once for Each Item".
+ */
+async function buildGlobals(fixture, log, context = {}) {
+    const staticData = staticDataSlices(context.staticData, context.nodeName, fixture);
+    const input = (fixture.input ?? [{ json: {} }]).map(asItem);
+    const nodes = {};
+    for (const [name, items] of Object.entries(fixture.nodes ?? {})) {
+        nodes[name] = makeNodeRef(items);
+    }
+    const $input = {
+        all: () => input,
+        first: () => input[0],
+        last: () => input[input.length - 1],
+        item: input[0],
+        params: fixture.params ?? {},
+    };
+    const $ = (name) => {
+        if (!nodes[name]) {
+            throw new Error(`node "${name}" has no fixture data — add it under "nodes" in the fixture JSON`);
+        }
+        return nodes[name];
+    };
+    // Luxon is what n8n exposes for DateTime/Duration/Interval. Optional: run
+    // still works for pure-logic nodes when it isn't installed.
+    let DateTime;
+    let Duration;
+    let Interval;
+    try {
+        ({ DateTime, Duration, Interval } = await import("luxon"));
+    }
+    catch {
+        log.warn("luxon not installed — DateTime/$now/$today are unavailable in this run");
+    }
+    return {
+        $input,
+        $,
+        $json: input[0]?.json ?? {},
+        $binary: input[0]?.binary ?? {},
+        // n8n's $env is scoped, not the whole host environment. A fixture's env
+        // always wins; otherwise $env is empty unless --allow-env opts into
+        // inheriting process.env (which can carry N8N_API_KEY and other secrets).
+        $env: fixture.env ?? (context.allowEnv ? { ...process.env } : {}),
+        $itemIndex: 0,
+        $runIndex: 0,
+        $now: DateTime ? DateTime.now() : undefined,
+        $today: DateTime ? DateTime.now().startOf("day") : undefined,
+        DateTime,
+        Duration,
+        Interval,
+        $workflow: fixture.workflow ?? { id: "local", name: "local", active: false },
+        $getWorkflowStaticData: (type) => {
+            if (type !== "global" && type !== "node") {
+                throw new Error(`$getWorkflowStaticData: type must be "global" or "node", got ${JSON.stringify(type)}`);
+            }
+            return staticData[type];
+        },
+        $execution: fixture.execution ?? { id: "local", mode: "test" },
+        $prevNode: fixture.prevNode ?? { name: "", outputIndex: 0, runIndex: 0 },
+        $jmespath: (data, expr) => {
+            throw new Error("$jmespath is not implemented in `run` — assert on the data directly");
+        },
+        console,
+    };
+}
+async function invoke(code, globals) {
+    const names = Object.keys(globals);
+    const fn = new AsyncFunction(...names, code);
+    return fn(...names.map((n) => globals[n]));
+}
+/**
+ * Execute a Code node's body locally against a (fake) n8n context and print
+ * what it returns. Offline; no credentials, no network. `.ts` is compiled with
+ * the same esbuild pass as push; `.js` runs verbatim (marker stripped if any).
+ */
+export async function runNode(file, fixturePath, log, opts = {}) {
+    const resolved = path.resolve(file);
+    if (!existsSync(resolved))
+        throw new Error(`node file not found: ${file}`);
+    if (!/\.(ts|js)$/.test(resolved))
+        throw new Error(`not a node source file (need .js or .ts): ${file}`);
+    const basename = path.basename(resolved);
+    const { node, staticData } = findNodeContext(resolved);
+    const mode = node?.parameters?.mode ?? "runOnceForAllItems";
+    if (!node)
+        log.warn(`no workflow.json placeholder points at ${basename} — assuming ${mode}`);
+    const code = resolved.endsWith(".ts")
+        ? await compileTs(resolved, log)
+        : splitMarker(readFileSync(resolved, "utf8")).body;
+    const fixture = loadFixture(fixturePath, log);
+    const globals = await buildGlobals(fixture, log, { nodeName: node?.name, staticData, allowEnv: opts.allowEnv });
+    log.info(`running ${basename} (${mode})${fixturePath ? ` with fixture ${path.basename(fixturePath)}` : ""}`);
+    log.info("─".repeat(48));
+    let output;
+    if (mode === "runOnceForEachItem") {
+        const input = globals.$input.all();
+        output = [];
+        for (let i = 0; i < input.length; i++) {
+            const perItem = {
+                ...globals,
+                $json: input[i].json,
+                $binary: input[i].binary ?? {},
+                $itemIndex: i,
+                $input: { ...globals.$input, item: input[i] },
+            };
+            const ret = await invoke(code, perItem);
+            if (ret !== undefined)
+                output.push(ret);
+        }
+    }
+    else {
+        output = await invoke(code, globals);
+    }
+    log.info("─".repeat(48));
+    const count = Array.isArray(output) ? output.length : output === undefined ? 0 : 1;
+    log.info(`returned ${count} item${count === 1 ? "" : "s"}:`);
+    console.log(JSON.stringify(output, null, 2));
+    return output;
+}

package/dist/lib/state.mjs

@@ -0,0 +1,156 @@
+import { existsSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { CODE_DIR } from "./util.mjs";
+export const STATE_FILE = ".decanter.json";
+/**
+ * Locate the workflow folder a node file belongs to: the file's own
+ * directory, or its parent when the file sits in `code/`. `marker` is the
+ * file that proves a workflow folder — `.decanter.json` for sync state,
+ * `workflow.json` for structure. Null when neither location qualifies.
+ */
+export function nodeFileContextDir(filePath, marker = STATE_FILE) {
+    let dir = path.dirname(filePath);
+    if (!existsSync(path.join(dir, marker)) && path.basename(dir) === CODE_DIR) {
+        dir = path.dirname(dir);
+    }
+    return existsSync(path.join(dir, marker)) ? dir : null;
+}
+/**
+ * Rename a node's source file *and* its `.remote.js` sibling to a new kebab
+ * base. Never renames across extensions (an `ext` differing from the current
+ * file's leaves the source in place — compiled JS must not silently become
+ * "TS source"), and never clobbers an existing target: skipped renames are
+ * silent because both callers handle them (pull rewrites content afterwards,
+ * remote being authoritative; rename pre-checks collisions and throws).
+ * Returns the wanted relative path (`code/<base><ext>`).
+ */
+export function renameNodeFilePair(dir, current, base, ext, log) {
+    const wanted = `${CODE_DIR}/${base}${ext}`;
+    const renames = [[current.replace(/\.(ts|js)$/, ".remote.js"), `${CODE_DIR}/${base}.remote.js`]];
+    if (path.extname(current) === ext)
+        renames.push([current, wanted]);
+    for (const [from, to] of renames) {
+        const fromPath = path.join(dir, from);
+        if (from !== to && existsSync(fromPath) && !existsSync(path.join(dir, to))) {
+            renameSync(fromPath, path.join(dir, to));
+            log.info(`renamed ${from} -> ${to}`);
+        }
+    }
+    return wanted;
+}
+/** Missing state is null; corrupt state throws a clear, file-naming error. */
+export function readState(dir) {
+    const file = path.join(dir, STATE_FILE);
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`corrupt ${STATE_FILE} (${err.message})`);
+    }
+}
+export function writeState(dir, state) {
+    writeFileSync(path.join(dir, STATE_FILE), JSON.stringify(state, null, 2) + "\n");
+}
+/** All workflow folders under root (dirs containing a .decanter.json). */
+export function listWorkflowDirs(root) {
+    const found = [];
+    if (!existsSync(root))
+        return found;
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        if (entries.some((e) => e.isFile() && e.name === STATE_FILE)) {
+            found.push(dir); // workflow folders don't nest
+            continue;
+        }
+        for (const e of entries) {
+            if (e.isDirectory() && e.name !== "node_modules")
+                stack.push(path.join(dir, e.name));
+        }
+    }
+    return found.sort();
+}
+/**
+ * All pulled workflows with their addressable names. A corrupt or missing
+ * state file only skips its own folder (warned via `log`), same as
+ * findWorkflowDir.
+ */
+export function listWorkflowRefs(root, log) {
+    const refs = [];
+    for (const dir of listWorkflowDirs(root)) {
+        let state;
+        try {
+            state = readState(dir);
+        }
+        catch (err) {
+            log?.warn(`${dir}: ${err.message} — skipping this folder`);
+            continue;
+        }
+        if (!state)
+            continue;
+        const folderName = path.basename(dir);
+        let wfName;
+        try {
+            wfName = JSON.parse(readFileSync(path.join(dir, "workflow.json"), "utf8")).name;
+        }
+        catch {
+            // no or unparsable workflow.json — the folder name still addresses it
+        }
+        const names = [...new Set([wfName, folderName].filter((n) => typeof n === "string" && n !== ""))];
+        refs.push({ id: state.workflowId, dir, name: wfName ?? folderName, names });
+    }
+    return refs;
+}
+/**
+ * Match a CLI workflow argument against candidates: exact id → exact name
+ * (case-insensitive) → unique name prefix. Several matches in a tier throw,
+ * listing the candidates; no match returns null (never a prompt — ambiguity
+ * must stay script- and LLM-safe).
+ */
+export function matchWorkflowRef(candidates, ref) {
+    const byId = candidates.find((c) => c.id === ref);
+    if (byId)
+        return byId;
+    const lc = ref.toLowerCase();
+    for (const tier of [
+        candidates.filter((c) => c.names.some((n) => n.toLowerCase() === lc)),
+        candidates.filter((c) => c.names.some((n) => n.toLowerCase().startsWith(lc))),
+    ]) {
+        if (tier.length === 1)
+            return tier[0];
+        if (tier.length > 1) {
+            throw new Error(`ambiguous workflow "${ref}" — matches ${tier.map((c) => `"${c.names[0]}" (${c.id})`).join(", ")}`);
+        }
+    }
+    return null;
+}
+/** True when a ref could plausibly be a raw workflow id (opaque alphanumeric token). */
+export function looksLikeWorkflowId(ref) {
+    return /^[A-Za-z0-9_-]+$/.test(ref);
+}
+/**
+ * Find the workflow folder for an id by scanning .decanter.json files.
+ * A corrupt state file only skips its own folder (warned via `log`) — it must
+ * not take down commands for every other workflow.
+ */
+export function findWorkflowDir(root, workflowId, log) {
+    for (const dir of listWorkflowDirs(root)) {
+        try {
+            if (readState(dir)?.workflowId === workflowId)
+                return dir;
+        }
+        catch (err) {
+            log?.warn(`${dir}: ${err.message} — skipping this folder`);
+        }
+    }
+    return null;
+}

package/dist/lib/status.mjs

@@ -0,0 +1,102 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { compileTs } from "./compile.mjs";
+import { unifiedDiff } from "./diff.mjs";
+import { findWorkflowDir, readState } from "./state.mjs";
+import { style } from "./style.mjs";
+import { isJsCodeNode, publicationState, sha256, splitMarker, workflowStructureHash } from "./util.mjs";
+/** The comparable local body: file content for .js, the compiled JS for .ts. */
+async function localBody(dir, file, log) {
+    const filePath = path.join(dir, file);
+    if (!existsSync(filePath))
+        return null;
+    if (file.endsWith(".ts"))
+        return compileTs(filePath, log);
+    return readFileSync(filePath, "utf8");
+}
+export async function statusWorkflow(api, root, id, log, { diff = false } = {}) {
+    const remote = await api.getWorkflow(id);
+    const dir = findWorkflowDir(root, id, log);
+    if (!dir) {
+        log.warn(`${remote.name} (${id}): not pulled yet`);
+        return { remoteDrift: true };
+    }
+    let remoteDrift = false;
+    const drift = () => {
+        remoteDrift = true;
+    };
+    const state = readState(dir);
+    const pub = publicationState(remote);
+    log.info(`${remote.name} (${id})  [${path.relative(process.cwd(), dir)}]${pub ? `  ${pub}` : ""}`);
+    const remoteStruct = workflowStructureHash(remote);
+    const wfFile = path.join(dir, "workflow.json");
+    const localStruct = existsSync(wfFile)
+        ? workflowStructureHash(JSON.parse(readFileSync(wfFile, "utf8")))
+        : null;
+    const base = state.lastPulledWorkflowHash;
+    if (remoteStruct !== base && localStruct !== base) {
+        log.warn("  structure: changed both locally and remotely");
+        drift();
+    }
+    else if (remoteStruct !== base) {
+        log.warn("  structure: changed remotely — pull");
+        drift();
+    }
+    else if (localStruct !== base)
+        log.info("  structure: changed locally — push pending");
+    else
+        log.ok("  structure: in sync");
+    for (const node of remote.nodes) {
+        if (!isJsCodeNode(node))
+            continue;
+        const nodeState = state.nodes[node.id];
+        const label = `  ${node.name}`;
+        if (!nodeState) {
+            log.warn(`${label}: remote code node unknown locally — pull`);
+            drift();
+            continue;
+        }
+        const remoteBody = splitMarker(node.parameters.jsCode).body;
+        const remoteHash = sha256(remoteBody);
+        const body = await localBody(dir, nodeState.file, log);
+        const local = body === null ? null : sha256(body);
+        // --diff: the same bodies the hashes compare — for .ts that is the
+        // compiled JS, which is what push would put on the remote
+        const printDiff = () => {
+            if (!diff || body === null)
+                return;
+            log.info(`    ${style.dim("--- remote (n8n)")}`);
+            log.info(`    ${style.dim(`+++ local (${nodeState.file})`)}`);
+            for (const line of unifiedDiff(remoteBody, body)) {
+                const styled = line.startsWith("+") ? style.green(line) : line.startsWith("-") ? style.red(line) : style.dim(line);
+                log.info(`    ${styled}`);
+            }
+        };
+        const last = nodeState.lastPushedHash;
+        if (local === null)
+            log.warn(`${label}: local file ${nodeState.file} missing`);
+        else if (local === remoteHash)
+            log.ok(`${label}: in sync (${nodeState.file})`);
+        else if (remoteHash === last) {
+            log.info(`${label}: local changes in ${nodeState.file} — push pending`);
+            printDiff();
+        }
+        else if (local === last) {
+            log.warn(`${label}: changed remotely — pull`);
+            drift();
+            printDiff();
+        }
+        else {
+            log.error(`${label}: CONFLICT — changed both locally and remotely`);
+            drift();
+            printDiff();
+        }
+    }
+    for (const [nodeId, nodeState] of Object.entries(state.nodes)) {
+        if (!remote.nodes.some((n) => n.id === nodeId)) {
+            log.warn(`  ${nodeState.file}: node ${nodeId} deleted remotely`);
+            drift();
+        }
+    }
+    return { remoteDrift };
+}

package/dist/lib/style.mjs

@@ -0,0 +1,40 @@
+// TTY-gated styling (Plan 11). One rule: escape codes exist only when the
+// target stream is a color-capable TTY — util.styleText handles that per
+// stream and also honors NO_COLOR / FORCE_COLOR. Piped output (LLM harnesses,
+// scripts, the e2e suite) gets the same words minus the escapes; color is
+// additive decoration and never carries information alone.
+import { styleText } from "node:util";
+function makeStyle(stream) {
+    const s = (format, text) => styleText(format, text, { stream });
+    return {
+        bold: (t) => s("bold", t),
+        dim: (t) => s("dim", t),
+        green: (t) => s("green", t),
+        yellow: (t) => s("yellow", t),
+        red: (t) => s("red", t),
+        link: (text, url) => stream.isTTY ? `\x1b]8;;${url}\x1b\\${text}\x1b]8;;\x1b\\` : text === url ? url : `${text} ${url}`,
+    };
+}
+/** Styling gated on the stream the text actually goes to. */
+export const style = makeStyle(process.stdout);
+export const styleErr = makeStyle(process.stderr);
+/**
+ * TTY-only transient status line ("pulling wf123…"): shown in place, erased
+ * before the next real log line replaces it. Piped output never sees it.
+ */
+export function transientLine() {
+    let pending = false;
+    return {
+        show(text) {
+            if (!process.stdout.isTTY)
+                return;
+            process.stdout.write(text);
+            pending = true;
+        },
+        clear() {
+            if (pending)
+                process.stdout.write("\r\x1b[2K");
+            pending = false;
+        },
+    };
+}

package/dist/lib/types.mjs

@@ -0,0 +1,2 @@
+// Shared shapes of the decanter data model. Types only — no runtime exports.
+export {};