@qraft/cli-utils 1.0.0-beta.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @qraft/cli-utils
+
+## 1.0.0-beta.0
+
+### Minor Changes
+
+- a282960: Introduce unified CLI tool `@qraft/cli` that extends code generation capabilities beyond OpenAPI to support AsyncAPI
+  specifications. The new CLI provides three main commands:
+  - `qraft openapi` - Generate type-safe code from OpenAPI documents (React Query hooks and TypeScript types)
+  - `qraft asyncapi` - Generate TypeScript types from AsyncAPI documents
+  - `qraft redocly` - Generate code from Redocly configuration files supporting both OpenAPI and AsyncAPI APIs
+
+  The CLI uses a plugin-based architecture where plugins are installed as peer dependencies, allowing users to install
+  only the plugins they need. It maintains full backward compatibility with existing OpenAPI workflows while adding
+  seamless support for event-driven API specifications.
+
+### Patch Changes
+
+- Updated dependencies [a282960]
+  - @qraft/plugin@1.0.0-beta.0

package/dist/addCommandUsageWithPlugins.d.ts

@@ -0,0 +1,6 @@
+import type { QraftCommand } from '@qraft/plugin';
+/**
+ * Adds plugin usage instructions by calling `command.usage(...)`
+ */
+export declare function addCommandUsageWithPlugins(command: QraftCommand<any>, plugins: string[]): void;
+//# sourceMappingURL=addCommandUsageWithPlugins.d.ts.map

package/dist/addCommandUsageWithPlugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addCommandUsageWithPlugins.d.ts","sourceRoot":"","sources":["../src/addCommandUsageWithPlugins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC,EAC1B,OAAO,EAAE,MAAM,EAAE,GAChB,IAAI,CAGN"}

package/dist/addCommandUsageWithPlugins.js

@@ -0,0 +1,8 @@
+/**
+ * Adds plugin usage instructions by calling `command.usage(...)`
+ */
+export function addCommandUsageWithPlugins(command, plugins) {
+    const pluginUsage = plugins.map((plugin) => `--plugin ${plugin}`).join(' ');
+    command.usage(`${pluginUsage} [input] [options]`);
+}
+//# sourceMappingURL=addCommandUsageWithPlugins.js.map

package/dist/addCommandUsageWithPlugins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"addCommandUsageWithPlugins.js","sourceRoot":"","sources":["../src/addCommandUsageWithPlugins.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAA0B,EAC1B,OAAiB;IAEjB,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,YAAY,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5E,OAAO,CAAC,KAAK,CAAC,GAAG,WAAW,oBAAoB,CAAC,CAAC;AACpD,CAAC"}

package/dist/extractArgvPluginOptions.d.ts

@@ -0,0 +1,10 @@
+export interface ExtractArgvPluginOptionsResult {
+    argv: string[];
+    plugins?: string[];
+}
+/**
+ * Extracts multiple `--plugin <name>` options from `argv`
+ * and returns both the filtered `argv` and the extracted plugins list.
+ */
+export declare function extractArgvPluginOptions(argv: string[]): ExtractArgvPluginOptionsResult;
+//# sourceMappingURL=extractArgvPluginOptions.d.ts.map

package/dist/extractArgvPluginOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractArgvPluginOptions.d.ts","sourceRoot":"","sources":["../src/extractArgvPluginOptions.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,8BAA8B;IAC7C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EAAE,GACb,8BAA8B,CA6BhC"}

package/dist/extractArgvPluginOptions.js

@@ -0,0 +1,30 @@
+/**
+ * Extracts multiple `--plugin <name>` options from `argv`
+ * and returns both the filtered `argv` and the extracted plugins list.
+ */
+export function extractArgvPluginOptions(argv) {
+    const pluginIndex = argv.indexOf('--plugin');
+    if (pluginIndex === -1)
+        return { argv };
+    const filteredArgv = argv.slice(0, pluginIndex);
+    const plugins = [];
+    for (let i = pluginIndex; i < argv.length; i++) {
+        if (argv[i] === '--plugin') {
+            const pluginName = argv.at(i + 1);
+            if (!pluginName)
+                throw new Error(`A plugin name must be specified after the '--plugin' option`);
+            if (pluginName?.startsWith('--'))
+                throw new Error(`Invalid plugin name: '${pluginName}'. Plugin names cannot start with '--'`);
+            plugins.push(pluginName);
+            i++; // Skip next item
+        }
+        else {
+            filteredArgv.push(argv[i]);
+        }
+    }
+    return {
+        argv: filteredArgv,
+        plugins,
+    };
+}
+//# sourceMappingURL=extractArgvPluginOptions.js.map

