@camunda8/cli 2.6.1 → 2.7.0-alpha.10

package/README.md

@@ -65,6 +65,7 @@ c8ctl help fail       # Shows fail command with all flags
 c8ctl help activate   # Shows activate command with all flags
 c8ctl help publish    # Shows publish command with all flags
 c8ctl help correlate  # Shows correlate command with all flags
+c8ctl help cluster    # Shows local cluster management help
 c8ctl help profiles   # Shows profile management help
 c8ctl help plugin     # Shows plugin management help
 
@@ -165,7 +166,23 @@ For comprehensive examples of all commands and their flags, see [EXAMPLES.md](EX
 
 ### Shell Completion
 
-c8ctl supports shell completion for `bash`, `zsh`, and `fish`. To enable completion:
+c8ctl supports shell completion for `bash`, `zsh`, and `fish`.
+
+#### Quick Install (recommended)
+
+```bash
+# Auto-detect your shell and install completions
+c8ctl completion install
+
+# Or specify a shell explicitly
+c8ctl completion install --shell zsh
+```
+
+This writes a completion script to the c8ctl data directory and wires it into your shell config (RC file for bash/zsh; completions directory for fish). Completions are **automatically refreshed** when c8ctl is upgraded — no manual re-install needed.
+
+#### Manual Setup
+
+If you prefer to manage the completion script yourself:
 
 #### Bash
 
@@ -568,6 +585,67 @@ c8ctl help list     # → JSON for specific command
 
 ---
 
+### Local Cluster
+
+c8ctl includes a built-in `cluster` command for managing a local Camunda 8 instance (powered by a default plugin). No Docker or docker-compose required — it downloads and runs Camunda directly.
+
+```bash
+# Start the latest stable version
+c8ctl cluster start
+
+# Start a specific version
+c8ctl cluster start 8.9
+c8ctl cluster start 8.9.0-alpha5
+
+# Stop the running cluster
+c8ctl cluster stop
+
+# Check cluster status
+c8ctl cluster status
+
+# Stream cluster logs
+c8ctl cluster logs
+
+# List locally cached versions
+c8ctl cluster list
+
+# List available remote versions
+c8ctl cluster list-remote
+
+# Pre-download a version without starting it
+c8ctl cluster install 8.9
+
+# Remove a cached version
+c8ctl cluster delete 8.9
+```
+
+#### Version Aliases
+
+Instead of an exact version number, you can use:
+
+- **`stable`** — the latest GA release (highest minor version that has shipped a `.0` release)
+- **`alpha`** — the latest alpha-train release (highest minor version overall, which may only have alpha builds)
+- **A major.minor pattern** like `8.9` — resolves to the latest patch/alpha within that minor
+
+`c8ctl cluster start` with no version argument defaults to `stable`.
+
+```bash
+c8ctl cluster start stable
+c8ctl cluster start alpha
+c8ctl cluster start 8.9     # latest 8.9.x
+```
+
+#### Online vs Offline Behaviour
+
+- **`cluster start`** prefers locally cached versions. If the requested version is already installed, it starts immediately without going online. A non-blocking background check runs to hint if a newer build is available, but never delays startup.
+- **`cluster install`** always checks the remote download server for the latest build. If a newer ETag is detected for an already-installed version, it re-downloads.
+- **`cluster list-remote`** fetches the full list of available versions from the download server.
+- **Offline fallback**: if the network is unavailable, alias resolution falls back to a locally cached mapping, then to a hardcoded default.
+
+Run `c8ctl help cluster` for full details. See [EXAMPLES.md](EXAMPLES.md#local-cluster) for a complete local development workflow.
+
+---
+
 ### Core Components
 
 - **Logger** (`src/logger.ts`): Handles output in text or JSON mode
@@ -604,6 +682,7 @@ c8ctl <verb> <resource> [arguments] [flags]
 - `sync` - Synchronize plugins
 - `use` - Set active profile or tenant
 - `output` - Show or set output format
+- `cluster` - Manage local Camunda 8 cluster (start, stop, status, logs, install, delete, list, list-remote)
 - `completion` - Generate shell completion script
 - `feedback` - Open the feedback page to report issues or request features
 

package/dist/command-dispatch.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Registry-driven command dispatch map.
+ *
+ * Maps "verb:resource" keys to command handlers. For resourceless verbs
+ * (deploy, run, watch, etc.), the key is "verb:".
+ *
+ * This replaces the ~1800-line if/else dispatch chain that previously
+ * lived in index.ts.
+ */
+import type { AnyCommandHandler } from "./command-framework.ts";
+/**
+ * Dispatch map keyed by "verb:resource".
+ * For resourceless verbs the key is "verb:" (empty resource).
+ */
+export declare const COMMAND_DISPATCH: ReadonlyMap<string, AnyCommandHandler>;
+//# sourceMappingURL=command-dispatch.d.ts.map

package/dist/command-dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-dispatch.d.ts","sourceRoot":"","sources":["../src/command-dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAmGhE;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAiHlE,CAAC"}

package/dist/command-dispatch.js

@@ -0,0 +1,129 @@
+/**
+ * Registry-driven command dispatch map.
+ *
+ * Maps "verb:resource" keys to command handlers. For resourceless verbs
+ * (deploy, run, watch, etc.), the key is "verb:".
+ *
+ * This replaces the ~1800-line if/else dispatch chain that previously
+ * lived in index.ts.
+ */
+import { deployCommand } from "./commands/deployments.js";
+import { getFormCommand } from "./commands/forms.js";
+import { createIdentityAuthorizationCommand, createIdentityGroupCommand, createIdentityMappingRuleCommand, createIdentityRoleCommand, createIdentityTenantCommand, createIdentityUserCommand, deleteIdentityAuthorizationCommand, deleteIdentityGroupCommand, deleteIdentityMappingRuleCommand, deleteIdentityRoleCommand, deleteIdentityTenantCommand, deleteIdentityUserCommand, getIdentityAuthorizationCommand, getIdentityGroupCommand, getIdentityMappingRuleCommand, getIdentityRoleCommand, getIdentityTenantCommand, getIdentityUserCommand, listAuthorizationsCommand, listGroupsCommand, listMappingRulesCommand, listRolesCommand, listTenantsCommand, listUsersCommand, searchIdentityAuthorizationsCommand, searchIdentityGroupsCommand, searchIdentityMappingRulesCommand, searchIdentityRolesCommand, searchIdentityTenantsCommand, searchIdentityUsersCommand, } from "./commands/identity.js";
+import { getIncidentCommand, listIncidentsCommand, resolveIncidentCommand, } from "./commands/incidents.js";
+import { activateJobsCommand, completeJobCommand, failJobCommand, listJobsCommand, } from "./commands/jobs.js";
+import { mcpProxyCommand } from "./commands/mcp-proxy.js";
+import { correlateMessageCommand, publishMessageCommand, } from "./commands/messages.js";
+import { feedbackCommand, openAppCommand } from "./commands/open.js";
+import { downgradePluginCommand, initPluginCommand, listPluginsCommand, loadPluginCommand, syncPluginsCommand, unloadPluginCommand, upgradePluginCommand, } from "./commands/plugins.js";
+import { getProcessDefinitionCommand, listProcessDefinitionsCommand, } from "./commands/process-definitions.js";
+import { awaitProcessInstanceCommand, cancelProcessInstanceCommand, createProcessInstanceCommand, getProcessInstanceCommand, listProcessInstancesCommand, } from "./commands/process-instances.js";
+import { addProfileCommand, listProfileCommand, removeProfileCommand, whichProfileCommand, } from "./commands/profiles.js";
+import { runCommand } from "./commands/run.js";
+import { searchIncidentsCommand, searchJobsCommand, searchProcessDefinitionsCommand, searchProcessInstancesCommand, searchUserTasksCommand, searchVariablesCommand, } from "./commands/search.js";
+import { outputCommand, useProfileCommand, useTenantCommand, } from "./commands/session.js";
+import { getTopologyCommand } from "./commands/topology.js";
+import { completeUserTaskCommand, listUserTasksCommand, } from "./commands/user-tasks.js";
+import { watchCommand } from "./commands/watch.js";
+/**
+ * Dispatch map keyed by "verb:resource".
+ * For resourceless verbs the key is "verb:" (empty resource).
+ */
+export const COMMAND_DISPATCH = new Map([
+    // ── Session / profile ──────────────────────────────────────────────
+    ["use:profile", useProfileCommand],
+    ["use:tenant", useTenantCommand],
+    ["output:", outputCommand],
+    ["list:profile", listProfileCommand],
+    ["add:profile", addProfileCommand],
+    ["remove:profile", removeProfileCommand],
+    ["which:profile", whichProfileCommand],
+    // ── Plugins ────────────────────────────────────────────────────────
+    ["list:plugin", listPluginsCommand],
+    ["load:plugin", loadPluginCommand],
+    ["unload:plugin", unloadPluginCommand],
+    ["sync:plugin", syncPluginsCommand],
+    ["upgrade:plugin", upgradePluginCommand],
+    ["downgrade:plugin", downgradePluginCommand],
+    ["init:plugin", initPluginCommand],
+    // ── Process instances ──────────────────────────────────────────────
+    ["list:process-instance", listProcessInstancesCommand],
+    ["get:process-instance", getProcessInstanceCommand],
+    ["create:process-instance", createProcessInstanceCommand],
+    ["cancel:process-instance", cancelProcessInstanceCommand],
+    ["await:process-instance", awaitProcessInstanceCommand],
+    // ── Process definitions ────────────────────────────────────────────
+    ["list:process-definition", listProcessDefinitionsCommand],
+    ["get:process-definition", getProcessDefinitionCommand],
+    // ── User tasks ─────────────────────────────────────────────────────
+    ["list:user-task", listUserTasksCommand],
+    ["complete:user-task", completeUserTaskCommand],
+    // ── Incidents ──────────────────────────────────────────────────────
+    ["list:incident", listIncidentsCommand],
+    ["get:incident", getIncidentCommand],
+    ["resolve:incident", resolveIncidentCommand],
+    // ── Jobs ────────────────────────────────────────────────────────────
+    ["list:jobs", listJobsCommand],
+    ["activate:jobs", activateJobsCommand],
+    ["complete:job", completeJobCommand],
+    ["fail:job", failJobCommand],
+    // ── Messages ───────────────────────────────────────────────────────
+    ["publish:message", publishMessageCommand],
+    ["correlate:message", correlateMessageCommand],
+    // ── Topology / forms ───────────────────────────────────────────────
+    ["get:topology", getTopologyCommand],
+    ["get:form", getFormCommand],
+    // ── Search ─────────────────────────────────────────────────────────
+    ["search:process-definition", searchProcessDefinitionsCommand],
+    ["search:process-instance", searchProcessInstancesCommand],
+    ["search:user-task", searchUserTasksCommand],
+    ["search:incident", searchIncidentsCommand],
+    ["search:jobs", searchJobsCommand],
+    ["search:variable", searchVariablesCommand],
+    ["search:user", searchIdentityUsersCommand],
+    ["search:role", searchIdentityRolesCommand],
+    ["search:group", searchIdentityGroupsCommand],
+    ["search:tenant", searchIdentityTenantsCommand],
+    ["search:authorization", searchIdentityAuthorizationsCommand],
+    ["search:mapping-rule", searchIdentityMappingRulesCommand],
+    // ── Identity: list ─────────────────────────────────────────────────
+    ["list:user", listUsersCommand],
+    ["list:role", listRolesCommand],
+    ["list:group", listGroupsCommand],
+    ["list:tenant", listTenantsCommand],
+    ["list:authorization", listAuthorizationsCommand],
+    ["list:mapping-rule", listMappingRulesCommand],
+    // ── Identity: get ──────────────────────────────────────────────────
+    ["get:user", getIdentityUserCommand],
+    ["get:role", getIdentityRoleCommand],
+    ["get:group", getIdentityGroupCommand],
+    ["get:tenant", getIdentityTenantCommand],
+    ["get:authorization", getIdentityAuthorizationCommand],
+    ["get:mapping-rule", getIdentityMappingRuleCommand],
+    // ── Identity: create ───────────────────────────────────────────────
+    ["create:user", createIdentityUserCommand],
+    ["create:role", createIdentityRoleCommand],
+    ["create:group", createIdentityGroupCommand],
+    ["create:tenant", createIdentityTenantCommand],
+    ["create:authorization", createIdentityAuthorizationCommand],
+    ["create:mapping-rule", createIdentityMappingRuleCommand],
+    // ── Identity: delete ───────────────────────────────────────────────
+    ["delete:user", deleteIdentityUserCommand],
+    ["delete:role", deleteIdentityRoleCommand],
+    ["delete:group", deleteIdentityGroupCommand],
+    ["delete:tenant", deleteIdentityTenantCommand],
+    ["delete:authorization", deleteIdentityAuthorizationCommand],
+    ["delete:mapping-rule", deleteIdentityMappingRuleCommand],
+    // ── Resourceless verbs ─────────────────────────────────────────────
+    ["deploy:", deployCommand],
+    ["run:", runCommand],
+    ["watch:", watchCommand],
+    ["open:", openAppCommand],
+    ["open:operate", openAppCommand],
+    ["open:tasklist", openAppCommand],
+    ["open:modeler", openAppCommand],
+    ["open:optimize", openAppCommand],
+    ["feedback:", feedbackCommand],
+    ["mcp-proxy:", mcpProxyCommand],
+]);
+//# sourceMappingURL=command-dispatch.js.map

package/dist/command-dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-dispatch.js","sourceRoot":"","sources":["../src/command-dispatch.ts"],"names":[],"mappings":"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"}

package/dist/command-framework.d.ts

@@ -0,0 +1,248 @@
+/**
+ * Type-safe command definition framework.
+ *
+ * Provides `defineCommand(verb, resource, handler)` — flags and positionals
+ * are derived from the command registry, so handlers receive branded SDK types
+ * without any ceremony or `as` casts.
+ *
+ * Handlers return a `CommandResult` discriminated union. The framework renders
+ * results and catches errors in a single place, eliminating per-handler
+ * boilerplate for table/json output, empty-list messages, dry-run emission,
+ * sorting, and error handling.
+ *
+ * Phase 2 of #230.
+ */
+import type { CamundaClient } from "@camunda8/orchestration-cluster-api";
+import { COMMAND_REGISTRY, type FlagDef, type PositionalDef } from "./command-registry.ts";
+import { type Logger, type SortOrder } from "./logger.ts";
+export type { PositionalDef };
+/** Narrow type of the registry — preserves literal keys and `as const` values. */
+type Registry = typeof COMMAND_REGISTRY;
+/**
+ * Resolve the flag schema for a verb×resource pair.
+ *
+ * If the verb has `resourceFlags[R]`, use it. Otherwise fall back to
+ * the verb-level `flags` superset.
+ */
+export type ResolvedFlags<V extends keyof Registry, R extends string> = Registry[V] extends {
+    resourceFlags: Record<string, Record<string, FlagDef>>;
+} ? R extends keyof Registry[V]["resourceFlags"] ? Registry[V]["resourceFlags"][R] : Registry[V]["flags"] : Registry[V]["flags"];
+/**
+ * Resolve the positional schema for a verb×resource pair.
+ *
+ * If the verb has `resourcePositionals[R]`, use it. Otherwise the
+ * command has no positional arguments.
+ */
+export type ResolvedPositionals<V extends keyof Registry, R extends string> = Registry[V] extends {
+    resourcePositionals: Record<string, readonly PositionalDef[]>;
+} ? R extends keyof Registry[V]["resourcePositionals"] ? Registry[V]["resourcePositionals"][R] : readonly [] : readonly [];
+/**
+ * Map a flag schema to typed handler parameters.
+ *
+ * - Flags with `validate` → the validator's return type (branded) | undefined
+ * - Boolean flags → boolean | undefined
+ * - Everything else → string | undefined
+ *
+ * All flags are optional because CLI users may omit any flag.
+ *
+ * The type parameter is unconstrained so conditional types like
+ * `ResolvedFlags<V, R>` can be passed through without constraint errors.
+ */
+export type InferFlags<F extends Record<string, any>> = {
+    [K in keyof F]: F[K] extends {
+        validate: (v: string) => infer R;
+    } ? R | undefined : F[K] extends {
+        type: "boolean";
+    } ? boolean | undefined : string | undefined;
+};
+/**
+ * Map a readonly positional schema tuple to a named record of typed values.
+ *
+ * - Positionals with `validate` → the validator's return type
+ * - Positionals without `validate` → string
+ * - Required positionals → non-optional
+ * - Optional positionals → `| undefined`
+ *
+ * Accepts any type and uses a conditional guard so deferred types
+ * like `ResolvedPositionals<V, R>` pass through cleanly.
+ */
+export type InferPositionals<P> = P extends readonly PositionalDef[] ? {
+    [K in P[number] as K["name"]]: K extends {
+        validate: (v: string) => infer R;
+    } ? K extends {
+        required: true;
+    } ? R : R | undefined : K extends {
+        required: true;
+    } ? string : string | undefined;
+} : Record<string, never>;
+/**
+ * Discriminated union returned by command handlers.
+ *
+ * The framework's `execute` method renders these centrally — handlers
+ * never call `logger.table()` or `logger.json()` directly.
+ */
+/** List/search command: render as table or JSON array. */
+export interface ListResult {
+    readonly kind: "list";
+    /** Already-mapped display rows (e.g. { Key, "Process ID", State }). */
+    readonly items: Record<string, unknown>[];
+    /** Message when items is empty (e.g. "No process instances found"). */
+    readonly emptyMessage: string;
+}
+/** Get command: render a single object as JSON. */
+export interface GetResult {
+    readonly kind: "get";
+    /** The raw API response object. */
+    readonly data: unknown;
+    /** Optional info message logged before the JSON data (e.g. source hint). */
+    readonly message?: string;
+}
+/** Raw output: emit a string verbatim (e.g. BPMN XML). */
+export interface RawResult {
+    readonly kind: "raw";
+    /** String content to output verbatim. */
+    readonly content: string;
+}
+/** Dry-run: handler determined a dry-run was emitted and wants to stop. */
+export interface DryRunResult {
+    readonly kind: "dryRun";
+    /** Dry-run info object (passed to logger.json). */
+    readonly info: Record<string, unknown>;
+}
+/** Info message: no data to display, just a message (e.g. "User task has no form"). */
+export interface InfoResult {
+    readonly kind: "info";
+    /** Message to display. */
+    readonly message: string;
+}
+/** Success message: a mutating operation succeeded (e.g. "Incident 77777 resolved"). */
+export interface SuccessResult {
+    readonly kind: "success";
+    /** Human-readable success message. */
+    readonly message: string;
+    /** Optional resource key to display alongside the message. */
+    readonly key?: string | number;
+}
+/** No result: side-effectful command that handles its own output (e.g. deploy, run, open). */
+export interface NoResult {
+    readonly kind: "none";
+}
+/** Never-returning command: runs indefinitely or takes over the process (e.g. watch, mcp-proxy). */
+export interface NeverResult {
+    readonly kind: "never";
+}
+export type CommandResult = ListResult | GetResult | RawResult | DryRunResult | InfoResult | SuccessResult | NoResult | NeverResult;
+/**
+ * Shared dependencies injected into every command handler.
+ *
+ * Replaces the current pattern where each handler independently calls
+ * createClient(), resolveTenantId(), getLogger().
+ */
+export interface CommandContext {
+    /** Authenticated SDK client for the active profile. */
+    client: CamundaClient;
+    /** Logger configured for the current output mode. */
+    logger: Logger;
+    /** Tenant ID from the active profile (undefined if not multi-tenant). */
+    tenantId: string | undefined;
+    /** Normalised resource name (e.g. "process-instance"). */
+    resource: string;
+    /** Positional arguments after verb and resource (e.g. the key in `get pi <key>`). */
+    positionals: string[];
+    /** Sort direction from --asc / --desc flags. */
+    sortOrder: SortOrder;
+    /** Sort field from --sortBy flag. */
+    sortBy: string | undefined;
+    /** Pagination limit from --limit flag (parsed to number). */
+    limit: number | undefined;
+    /** Whether --all was set (e.g. list all, disable default state filter). */
+    all: boolean | undefined;
+    /** Date range from --between flag (e.g. "7d", "2024-01-01..2024-12-31"). */
+    between: string | undefined;
+    /** Date field for --between filter. */
+    dateField: string | undefined;
+    /** Version filter (parsed from --version flag). */
+    version?: number | undefined;
+    /** Whether --dry-run was set. */
+    dryRun: boolean | undefined;
+    /** Active profile name (for client/tenant resolution). */
+    profile: string | undefined;
+}
+/**
+ * Return type of `defineCommand`. Stores the verb, resource, and an
+ * `execute` method that deserializes raw CLI input and calls the handler
+ * with fully typed flags and positionals.
+ */
+export interface CommandHandler<V extends keyof Registry, R extends string> {
+    verb: V;
+    resource: R;
+    execute: (ctx: CommandContext, rawValues: Record<string, unknown>, rawArgs: string[]) => Promise<void>;
+}
+/**
+ * Type-erased command handler for use in dispatch maps.
+ * Preserves the `execute` signature without carrying generic type params.
+ */
+export type AnyCommandHandler = CommandHandler<keyof Registry, string>;
+/**
+ * Define a command handler for a verb×resource pair.
+ *
+ * Flags and positionals are derived from the command registry —
+ * no ceremony, no duplication. The handler receives fully typed
+ * parameters.
+ *
+ * ```ts
+ * export const getProcessDefinition = defineCommand(
+ *   "get",
+ *   "process-definition",
+ *   async (ctx, flags, args) => {
+ *     // ctx.client is CamundaClient
+ *     // flags.xml is boolean | undefined
+ *     // args.key is ProcessDefinitionKey
+ *   },
+ * );
+ * ```
+ */
+export declare function defineCommand<V extends keyof Registry, R extends string>(verb: V, resource: R, handler: (ctx: CommandContext, flags: InferFlags<ResolvedFlags<V, R>>, args: InferPositionals<ResolvedPositionals<V, R>>) => Promise<CommandResult | undefined>): CommandHandler<V, R>;
+/**
+ * Deserialize raw parseArgs values into typed flags.
+ *
+ * For each flag in the schema:
+ * - If the flag has a `validate` function and the raw value is a non-empty
+ *   string, call the validator (which returns a branded type).
+ * - If the flag is boolean, extract the boolean value.
+ * - Otherwise, extract the string value.
+ *
+ * Validators that throw are intentionally NOT caught here — validation
+ * errors should propagate to the top-level error handler.
+ */
+export declare function deserializeFlags<F extends Record<string, FlagDef>>(values: Record<string, unknown>, flagDefs: F): InferFlags<F>;
+/**
+ * Deserialize raw positional strings into a typed named record.
+ *
+ * For each positional in the schema (in order):
+ * - If required and missing, exits with an error message.
+ * - If a `validate` function is present, calls it to produce a branded type.
+ * - Otherwise, passes the raw string through.
+ *
+ * Returns a named record keyed by each positional's `name`.
+ */
+export declare function deserializePositionals<P extends readonly PositionalDef[]>(raw: string[], positionalDefs: P, verb: string, resource: string): InferPositionals<P>;
+/**
+ * Check if dry-run mode is active and return a `DryRunResult` if so.
+ *
+ * Usage in handlers:
+ * ```ts
+ * const dr = dryRun({ command: "list pi", method: "POST", endpoint: "/process-instances/search", profile, body: filter });
+ * if (dr) return dr;
+ * ```
+ *
+ * Replaces the old `emitDryRun()` side-effecting pattern.
+ */
+export declare function dryRun(opts: {
+    command: string;
+    method: string;
+    endpoint: string;
+    profile?: string;
+    body?: unknown;
+}): DryRunResult | null;
+//# sourceMappingURL=command-framework.d.ts.map

package/dist/command-framework.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-framework.d.ts","sourceRoot":"","sources":["../src/command-framework.ts"],"names":[],"mappings":"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"}