@kb-labs/shared-command-kit 1.0.0

package/dist/analytics/index.d.ts

@@ -0,0 +1,111 @@
+import { IAnalytics } from '@kb-labs/core-platform';
+
+/**
+ * Analytics Wrapper
+ *
+ * Optional helper for wrapping operations with analytics events.
+ * You can always use ctx.platform.analytics.track() directly - this is just convenience.
+ *
+ * @example
+ * ```typescript
+ * import { withAnalytics } from '@kb-labs/shared-command-kit';
+ *
+ * const result = await withAnalytics(ctx, 'mind.query', {
+ *   started: { queryId, text, mode },
+ *   completed: (result) => ({ tokensIn: result.tokensIn, tokensOut: result.tokensOut }),
+ *   failed: (error) => ({ errorMessage: error.message }),
+ * }, async () => {
+ *   return await executeQuery(...);
+ * });
+ * ```
+ */
+
+/**
+ * Context with optional analytics
+ */
+interface AnalyticsContext {
+    platform?: {
+        analytics?: IAnalytics;
+    };
+}
+/**
+ * Analytics event configuration
+ */
+interface AnalyticsEvents<TResult> {
+    /** Event properties when operation starts */
+    started?: Record<string, unknown>;
+    /** Event properties when operation completes (can be function of result) */
+    completed?: Record<string, unknown> | ((result: TResult) => Record<string, unknown>);
+    /** Event properties when operation fails (can be function of error) */
+    failed?: Record<string, unknown> | ((error: Error) => Record<string, unknown>);
+}
+/**
+ * Wrap an async operation with analytics tracking
+ *
+ * Automatically tracks:
+ * - `{eventName}.started` when operation begins
+ * - `{eventName}.completed` when operation succeeds
+ * - `{eventName}.failed` when operation fails
+ *
+ * @param ctx - Context with platform.analytics
+ * @param eventName - Base event name (e.g., 'mind.query', 'workflow.run')
+ * @param events - Event properties for started/completed/failed events
+ * @param operation - Async operation to execute
+ * @returns Result of the operation
+ *
+ * @example
+ * ```typescript
+ * const result = await withAnalytics(ctx, 'mind.query', {
+ *   started: { queryId: '123', text: 'search query' },
+ *   completed: (result) => ({
+ *     tokensIn: result.tokensIn,
+ *     tokensOut: result.tokensOut,
+ *     resultsCount: result.results.length,
+ *   }),
+ *   failed: (error) => ({
+ *     errorCode: error.code,
+ *     errorMessage: error.message,
+ *   }),
+ * }, async () => {
+ *   return await executeQuery('search query');
+ * });
+ * ```
+ */
+declare function withAnalytics<TResult>(ctx: AnalyticsContext, eventName: string, events: AnalyticsEvents<TResult>, operation: () => Promise<TResult>): Promise<TResult>;
+/**
+ * Create a reusable analytics wrapper for a specific event
+ *
+ * @param eventName - Base event name
+ * @param defaultEvents - Default event properties
+ * @returns Function that wraps operations with analytics
+ *
+ * @example
+ * ```typescript
+ * const trackQuery = createAnalyticsWrapper('mind.query', {
+ *   started: { source: 'cli' },
+ *   completed: (result) => ({ resultsCount: result.results.length }),
+ * });
+ *
+ * // Use multiple times
+ * const result1 = await trackQuery(ctx, { text: 'query 1' }, async () => {...});
+ * const result2 = await trackQuery(ctx, { text: 'query 2' }, async () => {...});
+ * ```
+ */
+declare function createAnalyticsWrapper<TResult>(eventName: string, defaultEvents: AnalyticsEvents<TResult>): (ctx: AnalyticsContext, additionalEvents: Partial<AnalyticsEvents<TResult>>, operation: () => Promise<TResult>) => Promise<TResult>;
+/**
+ * Track a simple event (no wrapping)
+ *
+ * Convenience helper for tracking single events without wrapping an operation.
+ *
+ * @param ctx - Context with platform.analytics
+ * @param eventName - Event name
+ * @param properties - Event properties
+ *
+ * @example
+ * ```typescript
+ * await trackEvent(ctx, 'button.clicked', { buttonId: 'submit', page: 'settings' });
+ * ```
+ */
+declare function trackEvent(ctx: AnalyticsContext, eventName: string, properties?: Record<string, unknown>): Promise<void>;
+
+export { type AnalyticsContext, type AnalyticsEvents, createAnalyticsWrapper, trackEvent, withAnalytics };