package/dist/extractArgvPluginOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractArgvPluginOptions.js","sourceRoot":"","sources":["../src/extractArgvPluginOptions.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CACtC,IAAc;IAEd,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7C,IAAI,WAAW,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAExC,MAAM,YAAY,GAAa,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;IAC1D,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,IAAI,CAAC,GAAG,WAAW,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/C,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,UAAU,EAAE,CAAC;YAC3B,MAAM,UAAU,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAClC,IAAI,CAAC,UAAU;gBACb,MAAM,IAAI,KAAK,CACb,6DAA6D,CAC9D,CAAC;YACJ,IAAI,UAAU,EAAE,UAAU,CAAC,IAAI,CAAC;gBAC9B,MAAM,IAAI,KAAK,CACb,yBAAyB,UAAU,wCAAwC,CAC5E,CAAC;YACJ,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YACzB,CAAC,EAAE,CAAC,CAAC,iBAAiB;QACxB,CAAC;aAAM,CAAC;YACN,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,OAAO;KACR,CAAC;AACJ,CAAC"}

package/dist/fileHeader.d.ts

@@ -0,0 +1,2 @@
+export declare function createFileHeader(cliName: string): string;
+//# sourceMappingURL=fileHeader.d.ts.map

package/dist/fileHeader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileHeader.d.ts","sourceRoot":"","sources":["../src/fileHeader.ts"],"names":[],"mappings":"AAAA,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAOxD"}

package/dist/fileHeader.js

@@ -0,0 +1,9 @@
+export function createFileHeader(cliName) {
+    return `/**
+ * This file was auto-generated by ${cliName}.
+ * Do not make direct changes to the file.
+ */
+
+`;
+}
+//# sourceMappingURL=fileHeader.js.map

package/dist/fileHeader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileHeader.js","sourceRoot":"","sources":["../src/fileHeader.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,OAAO;qCAC4B,OAAO;;;;CAI3C,CAAC;AACF,CAAC"}

package/dist/hasHelpOption.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Checks if the argv array contains help option flags (--help or -h).
+ */
+export declare function hasHelpOption(argv: string[]): boolean;
+//# sourceMappingURL=hasHelpOption.d.ts.map

package/dist/hasHelpOption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hasHelpOption.d.ts","sourceRoot":"","sources":["../src/hasHelpOption.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAErD"}

package/dist/hasHelpOption.js

@@ -0,0 +1,7 @@
+/**
+ * Checks if the argv array contains help option flags (--help or -h).
+ */
+export function hasHelpOption(argv) {
+    return argv.includes('--help') || argv.includes('-h');
+}
+//# sourceMappingURL=hasHelpOption.js.map

package/dist/hasHelpOption.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hasHelpOption.js","sourceRoot":"","sources":["../src/hasHelpOption.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,IAAc;IAC1C,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACxD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { extractArgvPluginOptions, type ExtractArgvPluginOptionsResult, } from './extractArgvPluginOptions.js';
+export { setupPlugins, type BuiltInPlugins, type SetupPluginsOptions, } from './setupPlugins.js';
+export { addCommandUsageWithPlugins } from './addCommandUsageWithPlugins.js';
+export { hasHelpOption } from './hasHelpOption.js';
+export { createFileHeader } from './fileHeader.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,KAAK,8BAA8B,GACpC,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { extractArgvPluginOptions, } from './extractArgvPluginOptions.js';
+export { setupPlugins, } from './setupPlugins.js';
+export { addCommandUsageWithPlugins } from './addCommandUsageWithPlugins.js';
+export { hasHelpOption } from './hasHelpOption.js';
+export { createFileHeader } from './fileHeader.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,GAEzB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,YAAY,GAGb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/setupPlugins.d.ts

@@ -0,0 +1,18 @@
+import type { QraftCommand } from '@qraft/plugin';
+import type { QraftCommandPlugin } from '@qraft/plugin/lib/QraftCommandPlugin';
+export type BuiltInPlugins<T extends string = string> = Record<T, () => Promise<{
+    default: QraftCommandPlugin<QraftCommand<any>>;
+}>>;
+export interface SetupPluginsOptions<T extends string> {
+    command: QraftCommand<any>;
+    plugins: T[];
+    builtInPlugins: BuiltInPlugins<T>;
+    addUsage?: (command: QraftCommand<any>, plugins: T[]) => void;
+}
+/**
+ * Loads and configures plugins for a QraftCommand.
+ * Validates plugin names against builtInPlugins, dynamically imports each plugin,
+ * and calls setupCommand/postSetupCommand lifecycle methods.
+ */
+export declare function setupPlugins<T extends string>({ command, plugins, builtInPlugins, addUsage, }: SetupPluginsOptions<T>): Promise<void>;
+//# sourceMappingURL=setupPlugins.d.ts.map

