@bpmnkit/cli 0.0.9

package/README.md

@@ -0,0 +1,113 @@
+# casen
+
+CLI for the [Camunda 8 Orchestration Cluster REST API (v2)](https://docs.camunda.io/docs/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview/).
+
+Commands are auto-generated from the official OpenAPI specs — every resource and operation stays in sync automatically. See [DOCUMENTATION.md](./DOCUMENTATION.md) for the full command reference.
+
+## Features
+
+- **All API resources** — process instances, jobs, user tasks, decisions, users, groups, tenants, and more
+- **Multiple profiles** — store named connection configs and switch between them instantly
+- **Three output formats** — human-readable table (default), `--output json`, `--output yaml`
+- **Shell completions** — bash, zsh, and fish
+- **Zero dependencies** — no runtime requirements beyond Node.js
+
+## Installation
+
+```bash
+# From the monorepo root
+pnpm build
+
+# Then link globally (optional)
+npm link ./apps/cli
+```
+
+## Quick start
+
+**1. Create a profile**
+
+```bash
+# Bearer token (local / self-managed)
+casen profile create local \
+  --base-url http://localhost:8080/v2 \
+  --auth-type bearer \
+  --token my-token
+
+# OAuth2 (Camunda SaaS)
+casen profile create prod \
+  --base-url https://<cluster-id>.camunda.io/v2 \
+  --auth-type oauth2 \
+  --client-id <client-id> \
+  --client-secret <client-secret> \
+  --token-url https://login.cloud.camunda.io/oauth/token
+```
+
+The first profile created becomes the active profile automatically.
+
+**Import from a Camunda Cloud credentials file**
+
+When you create a client in Camunda Cloud, you can download a credentials file containing `export KEY='VALUE'` declarations. Import it directly:
+
+```bash
+casen profile import prod ./camunda-credentials.sh
+
+# or pipe via stdin
+cat camunda-credentials.sh | casen profile import prod -
+```
+
+The file must contain at least:
+
+| Variable | Fallback |
+|----------|----------|
+| `ZEEBE_REST_ADDRESS` | _(required)_ |
+| `CAMUNDA_CLIENT_ID` | `ZEEBE_CLIENT_ID` |
+| `CAMUNDA_CLIENT_SECRET` | `ZEEBE_CLIENT_SECRET` |
+| `CAMUNDA_OAUTH_URL` | `ZEEBE_AUTHORIZATION_SERVER_URL` |
+
+**2. Run a command**
+
+```bash
+casen process-instance list --filter '{"state":"ACTIVE"}'
+casen user-task list --filter '{"assignee":"alice"}'
+casen process-instance create --data '{"processDefinitionId":"order-process"}'
+```
+
+## Profiles
+
+Profiles store connection configuration in the OS config directory:
+
+| Platform | Location |
+|----------|----------|
+| Linux | `$XDG_CONFIG_HOME/casen/config.json` or `~/.config/casen/config.json` |
+| macOS | `~/Library/Application Support/casen/config.json` |
+| Windows | `%APPDATA%\casen\config.json` |
+
+Use `--profile <name>` on any command to temporarily override the active profile.
+
+## Output formats
+
+Results can be printed as a table (default), JSON, or YAML via `--output json` / `--output yaml`. Colors and table formatting are automatically disabled when stdout is not a TTY or when `NO_COLOR` is set.
+
+## Shell completions
+
+```bash
+# zsh
+mkdir -p ~/.zfunc && casen completion zsh > ~/.zfunc/_casen
+# add to ~/.zshrc: fpath=(~/.zfunc $fpath) && autoload -Uz compinit && compinit
+
+# bash
+casen completion bash >> ~/.bash_completion
+
+# fish
+casen completion fish > ~/.config/fish/completions/casen.fish
+```
+
+## Help
+
+```bash
+casen --help                       # Global help
+casen <resource> --help            # Resource-level help
+casen <resource> <command> --help  # Command-level help
+```
+
+For all available resources and commands see [DOCUMENTATION.md](./DOCUMENTATION.md).

package/dist/args.js

@@ -0,0 +1,101 @@
+/**
+ * Parse argv tokens into positional arguments and flags.
+ *
+ * Supports:
+ *   --flag value        string / number flag
+ *   --flag=value        alternative syntax
+ *   --flag              boolean flag (true)
+ *   --no-flag           boolean flag negation (false)
+ *   -f value            short flag
+ *   -f=value            short flag with equals
+ *   --                  stop flag parsing; everything after is positional
+ */
+export function parseArgs(argv) {
+    const positional = [];
+    const flags = {};
+    let i = 0;
+    let stopFlags = false;
+    while (i < argv.length) {
+        const arg = argv[i] ?? "";
+        if (stopFlags || arg === "") {
+            positional.push(arg);
+            i++;
+            continue;
+        }
+        if (arg === "--") {
+            stopFlags = true;
+            i++;
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            const raw = arg.slice(2);
+            const eqIdx = raw.indexOf("=");
+            if (eqIdx >= 0) {
+                // --flag=value
+                const name = raw.slice(0, eqIdx);
+                const value = raw.slice(eqIdx + 1);
+                flags[name] = coerce(value);
+            }
+            else if (raw.startsWith("no-")) {
+                // --no-flag → false
+                flags[raw.slice(3)] = false;
+            }
+            else {
+                // --flag [value?]
+                const next = argv[i + 1];
+                if (next !== undefined && !next.startsWith("-")) {
+                    flags[raw] = coerce(next);
+                    i++;
+                }
+                else {
+                    flags[raw] = true;
+                }
+            }
+        }
+        else if (arg.startsWith("-") && arg.length === 2) {
+            // -f [value?]
+            const short = arg.slice(1);
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith("-")) {
+                flags[short] = coerce(next);
+                i++;
+            }
+            else {
+                flags[short] = true;
+            }
+        }
+        else if (arg.startsWith("-") && arg.length > 2 && arg[2] !== "-") {
+            // -fVALUE or -f=VALUE
+            const short = arg[1] ?? "";
+            const rest = arg.slice(2).replace(/^=/, "");
+            flags[short] = coerce(rest);
+        }
+        else {
+            positional.push(arg);
+        }
+        i++;
+    }
+    return { positional, flags };
+}
+/** Coerce string to number or boolean if it looks like one. */
+function coerce(value) {
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    const n = Number(value);
+    if (!Number.isNaN(n) && value.trim() !== "")
+        return n;
+    return value;
+}
+/** Resolve a flag value with a fallback, returning it as a string. */
+export function flagStr(flags, name, short) {
+    const v = flags[name] ?? (short ? flags[short] : undefined);
+    return v !== undefined ? String(v) : undefined;
+}
+/** Resolve a flag value as a boolean. */
+export function flagBool(flags, name, short) {
+    const v = flags[name] ?? (short ? flags[short] : undefined);
+    return v === true || v === "true" || v === 1;
+}
+//# sourceMappingURL=args.js.map

