@kb-labs/shared-command-kit 2.94.0 → 2.98.0

package/dist/errors/index.js.map

@@ -1 +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  // eslint-disable-next-line @typescript-eslint/no-explicit-any\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 unknown[] = unknown[]> = {\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: Record<string, unknown> = {};\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: unknown[]) {\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: unknown[]\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 as { details?: Record<string, unknown> }).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] as { details?: Record<string, unknown> }).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"]}
+{"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 search --text <query>\n * Hint: Try kb mind search --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 search', schema, 'text')\n * // Returns: 'kb mind search --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  // eslint-disable-next-line @typescript-eslint/no-explicit-any\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 unknown[] = unknown[]> = {\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: Record<string, unknown> = {};\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: unknown[]) {\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: unknown[]\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 as { details?: Record<string, unknown> }).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] as { details?: Record<string, unknown> }).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/helpers/index.d.ts

@@ -1,6 +1,6 @@
 import { platform } from '@kb-labs/core-runtime';
 export { PluginContextV3 } from '@kb-labs/plugin-contracts';
-import { ILogger, LLMTier, UseLLMOptions, ILLM, IEmbeddings, IVectorStore, IAnalytics, IStorage, ICache } from '@kb-labs/core-platform';
+import { ILogger, LLMTier, UseLLMOptions, ILLM, IEmbeddings, IVectorStore, IAnalytics, IStorage, ICache, IDocumentDatabase, IKVStore, INotifier } from '@kb-labs/core-platform';
 export { LLMTier, UseLLMOptions } from '@kb-labs/core-platform';
 
 /**
@@ -613,6 +613,151 @@ declare function useCache(): ICache | undefined;
  */
 declare function isCacheAvailable(): boolean;
 
+/**
+ * @module @kb-labs/shared-command-kit/helpers/use-document-database
+ *
+ * Hook for the per-plugin document database — structured persistence with
+ * filters, transactions, and indexed collections.
+ *
+ * The adapter is resolved from the current `usePlatform()` context, so the
+ * instance you receive is already wrapped with this plugin's permissions:
+ * collection names are namespaced under `<pluginId>__<name>`, and any call
+ * to a collection the plugin didn't declare in
+ * `permissions.platform.database.document.owns` / `.access` rejects with
+ * `PermissionError`.
+ *
+ * @example
+ * ```typescript
+ * import { useDocumentDatabase } from '@kb-labs/shared-command-kit';
+ *
+ * interface Run extends BaseDocument {
+ *   status: 'queued' | 'running' | 'done';
+ *   startedAt: number;
+ * }
+ *
+ * async function handler() {
+ *   const docs = useDocumentDatabase();
+ *   if (!docs) {
+ *     throw new Error('Plugin needs documentDatabase configured');
+ *   }
+ *
+ *   await docs.ensureCollection('runs', {
+ *     indexes: [{ path: 'status' }],
+ *   });
+ *
+ *   const queued = await docs.find<Run>('runs', { status: { $eq: 'queued' } });
+ *   return queued;
+ * }
+ * ```
+ */
+
+/**
+ * Resolve the document database for the current execution.
+ *
+ * Returns `undefined` when no adapter is configured at all. When a plugin
+ * declared permissions but is missing the wiring (NoOp adapter on the
+ * platform side) you still get an instance — calls just throw on use.
+ *
+ * Always check before using:
+ *
+ * ```ts
+ * const docs = useDocumentDatabase();
+ * if (!docs) {
+ *   // The platform was started without a document database;
+ *   // either skip the feature or fail fast with a clear error.
+ *   return;
+ * }
+ * ```
+ */
+declare function useDocumentDatabase(): IDocumentDatabase | undefined;
+/**
+ * Cheap check for "is the document database available?". Returns true even
+ * for NoOp adapters configured by the platform — use this to gate optional
+ * features, not as a security check.
+ */
+declare function isDocumentDatabaseAvailable(): boolean;
+
+/**
+ * @module @kb-labs/shared-command-kit/helpers/use-kv-store
+ *
+ * Hook for the per-plugin durable key-value store.
+ *
+ * Unlike `useCache`, KV is the source of truth — entries persist until
+ * explicitly deleted or until their TTL expires. Use it for sessions,
+ * distributed locks, idempotency keys, counters — anything where losing
+ * the entry is a bug.
+ *
+ * Keys are namespaced under `<pluginId>:` transparently. Two plugins
+ * setting `"counter"` do not collide. `scan` only yields the calling
+ * plugin's own keys.
+ *
+ * @example
+ * ```typescript
+ * import { useKVStore } from '@kb-labs/shared-command-kit';
+ *
+ * async function withLock<T>(name: string, fn: () => Promise<T>): Promise<T> {
+ *   const kv = useKVStore();
+ *   if (!kv) throw new Error('KV store not configured');
+ *
+ *   const token = crypto.randomUUID();
+ *   const acquired = await kv.setIfNotExists(`lock:${name}`, token, { ttlMs: 30_000 });
+ *   if (!acquired) throw new Error('lock held');
+ *
+ *   try {
+ *     return await fn();
+ *   } finally {
+ *     // Release only if we still hold the token (cas guards against ttl-takeover).
+ *     await kv.cas(`lock:${name}`, token, null);
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Resolve the KV store for the current execution.
+ *
+ * Returns `undefined` only when no adapter is wired at all. A plugin
+ * that didn't declare `permissions.platform.database.kvStore` still gets
+ * an instance — every method throws `PermissionError` on use.
+ */
+declare function useKVStore(): IKVStore | undefined;
+/**
+ * Cheap check used to gate optional features. Note that it returns true
+ * even when the plugin lacks `permissions.platform.database.kvStore` —
+ * the runtime will replace the adapter with a deny stub in that case, so
+ * this check tells you "is the slot wired?", not "can I actually use it?".
+ */
+declare function isKVStoreAvailable(): boolean;
+
+/**
+ * @module @kb-labs/shared-command-kit/helpers/use-notifications
+ * Platform notifier access helper.
+ *
+ * @example
+ * ```typescript
+ * import { useNotifications } from '@kb-labs/shared-command-kit';
+ *
+ * async handler(ctx, argv, flags) {
+ *   const notifier = useNotifications();
+ *   await notifier?.notify({ title: 'Done', body: 'Workflow complete', severity: 'info' });
+ * }
+ * ```
+ */
+
+/**
+ * Access the platform notifier adapter.
+ * Returns undefined if the notifier adapter is not configured.
+ *
+ * @example
+ * ```typescript
+ * const notifier = useNotifications();
+ * if (notifier) {
+ *   await notifier.notify({ title: 'Alert', body: 'Something failed', severity: 'critical' });
+ * }
+ * ```
+ */
+declare function useNotifications(): INotifier | undefined;
+
 /**
  * @module @kb-labs/shared-command-kit/helpers/use-env
  *
@@ -639,4 +784,4 @@ declare function isCacheAvailable(): boolean;
  */
 declare function useEnv(key: string): string | undefined;
 
-export { getLLMTier, isCacheAvailable, isEmbeddingsAvailable, isLLMAvailable, isPlatformConfigured, isVectorStoreAvailable, trackAnalyticsEvent, useAnalytics, useCache, useConfig, useEmbeddings, useEnv, useLLM, useLogger, useLoggerWithContext, usePlatform, useStorage, useVectorStore };
+export { getLLMTier, isCacheAvailable, isDocumentDatabaseAvailable, isEmbeddingsAvailable, isKVStoreAvailable, isLLMAvailable, isPlatformConfigured, isVectorStoreAvailable, trackAnalyticsEvent, useAnalytics, useCache, useConfig, useDocumentDatabase, useEmbeddings, useEnv, useKVStore, useLLM, useLogger, useLoggerWithContext, useNotifications, usePlatform, useStorage, useVectorStore };

package/dist/helpers/index.js

@@ -52,12 +52,34 @@ async function useConfig(productId, profileId) {
   if (!effectiveProductId) {
     return void 0;
   }
+  const g = globalThis;
+  const rawConfig = g.__KB_EFFECTIVE_CONFIG__ ?? g.__KB_RAW_CONFIG__;
+  if (rawConfig) {
+    return selectProductSection(rawConfig, effectiveProductId, profileId);
+  }
   const { usePlatform: usePlatform2 } = await Promise.resolve().then(() => (init_use_platform(), use_platform_exports));
   const platform = usePlatform2();
-  if (!platform) {
-    return void 0;
+  if (platform?.config) {
+    return await platform.config.getConfig(effectiveProductId, profileId);
   }
-  return await platform.config.getConfig(effectiveProductId, profileId);
+  return void 0;
+}
+function selectProductSection(rawConfig, productId, profileId) {
+  const effectiveProfileId = profileId ?? process.env.KB_PROFILE ?? "default";
+  const profilesField = rawConfig.profiles;
+  if (Array.isArray(profilesField)) {
+    const profiles = profilesField;
+    const profile = profiles.find((p) => p.id === effectiveProfileId) ?? profiles[0];
+    if (profile?.products?.[productId] !== void 0) {
+      return profile.products[productId];
+    }
+  }
+  const legacyKeyMap = { mind: "knowledge" };
+  const legacyKey = legacyKeyMap[productId] ?? productId;
+  if (rawConfig[legacyKey] !== void 0) {
+    return rawConfig[legacyKey];
+  }
+  return void 0;
 }
 
 // src/helpers/use-logger.ts
@@ -271,6 +293,33 @@ function isCacheAvailable() {
   const cache = useCache();
   return !!cache;
 }
+
+// src/helpers/use-document-database.ts
+init_use_platform();
+function useDocumentDatabase() {
+  const platform = usePlatform();
+  return platform.documentDatabase;
+}
+function isDocumentDatabaseAvailable() {
+  return useDocumentDatabase() !== void 0;
+}
+
+// src/helpers/use-kv-store.ts
+init_use_platform();
+function useKVStore() {
+  const platform = usePlatform();
+  return platform.kvStore;
+}
+function isKVStoreAvailable() {
+  return useKVStore() !== void 0;
+}
+
+// src/helpers/use-notifications.ts
+init_use_platform();
+function useNotifications() {
+  const platform = usePlatform();
+  return platform.notifier;
+}
 function useEnv(key) {
   const runtime = runtimeContext.getStore();
   if (runtime?.env) {
@@ -279,6 +328,6 @@ function useEnv(key) {
   return process.env[key];
 }
 
-export { getLLMTier, isCacheAvailable, isEmbeddingsAvailable, isLLMAvailable, isPlatformConfigured, isVectorStoreAvailable, trackAnalyticsEvent, useAnalytics, useCache, useConfig, useEmbeddings, useEnv, useLLM, useLogger, useLoggerWithContext, usePlatform, useStorage, useVectorStore };
+export { getLLMTier, isCacheAvailable, isDocumentDatabaseAvailable, isEmbeddingsAvailable, isKVStoreAvailable, isLLMAvailable, isPlatformConfigured, isVectorStoreAvailable, trackAnalyticsEvent, useAnalytics, useCache, useConfig, useDocumentDatabase, useEmbeddings, useEnv, useKVStore, useLLM, useLogger, useLoggerWithContext, useNotifications, usePlatform, useStorage, useVectorStore };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/helpers/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/helpers/use-platform.ts","../../src/helpers/index.ts","../../src/helpers/use-config.ts","../../src/helpers/use-logger.ts","../../src/helpers/use-llm.ts","../../src/helpers/use-embeddings.ts","../../src/helpers/use-vector-store.ts","../../src/helpers/use-analytics.ts","../../src/helpers/use-storage.ts","../../src/helpers/use-cache.ts","../../src/helpers/use-env.ts"],"names":["globalPlatform","usePlatform","trace","optionsWithTrace"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @module @kb-labs/shared-command-kit/helpers/use-platform\n * Platform access hook with execution-scoped context.\n *\n * Uses AsyncLocalStorage to return the correct platform for the current\n * handler execution (governed, with correct permissions and proxy adapters).\n * Falls back to global singleton for code running outside handler context.\n *\n * @example\n * ```typescript\n * import { usePlatform } from '@kb-labs/shared-command-kit';\n *\n * // In any command handler — automatically gets the right platform\n * async handler(ctx, argv, flags) {\n *   const platform = usePlatform();\n *   const result = await platform.llm.complete('prompt');\n * }\n * ```\n */\n\nimport { platformContext } from '@kb-labs/plugin-contracts';\nimport { platform as globalPlatform } from '@kb-labs/core-runtime';\n\n/**\n * Access platform services for the current execution context.\n *\n * Priority:\n * 1. AsyncLocalStorage context (set by runInProcess) — per-execution, governed\n * 2. Global singleton fallback (core-runtime) — for code outside handler context\n *\n * @returns Platform services with correct adapters for current context\n */\nexport function usePlatform(): typeof globalPlatform {\n  return (platformContext.getStore() as typeof globalPlatform) ?? globalPlatform;\n}\n\n/**\n * Check if specific platform adapter is configured\n *\n * Useful for conditional logic based on available services.\n *\n * @param adapterName - Name of the adapter to check\n * @returns true if adapter is configured and available\n *\n * @example\n * ```typescript\n * if (isPlatformConfigured('llm')) {\n *   // Use LLM-powered feature\n * } else {\n *   // Use deterministic fallback\n * }\n * ```\n */\nexport function isPlatformConfigured(adapterName: keyof typeof globalPlatform): boolean {\n  const platform = usePlatform();\n\n  // Check if adapter exists and is not a noop/fallback\n  const adapter = platform[adapterName];\n\n  if (!adapter) {\n    return false;\n  }\n\n  // For adapters with hasAdapter method (like platform itself)\n  if ('hasAdapter' in platform && typeof platform.hasAdapter === 'function') {\n    return platform.hasAdapter(adapterName as string);\n  }\n\n  // Fallback: check if adapter is not noop\n  // Noop adapters usually have a specific constructor name or are simple objects\n  if (typeof adapter === 'object' && adapter.constructor) {\n    const constructorName = adapter.constructor.name;\n    return !constructorName.toLowerCase().includes('noop') &&\n           !constructorName.toLowerCase().includes('fallback');\n  }\n\n  return true;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers\n * Global platform access helpers\n *\n * Provides clean, type-safe access to platform services without context drilling.\n * Similar to React hooks pattern, but for KB Labs platform.\n *\n * @example\n * ```typescript\n * import { useLLM, useLogger, useAnalytics } from '@kb-labs/shared-command-kit/helpers';\n *\n * async handler(ctx, argv, flags) {\n *   const logger = useLogger();\n *   const llm = useLLM();\n *\n *   await logger.info('Processing started');\n *\n *   if (llm) {\n *     const result = await llm.complete('prompt');\n *     await logger.info('LLM result', { length: result.content.length });\n *   }\n * }\n * ```\n */\n\n// Platform singleton\nexport { usePlatform, isPlatformConfigured } from './use-platform';\n\n// Context types and helpers\nexport type { PluginContextV3 } from './context';\n\n// Config access\nexport { useConfig } from './use-config';\n\n// Core services\nexport { useLogger, useLoggerWithContext } from './use-logger.js';\nexport { useLLM, isLLMAvailable, getLLMTier, type LLMTier, type UseLLMOptions } from './use-llm.js';\nexport { useEmbeddings, isEmbeddingsAvailable } from './use-embeddings.js';\nexport { useVectorStore, isVectorStoreAvailable } from './use-vector-store.js';\nexport { useAnalytics, trackAnalyticsEvent } from './use-analytics.js';\nexport { useStorage } from './use-storage.js';\nexport { useCache, isCacheAvailable } from './use-cache.js';\n\n// Runtime shims\nexport { useEnv } from './use-env.js';\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-config\n * Global config access helper\n *\n * Provides clean access to product-specific configuration without context drilling.\n * Similar to React hooks pattern, but for KB Labs config.\n *\n * @example\n * ```typescript\n * import { useConfig } from '@kb-labs/shared-command-kit';\n *\n * // In any command handler\n * async handler(ctx, argv, flags) {\n *   const config = await useConfig('mind');\n *\n *   if (config) {\n *     const scopes = config.scopes;\n *     // Use config...\n *   }\n * }\n * ```\n */\n\n/**\n * Access product-specific configuration from kb.config.json\n *\n * Returns ONLY the config for the specified product and profile.\n * Uses platform.config adapter (works across parent/child processes via IPC).\n * Supports both Profiles v2 and legacy config structures.\n *\n * **Security:** This function returns ONLY the product-specific config,\n * not the entire kb.config.json. This prevents cross-product config access.\n *\n * **Auto-detection:** If productId is not provided, it's automatically inferred\n * from the plugin's manifest.configSection field (passed via execution context).\n *\n * **Profiles v2 structure:**\n * ```json\n * {\n *   \"profiles\": [\n *     {\n *       \"id\": \"default\",\n *       \"products\": {\n *         \"mind\": { \"scopes\": [...] },\n *         \"workflow\": { \"maxConcurrency\": 10 }\n *       }\n *     }\n *   ]\n * }\n * ```\n *\n * **Legacy structure:**\n * ```json\n * {\n *   \"knowledge\": { \"scopes\": [...] },  // for \"mind\" product\n *   \"workflow\": { \"maxConcurrency\": 10 }\n * }\n * ```\n *\n * @param productId - Product identifier (e.g., 'mind', 'workflow', 'plugins'). Optional - auto-detected from context.\n * @param profileId - Profile identifier (defaults to 'default' or KB_PROFILE env var)\n * @returns Promise resolving to product-specific config or undefined\n *\n * @example\n * ```typescript\n * // Auto-detect from context (recommended)\n * const config = await useConfig();\n *\n * // Explicit product ID\n * const mindConfig = await useConfig('mind');\n * if (mindConfig?.scopes) {\n *   // Use scopes\n * }\n *\n * // With explicit profile\n * const workflowConfig = await useConfig('workflow', 'production');\n * ```\n */\nexport async function useConfig<T = any>(productId?: string, profileId?: string): Promise<T | undefined> {\n  // Auto-detect productId from manifest.configSection if not provided\n  let effectiveProductId = productId;\n  if (!effectiveProductId) {\n    effectiveProductId = (globalThis as typeof globalThis & { __KB_CONFIG_SECTION__?: string }).__KB_CONFIG_SECTION__;\n  }\n\n  if (!effectiveProductId) {\n    return undefined;\n  }\n\n  const { usePlatform } = await import('./use-platform.js');\n  const platform = usePlatform();\n\n  if (!platform) {\n    return undefined;\n  }\n\n  // Returns ONLY the product-specific config, not the entire kb.config.json\n  return await platform.config.getConfig(effectiveProductId, profileId) as T | undefined;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-logger\n * Global logger access helper\n *\n * Provides clean access to structured logging without context drilling.\n *\n * @example\n * ```typescript\n * import { useLogger } from '@kb-labs/shared-command-kit';\n *\n * async handler(ctx, argv, flags) {\n *   const logger = useLogger();\n *\n *   await logger.info('Processing started');\n *   await logger.debug('Details', { userId: 123 });\n *   await logger.error('Failed', { error: err });\n * }\n * ```\n */\n\nimport { usePlatform } from './use-platform';\nimport type { ILogger } from '@kb-labs/core-platform';\n\n/**\n * Access global logger\n *\n * Returns the platform logger with structured logging capabilities.\n * Supports child loggers with additional context.\n *\n * **Methods:**\n * - `logger.trace(message, meta?)` - Trace-level logs (most verbose)\n * - `logger.debug(message, meta?)` - Debug-level logs\n * - `logger.info(message, meta?)` - Info-level logs\n * - `logger.warn(message, meta?)` - Warning-level logs\n * - `logger.error(message, meta?)` - Error-level logs\n * - `logger.child(meta)` - Create child logger with additional context\n *\n * @returns Platform logger instance\n *\n * @example\n * ```typescript\n * const logger = useLogger();\n *\n * await logger.info('Task started', { taskId: '123' });\n * await logger.error('Task failed', { taskId: '123', error: err.message });\n *\n * // Child logger with persistent context\n * const taskLogger = logger.child({ taskId: '123', userId: 'user-1' });\n * await taskLogger.info('Step 1 completed');\n * await taskLogger.info('Step 2 completed');\n * ```\n */\nexport function useLogger(): ILogger {\n  const platform = usePlatform();\n  return platform.logger;\n}\n\n/**\n * Create child logger with additional context\n *\n * Useful for scoped logging within a specific operation.\n *\n * @param context - Additional context to attach to all log entries\n * @returns Child logger with persistent context\n *\n * @example\n * ```typescript\n * const logger = useLoggerWithContext({ operation: 'release', version: '1.0.0' });\n *\n * await logger.info('Started');  // Automatically includes operation + version\n * await logger.info('Completed');\n * ```\n */\nexport function useLoggerWithContext(context: Record<string, unknown>): ILogger {\n  const logger = useLogger();\n  return logger.child(context);\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-llm\n * Global LLM access helper with tier-based model selection.\n *\n * Provides clean access to LLM with adaptive tier routing.\n * Plugins specify tiers (small/medium/large), platform resolves to actual models.\n *\n * @example\n * ```typescript\n * import { useLLM } from '@kb-labs/shared-command-kit';\n *\n * async handler(ctx, argv, flags) {\n *   // Simple usage (uses configured default tier)\n *   const llm = useLLM();\n *\n *   // Request specific tier (platform adapts if needed)\n *   const llm = useLLM({ tier: 'small' });   // Simple tasks\n *   const llm = useLLM({ tier: 'large' });   // Complex tasks\n *\n *   // Request capabilities\n *   const llm = useLLM({ tier: 'medium', capabilities: ['coding'] });\n *\n *   if (llm) {\n *     const result = await llm.complete('Explain this code');\n *     console.log(result.content);\n *   }\n * }\n * ```\n */\n\nimport { usePlatform } from './use-platform.js';\nimport type {\n  ILLM,\n  LLMTier,\n  LLMOptions,\n  LLMResponse,\n  LLMMessage,\n  LLMToolCallOptions,\n  LLMToolCallResponse,\n  UseLLMOptions,\n  ILLMRouter,\n  LLMAdapterBinding,\n  LLMExecutionPolicy,\n  LLMProtocolCapabilities,\n  LLMCacheDecisionTrace,\n} from '@kb-labs/core-platform';\n\n/**\n * Access global LLM adapter with tier-based selection.\n *\n * Platform automatically adapts to available models:\n * - If plugin requests 'small' but 'medium' configured → uses 'medium' (escalation)\n * - If plugin requests 'large' but 'medium' configured → uses 'medium' with warning (degradation)\n *\n * **Tiers are user-defined slots:**\n * - `small`  - Plugin says: \"This task is simple\"\n * - `medium` - Plugin says: \"Standard task\"\n * - `large`  - Plugin says: \"Complex task, need maximum quality\"\n *\n * User decides what model maps to each tier in their config.\n *\n * @param options - Optional tier and capability requirements\n * @returns LLM adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * // Simple usage (uses configured default)\n * const llm = useLLM();\n *\n * // Request specific tier\n * const llm = useLLM({ tier: 'small' });   // Simple tasks\n * const llm = useLLM({ tier: 'large' });   // Complex tasks\n *\n * // Request capabilities\n * const llm = useLLM({ tier: 'medium', capabilities: ['coding'] });\n * const llm = useLLM({ capabilities: ['vision'] });\n *\n * if (llm) {\n *   const result = await llm.complete('Generate commit message');\n *   console.log(result.content);\n * }\n * ```\n */\nexport function useLLM(options?: UseLLMOptions): ILLM | undefined {\n  const platform = usePlatform();\n  const llm = platform.llm;\n\n  if (!llm) {\n    return undefined;\n  }\n\n  // If router and options given → return immutable LazyBoundLLM (no state mutation)\n  if (options && isLLMRouter(llm)) {\n    return new LazyBoundLLM(llm, options);\n  }\n\n  return llm;\n}\n\n/**\n * Lazy adapter binding that resolves tier on first use.\n * Immutable — does NOT mutate the global LLMRouter state.\n * This fixes the race condition where useLLM({ tier: 'large' }) was immediately\n * overwritten by useLLM({ tier: 'small' }) from SmartSummarizer.\n */\nclass LazyBoundLLM implements ILLM {\n  private _resolved: Promise<LLMAdapterBinding> | null = null;\n\n  constructor(\n    private readonly router: ILLM & ILLMRouter,\n    private readonly options: UseLLMOptions,\n  ) {}\n\n  private resolve(): Promise<LLMAdapterBinding> {\n    if (!this._resolved) {\n      this._resolved = this.router.resolveAdapter(this.options);\n    }\n    return this._resolved;\n  }\n\n  private mergeExecutionPolicy(callOptions?: LLMOptions): LLMExecutionPolicy | undefined {\n    const globalPolicy = this.options.execution;\n    const localPolicy = callOptions?.execution;\n    if (!globalPolicy && !localPolicy) {\n      return undefined;\n    }\n    return {\n      ...globalPolicy,\n      ...localPolicy,\n      cache: { ...globalPolicy?.cache, ...localPolicy?.cache },\n      stream: { ...globalPolicy?.stream, ...localPolicy?.stream },\n    };\n  }\n\n  private async resolveProtocolCapabilities(adapter: ILLM): Promise<LLMProtocolCapabilities> {\n    if (!adapter.getProtocolCapabilities) {\n      return {\n        cache: { supported: false },\n        stream: { supported: true },\n      };\n    }\n    return adapter.getProtocolCapabilities();\n  }\n\n  private enforceCachePolicy(caps: LLMProtocolCapabilities, execution?: LLMExecutionPolicy): void {\n    if (execution?.cache?.mode === 'require' && !caps.cache.supported) {\n      throw new Error('CACHE_NOT_SUPPORTED: adapter does not support required cache policy');\n    }\n  }\n\n  private buildDecisionTrace(\n    caps: LLMProtocolCapabilities,\n    execution: LLMExecutionPolicy | undefined,\n    streamAppliedMode: 'prefer' | 'require' | 'off',\n    streamFallback?: 'complete',\n    reason?: string,\n  ): LLMCacheDecisionTrace {\n    const requestedCacheMode = execution?.cache?.mode ?? 'prefer';\n    const requestedStreamMode = execution?.stream?.mode ?? 'prefer';\n\n    return {\n      cacheRequestedMode: requestedCacheMode,\n      cacheSupported: caps.cache.supported,\n      cacheAppliedMode:\n        requestedCacheMode === 'require' || requestedCacheMode === 'bypass'\n          ? requestedCacheMode\n          : caps.cache.supported\n            ? 'prefer'\n            : 'bypass',\n      streamRequestedMode: requestedStreamMode,\n      streamSupported: caps.stream.supported,\n      streamAppliedMode,\n      streamFallback,\n      reason,\n    };\n  }\n\n  private withDecisionMetadata(\n    options: LLMOptions | undefined,\n    trace: LLMCacheDecisionTrace,\n  ): LLMOptions | undefined {\n    if (!options) {\n      return { metadata: { cacheDecisionTrace: trace } };\n    }\n\n    return {\n      ...options,\n      metadata: {\n        ...options.metadata,\n        cacheDecisionTrace: trace,\n      },\n    };\n  }\n\n  async complete(prompt: string, options?: LLMOptions): Promise<LLMResponse> {\n    const { adapter, model } = await this.resolve();\n    const execution = this.mergeExecutionPolicy(options);\n    const caps = await this.resolveProtocolCapabilities(adapter);\n    this.enforceCachePolicy(caps, execution);\n    const trace = this.buildDecisionTrace(caps, execution, 'off');\n    const optionsWithTrace = this.withDecisionMetadata(options, trace);\n    return adapter.complete(prompt, { ...optionsWithTrace, model, execution });\n  }\n\n  async *stream(prompt: string, options?: LLMOptions): AsyncIterable<string> {\n    const { adapter, model } = await this.resolve();\n    const execution = this.mergeExecutionPolicy(options);\n    const caps = await this.resolveProtocolCapabilities(adapter);\n    this.enforceCachePolicy(caps, execution);\n\n    const streamMode = execution?.stream?.mode ?? 'prefer';\n    const canStream = caps.stream.supported;\n    const allowFallback = execution?.stream?.fallbackToComplete ?? true;\n\n    if (streamMode === 'off' || (!canStream && streamMode === 'prefer' && allowFallback)) {\n      const fallbackReason =\n        streamMode === 'off'\n          ? 'STREAM_OFF'\n          : 'STREAM_UNSUPPORTED_FALLBACK_TO_COMPLETE';\n      const trace = this.buildDecisionTrace(caps, execution, 'off', 'complete', fallbackReason);\n      const optionsWithTrace = this.withDecisionMetadata(options, trace);\n      const response = await adapter.complete(prompt, { ...optionsWithTrace, model, execution });\n      if (response.content) {\n        yield response.content;\n      }\n      return;\n    }\n\n    if (!canStream && streamMode === 'require') {\n      throw new Error('STREAM_NOT_SUPPORTED: adapter does not support required streaming');\n    }\n\n    const trace = this.buildDecisionTrace(caps, execution, streamMode);\n    const optionsWithTrace = this.withDecisionMetadata(options, trace);\n    yield* adapter.stream(prompt, { ...optionsWithTrace, model, execution });\n  }\n\n  async chatWithTools(\n    messages: LLMMessage[],\n    options: LLMToolCallOptions,\n  ): Promise<LLMToolCallResponse> {\n    const { adapter, model, tier } = await this.resolve();\n    const execution = this.mergeExecutionPolicy(options);\n    const caps = await this.resolveProtocolCapabilities(adapter);\n    this.enforceCachePolicy(caps, execution);\n    if (!adapter.chatWithTools) {\n      throw new Error('Current adapter does not support chatWithTools');\n    }\n    const trace = this.buildDecisionTrace(caps, execution, 'off');\n    const optionsWithTrace = this.withDecisionMetadata(options, trace) as LLMToolCallOptions;\n    return adapter.chatWithTools(messages, {\n      ...optionsWithTrace,\n      model,\n      execution,\n      metadata: { ...optionsWithTrace.metadata, tier },\n    });\n  }\n}\n\n/**\n * Check if LLM is available.\n *\n * Useful for conditional logic (LLM-powered vs deterministic fallback).\n *\n * @returns true if LLM is configured and ready\n *\n * @example\n * ```typescript\n * if (isLLMAvailable()) {\n *   const summary = await generateWithLLM(data);\n * } else {\n *   const summary = generateDeterministic(data);\n * }\n * ```\n */\nexport function isLLMAvailable(): boolean {\n  const llm = useLLM();\n  return !!llm;\n}\n\n/**\n * Get configured LLM tier.\n *\n * Useful for diagnostics and logging.\n *\n * @returns Configured tier or undefined if LLM not available/not a router\n *\n * @example\n * ```typescript\n * const tier = getLLMTier();\n * console.log(`Using LLM tier: ${tier ?? 'default'}`);\n * ```\n */\nexport function getLLMTier(): LLMTier | undefined {\n  const platform = usePlatform();\n  const llm = platform.llm;\n\n  if (llm && isLLMRouter(llm)) {\n    return llm.getConfiguredTier();\n  }\n\n  return undefined;\n}\n\n/**\n * Type guard for ILLMRouter.\n */\nfunction isLLMRouter(llm: ILLM): llm is ILLM & ILLMRouter {\n  return (\n    typeof (llm as unknown as ILLMRouter).getConfiguredTier === 'function' &&\n    typeof (llm as unknown as ILLMRouter).resolve === 'function'\n  );\n}\n\n// Re-export types for convenience\nexport type { LLMTier, UseLLMOptions } from '@kb-labs/core-platform';\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-embeddings\n * Global Embeddings access helper\n */\n\nimport { usePlatform } from './use-platform';\nimport type { IEmbeddings } from '@kb-labs/core-platform';\n\n/**\n * Access global Embeddings adapter\n *\n * Returns the platform embeddings adapter (OpenAI, etc.).\n * Returns undefined if embeddings is not configured (graceful degradation).\n *\n * @returns Embeddings adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * const embeddings = useEmbeddings();\n *\n * if (embeddings) {\n *   const vector = await embeddings.embed('Hello, world!');\n *   console.log(vector.length); // e.g., 1536 for OpenAI\n * }\n * ```\n */\nexport function useEmbeddings(): IEmbeddings | undefined {\n  const platform = usePlatform();\n  return platform.embeddings;\n}\n\n/**\n * Check if Embeddings is available\n *\n * @returns true if embeddings is configured and ready\n *\n * @example\n * ```typescript\n * if (isEmbeddingsAvailable()) {\n *   const vector = await embeddings.embed(text);\n * } else {\n *   // Use deterministic fallback\n * }\n * ```\n */\nexport function isEmbeddingsAvailable(): boolean {\n  const embeddings = useEmbeddings();\n  return !!embeddings;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-vector-store\n * Global VectorStore access helper\n */\n\nimport { usePlatform } from './use-platform';\nimport type { IVectorStore } from '@kb-labs/core-platform';\n\n/**\n * Access global VectorStore adapter\n *\n * Returns the platform vector store adapter (Qdrant, local, etc.).\n * Returns undefined if vectorStore is not configured (graceful degradation).\n *\n * @returns VectorStore adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * const vectorStore = useVectorStore();\n *\n * if (vectorStore) {\n *   await vectorStore.upsert([{ id: '1', vector: [0.1, 0.2], metadata: {} }]);\n *   const results = await vectorStore.search([0.1, 0.2], 10);\n * }\n * ```\n */\nexport function useVectorStore(): IVectorStore | undefined {\n  const platform = usePlatform();\n  return platform.vectorStore;\n}\n\n/**\n * Check if VectorStore is available\n *\n * @returns true if vectorStore is configured and ready\n *\n * @example\n * ```typescript\n * if (isVectorStoreAvailable()) {\n *   await vectorStore.upsert(records);\n * } else {\n *   // Use local fallback\n * }\n * ```\n */\nexport function isVectorStoreAvailable(): boolean {\n  const vectorStore = useVectorStore();\n  return !!vectorStore;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-analytics\n * Global analytics access helper\n *\n * Provides clean access to analytics/telemetry without context drilling.\n *\n * @example\n * ```typescript\n * import { useAnalytics } from '@kb-labs/shared-command-kit';\n *\n * async handler(ctx, argv, flags) {\n *   const analytics = useAnalytics();\n *\n *   if (analytics) {\n *     await analytics.track('release_started', { version: '1.0.0' });\n *     analytics.metric('release_duration_ms', 1234);\n *   }\n * }\n * ```\n */\n\nimport { usePlatform } from './use-platform';\nimport type { IAnalytics } from '@kb-labs/core-platform';\n\n/**\n * Access global analytics adapter\n *\n * Returns the platform analytics adapter for tracking events and metrics.\n * Returns undefined if analytics is not configured (graceful degradation).\n *\n * **Methods:**\n * - `analytics.track(event, properties?)` - Track events\n * - `analytics.metric(name, value, tags?)` - Record metrics\n *\n * **Always check availability:**\n * ```typescript\n * const analytics = useAnalytics();\n * if (analytics) {\n *   await analytics.track('event');\n * }\n * ```\n *\n * @returns Analytics adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * const analytics = useAnalytics();\n *\n * if (analytics) {\n *   await analytics.track('command_executed', {\n *     command: 'release:run',\n *     duration_ms: 1234,\n *     success: true,\n *   });\n *\n *   analytics.metric('release_packages_count', 5, {\n *     project: 'kb-labs',\n *   });\n * }\n * ```\n */\nexport function useAnalytics(): IAnalytics | undefined {\n  const platform = usePlatform();\n  return platform.analytics;\n}\n\n/**\n * Track event with analytics (safe, global singleton)\n *\n * Convenience wrapper that uses global platform analytics.\n * Does nothing if analytics is not configured.\n *\n * NOTE: For context-based analytics, use trackEvent() from '../analytics/with-analytics'.\n * This helper uses global singleton, not request-scoped context.\n *\n * @param event - Event name\n * @param properties - Event properties\n *\n * @example\n * ```typescript\n * import { trackAnalyticsEvent } from '@kb-labs/shared-command-kit/helpers';\n *\n * // No need to check if analytics exists\n * await trackAnalyticsEvent('release_completed', { version: '1.0.0', packages: 5 });\n * ```\n */\nexport async function trackAnalyticsEvent(\n  event: string,\n  properties?: Record<string, unknown>\n): Promise<void> {\n  const analytics = useAnalytics();\n  if (analytics) {\n    await analytics.track(event, properties);\n  }\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-storage\n * Global storage access helper\n *\n * Provides clean access to file/blob storage adapter.\n *\n * @example\n * ```typescript\n * import { useStorage } from '@kb-labs/shared-command-kit';\n *\n * async handler(ctx, argv, flags) {\n *   const storage = useStorage();\n *\n *   if (storage) {\n *     await storage.write('path/to/file.txt', 'content');\n *     const content = await storage.read('path/to/file.txt');\n *   }\n * }\n * ```\n */\n\nimport { usePlatform } from './use-platform';\nimport type { IStorage } from '@kb-labs/core-platform';\n\n/**\n * Access global storage adapter\n *\n * Returns the platform storage adapter for file/blob operations.\n * Returns undefined if storage is not configured (graceful degradation).\n *\n * **Methods:**\n * - `storage.read(path)` - Read file content\n * - `storage.write(path, content)` - Write file content\n * - `storage.exists(path)` - Check if file exists\n * - `storage.delete(path)` - Delete file\n * - `storage.list(prefix?)` - List files\n *\n * **Always check availability:**\n * ```typescript\n * const storage = useStorage();\n * if (storage) {\n *   await storage.write('file.txt', 'content');\n * }\n * ```\n *\n * @returns Storage adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * const storage = useStorage();\n *\n * if (storage) {\n *   // Write file\n *   await storage.write('releases/v1.0.0.json', JSON.stringify(data));\n *\n *   // Read file\n *   const content = await storage.read('releases/v1.0.0.json');\n *   const data = JSON.parse(content);\n *\n *   // Check existence\n *   const exists = await storage.exists('releases/v1.0.0.json');\n *\n *   // List files\n *   const files = await storage.list('releases/');\n * }\n * ```\n */\nexport function useStorage(): IStorage | undefined {\n  const platform = usePlatform();\n  return platform.storage;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-cache\n * Global Cache access helper\n *\n * Provides clean access to platform cache (Redis, InMemory, or custom adapter).\n *\n * @example\n * ```typescript\n * import { useCache } from '@kb-labs/shared-command-kit';\n *\n * async handler(ctx, argv, flags) {\n *   const cache = useCache();\n *\n *   if (cache) {\n *     await cache.set('key', { data: 'value' }, 60000); // TTL: 60s\n *     const value = await cache.get('key');\n *     console.log(value);\n *   }\n * }\n * ```\n */\n\nimport { usePlatform } from './use-platform.js';\nimport type { ICache } from '@kb-labs/core-platform';\n\n/**\n * Access global cache adapter\n *\n * Returns the platform cache adapter (Redis, InMemory, or custom).\n * Returns undefined if cache is not configured (graceful degradation).\n *\n * **Methods:**\n * - `cache.set(key, value, ttlMs?)` - Store value with optional TTL\n * - `cache.get<T>(key)` - Retrieve value by key\n * - `cache.delete(key)` - Remove value\n * - `cache.clear()` - Clear all cached values\n *\n * **Always check availability:**\n * ```typescript\n * const cache = useCache();\n * if (cache) {\n *   await cache.set('query-123', result, 60000);\n * } else {\n *   // No caching, compute every time\n * }\n * ```\n *\n * @returns Cache adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * const cache = useCache();\n *\n * if (cache) {\n *   // Check cache first\n *   const cached = await cache.get<QueryResult>('query-123');\n *   if (cached) {\n *     return cached;\n *   }\n *\n *   // Compute result\n *   const result = await expensiveQuery();\n *\n *   // Cache for 5 minutes\n *   await cache.set('query-123', result, 5 * 60 * 1000);\n *\n *   return result;\n * }\n * ```\n */\nexport function useCache(): ICache | undefined {\n  const platform = usePlatform();\n  return platform.cache;\n}\n\n/**\n * Check if cache is available\n *\n * Useful for conditional logic (cached vs non-cached execution).\n *\n * @returns true if cache is configured and ready\n *\n * @example\n * ```typescript\n * if (isCacheAvailable()) {\n *   // Use cached results\n *   const result = await getCachedOrCompute(key);\n * } else {\n *   // Compute every time\n *   const result = await compute();\n * }\n * ```\n */\nexport function isCacheAvailable(): boolean {\n  const cache = useCache();\n  return !!cache;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-env\n *\n * Sandboxed environment variable access.\n *\n * Reads from runtimeContext (AsyncLocalStorage) when running inside\n * a governed handler execution (worker-pool, subprocess).\n * Falls back to process.env when no runtime context is set\n * (direct CLI, tests, code outside handler).\n *\n * @example\n * ```typescript\n * import { useEnv } from '@kb-labs/sdk';\n *\n * const token = useEnv('NPM_TOKEN');\n * const ci = useEnv('CI');\n * ```\n */\n\nimport { runtimeContext } from '@kb-labs/plugin-contracts';\n\n/**\n * Read an environment variable through the sandboxed runtime context.\n *\n * Inside a governed handler: reads through env-shim (permission-checked).\n * Outside handler context: reads process.env directly (backward compat).\n */\nexport function useEnv(key: string): string | undefined {\n  const runtime = runtimeContext.getStore();\n  if (runtime?.env) {\n    return runtime.env(key);\n  }\n  return process.env[key];\n}\n"]}
+{"version":3,"sources":["../../src/helpers/use-platform.ts","../../src/helpers/index.ts","../../src/helpers/use-config.ts","../../src/helpers/use-logger.ts","../../src/helpers/use-llm.ts","../../src/helpers/use-embeddings.ts","../../src/helpers/use-vector-store.ts","../../src/helpers/use-analytics.ts","../../src/helpers/use-storage.ts","../../src/helpers/use-cache.ts","../../src/helpers/use-document-database.ts","../../src/helpers/use-kv-store.ts","../../src/helpers/use-notifications.ts","../../src/helpers/use-env.ts"],"names":["globalPlatform","usePlatform","trace","optionsWithTrace"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @module @kb-labs/shared-command-kit/helpers/use-platform\n * Platform access hook with execution-scoped context.\n *\n * Uses AsyncLocalStorage to return the correct platform for the current\n * handler execution (governed, with correct permissions and proxy adapters).\n * Falls back to global singleton for code running outside handler context.\n *\n * @example\n * ```typescript\n * import { usePlatform } from '@kb-labs/shared-command-kit';\n *\n * // In any command handler — automatically gets the right platform\n * async handler(ctx, argv, flags) {\n *   const platform = usePlatform();\n *   const result = await platform.llm.complete('prompt');\n * }\n * ```\n */\n\nimport { platformContext } from '@kb-labs/plugin-contracts';\nimport { platform as globalPlatform } from '@kb-labs/core-runtime';\n\n/**\n * Access platform services for the current execution context.\n *\n * Priority:\n * 1. AsyncLocalStorage context (set by runInProcess) — per-execution, governed\n * 2. Global singleton fallback (core-runtime) — for code outside handler context\n *\n * @returns Platform services with correct adapters for current context\n */\nexport function usePlatform(): typeof globalPlatform {\n  // ALS stores PlatformServices (governed wrapper); at runtime it is always\n  // structurally compatible with PlatformContainer — the cast is safe.\n  return (platformContext.getStore() as unknown as typeof globalPlatform) ?? globalPlatform;\n}\n\n/**\n * Check if specific platform adapter is configured\n *\n * Useful for conditional logic based on available services.\n *\n * @param adapterName - Name of the adapter to check\n * @returns true if adapter is configured and available\n *\n * @example\n * ```typescript\n * if (isPlatformConfigured('llm')) {\n *   // Use LLM-powered feature\n * } else {\n *   // Use deterministic fallback\n * }\n * ```\n */\nexport function isPlatformConfigured(adapterName: keyof typeof globalPlatform): boolean {\n  const platform = usePlatform();\n\n  // Check if adapter exists and is not a noop/fallback\n  const adapter = platform[adapterName];\n\n  if (!adapter) {\n    return false;\n  }\n\n  // For adapters with hasAdapter method (like platform itself)\n  if ('hasAdapter' in platform && typeof platform.hasAdapter === 'function') {\n    return platform.hasAdapter(adapterName as string);\n  }\n\n  // Fallback: check if adapter is not noop\n  // Noop adapters usually have a specific constructor name or are simple objects\n  if (typeof adapter === 'object' && adapter.constructor) {\n    const constructorName = adapter.constructor.name;\n    return !constructorName.toLowerCase().includes('noop') &&\n           !constructorName.toLowerCase().includes('fallback');\n  }\n\n  return true;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers\n * Global platform access helpers\n *\n * Provides clean, type-safe access to platform services without context drilling.\n * Similar to React hooks pattern, but for KB Labs platform.\n *\n * @example\n * ```typescript\n * import { useLLM, useLogger, useAnalytics } from '@kb-labs/shared-command-kit/helpers';\n *\n * async handler(ctx, argv, flags) {\n *   const logger = useLogger();\n *   const llm = useLLM();\n *\n *   await logger.info('Processing started');\n *\n *   if (llm) {\n *     const result = await llm.complete('prompt');\n *     await logger.info('LLM result', { length: result.content.length });\n *   }\n * }\n * ```\n */\n\n// Platform singleton\nexport { usePlatform, isPlatformConfigured } from './use-platform';\n\n// Context types and helpers\nexport type { PluginContextV3 } from './context';\n\n// Config access\nexport { useConfig } from './use-config';\n\n// Core services\nexport { useLogger, useLoggerWithContext } from './use-logger.js';\nexport { useLLM, isLLMAvailable, getLLMTier, type LLMTier, type UseLLMOptions } from './use-llm.js';\nexport { useEmbeddings, isEmbeddingsAvailable } from './use-embeddings.js';\nexport { useVectorStore, isVectorStoreAvailable } from './use-vector-store.js';\nexport { useAnalytics, trackAnalyticsEvent } from './use-analytics.js';\nexport { useStorage } from './use-storage.js';\nexport { useCache, isCacheAvailable } from './use-cache.js';\nexport { useDocumentDatabase, isDocumentDatabaseAvailable } from './use-document-database.js';\nexport { useKVStore, isKVStoreAvailable } from './use-kv-store.js';\n\n// Notifications\nexport { useNotifications } from './use-notifications.js';\n\n// Runtime shims\nexport { useEnv } from './use-env.js';\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-config\n * Global config access helper\n *\n * Provides clean access to product-specific configuration without context drilling.\n * Similar to React hooks pattern, but for KB Labs config.\n *\n * @example\n * ```typescript\n * import { useConfig } from '@kb-labs/shared-command-kit';\n *\n * // In any command handler\n * async handler(ctx, argv, flags) {\n *   const config = await useConfig('mind');\n *\n *   if (config) {\n *     const scopes = config.scopes;\n *     // Use config...\n *   }\n * }\n * ```\n */\n\n/**\n * Access product-specific configuration from kb.config.json\n *\n * Returns ONLY the config for the specified product and profile.\n * Uses platform.config adapter (works across parent/child processes via IPC).\n * Supports both Profiles v2 and legacy config structures.\n *\n * **Security:** This function returns ONLY the product-specific config,\n * not the entire kb.config.json. This prevents cross-product config access.\n *\n * **Auto-detection:** If productId is not provided, it's automatically inferred\n * from the plugin's manifest.configSection field (passed via execution context).\n *\n * **Profiles v2 structure:**\n * ```json\n * {\n *   \"profiles\": [\n *     {\n *       \"id\": \"default\",\n *       \"products\": {\n *         \"mind\": { \"scopes\": [...] },\n *         \"workflow\": { \"maxConcurrency\": 10 }\n *       }\n *     }\n *   ]\n * }\n * ```\n *\n * **Legacy structure:**\n * ```json\n * {\n *   \"knowledge\": { \"scopes\": [...] },  // for \"mind\" product\n *   \"workflow\": { \"maxConcurrency\": 10 }\n * }\n * ```\n *\n * @param productId - Product identifier (e.g., 'mind', 'workflow', 'plugins'). Optional - auto-detected from context.\n * @param profileId - Profile identifier (defaults to 'default' or KB_PROFILE env var)\n * @returns Promise resolving to product-specific config or undefined\n *\n * @example\n * ```typescript\n * // Auto-detect from context (recommended)\n * const config = await useConfig();\n *\n * // Explicit product ID\n * const mindConfig = await useConfig('mind');\n * if (mindConfig?.scopes) {\n *   // Use scopes\n * }\n *\n * // With explicit profile\n * const workflowConfig = await useConfig('workflow', 'production');\n * ```\n */\nexport async function useConfig<T = any>(productId?: string, profileId?: string): Promise<T | undefined> {\n  // Auto-detect productId from manifest.configSection if not provided\n  let effectiveProductId = productId;\n  if (!effectiveProductId) {\n    effectiveProductId = (globalThis as typeof globalThis & { __KB_CONFIG_SECTION__?: string }).__KB_CONFIG_SECTION__;\n  }\n\n  if (!effectiveProductId) {\n    return undefined;\n  }\n\n  // ── EXPLICIT OVERRIDE (2026-06-07) ──────────────────────────────────────────\n  // Config is read DIRECTLY from the global the service already loaded\n  // (`service-bootstrap` sets `__KB_RAW_CONFIG__` / `__KB_EFFECTIVE_CONFIG__`),\n  // NOT through the `platform.config` adapter.\n  //\n  // Rationale: in-process the adapter was pure indirection over this same global,\n  // and on the isolated/worker path it crashed — config is attached post-assembly\n  // only on the parent path, so `platform.config` was undefined in worker handlers\n  // (the \"F2\" bug). The global IS populated even in those workers, so reading it\n  // directly is correct AND removes the adapter from the hot path.\n  //\n  // The `platform.config` proxy is kept ONLY as a fallback for a genuinely remote\n  // worker that has no shared memory (future client/server execution).\n  // ────────────────────────────────────────────────────────────────────────────\n  const g = globalThis as typeof globalThis & {\n    __KB_EFFECTIVE_CONFIG__?: Record<string, unknown>;\n    __KB_RAW_CONFIG__?: Record<string, unknown>;\n  };\n  const rawConfig = g.__KB_EFFECTIVE_CONFIG__ ?? g.__KB_RAW_CONFIG__;\n\n  if (rawConfig) {\n    return selectProductSection<T>(rawConfig, effectiveProductId, profileId);\n  }\n\n  // Fallback: no global in this process (genuinely remote/isolated worker without\n  // shared memory) → use the platform.config IPC proxy if present.\n  const { usePlatform } = await import('./use-platform.js');\n  const platform = usePlatform();\n  if (platform?.config) {\n    return (await platform.config.getConfig(effectiveProductId, profileId)) as T | undefined;\n  }\n\n  return undefined;\n}\n\n/**\n * Select a product's config section from the raw kb.config.json object.\n *\n * Mirrors core-runtime `ConfigAdapter.getConfig`: Profiles v2 first\n * (`profiles[].products[productId]`), then the legacy flat structure\n * (top-level key, with the `mind` → `knowledge` alias). Returns ONLY the\n * product-specific section, never the whole config.\n */\nfunction selectProductSection<T = any>(\n  rawConfig: Record<string, unknown>,\n  productId: string,\n  profileId?: string,\n): T | undefined {\n  const effectiveProfileId = profileId ?? process.env.KB_PROFILE ?? 'default';\n\n  // Profiles v2 structure\n  const profilesField = (rawConfig as { profiles?: unknown }).profiles;\n  if (Array.isArray(profilesField)) {\n    type RawProfile = { id?: string; products?: Record<string, unknown> };\n    const profiles = profilesField as RawProfile[];\n    const profile = profiles.find((p) => p.id === effectiveProfileId) ?? profiles[0];\n    if (profile?.products?.[productId] !== undefined) {\n      return profile.products[productId] as T;\n    }\n  }\n\n  // Legacy flat structure (mind → knowledge alias)\n  const legacyKeyMap: Record<string, string> = { mind: 'knowledge' };\n  const legacyKey = legacyKeyMap[productId] ?? productId;\n  if (rawConfig[legacyKey] !== undefined) {\n    return rawConfig[legacyKey] as T;\n  }\n\n  return undefined;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-logger\n * Global logger access helper\n *\n * Provides clean access to structured logging without context drilling.\n *\n * @example\n * ```typescript\n * import { useLogger } from '@kb-labs/shared-command-kit';\n *\n * async handler(ctx, argv, flags) {\n *   const logger = useLogger();\n *\n *   await logger.info('Processing started');\n *   await logger.debug('Details', { userId: 123 });\n *   await logger.error('Failed', { error: err });\n * }\n * ```\n */\n\nimport { usePlatform } from './use-platform';\nimport type { ILogger } from '@kb-labs/core-platform';\n\n/**\n * Access global logger\n *\n * Returns the platform logger with structured logging capabilities.\n * Supports child loggers with additional context.\n *\n * **Methods:**\n * - `logger.trace(message, meta?)` - Trace-level logs (most verbose)\n * - `logger.debug(message, meta?)` - Debug-level logs\n * - `logger.info(message, meta?)` - Info-level logs\n * - `logger.warn(message, meta?)` - Warning-level logs\n * - `logger.error(message, meta?)` - Error-level logs\n * - `logger.child(meta)` - Create child logger with additional context\n *\n * @returns Platform logger instance\n *\n * @example\n * ```typescript\n * const logger = useLogger();\n *\n * await logger.info('Task started', { taskId: '123' });\n * await logger.error('Task failed', { taskId: '123', error: err.message });\n *\n * // Child logger with persistent context\n * const taskLogger = logger.child({ taskId: '123', userId: 'user-1' });\n * await taskLogger.info('Step 1 completed');\n * await taskLogger.info('Step 2 completed');\n * ```\n */\nexport function useLogger(): ILogger {\n  const platform = usePlatform();\n  return platform.logger;\n}\n\n/**\n * Create child logger with additional context\n *\n * Useful for scoped logging within a specific operation.\n *\n * @param context - Additional context to attach to all log entries\n * @returns Child logger with persistent context\n *\n * @example\n * ```typescript\n * const logger = useLoggerWithContext({ operation: 'release', version: '1.0.0' });\n *\n * await logger.info('Started');  // Automatically includes operation + version\n * await logger.info('Completed');\n * ```\n */\nexport function useLoggerWithContext(context: Record<string, unknown>): ILogger {\n  const logger = useLogger();\n  return logger.child(context);\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-llm\n * Global LLM access helper with tier-based model selection.\n *\n * Provides clean access to LLM with adaptive tier routing.\n * Plugins specify tiers (small/medium/large), platform resolves to actual models.\n *\n * @example\n * ```typescript\n * import { useLLM } from '@kb-labs/shared-command-kit';\n *\n * async handler(ctx, argv, flags) {\n *   // Simple usage (uses configured default tier)\n *   const llm = useLLM();\n *\n *   // Request specific tier (platform adapts if needed)\n *   const llm = useLLM({ tier: 'small' });   // Simple tasks\n *   const llm = useLLM({ tier: 'large' });   // Complex tasks\n *\n *   // Request capabilities\n *   const llm = useLLM({ tier: 'medium', capabilities: ['coding'] });\n *\n *   if (llm) {\n *     const result = await llm.complete('Explain this code');\n *     console.log(result.content);\n *   }\n * }\n * ```\n */\n\nimport { usePlatform } from './use-platform.js';\nimport type {\n  ILLM,\n  LLMTier,\n  LLMOptions,\n  LLMResponse,\n  LLMMessage,\n  LLMToolCallOptions,\n  LLMToolCallResponse,\n  UseLLMOptions,\n  ILLMRouter,\n  LLMAdapterBinding,\n  LLMExecutionPolicy,\n  LLMProtocolCapabilities,\n  LLMCacheDecisionTrace,\n} from '@kb-labs/core-platform';\n\n/**\n * Access global LLM adapter with tier-based selection.\n *\n * Platform automatically adapts to available models:\n * - If plugin requests 'small' but 'medium' configured → uses 'medium' (escalation)\n * - If plugin requests 'large' but 'medium' configured → uses 'medium' with warning (degradation)\n *\n * **Tiers are user-defined slots:**\n * - `small`  - Plugin says: \"This task is simple\"\n * - `medium` - Plugin says: \"Standard task\"\n * - `large`  - Plugin says: \"Complex task, need maximum quality\"\n *\n * User decides what model maps to each tier in their config.\n *\n * @param options - Optional tier and capability requirements\n * @returns LLM adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * // Simple usage (uses configured default)\n * const llm = useLLM();\n *\n * // Request specific tier\n * const llm = useLLM({ tier: 'small' });   // Simple tasks\n * const llm = useLLM({ tier: 'large' });   // Complex tasks\n *\n * // Request capabilities\n * const llm = useLLM({ tier: 'medium', capabilities: ['coding'] });\n * const llm = useLLM({ capabilities: ['vision'] });\n *\n * if (llm) {\n *   const result = await llm.complete('Generate commit message');\n *   console.log(result.content);\n * }\n * ```\n */\nexport function useLLM(options?: UseLLMOptions): ILLM | undefined {\n  const platform = usePlatform();\n  const llm = platform.llm;\n\n  if (!llm) {\n    return undefined;\n  }\n\n  // If router and options given → return immutable LazyBoundLLM (no state mutation)\n  if (options && isLLMRouter(llm)) {\n    return new LazyBoundLLM(llm, options);\n  }\n\n  return llm;\n}\n\n/**\n * Lazy adapter binding that resolves tier on first use.\n * Immutable — does NOT mutate the global LLMRouter state.\n * This fixes the race condition where useLLM({ tier: 'large' }) was immediately\n * overwritten by useLLM({ tier: 'small' }) from SmartSummarizer.\n */\nclass LazyBoundLLM implements ILLM {\n  private _resolved: Promise<LLMAdapterBinding> | null = null;\n\n  constructor(\n    private readonly router: ILLM & ILLMRouter,\n    private readonly options: UseLLMOptions,\n  ) {}\n\n  private resolve(): Promise<LLMAdapterBinding> {\n    if (!this._resolved) {\n      this._resolved = this.router.resolveAdapter(this.options);\n    }\n    return this._resolved;\n  }\n\n  private mergeExecutionPolicy(callOptions?: LLMOptions): LLMExecutionPolicy | undefined {\n    const globalPolicy = this.options.execution;\n    const localPolicy = callOptions?.execution;\n    if (!globalPolicy && !localPolicy) {\n      return undefined;\n    }\n    return {\n      ...globalPolicy,\n      ...localPolicy,\n      cache: { ...globalPolicy?.cache, ...localPolicy?.cache },\n      stream: { ...globalPolicy?.stream, ...localPolicy?.stream },\n    };\n  }\n\n  private async resolveProtocolCapabilities(adapter: ILLM): Promise<LLMProtocolCapabilities> {\n    if (!adapter.getProtocolCapabilities) {\n      return {\n        cache: { supported: false },\n        stream: { supported: true },\n      };\n    }\n    return adapter.getProtocolCapabilities();\n  }\n\n  private enforceCachePolicy(caps: LLMProtocolCapabilities, execution?: LLMExecutionPolicy): void {\n    if (execution?.cache?.mode === 'require' && !caps.cache.supported) {\n      throw new Error('CACHE_NOT_SUPPORTED: adapter does not support required cache policy');\n    }\n  }\n\n  private buildDecisionTrace(\n    caps: LLMProtocolCapabilities,\n    execution: LLMExecutionPolicy | undefined,\n    streamAppliedMode: 'prefer' | 'require' | 'off',\n    streamFallback?: 'complete',\n    reason?: string,\n  ): LLMCacheDecisionTrace {\n    const requestedCacheMode = execution?.cache?.mode ?? 'prefer';\n    const requestedStreamMode = execution?.stream?.mode ?? 'prefer';\n\n    return {\n      cacheRequestedMode: requestedCacheMode,\n      cacheSupported: caps.cache.supported,\n      cacheAppliedMode:\n        requestedCacheMode === 'require' || requestedCacheMode === 'bypass'\n          ? requestedCacheMode\n          : caps.cache.supported\n            ? 'prefer'\n            : 'bypass',\n      streamRequestedMode: requestedStreamMode,\n      streamSupported: caps.stream.supported,\n      streamAppliedMode,\n      streamFallback,\n      reason,\n    };\n  }\n\n  private withDecisionMetadata(\n    options: LLMOptions | undefined,\n    trace: LLMCacheDecisionTrace,\n  ): LLMOptions | undefined {\n    if (!options) {\n      return { metadata: { cacheDecisionTrace: trace } };\n    }\n\n    return {\n      ...options,\n      metadata: {\n        ...options.metadata,\n        cacheDecisionTrace: trace,\n      },\n    };\n  }\n\n  async complete(prompt: string, options?: LLMOptions): Promise<LLMResponse> {\n    const { adapter, model } = await this.resolve();\n    const execution = this.mergeExecutionPolicy(options);\n    const caps = await this.resolveProtocolCapabilities(adapter);\n    this.enforceCachePolicy(caps, execution);\n    const trace = this.buildDecisionTrace(caps, execution, 'off');\n    const optionsWithTrace = this.withDecisionMetadata(options, trace);\n    return adapter.complete(prompt, { ...optionsWithTrace, model, execution });\n  }\n\n  async *stream(prompt: string, options?: LLMOptions): AsyncIterable<string> {\n    const { adapter, model } = await this.resolve();\n    const execution = this.mergeExecutionPolicy(options);\n    const caps = await this.resolveProtocolCapabilities(adapter);\n    this.enforceCachePolicy(caps, execution);\n\n    const streamMode = execution?.stream?.mode ?? 'prefer';\n    const canStream = caps.stream.supported;\n    const allowFallback = execution?.stream?.fallbackToComplete ?? true;\n\n    if (streamMode === 'off' || (!canStream && streamMode === 'prefer' && allowFallback)) {\n      const fallbackReason =\n        streamMode === 'off'\n          ? 'STREAM_OFF'\n          : 'STREAM_UNSUPPORTED_FALLBACK_TO_COMPLETE';\n      const trace = this.buildDecisionTrace(caps, execution, 'off', 'complete', fallbackReason);\n      const optionsWithTrace = this.withDecisionMetadata(options, trace);\n      const response = await adapter.complete(prompt, { ...optionsWithTrace, model, execution });\n      if (response.content) {\n        yield response.content;\n      }\n      return;\n    }\n\n    if (!canStream && streamMode === 'require') {\n      throw new Error('STREAM_NOT_SUPPORTED: adapter does not support required streaming');\n    }\n\n    const trace = this.buildDecisionTrace(caps, execution, streamMode);\n    const optionsWithTrace = this.withDecisionMetadata(options, trace);\n    yield* adapter.stream(prompt, { ...optionsWithTrace, model, execution });\n  }\n\n  async chatWithTools(\n    messages: LLMMessage[],\n    options: LLMToolCallOptions,\n  ): Promise<LLMToolCallResponse> {\n    const { adapter, model, tier } = await this.resolve();\n    const execution = this.mergeExecutionPolicy(options);\n    const caps = await this.resolveProtocolCapabilities(adapter);\n    this.enforceCachePolicy(caps, execution);\n    if (!adapter.chatWithTools) {\n      throw new Error('Current adapter does not support chatWithTools');\n    }\n    const trace = this.buildDecisionTrace(caps, execution, 'off');\n    const optionsWithTrace = this.withDecisionMetadata(options, trace) as LLMToolCallOptions;\n    return adapter.chatWithTools(messages, {\n      ...optionsWithTrace,\n      model,\n      execution,\n      metadata: { ...optionsWithTrace.metadata, tier },\n    });\n  }\n}\n\n/**\n * Check if LLM is available.\n *\n * Useful for conditional logic (LLM-powered vs deterministic fallback).\n *\n * @returns true if LLM is configured and ready\n *\n * @example\n * ```typescript\n * if (isLLMAvailable()) {\n *   const summary = await generateWithLLM(data);\n * } else {\n *   const summary = generateDeterministic(data);\n * }\n * ```\n */\nexport function isLLMAvailable(): boolean {\n  const llm = useLLM();\n  return !!llm;\n}\n\n/**\n * Get configured LLM tier.\n *\n * Useful for diagnostics and logging.\n *\n * @returns Configured tier or undefined if LLM not available/not a router\n *\n * @example\n * ```typescript\n * const tier = getLLMTier();\n * console.log(`Using LLM tier: ${tier ?? 'default'}`);\n * ```\n */\nexport function getLLMTier(): LLMTier | undefined {\n  const platform = usePlatform();\n  const llm = platform.llm;\n\n  if (llm && isLLMRouter(llm)) {\n    return llm.getConfiguredTier();\n  }\n\n  return undefined;\n}\n\n/**\n * Type guard for ILLMRouter.\n */\nfunction isLLMRouter(llm: ILLM): llm is ILLM & ILLMRouter {\n  return (\n    typeof (llm as unknown as ILLMRouter).getConfiguredTier === 'function' &&\n    typeof (llm as unknown as ILLMRouter).resolve === 'function'\n  );\n}\n\n// Re-export types for convenience\nexport type { LLMTier, UseLLMOptions } from '@kb-labs/core-platform';\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-embeddings\n * Global Embeddings access helper\n */\n\nimport { usePlatform } from './use-platform';\nimport type { IEmbeddings } from '@kb-labs/core-platform';\n\n/**\n * Access global Embeddings adapter\n *\n * Returns the platform embeddings adapter (OpenAI, etc.).\n * Returns undefined if embeddings is not configured (graceful degradation).\n *\n * @returns Embeddings adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * const embeddings = useEmbeddings();\n *\n * if (embeddings) {\n *   const vector = await embeddings.embed('Hello, world!');\n *   console.log(vector.length); // e.g., 1536 for OpenAI\n * }\n * ```\n */\nexport function useEmbeddings(): IEmbeddings | undefined {\n  const platform = usePlatform();\n  return platform.embeddings;\n}\n\n/**\n * Check if Embeddings is available\n *\n * @returns true if embeddings is configured and ready\n *\n * @example\n * ```typescript\n * if (isEmbeddingsAvailable()) {\n *   const vector = await embeddings.embed(text);\n * } else {\n *   // Use deterministic fallback\n * }\n * ```\n */\nexport function isEmbeddingsAvailable(): boolean {\n  const embeddings = useEmbeddings();\n  return !!embeddings;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-vector-store\n * Global VectorStore access helper\n */\n\nimport { usePlatform } from './use-platform';\nimport type { IVectorStore } from '@kb-labs/core-platform';\n\n/**\n * Access global VectorStore adapter\n *\n * Returns the platform vector store adapter (Qdrant, local, etc.).\n * Returns undefined if vectorStore is not configured (graceful degradation).\n *\n * @returns VectorStore adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * const vectorStore = useVectorStore();\n *\n * if (vectorStore) {\n *   await vectorStore.upsert([{ id: '1', vector: [0.1, 0.2], metadata: {} }]);\n *   const results = await vectorStore.search([0.1, 0.2], 10);\n * }\n * ```\n */\nexport function useVectorStore(): IVectorStore | undefined {\n  const platform = usePlatform();\n  return platform.vectorStore;\n}\n\n/**\n * Check if VectorStore is available\n *\n * @returns true if vectorStore is configured and ready\n *\n * @example\n * ```typescript\n * if (isVectorStoreAvailable()) {\n *   await vectorStore.upsert(records);\n * } else {\n *   // Use local fallback\n * }\n * ```\n */\nexport function isVectorStoreAvailable(): boolean {\n  const vectorStore = useVectorStore();\n  return !!vectorStore;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-analytics\n * Global analytics access helper\n *\n * Provides clean access to analytics/telemetry without context drilling.\n *\n * @example\n * ```typescript\n * import { useAnalytics } from '@kb-labs/shared-command-kit';\n *\n * async handler(ctx, argv, flags) {\n *   const analytics = useAnalytics();\n *\n *   if (analytics) {\n *     await analytics.track('release_started', { version: '1.0.0' });\n *     analytics.metric('release_duration_ms', 1234);\n *   }\n * }\n * ```\n */\n\nimport { usePlatform } from './use-platform';\nimport type { IAnalytics } from '@kb-labs/core-platform';\n\n/**\n * Access global analytics adapter\n *\n * Returns the platform analytics adapter for tracking events and metrics.\n * Returns undefined if analytics is not configured (graceful degradation).\n *\n * **Methods:**\n * - `analytics.track(event, properties?)` - Track events\n * - `analytics.metric(name, value, tags?)` - Record metrics\n *\n * **Always check availability:**\n * ```typescript\n * const analytics = useAnalytics();\n * if (analytics) {\n *   await analytics.track('event');\n * }\n * ```\n *\n * @returns Analytics adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * const analytics = useAnalytics();\n *\n * if (analytics) {\n *   await analytics.track('command_executed', {\n *     command: 'release:run',\n *     duration_ms: 1234,\n *     success: true,\n *   });\n *\n *   analytics.metric('release_packages_count', 5, {\n *     project: 'kb-labs',\n *   });\n * }\n * ```\n */\nexport function useAnalytics(): IAnalytics | undefined {\n  const platform = usePlatform();\n  return platform.analytics;\n}\n\n/**\n * Track event with analytics (safe, global singleton)\n *\n * Convenience wrapper that uses global platform analytics.\n * Does nothing if analytics is not configured.\n *\n * NOTE: For context-based analytics, use trackEvent() from '../analytics/with-analytics'.\n * This helper uses global singleton, not request-scoped context.\n *\n * @param event - Event name\n * @param properties - Event properties\n *\n * @example\n * ```typescript\n * import { trackAnalyticsEvent } from '@kb-labs/shared-command-kit/helpers';\n *\n * // No need to check if analytics exists\n * await trackAnalyticsEvent('release_completed', { version: '1.0.0', packages: 5 });\n * ```\n */\nexport async function trackAnalyticsEvent(\n  event: string,\n  properties?: Record<string, unknown>\n): Promise<void> {\n  const analytics = useAnalytics();\n  if (analytics) {\n    await analytics.track(event, properties);\n  }\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-storage\n * Global storage access helper\n *\n * Provides clean access to file/blob storage adapter.\n *\n * @example\n * ```typescript\n * import { useStorage } from '@kb-labs/shared-command-kit';\n *\n * async handler(ctx, argv, flags) {\n *   const storage = useStorage();\n *\n *   if (storage) {\n *     await storage.write('path/to/file.txt', 'content');\n *     const content = await storage.read('path/to/file.txt');\n *   }\n * }\n * ```\n */\n\nimport { usePlatform } from './use-platform';\nimport type { IStorage } from '@kb-labs/core-platform';\n\n/**\n * Access global storage adapter\n *\n * Returns the platform storage adapter for file/blob operations.\n * Returns undefined if storage is not configured (graceful degradation).\n *\n * **Methods:**\n * - `storage.read(path)` - Read file content\n * - `storage.write(path, content)` - Write file content\n * - `storage.exists(path)` - Check if file exists\n * - `storage.delete(path)` - Delete file\n * - `storage.list(prefix?)` - List files\n *\n * **Always check availability:**\n * ```typescript\n * const storage = useStorage();\n * if (storage) {\n *   await storage.write('file.txt', 'content');\n * }\n * ```\n *\n * @returns Storage adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * const storage = useStorage();\n *\n * if (storage) {\n *   // Write file\n *   await storage.write('releases/v1.0.0.json', JSON.stringify(data));\n *\n *   // Read file\n *   const content = await storage.read('releases/v1.0.0.json');\n *   const data = JSON.parse(content);\n *\n *   // Check existence\n *   const exists = await storage.exists('releases/v1.0.0.json');\n *\n *   // List files\n *   const files = await storage.list('releases/');\n * }\n * ```\n */\nexport function useStorage(): IStorage | undefined {\n  const platform = usePlatform();\n  return platform.storage;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-cache\n * Global Cache access helper\n *\n * Provides clean access to platform cache (Redis, InMemory, or custom adapter).\n *\n * @example\n * ```typescript\n * import { useCache } from '@kb-labs/shared-command-kit';\n *\n * async handler(ctx, argv, flags) {\n *   const cache = useCache();\n *\n *   if (cache) {\n *     await cache.set('key', { data: 'value' }, 60000); // TTL: 60s\n *     const value = await cache.get('key');\n *     console.log(value);\n *   }\n * }\n * ```\n */\n\nimport { usePlatform } from './use-platform.js';\nimport type { ICache } from '@kb-labs/core-platform';\n\n/**\n * Access global cache adapter\n *\n * Returns the platform cache adapter (Redis, InMemory, or custom).\n * Returns undefined if cache is not configured (graceful degradation).\n *\n * **Methods:**\n * - `cache.set(key, value, ttlMs?)` - Store value with optional TTL\n * - `cache.get<T>(key)` - Retrieve value by key\n * - `cache.delete(key)` - Remove value\n * - `cache.clear()` - Clear all cached values\n *\n * **Always check availability:**\n * ```typescript\n * const cache = useCache();\n * if (cache) {\n *   await cache.set('query-123', result, 60000);\n * } else {\n *   // No caching, compute every time\n * }\n * ```\n *\n * @returns Cache adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * const cache = useCache();\n *\n * if (cache) {\n *   // Check cache first\n *   const cached = await cache.get<QueryResult>('query-123');\n *   if (cached) {\n *     return cached;\n *   }\n *\n *   // Compute result\n *   const result = await expensiveQuery();\n *\n *   // Cache for 5 minutes\n *   await cache.set('query-123', result, 5 * 60 * 1000);\n *\n *   return result;\n * }\n * ```\n */\nexport function useCache(): ICache | undefined {\n  const platform = usePlatform();\n  return platform.cache;\n}\n\n/**\n * Check if cache is available\n *\n * Useful for conditional logic (cached vs non-cached execution).\n *\n * @returns true if cache is configured and ready\n *\n * @example\n * ```typescript\n * if (isCacheAvailable()) {\n *   // Use cached results\n *   const result = await getCachedOrCompute(key);\n * } else {\n *   // Compute every time\n *   const result = await compute();\n * }\n * ```\n */\nexport function isCacheAvailable(): boolean {\n  const cache = useCache();\n  return !!cache;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-document-database\n *\n * Hook for the per-plugin document database — structured persistence with\n * filters, transactions, and indexed collections.\n *\n * The adapter is resolved from the current `usePlatform()` context, so the\n * instance you receive is already wrapped with this plugin's permissions:\n * collection names are namespaced under `<pluginId>__<name>`, and any call\n * to a collection the plugin didn't declare in\n * `permissions.platform.database.document.owns` / `.access` rejects with\n * `PermissionError`.\n *\n * @example\n * ```typescript\n * import { useDocumentDatabase } from '@kb-labs/shared-command-kit';\n *\n * interface Run extends BaseDocument {\n *   status: 'queued' | 'running' | 'done';\n *   startedAt: number;\n * }\n *\n * async function handler() {\n *   const docs = useDocumentDatabase();\n *   if (!docs) {\n *     throw new Error('Plugin needs documentDatabase configured');\n *   }\n *\n *   await docs.ensureCollection('runs', {\n *     indexes: [{ path: 'status' }],\n *   });\n *\n *   const queued = await docs.find<Run>('runs', { status: { $eq: 'queued' } });\n *   return queued;\n * }\n * ```\n */\n\nimport type { IDocumentDatabase } from '@kb-labs/core-platform';\nimport { usePlatform } from './use-platform.js';\n\n/**\n * Resolve the document database for the current execution.\n *\n * Returns `undefined` when no adapter is configured at all. When a plugin\n * declared permissions but is missing the wiring (NoOp adapter on the\n * platform side) you still get an instance — calls just throw on use.\n *\n * Always check before using:\n *\n * ```ts\n * const docs = useDocumentDatabase();\n * if (!docs) {\n *   // The platform was started without a document database;\n *   // either skip the feature or fail fast with a clear error.\n *   return;\n * }\n * ```\n */\nexport function useDocumentDatabase(): IDocumentDatabase | undefined {\n  const platform = usePlatform();\n  return platform.documentDatabase;\n}\n\n/**\n * Cheap check for \"is the document database available?\". Returns true even\n * for NoOp adapters configured by the platform — use this to gate optional\n * features, not as a security check.\n */\nexport function isDocumentDatabaseAvailable(): boolean {\n  return useDocumentDatabase() !== undefined;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-kv-store\n *\n * Hook for the per-plugin durable key-value store.\n *\n * Unlike `useCache`, KV is the source of truth — entries persist until\n * explicitly deleted or until their TTL expires. Use it for sessions,\n * distributed locks, idempotency keys, counters — anything where losing\n * the entry is a bug.\n *\n * Keys are namespaced under `<pluginId>:` transparently. Two plugins\n * setting `\"counter\"` do not collide. `scan` only yields the calling\n * plugin's own keys.\n *\n * @example\n * ```typescript\n * import { useKVStore } from '@kb-labs/shared-command-kit';\n *\n * async function withLock<T>(name: string, fn: () => Promise<T>): Promise<T> {\n *   const kv = useKVStore();\n *   if (!kv) throw new Error('KV store not configured');\n *\n *   const token = crypto.randomUUID();\n *   const acquired = await kv.setIfNotExists(`lock:${name}`, token, { ttlMs: 30_000 });\n *   if (!acquired) throw new Error('lock held');\n *\n *   try {\n *     return await fn();\n *   } finally {\n *     // Release only if we still hold the token (cas guards against ttl-takeover).\n *     await kv.cas(`lock:${name}`, token, null);\n *   }\n * }\n * ```\n */\n\nimport type { IKVStore } from '@kb-labs/core-platform';\nimport { usePlatform } from './use-platform.js';\n\n/**\n * Resolve the KV store for the current execution.\n *\n * Returns `undefined` only when no adapter is wired at all. A plugin\n * that didn't declare `permissions.platform.database.kvStore` still gets\n * an instance — every method throws `PermissionError` on use.\n */\nexport function useKVStore(): IKVStore | undefined {\n  const platform = usePlatform();\n  return platform.kvStore;\n}\n\n/**\n * Cheap check used to gate optional features. Note that it returns true\n * even when the plugin lacks `permissions.platform.database.kvStore` —\n * the runtime will replace the adapter with a deny stub in that case, so\n * this check tells you \"is the slot wired?\", not \"can I actually use it?\".\n */\nexport function isKVStoreAvailable(): boolean {\n  return useKVStore() !== undefined;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-notifications\n * Platform notifier access helper.\n *\n * @example\n * ```typescript\n * import { useNotifications } from '@kb-labs/shared-command-kit';\n *\n * async handler(ctx, argv, flags) {\n *   const notifier = useNotifications();\n *   await notifier?.notify({ title: 'Done', body: 'Workflow complete', severity: 'info' });\n * }\n * ```\n */\n\nimport { usePlatform } from './use-platform';\nimport type { INotifier } from '@kb-labs/core-platform';\n\n/**\n * Access the platform notifier adapter.\n * Returns undefined if the notifier adapter is not configured.\n *\n * @example\n * ```typescript\n * const notifier = useNotifications();\n * if (notifier) {\n *   await notifier.notify({ title: 'Alert', body: 'Something failed', severity: 'critical' });\n * }\n * ```\n */\nexport function useNotifications(): INotifier | undefined {\n  const platform = usePlatform();\n  return platform.notifier;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-env\n *\n * Sandboxed environment variable access.\n *\n * Reads from runtimeContext (AsyncLocalStorage) when running inside\n * a governed handler execution (worker-pool, subprocess).\n * Falls back to process.env when no runtime context is set\n * (direct CLI, tests, code outside handler).\n *\n * @example\n * ```typescript\n * import { useEnv } from '@kb-labs/sdk';\n *\n * const token = useEnv('NPM_TOKEN');\n * const ci = useEnv('CI');\n * ```\n */\n\nimport { runtimeContext } from '@kb-labs/plugin-contracts';\n\n/**\n * Read an environment variable through the sandboxed runtime context.\n *\n * Inside a governed handler: reads through env-shim (permission-checked).\n * Outside handler context: reads process.env directly (backward compat).\n */\nexport function useEnv(key: string): string | undefined {\n  const runtime = runtimeContext.getStore();\n  if (runtime?.env) {\n    return runtime.env(key);\n  }\n  return process.env[key];\n}\n"]}