package/dist/setupPlugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupPlugins.d.ts","sourceRoot":"","sources":["../src/setupPlugins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAE/E,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,MAAM,CAC5D,CAAC,EACD,MAAM,OAAO,CAAC;IAAE,OAAO,EAAE,kBAAkB,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAA;CAAE,CAAC,CAClE,CAAC;AAEF,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS,MAAM;IACnD,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC;IAC3B,OAAO,EAAE,CAAC,EAAE,CAAC;IACb,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IAClC,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC;CAC/D;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,EACnD,OAAO,EACP,OAAO,EACP,cAAc,EACd,QAAQ,GACT,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBxC"}

package/dist/setupPlugins.js

@@ -0,0 +1,18 @@
+/**
+ * Loads and configures plugins for a QraftCommand.
+ * Validates plugin names against builtInPlugins, dynamically imports each plugin,
+ * and calls setupCommand/postSetupCommand lifecycle methods.
+ */
+export async function setupPlugins({ command, plugins, builtInPlugins, addUsage, }) {
+    const pluginList = [];
+    for (const pluginName of plugins) {
+        if (!(pluginName in builtInPlugins))
+            throw new Error(`Unknown plugin: '${pluginName}'`);
+        pluginList.push((await builtInPlugins[pluginName]())
+            .default);
+        addUsage?.(command, plugins);
+    }
+    await Promise.all(pluginList.map((plugin) => plugin.setupCommand(command)));
+    await Promise.all(pluginList.map((plugin) => plugin.postSetupCommand?.(command, plugins)));
+}
+//# sourceMappingURL=setupPlugins.js.map