package/dist/client.js

@@ -0,0 +1,19 @@
+import { AdminApiClient, CamundaClient } from "@bpmn-sdk/api";
+import { getActiveProfile, getProfile } from "./profile.js";
+function requireProfile(profileName) {
+    const profile = profileName ? getProfile(profileName) : getActiveProfile();
+    if (!profile) {
+        if (profileName) {
+            throw new Error(`Profile "${profileName}" not found. Run \`casen profile list\` to see available profiles.`);
+        }
+        throw new Error("No active profile. Create one with:\n\n  casen profile create <name> --base-url <url> --auth-type bearer --token <token>\n");
+    }
+    return profile;
+}
+export function createClientFromProfile(profileName) {
+    return new CamundaClient(requireProfile(profileName).config);
+}
+export function createAdminClientFromProfile(profileName) {
+    return new AdminApiClient(requireProfile(profileName).config);
+}
+//# sourceMappingURL=client.js.map

package/dist/color.js

@@ -0,0 +1,50 @@
+/**
+ * ANSI color helpers. Auto-disabled when:
+ *  - NO_COLOR env var is set
+ *  - stdout is not a TTY (piped output)
+ *  - --no-color flag is passed (checked externally via isEnabled)
+ */
+const ESC = "\x1b[";
+function wrap(code, reset) {
+    return (text, enabled) => enabled ? `${ESC}${code}m${text}${ESC}${reset}m` : text;
+}
+export const bold = wrap("1", "22");
+export const dim = wrap("2", "22");
+export const italic = wrap("3", "23");
+export const red = wrap("31", "39");
+export const green = wrap("32", "39");
+export const yellow = wrap("33", "39");
+export const blue = wrap("34", "39");
+export const magenta = wrap("35", "39");
+export const cyan = wrap("36", "39");
+export const white = wrap("37", "39");
+/** Check if colors should be enabled given env + TTY state. */
+export function shouldUseColor(noColorFlag) {
+    if (noColorFlag)
+        return false;
+    if (process.env.NO_COLOR !== undefined)
+        return false;
+    if (process.env.FORCE_COLOR !== undefined)
+        return true;
+    return process.stdout.isTTY === true;
+}
+/** Produce a state-colored string for Camunda entity states. */
+export function stateColor(state, enabled) {
+    switch (state.toUpperCase()) {
+        case "ACTIVE":
+        case "EVALUATED":
+        case "COMPLETED":
+            return green(state, enabled);
+        case "TERMINATED":
+        case "FAILED":
+        case "CANCELED":
+        case "REJECTED":
+            return red(state, enabled);
+        case "SUSPENDED":
+        case "INCIDENT":
+            return yellow(state, enabled);
+        default:
+            return state;
+    }
+}
+//# sourceMappingURL=color.js.map

