@kb-labs/shared-command-kit 1.0.0

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/flags/types.ts","../../src/errors/format-validation.ts","../../src/errors/format.ts","../../src/errors/factory.ts"],"names":["json","message"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @module @kb-labs/shared-command-kit/flags/types\n * Types for flag validation and schema definition\n */\n\n/**\n * Flag type definition\n */\nexport type FlagType = 'boolean' | 'string' | 'number' | 'array';\n\n/**\n * Base flag schema definition\n */\nexport interface BaseFlagSchema<T extends FlagType = FlagType> {\n  /** Flag name */\n  name?: string;\n  /** Flag type */\n  type: T;\n  /** Short alias (e.g., 'n' for 'dry-run') */\n  alias?: string;\n  /** Description for help text */\n  description?: string;\n  /** Default value if flag is not provided */\n  default?: unknown;\n  /** Whether flag is required */\n  required?: boolean;\n  /** Flags that conflict with this flag */\n  conflicts?: string[];\n  /** Flags that this flag depends on */\n  dependsOn?: string[];\n  /** Flags that are implied when this flag is set */\n  implies?: string[] | [string, unknown][];\n  // Note: transform is defined in child interfaces with specific types\n}\n\n/**\n * Boolean flag schema\n */\nexport interface BooleanFlagSchema extends BaseFlagSchema<'boolean'> {\n  type: 'boolean';\n  default?: boolean;\n  /** Transform function to apply to the value */\n  transform?: (value: boolean) => boolean | Promise<boolean>;\n}\n\n/**\n * String flag schema\n */\nexport interface StringFlagSchema extends BaseFlagSchema<'string'> {\n  type: 'string';\n  default?: string;\n  /** Allowed values (enum) */\n  choices?: readonly string[];\n  /** Regex pattern for validation */\n  pattern?: RegExp;\n  /** Minimum string length */\n  minLength?: number;\n  /** Maximum string length */\n  maxLength?: number;\n  /** Custom validation function */\n  validate?: (value: string) => true | string | Promise<true | string>;\n  /** Transform function to apply to the value */\n  transform?: (value: string) => string | Promise<string>;\n}\n\n/**\n * Number flag schema\n */\nexport interface NumberFlagSchema extends BaseFlagSchema<'number'> {\n  type: 'number';\n  default?: number;\n  /** Minimum value */\n  min?: number;\n  /** Maximum value */\n  max?: number;\n  /** Custom validation function */\n  validate?: (value: number) => true | string | Promise<true | string>;\n  /** Transform function to apply to the value */\n  transform?: (value: number) => number | Promise<number>;\n}\n\n/**\n * Array flag schema\n */\nexport interface ArrayFlagSchema extends BaseFlagSchema<'array'> {\n  type: 'array';\n  default?: unknown[];\n  /** Type of array items */\n  items?: 'string' | 'number' | 'boolean';\n  /** Minimum array length */\n  minLength?: number;\n  /** Maximum array length */\n  maxLength?: number;\n  /** Transform function to apply to the value */\n  transform?: (value: unknown[]) => unknown[] | Promise<unknown[]>;\n}\n\n/**\n * Union of all flag schema types\n */\nexport type FlagSchema =\n  | BooleanFlagSchema\n  | StringFlagSchema\n  | NumberFlagSchema\n  | ArrayFlagSchema;\n\n/**\n * Flag schema definition object (for defineFlags)\n */\nexport type FlagSchemaDefinition = Record<string, Omit<FlagSchema, 'name'>>;\n\n/**\n * Validation error\n */\nexport class FlagValidationError extends Error {\n  constructor(\n    public readonly flag: string,\n    message: string,\n    public readonly value?: unknown,\n    public readonly schema?: FlagSchemaDefinition,\n    public readonly commandName?: string\n  ) {\n    super(message);\n    this.name = 'FlagValidationError';\n  }\n}\n\n/**\n * Validation result\n */\nexport interface ValidationResult<T = Record<string, unknown>> {\n  success: boolean;\n  data?: T;\n  errors?: Array<{\n    flag: string;\n    message: string;\n    value?: unknown;\n  }>;\n}\n\n/**\n * Safe validation result (doesn't throw)\n */\nexport interface SafeValidationResult<T = Record<string, unknown>> {\n  success: boolean;\n  data?: T;\n  errors: Array<{\n    flag: string;\n    message: string;\n    value?: unknown;\n  }>;\n}\n\n","/**\n * @module @kb-labs/shared-command-kit/errors/format-validation\n * User-friendly formatting for flag validation errors\n */\n\nimport type { FlagValidationError, StringFlagSchema } from '../flags/types';\nimport type { FlagSchemaDefinition } from '../flags/types';\n\n/**\n * Format a validation error into a user-friendly message\n *\n * @example\n * ```\n * ❌ Missing required flag: --text\n *\n * Usage: kb mind rag-query --text <query>\n * Hint: Try kb mind rag-query --help\n * ```\n */\nexport function formatValidationError(\n  error: FlagValidationError,\n  options: {\n    commandName?: string;\n    schema?: FlagSchemaDefinition;\n  } = {}\n): string {\n  const { commandName, schema } = options;\n  const lines: string[] = [];\n\n  // Main error message with emoji\n  const errorMsg = error.message;\n\n  // Determine error type and format accordingly\n  if (errorMsg.includes('is required')) {\n    lines.push(`❌ Missing required flag: --${error.flag}`);\n  } else if (errorMsg.includes('must be one of')) {\n    // Extract the invalid value if available\n    const valueStr = error.value !== undefined ? ` ${error.value}` : '';\n    lines.push(`❌ Invalid value for --${error.flag}:${valueStr}`);\n  } else if (errorMsg.includes('must be a')) {\n    lines.push(`❌ Invalid type for --${error.flag}`);\n  } else if (errorMsg.includes('conflicts with')) {\n    lines.push(`❌ Flag conflict: --${error.flag}`);\n  } else if (errorMsg.includes('depends on')) {\n    lines.push(`❌ Missing dependency for --${error.flag}`);\n  } else {\n    // Fallback: use the original message\n    lines.push(`❌ ${errorMsg}`);\n  }\n\n  lines.push(''); // Empty line for spacing\n\n  // Generate usage hint if we have schema and command name\n  if (commandName && schema) {\n    const usageLine = generateUsageLine(commandName, schema, error.flag);\n    if (usageLine) {\n      lines.push(`Usage: ${usageLine}`);\n    }\n  }\n\n  // Add help hint\n  if (commandName) {\n    lines.push(`Hint: Try ${commandName} --help`);\n  } else {\n    lines.push('Hint: Try --help for more information');\n  }\n\n  return lines.join('\\n');\n}\n\n/**\n * Generate a usage line from command name and schema\n *\n * @example\n * generateUsageLine('kb mind rag-query', schema, 'text')\n * // Returns: 'kb mind rag-query --text <query> [options]'\n */\nfunction generateUsageLine(\n  commandName: string,\n  schema: FlagSchemaDefinition,\n  errorFlag: string\n): string {\n  const parts: string[] = [commandName];\n\n  // Add the flag that caused the error first\n  const errorFlagSchema = schema[errorFlag];\n  if (errorFlagSchema) {\n    const flagStr = formatFlagForUsage(errorFlag, errorFlagSchema);\n    parts.push(flagStr);\n  }\n\n  // Check if there are other required flags\n  const otherRequiredFlags = Object.entries(schema)\n    .filter(([name, flagSchema]) =>\n      name !== errorFlag && flagSchema.required\n    );\n\n  if (otherRequiredFlags.length > 0) {\n    // Add other required flags\n    for (const [name, flagSchema] of otherRequiredFlags) {\n      parts.push(formatFlagForUsage(name, flagSchema));\n    }\n  }\n\n  // Add [options] if there are optional flags\n  const hasOptionalFlags = Object.values(schema).some(s => !s.required);\n  if (hasOptionalFlags) {\n    parts.push('[options]');\n  }\n\n  return parts.join(' ');\n}\n\n/**\n * Format a single flag for usage display\n *\n * @example\n * formatFlagForUsage('text', { type: 'string', required: true })\n * // Returns: '--text <text>'\n *\n * formatFlagForUsage('mode', { type: 'string', choices: ['local', 'auto'] })\n * // Returns: '[--mode <local|auto>]'\n */\nfunction formatFlagForUsage(\n  name: string,\n  schema: FlagSchemaDefinition[string]\n): string {\n  let valueHint: string;\n\n  if ('choices' in schema && (schema as StringFlagSchema).choices && (schema as StringFlagSchema).choices!.length > 0) {\n    // Show choices: <local|auto>\n    valueHint = `<${(schema as StringFlagSchema).choices!.join('|')}>`;\n  } else if (schema.type === 'boolean') {\n    // Boolean flags don't need a value hint\n    return schema.required ? `--${name}` : `[--${name}]`;\n  } else {\n    // Generic type hint: <text>, <number>, etc.\n    valueHint = `<${name}>`;\n  }\n\n  const flagPart = `--${name} ${valueHint}`;\n\n  return schema.required ? flagPart : `[${flagPart}]`;\n}\n","/**\n * @module @kb-labs/shared-command-kit/errors/format\n * Error formatting utilities\n */\n\nimport type { FormattedError, FormatErrorOptions } from './types';\nimport { FlagValidationError } from '../flags/types';\nimport { formatValidationError } from './format-validation';\n\n/**\n * Format error for display\n * \n * @example\n * ```typescript\n * const formatted = formatError(error, {\n *   jsonMode: Boolean(flags.json),\n *   showStack: Boolean(flags.debug),\n *   timingMs: tracker.total(),\n * });\n * \n * if (flags.json) {\n *   ctx.output?.json(formatted.json);\n * } else {\n *   ctx.output?.error(formatted.message);\n * }\n * ```\n */\nexport function formatError(\n  error: unknown,\n  options: FormatErrorOptions = {}\n): FormattedError {\n  const { showStack = false, timingMs } = options;\n\n  // Special handling for FlagValidationError\n  if (error instanceof FlagValidationError) {\n    const friendlyMessage = formatValidationError(error, {\n      commandName: error.commandName,\n      schema: error.schema,\n    });\n\n    const json: FormattedError['json'] = {\n      ok: false,\n      error: error.message,\n    };\n\n    if (timingMs !== undefined) {\n      json.timingMs = timingMs;\n    }\n\n    if (showStack && error.stack) {\n      json.stack = error.stack;\n    }\n\n    let message = friendlyMessage;\n    if (showStack && error.stack) {\n      message = `${friendlyMessage}\\n\\nStack trace:\\n${error.stack}`;\n    }\n\n    return {\n      message,\n      json,\n    };\n  }\n\n  // Standard error formatting for other errors\n  const errorMessage = error instanceof Error ? error.message : String(error);\n  const errorStack = error instanceof Error ? error.stack : undefined;\n\n  const json: FormattedError['json'] = {\n    ok: false,\n    error: errorMessage,\n  };\n\n  if (timingMs !== undefined) {\n    json.timingMs = timingMs;\n  }\n\n  if (showStack && errorStack) {\n    json.stack = errorStack;\n  }\n\n  let message = errorMessage;\n  if (showStack && errorStack) {\n    message = `${errorMessage}\\n\\n${errorStack}`;\n  }\n\n  return {\n    message,\n    json,\n  };\n}\n\n","/**\n * Error Factory for KB Labs Plugins\n *\n * Optional helper for defining plugin errors without boilerplate.\n * You can always use standard Error classes - this is just convenience.\n *\n * @example\n * ```typescript\n * import { defineError } from '@kb-labs/shared-command-kit';\n *\n * export const MindError = defineError('MIND', {\n *   ValidationFailed: { code: 400, message: 'Validation failed' },\n *   IndexNotFound: { code: 404, message: (scope: string) => `Index '${scope}' not found` },\n *   QueryFailed: { code: 500, message: 'Query execution failed' },\n * });\n *\n * // Usage:\n * throw new MindError.IndexNotFound('default');\n * throw new MindError.ValidationFailed({ details: { field: 'cwd' } });\n * ```\n */\n\n/**\n * Error definition with HTTP code and message\n */\nexport interface ErrorDefinition {\n  /** HTTP status code (400, 404, 500, etc.) */\n  code: number;\n  /** Error message - can be string or function for parameterized messages */\n  message: string | ((...args: any[]) => string);\n  /** Optional additional details */\n  details?: Record<string, unknown>;\n}\n\n/**\n * Error definitions map\n */\nexport type ErrorDefinitions = Record<string, ErrorDefinition>;\n\n/**\n * Base error class with HTTP status code support\n */\nexport class PluginError extends Error {\n  public readonly statusCode: number;\n  public readonly errorCode: string;\n  public readonly details?: Record<string, unknown>;\n\n  constructor(\n    errorCode: string,\n    message: string,\n    statusCode: number,\n    details?: Record<string, unknown>\n  ) {\n    super(message);\n    this.name = 'PluginError';\n    this.errorCode = errorCode;\n    this.statusCode = statusCode;\n    this.details = details;\n\n    // Maintains proper stack trace for where our error was thrown (only available on V8)\n    if (Error.captureStackTrace) {\n      Error.captureStackTrace(this, PluginError);\n    }\n  }\n\n  /**\n   * Convert error to JSON for logging/serialization\n   */\n  toJSON() {\n    return {\n      name: this.name,\n      errorCode: this.errorCode,\n      message: this.message,\n      statusCode: this.statusCode,\n      details: this.details,\n      stack: this.stack,\n    };\n  }\n\n  /**\n   * Check if error is a PluginError\n   */\n  static isPluginError(error: unknown): error is PluginError {\n    return error instanceof PluginError;\n  }\n}\n\n/**\n * Type for error constructor created by defineError\n */\ntype ErrorConstructor<TArgs extends any[] = any[]> = {\n  new (details?: Record<string, unknown>): PluginError;\n  new (...args: TArgs): PluginError;\n};\n\n/**\n * Type for error namespace created by defineError\n */\ntype ErrorNamespace<TDefs extends ErrorDefinitions> = {\n  [K in keyof TDefs]: ErrorConstructor;\n} & {\n  /** Check if error is from this namespace */\n  is(error: unknown): error is PluginError;\n  /** Check if error has specific error code */\n  hasCode(error: unknown, code: keyof TDefs): boolean;\n};\n\n/**\n * Define a namespace of plugin errors\n *\n * @param prefix - Error code prefix (e.g., 'MIND', 'WORKFLOW')\n * @param definitions - Error definitions map\n * @returns Error namespace with error constructors\n *\n * @example\n * ```typescript\n * export const MindError = defineError('MIND', {\n *   IndexNotFound: {\n *     code: 404,\n *     message: (scope: string) => `Index '${scope}' not found`\n *   },\n *   QueryFailed: {\n *     code: 500,\n *     message: 'Query execution failed'\n *   },\n * });\n *\n * // Throw with template params\n * throw new MindError.IndexNotFound('default');\n * // Error message: \"Index 'default' not found\"\n *\n * // Throw with details\n * throw new MindError.QueryFailed({\n *   details: { query: 'test', reason: 'timeout' }\n * });\n * ```\n */\nexport function defineError<TDefs extends ErrorDefinitions>(\n  prefix: string,\n  definitions: TDefs\n): ErrorNamespace<TDefs> {\n  const errorNamespace: any = {};\n\n  // Create error constructor for each definition\n  for (const [key, def] of Object.entries(definitions)) {\n    const errorCode = `${prefix}_${key.toUpperCase()}`;\n\n    // Create error class\n    class DefinedError extends PluginError {\n      constructor(...args: any[]) {\n        const { message, details } = buildMessageAndDetails(def, args);\n        super(errorCode, message, def.code, details);\n        this.name = `${prefix}Error`;\n      }\n    }\n\n    errorNamespace[key] = DefinedError;\n  }\n\n  // Add helper methods\n  errorNamespace.is = (error: unknown): error is PluginError => {\n    return PluginError.isPluginError(error) && error.errorCode.startsWith(prefix + '_');\n  };\n\n  errorNamespace.hasCode = (error: unknown, code: keyof TDefs): boolean => {\n    const errorCode = `${prefix}_${String(code).toUpperCase()}`;\n    return PluginError.isPluginError(error) && error.errorCode === errorCode;\n  };\n\n  return errorNamespace as ErrorNamespace<TDefs>;\n}\n\n/**\n * Build error message and details from definition and constructor args\n */\nfunction buildMessageAndDetails(\n  def: ErrorDefinition,\n  args: any[]\n): { message: string; details?: Record<string, unknown> } {\n  let message: string;\n  let details: Record<string, unknown> | undefined;\n\n  if (typeof def.message === 'function') {\n    // Template message - args are template params\n    const lastArg = args[args.length - 1];\n\n    // Check if last arg is details object (has 'details' key)\n    const hasDetails = lastArg && typeof lastArg === 'object' && 'details' in lastArg;\n\n    if (hasDetails) {\n      // Last arg is details, rest are template params\n      const templateArgs = args.slice(0, -1);\n      message = def.message(...templateArgs);\n      details = { ...def.details, ...lastArg.details };\n    } else {\n      // All args are template params\n      message = def.message(...args);\n      details = def.details;\n    }\n  } else {\n    // Static message\n    message = def.message;\n\n    // First arg can be details object\n    if (args.length > 0 && typeof args[0] === 'object' && args[0] !== null) {\n      details = { ...def.details, ...args[0].details };\n    } else {\n      details = def.details;\n    }\n  }\n\n  return { message, details };\n}\n\n/**\n * Common error definitions that can be reused across plugins\n */\nexport const commonErrors = {\n  /**\n   * Validation error (400)\n   */\n  ValidationFailed: {\n    code: 400,\n    message: 'Validation failed',\n  },\n\n  /**\n   * Resource not found (404)\n   */\n  NotFound: {\n    code: 404,\n    message: (resource: string) => `${resource} not found`,\n  },\n\n  /**\n   * Unauthorized access (401)\n   */\n  Unauthorized: {\n    code: 401,\n    message: 'Unauthorized',\n  },\n\n  /**\n   * Forbidden access (403)\n   */\n  Forbidden: {\n    code: 403,\n    message: 'Forbidden',\n  },\n\n  /**\n   * Internal server error (500)\n   */\n  InternalError: {\n    code: 500,\n    message: 'Internal server error',\n  },\n\n  /**\n   * Service unavailable (503)\n   */\n  ServiceUnavailable: {\n    code: 503,\n    message: (service: string) => `Service '${service}' is unavailable`,\n  },\n\n  /**\n   * Timeout error (504)\n   */\n  Timeout: {\n    code: 504,\n    message: (operation: string) => `Operation '${operation}' timed out`,\n  },\n\n  /**\n   * Conflict error (409)\n   */\n  Conflict: {\n    code: 409,\n    message: (resource: string) => `${resource} already exists`,\n  },\n} satisfies ErrorDefinitions;\n"]}

