n8n-decanter 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -7,6 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-07-20
+
+### Fixed
+
+- **Globally-installed CLI (`npm i -g n8n-decanter`) could crash on
+  `push`/`check`/`watch`'s typecheck gate** — it resolved the `typescript`
+  package relative to its own install location instead of the sync dir
+  being checked, which only ever worked when the CLI happened to be nested
+  inside the sync dir's `node_modules` (e.g. a local `devDependency`
+  install). A global install is never nested there, so the gate could fail
+  to find `typescript` at all. Now resolved relative to the sync dir first,
+  falling back to the CLI's own location.
+
+## [0.3.1] - 2026-07-20
+
+### Added
+
+- **`publish` / `unpublish` verbs** close the n8n 2.x workflow lifecycle from
+  the CLI: `n8n-decanter <ref> publish` takes a draft live, `unpublish` returns
+  it to draft-only. Already-in-that-state is a no-op with a note, not an error.
+  A staged rollout is now `unpublish` → `push` → `publish` without leaving the
+  terminal.
+- **`create` verb** — `n8n-decanter create "<name>"` creates a blank workflow
+  on the server (born unpublished) and immediately pulls it, so the folder and
+  the new id are ready to edit → push → `publish`.
+- **`delete` verb** — `n8n-decanter <ref> delete` removes a workflow from the
+  server. It asks for a `y/N` confirmation naming the workflow; non-interactive
+  runs require `--force`. The **local folder is left untouched** as the
+  git-tracked record, and a stale `decanter.config.json` `workflows` entry is
+  flagged. Requires a ref (never deletes config workflows by default), one at a
+  time.
+
+### Changed
+
+- **`status` is version-aware.** On a published workflow whose draft has moved
+  ahead of the live version (a UI edit not yet published), `status` now says
+  the live version is older than the draft (`push` or `publish` to catch it
+  up) instead of the plain `published` note.
+- **`executions` warns on stale fixtures.** When a fetched execution ran a
+  published version different from your local draft, the fetch now warns that
+  the captured data may not match the code you're editing (still written — a
+  warning, not an error).
+- The recommended **scoped API key** now includes `workflow:create`,
+  `workflow:delete`, `workflow:activate`, and `workflow:deactivate` so the new
+  lifecycle verbs work (`README`, `.env.example`).
+
 ## [0.3.0] - 2026-07-20
 
 ### Security

package/README.md

