@camunda8/cli 2.6.1 → 2.7.0-alpha.10

package/dist/command-framework.js

@@ -0,0 +1,229 @@
+/**
+ * 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 { COMMAND_REGISTRY, } from "./command-registry.js";
+import { resolveClusterConfig } from "./config.js";
+import { handleCommandError } from "./errors.js";
+import { getLogger, sortTableData, } from "./logger.js";
+import { c8ctl } from "./runtime.js";
+// ─── defineCommand ───────────────────────────────────────────────────────────
+/**
+ * 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 function defineCommand(verb, resource, handler) {
+    // Widen to CommandDef so optional properties are accessible regardless of which verb V is
+    const entry = COMMAND_REGISTRY[verb];
+    const flagDefs = entry.resourceFlags?.[resource] ?? entry.flags;
+    const positionalDefs = entry.resourcePositionals?.[resource] ?? [];
+    return {
+        verb,
+        resource,
+        execute: async (ctx, rawValues, rawArgs) => {
+            const flags = deserializeFlags(rawValues, flagDefs);
+            const args = deserializePositionals(rawArgs, positionalDefs, verb, resource);
+            try {
+                const result = await handler(ctx, 
+                // biome-ignore lint/plugin: framework-internal assertion — flagDefs resolved from COMMAND_REGISTRY[V][R]
+                flags, 
+                // biome-ignore lint/plugin: framework-internal assertion — positionalDefs resolved from COMMAND_REGISTRY[V][R]
+                args);
+                if (result)
+                    renderResult(result, ctx);
+            }
+            catch (error) {
+                handleCommandError(ctx.logger, `Failed to ${verb} ${resource.replace(/-/g, " ")}`, error);
+            }
+        },
+    };
+}
+// ─── deserializeFlags ────────────────────────────────────────────────────────
+/**
+ * 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 function deserializeFlags(values, flagDefs) {
+    const result = {};
+    for (const [key, def] of Object.entries(flagDefs)) {
+        const raw = values[key];
+        if (raw === undefined || raw === false) {
+            result[key] = undefined;
+            continue;
+        }
+        if (def.type === "boolean") {
+            result[key] = typeof raw === "boolean" ? raw : undefined;
+        }
+        else if (typeof raw === "string" && raw !== "") {
+            result[key] = def.validate ? def.validate(raw) : raw;
+        }
+        else {
+            result[key] = undefined;
+        }
+    }
+    // biome-ignore lint/plugin: internal assertion — result is built key-by-key from flagDefs, matching InferFlags<F> structurally
+    return result;
+}
+// ─── deserializePositionals ──────────────────────────────────────────────────
+/**
+ * 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 function deserializePositionals(raw, positionalDefs, verb, resource) {
+    const result = {};
+    for (let i = 0; i < positionalDefs.length; i++) {
+        const def = positionalDefs[i];
+        const value = raw[i];
+        if (!value) {
+            if (def.required) {
+                // Build a human-readable label from the positional name:
+                // "roleId" → "role ID", "mappingRuleId" → "mapping rule ID", "key" → "key"
+                const expandedName = def.name
+                    .replace(/([a-z])([A-Z])/g, "$1 $2")
+                    .toLowerCase()
+                    .replace(/\bid\b/gi, "ID");
+                // If the expanded name already starts with the resource name,
+                // use it directly (e.g. "username" for resource "user" → "Username required").
+                // Otherwise, prepend the resource as context (e.g. "key" for "user-task" → "User task key required").
+                const resourceNorm = resource.replace(/-/g, " ");
+                const alreadyDescriptive = expandedName
+                    .toLowerCase()
+                    .startsWith(resourceNorm.toLowerCase());
+                let displayLabel;
+                if (alreadyDescriptive) {
+                    displayLabel =
+                        expandedName.charAt(0).toUpperCase() + expandedName.slice(1);
+                }
+                else {
+                    // Singularize trailing "s" for the prefix (e.g. "jobs" → "Job")
+                    const prefix = resourceNorm.replace(/s$/, "");
+                    displayLabel =
+                        prefix.charAt(0).toUpperCase() +
+                            prefix.slice(1) +
+                            " " +
+                            expandedName;
+                }
+                getLogger().error(`${displayLabel} required. Usage: c8 ${verb} ${resource} <${def.name}>`);
+                process.exit(1);
+            }
+            result[def.name] = undefined;
+            continue;
+        }
+        result[def.name] = def.validate ? def.validate(value) : value;
+    }
+    // biome-ignore lint/plugin: internal assertion — result is built key-by-key from positionalDefs, matching InferPositionals<P> structurally
+    return result;
+}
+// ─── renderResult ────────────────────────────────────────────────────────────
+/**
+ * Render a `CommandResult` to the user via the logger.
+ *
+ * This is the single rendering point for all command output —
+ * handlers never call logger.table/json/output/info directly.
+ *
+ * During migration, handlers that still do their own I/O return
+ * `undefined` (implicit void) — renderResult is a no-op in that case.
+ */
+function renderResult(result, ctx) {
+    if (!result)
+        return;
+    const { logger, sortBy, sortOrder } = ctx;
+    switch (result.kind) {
+        case "list":
+            if (result.items.length > 0) {
+                const sorted = sortTableData(result.items, sortBy, logger, sortOrder);
+                logger.table(sorted);
+            }
+            else {
+                logger.info(result.emptyMessage);
+            }
+            break;
+        case "get":
+            if (result.message)
+                logger.info(result.message);
+            logger.json(result.data);
+            break;
+        case "raw":
+            logger.output(result.content);
+            break;
+        case "dryRun":
+            logger.json(result.info);
+            break;
+        case "info":
+            logger.info(result.message);
+            break;
+        case "success":
+            logger.success(result.message, result.key);
+            break;
+        case "none":
+        case "never":
+            break;
+    }
+}
+// ─── dryRun ──────────────────────────────────────────────────────────────────
+/**
+ * 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 function dryRun(opts) {
+    if (!c8ctl.dryRun)
+        return null;
+    const config = resolveClusterConfig(opts.profile);
+    return {
+        kind: "dryRun",
+        info: {
+            dryRun: true,
+            command: opts.command,
+            method: opts.method,
+            url: `${config.baseUrl}${opts.endpoint}`,
+            ...(opts.body !== undefined && { body: opts.body }),
+        },
+    };
+}
+//# sourceMappingURL=command-framework.js.map

package/dist/command-framework.js.map

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