n8n-decanter 0.3.0

package/dist/lib/config.mjs

@@ -0,0 +1,61 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+/** Parse KEY=VALUE lines (optional `export`, quotes stripped) from an env file. */
+export function parseEnvFile(file) {
+    const values = {};
+    if (!existsSync(file))
+        return values;
+    for (const line of readFileSync(file, "utf8").split("\n")) {
+        const m = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
+        if (!m || m[0].trimStart().startsWith("#"))
+            continue;
+        values[m[1]] = m[2].replace(/^(['"])(.*)\1$/, "$2");
+    }
+    return values;
+}
+/** Load .env (if present) into process.env, not overriding existing vars. */
+export function loadEnv(dir) {
+    for (const [key, value] of Object.entries(parseEnvFile(path.join(dir, ".env")))) {
+        if (process.env[key] === undefined)
+            process.env[key] = value;
+    }
+}
+/** Load decanter.config.json from cwd (or nearest ancestor) and resolve paths. */
+export function loadConfig(cwd = process.cwd(), { requireCredentials = true } = {}) {
+    let dir = path.resolve(cwd);
+    for (;;) {
+        const file = path.join(dir, "decanter.config.json");
+        if (existsSync(file)) {
+            let parsed;
+            try {
+                parsed = JSON.parse(readFileSync(file, "utf8"));
+            }
+            catch (err) {
+                throw new Error(`${file}: invalid JSON (${err.message})`);
+            }
+            const cfg = parsed;
+            loadEnv(dir);
+            const host = (process.env.N8N_HOST ?? "").replace(/\/+$/, "");
+            const apiKey = process.env.N8N_API_KEY ?? "";
+            if (requireCredentials && (!host || !apiKey)) {
+                throw new Error("N8N_HOST and N8N_API_KEY must be set (via .env next to decanter.config.json or the environment)");
+            }
+            return {
+                configDir: dir,
+                root: path.resolve(dir, cfg.root ?? "./workflows"),
+                workflows: cfg.workflows ?? [],
+                commitOnPush: cfg.commitOnPush !== false,
+                commitOnPull: cfg.commitOnPull !== false,
+                browserReload: cfg.browserReload === "proxy" ? "proxy" : "off",
+                proxyPort: typeof cfg.proxyPort === "number" ? cfg.proxyPort : 5679,
+                requestTimeoutMs: typeof cfg.requestTimeoutMs === "number" && cfg.requestTimeoutMs > 0 ? cfg.requestTimeoutMs : 30_000,
+                host,
+                apiKey,
+            };
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            throw new Error("decanter.config.json not found (searched from " + cwd + " upward)");
+        dir = parent;
+    }
+}

package/dist/lib/diff.mjs

@@ -0,0 +1,74 @@
+// Minimal unified line diff for `status --diff` (plans/3 B). Zero deps by
+// design (Plan 11's rule); classic LCS backtracking is plenty at Code-node
+// scale, with a size cutoff instead of a fancier algorithm.
+function toLines(s) {
+    if (s === "")
+        return [];
+    const lines = s.split("\n");
+    if (lines[lines.length - 1] === "")
+        lines.pop(); // trailing newline is not a line
+    return lines;
+}
+/**
+ * Unified-style diff of `a` (rendered as `-`) vs `b` (`+`), with `@@` hunk
+ * headers and `context` unchanged lines around each change. Returns [] when
+ * the inputs are line-identical. The hunk numbers are informational — this
+ * diff is for reading, not for `patch`.
+ */
+export function unifiedDiff(a, b, context = 2) {
+    const al = toLines(a);
+    const bl = toLines(b);
+    const n = al.length;
+    const m = bl.length;
+    if (n * m > 4_000_000)
+        return ["(diff too large to render — contents differ)"];
+    // dp[i][j] = LCS length of al[i..] vs bl[j..]
+    const dp = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1));
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            dp[i][j] = al[i] === bl[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (al[i] === bl[j])
+            ops.push({ tag: " ", line: al[i], aLine: ++i, bLine: ++j });
+        else if (dp[i + 1][j] >= dp[i][j + 1])
+            ops.push({ tag: "-", line: al[i], aLine: ++i, bLine: j + 1 });
+        else
+            ops.push({ tag: "+", line: bl[j], aLine: i + 1, bLine: ++j });
+    }
+    while (i < n)
+        ops.push({ tag: "-", line: al[i], aLine: ++i, bLine: j + 1 });
+    while (j < m)
+        ops.push({ tag: "+", line: bl[j], aLine: i + 1, bLine: ++j });
+    const changed = ops.flatMap((op, idx) => (op.tag === " " ? [] : [idx]));
+    if (changed.length === 0)
+        return [];
+    // group changes whose context windows touch into hunks
+    const hunks = [];
+    let start = Math.max(0, changed[0] - context);
+    let end = Math.min(ops.length - 1, changed[0] + context);
+    for (const c of changed.slice(1)) {
+        if (c - context <= end + 1)
+            end = Math.min(ops.length - 1, c + context);
+        else {
+            hunks.push([start, end]);
+            start = Math.max(0, c - context);
+            end = Math.min(ops.length - 1, c + context);
+        }
+    }
+    hunks.push([start, end]);
+    const out = [];
+    for (const [from, to] of hunks) {
+        const slice = ops.slice(from, to + 1);
+        const aCount = slice.filter((o) => o.tag !== "+").length;
+        const bCount = slice.filter((o) => o.tag !== "-").length;
+        out.push(`@@ -${slice[0].aLine},${aCount} +${slice[0].bLine},${bCount} @@`);
+        for (const o of slice)
+            out.push(o.tag + o.line);
+    }
+    return out;
+}

package/dist/lib/executions.mjs

@@ -0,0 +1,76 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { findWorkflowDir, listWorkflowDirs } from "./state.mjs";
+export const EXECUTIONS_DIR = "executions";
+/**
+ * Materialize execution JSON under `<workflow>/executions/`. The dir is made
+ * self-ignoring via an `executions/.gitignore` containing `*` — execution
+ * data can hold credentials/PII and sits inside the commit-on-pull/push
+ * pathspec, so it must never reach git regardless of the sync dir's root
+ * .gitignore (which init scaffolds, but pre-existing dirs won't have).
+ */
+function writeExecutionFiles(dir, executions, log) {
+    const outDir = path.join(dir, EXECUTIONS_DIR);
+    mkdirSync(outDir, { recursive: true });
+    writeFileSync(path.join(outDir, ".gitignore"), "*\n");
+    for (const exec of executions) {
+        const file = path.join(outDir, `${exec.id}.json`);
+        writeFileSync(file, JSON.stringify(exec, null, 2) + "\n");
+        log.info(`wrote ${path.relative(process.cwd(), file)}${exec.status !== undefined ? ` (${exec.status})` : ""}`);
+    }
+}
+/** Fetch recent executions of one workflow into its `executions/` dir. */
+export async function fetchExecutions(api, root, workflowId, { status, limit }, log) {
+    const dir = findWorkflowDir(root, workflowId, log);
+    if (!dir)
+        throw new Error(`workflow ${workflowId} not found under ${root} — pull it first`);
+    const executions = await api.listExecutions({ workflowId, status, limit });
+    if (executions.length === 0) {
+        log.info(`no executions on the server for ${workflowId}${status !== undefined ? ` with status "${status}"` : ""}`);
+        return;
+    }
+    writeExecutionFiles(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)`);
+}
+/**
+ * Fetch one execution by its (numeric) id. The execution's own `workflowId`
+ * decides the target folder — no workflow ref needed on the CLI.
+ */
+export async function fetchExecutionById(api, root, executionId, log) {
+    const exec = await api.getExecution(executionId);
+    const workflowId = typeof exec.workflowId === "string" ? exec.workflowId : undefined;
+    if (workflowId === undefined)
+        throw new Error(`execution ${executionId}: response carries no workflowId — cannot place it`);
+    const dir = findWorkflowDir(root, workflowId, 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);
+    log.ok(`execution ${executionId} -> ${path.relative(process.cwd(), path.join(dir, EXECUTIONS_DIR))}`);
+}
+/**
+ * Delete `executions/` dirs — for the given workflow ids, or every pulled
+ * workflow when none are given. Offline; missing dirs are fine.
+ */
+export function cleanExecutions(root, workflowIds, log) {
+    const dirs = workflowIds.length > 0
+        ? workflowIds.map((id) => {
+            const dir = findWorkflowDir(root, id, log);
+            if (!dir)
+                throw new Error(`workflow ${id} not found under ${root}`);
+            return dir;
+        })
+        : listWorkflowDirs(root);
+    let removed = 0;
+    for (const dir of dirs) {
+        const outDir = path.join(dir, EXECUTIONS_DIR);
+        if (!existsSync(outDir))
+            continue;
+        rmSync(outDir, { recursive: true, force: true });
+        log.info(`removed ${path.relative(process.cwd(), outDir)}`);
+        removed++;
+    }
+    if (removed === 0)
+        log.info("no executions/ dirs to clean");
+    else
+        log.ok(`cleaned ${removed} executions dir${removed === 1 ? "" : "s"}`);
+}

package/dist/lib/git.mjs

@@ -0,0 +1,44 @@
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+const execFile = promisify(execFileCb);
+/**
+ * Best-effort git commit of one workflow folder after a successful sync.
+ * Never fails the sync: no git / not a repo / mid-merge all degrade to a
+ * warning ("failed"); a tree with nothing to commit reports "clean". The
+ * commit is pathspec-scoped to the folder, so staged-but-unrelated changes
+ * elsewhere in the repo stay untouched and unstaged. `extraPaths` (relative
+ * to dir) covers a renamed-away old folder, whose deletions live outside the
+ * new folder's pathspec.
+ */
+export async function commitWorkflowDir(dir, message, log, extraPaths = []) {
+    try {
+        await execFile("git", ["-C", dir, "rev-parse", "--is-inside-work-tree"]);
+    }
+    catch {
+        log.warn('not inside a git repository — skipping commit ("commitOnPush"/"commitOnPull": false silences this)');
+        return "failed";
+    }
+    try {
+        const spec = ["."];
+        for (const p of extraPaths) {
+            // only include extra paths that actually carry changes — an unmatched
+            // pathspec would make add/commit fail
+            const { stdout } = await execFile("git", ["-C", dir, "status", "--porcelain", "--", p]);
+            if (stdout.trim() !== "")
+                spec.push(p);
+        }
+        await execFile("git", ["-C", dir, "add", "-A", "--", ...spec]);
+        const { stdout } = await execFile("git", ["-C", dir, "status", "--porcelain", "--", ...spec]);
+        if (stdout.trim() === "")
+            return "clean"; // nothing changed under this folder
+        await execFile("git", ["-C", dir, "commit", "-m", message, "--", ...spec]);
+        log.info(`committed: ${message}`);
+        return "committed";
+    }
+    catch (err) {
+        const e = err;
+        const detail = (e.stderr || e.message || "").toString().trim().split("\n")[0];
+        log.warn(`git commit failed (${detail}) — push succeeded, commit skipped`);
+        return "failed";
+    }
+}

package/dist/lib/init.mjs

@@ -0,0 +1,152 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseEnvFile } from "./config.mjs";
+import { createPrompt } from "./prompt.mjs";
+import { style } from "./style.mjs";
+/**
+ * Nearest ancestor of `startDir` holding a package.json — the package root.
+ * Works from the checkout (lib/ → repo root) *and* from the published build
+ * (dist/lib/ → package root): dist/ ships no package.json, so a plain
+ * `../template` URL would resolve to the nonexistent dist/template in the
+ * npm tarball (release blocker found 2026-07-18). Exported for tests.
+ */
+export function packageRootFrom(startDir) {
+    let dir = path.resolve(startDir);
+    for (;;) {
+        if (existsSync(path.join(dir, "package.json")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return path.resolve(startDir); // fs root — let the template lookup fail loudly
+        dir = parent;
+    }
+}
+const PACKAGE_ROOT = packageRootFrom(path.dirname(fileURLToPath(import.meta.url)));
+const TEMPLATE_DIR = path.join(PACKAGE_ROOT, "template");
+/** Own package version (banner); tolerant of an unreadable package.json. */
+function cliVersion() {
+    try {
+        return JSON.parse(readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8")).version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+// Wordmark in the 2×2 quadrant-block minifont (Block Elements). The top row's
+// leading offset is load-bearing (ascenders of 8/d/t) — keep it verbatim.
+// Columns 0-5 are the "n8n" part (brand red on a TTY), the rest "decanter".
+const LOGO_ROWS = [
+    "  ▄▖     ▌        ▗",
+    "▛▌▙▌▛▌  ▛▌█▌▛▘▀▌▛▌▜▘█▌▛▘",
+    "▌▌▙▌▌▌  ▙▌▙▖▙▖█▌▌▌▐▖▙▖▌",
+];
+/** TTY: logo + tagline + version. Piped: one plain, stable version line. */
+export function printBanner(log) {
+    const version = cliVersion();
+    if (!process.stdout.isTTY) {
+        log.info(`n8n-decanter v${version}`);
+        return;
+    }
+    for (const row of LOGO_ROWS)
+        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 });
+        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));
+                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 exists = existsSync(destPath);
+            if (exists && (!force || protect.has(destPath)))
+                continue;
+            copyFileSync(srcPath, destPath);
+            if (exists)
+                overwritten.push(path.join(rel, name));
+        }
+    };
+    walk(srcDir, destDir, "");
+    return overwritten;
+}
+/** Interactive bootstrap: prompt for credentials, write .env, copy template/. */
+export async function init(targetDir, { force = false } = {}, log) {
+    printBanner(log);
+    const dir = path.resolve(targetDir ?? ".");
+    mkdirSync(dir, { recursive: true });
+    const envFile = path.join(dir, ".env");
+    const existing = parseEnvFile(envFile);
+    let host = existing.N8N_HOST ?? "";
+    let apiKey = existing.N8N_API_KEY ?? "";
+    if (host && apiKey) {
+        // complete .env → nothing to ask; edit or delete .env to change credentials
+        log.info(`using existing .env (${host})`);
+    }
+    else {
+        const rl = createPrompt();
+        try {
+            host = (await rl.question(`n8n host${host ? ` [${host}]` : ""}: `)).trim() || host;
+            apiKey = (await rl.question(`n8n API key${apiKey ? " [enter = keep existing]" : ""}: `)).trim() || apiKey;
+        }
+        finally {
+            rl.close();
+        }
+        if (!host || !apiKey)
+            throw new Error("host and API key are required");
+        if (!/^https?:\/\//.test(host))
+            host = "https://" + host;
+        host = host.replace(/\/+$/, "");
+        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).
+    // 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`);
+    const configFile = path.join(dir, "decanter.config.json");
+    if (!existsSync(configFile)) {
+        writeFileSync(configFile, JSON.stringify({ root: "./workflows", workflows: [] }, null, 2) + "\n");
+        log.info("wrote decanter.config.json — add your workflow ids to it");
+    }
+    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");
+        log.info("wrote .gitignore");
+    }
+    else if (!readFileSync(gitignoreFile, "utf8").split("\n").some((l) => l.trim() === ".env")) {
+        log.warn(".gitignore exists but does not ignore .env — add it, the file holds your API key");
+    }
+    try {
+        const res = await fetch(`${host}/api/v1/workflows?limit=1`, {
+            headers: { "X-N8N-API-KEY": apiKey, accept: "application/json" },
+            // best-effort probe: fail fast on a black-holed host rather than hanging init
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (res.ok)
+            log.info(`credentials verified against ${host}`);
+        else
+            log.warn(`credential check failed (${res.status} ${res.statusText}) — .env written anyway`);
+    }
+    catch (err) {
+        const e = err;
+        const reason = e.name === "TimeoutError" ? "timed out after 10s" : e.cause?.code ?? e.message;
+        log.warn(`could not reach ${host} (${reason}) — .env written anyway`);
+    }
+}

package/dist/lib/picker.mjs

@@ -0,0 +1,226 @@
+// Interactive workflow picker (Plan 19): bare `n8n-decanter` on a TTY in an
+// 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.
+import { emitKeypressEvents } from "node:readline";
+import { style } from "./style.mjs";
+/** Verb menu for a pulled workflow, in display order. */
+export const PICKER_VERBS = ["status", "pull", "push", "watch", "check", "executions"];
+export function initialState(entries, loadingRemote, opts = {}) {
+    const base = { stage: "workflow", entries, query: "", cursor: 0, verbCursor: 0, loadingRemote, notice: opts.notice };
+    const entry = opts.resume ? entries.find((e) => e.id === opts.resume.id) : undefined;
+    if (!entry)
+        return base;
+    // resumed workflow still unpulled (its pull failed): back on the list, cursor on it
+    if (!entry.pulled)
+        return { ...base, cursor: entries.indexOf(entry) };
+    const verbIndex = PICKER_VERBS.indexOf(opts.resume.verb);
+    return { ...base, stage: "verb", selected: entry, verbCursor: Math.max(0, verbIndex) };
+}
+/** Case-insensitive substring match on name and id; empty query matches all. */
+export function filterEntries(entries, query) {
+    const q = query.toLowerCase();
+    if (q === "")
+        return entries;
+    return entries.filter((e) => e.name.toLowerCase().includes(q) || e.id.toLowerCase().includes(q));
+}
+/** Append remote workflows not already present locally, marked unpulled. */
+export function mergeRemote(entries, remote) {
+    const known = new Set(entries.map((e) => e.id));
+    return [...entries, ...remote.filter((w) => !known.has(w.id)).map((w) => ({ id: w.id, name: w.name, pulled: false }))];
+}
+/** Scroll window over a list: keeps the cursor visible, clamps to bounds. */
+export function visibleWindow(length, cursor, height) {
+    if (length <= height)
+        return { start: 0, end: length };
+    const start = Math.min(Math.max(0, cursor - Math.floor(height / 2)), length - height);
+    return { start, end: start + height };
+}
+const isPrintable = (key) => key.sequence !== undefined && key.sequence.length === 1 && key.sequence >= " " && key.sequence !== "\x7f"
+    && key.ctrl !== true && key.meta !== true;
+export function reduceKey(state, key) {
+    if (key.ctrl && key.name === "c")
+        return { done: true, result: "interrupted" };
+    if (state.stage === "workflow")
+        return reduceWorkflowKey(state, key);
+    return reduceVerbKey(state, key);
+}
+function reduceWorkflowKey(state, key) {
+    const filtered = filterEntries(state.entries, state.query);
+    switch (key.name) {
+        case "escape":
+            return { done: true, result: "quit" };
+        case "up":
+            return { done: false, state: { ...state, cursor: Math.max(0, state.cursor - 1) } };
+        case "down":
+            return { done: false, state: { ...state, cursor: Math.min(Math.max(0, filtered.length - 1), state.cursor + 1) } };
+        case "return":
+        case "enter": {
+            const entry = filtered[state.cursor];
+            if (!entry)
+                return { done: false, state };
+            if (!entry.pulled)
+                return { done: true, result: { verb: "pull", id: entry.id, name: entry.name } };
+            return { done: false, state: { ...state, stage: "verb", selected: entry, verbCursor: 0 } };
+        }
+        case "backspace":
+            return { done: false, state: { ...state, query: state.query.slice(0, -1), cursor: 0 } };
+    }
+    if (isPrintable(key))
+        return { done: false, state: { ...state, query: state.query + key.sequence, cursor: 0 } };
+    return { done: false, state };
+}
+function reduceVerbKey(state, key) {
+    switch (key.name) {
+        case "escape":
+            return { done: false, state: { ...state, stage: "workflow", selected: undefined } };
+        case "up":
+            return { done: false, state: { ...state, verbCursor: Math.max(0, state.verbCursor - 1) } };
+        case "down":
+            return { done: false, state: { ...state, verbCursor: Math.min(PICKER_VERBS.length - 1, state.verbCursor + 1) } };
+        case "return":
+        case "enter":
+            return { done: true, result: { verb: PICKER_VERBS[state.verbCursor], id: state.selected.id, name: state.selected.name } };
+    }
+    // a letter jumps to the next verb starting with it, cycling through
+    // matches ("p" alternates pull/push) — no collision-free hotkeys needed
+    if (isPrintable(key)) {
+        const c = key.sequence.toLowerCase();
+        for (let step = 1; step <= PICKER_VERBS.length; step++) {
+            const i = (state.verbCursor + step) % PICKER_VERBS.length;
+            if (PICKER_VERBS[i].startsWith(c))
+                return { done: false, state: { ...state, verbCursor: i } };
+        }
+    }
+    return { done: false, state };
+}
+// ---------- terminal IO (TTY only, untested by CI — keep this part thin) ----------
+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.
+const SKELETON_WIDTHS = [[14, 8], [9, 8], [17, 8]];
+const truncate = (text, max) => (text.length > max ? text.slice(0, max - 1) + "…" : text);
+function renderLines(state) {
+    const d = style.dim;
+    const lines = [];
+    if (state.stage === "verb") {
+        const wf = state.selected;
+        lines.push(`${style.bold(truncate(wf.name, 48))}  ${d(wf.id)}`);
+        PICKER_VERBS.forEach((verb, i) => {
+            lines.push(i === state.verbCursor ? `${style.green("❯")} ${style.bold(verb)}` : `  ${verb}`);
+        });
+        lines.push(d("↑↓ move · enter run · esc back"));
+        return lines;
+    }
+    const filtered = filterEntries(state.entries, state.query);
+    lines.push(`${style.bold("?")} ${state.query === "" ? d("type to filter") : state.query}`);
+    const { start, end } = visibleWindow(filtered.length, state.cursor, LIST_HEIGHT);
+    for (let i = start; i < end; i++) {
+        const e = filtered[i];
+        const pointer = i === state.cursor ? style.green("❯") : " ";
+        const name = e.pulled ? style.green(truncate(e.name, 48)) : style.yellow(truncate(e.name, 48));
+        // "(not pulled)" in words, not only color — NO_COLOR/monochrome safety
+        lines.push(`${pointer} ${name}  ${d(e.id)}${e.pulled ? "" : `  ${d("(not pulled)")}`}`);
+    }
+    if (filtered.length === 0 && !state.loadingRemote)
+        lines.push(d(state.entries.length === 0 ? "  nothing pulled yet" : "  no match"));
+    if (end < filtered.length)
+        lines.push(d(`  … ${filtered.length - end} more`));
+    if (state.loadingRemote) {
+        for (const [nameWidth, idWidth] of SKELETON_WIDTHS) {
+            lines.push(`  ${d("░".repeat(nameWidth))}  ${d("░".repeat(idWidth))}`);
+        }
+    }
+    if (state.notice)
+        lines.push(d(state.notice));
+    const enterHint = filtered[state.cursor]?.pulled === false ? "enter pull" : "enter select";
+    lines.push(d(`↑↓ move · ${enterHint} · esc quit`));
+    return lines;
+}
+/**
+ * Run the picker on the current TTY. `remote` (when credentials exist) is
+ * 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).
+ */
+export async function runPicker(local, remote, opts = {}) {
+    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`);
+        prevLines = lines.length;
+    };
+    const erase = () => {
+        if (prevLines > 0)
+            process.stdout.write(`\x1b[${prevLines}A\r\x1b[J`);
+        prevLines = 0;
+    };
+    const stdin = process.stdin;
+    emitKeypressEvents(stdin);
+    const wasRaw = stdin.isRaw === true;
+    const restore = () => {
+        if (!wasRaw)
+            stdin.setRawMode(false);
+        process.stdout.write("\x1b[?25h");
+    };
+    stdin.setRawMode(true);
+    stdin.resume();
+    process.stdout.write("\x1b[?25l");
+    process.once("exit", restore); // belt and braces: never leave the terminal raw
+    let finished = false;
+    let onKeypress;
+    let onEnd;
+    try {
+        return await new Promise((resolve) => {
+            // stdin EOF can't happen on a real keyboard, but a closed input (pty
+            // teardown, misuse) must quit instead of wedging the process forever
+            onEnd = () => {
+                finished = true;
+                resolve("quit");
+            };
+            stdin.once("end", onEnd);
+            onKeypress = (_str, key) => {
+                const step = reduceKey(state, key ?? {});
+                if (step.done) {
+                    finished = true;
+                    resolve(step.result);
+                    return;
+                }
+                state = step.state;
+                repaint();
+            };
+            // handlers attach synchronously so a fast rejection is never unhandled
+            remote
+                ?.then((workflows) => {
+                if (finished)
+                    return;
+                state = { ...state, entries: mergeRemote(state.entries, workflows), loadingRemote: false };
+                repaint();
+            })
+                .catch((err) => {
+                if (finished)
+                    return;
+                state = { ...state, loadingRemote: false, notice: `remote list unavailable (${err.message.split("\n")[0]})` };
+                repaint();
+            });
+            stdin.on("keypress", onKeypress);
+            repaint();
+        });
+    }
+    finally {
+        finished = true;
+        if (onKeypress)
+            stdin.removeListener("keypress", onKeypress);
+        if (onEnd)
+            stdin.removeListener("end", onEnd);
+        erase();
+        restore();
+        process.removeListener("exit", restore);
+        stdin.pause();
+    }
+}

package/dist/lib/prompt.mjs

@@ -0,0 +1,34 @@
+import { createInterface } from "node:readline/promises";
+/**
+ * Prompt helper that also works with piped stdin: plain readline/promises
+ * drops lines arriving before question() is called and hangs forever on EOF.
+ */
+export function createPrompt() {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const buffered = [];
+    const waiters = [];
+    let closed = false;
+    rl.on("line", (line) => {
+        const waiter = waiters.shift();
+        if (waiter)
+            waiter(line);
+        else
+            buffered.push(line);
+    });
+    rl.on("close", () => {
+        closed = true;
+        for (const waiter of waiters.splice(0))
+            waiter("");
+    });
+    return {
+        async question(prompt) {
+            process.stdout.write(prompt);
+            if (buffered.length > 0)
+                return buffered.shift();
+            if (closed)
+                return "";
+            return new Promise((resolve) => waiters.push(resolve));
+        },
+        close: () => rl.close(),
+    };
+}