@@ -2,14 +2,20 @@
 
 [![CI](https://github.com/buttjer/n8n-decanter/actions/workflows/ci.yml/badge.svg)](https://github.com/buttjer/n8n-decanter/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/n8n-decanter)](https://www.npmjs.com/package/n8n-decanter)
+[![Docs](https://img.shields.io/badge/docs-website-blue.svg)](https://buttjer.github.io/n8n-decanter/)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 **Work on n8n like a codebase — built for AI coding agents.**
 
+**Pre-1.0 — breaking changes to the data model or CLI may ship in minor
+versions until v1.0.**
+
 n8n-decanter syncs your n8n instance into a git-friendly, folder-per-workflow
 layout: every Code node's source becomes its own `.js` or `.ts` file,
 editable in your IDE or by your agent, and pushed back through the n8n API.
 
+![Terminal demo — the interactive picker: filter workflows, choose a verb, sync](./docs/terminal-demo.gif)
+
 - **Real version control** — meaningful diffs, PRs, blame; every push and
   pull is auto-committed.
 - **TypeScript or typed JS** — write nodes in TS (compiled on push); n8n
@@ -33,7 +39,9 @@ editable in your IDE or by your agent, and pushed back through the n8n API.
   behavior that touches the API is verified against a real n8n 2.x instance
   by an automated integration suite.
 
-![VS Code Screenshot](./docs/screenshot.webp)
+![Agent demo — a coding agent edits a Code node, tests it offline, then pushes live](./docs/agent-demo.gif)
+
+📖 **Full documentation: [buttjer.github.io/n8n-decanter](https://buttjer.github.io/n8n-decanter/)**
 
 ## Setup
 
@@ -72,6 +80,8 @@ limited to the permissions the CLI actually uses rather than a full-access one,
 so a leaked `.env` has a small blast radius:
 
 - `workflow:read`, `workflow:list`, `workflow:update` — `pull` / `status` / `push`
+- `workflow:create`, `workflow:delete` — `create` / `delete`
+- `workflow:activate`, `workflow:deactivate` — `publish` / `unpublish`
 - `execution:read`, `execution:list` — the `executions` verb
 
 A full-access key also works if your n8n version predates scoped keys.
@@ -110,6 +120,12 @@ n8n-decanter <ref> rename "<old node>" "<new node>"   # rename a node everywhere
 n8n-decanter <ref> rename --workflow "<new name>"     # rename the workflow
 n8n-decanter [ref] watch            # push a workflow's nodes on save
                                     #   (+ browser live-reload, opt-in)
+n8n-decanter [ref...] publish       # take the draft(s) live
+n8n-decanter [ref...] unpublish     #   (unpublish returns to draft-only)
+n8n-decanter create "<name>"        # create a blank workflow, then pull it
+n8n-decanter <ref> delete [--force]   # delete a workflow from the server
+                                    #   (y/N confirm; --force skips it; the
+                                    #   local folder is left untouched)
 n8n-decanter [ref...] executions [--status=success|error|waiting] [--limit=N]
                                     # fetch recent execution data (run JSON)
                                     #   into workflows/<Name>/executions/
@@ -209,9 +225,13 @@ already run, so Claude Code on a Claude subscription needs no extra API tokens.
   update through the API** (pushing to an *unpublished* workflow only updates
   its draft). This is an n8n API limitation, not decanter's; decanter surfaces
   the outcome — push prints `published: code is live now` vs `unpublished:
-  draft only`, and `status`/`watch` show the state. For a staged rollout,
-  unpublish → push → publish (triggers are down in between), or push to a
-  staging-copy workflow.
+  draft only`, and `status`/`watch` show the state. The **`publish`** and
+  **`unpublish`** verbs take a draft live / return it to draft-only from the
+  CLI, so a staged rollout is `unpublish` → `push` → `publish` (triggers are
+  down in between) without leaving the terminal, or push to a staging-copy
+  workflow. On a published workflow whose draft has moved ahead in the UI,
+  `status` says the live version is older than the draft (`push` or `publish`
+  to catch it up).
 - **n8n's optimistic locking isn't reachable through the API.** That same `PUT`
   also forces `forceSave: true` and exposes no version checksum, so the server
   won't reject a stale write. Decanter's **drift guard** is the only thing

package/dist/lib/api.mjs

@@ -48,6 +48,32 @@ export class N8nApi {
     async updateWorkflow(id, body) {
         return this.#request("PUT", `/api/v1/workflows/${encodeURIComponent(id)}`, body);
     }
+    /**
+     * Create a blank draft on the server (n8n 2.x `POST /workflows`). The minimal
+     * accepted body is name + empty nodes/connections/settings (verified against
+     * 2.30.7 — name-only is rejected). Born **unpublished** (`active:false`); the
+     * caller pulls the returned id so the folder + state land. `createWorkflow` is
+     * the shared entry point Plan 21's `duplicate` reuses.
+     */
+    async createWorkflow(name) {
+        return this.#request("POST", "/api/v1/workflows", { name, nodes: [], connections: {}, settings: {} });
+    }
+    /** Take the draft live (n8n 2.x publish). Idempotent server-side; returns the workflow. */
+    async activateWorkflow(id) {
+        return this.#request("POST", `/api/v1/workflows/${encodeURIComponent(id)}/activate`);
+    }
+    /** Return a published workflow to draft-only. Idempotent server-side; returns the workflow. */
+    async deactivateWorkflow(id) {
+        return this.#request("POST", `/api/v1/workflows/${encodeURIComponent(id)}/deactivate`);
+    }
+    /**
+     * Hard-delete a workflow (n8n 2.x `DELETE /workflows/:id`). Verified to delete
+     * even a *published* workflow outright (no refusal, no archive), so the CLI's
+     * confirmation gate is the only guard. Returns the deleted workflow.
+     */
+    async deleteWorkflow(id) {
+        return this.#request("DELETE", `/api/v1/workflows/${encodeURIComponent(id)}`);
+    }
     async #request(method, pathname, body) {
         try {
             // The signal also covers body consumption, so a stalled response

package/dist/lib/executions.mjs

@@ -1,7 +1,37 @@
-import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { findWorkflowDir, listWorkflowDirs } from "./state.mjs";
 export const EXECUTIONS_DIR = "executions";
+/**
+ * Warn when fetched executions ran a *published* version that differs from the
+ * local draft (`workflow.json`'s `versionId`) — the captured data may not match
+ * the code you're now editing (PLAN.md's "convenience data, not ground truth"
+ * caveat, enforced). A warning, not an error: the data is still useful. Deduped
+ * 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) {
+    const wfFile = path.join(dir, "workflow.json");
+    if (!existsSync(wfFile))
+        return;
+    let draft;
+    try {
+        draft = JSON.parse(readFileSync(wfFile, "utf8")).versionId;
+    }
+    catch {
+        return; // unparsable workflow.json — nothing to compare against
+    }
+    if (typeof draft !== "string")
+        return;
+    const stale = new Set();
+    for (const exec of executions) {
+        if (typeof exec.workflowVersionId === "string" && exec.workflowVersionId !== draft)
+            stale.add(exec.workflowVersionId);
+    }
+    for (const ran of stale) {
+        log.warn(`captured executions ran published version ${ran}; your draft is ${draft} — the data may not match the code you're editing`);
+    }
+}
 /**
  * Materialize execution JSON under `<workflow>/executions/`. The dir is made
  * self-ignoring via an `executions/.gitignore` containing `*` — execution
@@ -30,6 +60,7 @@ export async function fetchExecutions(api, root, workflowId, { status, limit },
         return;
     }
     writeExecutionFiles(dir, executions, log);
+    warnStaleFixtures(dir, executions, log);
     log.ok(`${executions.length} execution${executions.length === 1 ? "" : "s"} -> ${path.relative(process.cwd(), path.join(dir, EXECUTIONS_DIR))} (gitignored — temp data, "executions clean" removes it)`);
 }
 /**
@@ -45,6 +76,7 @@ export async function fetchExecutionById(api, root, executionId, log) {
     if (!dir)
         throw new Error(`execution ${executionId} belongs to workflow ${workflowId}, which is not pulled under ${root} — pull it first`);
     writeExecutionFiles(dir, [exec], log);
+    warnStaleFixtures(dir, [exec], log);
     log.ok(`execution ${executionId} -> ${path.relative(process.cwd(), path.join(dir, EXECUTIONS_DIR))}`);
 }
 /**

package/dist/lib/lifecycle.mjs

@@ -0,0 +1,86 @@
+import path from "node:path";
+import { createPrompt } from "./prompt.mjs";
+import { pullWorkflow } from "./pull.mjs";
+import { findWorkflowDir } from "./state.mjs";
+import { publicationState } from "./util.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
+ * published workflow auto-publishes anyway. Needs credentials (not offline).
+ */
+export async function publishWorkflow(api, id, log) {
+    const before = await api.getWorkflow(id);
+    if (publicationState(before) === "published") {
+        log.info(`"${before.name}" (${id}) is already published — code is live (pushes auto-publish)`);
+        return;
+    }
+    await api.activateWorkflow(id);
+    log.ok(`published "${before.name}" (${id}) — code is live now`);
+}
+/**
+ * `unpublish` — return a published workflow to draft-only (n8n 2.x deactivate).
+ * Already-unpublished is a no-op-with-a-note. Needs credentials (not offline).
+ */
+export async function unpublishWorkflow(api, id, log) {
+    const before = await api.getWorkflow(id);
+    if (publicationState(before) === "unpublished") {
+        log.info(`"${before.name}" (${id}) is already unpublished — draft only`);
+        return;
+    }
+    await api.deactivateWorkflow(id);
+    log.ok(`unpublished "${before.name}" (${id}) — draft only`);
+}
+/**
+ * `create "<name>"` — a blank draft born on the server, then pulled so the
+ * folder + `.decanter.json` land and the id is printed. Born **unpublished**
+ * (`publish` takes it live), so create → edit → push → publish is a full CLI
+ * loop. The server still assigns the id and owns the birth (PLAN.md's "born in
+ * n8n" rule holds); the CLI only triggers it. Shares `api.createWorkflow` with
+ * Plan 21's `duplicate`.
+ */
+export async function createWorkflow(api, config, name, log) {
+    const created = await api.createWorkflow(name);
+    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> delete` — hard-delete a workflow from the server, deliberately.
+ * Destructive and outward-facing, so consent is explicit: on a TTY a `y/N`
+ * prompt naming the workflow; non-interactive runs require `--force` and abort
+ * without it. The **local folder is never touched** — it stays as the
+ * git-tracked record — and a stale `decanter.config.json` `workflows` entry is
+ * flagged. One workflow per call (the dispatcher enforces exactly one ref).
+ */
+export async function deleteWorkflow(api, config, id, { force = false } = {}, log) {
+    const remote = await api.getWorkflow(id); // authoritative name + proof it exists
+    const name = remote.name;
+    if (!force) {
+        if (!process.stdin.isTTY) {
+            throw new Error(`refusing to delete "${name}" (${id}) without confirmation — re-run with --force to delete in a non-interactive session`);
+        }
+        const rl = createPrompt();
+        let answer;
+        try {
+            answer = (await rl.question(`Delete workflow "${name}" (${id}) from the n8n server? This cannot be undone. [y/N] `)).trim().toLowerCase();
+        }
+        finally {
+            rl.close();
+        }
+        if (answer !== "y" && answer !== "yes") {
+            log.info("aborted — nothing deleted");
+            return;
+        }
+    }
+    await api.deleteWorkflow(id);
+    log.ok(`deleted "${name}" (${id}) from the server`);
+    const dir = findWorkflowDir(config.root, id, log);
+    if (dir) {
+        log.info(`local folder ${path.relative(process.cwd(), dir) || "."} left untouched — it's your git-tracked record`);
+    }
+    if (config.workflows.includes(id)) {
+        log.warn(`${id} is still listed in decanter.config.json "workflows" — remove it so pull/push/status stop targeting it`);
+    }
+}

package/dist/lib/picker.mjs

@@ -2,8 +2,9 @@
 // inited project. Two stages — type-to-filter workflow list (pulled green,
 // unpulled remote yellow), then a verb menu; unpulled entries pull directly.
 // The pure state machine (filter, reducer, window) is exported for unit
-// tests; only runPicker touches the terminal. Exists only behind a TTY gate,
-// so piped output never sees any of this.
+// tests; runPicker's terminal IO takes injectable input/output streams
+// (Plan 22) so test/interactive.mts can drive it without a real pty. Exists
+// only behind a TTY gate at the CLI, so piped output never sees any of this.
 import { emitKeypressEvents } from "node:readline";
 import { style } from "./style.mjs";
 /** Verb menu for a pulled workflow, in display order. */
@@ -96,7 +97,7 @@ function reduceVerbKey(state, key) {
     }
     return { done: false, state };
 }
-// ---------- terminal IO (TTY only, untested by CI — keep this part thin) ----------
+// ---------- terminal IO (covered by test/interactive.mts via injected streams) ----------
 const LIST_HEIGHT = 10;
 // Placeholder rows shown where remote workflows will appear while the list
 // loads: light-gray blocks shaped like "name  id", varied widths on purpose.
@@ -144,33 +145,35 @@ function renderLines(state) {
  * already in flight; its workflows are appended as they arrive. `resume`
  * re-opens a workflow's verb menu (the picker loop passes the last run).
  * Resolves with the chosen verb+id+name, or "quit" (Esc) / "interrupted"
- * (Ctrl-C).
+ * (Ctrl-C). `input`/`output` default to the real TTY streams — tests inject
+ * a `PassThrough` pair instead of needing a real pty (no new dependency).
  */
 export async function runPicker(local, remote, opts = {}) {
+    const input = opts.input ?? process.stdin;
+    const output = opts.output ?? process.stdout;
     let state = initialState(local, remote !== undefined, opts);
     let prevLines = 0;
     const repaint = () => {
         const lines = renderLines(state);
         const up = prevLines > 0 ? `\x1b[${prevLines}A` : "";
-        process.stdout.write(`${up}\r\x1b[J${lines.join("\n")}\n`);
+        output.write(`${up}\r\x1b[J${lines.join("\n")}\n`);
         prevLines = lines.length;
     };
     const erase = () => {
         if (prevLines > 0)
-            process.stdout.write(`\x1b[${prevLines}A\r\x1b[J`);
+            output.write(`\x1b[${prevLines}A\r\x1b[J`);
         prevLines = 0;
     };
-    const stdin = process.stdin;
-    emitKeypressEvents(stdin);
-    const wasRaw = stdin.isRaw === true;
+    emitKeypressEvents(input);
+    const wasRaw = input.isRaw === true;
     const restore = () => {
         if (!wasRaw)
-            stdin.setRawMode(false);
-        process.stdout.write("\x1b[?25h");
+            input.setRawMode?.(false);
+        output.write("\x1b[?25h");
     };
-    stdin.setRawMode(true);
-    stdin.resume();
-    process.stdout.write("\x1b[?25l");
+    input.setRawMode?.(true);
+    input.resume();
+    output.write("\x1b[?25l");
     process.once("exit", restore); // belt and braces: never leave the terminal raw
     let finished = false;
     let onKeypress;
@@ -183,7 +186,7 @@ export async function runPicker(local, remote, opts = {}) {
                 finished = true;
                 resolve("quit");
             };
-            stdin.once("end", onEnd);
+            input.once("end", onEnd);
             onKeypress = (_str, key) => {
                 const step = reduceKey(state, key ?? {});
                 if (step.done) {
@@ -208,19 +211,19 @@ export async function runPicker(local, remote, opts = {}) {
                 state = { ...state, loadingRemote: false, notice: `remote list unavailable (${err.message.split("\n")[0]})` };
                 repaint();
             });
-            stdin.on("keypress", onKeypress);
+            input.on("keypress", onKeypress);
             repaint();
         });
     }
     finally {
         finished = true;
         if (onKeypress)
-            stdin.removeListener("keypress", onKeypress);
+            input.removeListener("keypress", onKeypress);
         if (onEnd)
-            stdin.removeListener("end", onEnd);
+            input.removeListener("end", onEnd);
         erase();
         restore();
         process.removeListener("exit", restore);
-        stdin.pause();
+        input.pause();
     }
 }