package/dist/flags/index.d.ts

@@ -0,0 +1,196 @@
+/**
+ * @module @kb-labs/shared-command-kit/flags/types
+ * Types for flag validation and schema definition
+ */
+/**
+ * Flag type definition
+ */
+type FlagType = 'boolean' | 'string' | 'number' | 'array';
+/**
+ * Base flag schema definition
+ */
+interface BaseFlagSchema<T extends FlagType = FlagType> {
+    /** Flag name */
+    name?: string;
+    /** Flag type */
+    type: T;
+    /** Short alias (e.g., 'n' for 'dry-run') */
+    alias?: string;
+    /** Description for help text */
+    description?: string;
+    /** Default value if flag is not provided */
+    default?: unknown;
+    /** Whether flag is required */
+    required?: boolean;
+    /** Flags that conflict with this flag */
+    conflicts?: string[];
+    /** Flags that this flag depends on */
+    dependsOn?: string[];
+    /** Flags that are implied when this flag is set */
+    implies?: string[] | [string, unknown][];
+}
+/**
+ * Boolean flag schema
+ */
+interface BooleanFlagSchema extends BaseFlagSchema<'boolean'> {
+    type: 'boolean';
+    default?: boolean;
+    /** Transform function to apply to the value */
+    transform?: (value: boolean) => boolean | Promise<boolean>;
+}
+/**
+ * String flag schema
+ */
+interface StringFlagSchema extends BaseFlagSchema<'string'> {
+    type: 'string';
+    default?: string;
+    /** Allowed values (enum) */
+    choices?: readonly string[];
+    /** Regex pattern for validation */
+    pattern?: RegExp;
+    /** Minimum string length */
+    minLength?: number;
+    /** Maximum string length */
+    maxLength?: number;
+    /** Custom validation function */
+    validate?: (value: string) => true | string | Promise<true | string>;
+    /** Transform function to apply to the value */
+    transform?: (value: string) => string | Promise<string>;
+}
+/**
+ * Number flag schema
+ */
+interface NumberFlagSchema extends BaseFlagSchema<'number'> {
+    type: 'number';
+    default?: number;
+    /** Minimum value */
+    min?: number;
+    /** Maximum value */
+    max?: number;
+    /** Custom validation function */
+    validate?: (value: number) => true | string | Promise<true | string>;
+    /** Transform function to apply to the value */
+    transform?: (value: number) => number | Promise<number>;
+}
+/**
+ * Array flag schema
+ */
+interface ArrayFlagSchema extends BaseFlagSchema<'array'> {
+    type: 'array';
+    default?: unknown[];
+    /** Type of array items */
+    items?: 'string' | 'number' | 'boolean';
+    /** Minimum array length */
+    minLength?: number;
+    /** Maximum array length */
+    maxLength?: number;
+    /** Transform function to apply to the value */
+    transform?: (value: unknown[]) => unknown[] | Promise<unknown[]>;
+}
+/**
+ * Union of all flag schema types
+ */
+type FlagSchema = BooleanFlagSchema | StringFlagSchema | NumberFlagSchema | ArrayFlagSchema;
+/**
+ * Flag schema definition object (for defineFlags)
+ */
+type FlagSchemaDefinition = Record<string, Omit<FlagSchema, 'name'>>;
+/**
+ * Validation error
+ */
+declare class FlagValidationError extends Error {
+    readonly flag: string;
+    readonly value?: unknown | undefined;
+    readonly schema?: FlagSchemaDefinition | undefined;
+    readonly commandName?: string | undefined;
+    constructor(flag: string, message: string, value?: unknown | undefined, schema?: FlagSchemaDefinition | undefined, commandName?: string | undefined);
+}
+/**
+ * Validation result
+ */
+interface ValidationResult<T = Record<string, unknown>> {
+    success: boolean;
+    data?: T;
+    errors?: Array<{
+        flag: string;
+        message: string;
+        value?: unknown;
+    }>;
+}
+/**
+ * Safe validation result (doesn't throw)
+ */
+interface SafeValidationResult<T = Record<string, unknown>> {
+    success: boolean;
+    data?: T;
+    errors: Array<{
+        flag: string;
+        message: string;
+        value?: unknown;
+    }>;
+}
+
+/**
+ * @module @kb-labs/shared-command-kit/flags/define
+ * Define flag schemas with automatic type inference
+ */
+
+/**
+ * Flag schema with type inference
+ */
+interface FlagSchemaWithInfer<T extends FlagSchemaDefinition> {
+    /** Original schema definition */
+    readonly schema: T;
+    /** Infer TypeScript type from schema */
+    infer: InferFlags<T>;
+}
+/**
+ * Infer TypeScript type from flag schema definition
+ */
+type InferFlags<T extends FlagSchemaDefinition> = {
+    [K in keyof T]: T[K] extends BooleanFlagSchema ? T[K]['default'] extends boolean ? boolean : T[K]['required'] extends true ? boolean : boolean | undefined : T[K] extends StringFlagSchema ? T[K]['choices'] extends readonly string[] ? T[K]['required'] extends true ? T[K]['choices'][number] : T[K]['default'] extends string ? T[K]['choices'][number] : T[K]['choices'][number] | undefined : T[K]['required'] extends true ? string : T[K]['default'] extends string ? string : string | undefined : T[K] extends NumberFlagSchema ? T[K]['required'] extends true ? number : T[K]['default'] extends number ? number : number | undefined : T[K] extends ArrayFlagSchema ? T[K]['items'] extends 'string' ? string[] : T[K]['items'] extends 'number' ? number[] : T[K]['items'] extends 'boolean' ? boolean[] : unknown[] : unknown;
+};
+/**
+ * Define a flag schema with automatic type inference
+ *
+ * @example
+ * ```typescript
+ * const schema = defineFlags({
+ *   scope: {
+ *     type: 'string',
+ *     required: true,
+ *     pattern: /^[@a-z0-9-/]+$/i,
+ *   },
+ *   'dry-run': {
+ *     type: 'boolean',
+ *     default: false,
+ *   },
+ * });
+ *
+ * type Flags = typeof schema.infer;
+ * // Flags = { scope: string; 'dry-run': boolean }
+ * ```
+ */
+declare function defineFlags<T extends FlagSchemaDefinition>(definition: T): FlagSchemaWithInfer<T>;
+
+/**
+ * @module @kb-labs/shared-command-kit/flags/validate
+ * Validate flags against schema
+ */
+
+/**
+ * Validate flags against schema and return typed result
+ *
+ * @throws {FlagValidationError} If validation fails and safe mode is not used
+ */
+declare function validateFlags<T extends FlagSchemaDefinition>(rawFlags: Record<string, unknown>, schemaDefinition: {
+    schema: T;
+} | T): Promise<InferFlags<T>>;
+/**
+ * Safe version of validateFlags that doesn't throw
+ */
+declare function validateFlagsSafe<T extends FlagSchemaDefinition>(rawFlags: Record<string, unknown>, schemaDefinition: {
+    schema: T;
+} | T): Promise<SafeValidationResult<InferFlags<T>>>;
+
+export { type ArrayFlagSchema, type BaseFlagSchema, type BooleanFlagSchema, type FlagSchema, type FlagSchemaDefinition, type FlagSchemaWithInfer, type FlagType, FlagValidationError, type InferFlags, type NumberFlagSchema, type SafeValidationResult, type StringFlagSchema, type ValidationResult, defineFlags, validateFlags, validateFlagsSafe };