package/dist/analytics/index.js

@@ -0,0 +1,56 @@
+// src/analytics/with-analytics.ts
+async function withAnalytics(ctx, eventName, events, operation) {
+  const analytics = ctx.platform?.analytics;
+  const startTime = Date.now();
+  if (analytics && events.started) {
+    await analytics.track(`${eventName}.started`, {
+      ...events.started,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  try {
+    const result = await operation();
+    if (analytics && events.completed) {
+      const completedProps = typeof events.completed === "function" ? events.completed(result) : events.completed;
+      await analytics.track(`${eventName}.completed`, {
+        ...completedProps,
+        durationMs: Date.now() - startTime,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
+    return result;
+  } catch (error) {
+    if (analytics && events.failed) {
+      const failedProps = typeof events.failed === "function" ? events.failed(error) : events.failed;
+      await analytics.track(`${eventName}.failed`, {
+        ...failedProps,
+        durationMs: Date.now() - startTime,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
+    throw error;
+  }
+}
+function createAnalyticsWrapper(eventName, defaultEvents) {
+  return async (ctx, additionalEvents, operation) => {
+    const mergedEvents = {
+      started: { ...defaultEvents.started, ...additionalEvents.started },
+      completed: additionalEvents.completed || defaultEvents.completed,
+      failed: additionalEvents.failed || defaultEvents.failed
+    };
+    return withAnalytics(ctx, eventName, mergedEvents, operation);
+  };
+}
+async function trackEvent(ctx, eventName, properties) {
+  const analytics = ctx.platform?.analytics;
+  if (analytics) {
+    await analytics.track(eventName, {
+      ...properties,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+}
+
+export { createAnalyticsWrapper, trackEvent, withAnalytics };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/analytics/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/analytics/with-analytics.ts"],"names":[],"mappings":";AA2EA,eAAsB,aAAA,CACpB,GAAA,EACA,SAAA,EACA,MAAA,EACA,SAAA,EACkB;AAClB,EAAA,MAAM,SAAA,GAAY,IAAI,QAAA,EAAU,SAAA;AAChC,EAAA,MAAM,SAAA,GAAY,KAAK,GAAA,EAAI;AAG3B,EAAA,IAAI,SAAA,IAAa,OAAO,OAAA,EAAS;AAC/B,IAAA,MAAM,SAAA,CAAU,KAAA,CAAM,CAAA,EAAG,SAAS,CAAA,QAAA,CAAA,EAAY;AAAA,MAC5C,GAAG,MAAA,CAAO,OAAA;AAAA,MACV,SAAA,EAAA,iBAAW,IAAI,IAAA,EAAK,EAAE,WAAA;AAAY,KACnC,CAAA;AAAA,EACH;AAEA,EAAA,IAAI;AAEF,IAAA,MAAM,MAAA,GAAS,MAAM,SAAA,EAAU;AAG/B,IAAA,IAAI,SAAA,IAAa,OAAO,SAAA,EAAW;AACjC,MAAA,MAAM,cAAA,GAAiB,OAAO,MAAA,CAAO,SAAA,KAAc,aAC/C,MAAA,CAAO,SAAA,CAAU,MAAM,CAAA,GACvB,MAAA,CAAO,SAAA;AAEX,MAAA,MAAM,SAAA,CAAU,KAAA,CAAM,CAAA,EAAG,SAAS,CAAA,UAAA,CAAA,EAAc;AAAA,QAC9C,GAAG,cAAA;AAAA,QACH,UAAA,EAAY,IAAA,CAAK,GAAA,EAAI,GAAI,SAAA;AAAA,QACzB,SAAA,EAAA,iBAAW,IAAI,IAAA,EAAK,EAAE,WAAA;AAAY,OACnC,CAAA;AAAA,IACH;AAEA,IAAA,OAAO,MAAA;AAAA,EACT,SAAS,KAAA,EAAY;AAEnB,IAAA,IAAI,SAAA,IAAa,OAAO,MAAA,EAAQ;AAC9B,MAAA,MAAM,WAAA,GAAc,OAAO,MAAA,CAAO,MAAA,KAAW,aACzC,MAAA,CAAO,MAAA,CAAO,KAAK,CAAA,GACnB,MAAA,CAAO,MAAA;AAEX,MAAA,MAAM,SAAA,CAAU,KAAA,CAAM,CAAA,EAAG,SAAS,CAAA,OAAA,CAAA,EAAW;AAAA,QAC3C,GAAG,WAAA;AAAA,QACH,UAAA,EAAY,IAAA,CAAK,GAAA,EAAI,GAAI,SAAA;AAAA,QACzB,SAAA,EAAA,iBAAW,IAAI,IAAA,EAAK,EAAE,WAAA;AAAY,OACnC,CAAA;AAAA,IACH;AAGA,IAAA,MAAM,KAAA;AAAA,EACR;AACF;AAqBO,SAAS,sBAAA,CACd,WACA,aAAA,EACA;AACA,EAAA,OAAO,OACL,GAAA,EACA,gBAAA,EACA,SAAA,KACqB;AACrB,IAAA,MAAM,YAAA,GAAyC;AAAA,MAC7C,SAAS,EAAE,GAAG,cAAc,OAAA,EAAS,GAAG,iBAAiB,OAAA,EAAQ;AAAA,MACjE,SAAA,EAAW,gBAAA,CAAiB,SAAA,IAAa,aAAA,CAAc,SAAA;AAAA,MACvD,MAAA,EAAQ,gBAAA,CAAiB,MAAA,IAAU,aAAA,CAAc;AAAA,KACnD;AAEA,IAAA,OAAO,aAAA,CAAc,GAAA,EAAK,SAAA,EAAW,YAAA,EAAc,SAAS,CAAA;AAAA,EAC9D,CAAA;AACF;AAgBA,eAAsB,UAAA,CACpB,GAAA,EACA,SAAA,EACA,UAAA,EACe;AACf,EAAA,MAAM,SAAA,GAAY,IAAI,QAAA,EAAU,SAAA;AAEhC,EAAA,IAAI,SAAA,EAAW;AACb,IAAA,MAAM,SAAA,CAAU,MAAM,SAAA,EAAW;AAAA,MAC/B,GAAG,UAAA;AAAA,MACH,SAAA,EAAA,iBAAW,IAAI,IAAA,EAAK,EAAE,WAAA;AAAY,KACnC,CAAA;AAAA,EACH;AACF","file":"index.js","sourcesContent":["/**\n * Analytics Wrapper\n *\n * Optional helper for wrapping operations with analytics events.\n * You can always use ctx.platform.analytics.track() directly - this is just convenience.\n *\n * @example\n * ```typescript\n * import { withAnalytics } from '@kb-labs/shared-command-kit';\n *\n * const result = await withAnalytics(ctx, 'mind.query', {\n *   started: { queryId, text, mode },\n *   completed: (result) => ({ tokensIn: result.tokensIn, tokensOut: result.tokensOut }),\n *   failed: (error) => ({ errorMessage: error.message }),\n * }, async () => {\n *   return await executeQuery(...);\n * });\n * ```\n */\n\nimport type { IAnalytics } from '@kb-labs/core-platform';\n\n/**\n * Context with optional analytics\n */\nexport interface AnalyticsContext {\n  platform?: {\n    analytics?: IAnalytics;\n  };\n}\n\n/**\n * Analytics event configuration\n */\nexport interface AnalyticsEvents<TResult> {\n  /** Event properties when operation starts */\n  started?: Record<string, unknown>;\n  /** Event properties when operation completes (can be function of result) */\n  completed?: Record<string, unknown> | ((result: TResult) => Record<string, unknown>);\n  /** Event properties when operation fails (can be function of error) */\n  failed?: Record<string, unknown> | ((error: Error) => Record<string, unknown>);\n}\n\n/**\n * Wrap an async operation with analytics tracking\n *\n * Automatically tracks:\n * - `{eventName}.started` when operation begins\n * - `{eventName}.completed` when operation succeeds\n * - `{eventName}.failed` when operation fails\n *\n * @param ctx - Context with platform.analytics\n * @param eventName - Base event name (e.g., 'mind.query', 'workflow.run')\n * @param events - Event properties for started/completed/failed events\n * @param operation - Async operation to execute\n * @returns Result of the operation\n *\n * @example\n * ```typescript\n * const result = await withAnalytics(ctx, 'mind.query', {\n *   started: { queryId: '123', text: 'search query' },\n *   completed: (result) => ({\n *     tokensIn: result.tokensIn,\n *     tokensOut: result.tokensOut,\n *     resultsCount: result.results.length,\n *   }),\n *   failed: (error) => ({\n *     errorCode: error.code,\n *     errorMessage: error.message,\n *   }),\n * }, async () => {\n *   return await executeQuery('search query');\n * });\n * ```\n */\nexport async function withAnalytics<TResult>(\n  ctx: AnalyticsContext,\n  eventName: string,\n  events: AnalyticsEvents<TResult>,\n  operation: () => Promise<TResult>\n): Promise<TResult> {\n  const analytics = ctx.platform?.analytics;\n  const startTime = Date.now();\n\n  // Track started event\n  if (analytics && events.started) {\n    await analytics.track(`${eventName}.started`, {\n      ...events.started,\n      timestamp: new Date().toISOString(),\n    });\n  }\n\n  try {\n    // Execute operation\n    const result = await operation();\n\n    // Track completed event\n    if (analytics && events.completed) {\n      const completedProps = typeof events.completed === 'function'\n        ? events.completed(result)\n        : events.completed;\n\n      await analytics.track(`${eventName}.completed`, {\n        ...completedProps,\n        durationMs: Date.now() - startTime,\n        timestamp: new Date().toISOString(),\n      });\n    }\n\n    return result;\n  } catch (error: any) {\n    // Track failed event\n    if (analytics && events.failed) {\n      const failedProps = typeof events.failed === 'function'\n        ? events.failed(error)\n        : events.failed;\n\n      await analytics.track(`${eventName}.failed`, {\n        ...failedProps,\n        durationMs: Date.now() - startTime,\n        timestamp: new Date().toISOString(),\n      });\n    }\n\n    // Re-throw error\n    throw error;\n  }\n}\n\n/**\n * Create a reusable analytics wrapper for a specific event\n *\n * @param eventName - Base event name\n * @param defaultEvents - Default event properties\n * @returns Function that wraps operations with analytics\n *\n * @example\n * ```typescript\n * const trackQuery = createAnalyticsWrapper('mind.query', {\n *   started: { source: 'cli' },\n *   completed: (result) => ({ resultsCount: result.results.length }),\n * });\n *\n * // Use multiple times\n * const result1 = await trackQuery(ctx, { text: 'query 1' }, async () => {...});\n * const result2 = await trackQuery(ctx, { text: 'query 2' }, async () => {...});\n * ```\n */\nexport function createAnalyticsWrapper<TResult>(\n  eventName: string,\n  defaultEvents: AnalyticsEvents<TResult>\n) {\n  return async (\n    ctx: AnalyticsContext,\n    additionalEvents: Partial<AnalyticsEvents<TResult>>,\n    operation: () => Promise<TResult>\n  ): Promise<TResult> => {\n    const mergedEvents: AnalyticsEvents<TResult> = {\n      started: { ...defaultEvents.started, ...additionalEvents.started },\n      completed: additionalEvents.completed || defaultEvents.completed,\n      failed: additionalEvents.failed || defaultEvents.failed,\n    };\n\n    return withAnalytics(ctx, eventName, mergedEvents, operation);\n  };\n}\n\n/**\n * Track a simple event (no wrapping)\n *\n * Convenience helper for tracking single events without wrapping an operation.\n *\n * @param ctx - Context with platform.analytics\n * @param eventName - Event name\n * @param properties - Event properties\n *\n * @example\n * ```typescript\n * await trackEvent(ctx, 'button.clicked', { buttonId: 'submit', page: 'settings' });\n * ```\n */\nexport async function trackEvent(\n  ctx: AnalyticsContext,\n  eventName: string,\n  properties?: Record<string, unknown>\n): Promise<void> {\n  const analytics = ctx.platform?.analytics;\n\n  if (analytics) {\n    await analytics.track(eventName, {\n      ...properties,\n      timestamp: new Date().toISOString(),\n    });\n  }\n}\n"]}

package/dist/errors/index.d.ts

@@ -0,0 +1,227 @@
+/**
+ * @module @kb-labs/shared-command-kit/errors/types
+ * Types for error formatting
+ */
+/**
+ * Formatted error result
+ */
+interface FormattedError {
+    /** Human-readable error message */
+    message: string;
+    /** JSON representation */
+    json: {
+        ok: false;
+        error: string;
+        timingMs?: number;
+        stack?: string;
+    };
+}
+/**
+ * Error formatting options
+ */
+interface FormatErrorOptions {
+    /** Output in JSON format */
+    jsonMode?: boolean;
+    /** Include stack trace */
+    showStack?: boolean;
+    /** Timing information */
+    timingMs?: number;
+}
+
+/**
+ * @module @kb-labs/shared-command-kit/errors/format
+ * Error formatting utilities
+ */
+
+/**
+ * Format error for display
+ *
+ * @example
+ * ```typescript
+ * const formatted = formatError(error, {
+ *   jsonMode: Boolean(flags.json),
+ *   showStack: Boolean(flags.debug),
+ *   timingMs: tracker.total(),
+ * });
+ *
+ * if (flags.json) {
+ *   ctx.output?.json(formatted.json);
+ * } else {
+ *   ctx.output?.error(formatted.message);
+ * }
+ * ```
+ */
+declare function formatError(error: unknown, options?: FormatErrorOptions): FormattedError;
+
+/**
+ * Error Factory for KB Labs Plugins
+ *
+ * Optional helper for defining plugin errors without boilerplate.
+ * You can always use standard Error classes - this is just convenience.
+ *
+ * @example
+ * ```typescript
+ * import { defineError } from '@kb-labs/shared-command-kit';
+ *
+ * export const MindError = defineError('MIND', {
+ *   ValidationFailed: { code: 400, message: 'Validation failed' },
+ *   IndexNotFound: { code: 404, message: (scope: string) => `Index '${scope}' not found` },
+ *   QueryFailed: { code: 500, message: 'Query execution failed' },
+ * });
+ *
+ * // Usage:
+ * throw new MindError.IndexNotFound('default');
+ * throw new MindError.ValidationFailed({ details: { field: 'cwd' } });
+ * ```
+ */
+/**
+ * Error definition with HTTP code and message
+ */
+interface ErrorDefinition {
+    /** HTTP status code (400, 404, 500, etc.) */
+    code: number;
+    /** Error message - can be string or function for parameterized messages */
+    message: string | ((...args: any[]) => string);
+    /** Optional additional details */
+    details?: Record<string, unknown>;
+}
+/**
+ * Error definitions map
+ */
+type ErrorDefinitions = Record<string, ErrorDefinition>;
+/**
+ * Base error class with HTTP status code support
+ */
+declare class PluginError extends Error {
+    readonly statusCode: number;
+    readonly errorCode: string;
+    readonly details?: Record<string, unknown>;
+    constructor(errorCode: string, message: string, statusCode: number, details?: Record<string, unknown>);
+    /**
+     * Convert error to JSON for logging/serialization
+     */
+    toJSON(): {
+        name: string;
+        errorCode: string;
+        message: string;
+        statusCode: number;
+        details: Record<string, unknown> | undefined;
+        stack: string | undefined;
+    };
+    /**
+     * Check if error is a PluginError
+     */
+    static isPluginError(error: unknown): error is PluginError;
+}
+/**
+ * Type for error constructor created by defineError
+ */
+type ErrorConstructor<TArgs extends any[] = any[]> = {
+    new (details?: Record<string, unknown>): PluginError;
+    new (...args: TArgs): PluginError;
+};
+/**
+ * Type for error namespace created by defineError
+ */
+type ErrorNamespace<TDefs extends ErrorDefinitions> = {
+    [K in keyof TDefs]: ErrorConstructor;
+} & {
+    /** Check if error is from this namespace */
+    is(error: unknown): error is PluginError;
+    /** Check if error has specific error code */
+    hasCode(error: unknown, code: keyof TDefs): boolean;
+};
+/**
+ * Define a namespace of plugin errors
+ *
+ * @param prefix - Error code prefix (e.g., 'MIND', 'WORKFLOW')
+ * @param definitions - Error definitions map
+ * @returns Error namespace with error constructors
+ *
+ * @example
+ * ```typescript
+ * export const MindError = defineError('MIND', {
+ *   IndexNotFound: {
+ *     code: 404,
+ *     message: (scope: string) => `Index '${scope}' not found`
+ *   },
+ *   QueryFailed: {
+ *     code: 500,
+ *     message: 'Query execution failed'
+ *   },
+ * });
+ *
+ * // Throw with template params
+ * throw new MindError.IndexNotFound('default');
+ * // Error message: "Index 'default' not found"
+ *
+ * // Throw with details
+ * throw new MindError.QueryFailed({
+ *   details: { query: 'test', reason: 'timeout' }
+ * });
+ * ```
+ */
+declare function defineError<TDefs extends ErrorDefinitions>(prefix: string, definitions: TDefs): ErrorNamespace<TDefs>;
+/**
+ * Common error definitions that can be reused across plugins
+ */
+declare const commonErrors: {
+    /**
+     * Validation error (400)
+     */
+    ValidationFailed: {
+        code: number;
+        message: string;
+    };
+    /**
+     * Resource not found (404)
+     */
+    NotFound: {
+        code: number;
+        message: (resource: string) => string;
+    };
+    /**
+     * Unauthorized access (401)
+     */
+    Unauthorized: {
+        code: number;
+        message: string;
+    };
+    /**
+     * Forbidden access (403)
+     */
+    Forbidden: {
+        code: number;
+        message: string;
+    };
+    /**
+     * Internal server error (500)
+     */
+    InternalError: {
+        code: number;
+        message: string;
+    };
+    /**
+     * Service unavailable (503)
+     */
+    ServiceUnavailable: {
+        code: number;
+        message: (service: string) => string;
+    };
+    /**
+     * Timeout error (504)
+     */
+    Timeout: {
+        code: number;
+        message: (operation: string) => string;
+    };
+    /**
+     * Conflict error (409)
+     */
+    Conflict: {
+        code: number;
+        message: (resource: string) => string;
+    };
+};
+
+export { type ErrorDefinition, type ErrorDefinitions, type FormatErrorOptions, type FormattedError, PluginError, commonErrors, defineError, formatError };

package/dist/errors/index.js

@@ -0,0 +1,276 @@
+// src/flags/types.ts
+var FlagValidationError = class extends Error {
+  constructor(flag, message, value, schema, commandName) {
+    super(message);
+    this.flag = flag;
+    this.value = value;
+    this.schema = schema;
+    this.commandName = commandName;
+    this.name = "FlagValidationError";
+  }
+};
+
+// src/errors/format-validation.ts
+function formatValidationError(error, options = {}) {
+  const { commandName, schema } = options;
+  const lines = [];
+  const errorMsg = error.message;
+  if (errorMsg.includes("is required")) {
+    lines.push(`\u274C Missing required flag: --${error.flag}`);
+  } else if (errorMsg.includes("must be one of")) {
+    const valueStr = error.value !== void 0 ? ` ${error.value}` : "";
+    lines.push(`\u274C Invalid value for --${error.flag}:${valueStr}`);
+  } else if (errorMsg.includes("must be a")) {
+    lines.push(`\u274C Invalid type for --${error.flag}`);
+  } else if (errorMsg.includes("conflicts with")) {
+    lines.push(`\u274C Flag conflict: --${error.flag}`);
+  } else if (errorMsg.includes("depends on")) {
+    lines.push(`\u274C Missing dependency for --${error.flag}`);
+  } else {
+    lines.push(`\u274C ${errorMsg}`);
+  }
+  lines.push("");
+  if (commandName && schema) {
+    const usageLine = generateUsageLine(commandName, schema, error.flag);
+    if (usageLine) {
+      lines.push(`Usage: ${usageLine}`);
+    }
+  }
+  if (commandName) {
+    lines.push(`Hint: Try ${commandName} --help`);
+  } else {
+    lines.push("Hint: Try --help for more information");
+  }
+  return lines.join("\n");
+}
+function generateUsageLine(commandName, schema, errorFlag) {
+  const parts = [commandName];
+  const errorFlagSchema = schema[errorFlag];
+  if (errorFlagSchema) {
+    const flagStr = formatFlagForUsage(errorFlag, errorFlagSchema);
+    parts.push(flagStr);
+  }
+  const otherRequiredFlags = Object.entries(schema).filter(
+    ([name, flagSchema]) => name !== errorFlag && flagSchema.required
+  );
+  if (otherRequiredFlags.length > 0) {
+    for (const [name, flagSchema] of otherRequiredFlags) {
+      parts.push(formatFlagForUsage(name, flagSchema));
+    }
+  }
+  const hasOptionalFlags = Object.values(schema).some((s) => !s.required);
+  if (hasOptionalFlags) {
+    parts.push("[options]");
+  }
+  return parts.join(" ");
+}
+function formatFlagForUsage(name, schema) {
+  let valueHint;
+  if ("choices" in schema && schema.choices && schema.choices.length > 0) {
+    valueHint = `<${schema.choices.join("|")}>`;
+  } else if (schema.type === "boolean") {
+    return schema.required ? `--${name}` : `[--${name}]`;
+  } else {
+    valueHint = `<${name}>`;
+  }
+  const flagPart = `--${name} ${valueHint}`;
+  return schema.required ? flagPart : `[${flagPart}]`;
+}
+
+// src/errors/format.ts
+function formatError(error, options = {}) {
+  const { showStack = false, timingMs } = options;
+  if (error instanceof FlagValidationError) {
+    const friendlyMessage = formatValidationError(error, {
+      commandName: error.commandName,
+      schema: error.schema
+    });
+    const json2 = {
+      ok: false,
+      error: error.message
+    };
+    if (timingMs !== void 0) {
+      json2.timingMs = timingMs;
+    }
+    if (showStack && error.stack) {
+      json2.stack = error.stack;
+    }
+    let message2 = friendlyMessage;
+    if (showStack && error.stack) {
+      message2 = `${friendlyMessage}
+
+Stack trace:
+${error.stack}`;
+    }
+    return {
+      message: message2,
+      json: json2
+    };
+  }
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  const errorStack = error instanceof Error ? error.stack : void 0;
+  const json = {
+    ok: false,
+    error: errorMessage
+  };
+  if (timingMs !== void 0) {
+    json.timingMs = timingMs;
+  }
+  if (showStack && errorStack) {
+    json.stack = errorStack;
+  }
+  let message = errorMessage;
+  if (showStack && errorStack) {
+    message = `${errorMessage}
+
+${errorStack}`;
+  }
+  return {
+    message,
+    json
+  };
+}
+
+// src/errors/factory.ts
+var PluginError = class _PluginError extends Error {
+  statusCode;
+  errorCode;
+  details;
+  constructor(errorCode, message, statusCode, details) {
+    super(message);
+    this.name = "PluginError";
+    this.errorCode = errorCode;
+    this.statusCode = statusCode;
+    this.details = details;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _PluginError);
+    }
+  }
+  /**
+   * Convert error to JSON for logging/serialization
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      errorCode: this.errorCode,
+      message: this.message,
+      statusCode: this.statusCode,
+      details: this.details,
+      stack: this.stack
+    };
+  }
+  /**
+   * Check if error is a PluginError
+   */
+  static isPluginError(error) {
+    return error instanceof _PluginError;
+  }
+};
+function defineError(prefix, definitions) {
+  const errorNamespace = {};
+  for (const [key, def] of Object.entries(definitions)) {
+    const errorCode = `${prefix}_${key.toUpperCase()}`;
+    class DefinedError extends PluginError {
+      constructor(...args) {
+        const { message, details } = buildMessageAndDetails(def, args);
+        super(errorCode, message, def.code, details);
+        this.name = `${prefix}Error`;
+      }
+    }
+    errorNamespace[key] = DefinedError;
+  }
+  errorNamespace.is = (error) => {
+    return PluginError.isPluginError(error) && error.errorCode.startsWith(prefix + "_");
+  };
+  errorNamespace.hasCode = (error, code) => {
+    const errorCode = `${prefix}_${String(code).toUpperCase()}`;
+    return PluginError.isPluginError(error) && error.errorCode === errorCode;
+  };
+  return errorNamespace;
+}
+function buildMessageAndDetails(def, args) {
+  let message;
+  let details;
+  if (typeof def.message === "function") {
+    const lastArg = args[args.length - 1];
+    const hasDetails = lastArg && typeof lastArg === "object" && "details" in lastArg;
+    if (hasDetails) {
+      const templateArgs = args.slice(0, -1);
+      message = def.message(...templateArgs);
+      details = { ...def.details, ...lastArg.details };
+    } else {
+      message = def.message(...args);
+      details = def.details;
+    }
+  } else {
+    message = def.message;
+    if (args.length > 0 && typeof args[0] === "object" && args[0] !== null) {
+      details = { ...def.details, ...args[0].details };
+    } else {
+      details = def.details;
+    }
+  }
+  return { message, details };
+}
+var commonErrors = {
+  /**
+   * Validation error (400)
+   */
+  ValidationFailed: {
+    code: 400,
+    message: "Validation failed"
+  },
+  /**
+   * Resource not found (404)
+   */
+  NotFound: {
+    code: 404,
+    message: (resource) => `${resource} not found`
+  },
+  /**
+   * Unauthorized access (401)
+   */
+  Unauthorized: {
+    code: 401,
+    message: "Unauthorized"
+  },
+  /**
+   * Forbidden access (403)
+   */
+  Forbidden: {
+    code: 403,
+    message: "Forbidden"
+  },
+  /**
+   * Internal server error (500)
+   */
+  InternalError: {
+    code: 500,
+    message: "Internal server error"
+  },
+  /**
+   * Service unavailable (503)
+   */
+  ServiceUnavailable: {
+    code: 503,
+    message: (service) => `Service '${service}' is unavailable`
+  },
+  /**
+   * Timeout error (504)
+   */
+  Timeout: {
+    code: 504,
+    message: (operation) => `Operation '${operation}' timed out`
+  },
+  /**
+   * Conflict error (409)
+   */
+  Conflict: {
+    code: 409,
+    message: (resource) => `${resource} already exists`
+  }
+};
+
+export { PluginError, commonErrors, defineError, formatError };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map