@camunda8/cli 2.8.0-alpha.7 → 2.8.0-alpha.9

package/dist/command-registry.d.ts

@@ -51,9 +51,47 @@ export interface CommandDef {
     requiresResource: boolean;
     /** Valid resource names (canonical short forms used in help). */
     resources: string[];
-    /** Flags specific to this verb (beyond global flags). Superset of all resource-specific flags. */
+    /**
+     * Verb-level flag schema. Per-resource flags must live exclusively in
+     * `resourceFlags` — they are *not* duplicated here. Mixing a flag into
+     * both buckets defeats unknown-flag detection (#256), and the
+     * structural disjointness invariant in
+     * `tests/unit/command-registry.test.ts` will fail.
+     *
+     * **Effective-resolution semantics** (see `ResolvedFlags` in
+     * `src/command-framework.ts` and `validateFlags` in `src/index.ts`):
+     * the handler's typed `flags` parameter and `validateFlags`'s
+     * required-field/validator checks resolve to
+     * `resourceFlags[resource] ?? flags`. So for a verb that declares
+     * **both** `flags` and `resourceFlags[r]`, the verb-level `flags` are
+     * **not** seen by the handler or by `validateFlags` when dispatching to
+     * resource `r` — only `resourceFlags[r]` is. Verb-level `flags` are
+     * still treated as valid by `detectUnknownFlags`, so
+     * `detectUnknownFlags`/`warnUnknownFlags` will not emit an
+     * unknown-flag warning for them, and `deriveParseArgsOptions` still
+     * includes them so they parse, but they will not flow into the
+     * handler's typed parameter for any resource that has its own bucket.
+     *
+     * Practical guidance: if a flag must be visible to the handler for a
+     * given resource, declare it in that resource's `resourceFlags` bucket
+     * (typically by spreading a shared constant such as `SEARCH_FLAGS`
+     * into each per-resource bucket). Reserve verb-level `flags` for verbs
+     * with no `resourceFlags` at all, or for flags that are deliberately
+     * parse-only on resources with their own bucket.
+     */
     flags: Record<string, FlagDef>;
-    /** Per-resource flag scoping. Keys are canonical resource names. */
+    /**
+     * Per-resource flag scoping. Keys are canonical resource names.
+     * Flags declared here must not also appear in `flags` (see above).
+     *
+     * When a resource has an entry here, the framework resolves the
+     * effective flag schema as `resourceFlags[resource]` and **ignores**
+     * the verb-level `flags` for handler typing and `validateFlags`.
+     * `deriveParseArgsOptions` still includes both buckets so they parse,
+     * and the scoping lets `warnUnknownFlags` warn when a flag is passed
+     * against a resource that does not declare it. See the doc on `flags`
+     * above for the full effective-resolution semantics.
+     */
     resourceFlags?: Record<string, Record<string, FlagDef>>;
     /** Per-resource positional argument schemas. Keys are canonical resource names. */
     resourcePositionals?: Record<string, readonly PositionalDef[]>;
@@ -127,6 +165,12 @@ export declare const GLOBAL_FLAGS: {
         readonly agentDescription: "Comma-separated list of output fields to include.\nReduces context window size when parsing output.\nExample: c8ctl list pi --fields Key,State,processDefinitionId\nCase-insensitive.";
         readonly agentAppliesTo: "all list/search/get commands";
     };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Force JSON output for this invocation (does not persist; overrides session state and C8CTL_OUTPUT_MODE)";
+        readonly agentDescription: "Per-invocation JSON output. Equivalent to setting outputMode=json for one command without mutating session.json.\nPrecedence: --json > C8CTL_OUTPUT_MODE > persisted session state.";
+        readonly agentAppliesTo: "all commands";
+    };
 };
 /**
  * Flags shared across all search/list commands.
@@ -182,136 +226,6 @@ export declare const COMMAND_REGISTRY: {
         }[];
         resources: string[];
         flags: {
-            mappingRuleId: {
-                readonly type: "string";
-                readonly description: "Filter by mapping rule ID";
-            };
-            name: {
-                readonly type: "string";
-                readonly description: "Filter by name";
-            };
-            claimName: {
-                readonly type: "string";
-                readonly description: "Filter by claim name";
-            };
-            claimValue: {
-                readonly type: "string";
-                readonly description: "Filter by claim value";
-            };
-            ownerId: {
-                readonly type: "string";
-                readonly description: "Filter by owner ID";
-            };
-            ownerType: {
-                readonly type: "string";
-                readonly description: "Filter by owner type";
-            };
-            resourceType: {
-                readonly type: "string";
-                readonly description: "Filter by resource type";
-            };
-            resourceId: {
-                readonly type: "string";
-                readonly description: "Filter by resource ID";
-            };
-            tenantId: {
-                readonly type: "string";
-                readonly description: "Filter by tenant ID";
-                readonly validate: typeof TenantId.assumeExists;
-            };
-            groupId: {
-                readonly type: "string";
-                readonly description: "Filter by group ID";
-            };
-            roleId: {
-                readonly type: "string";
-                readonly description: "Filter by role ID";
-            };
-            username: {
-                readonly type: "string";
-                readonly description: "Filter by username";
-                readonly validate: typeof Username.assumeExists;
-            };
-            email: {
-                readonly type: "string";
-                readonly description: "Filter by email";
-            };
-            state: {
-                readonly type: "string";
-                readonly description: "Filter by state";
-            };
-            type: {
-                readonly type: "string";
-                readonly description: "Filter by job type";
-            };
-            processInstanceKey: {
-                readonly type: "string";
-                readonly description: "Filter by process instance key";
-                readonly validate: typeof ProcessInstanceKey.assumeExists;
-            };
-            processDefinitionKey: {
-                readonly type: "string";
-                readonly description: "Filter by process definition key";
-                readonly validate: typeof ProcessDefinitionKey.assumeExists;
-            };
-            itype: {
-                readonly type: "string";
-                readonly description: "Case-insensitive filter by job type";
-            };
-            bpmnProcessId: {
-                readonly type: "string";
-                readonly description: "Filter by BPMN process ID";
-            };
-            id: {
-                readonly type: "string";
-                readonly description: "Filter by BPMN process ID (alias)";
-            };
-            processDefinitionId: {
-                readonly type: "string";
-                readonly description: "Filter by process definition ID";
-                readonly validate: typeof ProcessDefinitionId.assumeExists;
-            };
-            errorType: {
-                readonly type: "string";
-                readonly description: "Filter by error type";
-            };
-            errorMessage: {
-                readonly type: "string";
-                readonly description: "Filter by error message";
-            };
-            ierrorMessage: {
-                readonly type: "string";
-                readonly description: "Case-insensitive filter by error message";
-            };
-            iid: {
-                readonly type: "string";
-                readonly description: "Case-insensitive filter by BPMN process ID";
-            };
-            assignee: {
-                readonly type: "string";
-                readonly description: "Filter by assignee";
-            };
-            elementId: {
-                readonly type: "string";
-                readonly description: "Filter by element ID";
-            };
-            iassignee: {
-                readonly type: "string";
-                readonly description: "Case-insensitive filter by assignee";
-            };
-            key: {
-                readonly type: "string";
-                readonly description: "Filter by key";
-            };
-            iname: {
-                readonly type: "string";
-                readonly description: "Case-insensitive filter by name";
-            };
-            parentProcessInstanceKey: {
-                readonly type: "string";
-                readonly description: "Filter by parent process instance key";
-                readonly validate: typeof ProcessInstanceKey.assumeExists;
-            };
             sortBy: {
                 readonly type: "string";
                 readonly description: "Sort results by field";
@@ -604,152 +518,6 @@ export declare const COMMAND_REGISTRY: {
         }[];
         resources: string[];
         flags: {
-            mappingRuleId: {
-                readonly type: "string";
-                readonly description: "Filter by mapping rule ID";
-            };
-            name: {
-                readonly type: "string";
-                readonly description: "Filter by name";
-            };
-            claimName: {
-                readonly type: "string";
-                readonly description: "Filter by claim name";
-            };
-            claimValue: {
-                readonly type: "string";
-                readonly description: "Filter by claim value";
-            };
-            ownerId: {
-                readonly type: "string";
-                readonly description: "Filter by owner ID";
-            };
-            ownerType: {
-                readonly type: "string";
-                readonly description: "Filter by owner type";
-            };
-            resourceType: {
-                readonly type: "string";
-                readonly description: "Filter by resource type";
-            };
-            resourceId: {
-                readonly type: "string";
-                readonly description: "Filter by resource ID";
-            };
-            tenantId: {
-                readonly type: "string";
-                readonly description: "Filter by tenant ID";
-                readonly validate: typeof TenantId.assumeExists;
-            };
-            groupId: {
-                readonly type: "string";
-                readonly description: "Filter by group ID";
-            };
-            roleId: {
-                readonly type: "string";
-                readonly description: "Filter by role ID";
-            };
-            username: {
-                readonly type: "string";
-                readonly description: "Filter by username";
-                readonly validate: typeof Username.assumeExists;
-            };
-            email: {
-                readonly type: "string";
-                readonly description: "Filter by email";
-            };
-            value: {
-                readonly type: "string";
-                readonly description: "Filter by value";
-            };
-            processInstanceKey: {
-                readonly type: "string";
-                readonly description: "Filter by process instance key";
-                readonly validate: typeof ProcessInstanceKey.assumeExists;
-            };
-            scopeKey: {
-                readonly type: "string";
-                readonly description: "Filter by scope key";
-            };
-            fullValue: {
-                readonly type: "boolean";
-                readonly description: "Return full variable values (not truncated)";
-            };
-            iname: {
-                readonly type: "string";
-                readonly description: "Case-insensitive filter by name";
-            };
-            ivalue: {
-                readonly type: "string";
-                readonly description: "Case-insensitive filter by value";
-            };
-            state: {
-                readonly type: "string";
-                readonly description: "Filter by state";
-            };
-            type: {
-                readonly type: "string";
-                readonly description: "Filter by job type";
-            };
-            processDefinitionKey: {
-                readonly type: "string";
-                readonly description: "Filter by process definition key";
-                readonly validate: typeof ProcessDefinitionKey.assumeExists;
-            };
-            itype: {
-                readonly type: "string";
-                readonly description: "Case-insensitive filter by job type";
-            };
-            bpmnProcessId: {
-                readonly type: "string";
-                readonly description: "Filter by BPMN process ID";
-            };
-            id: {
-                readonly type: "string";
-                readonly description: "Filter by BPMN process ID (alias)";
-            };
-            processDefinitionId: {
-                readonly type: "string";
-                readonly description: "Filter by process definition ID";
-                readonly validate: typeof ProcessDefinitionId.assumeExists;
-            };
-            errorType: {
-                readonly type: "string";
-                readonly description: "Filter by error type";
-            };
-            errorMessage: {
-                readonly type: "string";
-                readonly description: "Filter by error message";
-            };
-            ierrorMessage: {
-                readonly type: "string";
-                readonly description: "Case-insensitive filter by error message";
-            };
-            iid: {
-                readonly type: "string";
-                readonly description: "Case-insensitive filter by BPMN process ID";
-            };
-            assignee: {
-                readonly type: "string";
-                readonly description: "Filter by assignee";
-            };
-            elementId: {
-                readonly type: "string";
-                readonly description: "Filter by element ID";
-            };
-            iassignee: {
-                readonly type: "string";
-                readonly description: "Case-insensitive filter by assignee";
-            };
-            key: {
-                readonly type: "string";
-                readonly description: "Filter by key";
-            };
-            parentProcessInstanceKey: {
-                readonly type: "string";
-                readonly description: "Filter by parent process instance key";
-                readonly validate: typeof ProcessInstanceKey.assumeExists;
-            };
             sortBy: {
                 readonly type: "string";
                 readonly description: "Sort results by field";
@@ -1068,32 +836,7 @@ export declare const COMMAND_REGISTRY: {
             description: string;
         }[];
         resources: string[];
-        flags: {
-            variables: {
-                readonly type: "boolean";
-                readonly description: "Include variables in output";
-            };
-            userTask: {
-                readonly type: "boolean";
-                readonly description: "Get form for user task";
-            };
-            ut: {
-                readonly type: "boolean";
-                readonly description: "Alias for --userTask";
-            };
-            processDefinition: {
-                readonly type: "boolean";
-                readonly description: "Get form for process definition";
-            };
-            pd: {
-                readonly type: "boolean";
-                readonly description: "Alias for --processDefinition";
-            };
-            xml: {
-                readonly type: "boolean";
-                readonly description: "Get BPMN XML (process definitions)";
-            };
-        };
+        flags: {};
         resourceFlags: {
             "process-definition": {
                 readonly xml: {
@@ -2012,12 +1755,7 @@ export declare const COMMAND_REGISTRY: {
             description: string;
         }[];
         resources: string[];
-        flags: {
-            shell: {
-                type: "string";
-                description: string;
-            };
-        };
+        flags: {};
         resourceFlags: {
             install: {
                 shell: {
@@ -2106,7 +1844,7 @@ export declare function isValidCommand(verb: string, resource: string): boolean;
  * "string" wins because parseArgs with `type: "string"` can accept any
  * value, whereas `type: "boolean"` would discard the string payload.
  */