package/dist/flags/index.js

@@ -0,0 +1,288 @@
+// 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/flags/define.ts
+function defineFlags(definition) {
+  return {
+    schema: definition,
+    infer: {}
+  };
+}
+
+// src/flags/validate.ts
+function coerceValue(value, type) {
+  if (value === void 0 || value === null) {
+    return value;
+  }
+  switch (type) {
+    case "boolean":
+      if (typeof value === "boolean") {
+        return value;
+      }
+      if (typeof value === "string") {
+        const lower = value.toLowerCase().trim();
+        if (lower === "true" || lower === "1" || lower === "yes") {
+          return true;
+        }
+        if (lower === "false" || lower === "0" || lower === "no" || lower === "") {
+          return false;
+        }
+      }
+      return Boolean(value);
+    case "number":
+      if (typeof value === "number") {
+        return value;
+      }
+      if (typeof value === "string") {
+        const parsed = Number(value);
+        if (!Number.isNaN(parsed) && Number.isFinite(parsed)) {
+          return parsed;
+        }
+      }
+      return Number(value);
+    case "array":
+      if (Array.isArray(value)) {
+        return value;
+      }
+      if (typeof value === "string") {
+        return value.split(",").map((item) => item.trim());
+      }
+      return [value];
+    case "string":
+      return String(value);
+    default:
+      return value;
+  }
+}
+async function validateFlag(flagName, value, schema) {
+  const { type, required } = schema;
+  const choices = "choices" in schema ? schema.choices : void 0;
+  const pattern = "pattern" in schema ? schema.pattern : void 0;
+  const min = "min" in schema ? schema.min : void 0;
+  const max = "max" in schema ? schema.max : void 0;
+  const validate = "validate" in schema ? schema.validate : void 0;
+  const minLength = "minLength" in schema ? schema.minLength : void 0;
+  const maxLength = "maxLength" in schema ? schema.maxLength : void 0;
+  const items = "items" in schema ? schema.items : void 0;
+  if (required && (value === void 0 || value === null || value === "")) {
+    return `Flag --${flagName} is required`;
+  }
+  if (value === void 0 || value === null) {
+    return true;
+  }
+  const coerced = coerceValue(value, type);
+  switch (type) {
+    case "boolean":
+      if (typeof coerced !== "boolean") {
+        return `Flag --${flagName} must be a boolean`;
+      }
+      break;
+    case "string":
+      if (typeof coerced !== "string") {
+        return `Flag --${flagName} must be a string`;
+      }
+      if (minLength !== void 0 && coerced.length < minLength) {
+        return `Flag --${flagName} must be at least ${minLength} characters long`;
+      }
+      if (maxLength !== void 0 && coerced.length > maxLength) {
+        return `Flag --${flagName} must be at most ${maxLength} characters long`;
+      }
+      if (choices && !choices.includes(coerced)) {
+        return `Flag --${flagName} must be one of: ${choices.join(", ")} (got: ${coerced})`;
+      }
+      if (pattern && !pattern.test(coerced)) {
+        return `Flag --${flagName} must match pattern ${pattern.toString()}`;
+      }
+      if (validate) {
+        const stringValidate = validate;
+        const result = await stringValidate(coerced);
+        if (result !== true) {
+          return result;
+        }
+      }
+      break;
+    case "number":
+      if (typeof coerced !== "number" || !Number.isFinite(coerced)) {
+        return `Flag --${flagName} must be a number`;
+      }
+      if (min !== void 0 && coerced < min) {
+        return `Flag --${flagName} must be >= ${min} (got: ${coerced})`;
+      }
+      if (max !== void 0 && coerced > max) {
+        return `Flag --${flagName} must be <= ${max} (got: ${coerced})`;
+      }
+      if (validate) {
+        const numberValidate = validate;
+        const result = await numberValidate(coerced);
+        if (result !== true) {
+          return result;
+        }
+      }
+      break;
+    case "array":
+      if (!Array.isArray(coerced)) {
+        return `Flag --${flagName} must be an array`;
+      }
+      if (minLength !== void 0 && coerced.length < minLength) {
+        return `Flag --${flagName} must have at least ${minLength} items`;
+      }
+      if (maxLength !== void 0 && coerced.length > maxLength) {
+        return `Flag --${flagName} must have at most ${maxLength} items`;
+      }
+      if (items) {
+        for (let i = 0; i < coerced.length; i++) {
+          const item = coerced[i];
+          if (items === "string" && typeof item !== "string") {
+            return `Flag --${flagName}[${i}] must be a string`;
+          }
+          if (items === "number" && typeof item !== "number") {
+            return `Flag --${flagName}[${i}] must be a number`;
+          }
+          if (items === "boolean" && typeof item !== "boolean") {
+            return `Flag --${flagName}[${i}] must be a boolean`;
+          }
+        }
+      }
+      break;
+  }
+  return true;
+}
+async function validateFlags(rawFlags, schemaDefinition) {
+  const schema = "schema" in schemaDefinition ? schemaDefinition.schema : schemaDefinition;
+  const errors = [];
+  const result = {};
+  const flagValues = { ...rawFlags };
+  for (const [flagName, flagSchema] of Object.entries(schema)) {
+    const value = flagValues[flagName];
+    if (value !== void 0 && value !== null && value !== false && value !== "") {
+      const implies = flagSchema.implies;
+      if (implies) {
+        for (const implied of implies) {
+          if (Array.isArray(implied) && implied.length === 2) {
+            const [impliedFlag, impliedValue] = implied;
+            if (flagValues[impliedFlag] === void 0) {
+              flagValues[impliedFlag] = impliedValue;
+            }
+          } else if (typeof implied === "string") {
+            if (flagValues[implied] === void 0) {
+              flagValues[implied] = true;
+            }
+          }
+        }
+      }
+    }
+  }
+  for (const [flagName, flagSchema] of Object.entries(schema)) {
+    const value = flagValues[flagName];
+    const schemaWithName = { ...flagSchema, name: flagName };
+    const conflicts = flagSchema.conflicts;
+    if (conflicts && value !== void 0 && value !== null && value !== false && value !== "") {
+      for (const conflictingFlag of conflicts) {
+        const conflictingValue = flagValues[conflictingFlag];
+        if (conflictingValue !== void 0 && conflictingValue !== null && conflictingValue !== false && conflictingValue !== "") {
+          errors.push({
+            flag: flagName,
+            message: `Flag --${flagName} conflicts with --${conflictingFlag}`,
+            value
+          });
+          break;
+        }
+      }
+      if (errors.some((e) => e.flag === flagName)) {
+        continue;
+      }
+    }
+    const dependsOn = flagSchema.dependsOn;
+    if (dependsOn && value !== void 0 && value !== null && value !== "") {
+      for (const dependency of dependsOn) {
+        const dependencyValue = flagValues[dependency];
+        if (dependencyValue === void 0 || dependencyValue === null || dependencyValue === "") {
+          errors.push({
+            flag: flagName,
+            message: `Flag --${flagName} depends on --${dependency}`,
+            value
+          });
+          break;
+        }
+      }
+      if (errors.some((e) => e.flag === flagName)) {
+        continue;
+      }
+    }
+    if (flagSchema.required && (value === void 0 || value === null || value === "")) {
+      errors.push({
+        flag: flagName,
+        message: `Flag --${flagName} is required`,
+        value
+      });
+      continue;
+    }
+    const finalValue = value !== void 0 ? value : flagSchema.default;
+    if (finalValue === void 0 && !flagSchema.required) {
+      continue;
+    }
+    const validationResult = await validateFlag(flagName, finalValue, schemaWithName);
+    if (validationResult !== true) {
+      errors.push({
+        flag: flagName,
+        message: validationResult,
+        value: finalValue
+      });
+      continue;
+    }
+    let transformedValue = coerceValue(finalValue, flagSchema.type);
+    const transform = flagSchema.transform;
+    if (transform) {
+      transformedValue = await transform(transformedValue);
+    }
+    result[flagName] = transformedValue;
+  }
+  if (errors.length > 0) {
+    const firstError = errors[0];
+    throw new FlagValidationError(
+      firstError.flag,
+      firstError.message,
+      firstError.value,
+      schema
+      // Pass schema for usage generation
+    );
+  }
+  return result;
+}
+async function validateFlagsSafe(rawFlags, schemaDefinition) {
+  try {
+    const data = await validateFlags(rawFlags, schemaDefinition);
+    return {
+      success: true,
+      data,
+      errors: []
+    };
+  } catch (error) {
+    if (error instanceof FlagValidationError) {
+      return {
+        success: false,
+        errors: [
+          {
+            flag: error.flag,
+            message: error.message,
+            value: error.value
+          }
+        ]
+      };
+    }
+    throw error;
+  }
+}
+
+export { FlagValidationError, defineFlags, validateFlags, validateFlagsSafe };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/flags/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/flags/types.ts","../../src/flags/define.ts","../../src/flags/validate.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @module @kb-labs/shared-command-kit/flags/types\n * Types for flag validation and schema definition\n */\n\n/**\n * Flag type definition\n */\nexport type FlagType = 'boolean' | 'string' | 'number' | 'array';\n\n/**\n * Base flag schema definition\n */\nexport interface BaseFlagSchema<T extends FlagType = FlagType> {\n  /** Flag name */\n  name?: string;\n  /** Flag type */\n  type: T;\n  /** Short alias (e.g., 'n' for 'dry-run') */\n  alias?: string;\n  /** Description for help text */\n  description?: string;\n  /** Default value if flag is not provided */\n  default?: unknown;\n  /** Whether flag is required */\n  required?: boolean;\n  /** Flags that conflict with this flag */\n  conflicts?: string[];\n  /** Flags that this flag depends on */\n  dependsOn?: string[];\n  /** Flags that are implied when this flag is set */\n  implies?: string[] | [string, unknown][];\n  // Note: transform is defined in child interfaces with specific types\n}\n\n/**\n * Boolean flag schema\n */\nexport interface BooleanFlagSchema extends BaseFlagSchema<'boolean'> {\n  type: 'boolean';\n  default?: boolean;\n  /** Transform function to apply to the value */\n  transform?: (value: boolean) => boolean | Promise<boolean>;\n}\n\n/**\n * String flag schema\n */\nexport interface StringFlagSchema extends BaseFlagSchema<'string'> {\n  type: 'string';\n  default?: string;\n  /** Allowed values (enum) */\n  choices?: readonly string[];\n  /** Regex pattern for validation */\n  pattern?: RegExp;\n  /** Minimum string length */\n  minLength?: number;\n  /** Maximum string length */\n  maxLength?: number;\n  /** Custom validation function */\n  validate?: (value: string) => true | string | Promise<true | string>;\n  /** Transform function to apply to the value */\n  transform?: (value: string) => string | Promise<string>;\n}\n\n/**\n * Number flag schema\n */\nexport interface NumberFlagSchema extends BaseFlagSchema<'number'> {\n  type: 'number';\n  default?: number;\n  /** Minimum value */\n  min?: number;\n  /** Maximum value */\n  max?: number;\n  /** Custom validation function */\n  validate?: (value: number) => true | string | Promise<true | string>;\n  /** Transform function to apply to the value */\n  transform?: (value: number) => number | Promise<number>;\n}\n\n/**\n * Array flag schema\n */\nexport interface ArrayFlagSchema extends BaseFlagSchema<'array'> {\n  type: 'array';\n  default?: unknown[];\n  /** Type of array items */\n  items?: 'string' | 'number' | 'boolean';\n  /** Minimum array length */\n  minLength?: number;\n  /** Maximum array length */\n  maxLength?: number;\n  /** Transform function to apply to the value */\n  transform?: (value: unknown[]) => unknown[] | Promise<unknown[]>;\n}\n\n/**\n * Union of all flag schema types\n */\nexport type FlagSchema =\n  | BooleanFlagSchema\n  | StringFlagSchema\n  | NumberFlagSchema\n  | ArrayFlagSchema;\n\n/**\n * Flag schema definition object (for defineFlags)\n */\nexport type FlagSchemaDefinition = Record<string, Omit<FlagSchema, 'name'>>;\n\n/**\n * Validation error\n */\nexport class FlagValidationError extends Error {\n  constructor(\n    public readonly flag: string,\n    message: string,\n    public readonly value?: unknown,\n    public readonly schema?: FlagSchemaDefinition,\n    public readonly commandName?: string\n  ) {\n    super(message);\n    this.name = 'FlagValidationError';\n  }\n}\n\n/**\n * Validation result\n */\nexport interface ValidationResult<T = Record<string, unknown>> {\n  success: boolean;\n  data?: T;\n  errors?: Array<{\n    flag: string;\n    message: string;\n    value?: unknown;\n  }>;\n}\n\n/**\n * Safe validation result (doesn't throw)\n */\nexport interface SafeValidationResult<T = Record<string, unknown>> {\n  success: boolean;\n  data?: T;\n  errors: Array<{\n    flag: string;\n    message: string;\n    value?: unknown;\n  }>;\n}\n\n","/**\n * @module @kb-labs/shared-command-kit/flags/define\n * Define flag schemas with automatic type inference\n */\n\nimport type {\n  FlagSchemaDefinition,\n  BooleanFlagSchema,\n  StringFlagSchema,\n  NumberFlagSchema,\n  ArrayFlagSchema,\n} from './types';\n\n/**\n * Flag schema with type inference\n */\nexport interface FlagSchemaWithInfer<T extends FlagSchemaDefinition> {\n  /** Original schema definition */\n  readonly schema: T;\n  /** Infer TypeScript type from schema */\n  infer: InferFlags<T>;\n}\n\n/**\n * Infer TypeScript type from flag schema definition\n */\nexport type InferFlags<T extends FlagSchemaDefinition> = {\n  [K in keyof T]: T[K] extends BooleanFlagSchema\n    ? T[K]['default'] extends boolean\n      ? boolean\n      : T[K]['required'] extends true\n        ? boolean\n        : boolean | undefined\n    : T[K] extends StringFlagSchema\n      ? T[K]['choices'] extends readonly string[]\n        ? T[K]['required'] extends true\n          ? T[K]['choices'][number]\n          : T[K]['default'] extends string\n            ? T[K]['choices'][number]\n            : T[K]['choices'][number] | undefined\n        : T[K]['required'] extends true\n          ? string\n          : T[K]['default'] extends string\n            ? string\n            : string | undefined\n      : T[K] extends NumberFlagSchema\n        ? T[K]['required'] extends true\n          ? number\n          : T[K]['default'] extends number\n            ? number\n            : number | undefined\n        : T[K] extends ArrayFlagSchema\n          ? T[K]['items'] extends 'string'\n            ? string[]\n            : T[K]['items'] extends 'number'\n              ? number[]\n              : T[K]['items'] extends 'boolean'\n                ? boolean[]\n                : unknown[]\n          : unknown;\n};\n\n/**\n * Define a flag schema with automatic type inference\n *\n * @example\n * ```typescript\n * const schema = defineFlags({\n *   scope: {\n *     type: 'string',\n *     required: true,\n *     pattern: /^[@a-z0-9-/]+$/i,\n *   },\n *   'dry-run': {\n *     type: 'boolean',\n *     default: false,\n *   },\n * });\n *\n * type Flags = typeof schema.infer;\n * // Flags = { scope: string; 'dry-run': boolean }\n * ```\n */\nexport function defineFlags<T extends FlagSchemaDefinition>(\n  definition: T\n): FlagSchemaWithInfer<T> {\n  return {\n    schema: definition,\n    infer: {} as InferFlags<T>,\n  };\n}\n\n","/**\n * @module @kb-labs/shared-command-kit/flags/validate\n * Validate flags against schema\n */\n\nimport {\n  FlagValidationError,\n  type FlagSchema,\n  type FlagSchemaDefinition,\n  type SafeValidationResult,\n} from './types';\nimport type { InferFlags } from './define';\n\n/**\n * Parse and coerce flag value based on type\n */\nfunction coerceValue(value: unknown, type: FlagSchema['type']): unknown {\n  if (value === undefined || value === null) {\n    return value;\n  }\n\n  switch (type) {\n    case 'boolean':\n      if (typeof value === 'boolean') {\n        return value;\n      }\n      if (typeof value === 'string') {\n        const lower = value.toLowerCase().trim();\n        if (lower === 'true' || lower === '1' || lower === 'yes') {\n          return true;\n        }\n        if (lower === 'false' || lower === '0' || lower === 'no' || lower === '') {\n          return false;\n        }\n      }\n      return Boolean(value);\n\n    case 'number':\n      if (typeof value === 'number') {\n        return value;\n      }\n      if (typeof value === 'string') {\n        const parsed = Number(value);\n        if (!Number.isNaN(parsed) && Number.isFinite(parsed)) {\n          return parsed;\n        }\n      }\n      return Number(value);\n\n    case 'array':\n      if (Array.isArray(value)) {\n        return value;\n      }\n      if (typeof value === 'string') {\n        return value.split(',').map((item) => item.trim());\n      }\n      return [value];\n\n    case 'string':\n      return String(value);\n\n    default:\n      return value;\n  }\n}\n\n/**\n * Validate a single flag value against its schema\n */\nasync function validateFlag(\n  flagName: string,\n  value: unknown,\n  schema: FlagSchema\n): Promise<true | string> {\n  const { type, required } = schema;\n  \n  // Type-specific properties (using type guards)\n  const choices = 'choices' in schema ? schema.choices : undefined;\n  const pattern = 'pattern' in schema ? schema.pattern : undefined;\n  const min = 'min' in schema ? schema.min : undefined;\n  const max = 'max' in schema ? schema.max : undefined;\n  const validate = 'validate' in schema ? schema.validate : undefined;\n  const minLength = 'minLength' in schema ? schema.minLength : undefined;\n  const maxLength = 'maxLength' in schema ? schema.maxLength : undefined;\n  const items = 'items' in schema ? schema.items : undefined;\n  const transform = 'transform' in schema ? schema.transform : undefined;\n\n  // Check required\n  if (required && (value === undefined || value === null || value === '')) {\n    return `Flag --${flagName} is required`;\n  }\n\n  // Skip validation if value is undefined and not required\n  if (value === undefined || value === null) {\n    return true;\n  }\n\n  // Coerce value to correct type\n  const coerced = coerceValue(value, type);\n\n  // Type-specific validation\n  switch (type) {\n    case 'boolean':\n      if (typeof coerced !== 'boolean') {\n        return `Flag --${flagName} must be a boolean`;\n      }\n      break;\n\n    case 'string':\n      if (typeof coerced !== 'string') {\n        return `Flag --${flagName} must be a string`;\n      }\n      if (minLength !== undefined && coerced.length < minLength) {\n        return `Flag --${flagName} must be at least ${minLength} characters long`;\n      }\n      if (maxLength !== undefined && coerced.length > maxLength) {\n        return `Flag --${flagName} must be at most ${maxLength} characters long`;\n      }\n      if (choices && !choices.includes(coerced)) {\n        return `Flag --${flagName} must be one of: ${choices.join(', ')} (got: ${coerced})`;\n      }\n      if (pattern && !pattern.test(coerced)) {\n        return `Flag --${flagName} must match pattern ${pattern.toString()}`;\n      }\n      if (validate) {\n        const stringValidate = validate as (value: string) => true | string | Promise<true | string>;\n        const result = await stringValidate(coerced as string);\n        if (result !== true) {\n          return result;\n        }\n      }\n      break;\n\n    case 'number':\n      if (typeof coerced !== 'number' || !Number.isFinite(coerced)) {\n        return `Flag --${flagName} must be a number`;\n      }\n      if (min !== undefined && coerced < min) {\n        return `Flag --${flagName} must be >= ${min} (got: ${coerced})`;\n      }\n      if (max !== undefined && coerced > max) {\n        return `Flag --${flagName} must be <= ${max} (got: ${coerced})`;\n      }\n      if (validate) {\n        const numberValidate = validate as (value: number) => true | string | Promise<true | string>;\n        const result = await numberValidate(coerced as number);\n        if (result !== true) {\n          return result;\n        }\n      }\n      break;\n\n    case 'array':\n      if (!Array.isArray(coerced)) {\n        return `Flag --${flagName} must be an array`;\n      }\n      if (minLength !== undefined && coerced.length < minLength) {\n        return `Flag --${flagName} must have at least ${minLength} items`;\n      }\n      if (maxLength !== undefined && coerced.length > maxLength) {\n        return `Flag --${flagName} must have at most ${maxLength} items`;\n      }\n      if (items) {\n        for (let i = 0; i < coerced.length; i++) {\n          const item = coerced[i];\n          if (items === 'string' && typeof item !== 'string') {\n            return `Flag --${flagName}[${i}] must be a string`;\n          }\n          if (items === 'number' && typeof item !== 'number') {\n            return `Flag --${flagName}[${i}] must be a number`;\n          }\n          if (items === 'boolean' && typeof item !== 'boolean') {\n            return `Flag --${flagName}[${i}] must be a boolean`;\n          }\n        }\n      }\n      break;\n  }\n\n  return true;\n}\n\n/**\n * Validate flags against schema and return typed result\n *\n * @throws {FlagValidationError} If validation fails and safe mode is not used\n */\nexport async function validateFlags<T extends FlagSchemaDefinition>(\n  rawFlags: Record<string, unknown>,\n  schemaDefinition: { schema: T } | T\n): Promise<InferFlags<T>> {\n  const schema = 'schema' in schemaDefinition ? schemaDefinition.schema : schemaDefinition;\n  const errors: Array<{ flag: string; message: string; value?: unknown }> = [];\n  const result: Record<string, unknown> = {};\n  const flagValues: Record<string, unknown> = { ...rawFlags };\n\n  // First pass: apply implies\n  for (const [flagName, flagSchema] of Object.entries(schema)) {\n    const value = flagValues[flagName];\n    if (value !== undefined && value !== null && value !== false && value !== '') {\n      const implies = flagSchema.implies;\n      if (implies) {\n        for (const implied of implies) {\n          if (Array.isArray(implied) && implied.length === 2) {\n            // [flagName, value] format\n            const [impliedFlag, impliedValue] = implied;\n            if (flagValues[impliedFlag] === undefined) {\n              flagValues[impliedFlag] = impliedValue;\n            }\n          } else if (typeof implied === 'string') {\n            // Just flag name - set to true\n            if (flagValues[implied] === undefined) {\n              flagValues[implied] = true;\n            }\n          }\n        }\n      }\n    }\n  }\n\n  // Second pass: validate each flag\n  for (const [flagName, flagSchema] of Object.entries(schema)) {\n    const value = flagValues[flagName];\n    const schemaWithName: FlagSchema = { ...flagSchema, name: flagName };\n\n    // Check conflicts\n    const conflicts = flagSchema.conflicts;\n    if (conflicts && value !== undefined && value !== null && value !== false && value !== '') {\n      for (const conflictingFlag of conflicts) {\n        const conflictingValue = flagValues[conflictingFlag];\n        if (conflictingValue !== undefined && conflictingValue !== null && conflictingValue !== false && conflictingValue !== '') {\n          errors.push({\n            flag: flagName,\n            message: `Flag --${flagName} conflicts with --${conflictingFlag}`,\n            value,\n          });\n          break;\n        }\n      }\n      if (errors.some(e => e.flag === flagName)) {\n        continue;\n      }\n    }\n\n    // Check dependsOn\n    const dependsOn = flagSchema.dependsOn;\n    if (dependsOn && value !== undefined && value !== null && value !== '') {\n      for (const dependency of dependsOn) {\n        const dependencyValue = flagValues[dependency];\n        if (dependencyValue === undefined || dependencyValue === null || dependencyValue === '') {\n          errors.push({\n            flag: flagName,\n            message: `Flag --${flagName} depends on --${dependency}`,\n            value,\n          });\n          break;\n        }\n      }\n      if (errors.some(e => e.flag === flagName)) {\n        continue;\n      }\n    }\n\n    // Check required\n    if (flagSchema.required && (value === undefined || value === null || value === '')) {\n      errors.push({\n        flag: flagName,\n        message: `Flag --${flagName} is required`,\n        value,\n      });\n      continue;\n    }\n\n    // Apply default if value is missing\n    const finalValue = value !== undefined ? value : flagSchema.default;\n\n    // Skip validation if value is undefined and not required\n    if (finalValue === undefined && !flagSchema.required) {\n      continue;\n    }\n\n    // Validate flag\n    const validationResult = await validateFlag(flagName, finalValue, schemaWithName);\n    if (validationResult !== true) {\n      errors.push({\n        flag: flagName,\n        message: validationResult,\n        value: finalValue,\n      });\n      continue;\n    }\n\n    // Apply transform if present\n    let transformedValue = coerceValue(finalValue, flagSchema.type);\n    const transform = flagSchema.transform;\n    if (transform) {\n      transformedValue = await transform(transformedValue);\n    }\n\n    // Store value\n    result[flagName] = transformedValue;\n  }\n\n  // Check for unknown flags (optional - could be enabled via option)\n  // for (const flagName of Object.keys(rawFlags)) {\n  //   if (!(flagName in schema)) {\n  //     errors.push({\n  //       flag: flagName,\n  //       message: `Unknown flag: --${flagName}`,\n  //       value: rawFlags[flagName],\n  //     });\n  //   }\n  // }\n\n  if (errors.length > 0) {\n    const firstError = errors[0]!;\n    throw new FlagValidationError(\n      firstError.flag,\n      firstError.message,\n      firstError.value,\n      schema as FlagSchemaDefinition // Pass schema for usage generation\n    );\n  }\n\n  return result as InferFlags<T>;\n}\n\n/**\n * Safe version of validateFlags that doesn't throw\n */\nexport async function validateFlagsSafe<T extends FlagSchemaDefinition>(\n  rawFlags: Record<string, unknown>,\n  schemaDefinition: { schema: T } | T\n): Promise<SafeValidationResult<InferFlags<T>>> {\n  try {\n    const data = await validateFlags(rawFlags, schemaDefinition);\n    return {\n      success: true,\n      data,\n      errors: [],\n    };\n  } catch (error) {\n    if (error instanceof FlagValidationError) {\n      return {\n        success: false,\n        errors: [\n          {\n            flag: error.flag,\n            message: error.message,\n            value: error.value,\n          },\n        ],\n      };\n    }\n    throw error;\n  }\n}\n\n"]}