package/dist/lib/pull.mjs

@@ -124,11 +124,15 @@ export async function pullWorkflow(api, root, id, { commitOnPull = false } = {},
     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.
+    // included), sharing metadata (`shared`), and the published-version pointer
+    // (`activeVersionId`) — derived data that would duplicate every node's source
+    // in git and/or churn on each publish. None is pushable (sanitizeForPut
+    // whitelists) and no local command reads them from workflow.json (the
+    // version-aware `status` reads `activeVersionId` straight off the live GET),
+    // so dropping them loses nothing. The draft `versionId` is kept — the
+    // executions stale-fixture warning compares against it.
     delete wfOut.activeVersion;
+    delete wfOut.activeVersionId;
     delete wfOut.shared;
     for (const node of wfOut.nodes) {
         const file = placeholders.get(node.id);

package/dist/lib/status.mjs

@@ -4,7 +4,7 @@ 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";
+import { isJsCodeNode, publicationState, publishedVersionLagsDraft, 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);
@@ -27,7 +27,13 @@ export async function statusWorkflow(api, root, id, log, { diff = false } = {})
     };
     const state = readState(dir);
     const pub = publicationState(remote);
-    log.info(`${remote.name} (${id})  [${path.relative(process.cwd(), dir)}]${pub ? `  ${pub}` : ""}`);
+    // Version-aware note: on a published workflow whose live version lags the
+    // draft (a UI edit not yet published), say so; otherwise the plain state word,
+    // or nothing when the server omits `active` (defensive, mirrors publicationState).
+    const pubNote = publishedVersionLagsDraft(remote)
+        ? `  published — live version is older than the draft (push or "publish" to go live)`
+        : pub ? `  ${pub}` : "";
+    log.info(`${remote.name} (${id})  [${path.relative(process.cwd(), dir)}]${pubNote}`);
     const remoteStruct = workflowStructureHash(remote);
     const wfFile = path.join(dir, "workflow.json");
     const localStruct = existsSync(wfFile)

package/dist/lib/util.mjs

@@ -187,6 +187,21 @@ export function publicationState(wf) {
         return undefined;
     return wf.active ? "published" : "unpublished";
 }
+/**
+ * True when a **published** workflow's live version lags its draft — i.e. the
+ * draft was edited (in the n8n UI) without being published, so the live code is
+ * older than what `pull` would bring down. Compares the n8n 2.x GET fields
+ * `versionId` (draft) and `activeVersionId` (published). Undefined when the
+ * workflow is unpublished or the server omits either field (mocks, exotic
+ * versions) — the same defensive stance as `publicationState`.
+ */
+export function publishedVersionLagsDraft(wf) {
+    if (publicationState(wf) !== "published")
+        return undefined;
+    if (typeof wf?.versionId !== "string" || typeof wf?.activeVersionId !== "string")
+        return undefined;
+    return wf.activeVersionId !== wf.versionId;
+}
 /**
  * Hash of the sanitized, code-stripped workflow — detects structural edits
  * (nodes added/moved/reconnected, settings changed) independent of code edits.

package/dist/lib/watch.mjs

@@ -46,8 +46,15 @@ export function structureAction(localHash, remoteHash, baseline) {
  * With `browserReload: "proxy"` a transparent dev proxy boots first (Plan 5);
  * each successful push signals the browser tab to refresh (notifyPushed in
  * lib/proxy).
+ *
+ * `promptFactory` (default `createPrompt`) supplies the conflict-resolution
+ * prompt — injectable so tests can drive `[m]`/`[l]`/`[r]`/Enter with canned
+ * answers (Plan 22) without a real TTY. Passing one explicitly also bypasses
+ * the non-interactive (`!process.stdin.isTTY`) skip below, since a test
+ * deliberately supplying answers isn't the "no one is there to answer" case
+ * that skip exists for.
  */
-export async function watchWorkflow(api, config, id, { force = false } = {}, log) {
+export async function watchWorkflow(api, config, id, { force = false, promptFactory } = {}, log) {
     const found = findWorkflowDir(config.root, id, log);
     if (!found)
         throw new Error(`workflow ${id} not found under ${config.root} — pull it first`);
@@ -151,11 +158,11 @@ export async function watchWorkflow(api, config, id, { force = false } = {}, log
     /** Interactive conflict resolution; returns true when the workflow got fully synced. */
     const resolveConflict = async (remote) => {
         log.error("structural conflict: workflow.json and the remote workflow both changed since last sync");
-        if (!process.stdin.isTTY) {
+        if (!promptFactory && !process.stdin.isTTY) {
             log.error("non-interactive session — skipped the structural push; pull (or push --force) to resolve");
             return false;
         }
-        const rl = createPrompt();
+        const rl = (promptFactory ?? createPrompt)();
         let choice;
         try {
             choice = (await rl.question(`  [m]erge  — write ${remoteJsonRel} for manual reconciliation\n` +

package/dist/n8n-decanter.mjs

@@ -5,6 +5,7 @@ import { N8nApi } from "./lib/api.mjs";
 import { loadConfig } from "./lib/config.mjs";
 import { cleanExecutions, fetchExecutionById, fetchExecutions } from "./lib/executions.mjs";
 import { init, printBanner } from "./lib/init.mjs";
+import { createWorkflow, deleteWorkflow, publishWorkflow, unpublishWorkflow } from "./lib/lifecycle.mjs";
 import { mergeRemote, runPicker } from "./lib/picker.mjs";
 import { pullWorkflow } from "./lib/pull.mjs";
 import { pushWorkflow } from "./lib/push.mjs";
@@ -51,6 +52,11 @@ const usage = () => {
   ${b("n8n-decanter")} [ref...] ${b("check")} [--no-typecheck]   ${d("offline layout-compliance check")}
   ${b("n8n-decanter")} <ref> ${b("rename")} "<old node>" "<new node>"   ${d("rename a node everywhere (offline)")}
   ${b("n8n-decanter")} <ref> ${b("rename")} --workflow "<new name>"     ${d("rename the workflow itself")}
+  ${b("n8n-decanter")} [ref...] ${b("publish")}     ${d("take the draft(s) live (unpublish returns to draft-only)")}
+  ${b("n8n-decanter")} [ref...] ${b("unpublish")}
+  ${b("n8n-decanter create")} "<name>"     ${d("create a blank workflow on the server, then pull it")}
+  ${b("n8n-decanter")} <ref> ${b("delete")} [--force]   ${d("delete a workflow from the server (y/N confirm;")}
+                                   ${d("--force skips it; the local folder is left untouched)")}
   ${b("n8n-decanter")} [ref] ${b("watch")} [--force]   ${d("watch code/ + workflow.json, push on save")}
                                    ${d("(starts with a safety commit + pull; structural")}
                                    ${d("conflicts prompt; browser live-reload optional)")}
@@ -75,9 +81,9 @@ and flags may appear in any position too.
 Config: decanter.config.json (searched upward from cwd), credentials from .env
 next to it or the environment (N8N_HOST, N8N_API_KEY).`;
 };
-const VERBS = new Set(["init", "pull", "push", "status", "check", "rename", "watch", "run", "uuid", "list", "executions", "completion", "__complete", "help"]);
+const VERBS = new Set(["init", "pull", "push", "status", "check", "rename", "watch", "run", "uuid", "list", "executions", "publish", "unpublish", "create", "delete", "completion", "__complete", "help"]);
 /** Verbs whose workflow arguments go through name resolution. */
-const REF_VERBS = new Set(["pull", "push", "status", "check", "watch"]);
+const REF_VERBS = new Set(["pull", "push", "status", "check", "watch", "publish", "unpublish", "delete"]);
 // Both scripts delegate to the hidden `__complete` verb at completion time,
 // so candidates stay current without regenerating the script.
 const COMPLETION_SCRIPTS = {
@@ -445,6 +451,44 @@ async function dispatch(command, rest, flags) {
                 process.exitCode = 1;
             break;
         }
+        case "publish":
+        case "unpublish": {
+            if (ids.length === 0) {
+                throw new Error('no workflow ids: pass them as arguments or list them in decanter.config.json "workflows"');
+            }
+            let failed = false;
+            for (const id of ids) {
+                try {
+                    if (command === "publish")
+                        await publishWorkflow(api, id, log);
+                    else
+                        await unpublishWorkflow(api, id, log);
+                }
+                catch (err) {
+                    failed = true;
+                    log.error(`${id}: ${err.message}`);
+                }
+            }
+            if (failed)
+                process.exitCode = 1;
+            break;
+        }
+        case "create": {
+            if (rest.length !== 1)
+                throw new Error('create needs exactly one name: n8n-decanter create "<name>"');
+            await createWorkflow(api, config, rest[0], log);
+            break;
+        }
+        case "delete": {
+            // Deliberately never falls back to config.workflows — a ref is required,
+            // one workflow per call (no cascade, too much blast radius for a default).
+            if (refs.length === 0)
+                throw new Error("delete needs a workflow ref: n8n-decanter <ref> delete");
+            if (refs.length > 1)
+                throw new Error("delete takes exactly one workflow — delete them one at a time");
+            await deleteWorkflow(api, config, refs[0], { force }, log);
+            break;
+        }
         case "rename": {
             const [id, ...names] = refs;
             if (!id)

package/dist/scripts/typecheck.mjs

@@ -5,10 +5,28 @@
 // in memory only — files on disk stay verbatim — and maps diagnostic line
 // numbers back. Node files are recognized by a .decanter.json sibling, or —
 // code/ layout — one in the parent of their code/ dir.
+import { createRequire } from "node:module";
 import path from "node:path";
-import ts from "typescript";
 import { scanNodeImports } from "../lib/compile.mjs";
 import { nodeFileContextDir } from "../lib/state.mjs";
+// `typescript` is a devDependency of *this* package, never a runtime one —
+// a plain `import ts from "typescript"` resolves relative to this script's
+// own location, which for a globally-installed CLI is nowhere near the sync
+// dir being typechecked, so it can never find the sync dir's scaffolded
+// `typescript` devDependency (plans/13). Resolve from cwd (the sync dir —
+// lib/validate.mts spawns this script with cwd set to it) first, falling
+// back to this script's own location for setups where the sync dir has no
+// `typescript` of its own (e.g. this repo's own dev/test tree, where the
+// CLI's own node_modules carries it).
+function resolveTypescript() {
+    try {
+        return createRequire(path.join(process.cwd(), "package.json"))("typescript");
+    }
+    catch {
+        return createRequire(import.meta.url)("typescript");
+    }
+}
+const ts = resolveTypescript();
 const PREFIX = "async function __n8nNode() {\n";
 const SUFFIX = "\n}\nvoid __n8nNode;\n";
 // Optional dir arguments scope the *output*: the whole project is still

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-decanter",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Work on n8n like a codebase — built for AI coding agents",
   "keywords": [
     "n8n",
@@ -33,7 +33,7 @@
     "build": "tsc -p tsconfig.build.json",
     "prepack": "npm run build",
     "typecheck": "tsc -p tsconfig.cli.json && node scripts/typecheck.mts",
-    "test": "node --test 'test/unit/*.test.mts' && node test/e2e.mts && node test/proxy.mts",
+    "test": "node --test 'test/unit/*.test.mts' && node test/e2e.mts && node test/proxy.mts && node test/interactive.mts",
     "test:smoke": "node test/smoke-n8n.mts"
   },
   "engines": {

package/template/.env.example

@@ -4,7 +4,9 @@ N8N_HOST=https://your-n8n.example.com
 # Prefer a SCOPED API key (n8n → Settings → n8n API → Create) limited to the
 # permissions this tool actually uses, not a full-access key — smaller blast
 # radius if .env leaks:
-#   workflow:read  workflow:list  workflow:update    (pull / status / push)
-#   execution:read  execution:list                   (executions)
+#   workflow:read  workflow:list  workflow:update       (pull / status / push)
+#   workflow:create  workflow:delete                     (create / delete)
+#   workflow:activate  workflow:deactivate               (publish / unpublish)
+#   execution:read  execution:list                       (executions)
 # A full-access key also works.
 N8N_API_KEY=n8n_api_...

package/template/AGENTS.md.example

@@ -36,9 +36,13 @@ runtime. It is **wrong** about how code is stored here. The deviations:
    pushes. Never edit `.remote.js` itself; never push while one exists.
 6. **Renames have no UI magic here.** The n8n editor auto-updates references on
    rename; raw JSON editing does not. See the rename checklist below.
-7. **New workflows are born in n8n, not here.** The tool has no create. To add a
-   workflow: create it (even empty) in the n8n UI, add its id to
-   `decanter.config.json`, then the user runs `pull`.
+7. **New workflows are born on the server, not from a repo folder.** There is no
+   id-less folder that becomes a workflow on push. Use `n8n-decanter create
+   "<name>"` — it posts a blank draft to n8n and pulls it back (the server
+   assigns the id) — or create it in the n8n UI and `pull`. Then add its id to
+   `decanter.config.json`. A created workflow is **unpublished**; `publish`
+   takes it live, `unpublish` returns it to draft-only, and `<ref> delete`
+   removes one from the server (the local folder is kept).
 
 > **Enforcement.** Rules 1, 3, 4, 5 are *hard invariants* — violating them corrupts
 > sync state. They are enforced by the CLI at `push` time regardless of who made the
@@ -295,8 +299,17 @@ Rules:
   (fetches execution data, read-only) — safe to run, but they do contact the
   instance.
 - **Live n8n instance — only when the user explicitly asks:** `n8n-decanter
-  pull` / `push` / `watch` read/write the real instance and `push` deploys.
-  Otherwise finish edits, verify with `check` + `run`, and report that the
-  change is ready to push.
+  pull` / `push` / `watch` read/write the real instance and `push` deploys;
+  `create "<name>"` adds a new workflow, and `publish` / `unpublish` change what
+  is live (`publish` takes the draft live immediately, `unpublish` returns it to
+  draft-only). Otherwise finish edits, verify with `check` + `run`, and report
+  that the change is ready to push (or publish).
+- **Destructive — never without an explicit instruction:** `n8n-decanter <ref>
+  delete` removes a workflow from the server (hard delete, even if published;
+  the local folder is kept as the git record). Run it only when the user has
+  clearly asked to delete that specific workflow; it prompts for `y/N` and needs
+  `--force` to run non-interactively.
 - Never use `--force` on push without the user's explicit instruction — it
-  overrides the drift guard that protects edits made in the n8n UI.
+  overrides the drift guard that protects edits made in the n8n UI. (On
+  `delete`, `--force` instead means "skip the confirmation" — same rule: only
+  on an explicit instruction.)