-export declare function deriveParseArgsOptions(): Record<string, {
+export declare function deriveParseArgsOptions(pluginFlags?: Record<string, Record<string, FlagDef>>): Record<string, {
     type: "string" | "boolean";
     short?: string;
 }>;

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

@@ -1 +1 @@
-{"version":3,"file":"command-registry.d.ts","sourceRoot":"","sources":["../src/command-registry.ts"],"names":[],"mappings":"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8jCS,CAAC;AAEvC,yEAAyE;AACzE,MAAM,MAAM,IAAI,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAIjD;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAe9C,CAAC;AAEL;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CASlE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC/B,IAAI,EAAE,MAAM,GACV,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAUrC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAWtE;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAC/C,MAAM,EACN;IAAE,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAC9C,CAwCA"}
+{"version":3,"file":"command-registry.d.ts","sourceRoot":"","sources":["../src/command-registry.ts"],"names":[],"mappings":"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"}

package/dist/command-registry.js

@@ -62,6 +62,12 @@ export const GLOBAL_FLAGS = {
         agentDescription: "Comma-separated list of output fields to include.\nReduces context window size when parsing output.\nExample: c8ctl list pi --fields Key,State,processDefinitionId\nCase-insensitive.",
         agentAppliesTo: "all list/search/get commands",
     },
+    json: {
+        type: "boolean",
+        description: "Force JSON output for this invocation (does not persist; overrides session state and C8CTL_OUTPUT_MODE)",
+        agentDescription: "Per-invocation JSON output. Equivalent to setting outputMode=json for one command without mutating session.json.\nPrecedence: --json > C8CTL_OUTPUT_MODE > persisted session state.",
+        agentAppliesTo: "all commands",
+    },
 };
 /**
  * Flags shared across all search/list commands.
@@ -418,23 +424,18 @@ export const COMMAND_REGISTRY = {
             "auth",
             "mapping-rules",
         ],
+        // Verb-level `flags` holds only genuinely shared flags. Per-resource
+        // flags live exclusively in `resourceFlags` so unknown-flag detection
+        // warns when (e.g.) `--processDefinitionId` is passed against a
+        // non-PD resource (#256). The flag is still parsed by `parseArgs`
+        // (see `deriveParseArgsOptions`, which iterates `resourceFlags` too)
+        // and the value is ignored — the warning is the user-facing signal.
         flags: {
             all: {
                 type: "boolean",
                 description: "List all (disable pagination limit)",
             },
             ...SEARCH_FLAGS,
-            ...PI_SEARCH_FLAGS,
-            ...PD_SEARCH_FLAGS,
-            ...UT_SEARCH_FLAGS,
-            ...INC_SEARCH_FLAGS,
-            ...JOB_SEARCH_FLAGS,
-            ...USER_SEARCH_FLAGS,
-            ...ROLE_SEARCH_FLAGS,
-            ...GROUP_SEARCH_FLAGS,
-            ...TENANT_SEARCH_FLAGS,
-            ...AUTH_SEARCH_FLAGS,
-            ...MR_SEARCH_FLAGS,
         },
         resourceFlags: {
             "process-definition": PD_SEARCH_FLAGS,
@@ -521,20 +522,14 @@ export const COMMAND_REGISTRY = {
             "auth",
             "mapping-rules",
         ],
+        // Verb-level `flags` holds only genuinely shared flags. Per-resource
+        // flags live exclusively in `resourceFlags` so unknown-flag detection
+        // warns when (e.g.) `--processDefinitionId` is passed against a
+        // non-PD resource (#256). The flag is still parsed by `parseArgs`
+        // (see `deriveParseArgsOptions`, which iterates `resourceFlags` too)
+        // and the value is ignored — the warning is the user-facing signal.
         flags: {
             ...SEARCH_FLAGS,
-            ...PI_SEARCH_FLAGS,
-            ...PD_SEARCH_FLAGS,
-            ...UT_SEARCH_FLAGS,
-            ...INC_SEARCH_FLAGS,
-            ...JOB_SEARCH_FLAGS,
-            ...VAR_SEARCH_FLAGS,
-            ...USER_SEARCH_FLAGS,
-            ...ROLE_SEARCH_FLAGS,
-            ...GROUP_SEARCH_FLAGS,
-            ...TENANT_SEARCH_FLAGS,
-            ...AUTH_SEARCH_FLAGS,
-            ...MR_SEARCH_FLAGS,
         },
         resourceFlags: {
             "process-definition": PD_SEARCH_FLAGS,
@@ -602,7 +597,13 @@ export const COMMAND_REGISTRY = {
             "auth",
             "mapping-rule",
         ],
-        flags: { ...GET_PD_FLAGS, ...GET_FORM_FLAGS, ...GET_PI_FLAGS },
+        // Verb-level `flags` holds only genuinely shared flags. Per-resource
+        // flags live exclusively in `resourceFlags` so unknown-flag detection
+        // warns when (e.g.) `--xml` is passed against a non-PD resource
+        // (#256). The flag is still parsed by `parseArgs` (see
+        // `deriveParseArgsOptions`, which iterates `resourceFlags` too) and
+        // the value is ignored — the warning is the user-facing signal.
+        flags: {},
         resourceFlags: {
             "process-definition": GET_PD_FLAGS,
             form: GET_FORM_FLAGS,
@@ -1359,12 +1360,14 @@ export const COMMAND_REGISTRY = {
             },
         ],
         resources: ["bash", "zsh", "fish", "install"],
-        flags: {
-            shell: {
-                type: "string",
-                description: "Shell to install completions for (bash, zsh, fish)",
-            },
-        },
+        // `--shell` only applies to `completion install` — declared once in
+        // `resourceFlags.install` so it triggers an unknown-flag warning when
+        // passed to other resources (e.g. `completion zsh --shell bash`).
+        // This is the original #256 defect class. `parseArgs` still accepts
+        // the flag globally via `deriveParseArgsOptions` iterating
+        // `resourceFlags`, and the value is ignored on non-install branches
+        // of `completionCommand` — the warning is the user-facing signal.
+        flags: {},
         resourceFlags: {
             install: {
                 shell: {
@@ -1403,7 +1406,7 @@ export const COMMAND_REGISTRY = {
         aliases: ["menu"],
     },
     which: {
-        description: "Show active profile",
+        description: "Show active profile or output mode",
         mutating: false,
         requiresResource: true,
         helpExamples: [
@@ -1411,8 +1414,12 @@ export const COMMAND_REGISTRY = {
                 command: "c8ctl which profile",
                 description: "Show currently active profile",
             },
+            {
+                command: "c8ctl which output",
+                description: "Show current output mode",
+            },
         ],
-        resources: ["profile"],
+        resources: ["profile", "output"],
         flags: {},
     },
 };
@@ -1499,7 +1506,7 @@ export function isValidCommand(verb, resource) {
  * "string" wins because parseArgs with `type: "string"` can accept any
  * value, whereas `type: "boolean"` would discard the string payload.
  */
-export function deriveParseArgsOptions() {
+export function deriveParseArgsOptions(pluginFlags) {
     const options = {};
     function addFlags(flags) {
         for (const [name, def] of Object.entries(flags)) {
@@ -1533,6 +1540,12 @@ export function deriveParseArgsOptions() {
             }
         }
     }
+    // Add plugin flags if provided
+    if (pluginFlags) {
+        for (const commandFlags of Object.values(pluginFlags)) {
+            addFlags(commandFlags);
+        }
+    }
     return options;
 }
 //# sourceMappingURL=command-registry.js.map