n8n-decanter 0.3.2 → 0.5.0

package/dist/lib/datatables.mjs

@@ -0,0 +1,124 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { kebabCase } from "./util.mjs";
+/** Top-level dir (next to decanter.config.json) holding fetched data tables. */
+export const DATA_TABLES_DIR = "data-tables";
+/** Default rows fetched per page — the API caps a page at 250. */
+export const DEFAULT_ROW_LIMIT = 100;
+/**
+ * Folder slug for a fetched table: the kebab of its name with the id appended
+ * (data-table names aren't guaranteed unique, so the id disambiguates). The id
+ * is stripped of anything non-alphanumeric to stay filesystem-safe.
+ */
+export function dataTableSlug(id, name) {
+    const safeId = String(id).replace(/[^A-Za-z0-9]+/g, "") || "id";
+    return `${kebabCase(name)}-${safeId}`;
+}
+/** Pick the tables named by `tableRefs` (id or exact name); empty = all. */
+function selectTables(tables, tableRefs) {
+    if (tableRefs.length === 0)
+        return tables;
+    const picked = new Map();
+    for (const ref of tableRefs) {
+        const lc = ref.toLowerCase();
+        const hits = tables.filter((t) => String(t.id) === ref || t.name.toLowerCase() === lc);
+        if (hits.length === 0) {
+            const known = tables.map((t) => `"${t.name}" (${t.id})`).join(", ");
+            throw new Error(`no data table matches "${ref}"${known ? ` — tables: ${known}` : " — no data tables on the server"}`);
+        }
+        for (const t of hits)
+            picked.set(String(t.id), t);
+    }
+    return [...picked.values()];
+}
+/** Human summary fragment naming the applied server-side filter, or "". */
+function filterSummary(opts) {
+    const parts = [];
+    if (opts.filter !== undefined)
+        parts.push(`filter ${opts.filter}`);
+    if (opts.search !== undefined)
+        parts.push(`search "${opts.search}"`);
+    if (opts.sortBy !== undefined)
+        parts.push(`sort ${opts.sortBy}`);
+    return parts.length > 0 ? ` [${parts.join(", ")}]` : "";
+}
+/**
+ * Fetch data-table schemas + (filtered) rows into a single top-level,
+ * self-ignored `data-tables/` dir — mirrors `executions` (read-only, temp,
+ * gitignored). Data tables are project-scoped (not owned by a workflow), so
+ * they land next to `decanter.config.json`, not under a workflow folder. Each
+ * table becomes `data-tables/<slug>/{meta,columns,rows}.json`; `meta.json`
+ * records the applied filter/search/sort/limit and the row count so a filtered
+ * `rows.json` is self-describing. The CLI never writes any data-table endpoint.
+ */
+export async function fetchDataTables(api, configDir, opts, log) {
+    let tables;
+    try {
+        tables = await api.listDataTables();
+    }
+    catch (err) {
+        const msg = err.message;
+        if (/\b404\b/.test(msg)) {
+            throw new Error(`the n8n data-tables API is not available (404) — data tables need n8n ≥ 2.x; a full-access key still works if your instance predates them\n${msg}`);
+        }
+        throw err;
+    }
+    const selected = selectTables(tables, opts.tableRefs ?? []);
+    if (selected.length === 0) {
+        log.info("no data tables on the server");
+        return;
+    }
+    const outRoot = path.join(configDir, DATA_TABLES_DIR);
+    mkdirSync(outRoot, { recursive: true });
+    // Self-ignoring dir: data tables can hold PII — same reasoning as executions/.
+    writeFileSync(path.join(outRoot, ".gitignore"), "*\n");
+    const rel = (p) => path.relative(process.cwd(), p);
+    const filterDesc = filterSummary(opts);
+    for (const table of selected) {
+        const dir = path.join(outRoot, dataTableSlug(table.id, table.name));
+        mkdirSync(dir, { recursive: true });
+        const columns = await api.getDataTableColumns(String(table.id));
+        const rows = [];
+        let cursor;
+        do {
+            const page = await api.getDataTableRows(String(table.id), {
+                limit: opts.limit ?? DEFAULT_ROW_LIMIT,
+                cursor,
+                filter: opts.filter,
+                search: opts.search,
+                sortBy: opts.sortBy,
+            });
+            rows.push(...page.data);
+            cursor = opts.all ? (page.nextCursor ?? undefined) : undefined;
+        } while (cursor !== undefined);
+        const meta = {
+            id: table.id,
+            name: table.name,
+            projectId: table.projectId ?? null,
+            fetchedAt: new Date().toISOString(),
+            rowCount: rows.length,
+            // A filtered rows.json is a slice, never the whole table — record what
+            // produced it so it can't be mistaken for a full export.
+            filter: opts.filter ?? null,
+            search: opts.search ?? null,
+            sortBy: opts.sortBy ?? null,
+            limit: opts.limit ?? DEFAULT_ROW_LIMIT,
+            all: Boolean(opts.all),
+        };
+        writeFileSync(path.join(dir, "meta.json"), JSON.stringify(meta, null, 2) + "\n");
+        writeFileSync(path.join(dir, "columns.json"), JSON.stringify(columns, null, 2) + "\n");
+        writeFileSync(path.join(dir, "rows.json"), JSON.stringify(rows, null, 2) + "\n");
+        log.info(`wrote ${rel(dir)}/{meta,columns,rows}.json (${columns.length} column${columns.length === 1 ? "" : "s"}, ${rows.length} row${rows.length === 1 ? "" : "s"})`);
+    }
+    log.ok(`${selected.length} data table${selected.length === 1 ? "" : "s"}${filterDesc} -> ${rel(outRoot)} (gitignored — temp data, "data-tables clean" removes it)`);
+}
+/** Offline delete of the local `data-tables/` dir (mirrors cleanExecutions). */
+export function cleanDataTables(configDir, log) {
+    const outRoot = path.join(configDir, DATA_TABLES_DIR);
+    if (!existsSync(outRoot)) {
+        log.info("no data-tables/ dir to clean");
+        return;
+    }
+    rmSync(outRoot, { recursive: true, force: true });
+    log.ok(`removed ${path.relative(process.cwd(), outRoot)}`);
+}