package/dist/commands/admin-shared.js

@@ -0,0 +1,180 @@
+// ─── Shared flag specs ────────────────────────────────────────────────────────
+export const FILTER_FLAG = {
+    name: "filter",
+    short: "f",
+    description: "Filter as JSON object",
+    type: "string",
+    placeholder: "JSON",
+};
+export const DATA_FLAG = {
+    name: "data",
+    short: "d",
+    description: "Request body as JSON",
+    type: "string",
+    required: true,
+    placeholder: "JSON",
+};
+export const DATA_OPT_FLAG = {
+    name: "data",
+    short: "d",
+    description: "Request body as JSON",
+    type: "string",
+    placeholder: "JSON",
+};
+export const LIMIT_FLAG = {
+    name: "limit",
+    short: "l",
+    description: "Maximum number of results",
+    type: "number",
+    default: 20,
+};
+export const SORT_FLAG = {
+    name: "sort-by",
+    description: "Sort field",
+    type: "string",
+    placeholder: "FIELD",
+};
+export const SORT_ORDER_FLAG = {
+    name: "sort-order",
+    description: "Sort order: asc|desc",
+    type: "string",
+    default: "asc",
+};
+// ─── JSON helpers ─────────────────────────────────────────────────────────────
+export function parseJson(value, flagName) {
+    if (!value)
+        return undefined;
+    try {
+        return JSON.parse(value);
+    }
+    catch (err) {
+        throw new Error(`Invalid JSON for --${flagName}: ${err instanceof Error ? err.message : String(err)}\n\nGot: ${value}`);
+    }
+}
+function buildSearchBody(ctx) {
+    const filter = parseJson(ctx.flags.filter, "filter");
+    const limit = ctx.flags.limit;
+    const sortBy = ctx.flags["sort-by"];
+    const sortOrder = ctx.flags["sort-order"];
+    const body = {};
+    if (filter)
+        body.filter = filter;
+    if (limit !== undefined)
+        body.page = { limit };
+    if (sortBy)
+        body.sort = [{ field: sortBy, order: sortOrder ?? "asc" }];
+    return Object.keys(body).length > 0 ? body : undefined;
+}
+// ─── Command factories ────────────────────────────────────────────────────────
+export function makeListCmd(opts) {
+    const filterFlag = opts.filterFields
+        ? { ...FILTER_FLAG, fields: opts.filterFields }
+        : FILTER_FLAG;
+    return {
+        name: opts.name ?? "list",
+        aliases: opts.aliases,
+        description: opts.description,
+        flags: [filterFlag, LIMIT_FLAG, SORT_FLAG, SORT_ORDER_FLAG, ...(opts.extraFlags ?? [])],
+        examples: opts.examples,
+        async run(ctx) {
+            const client = await ctx.getAdminClient();
+            const body = buildSearchBody(ctx);
+            const result = await opts.search(client, body);
+            ctx.output.printList(result, opts.columns);
+        },
+    };
+}
+export function makeGetCmd(opts) {
+    return {
+        name: opts.name ?? "get",
+        aliases: opts.aliases,
+        description: opts.description,
+        args: [
+            {
+                name: opts.argName,
+                description: opts.argDesc ?? `${opts.argName} to retrieve`,
+                required: true,
+            },
+        ],
+        examples: opts.examples,
+        async run(ctx) {
+            const key = ctx.positional[0];
+            if (!key)
+                throw new Error(`Missing required argument: <${opts.argName}>`);
+            const client = await ctx.getAdminClient();
+            const result = await opts.get(client, key);
+            ctx.output.printItem(result);
+        },
+    };
+}
+export function makeDeleteCmd(opts) {
+    return {
+        name: opts.name ?? "delete",
+        aliases: opts.aliases,
+        description: opts.description,
+        args: [{ name: opts.argName, description: `${opts.argName} to delete`, required: true }],
+        flags: opts.extraFlags ? [DATA_OPT_FLAG, ...opts.extraFlags] : undefined,
+        examples: opts.examples,
+        async run(ctx) {
+            const key = ctx.positional[0];
+            if (!key)
+                throw new Error(`Missing required argument: <${opts.argName}>`);
+            const body = opts.extraFlags
+                ? parseJson(ctx.flags.data, "data")
+                : undefined;
+            const client = await ctx.getAdminClient();
+            await opts.delete(client, key, body);
+            const msg = opts.successMsg ? opts.successMsg(key) : `Deleted ${key}`;
+            ctx.output.ok(msg);
+        },
+    };
+}
+export function makeCreateCmd(opts) {
+    const dataFlag = opts.bodyFields ? { ...DATA_FLAG, fields: opts.bodyFields } : DATA_FLAG;
+    return {
+        name: opts.name ?? "create",
+        aliases: opts.aliases,
+        description: opts.description,
+        flags: [dataFlag, ...(opts.extraFlags ?? [])],
+        examples: opts.examples,
+        async run(ctx) {
+            const raw = ctx.flags.data;
+            const body = parseJson(raw, "data") ?? {};
+            const client = await ctx.getAdminClient();
+            const result = await opts.create(client, body);
+            if (result !== undefined && result !== null) {
+                ctx.output.printItem(result);
+            }
+            else {
+                ctx.output.ok(opts.successMsg ?? "Created successfully.");
+            }
+        },
+    };
+}
+export function makeUpdateCmd(opts) {
+    const dataFlag = opts.bodyFields ? { ...DATA_FLAG, fields: opts.bodyFields } : DATA_FLAG;
+    return {
+        name: opts.name ?? "update",
+        aliases: opts.aliases,
+        description: opts.description,
+        args: [{ name: opts.argName, description: `${opts.argName} to update`, required: true }],
+        flags: [dataFlag, ...(opts.extraFlags ?? [])],
+        examples: opts.examples,
+        async run(ctx) {
+            const key = ctx.positional[0];
+            if (!key)
+                throw new Error(`Missing required argument: <${opts.argName}>`);
+            const raw = ctx.flags.data;
+            const body = parseJson(raw, "data") ?? {};
+            const client = await ctx.getAdminClient();
+            const result = await opts.update(client, key, body);
+            if (result !== undefined && result !== null) {
+                ctx.output.printItem(result);
+            }
+            else {
+                ctx.output.ok(`Updated ${key}.`);
+            }
+        },
+    };
+}
+//# sourceMappingURL=admin-shared.js.map

