@bpmnkit/cli 0.0.13 → 0.0.15

package/dist/commands/ask.js

@@ -0,0 +1,413 @@
+import { spawn } from "node:child_process";
+// ─── Spinner ──────────────────────────────────────────────────────────────────
+class Spinner {
+    frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+    i = 0;
+    timer = null;
+    msg = "";
+    isTTY = process.stderr.isTTY === true;
+    start(msg) {
+        this.msg = msg;
+        if (!this.isTTY) {
+            process.stderr.write(`${msg}\n`);
+            return;
+        }
+        process.stderr.write(`${this.frames[0]} ${msg}`);
+        this.timer = setInterval(() => {
+            this.i++;
+            process.stderr.write(`\r${this.frames[this.i % this.frames.length]} ${this.msg}`);
+        }, 80);
+    }
+    update(msg) {
+        this.msg = msg;
+        if (!this.isTTY) {
+            process.stderr.write(`${msg}\n`);
+            return;
+        }
+        process.stderr.write(`\r${this.frames[this.i % this.frames.length]} ${msg}`);
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        if (this.isTTY) {
+            process.stderr.write("\r\x1b[K"); // CR + erase to end of line
+        }
+    }
+}
+// ─── Compact AI adapter ───────────────────────────────────────────────────────
+/** Try claude → copilot → gemini. Return the first available binary name. */
+async function detectAi() {
+    for (const bin of ["claude", "copilot", "gemini"]) {
+        const ok = await Promise.race([
+            new Promise((res) => {
+                const p = spawn(bin, ["--version"], { stdio: "ignore" });
+                p.on("error", () => res(false));
+                p.on("close", (code) => res(code === 0));
+            }),
+            new Promise((res) => setTimeout(() => res(false), 3000)),
+        ]);
+        if (ok)
+            return bin;
+    }
+    return null;
+}
+/** Run an AI binary with the given prompt and collect the full text output. */
+async function runAi(bin, prompt) {
+    return new Promise((resolve, reject) => {
+        let args;
+        if (bin === "claude") {
+            args = [
+                "-p",
+                prompt,
+                "--output-format",
+                "stream-json",
+                "--verbose",
+                "--dangerously-skip-permissions",
+                "--permission-mode",
+                "bypassPermissions",
+            ];
+        }
+        else if (bin === "copilot") {
+            args = ["-p", prompt, "--yolo"];
+        }
+        else {
+            args = ["--prompt", prompt, "--yolo"];
+        }
+        const env = { ...process.env, CLAUDECODE: undefined };
+        const proc = spawn(bin, args, { stdio: ["ignore", "pipe", "pipe"], env });
+        // Drain stderr to prevent the pipe buffer from filling and stalling the child.
+        proc.stderr?.resume();
+        let out = "";
+        let buf = "";
+        if (bin === "claude") {
+            proc.stdout?.on("data", (chunk) => {
+                buf += chunk.toString();
+                const lines = buf.split("\n");
+                buf = lines.pop() ?? "";
+                for (const line of lines) {
+                    if (!line.trim())
+                        continue;
+                    try {
+                        const ev = JSON.parse(line);
+                        if (ev.type === "assistant" && ev.message?.content) {
+                            for (const block of ev.message.content) {
+                                if (block.type === "text" && block.text)
+                                    out += block.text;
+                            }
+                        }
+                    }
+                    catch {
+                        /* skip non-JSON */
+                    }
+                }
+            });
+        }
+        else {
+            proc.stdout?.on("data", (chunk) => {
+                out += chunk.toString();
+            });
+        }
+        proc.on("error", reject);
+        proc.on("close", (code) => {
+            if (code === 0)
+                resolve(out);
+            else
+                reject(new Error(`${bin} exited with code ${code}`));
+        });
+    });
+}
+// ─── System prompt ────────────────────────────────────────────────────────────
+const SYSTEM_PROMPT = [
+    "Convert the user query into a Camunda 8 search spec. Output ONLY a valid JSON object — no prose, no markdown.",
+    "",
+    'Schema: { "resource": <resource>, "filter": { ... } }',
+    "",
+    "Resources and filter fields:",
+    '  "processInstances": state("ACTIVE"|"COMPLETED"|"TERMINATED"), hasIncident(bool), processDefinitionId(str), processInstanceKey(str)',
+    '  "incidents":        state("ACTIVE"|"RESOLVED"), type(str), processInstanceKey(str), processDefinitionKey(str)',
+    '  "userTasks":        state("CREATED"|"COMPLETED"|"CANCELED"), processInstanceKey(str), assignee(str)',
+    '  "variables":        name(str), value(str — JSON-serialized: 3355→"3355", true→"true", hello→"\\"hello\\""), processInstanceKey(str)',
+    '  "jobs":             state("ACTIVATABLE"|"ACTIVE"|"FAILED"|"COMPLETED"|"CANCELED"|"ERROR_THROWN"), type(str), processInstanceKey(str)',
+    '  "decisionInstances": decisionDefinitionId(str), state("EVALUATED"|"FAILED"), processInstanceKey(str)',
+    "",
+    'Use "variables" whenever a variable name or value is mentioned.',
+    "Omit filter fields that are not relevant. Output ONLY the JSON object.",
+].join("\n");
+async function fetchSpec(spec, getClient) {
+    const client = await getClient();
+    const filter = spec.filter;
+    const body = { filter };
+    switch (spec.resource) {
+        case "processInstances": {
+            const result = await client.processInstance.searchProcessInstances(body);
+            const items = result.items ?? [];
+            const total = result.page?.totalItems ?? items.length;
+            return {
+                resource: spec.resource,
+                filter,
+                items,
+                total,
+                columns: [
+                    { key: "processInstanceKey", header: "PROCESS INSTANCE KEY", maxWidth: 22 },
+                    { key: "processDefinitionId", header: "PROCESS", maxWidth: 30 },
+                    { key: "state", header: "STATE", maxWidth: 12 },
+                    { key: "startDate", header: "STARTED", maxWidth: 20, transform: relTime },
+                    { key: "hasIncident", header: "INCIDENT", maxWidth: 8 },
+                ],
+                relations: [
+                    {
+                        groupName: "process-instance",
+                        commandName: "get",
+                        description: "View process instance",
+                        params: [{ field: "processInstanceKey", param: "processInstanceKey" }],
+                    },
+                ],
+            };
+        }
+        case "incidents": {
+            const result = await client.incident.searchIncidents(body);
+            const items = result.items ?? [];
+            const total = result.page?.totalItems ?? items.length;
+            return {
+                resource: spec.resource,
+                filter,
+                items,
+                total,
+                columns: [
+                    { key: "incidentKey", header: "INCIDENT KEY", maxWidth: 22 },
+                    { key: "processInstanceKey", header: "PROCESS INSTANCE KEY", maxWidth: 22 },
+                    { key: "type", header: "TYPE", maxWidth: 28 },
+                    { key: "state", header: "STATE", maxWidth: 10 },
+                    { key: "message", header: "MESSAGE", maxWidth: 50 },
+                ],
+                relations: [
+                    {
+                        groupName: "process-instance",
+                        commandName: "get",
+                        description: "View process instance",
+                        params: [{ field: "processInstanceKey", param: "processInstanceKey" }],
+                    },
+                ],
+            };
+        }
+        case "userTasks": {
+            const result = await client.userTask.searchUserTasks(body);
+            const items = result.items ?? [];
+            const total = result.page?.totalItems ?? items.length;
+            return {
+                resource: spec.resource,
+                filter,
+                items,
+                total,
+                columns: [
+                    { key: "userTaskKey", header: "USER TASK KEY", maxWidth: 22 },
+                    { key: "processInstanceKey", header: "PROCESS INSTANCE KEY", maxWidth: 22 },
+                    { key: "elementId", header: "ELEMENT", maxWidth: 24 },
+                    { key: "assignee", header: "ASSIGNEE", maxWidth: 20 },
+                    { key: "state", header: "STATE", maxWidth: 12 },
+                ],
+                relations: [
+                    {
+                        groupName: "user-task",
+                        commandName: "get",
+                        description: "View user task",
+                        params: [{ field: "userTaskKey", param: "userTaskKey" }],
+                    },
+                    {
+                        groupName: "process-instance",
+                        commandName: "get",
+                        description: "View process instance",
+                        params: [{ field: "processInstanceKey", param: "processInstanceKey" }],
+                    },
+                ],
+            };
+        }
+        case "variables": {
+            const result = await client.variable.searchVariables(body);
+            const items = result.items ?? [];
+            const total = result.page?.totalItems ?? items.length;
+            return {
+                resource: spec.resource,
+                filter,
+                items,
+                total,
+                columns: [
+                    { key: "variableKey", header: "VARIABLE KEY", maxWidth: 22 },
+                    { key: "processInstanceKey", header: "PROCESS INSTANCE KEY", maxWidth: 22 },
+                    { key: "name", header: "NAME", maxWidth: 24 },
+                    { key: "value", header: "VALUE", maxWidth: 50 },
+                ],
+                relations: [
+                    {
+                        groupName: "variable",
+                        commandName: "get",
+                        description: "View variable",
+                        params: [{ field: "variableKey", param: "variableKey" }],
+                    },
+                    {
+                        groupName: "process-instance",
+                        commandName: "get",
+                        description: "View process instance",
+                        params: [{ field: "processInstanceKey", param: "processInstanceKey" }],
+                    },
+                ],
+            };
+        }
+        case "jobs": {
+            const result = await client.job.searchJobs(body);
+            const items = result.items ?? [];
+            const total = result.page?.totalItems ?? items.length;
+            return {
+                resource: spec.resource,
+                filter,
+                items,
+                total,
+                columns: [
+                    { key: "jobKey", header: "JOB KEY", maxWidth: 22 },
+                    { key: "processInstanceKey", header: "PROCESS INSTANCE KEY", maxWidth: 22 },
+                    { key: "type", header: "TYPE", maxWidth: 28 },
+                    { key: "state", header: "STATE", maxWidth: 12 },
+                    { key: "retries", header: "RETRIES", maxWidth: 8 },
+                ],
+                relations: [
+                    {
+                        groupName: "process-instance",
+                        commandName: "get",
+                        description: "View process instance",
+                        params: [{ field: "processInstanceKey", param: "processInstanceKey" }],
+                    },
+                ],
+            };
+        }
+        case "decisionInstances": {
+            const result = await client.decisionInstance.searchDecisionInstances(body);
+            const items = result.items ?? [];
+            const total = result.page?.totalItems ?? items.length;
+            return {
+                resource: spec.resource,
+                filter,
+                items,
+                total,
+                columns: [
+                    { key: "decisionInstanceKey", header: "DECISION INSTANCE KEY", maxWidth: 22 },
+                    { key: "processInstanceKey", header: "PROCESS INSTANCE KEY", maxWidth: 22 },
+                    { key: "decisionDefinitionId", header: "DECISION", maxWidth: 30 },
+                    { key: "state", header: "STATE", maxWidth: 12 },
+                ],
+                relations: [
+                    {
+                        groupName: "process-instance",
+                        commandName: "get",
+                        description: "View process instance",
+                        params: [{ field: "processInstanceKey", param: "processInstanceKey" }],
+                    },
+                ],
+            };
+        }
+        default:
+            throw new Error(`Unknown resource: "${spec.resource}"`);
+    }
+}
+function relTime(value) {
+    if (typeof value !== "string" || !value)
+        return "—";
+    const d = new Date(value);
+    const diff = Date.now() - d.getTime();
+    const m = Math.floor(diff / 60_000);
+    if (m < 1)
+        return "just now";
+    if (m < 60)
+        return `${m}m ago`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h ${m % 60}m ago`;
+    return d.toLocaleString(undefined, {
+        month: "short",
+        day: "numeric",
+        hour: "2-digit",
+        minute: "2-digit",
+    });
+}
+// ─── Quick-parse bypass (no AI needed) ───────────────────────────────────────
+function quickParse(query) {
+    const q = query.trim().toLowerCase();
+    // Pure numeric → process instance key lookup
+    if (/^\d+$/.test(query.trim())) {
+        return { resource: "processInstances", filter: { processInstanceKey: query.trim() } };
+    }
+    // Single state keyword
+    const stateMap = {
+        active: { resource: "processInstances", filter: { state: "ACTIVE" } },
+        completed: { resource: "processInstances", filter: { state: "COMPLETED" } },
+        terminated: { resource: "processInstances", filter: { state: "TERMINATED" } },
+        incidents: { resource: "incidents", filter: {} },
+    };
+    if (q in stateMap)
+        return stateMap[q] ?? null;
+    return null;
+}
+// ─── Exported query runner ────────────────────────────────────────────────────
+export async function runAskQuery(query, getClient, onStatus) {
+    // Try quick-parse first (no AI token cost)
+    const quick = quickParse(query);
+    if (quick) {
+        return fetchSpec(quick, getClient);
+    }
+    // Detect AI binary
+    onStatus("Detecting AI…");
+    const bin = await detectAi();
+    if (!bin) {
+        throw new Error("No AI CLI found. Install claude, copilot, or gemini and ensure it is in PATH.");
+    }
+    // Ask AI to translate query → search spec
+    onStatus(`Asking ${bin}…`);
+    const fullPrompt = `${SYSTEM_PROMPT}\n\nQuery: ${query}\n\nJSON:`;
+    const raw = await runAi(bin, fullPrompt);
+    // Extract JSON from the response (strip any prose/markdown fences)
+    const jsonMatch = raw.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) {
+        throw new Error(`AI returned no JSON.\n\nRaw output:\n${raw}`);
+    }
+    let spec;
+    try {
+        spec = JSON.parse(jsonMatch[0]);
+    }
+    catch {
+        throw new Error(`AI returned invalid JSON.\n\nRaw output:\n${raw}`);
+    }
+    // Execute the spec against the API
+    onStatus(`Searching ${spec.resource}…`);
+    return fetchSpec(spec, getClient);
+}
+// ─── Command group ────────────────────────────────────────────────────────────
+export const askGroup = {
+    name: "ask",
+    description: "Natural language search using a local AI (claude/copilot/gemini)",
+    commands: [
+        {
+            name: "query",
+            description: "Ask in plain language; the AI translates it to a Camunda API search",
+            args: [{ name: "query", description: "Natural language query", required: true }],
+            async run(ctx) {
+                const query = ctx.positional.join(" ").trim();
+                if (!query)
+                    throw new Error("Provide a query, e.g.: casen ask active incidents");
+                const spinner = new Spinner();
+                try {
+                    spinner.start("Detecting AI…");
+                    const result = await runAskQuery(query, ctx.getClient, (msg) => spinner.update(msg));
+                    spinner.stop();
+                    ctx.output.info(`${result.resource} ${JSON.stringify(result.filter)}`);
+                    ctx.output.printList({ items: result.items, page: { totalItems: result.total } }, result.columns);
+                }
+                catch (err) {
+                    spinner.stop();
+                    throw err;
+                }
+            },
+        },
+    ],
+};
+//# sourceMappingURL=ask.js.map

package/dist/commands/index.js

@@ -1,5 +1,6 @@
 import { adminCommandGroups } from "../generated/admin-commands.js";
 import { decisionDefinitionGroup, decisionRequirementsGroup, generatedCommandGroups, jobGroup, processDefinitionGroup, userTaskGroup, } from "../generated/commands.js";
+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";
@@ -32,16 +33,50 @@ const customisedGroups = generatedCommandGroups.map((g) => {
     }
     return g;
 });
-const allGroups = [
-    profileGroup,
-    settingsGroup,
+const sortedOtherGroups = [
     connectorGroup,
     ...customisedGroups,
     ...adminCommandGroups,
     completionGroup,
+].sort((a, b) => a.name.localeCompare(b.name));
+export const commandGroups = [
+    askGroup,
+    settingsGroup,
+    profileGroup,
+    ...sortedOtherGroups,
 ];
-// Sort alphabetically by name for the main menu
-export const commandGroups = allGroups.sort((a, b) => a.name.localeCompare(b.name));
 // 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
+// list, so they have no `columns` and are skipped by computeRelations).
+const piGroup = commandGroups.find((g) => g.name === "process-instance");
+const pdGroup = commandGroups.find((g) => g.name === "process-definition");
+const piGetCmd = piGroup?.commands.find((c) => c.name === "get");
+const pdGetCmd = pdGroup?.commands.find((c) => c.name === "get");
+const pdRelations = [
+    {
+        groupName: "process-definition",
+        commandName: "get",
+        description: "View process definition",
+        params: [{ field: "processDefinitionKey", param: "processDefinitionKey" }],
+    },
+    {
+        groupName: "process-definition",
+        commandName: "render",
+        description: "Render BPMN diagram",
+        params: [{ field: "processDefinitionKey", param: "processDefinitionKey" }],
+    },
+    {
+        groupName: "process-definition",
+        commandName: "get-xml",
+        description: "Get BPMN XML",
+        params: [{ field: "processDefinitionKey", param: "processDefinitionKey" }],
+    },
+];
+if (piGetCmd) {
+    piGetCmd.relations = pdRelations;
+}
+if (pdGetCmd) {
+    pdGetCmd.relations = pdRelations.filter((r) => r.commandName !== "get");
+}
 //# sourceMappingURL=index.js.map

package/dist/generated/commands.js

@@ -406,21 +406,6 @@ export const decisionInstanceGroup = {
             argName: "decisionEvaluationInstanceKey",
             get: (client, key) => client.decisionInstance.getDecisionInstance(key),
         }),
-        {
-            name: "delete",
-            description: "Delete decision instance",
-            args: [{ name: "decisionInstanceKey", description: "decisionInstanceKey", required: true }],
-            flags: [DATA_OPT_FLAG],
-            async run(ctx) {
-                const decisionInstanceKey = ctx.positional[0];
-                if (!decisionInstanceKey)
-                    throw new Error("Missing required argument: <decisionInstanceKey>");
-                const body = parseJson(ctx.flags.data, "data");
-                const client = await ctx.getClient();
-                await client.decisionInstance.deleteDecisionInstance(decisionInstanceKey, body);
-                ctx.output.ok("delete completed.");
-            },
-        },
         makeCreateCmd({
             name: "delete-batch-operation",
             description: "Delete decision instances (batch)",

package/dist/run.js

@@ -6,7 +6,7 @@ import { printCommandHelp, printGlobalHelp, printGroupHelp, printVersion } from
 import { createNullWriter, createOutputWriter, printRawResponse } from "./output.js";
 import { runProfileManager } from "./profile-tui.js";
 import { runSettingsManager } from "./settings-tui.js";
-import { runGroupTui, runMainTui } from "./tui.js";
+import { runAskTui, runGroupTui, runMainTui } from "./tui.js";
 // ─── Profile info ─────────────────────────────────────────────────────────────
 function buildProfileInfo(profileName) {
     const effectiveName = profileName ?? getActiveName() ?? "none";
@@ -91,9 +91,32 @@ export async function run(argv) {
         process.exitCode = 1;
         return;
     }
+    // ── ask: join remaining positionals as the query ─────────────────────────
+    if (group.name === "ask" && positional.length >= 2 && !wantHelp) {
+        const queryWords = positional.slice(1);
+        const output = createOutputWriter((flags.output ?? flags.o ?? "table"), flags["no-color"] === true);
+        const ctx = {
+            positional: queryWords,
+            flags,
+            output,
+            getClient: () => Promise.resolve(createClientFromProfile(profileName)),
+            getAdminClient: () => Promise.resolve(createAdminClientFromProfile(profileName)),
+        };
+        const cmd = group.commands[0];
+        if (cmd)
+            await cmd.run(ctx);
+        return;
+    }
     // ── TUI (no subcommand, no --help) ───────────────────────────────────────
     if (positional.length === 1 && !wantHelp) {
-        if (group.name === "profile") {
+        if (group.name === "ask") {
+            const { name: pName, info: pInfo } = buildProfileInfo(profileName);
+            await runAskTui(commandGroups, getClient, getAdminClient, {
+                profile: pName,
+                profileInfo: pInfo,
+            });
+        }
+        else if (group.name === "profile") {
             await runProfileManager();
         }
         else if (group.name === "settings") {

package/dist/tui.js

@@ -1,6 +1,7 @@
 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";
 // ─── ANSI helpers ─────────────────────────────────────────────────────────────
 const CSI = "\x1b[";
 const HIDE = `${CSI}?25l`;
@@ -375,6 +376,10 @@ 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) {
+            lines.push(`  ${dim("─".repeat(cols - 4))}`);
+        }
     }
     if (groups.length > viewH) {
         const hi = Math.min(screen.scroll + viewH, groups.length);
@@ -386,6 +391,33 @@ function renderMain(state, screen) {
     lines.push(`\n${hint}`);
     return lines;
 }
+const ASK_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+let askSpinnerFrame = 0;
+function renderAsk(state, screen) {
+    const { cols } = termSize();
+    const lines = [
+        renderHeader(["casen", "ask"], cols, state.profile),
+        `\n  ${dim("Natural language search using a local AI (claude/copilot/gemini)")}\n`,
+    ];
+    const inputLine = `  > ${renderText(screen.query, screen.cursor, cols - 6, true)}`;
+    lines.push(inputLine);
+    lines.push("");
+    if (screen.status === "running" && screen.statusMsg) {
+        const frame = ASK_SPINNER_FRAMES[askSpinnerFrame % ASK_SPINNER_FRAMES.length] ?? "⠋";
+        lines.push(`  ${frame} ${dim(screen.statusMsg)}`);
+    }
+    else if (screen.error) {
+        lines.push(`  ${red("error:")} ${screen.error}`);
+    }
+    lines.push("");
+    if (screen.status === "running") {
+        lines.push(`  ${dim("type query")}  ${cyan("enter")} run  ${cyan("esc")} back  ${cyan("^C")} abort`);
+    }
+    else {
+        lines.push(`  ${dim("type query")}  ${cyan("enter")} run  ${cyan("esc")} back  ${cyan("^C")} quit`);
+    }
+    return lines;
+}
 function renderCommands(state, screen) {
     const { cols, rows } = termSize();
     const searching = screen.search.length > 0;
@@ -688,9 +720,10 @@ function renderResults(state, screen) {
             lines.push(isCursor ? inv(line.padEnd(cols - 1)) : line);
         }
         const spaceHint = entries.some(([, v]) => v instanceof ArrayValue)
-            ? `  ${cyan("space")} expand array`
+            ? `  ${cyan("space")} expand`
             : "";
-        lines.push(`\n${rawToggle}${curlToggle}${spaceHint}  ${cyan("m")} main menu  ${cyan("esc")} back  ${cyan("q")} quit`);
+        const fHint = screen.cmd.relations ? `  ${cyan("f")} follow-up` : "";
+        lines.push(`\n  ${dim("↑↓")} navigate  ${cyan("enter")} navigate field${spaceHint}${fHint}${rawToggle}${curlToggle}  ${cyan("m")} main  ${cyan("esc")} back  ${cyan("q")} quit`);
     }
     else {
         lines.push(renderHeader([screen.group.name, screen.cmd.name], cols, state.profile));
@@ -746,7 +779,8 @@ function renderDetail(state, screen) {
     const spaceHint = entries.some(([, v]) => v instanceof ArrayValue)
         ? `  ${cyan("space/→")} expand  ${cyan("←")} back`
         : `  ${cyan("←")} back`;
-    lines.push(`  ${dim("↑↓")} navigate${spaceHint}  ${cyan("m")} main menu  ${cyan("esc")} back  ${cyan("q")} quit`);
+    const fHint = screen.cmd?.relations ? `  ${cyan("f")} follow-up` : "";
+    lines.push(`  ${dim("↑↓")} navigate  ${cyan("enter")} navigate field${spaceHint}${fHint}  ${cyan("m")} main  ${cyan("esc")} back  ${cyan("q")} quit`);
     return lines;
 }
 function renderFollowup(state, screen) {
@@ -1171,6 +1205,160 @@ function launchWorkerView(inputScreen, state) {
         stopWorkerScreen(ws);
     });
 }
+// ─── Ask screen helpers ───────────────────────────────────────────────────────
+async function runAskInTui(screen, state) {
+    let frame = 0;
+    screen._timer = setInterval(() => {
+        frame++;
+        askSpinnerFrame = frame;
+        if (!state.quitting && state.stack.includes(screen)) {
+            render(state);
+        }
+        else {
+            if (screen._timer !== null) {
+                clearInterval(screen._timer);
+                screen._timer = null;
+            }
+        }
+    }, 80);
+    let result;
+    try {
+        result = await runAskQuery(screen.query, state.getClient, (msg) => {
+            screen.statusMsg = msg;
+        });
+    }
+    catch (err) {
+        if (screen._timer !== null) {
+            clearInterval(screen._timer);
+            screen._timer = null;
+        }
+        screen.error = err instanceof Error ? err.message : String(err);
+        screen.status = "idle";
+        screen.statusMsg = "";
+        render(state);
+        return;
+    }
+    if (screen._timer !== null) {
+        clearInterval(screen._timer);
+        screen._timer = null;
+    }
+    const askGrp = state.groups.find((g) => g.name === "ask") ?? {
+        name: "ask",
+        description: "",
+        commands: [],
+    };
+    const syntheticCmd = {
+        name: result.resource,
+        description: "AI search results",
+        run: async () => { },
+        relations: result.relations,
+    };
+    state.stack.push({
+        kind: "results",
+        group: askGrp,
+        cmd: syntheticCmd,
+        output: {
+            type: "list",
+            items: result.items,
+            columns: result.columns,
+            total: result.total,
+        },
+        raw: null,
+        rawView: false,
+        curlView: false,
+        altView: false,
+        cursor: 0,
+        scroll: 0,
+    });
+    render(state);
+}
+async function handleAskKey(key, screen, state, done) {
+    // Ctrl+C always quits
+    if (key === "\x03") {
+        done();
+        return;
+    }
+    // ESC: if running do nothing; otherwise pop
+    if (key === "\x1b") {
+        if (screen.status === "running") {
+            render(state);
+            return;
+        }
+        if (screen._timer !== null) {
+            clearInterval(screen._timer);
+            screen._timer = null;
+        }
+        state.stack.pop();
+        render(state);
+        return;
+    }
+    // Enter: run if not running and has query
+    if (key === "\r" || key === "\n") {
+        if (screen.status !== "running" && screen.query.trim()) {
+            screen.status = "running";
+            screen.statusMsg = "";
+            screen.error = "";
+            render(state);
+            runAskInTui(screen, state).catch((err) => {
+                if (screen._timer !== null) {
+                    clearInterval(screen._timer);
+                    screen._timer = null;
+                }
+                screen.error = err instanceof Error ? err.message : String(err);
+                screen.status = "idle";
+                render(state);
+            });
+        }
+        return;
+    }
+    // Text editing (only when idle)
+    if (screen.status === "running") {
+        render(state);
+        return;
+    }
+    switch (key) {
+        case "\x7f": // backspace
+        case "\x08":
+            if (screen.cursor > 0) {
+                screen.query = screen.query.slice(0, screen.cursor - 1) + screen.query.slice(screen.cursor);
+                screen.cursor--;
+            }
+            break;
+        case "\x01": // Ctrl+A
+        case "\x1b[H":
+            screen.cursor = 0;
+            break;
+        case "\x05": // Ctrl+E
+        case "\x1b[F":
+            screen.cursor = screen.query.length;
+            break;
+        case "\x0b": // Ctrl+K — clear to end
+            screen.query = screen.query.slice(0, screen.cursor);
+            break;
+        case "\x15": // Ctrl+U — clear line
+            screen.query = "";
+            screen.cursor = 0;
+            break;
+        case "\x1b[D": // left arrow
+            if (screen.cursor > 0)
+                screen.cursor--;
+            break;
+        case "\x1b[C": // right arrow
+            if (screen.cursor < screen.query.length)
+                screen.cursor++;
+            break;
+        default: {
+            const printable = [...key].filter((ch) => ch >= " ").join("");
+            if (printable) {
+                screen.query =
+                    screen.query.slice(0, screen.cursor) + printable + screen.query.slice(screen.cursor);
+                screen.cursor += printable.length;
+            }
+            break;
+        }
+    }
+    render(state);
+}
 function render(state) {
     if (state.quitting)
         return;
@@ -1182,6 +1370,9 @@ function render(state) {
         case "main":
             lines = renderMain(state, screen);
             break;
+        case "ask":
+            lines = renderAsk(state, screen);
+            break;
         case "commands":
             lines = renderCommands(state, screen);
             break;
@@ -1283,6 +1474,17 @@ function handleMainKey(key, screen, state, done) {
                     message: "",
                 });
             }
+            else if (group?.name === "ask") {
+                state.stack.push({
+                    kind: "ask",
+                    query: "",
+                    cursor: 0,
+                    status: "idle",
+                    statusMsg: "",
+                    error: "",
+                    _timer: null,
+                });
+            }
             else if (group) {
                 state.stack.push({ kind: "commands", group, cursor: 0, search: "" });
             }
@@ -1762,6 +1964,41 @@ function handleResultsKey(key, screen, state, done) {
                 screen.cursor++;
             else if (key === " " || key === "\x1b[C")
                 expandArray();
+            else if (key === "\r" || key === "\n") {
+                const entry = entries[screen.cursor];
+                if (entry) {
+                    const [fieldKey, v] = entry;
+                    if (v instanceof ArrayValue) {
+                        expandArray();
+                    }
+                    else {
+                        const resolved = resolveRelationsForField(fieldKey, screen.cmd.relations, state.groups);
+                        if (resolved.length > 0) {
+                            state.stack.push({
+                                kind: "followup",
+                                sourceGroup: screen.group,
+                                item: screen.output.data,
+                                relations: resolved,
+                                cursor: 0,
+                                scroll: 0,
+                            });
+                        }
+                    }
+                }
+            }
+            else if (key === "f" || key === "F") {
+                const resolved = resolveAllRelations(screen.cmd.relations, state.groups);
+                if (resolved.length > 0) {
+                    state.stack.push({
+                        kind: "followup",
+                        sourceGroup: screen.group,
+                        item: screen.output.data,
+                        relations: resolved,
+                        cursor: 0,
+                        scroll: 0,
+                    });
+                }
+            }
             else if (key === "\x1b[D")
                 state.stack.pop();
             else if (key === "\x1b")
@@ -1851,6 +2088,7 @@ function handleResultsKey(key, screen, state, done) {
                 state.stack.push({
                     kind: "detail",
                     group: screen.group,
+                    cmd: screen.cmd,
                     item,
                     label: "detail",
                     cursor: 0,
@@ -1862,17 +2100,8 @@ function handleResultsKey(key, screen, state, done) {
         case "f":
         case "F": {
             const item = screen.output.items[screen.cursor];
-            if (item && screen.cmd.relations) {
-                const resolved = [];
-                for (const rel of screen.cmd.relations) {
-                    const tGroup = state.groups.find((g) => g.name === rel.groupName);
-                    if (!tGroup)
-                        continue;
-                    const tCmd = tGroup.commands.find((c) => c.name === rel.commandName);
-                    if (!tCmd)
-                        continue;
-                    resolved.push({ group: tGroup, cmd: tCmd, params: rel.params });
-                }
+            if (item) {
+                const resolved = resolveAllRelations(screen.cmd.relations, state.groups);
                 if (resolved.length > 0) {
                     state.stack.push({
                         kind: "followup",
@@ -1900,6 +2129,25 @@ function handleResultsKey(key, screen, state, done) {
     }
     render(state);
 }
+function resolveAllRelations(relations, groups) {
+    if (!relations)
+        return [];
+    const out = [];
+    for (const rel of relations) {
+        const tGroup = groups.find((g) => g.name === rel.groupName);
+        if (!tGroup)
+            continue;
+        const tCmd = tGroup.commands.find((c) => c.name === rel.commandName);
+        if (!tCmd)
+            continue;
+        out.push({ group: tGroup, cmd: tCmd, params: rel.params });
+    }
+    return out;
+}
+function resolveRelationsForField(fieldName, relations, groups) {
+    const matching = (relations ?? []).filter((rel) => rel.params.some((p) => p.field === fieldName));
+    return resolveAllRelations(matching, groups);
+}
 function handleDetailKey(key, screen, state, done) {
     const { rows } = termSize();
     const viewH = Math.max(3, rows - 7);
@@ -1946,9 +2194,59 @@ function handleDetailKey(key, screen, state, done) {
             }
             break;
         }
+        case "\r":
+        case "\n": {
+            const entry = entries[screen.cursor];
+            if (entry && typeof screen.item === "object" && screen.item !== null) {
+                const [fieldKey, v] = entry;
+                if (v instanceof ArrayValue) {
+                    state.stack.push({
+                        kind: "detail",
+                        group: screen.group,
+                        item: v.items,
+                        label: `${fieldKey} (${v.items.length})`,
+                        cursor: 0,
+                        scroll: 0,
+                    });
+                }
+                else {
+                    const item = screen.item;
+                    const resolved = resolveRelationsForField(fieldKey, screen.cmd?.relations, state.groups);
+                    if (resolved.length > 0) {
+                        state.stack.push({
+                            kind: "followup",
+                            sourceGroup: screen.group,
+                            item,
+                            relations: resolved,
+                            cursor: 0,
+                            scroll: 0,
+                        });
+                    }
+                }
+            }
+            break;
+        }
         case "\x1b[D":
             state.stack.pop();
             break;
+        case "f":
+        case "F": {
+            if (typeof screen.item === "object" && screen.item !== null) {
+                const item = screen.item;
+                const resolved = resolveAllRelations(screen.cmd?.relations, state.groups);
+                if (resolved.length > 0) {
+                    state.stack.push({
+                        kind: "followup",
+                        sourceGroup: screen.group,
+                        item,
+                        relations: resolved,
+                        cursor: 0,
+                        scroll: 0,
+                    });
+                }
+            }
+            break;
+        }
         case "m":
         case "M":
             popToMain(state);
@@ -2421,6 +2719,9 @@ async function handleKey(key, state, done) {
         case "main":
             handleMainKey(key, screen, state, done);
             break;
+        case "ask":
+            await handleAskKey(key, screen, state, done);
+            break;
         case "commands":
             handleCommandsKey(key, screen, state, done);
             break;
@@ -2520,6 +2821,23 @@ export async function runMainTui(groups, getClient, getAdminClient, opts) {
         profileInfo: opts?.profileInfo ?? [],
     });
 }
+/** Open the TUI directly at the ask screen (natural language search). */
+export async function runAskTui(groups, getClient, getAdminClient, opts) {
+    return startTui({
+        groups,
+        stack: [
+            { kind: "main", cursor: 0, scroll: 0, search: "" },
+            { kind: "ask", query: "", cursor: 0, status: "idle", statusMsg: "", error: "", _timer: null },
+        ],
+        getClient,
+        getAdminClient: getAdminClient ??
+            opts?.getAdminClient ??
+            (() => Promise.reject(new Error("No admin client"))),
+        quitting: false,
+        profile: opts?.profile ?? "",
+        profileInfo: opts?.profileInfo ?? [],
+    });
+}
 /**
  * Open the TUI directly at a specific group's command list.
  * The main menu is placed at the bottom of the stack so `m` always works.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmnkit/cli",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "Command-line interface for Camunda 8 — deploy, manage, and monitor processes from the terminal",
   "type": "module",
   "bin": {
@@ -15,9 +15,9 @@
     "node": ">=20"
   },
   "dependencies": {
+    "@bpmnkit/connector-gen": "0.0.7",
     "@bpmnkit/api": "0.0.12",
-    "@bpmnkit/ascii": "0.0.12",
-    "@bpmnkit/connector-gen": "0.0.6",
+    "@bpmnkit/ascii": "0.0.13",
     "@bpmnkit/profiles": "0.0.9"
   },
   "publishConfig": {