package/dist/lib/engine.mjs

@@ -0,0 +1,192 @@
+// Plan 7 — the engine backend for `simulate`. Runs a transformed simulation
+// workflow through a *real* n8n via route B (validated by the Plan 7 spike):
+// `n8n import:workflow` + `n8n execute --id --rawOutput` in a throwaway
+// container, no server and no credentials, output scraped from the result JSON.
+//
+// Backend: Docker (`n8nio/n8n:<version>`). The plan's eventual default is a
+// dependency-free `npx n8n@<ver>` backend; that needs its own validation
+// (heavy native install) and is a follow-up — the backend is pluggable, Docker
+// is what's proven. `--network none` adds an enforced outbound cutoff on top of
+// the structural guarantee (no I/O-capable node survives the transform).
+import { execFile as execFileCb } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFile = promisify(execFileCb);
+/** n8n version the engine defaults to — the smoke-suite pin (Plan 7 version policy). */
+/* Keep in sync with test/smoke-n8n.mts IMAGE and .github/workflows/ci.yml smoke floor. */
+export const DEFAULT_N8N_VERSION = "2.30.7";
+/** Fixed workflow id the sim copy is imported under (throwaway DB, one workflow). */
+const SIM_WORKFLOW_ID = "decantersim0000";
+const EXEC_MARKER = "---DECANTER-EXEC---";
+const docker = (args, opts = {}) => execFile("docker", args, { encoding: "utf8", maxBuffer: 128 * 1024 * 1024, timeout: opts.timeoutMs ?? 120_000 });
+/** True when a Docker daemon is reachable — lets `simulate`/`test:sim` skip cleanly. */
+export async function dockerAvailable() {
+    try {
+        await docker(["version", "--format", "{{.Server.Version}}"], { timeoutMs: 10_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Isolation env for the engine container (Plan 7 task 4): telemetry/notifications/
+ *  template fetches off, Code-node module allowlists emptied. Credentials never
+ *  enter — `docker run` passes only these `-e` values, so host `N8N_*` stays out. */
+function isolationEnv() {
+    return [
+        "N8N_DIAGNOSTICS_ENABLED=false",
+        "N8N_VERSION_NOTIFICATIONS_ENABLED=false",
+        "N8N_TEMPLATES_ENABLED=false",
+        "N8N_PERSONALIZATION_ENABLED=false",
+        "EXTERNAL_FRONTEND_HOOKS_URLS=",
+        "NODE_FUNCTION_ALLOW_EXTERNAL=",
+        "N8N_USER_FOLDER=/tmp/n8n",
+    ];
+}
+/** Normalize an n8n `runData` object (from CLI JSON or the API) into a per-node item map. */
+function runDataToMap(rd) {
+    const map = new Map();
+    for (const [node, runs] of Object.entries(rd)) {
+        const main = runs?.[0]?.data?.main;
+        map.set(node, Array.isArray(main) && Array.isArray(main[0]) ? main[0] : []);
+    }
+    return map;
+}
+/** Parse the `--rawOutput` result JSON that follows our marker, into a runData map. */
+function parseRunData(stdout) {
+    const after = stdout.includes(EXEC_MARKER) ? stdout.slice(stdout.indexOf(EXEC_MARKER) + EXEC_MARKER.length) : stdout;
+    const start = after.indexOf("{");
+    const end = after.lastIndexOf("}");
+    if (start === -1 || end <= start) {
+        const tail = stdout.trim().split("\n").slice(-4).join(" | ").slice(0, 400);
+        return { runData: new Map(), ok: false, error: `engine produced no result JSON — ${tail}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(after.slice(start, end + 1));
+    }
+    catch (err) {
+        return { runData: new Map(), ok: false, error: `unparsable engine result JSON (${err.message})` };
+    }
+    const error = parsed.data?.resultData?.error?.message;
+    return { runData: runDataToMap(parsed.data?.resultData?.runData ?? {}), ok: error === undefined, error };
+}
+/**
+ * Import the simulation workflow into a throwaway n8n and execute it, returning
+ * per-node output. Throws only on infrastructure failure (no Docker, image
+ * missing); a workflow that errors inside the engine comes back as `ok: false`
+ * with the message — the caller decides what a failed run means.
+ */
+export async function runEngine(workflow, opts, log) {
+    const image = `n8nio/n8n:${opts.version}`;
+    const tmp = mkdtempSync(path.join(os.tmpdir(), "decanter-sim-"));
+    const simFile = path.join(tmp, "sim.json");
+    const container = `decanter-sim-${process.pid}-${Date.now()}`;
+    writeFileSync(simFile, JSON.stringify({ ...workflow, id: SIM_WORKFLOW_ID, active: false }));
+    const runArgs = [
+        "run", "--rm", "--name", container,
+        ...(opts.networkNone ? ["--network", "none"] : []),
+        ...isolationEnv().flatMap((e) => ["-e", e]),
+        "-v", `${simFile}:/tmp/sim.json:ro`,
+        "--entrypoint", "sh", image,
+        "-c", `mkdir -p /tmp/n8n && n8n import:workflow --input=/tmp/sim.json >/tmp/import.log 2>&1 && echo '${EXEC_MARKER}' && n8n execute --id=${SIM_WORKFLOW_ID} --rawOutput 2>/dev/null`,
+    ];
+    log.info(`engine: ${image}${opts.networkNone ? " (network: none)" : ""} — importing + executing simulation`);
+    try {
+        const { stdout, stderr } = await docker(runArgs, { timeoutMs: 180_000 });
+        return parseRunData(stdout + stderr);
+    }
+    catch (err) {
+        const e = err;
+        // A non-zero exit with a result JSON still means "ran, workflow errored".
+        if ((e.stdout ?? "").includes(EXEC_MARKER))
+            return parseRunData((e.stdout ?? "") + (e.stderr ?? ""));
+        throw new Error(`engine run failed (${image}): ${(e.stderr || e.message || "").split("\n").slice(0, 3).join(" ").slice(0, 300)}`);
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+        await docker(["rm", "-f", container], { timeoutMs: 15_000 }).catch(() => { });
+    }
+}
+/** Stable name of the kept-alive viewer container (one at a time; replaced per run). */
+export const VIEWER_CONTAINER = "decanter-sim-viewer";
+/** Fixed local owner for the throwaway viewer — printed so you can log in to browse. */
+export const VIEWER_LOGIN = { email: "simulate@decanter.local", password: "Decanter-Sim-0000", firstName: "Decanter", lastName: "Simulate" };
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Launch a *kept-alive* local n8n that has the simulation run saved and
+ * browsable: import + `n8n execute` (persists the run) + `n8n start` (serves
+ * it). Returns the execution's UI URL and a local login (n8n requires auth; we
+ * seed a fixed throwaway owner). The container is left running (bound to
+ * 127.0.0.1 only, throwaway data, no credentials) and replaced on the next
+ * viewer run. The diff comes from the separate headless run, so nothing is read
+ * back here. Incompatible with `--network none` (a published port needs a
+ * network). Throwaway DB ⇒ the run is always execution id 1.
+ */
+export async function startViewer(workflow, opts, log) {
+    const image = `n8nio/n8n:${opts.version}`;
+    // A *stable* file the long-lived viewer bind-mounts: `docker run -d` is
+    // detached and the container reads it at startup, so it must outlive this call
+    // (unlike the headless run, which isn't detached). Reap the previous viewer
+    // before overwriting it, so nothing is holding the old mount.
+    const simFile = path.join(os.tmpdir(), "decanter-sim-viewer.json");
+    await docker(["rm", "-f", VIEWER_CONTAINER], { timeoutMs: 15_000 }).catch(() => { });
+    // `n8n execute` only persists the run (needed for it to be browsable) when the
+    // workflow opts in — force the save settings on the viewer copy.
+    const viewerWf = {
+        ...workflow, id: SIM_WORKFLOW_ID, active: false,
+        settings: { ...workflow.settings, saveDataSuccessExecution: "all", saveDataErrorExecution: "all", saveManualExecutions: true },
+    };
+    writeFileSync(simFile, JSON.stringify(viewerWf));
+    log.info(`engine: ${image} — starting a local viewer (kept alive so you can open the run)`);
+    // Minimal env: enough to save the run and serve it over http. The strict
+    // task-runner isolation (empty module allowlist, etc.) belongs to the headless
+    // dry run — the viewer's safety is structural (no credentials survive the
+    // transform), and it needs a network for the browser anyway.
+    await docker([
+        "run", "-d", "--name", VIEWER_CONTAINER, "-p", "127.0.0.1::5678",
+        "-e", "N8N_SECURE_COOKIE=false", "-e", "N8N_DIAGNOSTICS_ENABLED=false", "-e", "N8N_PERSONALIZATION_ENABLED=false",
+        "-e", "EXECUTIONS_DATA_SAVE_ON_SUCCESS=all", "-e", "EXECUTIONS_DATA_SAVE_ON_ERROR=all", "-e", "EXECUTIONS_DATA_SAVE_MANUAL_EXECUTIONS=true",
+        "-v", `${simFile}:/tmp/sim.json:ro`, "--entrypoint", "sh", image,
+        "-c", `n8n import:workflow --input=/tmp/sim.json && n8n execute --id=${SIM_WORKFLOW_ID}; n8n start`,
+    ], { timeoutMs: 60_000 });
+    const host = `http://${(await docker(["port", VIEWER_CONTAINER, "5678"])).stdout.trim().split("\n")[0]}`;
+    // wait for REST to serve real JSON (readiness, not just /healthz liveness)
+    let ready = false;
+    for (let i = 0; i < 90 && !ready; i++) {
+        ready = await fetch(`${host}/rest/settings`).then((r) => r.ok && (r.headers.get("content-type") ?? "").includes("json")).catch(() => false);
+        if (!ready)
+            await sleep(2000);
+    }
+    if (!ready)
+        throw new Error(`viewer n8n never became ready at ${host}`);
+    // Seed a fixed local owner so the browser lands on a login (not the setup
+    // wizard), and so we can read the saved run back to confirm it's browsable.
+    const authCookie = (r) => r.headers.getSetCookie().join("; ").match(/n8n-auth=[^;]+/)?.[0];
+    await fetch(`${host}/rest/owner/setup`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(VIEWER_LOGIN) }).catch(() => undefined);
+    let cookie;
+    for (let i = 0; i < 5 && !cookie; i++) {
+        const l = await fetch(`${host}/rest/login`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ emailOrLdapLoginId: VIEWER_LOGIN.email, password: VIEWER_LOGIN.password }) }).catch(() => undefined);
+        cookie = l && authCookie(l);
+        if (!cookie)
+            await sleep(1000);
+    }
+    // Poll until the saved run is queryable (it lands a beat after the server
+    // finishes initializing) and use its real id for the URL.
+    let execId = "1";
+    for (let i = 0; i < 20 && cookie; i++) {
+        const list = await fetch(`${host}/rest/executions`, { headers: { cookie } }).then((r) => r.json()).catch(() => undefined);
+        const first = (list?.data?.results ?? list?.data ?? [])[0];
+        if (first?.id) {
+            execId = String(first.id);
+            break;
+        }
+        await sleep(1000);
+    }
+    return {
+        url: `${host}/workflow/${SIM_WORKFLOW_ID}/executions/${execId}`,
+        login: { email: VIEWER_LOGIN.email, password: VIEWER_LOGIN.password },
+    };
+}

package/dist/lib/executions.mjs

@@ -1,7 +1,26 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { findWorkflowDir, listWorkflowDirs } from "./state.mjs";
 export const EXECUTIONS_DIR = "executions";
+/**
+ * The newest captured execution id in a workflow folder's `executions/` dir, or
+ * null when none are captured. n8n execution ids are incrementing integers, so
+ * "newest" is the highest numeric filename; non-numeric files are ignored. Lets
+ * `simulate` (and the picker, which can't supply an id) default to the latest
+ * capture.
+ */
+export function latestCaptureId(dir) {
+    const outDir = path.join(dir, EXECUTIONS_DIR);
+    if (!existsSync(outDir))
+        return null;
+    let best = null;
+    for (const entry of readdirSync(outDir)) {
+        const m = entry.match(/^(\d+)\.json$/);
+        if (m && (best === null || Number(m[1]) > best))
+            best = Number(m[1]);
+    }
+    return best === null ? null : String(best);
+}
 /**
  * Warn when fetched executions ran a *published* version that differs from the
  * local draft (`workflow.json`'s `versionId`) — the captured data may not match
@@ -10,7 +29,7 @@ export const EXECUTIONS_DIR = "executions";
  * by version so a page of same-version executions warns once; silent when the
  * draft version or the execution version is unavailable (defensive).
  */
-function warnStaleFixtures(dir, executions, log) {
+export function warnStaleFixtures(dir, executions, log) {
     const wfFile = path.join(dir, "workflow.json");
     if (!existsSync(wfFile))
         return;

package/dist/lib/init.mjs

@@ -4,6 +4,8 @@ import { fileURLToPath } from "node:url";
 import { parseEnvFile } from "./config.mjs";
 import { createPrompt } from "./prompt.mjs";
 import { style } from "./style.mjs";
+import { classifyTemplateFile, MANIFEST_FILE, readManifest, writeManifest } from "./template.mjs";
+import { sha256 } from "./util.mjs";
 /**
  * Nearest ancestor of `startDir` holding a package.json — the package root.
  * Works from the checkout (lib/ → repo root) *and* from the published build
@@ -52,30 +54,151 @@ export function printBanner(log) {
         console.log(style.red(row.slice(0, 6)) + style.bold(row.slice(6)));
     console.log(style.dim(`n8n workflows ⇄ agentic code · v${version}`));
 }
-function copyTemplate(srcDir, destDir, { force = false, protect = new Set() } = {}) {
-    const overwritten = [];
-    const walk = (src, dest, rel) => {
-        mkdirSync(dest, { recursive: true });
+/**
+ * Classify every template file against the target dir and the copy-time
+ * baseline manifest. Pure scan — no files are written.
+ */
+function scanTemplate(srcDir, destDir, manifest, protect) {
+    const entries = [];
+    const walk = (src, rel) => {
         for (const entry of readdirSync(src, { withFileTypes: true })) {
             const srcPath = path.join(src, entry.name);
             if (entry.isDirectory()) {
-                walk(srcPath, path.join(dest, entry.name), path.join(rel, entry.name));
+                walk(srcPath, path.join(rel, entry.name));
                 continue;
             }
             const name = entry.name.endsWith(".example") && entry.name !== ".example"
                 ? entry.name.slice(0, -".example".length)
                 : entry.name;
-            const destPath = path.join(dest, 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);
-            if (exists && (!force || protect.has(destPath)))
-                continue;
-            copyFileSync(srcPath, destPath);
-            if (exists)
-                overwritten.push(path.join(rel, name));
+            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 }),
+            });
         }
     };
-    walk(srcDir, destDir, "");
-    return overwritten;
+    walk(srcDir, "");
+    return entries;
+}
+function copyEntry(entry) {
+    mkdirSync(path.dirname(entry.destPath), { recursive: true });
+    copyFileSync(entry.srcPath, entry.destPath);
+}
+/**
+ * Modification-aware template refresh (dpkg conffile-style). First init copies
+ * everything and records a baseline manifest. Re-init copies files new to the
+ * template, offers to refresh files the user hasn't touched (pristine), and
+ * 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) {
+    const manifest = readManifest(destDir);
+    const firstInit = !existsSync(path.join(destDir, MANIFEST_FILE));
+    const entries = scanTemplate(srcDir, destDir, manifest.files, protect);
+    const nextFiles = {};
+    if (force) {
+        let anyExisting = false;
+        for (const e of entries) {
+            const changed = e.targetHash !== undefined && e.targetHash !== e.templateHash;
+            if (e.targetHash !== undefined)
+                anyExisting = true;
+            copyEntry(e);
+            nextFiles[e.rel] = e.templateHash;
+            if (e.targetHash !== undefined)
+                log.warn(`--force: overwrote ${e.rel} with the template version${changed ? " (had local changes)" : ""}`);
+        }
+        writeManifest(destDir, { version, files: nextFiles });
+        log.info(anyExisting ? `reset template -> ${destDir}` : `copied template -> ${destDir}`);
+        return;
+    }
+    const added = [];
+    const pending = [];
+    const modified = [];
+    const conflicts = [];
+    let uptodate = 0;
+    for (const e of entries) {
+        switch (e.outcome) {
+            case "added":
+                copyEntry(e);
+                nextFiles[e.rel] = e.templateHash;
+                added.push(e.rel);
+                break;
+            case "converged":
+                nextFiles[e.rel] = e.templateHash; // adopt: on-disk copy now equals the template
+                break;
+            case "adopt":
+                nextFiles[e.rel] = e.targetHash; // legacy dir: trust the on-disk copy as the baseline
+                break;
+            case "update":
+                pending.push(e);
+                nextFiles[e.rel] = manifest.files[e.rel]; // provisional; set to templateHash if applied
+                break;
+            case "drift-modified":
+                modified.push(e.rel);
+                nextFiles[e.rel] = manifest.files[e.rel];
+                break;
+            case "drift-conflict":
+                conflicts.push(e.rel);
+                nextFiles[e.rel] = manifest.files[e.rel];
+                break;
+            case "uptodate":
+                uptodate++;
+                nextFiles[e.rel] = e.templateHash;
+                break;
+        }
+    }
+    // On first init everything is "added" — the single "copied template" line
+    // below says it; only call out files the template *gained* on a re-init.
+    if (!firstInit)
+        for (const rel of added)
+            log.info(`added ${rel} from the template`);
+    if (pending.length > 0) {
+        let apply = false;
+        if (process.stdin.isTTY) {
+            const rl = createPrompt();
+            try {
+                log.info(`${pending.length} template file(s) have newer versions and are unmodified locally:`);
+                for (const e of pending)
+                    log.info(`  ${e.rel}`);
+                apply = (await rl.question(`Update ${pending.length} pristine file(s) to the template version? [y/N] `)).trim().toLowerCase().startsWith("y");
+            }
+            finally {
+                rl.close();
+            }
+        }
+        else {
+            log.warn(`${pending.length} pristine template file(s) have updates available — re-run init interactively or with --force to apply: ${pending.map((e) => e.rel).join(", ")}`);
+        }
+        if (apply) {
+            for (const e of pending) {
+                copyEntry(e);
+                nextFiles[e.rel] = e.templateHash;
+            }
+            log.info(`updated ${pending.length} file(s) from the template`);
+        }
+    }
+    if (modified.length > 0)
+        log.warn(`left unchanged (modified locally): ${modified.join(", ")}`);
+    if (conflicts.length > 0)
+        log.warn(`left unchanged (changed in both the template and your copy — resolve manually or --force to reset): ${conflicts.join(", ")}`);
+    writeManifest(destDir, { version, files: nextFiles });
+    // "copied" only when the whole tree was genuinely fresh; a dir that pre-dates
+    // the manifest (files present, no baseline) adopts in place — report as such.
+    if (added.length === entries.length)
+        log.info(`copied template -> ${destDir}`);
+    else
+        log.info(`template up to date (${uptodate} unchanged${added.length ? `, ${added.length} added` : ""})`);
 }
 /** Interactive bootstrap: prompt for credentials, write .env, copy template/. */
 export async function init(targetDir, { force = false } = {}, log) {
@@ -107,16 +230,14 @@ export async function init(targetDir, { force = false } = {}, log) {
         writeFileSync(envFile, `N8N_HOST=${host}\nN8N_API_KEY=${apiKey}\n`);
         log.info(`wrote ${envFile}`);
     }
-    // Copy the template completely (whatever it contains, recursively).
-    // Default: never overwrite files that already exist in the target.
-    // --force re-copies template files over existing ones (.env excepted —
-    // it was just written with real credentials).
+    // Copy the template (whatever it contains, recursively), recording a
+    // per-file baseline in .decanter-template.json. Re-init is modification-aware:
+    // pristine files can be refreshed (after confirm), locally-edited files are
+    // left alone with drift reported, and `--force` overwrites everything. `.env`
+    // 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.
-    const overwritten = copyTemplate(TEMPLATE_DIR, dir, { force, protect: new Set([envFile]) });
-    log.info(`copied template -> ${dir}`);
-    for (const rel of overwritten)
-        log.warn(`--force: overwrote ${rel} with the template version`);
+    await refreshTemplate(TEMPLATE_DIR, dir, { force, protect: new Set([envFile]), version: cliVersion() }, log);
     const configFile = path.join(dir, "decanter.config.json");
     if (!existsSync(configFile)) {
         writeFileSync(configFile, JSON.stringify({ root: "./workflows", workflows: [] }, null, 2) + "\n");
@@ -124,10 +245,10 @@ export async function init(targetDir, { force = false } = {}, log) {
     }
     const gitignoreFile = path.join(dir, ".gitignore");
     if (!existsSync(gitignoreFile)) {
-        // executions/ holds fetched run data (may contain credentials/PII);
-        // belt-and-braces with the self-ignoring executions/.gitignore the
-        // `executions` verb writes into pre-existing sync dirs
-        writeFileSync(gitignoreFile, "node_modules/\n.env\nworkflows/*/executions/\n");
+        // executions/ and data-tables/ hold fetched data (may contain
+        // credentials/PII); belt-and-braces with the self-ignoring .gitignore each
+        // fetch verb writes into pre-existing sync dirs
+        writeFileSync(gitignoreFile, "node_modules/\n.env\nworkflows/*/executions/\ndata-tables/\n");
         log.info("wrote .gitignore");
     }
     else if (!readFileSync(gitignoreFile, "utf8").split("\n").some((l) => l.trim() === ".env")) {

package/dist/lib/lifecycle.mjs

@@ -1,8 +1,11 @@
+import { readFileSync } from "node:fs";
 import path from "node:path";
 import { createPrompt } from "./prompt.mjs";
 import { pullWorkflow } from "./pull.mjs";
+import { assertCompliant, buildNodeCode } from "./push.mjs";
 import { findWorkflowDir } from "./state.mjs";
-import { publicationState } from "./util.mjs";
+import { isJsCodeNode, placeholderFile, publicationState, sanitizeForPut } from "./util.mjs";
+import { validateWorkflowDir } from "./validate.mjs";
 /**
  * `publish` — take an unpublished draft live (n8n 2.x activate). A workflow
  * that is already published is a no-op-with-a-note, not an error: a push to a
@@ -39,13 +42,47 @@ export async function unpublishWorkflow(api, id, log) {
  * Plan 21's `duplicate`.
  */
 export async function createWorkflow(api, config, name, log) {
-    const created = await api.createWorkflow(name);
+    const created = await api.createWorkflow({ name, nodes: [], connections: {}, settings: {} });
     const id = created.id;
     log.ok(`created "${name}" (${id}) on the server — unpublished draft`);
     const { dir } = await pullWorkflow(api, config.root, id, { commitOnPull: config.commitOnPull }, log);
     log.info(`edit code/, push, then "publish" to go live`);
     return { dir, id };
 }
+/**
+ * `<ref> duplicate ["<new name>"]` — clone an already-pulled workflow into a
+ * brand-new remote one, then pull the copy. The body is assembled from the
+ * **local** folder exactly as `push` does (placeholders reconstituted from
+ * `code/`, `.ts` nodes compiled), so the clone carries the repo's current
+ * content — even edits not yet pushed to the source. The default name is
+ * `"<name> (copy)"` (matching the n8n UI). Born **unpublished**, like any
+ * create; the source folder and the source remote workflow are left untouched.
+ * Pull-first is preserved: the copy is born server-side and materialized via a
+ * fresh pull. Reuses `api.createWorkflow` (Plan 20) with a full body.
+ */
+export async function duplicateWorkflow(api, config, id, newName, log) {
+    const dir = findWorkflowDir(config.root, id, log);
+    if (!dir)
+        throw new Error(`workflow ${id} not found under ${config.root} — pull it first`);
+    assertCompliant(validateWorkflowDir(dir), log, `"${path.basename(dir)}"`);
+    const wf = JSON.parse(readFileSync(path.join(dir, "workflow.json"), "utf8"));
+    const sourceName = wf.name;
+    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;
+    }
+    const body = sanitizeForPut(wf);
+    body.name = newName?.trim() || `${sourceName} (copy)`;
+    const created = await api.createWorkflow(body);
+    log.ok(`duplicated "${sourceName}" -> "${body.name}" (${created.id}) on the server — unpublished draft`);
+    const { dir: newDir } = await pullWorkflow(api, config.root, created.id, { commitOnPull: config.commitOnPull }, log);
+    log.info(`edit code/, push, then "publish" to go live`);
+    return { dir: newDir, id: created.id };
+}
 /**
  * `<ref> delete` — hard-delete a workflow from the server, deliberately.
  * Destructive and outward-facing, so consent is explicit: on a TTY a `y/N`