package/dist/commands/bpmn.js

@@ -0,0 +1,143 @@
+import { renderBpmnAscii, renderDmnAscii, renderFormAscii } from "@bpmnkit/ascii";
+/**
+ * Replaces the generated `get-x-m-l` command. The endpoint returns text/xml,
+ * so we must set Accept: text/xml and parse the body as text, not JSON.
+ * The XML is then rendered as ASCII art via @bpmnkit/ascii.
+ */
+export const getXmlCmd = {
+    name: "get-xml",
+    description: "Get process definition XML and render as ASCII art",
+    args: [{ name: "processDefinitionKey", description: "Process definition key", required: true }],
+    async run(ctx) {
+        const key = ctx.positional[0];
+        if (!key)
+            throw new Error("Missing required argument: <processDefinitionKey>");
+        const client = await ctx.getClient();
+        const xml = await client.http.request({
+            method: "GET",
+            path: `/process-definitions/${key}/xml`,
+            accept: "text/xml",
+            responseType: "text",
+            cacheable: true,
+        });
+        if (!xml)
+            throw new Error("No XML returned for this process definition");
+        const art = renderBpmnAscii(xml);
+        ctx.output.print(art);
+    },
+};
+/**
+ * Fetches a process definition's BPMN XML and renders it as ASCII art.
+ * Injected into the generated process-definition command group.
+ */
+export const renderBpmnCmd = {
+    name: "render",
+    description: "Render process definition as ASCII art in the terminal",
+    args: [{ name: "processDefinitionKey", description: "Process definition key", required: true }],
+    async run(ctx) {
+        const key = ctx.positional[0];
+        if (!key)
+            throw new Error("Missing required argument: <processDefinitionKey>");
+        // Reuse the XML fetch + render logic
+        await getXmlCmd.run(ctx);
+    },
+};
+// ── DMN ───────────────────────────────────────────────────────────────────────
+/**
+ * Replaces the generated `get-x-m-l` command on decision-definition.
+ * Fetches DMN XML and renders it as ASCII art.
+ */
+export const getDmnXmlCmd = {
+    name: "get-xml",
+    description: "Get decision definition XML and render as ASCII art",
+    args: [{ name: "decisionDefinitionKey", description: "Decision definition key", required: true }],
+    async run(ctx) {
+        const key = ctx.positional[0];
+        if (!key)
+            throw new Error("Missing required argument: <decisionDefinitionKey>");
+        const client = await ctx.getClient();
+        const xml = await client.http.request({
+            method: "GET",
+            path: `/decision-definitions/${key}/xml`,
+            accept: "text/xml",
+            responseType: "text",
+            cacheable: true,
+        });
+        if (!xml)
+            throw new Error("No XML returned for this decision definition");
+        ctx.output.print(renderDmnAscii(xml));
+    },
+};
+/**
+ * Replaces the generated `get-x-m-l` command on decision-requirements.
+ * Fetches DMN requirements XML and renders it as ASCII art.
+ */
+export const getDmnReqsXmlCmd = {
+    name: "get-xml",
+    description: "Get decision requirements XML and render as ASCII art",
+    args: [
+        { name: "decisionRequirementsKey", description: "Decision requirements key", required: true },
+    ],
+    async run(ctx) {
+        const key = ctx.positional[0];
+        if (!key)
+            throw new Error("Missing required argument: <decisionRequirementsKey>");
+        const client = await ctx.getClient();
+        const xml = await client.http.request({
+            method: "GET",
+            path: `/decision-requirements/${key}/xml`,
+            accept: "text/xml",
+            responseType: "text",
+            cacheable: true,
+        });
+        if (!xml)
+            throw new Error("No XML returned for this decision requirements");
+        ctx.output.print(renderDmnAscii(xml));
+    },
+};
+function renderFormResult(result, ctx) {
+    const schema = result.schema;
+    if (!schema) {
+        ctx.output.print("(no form schema)");
+        return;
+    }
+    // The Camunda API returns `schema` as a JSON-encoded string even though the
+    // generated TypeScript type says Record<string, unknown>. Handle both cases.
+    const json = typeof schema === "string" ? schema : JSON.stringify(schema);
+    ctx.output.print(renderFormAscii(json));
+}
+/**
+ * Replaces the generated `getstart-form` command on process-definition.
+ * Fetches the start form schema and renders it as ASCII art.
+ */
+export const getStartFormCmd = {
+    name: "get-start-form",
+    description: "Get process start form and render as ASCII art",
+    args: [{ name: "processDefinitionKey", description: "Process definition key", required: true }],
+    async run(ctx) {
+        const key = ctx.positional[0];
+        if (!key)
+            throw new Error("Missing required argument: <processDefinitionKey>");
+        const client = await ctx.getClient();
+        const result = await client.processDefinition.getStartProcessForm(key);
+        renderFormResult(result, ctx);
+    },
+};
+/**
+ * Replaces the generated `get-form` command on user-task.
+ * Fetches the user task form schema and renders it as ASCII art.
+ */
+export const getUserTaskFormCmd = {
+    name: "get-form",
+    description: "Get user task form and render as ASCII art",
+    args: [{ name: "userTaskKey", description: "User task key", required: true }],
+    async run(ctx) {
+        const key = ctx.positional[0];
+        if (!key)
+            throw new Error("Missing required argument: <userTaskKey>");
+        const client = await ctx.getClient();
+        const result = await client.userTask.getUserTaskForm(key);
+        renderFormResult(result, ctx);
+    },
+};
+//# sourceMappingURL=bpmn.js.map

