@bpmnkit/cli 0.0.16 → 0.0.17

package/README.md

@@ -109,6 +109,8 @@ casen instances list --state active
 | [`@bpmnkit/cli-sdk`](https://www.npmjs.com/package/@bpmnkit/cli-sdk) | Plugin authoring SDK for the casen CLI |
 | [`@bpmnkit/create-casen-plugin`](https://www.npmjs.com/package/@bpmnkit/create-casen-plugin) | Scaffold a new casen CLI plugin in seconds |
 | [`@bpmnkit/casen-report`](https://www.npmjs.com/package/@bpmnkit/casen-report) | HTML reports from Camunda 8 incident and SLA data |
+| [`@bpmnkit/casen-worker-http`](https://www.npmjs.com/package/@bpmnkit/casen-worker-http) | Example HTTP worker plugin — completes jobs with live JSONPlaceholder API data |
+| [`@bpmnkit/casen-worker-ai`](https://www.npmjs.com/package/@bpmnkit/casen-worker-ai) | AI task worker — classify, summarize, extract, and decide using Claude |
 
 ## License
 

package/dist/commands/index.js

@@ -4,10 +4,13 @@ import { askGroup } from "./ask.js";
 import { getDmnReqsXmlCmd, getDmnXmlCmd, getStartFormCmd, getUserTaskFormCmd, getXmlCmd, renderBpmnCmd, } from "./bpmn.js";
 import { completionGroup } from "./completion.js";
 import { connectorGroup } from "./connector.js";
+import { lintGroup } from "./lint.js";
 import { pluginGroup } from "./plugin.js";
 import { profileGroup } from "./profile.js";
 import { computeRelations } from "./relations.js";
 import { settingsGroup } from "./settings.js";
+import { storyGroup } from "./story.js";
+import { testGroup } from "./test.js";
 import { workerCmd } from "./worker.js";
 // Inject custom commands into generated groups without modifying generated files.
 // Also remove the broken generated get-x-m-l commands (return text/xml, not JSON)
@@ -30,23 +33,36 @@ const customisedGroups = generatedCommandGroups.map((g) => {
         return { ...g, commands: [...commands, getUserTaskFormCmd] };
     }
     if (g === jobGroup) {
-        return { ...g, commands: [...g.commands, workerCmd] };
+        return g;
     }
     return g;
 });
 const sortedOtherGroups = [
     connectorGroup,
-    pluginGroup,
     ...customisedGroups,
     ...adminCommandGroups,
     completionGroup,
 ].sort((a, b) => a.name.localeCompare(b.name));
-export const commandGroups = [
+const workerGroup = {
+    name: "worker",
+    description: workerCmd.description,
+    commands: [workerCmd],
+};
+/** Pinned groups shown above the separator in the main TUI menu. */
+export const pinnedGroups = [
     askGroup,
+    lintGroup,
+    storyGroup,
     settingsGroup,
-    profileGroup,
-    ...sortedOtherGroups,
+    testGroup,
+    workerGroup,
 ];
+/** API command groups — shown below the plugin section in the main TUI menu. */
+export const apiGroups = sortedOtherGroups;
+/** All built-in groups — used for CLI routing. */
+export const commandGroups = [...pinnedGroups, ...apiGroups];
+// Exported for CLI routing in run.ts (not shown in main TUI menu)
+export { pluginGroup, profileGroup };
 // Compute follow-up relations between commands based on shared field/arg names
 computeRelations(commandGroups);
 // Manually inject relations on GET commands (they return a single object, not a

package/dist/commands/lint.js

@@ -0,0 +1,65 @@
+import { readFile } from "node:fs/promises";
+import { Bpmn, optimize } from "@bpmnkit/core";
+const SEVERITY_SYMBOL = {
+    error: "✖",
+    warning: "⚠",
+    info: "ℹ",
+};
+const lintCmd = {
+    name: "lint",
+    description: "Lint a BPMN file — run all static analysis and pattern checks",
+    args: [{ name: "file", description: "Path to the .bpmn file", required: true }],
+    flags: [
+        {
+            name: "categories",
+            description: "Comma-separated categories to run (default: all)",
+            type: "string",
+        },
+        {
+            name: "format",
+            description: "Output format: text (default) or json",
+            type: "string",
+        },
+    ],
+    async run(ctx) {
+        const filePath = ctx.positional[0];
+        if (!filePath)
+            throw new Error("Missing required argument: <file>");
+        const xml = await readFile(filePath, "utf-8");
+        const defs = Bpmn.parse(xml);
+        const categoriesFlag = ctx.flags.categories;
+        const categories = typeof categoriesFlag === "string" && categoriesFlag.length > 0
+            ? categoriesFlag.split(",").map((s) => s.trim())
+            : undefined;
+        const report = optimize(defs, categories !== undefined ? { categories } : undefined);
+        const { findings } = report;
+        const formatFlag = ctx.flags.format;
+        if (formatFlag === "json") {
+            ctx.output.print(findings);
+            return;
+        }
+        if (findings.length === 0) {
+            ctx.output.ok("No issues found.");
+            return;
+        }
+        for (const f of findings) {
+            const symbol = SEVERITY_SYMBOL[f.severity] ?? "·";
+            const elIds = f.elementIds.length > 0 ? ` [${f.elementIds.join(", ")}]` : "";
+            ctx.output.info(`${symbol} [${f.category}]${elIds} ${f.message}`);
+        }
+        const { total, bySeverity } = report.summary;
+        const errorCount = bySeverity.error ?? 0;
+        const warnCount = bySeverity.warning ?? 0;
+        const infoCount = bySeverity.info ?? 0;
+        ctx.output.info(`\n${total} finding${total !== 1 ? "s" : ""}: ${errorCount} error${errorCount !== 1 ? "s" : ""}, ${warnCount} warning${warnCount !== 1 ? "s" : ""}, ${infoCount} info`);
+        if (errorCount > 0) {
+            throw new Error(`Lint failed with ${errorCount} error${errorCount !== 1 ? "s" : ""}`);
+        }
+    },
+};
+export const lintGroup = {
+    name: "lint",
+    description: "Lint BPMN files using the static analyzer",
+    commands: [lintCmd],
+};
+//# sourceMappingURL=lint.js.map

package/dist/commands/plugin.js

@@ -17,7 +17,7 @@ function runNpm(args, cwd) {
         child.on("error", reject);
     });
 }
-async function searchNpmRegistry(query) {
+export async function searchNpmRegistry(query) {
     const text = `keywords:casen-plugin${query ? ` ${query}` : ""}`;
     const url = `https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(text)}&size=50`;
     const res = await fetch(url);

package/dist/commands/story.js

@@ -0,0 +1,42 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { Bpmn, renderStoryHtml } from "@bpmnkit/core";
+const storyCmd = {
+    name: "story",
+    description: "Render a BPMN process as a standalone story-mode HTML file",
+    args: [{ name: "file", description: "Path to the .bpmn file", required: true }],
+    flags: [
+        {
+            name: "output",
+            short: "o",
+            description: "Output path (default: <file>.story.html)",
+            type: "string",
+        },
+        {
+            name: "theme",
+            description: "Color theme: light (default) or dark",
+            type: "string",
+        },
+    ],
+    async run(ctx) {
+        const filePath = ctx.positional[0];
+        if (!filePath)
+            throw new Error("Missing required argument: <file>");
+        const xml = await readFile(filePath, "utf-8");
+        const defs = Bpmn.parse(xml);
+        const themeFlag = ctx.flags.theme;
+        const theme = themeFlag === "dark" ? "dark" : "light";
+        const outputFlag = ctx.flags.output;
+        const outputPath = typeof outputFlag === "string" && outputFlag.length > 0
+            ? outputFlag
+            : `${filePath}.story.html`;
+        const html = renderStoryHtml(defs, { standalone: true, theme });
+        await writeFile(outputPath, html, "utf-8");
+        ctx.output.ok(`Story HTML written to ${outputPath}`);
+    },
+};
+export const storyGroup = {
+    name: "story",
+    description: "Render BPMN processes as narrative HTML",
+    commands: [storyCmd],
+};
+//# sourceMappingURL=story.js.map

package/dist/commands/test.js

@@ -0,0 +1,77 @@
+import { readFile } from "node:fs/promises";
+import { Bpmn } from "@bpmnkit/core";
+import { Engine, runScenario } from "@bpmnkit/engine";
+const testCmd = {
+    name: "test",
+    description: "Run scenario tests for a BPMN process file",
+    args: [
+        {
+            name: "file",
+            description: "Path to the .bpmn file",
+            required: true,
+        },
+    ],
+    flags: [
+        {
+            name: "scenarios",
+            short: "s",
+            description: "Path to the .bpmn.tests.json scenarios file (default: <file>.tests.json)",
+            type: "string",
+        },
+    ],
+    async run(ctx) {
+        const bpmnPath = ctx.positional[0];
+        if (bpmnPath === undefined)
+            throw new Error("Missing required argument: <file>");
+        const scenariosPath = typeof ctx.flags.scenarios === "string" ? ctx.flags.scenarios : `${bpmnPath}.tests.json`;
+        const bpmnXml = await readFile(bpmnPath, "utf8").catch(() => {
+            throw new Error(`Cannot read BPMN file: ${bpmnPath}`);
+        });
+        const scenariosRaw = await readFile(scenariosPath, "utf8").catch(() => {
+            throw new Error(`Cannot read scenarios file: ${scenariosPath}`);
+        });
+        let scenarios;
+        try {
+            scenarios = JSON.parse(scenariosRaw);
+        }
+        catch {
+            throw new Error(`Invalid JSON in scenarios file: ${scenariosPath}`);
+        }
+        if (!Array.isArray(scenarios) || scenarios.length === 0) {
+            ctx.output.info("No scenarios found.");
+            return;
+        }
+        const defs = Bpmn.parse(bpmnXml);
+        const engine = new Engine();
+        let passed = 0;
+        let failed = 0;
+        for (const scenario of scenarios) {
+            const result = await runScenario(engine, defs, scenario);
+            if (result.passed) {
+                passed++;
+                ctx.output.ok(`PASS  ${scenario.name}  (${result.durationMs}ms)`);
+            }
+            else {
+                failed++;
+                ctx.output.info(`FAIL  ${scenario.name}  (${result.durationMs}ms)`);
+                for (const f of result.failures) {
+                    ctx.output.info(`       ${f.field}: expected ${JSON.stringify(f.expected)}, got ${JSON.stringify(f.actual)}`);
+                }
+                for (const e of result.errors) {
+                    ctx.output.info(`       error${e.elementId !== undefined ? ` (${e.elementId})` : ""}: ${e.message}`);
+                }
+            }
+        }
+        const total = passed + failed;
+        ctx.output.info(`\n${passed}/${total} passed`);
+        if (failed > 0) {
+            throw new Error(`${failed} scenario(s) failed`);
+        }
+    },
+};
+export const testGroup = {
+    name: "test",
+    description: "Run scenario-based tests for BPMN processes",
+    commands: [testCmd],
+};
+//# sourceMappingURL=test.js.map

package/dist/commands/worker.js

@@ -11,11 +11,13 @@
 export const workerCmd = {
     name: "worker",
     description: "Run a simple job worker that auto-completes jobs of a given type",
+    _worker: { jobType: "io.camunda.connector.HttpJson:1" },
     args: [
         {
             name: "type",
             description: "Job type to subscribe to (matches the task definition type in BPMN)",
             required: true,
+            default: "io.camunda.connector.HttpJson:1",
         },
     ],
     flags: [
@@ -46,11 +48,11 @@ export const workerCmd = {
     examples: [
         {
             description: "Subscribe to jobs of type 'payment-service'",
-            command: "casen job worker payment-service",
+            command: "casen worker payment-service",
         },
         {
             description: "Return custom variables on completion",
-            command: 'casen job worker payment-service --variables \'{"status":"ok","amount":100}\'',
+            command: 'casen worker payment-service --variables \'{"status":"ok","amount":100}\'',
         },
     ],
     async run(ctx) {

package/dist/run.js

@@ -1,6 +1,6 @@
 import { appendAuditEntry, createAdminClientFromProfile, createClientFromProfile, getActiveName, getProfile, } from "@bpmnkit/profiles";
 import { parseArgs } from "./args.js";
-import { commandGroups } from "./commands/index.js";
+import { apiGroups, commandGroups, pinnedGroups, pluginGroup, profileGroup, } from "./commands/index.js";
 import { getRuntimeCompletions } from "./completion.js";
 import { printCommandHelp, printGlobalHelp, printGroupHelp, printVersion } from "./help.js";
 import { createNullWriter, createOutputWriter, printRawResponse } from "./output.js";
@@ -51,7 +51,7 @@ export async function run(argv) {
     // Load plugin-contributed groups and merge with built-in groups.
     // Failures are isolated inside loadPlugins — a broken plugin cannot crash the CLI.
     const pluginGroups = await loadPlugins();
-    const allGroups = [...commandGroups, ...pluginGroups];
+    const allGroups = [...commandGroups, profileGroup, pluginGroup, ...pluginGroups];
     // ── Completion protocol ───────────────────────────────────────────────────
     // casen --complete <cursorWordIndex> -- <words...>
     const completeIdx = argv.indexOf("--complete");
@@ -82,7 +82,13 @@ export async function run(argv) {
         }
         else {
             const { name: pName, info: pInfo } = buildProfileInfo(profileName);
-            await runMainTui(allGroups, () => Promise.resolve(createClientFromProfile(profileName)), () => Promise.resolve(createAdminClientFromProfile(profileName)), { profile: pName, profileInfo: pInfo });
+            await runMainTui(
+            // Order: pinned → plugins (tagged) → api groups
+            [
+                ...pinnedGroups,
+                ...pluginGroups.map((g) => ({ ...g, _plugin: true })),
+                ...apiGroups,
+            ], () => Promise.resolve(createClientFromProfile(profileName)), () => Promise.resolve(createAdminClientFromProfile(profileName)), { profile: pName, profileInfo: pInfo });
         }
         return;
     }
@@ -96,6 +102,21 @@ export async function run(argv) {
         process.exitCode = 1;
         return;
     }
+    // ── worker: treat positional[1] as the job type argument ─────────────────
+    if (group.name === "worker" && positional.length >= 2 && !wantHelp) {
+        const output = createOutputWriter(outputFormat, noColor);
+        const ctx = {
+            positional: positional.slice(1),
+            flags,
+            output,
+            getClient,
+            getAdminClient,
+        };
+        const cmd = group.commands[0];
+        if (cmd)
+            await cmd.run(ctx);
+        return;
+    }
     // ── ask: join remaining positionals as the query ─────────────────────────
     if (group.name === "ask" && positional.length >= 2 && !wantHelp) {
         const queryWords = positional.slice(1);

package/dist/tui.js

@@ -2,6 +2,9 @@ import { spawn } from "node:child_process";
 import { renderBpmnAscii } from "@bpmnkit/ascii";
 import { appendAuditEntry, getAuditLog, getSettings, saveSettings } from "@bpmnkit/profiles";
 import { runAskQuery } from "./commands/ask.js";
+import { pluginGroup, searchNpmRegistry } from "./commands/plugin.js";
+import { profileGroup } from "./commands/profile.js";
+import { readInstalledPlugins } from "./plugin-loader.js";
 // ─── ANSI helpers ─────────────────────────────────────────────────────────────
 const CSI = "\x1b[";
 const HIDE = `${CSI}?25l`;
@@ -83,12 +86,13 @@ const SKIP_FLAGS = new Set(["output", "profile", "help", "no-color", "debug"]);
 function buildFields(cmd) {
     const fields = [];
     for (const arg of cmd.args ?? []) {
+        const defaultVal = arg.default ?? "";
         fields.push({
             kind: "arg",
             label: arg.name,
             hint: arg.required ? "required" : "optional",
-            value: "",
-            cursor: 0,
+            value: defaultVal,
+            cursor: defaultVal.length,
             required: arg.required ?? false,
             argSpec: arg,
         });
@@ -376,8 +380,12 @@ function renderMain(state, screen) {
         const desc = dim(fit(g.description, cols - nameW - 8));
         const line = `  ${name}  ${desc}`;
         lines.push(isCursor ? inv(line.padEnd(cols - 1)) : line);
-        // Add separator after the pinned top section (ask, settings, profile)
-        if (!searching && g.name === "profile" && i < groups.length - 1) {
+        // Separator after pinned section (after "worker", before plugins or api groups)
+        if (!searching && g.name === "worker" && i < groups.length - 1) {
+            lines.push(`  ${dim("─".repeat(cols - 4))}`);
+        }
+        // Separator after the last plugin group (before api groups), only when plugins exist
+        if (!searching && g._plugin && !groups[i + 1]?._plugin && i < groups.length - 1) {
             lines.push(`  ${dim("─".repeat(cols - 4))}`);
         }
     }
@@ -836,7 +844,7 @@ function renderProfile(state, screen) {
         const hi = Math.min(screen.scroll + viewH, state.profileInfo.length);
         lines.push(`  ${dim(`${screen.scroll + 1}–${hi} of ${state.profileInfo.length}`)}`);
     }
-    lines.push(`  ${dim("↑↓")} scroll  ${cyan("esc/p")} close  ${cyan("q")} quit`);
+    lines.push(`  ${dim("↑↓")} scroll  ${cyan("esc")} close  ${cyan("q")} quit`);
     return lines;
 }
 const SETTINGS_ROWS = [
@@ -854,6 +862,24 @@ const SETTINGS_ROWS = [
         label: "Show Audit Log",
         description: "View recent commands executed for the active profile",
     },
+    {
+        kind: "nav",
+        id: "active-profile",
+        label: "Active Profile",
+        description: "View details for the current connection profile",
+    },
+    {
+        kind: "nav",
+        id: "profiles",
+        label: "Profiles",
+        description: "Manage and switch connection profiles",
+    },
+    {
+        kind: "nav",
+        id: "plugins",
+        label: "Plugins",
+        description: "Browse and manage CLI plugins",
+    },
 ];
 function renderSettings(state, screen) {
     const { cols } = termSize();
@@ -936,7 +962,7 @@ function renderWorker(state, screen) {
             : screen.status === "stopping"
                 ? cyan("◌ STOPPING")
                 : dim("■ STOPPED");
-    const lines = [renderHeader(["job", "worker"], cols, state.profile), ""];
+    const lines = [renderHeader(["worker"], cols, state.profile), ""];
     lines.push(`  ${padEnd(dim("type"), 8)}  ${cyan(screen.jobType)}    ${dim("status")}  ${statusStr}`);
     lines.push(`  ${dim("─".repeat(cols - 4))}`);
     const { activated, completed, failed } = screen.stats;
@@ -1130,14 +1156,44 @@ async function runWorkerLoop(ws, state, variables, jobTimeout, maxJobs) {
                 break;
             ws.stats.activated++;
             addWorkerLog(ws, "info", `Activated ${job.jobKey}  process=${job.processDefinitionId}  element=${job.elementId}`);
+            let jobResult = { outcome: "complete", variables };
+            const processJob = ws.cmd._worker?.processJob;
+            if (processJob) {
+                try {
+                    jobResult = await processJob(job);
+                }
+                catch (err) {
+                    addWorkerLog(ws, "err", `Handler error: ${err instanceof Error ? err.message : String(err)} — using defaults`);
+                }
+            }
             try {
-                await client.job.completeJob(job.jobKey, { variables });
-                ws.stats.completed++;
-                addWorkerLog(ws, "ok", `Completed ${job.jobKey}`);
+                if (jobResult.outcome === "complete") {
+                    await client.job.completeJob(job.jobKey, { variables: jobResult.variables });
+                    ws.stats.completed++;
+                    addWorkerLog(ws, "ok", `Completed ${job.jobKey}`);
+                }
+                else if (jobResult.outcome === "fail") {
+                    await client.job.failJob(job.jobKey, {
+                        errorMessage: jobResult.errorMessage,
+                        retries: jobResult.retries,
+                        retryBackOff: jobResult.retryBackOff,
+                    });
+                    ws.stats.failed++;
+                    addWorkerLog(ws, "err", `Failed ${job.jobKey}: ${jobResult.errorMessage}`);
+                }
+                else {
+                    await client.job.throwJobError(job.jobKey, {
+                        errorCode: jobResult.errorCode,
+                        errorMessage: jobResult.errorMessage,
+                        variables: jobResult.variables,
+                    });
+                    ws.stats.failed++;
+                    addWorkerLog(ws, "err", `Error ${job.jobKey} [${jobResult.errorCode}]: ${jobResult.errorMessage ?? ""}`);
+                }
             }
             catch (err) {
                 ws.stats.failed++;
-                addWorkerLog(ws, "err", `Failed to complete ${job.jobKey}: ${err instanceof Error ? err.message : String(err)}`);
+                addWorkerLog(ws, "err", `Failed to settle ${job.jobKey}: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
         if (jobs.length > 0)
@@ -1403,6 +1459,9 @@ function render(state) {
         case "json-editor":
             lines = renderJsonEditor(state, screen);
             break;
+        case "plugins":
+            lines = renderPlugins(state, screen);
+            break;
     }
     process.stdout.write(`${CLEAR}${lines.join("\n")}\n`);
 }
@@ -1485,6 +1544,24 @@ function handleMainKey(key, screen, state, done) {
                     _timer: null,
                 });
             }
+            else if (group &&
+                group.commands.length === 1 &&
+                group.commands[0] &&
+                "_worker" in group.commands[0]) {
+                // Single-command worker group: skip commands list, go straight to input
+                const cmd = group.commands[0];
+                state.stack.push({
+                    kind: "input",
+                    group,
+                    cmd,
+                    fields: buildFields(cmd),
+                    cursor: 0,
+                    scroll: 0,
+                    editing: false,
+                    error: "",
+                    running: false,
+                });
+            }
             else if (group) {
                 state.stack.push({ kind: "commands", group, cursor: 0, search: "" });
             }
@@ -1794,7 +1871,7 @@ async function handleInputKey(key, screen, state, done) {
             if (!field)
                 break;
             if (field.kind === "run") {
-                if (screen.cmd.name === "worker") {
+                if ("_worker" in screen.cmd) {
                     launchWorkerView(screen, state);
                 }
                 else {
@@ -2600,6 +2677,15 @@ function handleSettingsKey(key, screen, state, done) {
             else if (row?.kind === "action" && row.id === "show-audit-log") {
                 state.stack.push({ kind: "audit-log", scroll: 0 });
             }
+            else if (row?.kind === "nav" && row.id === "active-profile") {
+                state.stack.push({ kind: "profile", scroll: 0 });
+            }
+            else if (row?.kind === "nav" && row.id === "profiles") {
+                state.stack.push({ kind: "commands", group: profileGroup, cursor: 0, search: "" });
+            }
+            else if (row?.kind === "nav" && row.id === "plugins") {
+                state.stack.push(newPluginsScreen());
+            }
             break;
         }
         case "\x1b":
@@ -2693,6 +2779,499 @@ function handleWorkerKey(key, screen, state, done) {
     }
     render(state);
 }
+// ─── Plugins screen ───────────────────────────────────────────────────────────
+const PLUGIN_MENU = [
+    { id: "search", label: "search", description: "Search the npm registry for plugins" },
+    { id: "list", label: "list", description: "Show installed plugins" },
+    { id: "install", label: "install", description: "Install a plugin from npm or local path" },
+    {
+        id: "update",
+        label: "update",
+        description: "Update installed plugins to their latest versions",
+    },
+    { id: "remove", label: "remove", description: "Remove a plugin" },
+];
+function newPluginsScreen() {
+    return {
+        kind: "plugins",
+        subview: "menu",
+        menuCursor: 0,
+        query: "",
+        queryCursor: 0,
+        resultKind: "search",
+        results: [],
+        resultCursor: 0,
+        resultScroll: 0,
+        promptLabel: "",
+        promptValue: "",
+        promptCursor: 0,
+        promptAction: "install",
+        message: "",
+        error: "",
+        running: false,
+    };
+}
+function renderPlugins(state, screen) {
+    const { cols, rows } = termSize();
+    if (screen.subview === "menu") {
+        const nameW = PLUGIN_MENU.reduce((m, item) => Math.max(m, item.label.length), 0) + 2;
+        const lines = [renderHeader(["settings", "plugins"], cols, state.profile), ""];
+        for (let i = 0; i < PLUGIN_MENU.length; i++) {
+            const item = PLUGIN_MENU[i];
+            if (!item)
+                continue;
+            const isCursor = i === screen.menuCursor;
+            const name = padEnd(isCursor ? cyan(item.label) : item.label, nameW);
+            const desc = dim(fit(item.description, cols - nameW - 6));
+            const line = `  ${name}  ${desc}`;
+            lines.push(isCursor ? inv(line.padEnd(cols - 1)) : line);
+        }
+        lines.push("");
+        lines.push(`  ${dim("↑↓")} navigate  ${cyan("enter")} open  ${cyan("esc")} back  ${cyan("q")} quit`);
+        return lines;
+    }
+    if (screen.subview === "search") {
+        const lines = [renderHeader(["settings", "plugins", "search"], cols, state.profile), ""];
+        lines.push(`  ${dim("Search the npm registry — leave empty to browse all plugins")}`);
+        lines.push("");
+        lines.push(`  > ${renderText(screen.query, screen.queryCursor, cols - 6, true)}`);
+        if (screen.running) {
+            lines.push("");
+            lines.push(`  ${dim("Searching…")}`);
+        }
+        else if (screen.error) {
+            lines.push("");
+            lines.push(`  ${red("error:")} ${screen.error}`);
+        }
+        lines.push("");
+        lines.push(`  ${dim("type query")}  ${cyan("enter")} search  ${cyan("esc")} back  ${cyan("^C")} quit`);
+        return lines;
+    }
+    if (screen.subview === "results") {
+        const viewH = Math.max(3, rows - 10);
+        const isSearch = screen.resultKind === "search";
+        const title = isSearch ? "search results" : "installed";
+        const lines = [renderHeader(["settings", "plugins", title], cols, state.profile), ""];
+        if (screen.results.length === 0) {
+            lines.push(`  ${dim(isSearch ? "No plugins found." : "No plugins installed.")}`);
+        }
+        else {
+            const nameW = Math.min(32, screen.results.reduce((m, r) => Math.max(m, r.name.length), 0)) + 2;
+            // Official badge shown for @bpmnkit/* packages (2 visible chars: "◆ ")
+            const BADGE = `${cyan("◆")} `;
+            const BADGE_W = 2;
+            const visible = screen.results.slice(screen.resultScroll, screen.resultScroll + viewH);
+            for (let vi = 0; vi < visible.length; vi++) {
+                const r = visible[vi];
+                if (!r)
+                    continue;
+                const ri = screen.resultScroll + vi;
+                const isCursor = ri === screen.resultCursor;
+                const isOfficial = r.name.startsWith("@bpmnkit/");
+                const badge = isOfficial ? BADGE : " ".repeat(BADGE_W);
+                const name = padEnd(isCursor ? cyan(r.name) : r.name, nameW);
+                const verStr = r.version.padEnd(10);
+                const extra = isSearch
+                    ? dim(fit(r.description, cols - nameW - BADGE_W - 14))
+                    : dim(r.installedAt.slice(0, 10));
+                const line = `  ${badge}${name}  ${verStr}  ${extra}`;
+                lines.push(isCursor ? inv(line.padEnd(cols - 1)) : line);
+            }
+        }
+        if (screen.message) {
+            lines.push("");
+            lines.push(`  ${screen.message}`);
+        }
+        lines.push("");
+        const actions = isSearch
+            ? `${cyan("enter/i")} install  ${cyan("esc")} back  ${cyan("q")} quit`
+            : `${cyan("enter/r")} remove  ${cyan("esc")} back  ${cyan("q")} quit`;
+        lines.push(`  ${dim("↑↓")} navigate  ${actions}`);
+        lines.push(`  ${cyan("◆")} ${dim("= official @bpmnkit plugin")}`);
+        return lines;
+    }
+    if (screen.subview === "prompt") {
+        const lines = [
+            renderHeader(["settings", "plugins", screen.promptAction], cols, state.profile),
+            "",
+        ];
+        lines.push(`  ${screen.promptLabel}`);
+        lines.push("");
+        lines.push(`  > ${renderText(screen.promptValue, screen.promptCursor, cols - 6, true)}`);
+        if (screen.running) {
+            lines.push("");
+            lines.push(`  ${dim("Running…")}`);
+        }
+        else if (screen.error) {
+            lines.push("");
+            lines.push(`  ${red("error:")} ${screen.error}`);
+        }
+        lines.push("");
+        lines.push(`  ${dim("type name")}  ${cyan("enter")} confirm  ${cyan("esc")} back  ${cyan("^C")} quit`);
+        return lines;
+    }
+    // "done"
+    const lines = [renderHeader(["settings", "plugins"], cols, state.profile), "", ""];
+    if (screen.error) {
+        lines.push(`  ${red("error:")} ${screen.error}`);
+    }
+    else {
+        for (const line of screen.message.split("\n")) {
+            lines.push(`  ${line}`);
+        }
+    }
+    lines.push("");
+    lines.push(`  ${cyan("esc")} back  ${cyan("q")} quit`);
+    return lines;
+}
+/** Temporarily restore the normal terminal, run fn (which may spawn processes), then re-enter. */
+async function runWithTerminal(fn) {
+    process.stdout.write(`${ALT_OFF}${SHOW}`);
+    if (process.stdin.isTTY)
+        process.stdin.setRawMode(false);
+    try {
+        await fn();
+    }
+    finally {
+        if (process.stdin.isTTY)
+            process.stdin.setRawMode(true);
+        process.stdout.write(`${ALT_ON}${HIDE}${CLEAR}`);
+    }
+}
+async function handlePluginsKey(key, screen, state, done) {
+    if (key === "\x03") {
+        done();
+        return;
+    }
+    // ── Menu subview ──────────────────────────────────────────────────────────
+    if (screen.subview === "menu") {
+        switch (key) {
+            case "\x1b[A":
+                if (screen.menuCursor > 0)
+                    screen.menuCursor--;
+                break;
+            case "\x1b[B":
+                if (screen.menuCursor < PLUGIN_MENU.length - 1)
+                    screen.menuCursor++;
+                break;
+            case "\r":
+            case "\n": {
+                const item = PLUGIN_MENU[screen.menuCursor];
+                if (item?.id === "search") {
+                    screen.subview = "search";
+                    screen.query = "";
+                    screen.queryCursor = 0;
+                    screen.error = "";
+                }
+                else if (item?.id === "list") {
+                    screen.running = true;
+                    screen.error = "";
+                    render(state);
+                    try {
+                        const plugins = await readInstalledPlugins();
+                        screen.resultKind = "installed";
+                        screen.results = plugins.map((p) => ({
+                            name: p.package,
+                            version: p.version,
+                            description: "",
+                            publisher: "",
+                            score: "",
+                            installedAt: p.installedAt,
+                        }));
+                        screen.resultCursor = 0;
+                        screen.resultScroll = 0;
+                        screen.message = "";
+                        screen.subview = "results";
+                    }
+                    catch (err) {
+                        screen.error = err instanceof Error ? err.message : String(err);
+                    }
+                    finally {
+                        screen.running = false;
+                    }
+                }
+                else if (item?.id === "install") {
+                    screen.subview = "prompt";
+                    screen.promptLabel = "Package name (e.g. casen-deploy or ./local-path):";
+                    screen.promptValue = "";
+                    screen.promptCursor = 0;
+                    screen.promptAction = "install";
+                    screen.error = "";
+                }
+                else if (item?.id === "update") {
+                    await runWithTerminal(async () => {
+                        const cmd = pluginGroup.commands.find((c) => c.name === "update");
+                        if (!cmd)
+                            return;
+                        const { writer } = makeCapturingWriter();
+                        await cmd.run({
+                            positional: [],
+                            flags: {},
+                            output: writer,
+                            getClient: state.getClient,
+                            getAdminClient: state.getAdminClient,
+                        });
+                    });
+                    screen.subview = "done";
+                    screen.message = green("✓ Update complete. Restart casen to activate changes.");
+                    screen.error = "";
+                }
+                else if (item?.id === "remove") {
+                    screen.subview = "prompt";
+                    screen.promptLabel = "Plugin package name to remove:";
+                    screen.promptValue = "";
+                    screen.promptCursor = 0;
+                    screen.promptAction = "remove";
+                    screen.error = "";
+                }
+                break;
+            }
+            case "\x1b":
+                state.stack.pop();
+                break;
+            case "q":
+            case "Q":
+                done();
+                return;
+        }
+        render(state);
+        return;
+    }
+    // ── Search subview ────────────────────────────────────────────────────────
+    if (screen.subview === "search") {
+        if (key === "\x1b") {
+            screen.subview = "menu";
+            render(state);
+            return;
+        }
+        if (key === "\r" || key === "\n") {
+            screen.running = true;
+            screen.error = "";
+            render(state);
+            try {
+                const raw = await searchNpmRegistry(screen.query);
+                screen.results = raw.map((r) => ({
+                    name: r.package.name,
+                    version: r.package.version,
+                    description: r.package.description ?? "",
+                    publisher: r.package.publisher?.username ?? "",
+                    score: r.score.final.toFixed(2),
+                    installedAt: "",
+                }));
+                screen.resultKind = "search";
+                screen.resultCursor = 0;
+                screen.resultScroll = 0;
+                screen.message = "";
+                screen.subview = "results";
+            }
+            catch (err) {
+                screen.error = err instanceof Error ? err.message : String(err);
+            }
+            finally {
+                screen.running = false;
+            }
+            render(state);
+            return;
+        }
+        if (key === "\x7f" || key === "\x08") {
+            if (screen.queryCursor > 0) {
+                screen.query =
+                    screen.query.slice(0, screen.queryCursor - 1) + screen.query.slice(screen.queryCursor);
+                screen.queryCursor--;
+            }
+        }
+        else if (key === "\x1b[D") {
+            if (screen.queryCursor > 0)
+                screen.queryCursor--;
+        }
+        else if (key === "\x1b[C") {
+            if (screen.queryCursor < screen.query.length)
+                screen.queryCursor++;
+        }
+        else if (key === "\x01" || key === "\x1b[H") {
+            screen.queryCursor = 0;
+        }
+        else if (key === "\x05" || key === "\x1b[F") {
+            screen.queryCursor = screen.query.length;
+        }
+        else if (key.length === 1 && key >= " ") {
+            screen.query =
+                screen.query.slice(0, screen.queryCursor) + key + screen.query.slice(screen.queryCursor);
+            screen.queryCursor++;
+        }
+        render(state);
+        return;
+    }
+    // ── Results subview ───────────────────────────────────────────────────────
+    if (screen.subview === "results") {
+        const { rows } = termSize();
+        const viewH = Math.max(3, rows - 10);
+        switch (key) {
+            case "\x1b[A":
+                if (screen.resultCursor > 0) {
+                    screen.resultCursor--;
+                    if (screen.resultCursor < screen.resultScroll)
+                        screen.resultScroll--;
+                }
+                break;
+            case "\x1b[B":
+                if (screen.resultCursor < screen.results.length - 1) {
+                    screen.resultCursor++;
+                    if (screen.resultCursor >= screen.resultScroll + viewH)
+                        screen.resultScroll++;
+                }
+                break;
+            case "\r":
+            case "\n":
+            case "i":
+            case "I":
+            case "r":
+            case "R": {
+                const result = screen.results[screen.resultCursor];
+                if (!result)
+                    break;
+                if (screen.resultKind === "installed" && (key === "i" || key === "I"))
+                    break;
+                const action = screen.resultKind === "installed" ? "remove" : "install";
+                const pkgName = result.name;
+                screen.message = dim(`${action === "install" ? "Installing" : "Removing"} ${pkgName}…`);
+                render(state);
+                const cmd = pluginGroup.commands.find((c) => c.name === action);
+                if (!cmd)
+                    break;
+                let opError = "";
+                let opMessage = "";
+                await runWithTerminal(async () => {
+                    const { writer, get } = makeCapturingWriter();
+                    try {
+                        await cmd.run({
+                            positional: [pkgName],
+                            flags: {},
+                            output: writer,
+                            getClient: state.getClient,
+                            getAdminClient: state.getAdminClient,
+                        });
+                        const out = get();
+                        if (out.type === "messages")
+                            opMessage = out.lines.join("\n");
+                        else
+                            opMessage = green(`✓ ${action === "install" ? "Installed" : "Removed"} ${pkgName}`);
+                    }
+                    catch (err) {
+                        opError = err instanceof Error ? err.message : String(err);
+                    }
+                });
+                screen.subview = "done";
+                screen.message = opMessage;
+                screen.error = opError;
+                break;
+            }
+            case "\x1b":
+                // Go back to search input if came from search, else back to menu
+                if (screen.resultKind === "search") {
+                    screen.subview = "search";
+                }
+                else {
+                    screen.subview = "menu";
+                }
+                break;
+            case "q":
+            case "Q":
+                done();
+                return;
+        }
+        render(state);
+        return;
+    }
+    // ── Prompt subview ────────────────────────────────────────────────────────
+    if (screen.subview === "prompt") {
+        if (key === "\x1b") {
+            screen.subview = "menu";
+            render(state);
+            return;
+        }
+        if (key === "\r" || key === "\n") {
+            const pkgName = screen.promptValue.trim();
+            if (!pkgName) {
+                screen.error = "Package name is required";
+                render(state);
+                return;
+            }
+            const cmd = pluginGroup.commands.find((c) => c.name === screen.promptAction);
+            if (!cmd)
+                return;
+            let opError = "";
+            let opMessage = "";
+            await runWithTerminal(async () => {
+                const { writer, get } = makeCapturingWriter();
+                try {
+                    await cmd.run({
+                        positional: [pkgName],
+                        flags: {},
+                        output: writer,
+                        getClient: state.getClient,
+                        getAdminClient: state.getAdminClient,
+                    });
+                    const out = get();
+                    if (out.type === "messages")
+                        opMessage = out.lines.join("\n");
+                    else
+                        opMessage = green("✓ Done");
+                }
+                catch (err) {
+                    opError = err instanceof Error ? err.message : String(err);
+                }
+            });
+            screen.subview = "done";
+            screen.message = opMessage;
+            screen.error = opError;
+            render(state);
+            return;
+        }
+        if (key === "\x7f" || key === "\x08") {
+            if (screen.promptCursor > 0) {
+                screen.promptValue =
+                    screen.promptValue.slice(0, screen.promptCursor - 1) +
+                        screen.promptValue.slice(screen.promptCursor);
+                screen.promptCursor--;
+            }
+        }
+        else if (key === "\x1b[D") {
+            if (screen.promptCursor > 0)
+                screen.promptCursor--;
+        }
+        else if (key === "\x1b[C") {
+            if (screen.promptCursor < screen.promptValue.length)
+                screen.promptCursor++;
+        }
+        else if (key === "\x01" || key === "\x1b[H") {
+            screen.promptCursor = 0;
+        }
+        else if (key === "\x05" || key === "\x1b[F") {
+            screen.promptCursor = screen.promptValue.length;
+        }
+        else if (key.length === 1 && key >= " ") {
+            screen.promptValue =
+                screen.promptValue.slice(0, screen.promptCursor) +
+                    key +
+                    screen.promptValue.slice(screen.promptCursor);
+            screen.promptCursor++;
+        }
+        render(state);
+        return;
+    }
+    // ── Done subview ──────────────────────────────────────────────────────────
+    switch (key) {
+        case "\x1b":
+            screen.subview = "menu";
+            break;
+        case "q":
+        case "Q":
+            done();
+            return;
+    }
+    render(state);
+}
 async function handleKey(key, state, done) {
     if (state.quitting)
         return;
@@ -2703,18 +3282,6 @@ async function handleKey(key, state, done) {
     const screen = state.stack[state.stack.length - 1];
     if (!screen)
         return;
-    // Global p/P: open profile view (skip when actively editing text)
-    if (key === "p" || key === "P") {
-        const isEditing = (screen.kind === "input" && screen.editing) ||
-            (screen.kind === "json-editor" && screen.editing) ||
-            (screen.kind === "settings" && screen.editing);
-        const isProfile = screen.kind === "profile";
-        if (!isEditing && !isProfile) {
-            state.stack.push({ kind: "profile", scroll: 0 });
-            render(state);
-            return;
-        }
-    }
     switch (screen.kind) {
         case "main":
             handleMainKey(key, screen, state, done);
@@ -2752,6 +3319,9 @@ async function handleKey(key, state, done) {
         case "json-editor":
             handleJsonEditorKey(key, screen, state, done);
             break;
+        case "plugins":
+            await handlePluginsKey(key, screen, state, done);
+            break;
     }
 }
 // ─── Shared TUI runner ────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmnkit/cli",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "description": "Command-line interface for Camunda 8 — deploy, manage, and monitor processes from the terminal",
   "type": "module",
   "bin": {
@@ -16,8 +16,10 @@
   },
   "dependencies": {
     "@bpmnkit/api": "0.0.13",
-    "@bpmnkit/ascii": "0.0.14",
+    "@bpmnkit/ascii": "0.0.15",
     "@bpmnkit/connector-gen": "0.0.8",
+    "@bpmnkit/core": "0.0.15",
+    "@bpmnkit/engine": "0.1.14",
     "@bpmnkit/profiles": "0.0.10"
   },
   "publishConfig": {