@kb-labs/shared-command-kit 2.119.0-canary.0b1ec4151 → 2.119.0-canary.1b2bf822b
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["
|
|
1
|
+
{"version":3,"sources":["../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/src/analytics/with-analytics.ts"],"names":[],"mappings":";AA2EA,eAAsB,aAAA,CACpB,GAAA,EACA,SAAA,EACA,MAAA,EACA,SAAA,EACkB;AAClB,EAAA,MAAM,SAAA,GAAY,IAAI,QAAA,EAAU,SAAA;AAChC,EAAA,MAAM,SAAA,GAAY,KAAK,GAAA,EAAI;AAG3B,EAAA,IAAI,SAAA,IAAa,OAAO,OAAA,EAAS;AAC/B,IAAA,MAAM,SAAA,CAAU,KAAA,CAAM,CAAA,EAAG,SAAS,CAAA,QAAA,CAAA,EAAY;AAAA,MAC5C,GAAG,MAAA,CAAO,OAAA;AAAA,MACV,SAAA,EAAA,iBAAW,IAAI,IAAA,EAAK,EAAE,WAAA;AAAY,KACnC,CAAA;AAAA,EACH;AAEA,EAAA,IAAI;AAEF,IAAA,MAAM,MAAA,GAAS,MAAM,SAAA,EAAU;AAG/B,IAAA,IAAI,SAAA,IAAa,OAAO,SAAA,EAAW;AACjC,MAAA,MAAM,cAAA,GAAiB,OAAO,MAAA,CAAO,SAAA,KAAc,aAC/C,MAAA,CAAO,SAAA,CAAU,MAAM,CAAA,GACvB,MAAA,CAAO,SAAA;AAEX,MAAA,MAAM,SAAA,CAAU,KAAA,CAAM,CAAA,EAAG,SAAS,CAAA,UAAA,CAAA,EAAc;AAAA,QAC9C,GAAG,cAAA;AAAA,QACH,UAAA,EAAY,IAAA,CAAK,GAAA,EAAI,GAAI,SAAA;AAAA,QACzB,SAAA,EAAA,iBAAW,IAAI,IAAA,EAAK,EAAE,WAAA;AAAY,OACnC,CAAA;AAAA,IACH;AAEA,IAAA,OAAO,MAAA;AAAA,EACT,SAAS,KAAA,EAAgB;AAEvB,IAAA,IAAI,SAAA,IAAa,OAAO,MAAA,EAAQ;AAC9B,MAAA,MAAM,WAAA,GAAc,OAAO,MAAA,CAAO,MAAA,KAAW,aACzC,MAAA,CAAO,MAAA,CAAO,KAAc,CAAA,GAC5B,MAAA,CAAO,MAAA;AAEX,MAAA,MAAM,SAAA,CAAU,KAAA,CAAM,CAAA,EAAG,SAAS,CAAA,OAAA,CAAA,EAAW;AAAA,QAC3C,GAAG,WAAA;AAAA,QACH,UAAA,EAAY,IAAA,CAAK,GAAA,EAAI,GAAI,SAAA;AAAA,QACzB,SAAA,EAAA,iBAAW,IAAI,IAAA,EAAK,EAAE,WAAA;AAAY,OACnC,CAAA;AAAA,IACH;AAGA,IAAA,MAAM,KAAA;AAAA,EACR;AACF;AAqBO,SAAS,sBAAA,CACd,WACA,aAAA,EACA;AACA,EAAA,OAAO,OACL,GAAA,EACA,gBAAA,EACA,SAAA,KACqB;AACrB,IAAA,MAAM,YAAA,GAAyC;AAAA,MAC7C,SAAS,EAAE,GAAG,cAAc,OAAA,EAAS,GAAG,iBAAiB,OAAA,EAAQ;AAAA,MACjE,SAAA,EAAW,gBAAA,CAAiB,SAAA,IAAa,aAAA,CAAc,SAAA;AAAA,MACvD,MAAA,EAAQ,gBAAA,CAAiB,MAAA,IAAU,aAAA,CAAc;AAAA,KACnD;AAEA,IAAA,OAAO,aAAA,CAAc,GAAA,EAAK,SAAA,EAAW,YAAA,EAAc,SAAS,CAAA;AAAA,EAC9D,CAAA;AACF;AAgBA,eAAsB,UAAA,CACpB,GAAA,EACA,SAAA,EACA,UAAA,EACe;AACf,EAAA,MAAM,SAAA,GAAY,IAAI,QAAA,EAAU,SAAA;AAEhC,EAAA,IAAI,SAAA,EAAW;AACb,IAAA,MAAM,SAAA,CAAU,MAAM,SAAA,EAAW;AAAA,MAC/B,GAAG,UAAA;AAAA,MACH,SAAA,EAAA,iBAAW,IAAI,IAAA,EAAK,EAAE,WAAA;AAAY,KACnC,CAAA;AAAA,EACH;AACF","file":"index.js","sourcesContent":["/**\n * Analytics Wrapper\n *\n * Optional helper for wrapping operations with analytics events.\n * You can always use ctx.platform.analytics.track() directly - this is just convenience.\n *\n * @example\n * ```typescript\n * import { withAnalytics } from '@kb-labs/shared-command-kit';\n *\n * const result = await withAnalytics(ctx, 'mind.query', {\n * started: { queryId, text, mode },\n * completed: (result) => ({ tokensIn: result.tokensIn, tokensOut: result.tokensOut }),\n * failed: (error) => ({ errorMessage: error.message }),\n * }, async () => {\n * return await executeQuery(...);\n * });\n * ```\n */\n\nimport type { IAnalytics } from '@kb-labs/core-platform';\n\n/**\n * Context with optional analytics\n */\nexport interface AnalyticsContext {\n platform?: {\n analytics?: IAnalytics;\n };\n}\n\n/**\n * Analytics event configuration\n */\nexport interface AnalyticsEvents<TResult> {\n /** Event properties when operation starts */\n started?: Record<string, unknown>;\n /** Event properties when operation completes (can be function of result) */\n completed?: Record<string, unknown> | ((result: TResult) => Record<string, unknown>);\n /** Event properties when operation fails (can be function of error) */\n failed?: Record<string, unknown> | ((error: Error) => Record<string, unknown>);\n}\n\n/**\n * Wrap an async operation with analytics tracking\n *\n * Automatically tracks:\n * - `{eventName}.started` when operation begins\n * - `{eventName}.completed` when operation succeeds\n * - `{eventName}.failed` when operation fails\n *\n * @param ctx - Context with platform.analytics\n * @param eventName - Base event name (e.g., 'mind.query', 'workflow.run')\n * @param events - Event properties for started/completed/failed events\n * @param operation - Async operation to execute\n * @returns Result of the operation\n *\n * @example\n * ```typescript\n * const result = await withAnalytics(ctx, 'mind.query', {\n * started: { queryId: '123', text: 'search query' },\n * completed: (result) => ({\n * tokensIn: result.tokensIn,\n * tokensOut: result.tokensOut,\n * resultsCount: result.results.length,\n * }),\n * failed: (error) => ({\n * errorCode: error.code,\n * errorMessage: error.message,\n * }),\n * }, async () => {\n * return await executeQuery('search query');\n * });\n * ```\n */\nexport async function withAnalytics<TResult>(\n ctx: AnalyticsContext,\n eventName: string,\n events: AnalyticsEvents<TResult>,\n operation: () => Promise<TResult>\n): Promise<TResult> {\n const analytics = ctx.platform?.analytics;\n const startTime = Date.now();\n\n // Track started event\n if (analytics && events.started) {\n await analytics.track(`${eventName}.started`, {\n ...events.started,\n timestamp: new Date().toISOString(),\n });\n }\n\n try {\n // Execute operation\n const result = await operation();\n\n // Track completed event\n if (analytics && events.completed) {\n const completedProps = typeof events.completed === 'function'\n ? events.completed(result)\n : events.completed;\n\n await analytics.track(`${eventName}.completed`, {\n ...completedProps,\n durationMs: Date.now() - startTime,\n timestamp: new Date().toISOString(),\n });\n }\n\n return result;\n } catch (error: unknown) {\n // Track failed event\n if (analytics && events.failed) {\n const failedProps = typeof events.failed === 'function'\n ? events.failed(error as Error)\n : events.failed;\n\n await analytics.track(`${eventName}.failed`, {\n ...failedProps,\n durationMs: Date.now() - startTime,\n timestamp: new Date().toISOString(),\n });\n }\n\n // Re-throw error\n throw error;\n }\n}\n\n/**\n * Create a reusable analytics wrapper for a specific event\n *\n * @param eventName - Base event name\n * @param defaultEvents - Default event properties\n * @returns Function that wraps operations with analytics\n *\n * @example\n * ```typescript\n * const trackQuery = createAnalyticsWrapper('mind.query', {\n * started: { source: 'cli' },\n * completed: (result) => ({ resultsCount: result.results.length }),\n * });\n *\n * // Use multiple times\n * const result1 = await trackQuery(ctx, { text: 'query 1' }, async () => {...});\n * const result2 = await trackQuery(ctx, { text: 'query 2' }, async () => {...});\n * ```\n */\nexport function createAnalyticsWrapper<TResult>(\n eventName: string,\n defaultEvents: AnalyticsEvents<TResult>\n) {\n return async (\n ctx: AnalyticsContext,\n additionalEvents: Partial<AnalyticsEvents<TResult>>,\n operation: () => Promise<TResult>\n ): Promise<TResult> => {\n const mergedEvents: AnalyticsEvents<TResult> = {\n started: { ...defaultEvents.started, ...additionalEvents.started },\n completed: additionalEvents.completed || defaultEvents.completed,\n failed: additionalEvents.failed || defaultEvents.failed,\n };\n\n return withAnalytics(ctx, eventName, mergedEvents, operation);\n };\n}\n\n/**\n * Track a simple event (no wrapping)\n *\n * Convenience helper for tracking single events without wrapping an operation.\n *\n * @param ctx - Context with platform.analytics\n * @param eventName - Event name\n * @param properties - Event properties\n *\n * @example\n * ```typescript\n * await trackEvent(ctx, 'button.clicked', { buttonId: 'submit', page: 'settings' });\n * ```\n */\nexport async function trackEvent(\n ctx: AnalyticsContext,\n eventName: string,\n properties?: Record<string, unknown>\n): Promise<void> {\n const analytics = ctx.platform?.analytics;\n\n if (analytics) {\n await analytics.track(eventName, {\n ...properties,\n timestamp: new Date().toISOString(),\n });\n }\n}\n"]}
|
package/dist/errors/index.js.map
CHANGED
|
@@ -1 +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 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"]}
|
|
1
|
+
{"version":3,"sources":["../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/src/flags/types.ts","../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/src/errors/format-validation.ts","../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/src/errors/format.ts","../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/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/flags/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../src/flags/types.ts","../../src/flags/define.ts","../../src/flags/validate.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @module @kb-labs/shared-command-kit/flags/types\n * Types for flag validation and schema definition\n */\n\n/**\n * Flag type definition\n */\nexport type FlagType = 'boolean' | 'string' | 'number' | 'array';\n\n/**\n * Base flag schema definition\n */\nexport interface BaseFlagSchema<T extends FlagType = FlagType> {\n /** Flag name */\n name?: string;\n /** Flag type */\n type: T;\n /** Short alias (e.g., 'n' for 'dry-run') */\n alias?: string;\n /** Description for help text */\n description?: string;\n /** Default value if flag is not provided */\n default?: unknown;\n /** Whether flag is required */\n required?: boolean;\n /** Flags that conflict with this flag */\n conflicts?: string[];\n /** Flags that this flag depends on */\n dependsOn?: string[];\n /** Flags that are implied when this flag is set */\n implies?: string[] | [string, unknown][];\n // Note: transform is defined in child interfaces with specific types\n}\n\n/**\n * Boolean flag schema\n */\nexport interface BooleanFlagSchema extends BaseFlagSchema<'boolean'> {\n type: 'boolean';\n default?: boolean;\n /** Transform function to apply to the value */\n transform?: (value: boolean) => boolean | Promise<boolean>;\n}\n\n/**\n * String flag schema\n */\nexport interface StringFlagSchema extends BaseFlagSchema<'string'> {\n type: 'string';\n default?: string;\n /** Allowed values (enum) */\n choices?: readonly string[];\n /** Regex pattern for validation */\n pattern?: RegExp;\n /** Minimum string length */\n minLength?: number;\n /** Maximum string length */\n maxLength?: number;\n /** Custom validation function */\n validate?: (value: string) => true | string | Promise<true | string>;\n /** Transform function to apply to the value */\n transform?: (value: string) => string | Promise<string>;\n}\n\n/**\n * Number flag schema\n */\nexport interface NumberFlagSchema extends BaseFlagSchema<'number'> {\n type: 'number';\n default?: number;\n /** Minimum value */\n min?: number;\n /** Maximum value */\n max?: number;\n /** Custom validation function */\n validate?: (value: number) => true | string | Promise<true | string>;\n /** Transform function to apply to the value */\n transform?: (value: number) => number | Promise<number>;\n}\n\n/**\n * Array flag schema\n */\nexport interface ArrayFlagSchema extends BaseFlagSchema<'array'> {\n type: 'array';\n default?: unknown[];\n /** Type of array items */\n items?: 'string' | 'number' | 'boolean';\n /** Minimum array length */\n minLength?: number;\n /** Maximum array length */\n maxLength?: number;\n /** Transform function to apply to the value */\n transform?: (value: unknown[]) => unknown[] | Promise<unknown[]>;\n}\n\n/**\n * Union of all flag schema types\n */\nexport type FlagSchema =\n | BooleanFlagSchema\n | StringFlagSchema\n | NumberFlagSchema\n | ArrayFlagSchema;\n\n/**\n * Flag schema definition object (for defineFlags)\n */\nexport type FlagSchemaDefinition = Record<string, Omit<FlagSchema, 'name'>>;\n\n/**\n * Validation error\n */\nexport class FlagValidationError extends Error {\n constructor(\n public readonly flag: string,\n message: string,\n public readonly value?: unknown,\n public readonly schema?: FlagSchemaDefinition,\n public readonly commandName?: string\n ) {\n super(message);\n this.name = 'FlagValidationError';\n }\n}\n\n/**\n * Validation result\n */\nexport interface ValidationResult<T = Record<string, unknown>> {\n success: boolean;\n data?: T;\n errors?: Array<{\n flag: string;\n message: string;\n value?: unknown;\n }>;\n}\n\n/**\n * Safe validation result (doesn't throw)\n */\nexport interface SafeValidationResult<T = Record<string, unknown>> {\n success: boolean;\n data?: T;\n errors: Array<{\n flag: string;\n message: string;\n value?: unknown;\n }>;\n}\n\n","/**\n * @module @kb-labs/shared-command-kit/flags/define\n * Define flag schemas with automatic type inference\n */\n\nimport type {\n FlagSchemaDefinition,\n BooleanFlagSchema,\n StringFlagSchema,\n NumberFlagSchema,\n ArrayFlagSchema,\n} from './types';\n\n/**\n * Flag schema with type inference\n */\nexport interface FlagSchemaWithInfer<T extends FlagSchemaDefinition> {\n /** Original schema definition */\n readonly schema: T;\n /** Infer TypeScript type from schema */\n infer: InferFlags<T>;\n}\n\n/**\n * Infer TypeScript type from flag schema definition\n */\nexport type InferFlags<T extends FlagSchemaDefinition> = {\n [K in keyof T]: T[K] extends BooleanFlagSchema\n ? T[K]['default'] extends boolean\n ? boolean\n : T[K]['required'] extends true\n ? boolean\n : boolean | undefined\n : T[K] extends StringFlagSchema\n ? T[K]['choices'] extends readonly string[]\n ? T[K]['required'] extends true\n ? T[K]['choices'][number]\n : T[K]['default'] extends string\n ? T[K]['choices'][number]\n : T[K]['choices'][number] | undefined\n : T[K]['required'] extends true\n ? string\n : T[K]['default'] extends string\n ? string\n : string | undefined\n : T[K] extends NumberFlagSchema\n ? T[K]['required'] extends true\n ? number\n : T[K]['default'] extends number\n ? number\n : number | undefined\n : T[K] extends ArrayFlagSchema\n ? T[K]['items'] extends 'string'\n ? string[]\n : T[K]['items'] extends 'number'\n ? number[]\n : T[K]['items'] extends 'boolean'\n ? boolean[]\n : unknown[]\n : unknown;\n};\n\n/**\n * Define a flag schema with automatic type inference\n *\n * @example\n * ```typescript\n * const schema = defineFlags({\n * scope: {\n * type: 'string',\n * required: true,\n * pattern: /^[@a-z0-9-/]+$/i,\n * },\n * 'dry-run': {\n * type: 'boolean',\n * default: false,\n * },\n * });\n *\n * type Flags = typeof schema.infer;\n * // Flags = { scope: string; 'dry-run': boolean }\n * ```\n */\nexport function defineFlags<T extends FlagSchemaDefinition>(\n definition: T\n): FlagSchemaWithInfer<T> {\n return {\n schema: definition,\n infer: {} as InferFlags<T>,\n };\n}\n\n","/**\n * @module @kb-labs/shared-command-kit/flags/validate\n * Validate flags against schema\n */\n\nimport {\n FlagValidationError,\n type FlagSchema,\n type FlagSchemaDefinition,\n type SafeValidationResult,\n} from './types';\nimport type { InferFlags } from './define';\n\n/**\n * Parse and coerce flag value based on type\n */\nfunction coerceValue(value: unknown, type: FlagSchema['type']): unknown {\n if (value === undefined || value === null) {\n return value;\n }\n\n switch (type) {\n case 'boolean':\n if (typeof value === 'boolean') {\n return value;\n }\n if (typeof value === 'string') {\n const lower = value.toLowerCase().trim();\n if (lower === 'true' || lower === '1' || lower === 'yes') {\n return true;\n }\n if (lower === 'false' || lower === '0' || lower === 'no' || lower === '') {\n return false;\n }\n }\n return Boolean(value);\n\n case 'number':\n if (typeof value === 'number') {\n return value;\n }\n if (typeof value === 'string') {\n const parsed = Number(value);\n if (!Number.isNaN(parsed) && Number.isFinite(parsed)) {\n return parsed;\n }\n }\n return Number(value);\n\n case 'array':\n if (Array.isArray(value)) {\n return value;\n }\n if (typeof value === 'string') {\n return value.split(',').map((item) => item.trim());\n }\n return [value];\n\n case 'string':\n return String(value);\n\n default:\n return value;\n }\n}\n\n/**\n * Validate a single flag value against its schema\n */\nasync function validateFlag(\n flagName: string,\n value: unknown,\n schema: FlagSchema\n): Promise<true | string> {\n const { type, required } = schema;\n \n // Type-specific properties (using type guards)\n const choices = 'choices' in schema ? schema.choices : undefined;\n const pattern = 'pattern' in schema ? schema.pattern : undefined;\n const min = 'min' in schema ? schema.min : undefined;\n const max = 'max' in schema ? schema.max : undefined;\n const validate = 'validate' in schema ? schema.validate : undefined;\n const minLength = 'minLength' in schema ? schema.minLength : undefined;\n const maxLength = 'maxLength' in schema ? schema.maxLength : undefined;\n const items = 'items' in schema ? schema.items : undefined;\n const transform = 'transform' in schema ? schema.transform : undefined;\n\n // Check required\n if (required && (value === undefined || value === null || value === '')) {\n return `Flag --${flagName} is required`;\n }\n\n // Skip validation if value is undefined and not required\n if (value === undefined || value === null) {\n return true;\n }\n\n // Coerce value to correct type\n const coerced = coerceValue(value, type);\n\n // Type-specific validation\n switch (type) {\n case 'boolean':\n if (typeof coerced !== 'boolean') {\n return `Flag --${flagName} must be a boolean`;\n }\n break;\n\n case 'string':\n if (typeof coerced !== 'string') {\n return `Flag --${flagName} must be a string`;\n }\n if (minLength !== undefined && coerced.length < minLength) {\n return `Flag --${flagName} must be at least ${minLength} characters long`;\n }\n if (maxLength !== undefined && coerced.length > maxLength) {\n return `Flag --${flagName} must be at most ${maxLength} characters long`;\n }\n if (choices && !choices.includes(coerced)) {\n return `Flag --${flagName} must be one of: ${choices.join(', ')} (got: ${coerced})`;\n }\n if (pattern && !pattern.test(coerced)) {\n return `Flag --${flagName} must match pattern ${pattern.toString()}`;\n }\n if (validate) {\n const stringValidate = validate as (value: string) => true | string | Promise<true | string>;\n const result = await stringValidate(coerced as string);\n if (result !== true) {\n return result;\n }\n }\n break;\n\n case 'number':\n if (typeof coerced !== 'number' || !Number.isFinite(coerced)) {\n return `Flag --${flagName} must be a number`;\n }\n if (min !== undefined && coerced < min) {\n return `Flag --${flagName} must be >= ${min} (got: ${coerced})`;\n }\n if (max !== undefined && coerced > max) {\n return `Flag --${flagName} must be <= ${max} (got: ${coerced})`;\n }\n if (validate) {\n const numberValidate = validate as (value: number) => true | string | Promise<true | string>;\n const result = await numberValidate(coerced as number);\n if (result !== true) {\n return result;\n }\n }\n break;\n\n case 'array':\n if (!Array.isArray(coerced)) {\n return `Flag --${flagName} must be an array`;\n }\n if (minLength !== undefined && coerced.length < minLength) {\n return `Flag --${flagName} must have at least ${minLength} items`;\n }\n if (maxLength !== undefined && coerced.length > maxLength) {\n return `Flag --${flagName} must have at most ${maxLength} items`;\n }\n if (items) {\n for (let i = 0; i < coerced.length; i++) {\n const item = coerced[i];\n if (items === 'string' && typeof item !== 'string') {\n return `Flag --${flagName}[${i}] must be a string`;\n }\n if (items === 'number' && typeof item !== 'number') {\n return `Flag --${flagName}[${i}] must be a number`;\n }\n if (items === 'boolean' && typeof item !== 'boolean') {\n return `Flag --${flagName}[${i}] must be a boolean`;\n }\n }\n }\n break;\n }\n\n return true;\n}\n\n/**\n * Validate flags against schema and return typed result\n *\n * @throws {FlagValidationError} If validation fails and safe mode is not used\n */\nexport async function validateFlags<T extends FlagSchemaDefinition>(\n rawFlags: Record<string, unknown>,\n schemaDefinition: { schema: T } | T\n): Promise<InferFlags<T>> {\n const schema = 'schema' in schemaDefinition ? schemaDefinition.schema : schemaDefinition;\n const errors: Array<{ flag: string; message: string; value?: unknown }> = [];\n const result: Record<string, unknown> = {};\n const flagValues: Record<string, unknown> = { ...rawFlags };\n\n // First pass: apply implies\n for (const [flagName, flagSchema] of Object.entries(schema)) {\n const value = flagValues[flagName];\n if (value !== undefined && value !== null && value !== false && value !== '') {\n const implies = flagSchema.implies;\n if (implies) {\n for (const implied of implies) {\n if (Array.isArray(implied) && implied.length === 2) {\n // [flagName, value] format\n const [impliedFlag, impliedValue] = implied;\n if (flagValues[impliedFlag] === undefined) {\n flagValues[impliedFlag] = impliedValue;\n }\n } else if (typeof implied === 'string') {\n // Just flag name - set to true\n if (flagValues[implied] === undefined) {\n flagValues[implied] = true;\n }\n }\n }\n }\n }\n }\n\n // Second pass: validate each flag\n for (const [flagName, flagSchema] of Object.entries(schema)) {\n const value = flagValues[flagName];\n const schemaWithName: FlagSchema = { ...flagSchema, name: flagName };\n\n // Check conflicts\n const conflicts = flagSchema.conflicts;\n if (conflicts && value !== undefined && value !== null && value !== false && value !== '') {\n for (const conflictingFlag of conflicts) {\n const conflictingValue = flagValues[conflictingFlag];\n if (conflictingValue !== undefined && conflictingValue !== null && conflictingValue !== false && conflictingValue !== '') {\n errors.push({\n flag: flagName,\n message: `Flag --${flagName} conflicts with --${conflictingFlag}`,\n value,\n });\n break;\n }\n }\n if (errors.some(e => e.flag === flagName)) {\n continue;\n }\n }\n\n // Check dependsOn\n const dependsOn = flagSchema.dependsOn;\n if (dependsOn && value !== undefined && value !== null && value !== '') {\n for (const dependency of dependsOn) {\n const dependencyValue = flagValues[dependency];\n if (dependencyValue === undefined || dependencyValue === null || dependencyValue === '') {\n errors.push({\n flag: flagName,\n message: `Flag --${flagName} depends on --${dependency}`,\n value,\n });\n break;\n }\n }\n if (errors.some(e => e.flag === flagName)) {\n continue;\n }\n }\n\n // Check required\n if (flagSchema.required && (value === undefined || value === null || value === '')) {\n errors.push({\n flag: flagName,\n message: `Flag --${flagName} is required`,\n value,\n });\n continue;\n }\n\n // Apply default if value is missing\n const finalValue = value !== undefined ? value : flagSchema.default;\n\n // Skip validation if value is undefined and not required\n if (finalValue === undefined && !flagSchema.required) {\n continue;\n }\n\n // Validate flag\n const validationResult = await validateFlag(flagName, finalValue, schemaWithName);\n if (validationResult !== true) {\n errors.push({\n flag: flagName,\n message: validationResult,\n value: finalValue,\n });\n continue;\n }\n\n // Apply transform if present\n let transformedValue = coerceValue(finalValue, flagSchema.type);\n const transform = flagSchema.transform;\n if (transform) {\n transformedValue = await transform(transformedValue);\n }\n\n // Store value\n result[flagName] = transformedValue;\n }\n\n // Check for unknown flags (optional - could be enabled via option)\n // for (const flagName of Object.keys(rawFlags)) {\n // if (!(flagName in schema)) {\n // errors.push({\n // flag: flagName,\n // message: `Unknown flag: --${flagName}`,\n // value: rawFlags[flagName],\n // });\n // }\n // }\n\n if (errors.length > 0) {\n const firstError = errors[0]!;\n throw new FlagValidationError(\n firstError.flag,\n firstError.message,\n firstError.value,\n schema as FlagSchemaDefinition // Pass schema for usage generation\n );\n }\n\n return result as InferFlags<T>;\n}\n\n/**\n * Safe version of validateFlags that doesn't throw\n */\nexport async function validateFlagsSafe<T extends FlagSchemaDefinition>(\n rawFlags: Record<string, unknown>,\n schemaDefinition: { schema: T } | T\n): Promise<SafeValidationResult<InferFlags<T>>> {\n try {\n const data = await validateFlags(rawFlags, schemaDefinition);\n return {\n success: true,\n data,\n errors: [],\n };\n } catch (error) {\n if (error instanceof FlagValidationError) {\n return {\n success: false,\n errors: [\n {\n flag: error.flag,\n message: error.message,\n value: error.value,\n },\n ],\n };\n }\n throw error;\n }\n}\n\n"]}
|
|
1
|
+
{"version":3,"sources":["../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/src/flags/types.ts","../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/src/flags/define.ts","../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/src/flags/validate.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @module @kb-labs/shared-command-kit/flags/types\n * Types for flag validation and schema definition\n */\n\n/**\n * Flag type definition\n */\nexport type FlagType = 'boolean' | 'string' | 'number' | 'array';\n\n/**\n * Base flag schema definition\n */\nexport interface BaseFlagSchema<T extends FlagType = FlagType> {\n /** Flag name */\n name?: string;\n /** Flag type */\n type: T;\n /** Short alias (e.g., 'n' for 'dry-run') */\n alias?: string;\n /** Description for help text */\n description?: string;\n /** Default value if flag is not provided */\n default?: unknown;\n /** Whether flag is required */\n required?: boolean;\n /** Flags that conflict with this flag */\n conflicts?: string[];\n /** Flags that this flag depends on */\n dependsOn?: string[];\n /** Flags that are implied when this flag is set */\n implies?: string[] | [string, unknown][];\n // Note: transform is defined in child interfaces with specific types\n}\n\n/**\n * Boolean flag schema\n */\nexport interface BooleanFlagSchema extends BaseFlagSchema<'boolean'> {\n type: 'boolean';\n default?: boolean;\n /** Transform function to apply to the value */\n transform?: (value: boolean) => boolean | Promise<boolean>;\n}\n\n/**\n * String flag schema\n */\nexport interface StringFlagSchema extends BaseFlagSchema<'string'> {\n type: 'string';\n default?: string;\n /** Allowed values (enum) */\n choices?: readonly string[];\n /** Regex pattern for validation */\n pattern?: RegExp;\n /** Minimum string length */\n minLength?: number;\n /** Maximum string length */\n maxLength?: number;\n /** Custom validation function */\n validate?: (value: string) => true | string | Promise<true | string>;\n /** Transform function to apply to the value */\n transform?: (value: string) => string | Promise<string>;\n}\n\n/**\n * Number flag schema\n */\nexport interface NumberFlagSchema extends BaseFlagSchema<'number'> {\n type: 'number';\n default?: number;\n /** Minimum value */\n min?: number;\n /** Maximum value */\n max?: number;\n /** Custom validation function */\n validate?: (value: number) => true | string | Promise<true | string>;\n /** Transform function to apply to the value */\n transform?: (value: number) => number | Promise<number>;\n}\n\n/**\n * Array flag schema\n */\nexport interface ArrayFlagSchema extends BaseFlagSchema<'array'> {\n type: 'array';\n default?: unknown[];\n /** Type of array items */\n items?: 'string' | 'number' | 'boolean';\n /** Minimum array length */\n minLength?: number;\n /** Maximum array length */\n maxLength?: number;\n /** Transform function to apply to the value */\n transform?: (value: unknown[]) => unknown[] | Promise<unknown[]>;\n}\n\n/**\n * Union of all flag schema types\n */\nexport type FlagSchema =\n | BooleanFlagSchema\n | StringFlagSchema\n | NumberFlagSchema\n | ArrayFlagSchema;\n\n/**\n * Flag schema definition object (for defineFlags)\n */\nexport type FlagSchemaDefinition = Record<string, Omit<FlagSchema, 'name'>>;\n\n/**\n * Validation error\n */\nexport class FlagValidationError extends Error {\n constructor(\n public readonly flag: string,\n message: string,\n public readonly value?: unknown,\n public readonly schema?: FlagSchemaDefinition,\n public readonly commandName?: string\n ) {\n super(message);\n this.name = 'FlagValidationError';\n }\n}\n\n/**\n * Validation result\n */\nexport interface ValidationResult<T = Record<string, unknown>> {\n success: boolean;\n data?: T;\n errors?: Array<{\n flag: string;\n message: string;\n value?: unknown;\n }>;\n}\n\n/**\n * Safe validation result (doesn't throw)\n */\nexport interface SafeValidationResult<T = Record<string, unknown>> {\n success: boolean;\n data?: T;\n errors: Array<{\n flag: string;\n message: string;\n value?: unknown;\n }>;\n}\n\n","/**\n * @module @kb-labs/shared-command-kit/flags/define\n * Define flag schemas with automatic type inference\n */\n\nimport type {\n FlagSchemaDefinition,\n BooleanFlagSchema,\n StringFlagSchema,\n NumberFlagSchema,\n ArrayFlagSchema,\n} from './types';\n\n/**\n * Flag schema with type inference\n */\nexport interface FlagSchemaWithInfer<T extends FlagSchemaDefinition> {\n /** Original schema definition */\n readonly schema: T;\n /** Infer TypeScript type from schema */\n infer: InferFlags<T>;\n}\n\n/**\n * Infer TypeScript type from flag schema definition\n */\nexport type InferFlags<T extends FlagSchemaDefinition> = {\n [K in keyof T]: T[K] extends BooleanFlagSchema\n ? T[K]['default'] extends boolean\n ? boolean\n : T[K]['required'] extends true\n ? boolean\n : boolean | undefined\n : T[K] extends StringFlagSchema\n ? T[K]['choices'] extends readonly string[]\n ? T[K]['required'] extends true\n ? T[K]['choices'][number]\n : T[K]['default'] extends string\n ? T[K]['choices'][number]\n : T[K]['choices'][number] | undefined\n : T[K]['required'] extends true\n ? string\n : T[K]['default'] extends string\n ? string\n : string | undefined\n : T[K] extends NumberFlagSchema\n ? T[K]['required'] extends true\n ? number\n : T[K]['default'] extends number\n ? number\n : number | undefined\n : T[K] extends ArrayFlagSchema\n ? T[K]['items'] extends 'string'\n ? string[]\n : T[K]['items'] extends 'number'\n ? number[]\n : T[K]['items'] extends 'boolean'\n ? boolean[]\n : unknown[]\n : unknown;\n};\n\n/**\n * Define a flag schema with automatic type inference\n *\n * @example\n * ```typescript\n * const schema = defineFlags({\n * scope: {\n * type: 'string',\n * required: true,\n * pattern: /^[@a-z0-9-/]+$/i,\n * },\n * 'dry-run': {\n * type: 'boolean',\n * default: false,\n * },\n * });\n *\n * type Flags = typeof schema.infer;\n * // Flags = { scope: string; 'dry-run': boolean }\n * ```\n */\nexport function defineFlags<T extends FlagSchemaDefinition>(\n definition: T\n): FlagSchemaWithInfer<T> {\n return {\n schema: definition,\n infer: {} as InferFlags<T>,\n };\n}\n\n","/**\n * @module @kb-labs/shared-command-kit/flags/validate\n * Validate flags against schema\n */\n\nimport {\n FlagValidationError,\n type FlagSchema,\n type FlagSchemaDefinition,\n type SafeValidationResult,\n} from './types';\nimport type { InferFlags } from './define';\n\n/**\n * Parse and coerce flag value based on type\n */\nfunction coerceValue(value: unknown, type: FlagSchema['type']): unknown {\n if (value === undefined || value === null) {\n return value;\n }\n\n switch (type) {\n case 'boolean':\n if (typeof value === 'boolean') {\n return value;\n }\n if (typeof value === 'string') {\n const lower = value.toLowerCase().trim();\n if (lower === 'true' || lower === '1' || lower === 'yes') {\n return true;\n }\n if (lower === 'false' || lower === '0' || lower === 'no' || lower === '') {\n return false;\n }\n }\n return Boolean(value);\n\n case 'number':\n if (typeof value === 'number') {\n return value;\n }\n if (typeof value === 'string') {\n const parsed = Number(value);\n if (!Number.isNaN(parsed) && Number.isFinite(parsed)) {\n return parsed;\n }\n }\n return Number(value);\n\n case 'array':\n if (Array.isArray(value)) {\n return value;\n }\n if (typeof value === 'string') {\n return value.split(',').map((item) => item.trim());\n }\n return [value];\n\n case 'string':\n return String(value);\n\n default:\n return value;\n }\n}\n\n/**\n * Validate a single flag value against its schema\n */\nasync function validateFlag(\n flagName: string,\n value: unknown,\n schema: FlagSchema\n): Promise<true | string> {\n const { type, required } = schema;\n \n // Type-specific properties (using type guards)\n const choices = 'choices' in schema ? schema.choices : undefined;\n const pattern = 'pattern' in schema ? schema.pattern : undefined;\n const min = 'min' in schema ? schema.min : undefined;\n const max = 'max' in schema ? schema.max : undefined;\n const validate = 'validate' in schema ? schema.validate : undefined;\n const minLength = 'minLength' in schema ? schema.minLength : undefined;\n const maxLength = 'maxLength' in schema ? schema.maxLength : undefined;\n const items = 'items' in schema ? schema.items : undefined;\n const transform = 'transform' in schema ? schema.transform : undefined;\n\n // Check required\n if (required && (value === undefined || value === null || value === '')) {\n return `Flag --${flagName} is required`;\n }\n\n // Skip validation if value is undefined and not required\n if (value === undefined || value === null) {\n return true;\n }\n\n // Coerce value to correct type\n const coerced = coerceValue(value, type);\n\n // Type-specific validation\n switch (type) {\n case 'boolean':\n if (typeof coerced !== 'boolean') {\n return `Flag --${flagName} must be a boolean`;\n }\n break;\n\n case 'string':\n if (typeof coerced !== 'string') {\n return `Flag --${flagName} must be a string`;\n }\n if (minLength !== undefined && coerced.length < minLength) {\n return `Flag --${flagName} must be at least ${minLength} characters long`;\n }\n if (maxLength !== undefined && coerced.length > maxLength) {\n return `Flag --${flagName} must be at most ${maxLength} characters long`;\n }\n if (choices && !choices.includes(coerced)) {\n return `Flag --${flagName} must be one of: ${choices.join(', ')} (got: ${coerced})`;\n }\n if (pattern && !pattern.test(coerced)) {\n return `Flag --${flagName} must match pattern ${pattern.toString()}`;\n }\n if (validate) {\n const stringValidate = validate as (value: string) => true | string | Promise<true | string>;\n const result = await stringValidate(coerced as string);\n if (result !== true) {\n return result;\n }\n }\n break;\n\n case 'number':\n if (typeof coerced !== 'number' || !Number.isFinite(coerced)) {\n return `Flag --${flagName} must be a number`;\n }\n if (min !== undefined && coerced < min) {\n return `Flag --${flagName} must be >= ${min} (got: ${coerced})`;\n }\n if (max !== undefined && coerced > max) {\n return `Flag --${flagName} must be <= ${max} (got: ${coerced})`;\n }\n if (validate) {\n const numberValidate = validate as (value: number) => true | string | Promise<true | string>;\n const result = await numberValidate(coerced as number);\n if (result !== true) {\n return result;\n }\n }\n break;\n\n case 'array':\n if (!Array.isArray(coerced)) {\n return `Flag --${flagName} must be an array`;\n }\n if (minLength !== undefined && coerced.length < minLength) {\n return `Flag --${flagName} must have at least ${minLength} items`;\n }\n if (maxLength !== undefined && coerced.length > maxLength) {\n return `Flag --${flagName} must have at most ${maxLength} items`;\n }\n if (items) {\n for (let i = 0; i < coerced.length; i++) {\n const item = coerced[i];\n if (items === 'string' && typeof item !== 'string') {\n return `Flag --${flagName}[${i}] must be a string`;\n }\n if (items === 'number' && typeof item !== 'number') {\n return `Flag --${flagName}[${i}] must be a number`;\n }\n if (items === 'boolean' && typeof item !== 'boolean') {\n return `Flag --${flagName}[${i}] must be a boolean`;\n }\n }\n }\n break;\n }\n\n return true;\n}\n\n/**\n * Validate flags against schema and return typed result\n *\n * @throws {FlagValidationError} If validation fails and safe mode is not used\n */\nexport async function validateFlags<T extends FlagSchemaDefinition>(\n rawFlags: Record<string, unknown>,\n schemaDefinition: { schema: T } | T\n): Promise<InferFlags<T>> {\n const schema = 'schema' in schemaDefinition ? schemaDefinition.schema : schemaDefinition;\n const errors: Array<{ flag: string; message: string; value?: unknown }> = [];\n const result: Record<string, unknown> = {};\n const flagValues: Record<string, unknown> = { ...rawFlags };\n\n // First pass: apply implies\n for (const [flagName, flagSchema] of Object.entries(schema)) {\n const value = flagValues[flagName];\n if (value !== undefined && value !== null && value !== false && value !== '') {\n const implies = flagSchema.implies;\n if (implies) {\n for (const implied of implies) {\n if (Array.isArray(implied) && implied.length === 2) {\n // [flagName, value] format\n const [impliedFlag, impliedValue] = implied;\n if (flagValues[impliedFlag] === undefined) {\n flagValues[impliedFlag] = impliedValue;\n }\n } else if (typeof implied === 'string') {\n // Just flag name - set to true\n if (flagValues[implied] === undefined) {\n flagValues[implied] = true;\n }\n }\n }\n }\n }\n }\n\n // Second pass: validate each flag\n for (const [flagName, flagSchema] of Object.entries(schema)) {\n const value = flagValues[flagName];\n const schemaWithName: FlagSchema = { ...flagSchema, name: flagName };\n\n // Check conflicts\n const conflicts = flagSchema.conflicts;\n if (conflicts && value !== undefined && value !== null && value !== false && value !== '') {\n for (const conflictingFlag of conflicts) {\n const conflictingValue = flagValues[conflictingFlag];\n if (conflictingValue !== undefined && conflictingValue !== null && conflictingValue !== false && conflictingValue !== '') {\n errors.push({\n flag: flagName,\n message: `Flag --${flagName} conflicts with --${conflictingFlag}`,\n value,\n });\n break;\n }\n }\n if (errors.some(e => e.flag === flagName)) {\n continue;\n }\n }\n\n // Check dependsOn\n const dependsOn = flagSchema.dependsOn;\n if (dependsOn && value !== undefined && value !== null && value !== '') {\n for (const dependency of dependsOn) {\n const dependencyValue = flagValues[dependency];\n if (dependencyValue === undefined || dependencyValue === null || dependencyValue === '') {\n errors.push({\n flag: flagName,\n message: `Flag --${flagName} depends on --${dependency}`,\n value,\n });\n break;\n }\n }\n if (errors.some(e => e.flag === flagName)) {\n continue;\n }\n }\n\n // Check required\n if (flagSchema.required && (value === undefined || value === null || value === '')) {\n errors.push({\n flag: flagName,\n message: `Flag --${flagName} is required`,\n value,\n });\n continue;\n }\n\n // Apply default if value is missing\n const finalValue = value !== undefined ? value : flagSchema.default;\n\n // Skip validation if value is undefined and not required\n if (finalValue === undefined && !flagSchema.required) {\n continue;\n }\n\n // Validate flag\n const validationResult = await validateFlag(flagName, finalValue, schemaWithName);\n if (validationResult !== true) {\n errors.push({\n flag: flagName,\n message: validationResult,\n value: finalValue,\n });\n continue;\n }\n\n // Apply transform if present\n let transformedValue = coerceValue(finalValue, flagSchema.type);\n const transform = flagSchema.transform;\n if (transform) {\n transformedValue = await transform(transformedValue);\n }\n\n // Store value\n result[flagName] = transformedValue;\n }\n\n // Check for unknown flags (optional - could be enabled via option)\n // for (const flagName of Object.keys(rawFlags)) {\n // if (!(flagName in schema)) {\n // errors.push({\n // flag: flagName,\n // message: `Unknown flag: --${flagName}`,\n // value: rawFlags[flagName],\n // });\n // }\n // }\n\n if (errors.length > 0) {\n const firstError = errors[0]!;\n throw new FlagValidationError(\n firstError.flag,\n firstError.message,\n firstError.value,\n schema as FlagSchemaDefinition // Pass schema for usage generation\n );\n }\n\n return result as InferFlags<T>;\n}\n\n/**\n * Safe version of validateFlags that doesn't throw\n */\nexport async function validateFlagsSafe<T extends FlagSchemaDefinition>(\n rawFlags: Record<string, unknown>,\n schemaDefinition: { schema: T } | T\n): Promise<SafeValidationResult<InferFlags<T>>> {\n try {\n const data = await validateFlags(rawFlags, schemaDefinition);\n return {\n success: true,\n data,\n errors: [],\n };\n } catch (error) {\n if (error instanceof FlagValidationError) {\n return {\n success: false,\n errors: [\n {\n flag: error.flag,\n message: error.message,\n value: error.value,\n },\n ],\n };\n }\n throw error;\n }\n}\n\n"]}
|
|
@@ -1 +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-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"]}
|
|
1
|
+
{"version":3,"sources":["../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/src/helpers/use-platform.ts","../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/src/helpers/index.ts","../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/src/helpers/use-config.ts","../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/src/helpers/use-logger.ts","../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/src/helpers/use-llm.ts","../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/src/helpers/use-embeddings.ts","../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/src/helpers/use-vector-store.ts","../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/src/helpers/use-analytics.ts","../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/src/helpers/use-storage.ts","../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/src/helpers/use-cache.ts","../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/src/helpers/use-document-database.ts","../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/src/helpers/use-kv-store.ts","../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/src/helpers/use-notifications.ts","../../../home/runner/work/kb-labs/kb-labs/shared/command-kit/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"]}
|