package/dist/commands/completion.js

@@ -0,0 +1,52 @@
+import { getBashScript, getFishScript, getZshScript } from "../completion.js";
+export const completionGroup = {
+    name: "completion",
+    description: "Generate shell completion scripts",
+    commands: [
+        {
+            name: "bash",
+            description: "Generate bash completion script",
+            examples: [
+                { description: "Install bash completion", command: 'eval "$(casen completion bash)"' },
+                {
+                    description: "Persist bash completion",
+                    command: "casen completion bash >> ~/.bash_completion",
+                },
+            ],
+            async run(ctx) {
+                ctx.output.print(getBashScript());
+            },
+        },
+        {
+            name: "zsh",
+            description: "Generate zsh completion script",
+            examples: [
+                {
+                    description: "Install zsh completion",
+                    command: "mkdir -p ~/.zfunc && casen completion zsh > ~/.zfunc/_casen",
+                },
+                {
+                    description: "Then add to ~/.zshrc",
+                    command: "# fpath=(~/.zfunc $fpath); autoload -Uz compinit && compinit",
+                },
+            ],
+            async run(ctx) {
+                ctx.output.print(getZshScript());
+            },
+        },
+        {
+            name: "fish",
+            description: "Generate fish completion script",
+            examples: [
+                {
+                    description: "Install fish completion",
+                    command: "casen completion fish > ~/.config/fish/completions/casen.fish",
+                },
+            ],
+            async run(ctx) {
+                ctx.output.print(getFishScript());
+            },
+        },
+    ],
+};
+//# sourceMappingURL=completion.js.map