package/dist/setupPlugins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupPlugins.js","sourceRoot":"","sources":["../src/setupPlugins.ts"],"names":[],"mappings":"AAeA;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAmB,EACnD,OAAO,EACP,OAAO,EACP,cAAc,EACd,QAAQ,GACe;IACvB,MAAM,UAAU,GAA4C,EAAE,CAAC;IAE/D,KAAK,MAAM,UAAU,IAAI,OAAO,EAAE,CAAC;QACjC,IAAI,CAAC,CAAC,UAAU,IAAI,cAAc,CAAC;YACjC,MAAM,IAAI,KAAK,CAAC,oBAAoB,UAAU,GAAG,CAAC,CAAC;QAErD,UAAU,CAAC,IAAI,CACb,CAAC,MAAM,cAAc,CAAC,UAAyC,CAAC,EAAE,CAAC;aAChE,OAAO,CACX,CAAC;QAEF,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5E,MAAM,OAAO,CAAC,GAAG,CACf,UAAU,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CACxE,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@qraft/cli-utils",
+  "version": "1.0.0-beta.0",
+  "description": "Shared CLI utilities for Qraft code generation tools",
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "dev": "yarn build --watch --noEmitOnError false",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint",
+    "clean": "rimraf dist/"
+  },
+  "type": "module",
+  "dependencies": {
+    "@qraft/plugin": "1.0.0-beta.0"
+  },
+  "devDependencies": {
+    "@openapi-qraft/eslint-config": "1.0.1",
+    "@types/node": "^20.16.5",
+    "eslint": "^9.39.1",
+    "rimraf": "^6.1.2",
+    "typescript": "^5.6.2",
+    "vitest": "^3.2.4"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!dist/**/*.test.*",
+    "!dist/**/*.spec.*",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*"
+  ],
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "dist/*"
+      ]
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OpenAPI-Qraft/openapi-qraft.git",
+    "directory": "packages/cli-utils"
+  },
+  "bugs": {
+    "url": "https://github.com/OpenAPI-Qraft/openapi-qraft/issues"
+  },
+  "homepage": "https://openapi-qraft.github.io/openapi-qraft/",
+  "keywords": [
+    "openapi",
+    "swagger",
+    "rest",
+    "api",
+    "oapi_3",
+    "oapi_3_1",
+    "typescript",
+    "ts",
+    "dts",
+    "codegen",
+    "generation",
+    "fetch",
+    "react",
+    "hooks",
+    "TanStack Query"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/addCommandUsageWithPlugins.ts

@@ -0,0 +1,12 @@
+import type { QraftCommand } from '@qraft/plugin';
+
+/**
+ * Adds plugin usage instructions by calling `command.usage(...)`
+ */
+export function addCommandUsageWithPlugins(
+  command: QraftCommand<any>,
+  plugins: string[]
+): void {
+  const pluginUsage = plugins.map((plugin) => `--plugin ${plugin}`).join(' ');
+  command.usage(`${pluginUsage} [input] [options]`);
+}

package/src/extractArgvPluginOptions.ts

@@ -0,0 +1,41 @@
+export interface ExtractArgvPluginOptionsResult {
+  argv: string[];
+  plugins?: string[];
+}
+
+/**
+ * Extracts multiple `--plugin <name>` options from `argv`
+ * and returns both the filtered `argv` and the extracted plugins list.
+ */
+export function extractArgvPluginOptions(
+  argv: string[]
+): ExtractArgvPluginOptionsResult {
+  const pluginIndex = argv.indexOf('--plugin');
+  if (pluginIndex === -1) return { argv };
+
+  const filteredArgv: string[] = argv.slice(0, pluginIndex);
+  const plugins: string[] = [];
+
+  for (let i = pluginIndex; i < argv.length; i++) {
+    if (argv[i] === '--plugin') {
+      const pluginName = argv.at(i + 1);
+      if (!pluginName)
+        throw new Error(
+          `A plugin name must be specified after the '--plugin' option`
+        );
+      if (pluginName?.startsWith('--'))
+        throw new Error(
+          `Invalid plugin name: '${pluginName}'. Plugin names cannot start with '--'`
+        );
+      plugins.push(pluginName);
+      i++; // Skip next item
+    } else {
+      filteredArgv.push(argv[i]);
+    }
+  }
+
+  return {
+    argv: filteredArgv,
+    plugins,
+  };
+}

package/src/fileHeader.ts

@@ -0,0 +1,8 @@
+export function createFileHeader(cliName: string): string {
+  return `/**
+ * This file was auto-generated by ${cliName}.
+ * Do not make direct changes to the file.
+ */
+
+`;
+}

package/src/hasHelpOption.ts

@@ -0,0 +1,6 @@
+/**
+ * Checks if the argv array contains help option flags (--help or -h).
+ */
+export function hasHelpOption(argv: string[]): boolean {
+  return argv.includes('--help') || argv.includes('-h');
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export {
+  extractArgvPluginOptions,
+  type ExtractArgvPluginOptionsResult,
+} from './extractArgvPluginOptions.js';
+export {
+  setupPlugins,
+  type BuiltInPlugins,
+  type SetupPluginsOptions,
+} from './setupPlugins.js';
+export { addCommandUsageWithPlugins } from './addCommandUsageWithPlugins.js';
+export { hasHelpOption } from './hasHelpOption.js';
+export { createFileHeader } from './fileHeader.js';

package/src/setupPlugins.ts

@@ -0,0 +1,45 @@
+import type { QraftCommand } from '@qraft/plugin';
+import type { QraftCommandPlugin } from '@qraft/plugin/lib/QraftCommandPlugin';
+
+export type BuiltInPlugins<T extends string = string> = Record<
+  T,
+  () => Promise<{ default: QraftCommandPlugin<QraftCommand<any>> }>
+>;
+
+export interface SetupPluginsOptions<T extends string> {
+  command: QraftCommand<any>;
+  plugins: T[];
+  builtInPlugins: BuiltInPlugins<T>;
+  addUsage?: (command: QraftCommand<any>, plugins: T[]) => void;
+}
+
+/**
+ * Loads and configures plugins for a QraftCommand.
+ * Validates plugin names against builtInPlugins, dynamically imports each plugin,
+ * and calls setupCommand/postSetupCommand lifecycle methods.
+ */
+export async function setupPlugins<T extends string>({
+  command,
+  plugins,
+  builtInPlugins,
+  addUsage,
+}: SetupPluginsOptions<T>): Promise<void> {
+  const pluginList: QraftCommandPlugin<QraftCommand<any>>[] = [];
+
+  for (const pluginName of plugins) {
+    if (!(pluginName in builtInPlugins))
+      throw new Error(`Unknown plugin: '${pluginName}'`);
+
+    pluginList.push(
+      (await builtInPlugins[pluginName as keyof typeof builtInPlugins]())
+        .default
+    );
+
+    addUsage?.(command, plugins);
+  }
+
+  await Promise.all(pluginList.map((plugin) => plugin.setupCommand(command)));
+  await Promise.all(
+    pluginList.map((plugin) => plugin.postSetupCommand?.(command, plugins))
+  );
+}