@kb-labs/shared-command-kit 1.0.0

package/dist/helpers/index.d.ts

@@ -0,0 +1,650 @@
+import { platform } from '@kb-labs/core-runtime';
+export { PluginContextV3 } from '@kb-labs/plugin-contracts';
+import { ILogger, UseLLMOptions, ILLM, LLMTier, IEmbeddings, IVectorStore, IAnalytics, IStorage, ICache } from '@kb-labs/core-platform';
+export { LLMTier, UseLLMOptions } from '@kb-labs/core-platform';
+
+/**
+ * @module @kb-labs/shared-command-kit/helpers/use-platform
+ * Global platform singleton access helper
+ *
+ * Provides clean access to platform services without context drilling.
+ * Similar to React hooks pattern, but for KB Labs platform.
+ *
+ * @example
+ * ```typescript
+ * import { usePlatform } from '@kb-labs/shared-command-kit';
+ *
+ * // In any command handler
+ * async handler(ctx, argv, flags) {
+ *   const platform = usePlatform();
+ *
+ *   if (platform.llm) {
+ *     const result = await platform.llm.complete('prompt');
+ *   }
+ *
+ *   await platform.logger.info('Task completed');
+ * }
+ * ```
+ */
+
+/**
+ * Access global platform singleton
+ *
+ * Returns the initialized platform object with all registered adapters.
+ * This is the single source of truth for platform services.
+ *
+ * **What's available:**
+ * - `platform.llm` - LLM adapter (OpenAI, Anthropic, etc.)
+ * - `platform.embeddings` - Embeddings adapter
+ * - `platform.vectorStore` - Vector storage (Qdrant, local, etc.)
+ * - `platform.storage` - File/blob storage
+ * - `platform.cache` - Caching layer
+ * - `platform.analytics` - Analytics/telemetry
+ * - `platform.logger` - Structured logging
+ * - `platform.eventBus` - Event system
+ * - `platform.workflows` - Workflow engine
+ * - `platform.jobs` - Background jobs
+ * - `platform.cron` - Scheduled tasks
+ * - `platform.resources` - Resource management
+ * - `platform.invoke` - Plugin invocation
+ * - `platform.artifacts` - Build artifacts
+ *
+ * **Graceful degradation:**
+ * Always check if adapter is available before using:
+ * ```typescript
+ * const platform = usePlatform();
+ * if (platform.llm) {
+ *   // Use LLM
+ * } else {
+ *   // Fallback logic
+ * }
+ * ```
+ *
+ * **Multi-tenancy:**
+ * Currently returns global singleton (single-tenant).
+ * Future: Will support tenant-scoped platform via AsyncLocalStorage.
+ *
+ * @returns Global platform singleton
+ */
+declare function usePlatform(): typeof platform;
+/**
+ * Check if specific platform adapter is configured
+ *
+ * Useful for conditional logic based on available services.
+ *
+ * @param adapterName - Name of the adapter to check
+ * @returns true if adapter is configured and available
+ *
+ * @example
+ * ```typescript
+ * if (isPlatformConfigured('llm')) {
+ *   // Use LLM-powered feature
+ * } else {
+ *   // Use deterministic fallback
+ * }
+ * ```
+ */
+declare function isPlatformConfigured(adapterName: keyof typeof platform): boolean;
+
+/**
+ * @module @kb-labs/shared-command-kit/helpers/use-config
+ * Global config access helper
+ *
+ * Provides clean access to product-specific configuration without context drilling.
+ * Similar to React hooks pattern, but for KB Labs config.
+ *
+ * @example
+ * ```typescript
+ * import { useConfig } from '@kb-labs/shared-command-kit';
+ *
+ * // In any command handler
+ * async handler(ctx, argv, flags) {
+ *   const config = await useConfig('mind');
+ *
+ *   if (config) {
+ *     const scopes = config.scopes;
+ *     // Use config...
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Access product-specific configuration from kb.config.json
+ *
+ * Returns ONLY the config for the specified product and profile.
+ * Uses platform.config adapter (works across parent/child processes via IPC).
+ * Supports both Profiles v2 and legacy config structures.
+ *
+ * **Security:** This function returns ONLY the product-specific config,
+ * not the entire kb.config.json. This prevents cross-product config access.
+ *
+ * **Auto-detection:** If productId is not provided, it's automatically inferred
+ * from the plugin's manifest.configSection field (passed via execution context).
+ *
+ * **Profiles v2 structure:**
+ * ```json
+ * {
+ *   "profiles": [
+ *     {
+ *       "id": "default",
+ *       "products": {
+ *         "mind": { "scopes": [...] },
+ *         "workflow": { "maxConcurrency": 10 }
+ *       }
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * **Legacy structure:**
+ * ```json
+ * {
+ *   "knowledge": { "scopes": [...] },  // for "mind" product
+ *   "workflow": { "maxConcurrency": 10 }
+ * }
+ * ```
+ *
+ * @param productId - Product identifier (e.g., 'mind', 'workflow', 'plugins'). Optional - auto-detected from context.
+ * @param profileId - Profile identifier (defaults to 'default' or KB_PROFILE env var)
+ * @returns Promise resolving to product-specific config or undefined
+ *
+ * @example
+ * ```typescript
+ * // Auto-detect from context (recommended)
+ * const config = await useConfig();
+ *
+ * // Explicit product ID
+ * const mindConfig = await useConfig('mind');
+ * if (mindConfig?.scopes) {
+ *   // Use scopes
+ * }
+ *
+ * // With explicit profile
+ * const workflowConfig = await useConfig('workflow', 'production');
+ * ```
+ */
+declare function useConfig<T = any>(productId?: string, profileId?: string): Promise<T | undefined>;
+
+/**
+ * @module @kb-labs/shared-command-kit/helpers/use-logger
+ * Global logger access helper
+ *
+ * Provides clean access to structured logging without context drilling.
+ *
+ * @example
+ * ```typescript
+ * import { useLogger } from '@kb-labs/shared-command-kit';
+ *
+ * async handler(ctx, argv, flags) {
+ *   const logger = useLogger();
+ *
+ *   await logger.info('Processing started');
+ *   await logger.debug('Details', { userId: 123 });
+ *   await logger.error('Failed', { error: err });
+ * }
+ * ```
+ */
+
+/**
+ * Access global logger
+ *
+ * Returns the platform logger with structured logging capabilities.
+ * Supports child loggers with additional context.
+ *
+ * **Methods:**
+ * - `logger.trace(message, meta?)` - Trace-level logs (most verbose)
+ * - `logger.debug(message, meta?)` - Debug-level logs
+ * - `logger.info(message, meta?)` - Info-level logs
+ * - `logger.warn(message, meta?)` - Warning-level logs
+ * - `logger.error(message, meta?)` - Error-level logs
+ * - `logger.child(meta)` - Create child logger with additional context
+ *
+ * @returns Platform logger instance
+ *
+ * @example
+ * ```typescript
+ * const logger = useLogger();
+ *
+ * await logger.info('Task started', { taskId: '123' });
+ * await logger.error('Task failed', { taskId: '123', error: err.message });
+ *
+ * // Child logger with persistent context
+ * const taskLogger = logger.child({ taskId: '123', userId: 'user-1' });
+ * await taskLogger.info('Step 1 completed');
+ * await taskLogger.info('Step 2 completed');
+ * ```
+ */
+declare function useLogger(): ILogger;
+/**
+ * Create child logger with additional context
+ *
+ * Useful for scoped logging within a specific operation.
+ *
+ * @param context - Additional context to attach to all log entries
+ * @returns Child logger with persistent context
+ *
+ * @example
+ * ```typescript
+ * const logger = useLoggerWithContext({ operation: 'release', version: '1.0.0' });
+ *
+ * await logger.info('Started');  // Automatically includes operation + version
+ * await logger.info('Completed');
+ * ```
+ */
+declare function useLoggerWithContext(context: Record<string, unknown>): ILogger;
+
+/**
+ * @module @kb-labs/shared-command-kit/helpers/use-llm
+ * Global LLM access helper with tier-based model selection.
+ *
+ * Provides clean access to LLM with adaptive tier routing.
+ * Plugins specify tiers (small/medium/large), platform resolves to actual models.
+ *
+ * @example
+ * ```typescript
+ * import { useLLM } from '@kb-labs/shared-command-kit';
+ *
+ * async handler(ctx, argv, flags) {
+ *   // Simple usage (uses configured default tier)
+ *   const llm = useLLM();
+ *
+ *   // Request specific tier (platform adapts if needed)
+ *   const llm = useLLM({ tier: 'small' });   // Simple tasks
+ *   const llm = useLLM({ tier: 'large' });   // Complex tasks
+ *
+ *   // Request capabilities
+ *   const llm = useLLM({ tier: 'medium', capabilities: ['coding'] });
+ *
+ *   if (llm) {
+ *     const result = await llm.complete('Explain this code');
+ *     console.log(result.content);
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Access global LLM adapter with tier-based selection.
+ *
+ * Platform automatically adapts to available models:
+ * - If plugin requests 'small' but 'medium' configured → uses 'medium' (escalation)
+ * - If plugin requests 'large' but 'medium' configured → uses 'medium' with warning (degradation)
+ *
+ * **Tiers are user-defined slots:**
+ * - `small`  - Plugin says: "This task is simple"
+ * - `medium` - Plugin says: "Standard task"
+ * - `large`  - Plugin says: "Complex task, need maximum quality"
+ *
+ * User decides what model maps to each tier in their config.
+ *
+ * @param options - Optional tier and capability requirements
+ * @returns LLM adapter or undefined if not configured
+ *
+ * @example
+ * ```typescript
+ * // Simple usage (uses configured default)
+ * const llm = useLLM();
+ *
+ * // Request specific tier
+ * const llm = useLLM({ tier: 'small' });   // Simple tasks
+ * const llm = useLLM({ tier: 'large' });   // Complex tasks
+ *
+ * // Request capabilities
+ * const llm = useLLM({ tier: 'medium', capabilities: ['coding'] });
+ * const llm = useLLM({ capabilities: ['vision'] });
+ *
+ * if (llm) {
+ *   const result = await llm.complete('Generate commit message');
+ *   console.log(result.content);
+ * }
+ * ```
+ */
+declare function useLLM(options?: UseLLMOptions): ILLM | undefined;
+/**
+ * Check if LLM is available.
+ *
+ * Useful for conditional logic (LLM-powered vs deterministic fallback).
+ *
+ * @returns true if LLM is configured and ready
+ *
+ * @example
+ * ```typescript
+ * if (isLLMAvailable()) {
+ *   const summary = await generateWithLLM(data);
+ * } else {
+ *   const summary = generateDeterministic(data);
+ * }
+ * ```
+ */
+declare function isLLMAvailable(): boolean;
+/**
+ * Get configured LLM tier.
+ *
+ * Useful for diagnostics and logging.
+ *
+ * @returns Configured tier or undefined if LLM not available/not a router
+ *
+ * @example
+ * ```typescript
+ * const tier = getLLMTier();
+ * console.log(`Using LLM tier: ${tier ?? 'default'}`);
+ * ```
+ */
+declare function getLLMTier(): LLMTier | undefined;
+
+/**
+ * @module @kb-labs/shared-command-kit/helpers/use-embeddings
+ * Global Embeddings access helper
+ */
+
+/**
+ * Access global Embeddings adapter
+ *
+ * Returns the platform embeddings adapter (OpenAI, etc.).
+ * Returns undefined if embeddings is not configured (graceful degradation).
+ *
+ * @returns Embeddings adapter or undefined if not configured
+ *
+ * @example
+ * ```typescript
+ * const embeddings = useEmbeddings();
+ *
+ * if (embeddings) {
+ *   const vector = await embeddings.embed('Hello, world!');
+ *   console.log(vector.length); // e.g., 1536 for OpenAI
+ * }
+ * ```
+ */
+declare function useEmbeddings(): IEmbeddings | undefined;
+/**
+ * Check if Embeddings is available
+ *
+ * @returns true if embeddings is configured and ready
+ *
+ * @example
+ * ```typescript
+ * if (isEmbeddingsAvailable()) {
+ *   const vector = await embeddings.embed(text);
+ * } else {
+ *   // Use deterministic fallback
+ * }
+ * ```
+ */
+declare function isEmbeddingsAvailable(): boolean;
+
+/**
+ * @module @kb-labs/shared-command-kit/helpers/use-vector-store
+ * Global VectorStore access helper
+ */
+
+/**
+ * Access global VectorStore adapter
+ *
+ * Returns the platform vector store adapter (Qdrant, local, etc.).
+ * Returns undefined if vectorStore is not configured (graceful degradation).
+ *
+ * @returns VectorStore adapter or undefined if not configured
+ *
+ * @example
+ * ```typescript
+ * const vectorStore = useVectorStore();
+ *
+ * if (vectorStore) {
+ *   await vectorStore.upsert([{ id: '1', vector: [0.1, 0.2], metadata: {} }]);
+ *   const results = await vectorStore.search([0.1, 0.2], 10);
+ * }
+ * ```
+ */
+declare function useVectorStore(): IVectorStore | undefined;
+/**
+ * Check if VectorStore is available
+ *
+ * @returns true if vectorStore is configured and ready
+ *
+ * @example
+ * ```typescript
+ * if (isVectorStoreAvailable()) {
+ *   await vectorStore.upsert(records);
+ * } else {
+ *   // Use local fallback
+ * }
+ * ```
+ */
+declare function isVectorStoreAvailable(): boolean;
+
+/**
+ * @module @kb-labs/shared-command-kit/helpers/use-analytics
+ * Global analytics access helper
+ *
+ * Provides clean access to analytics/telemetry without context drilling.
+ *
+ * @example
+ * ```typescript
+ * import { useAnalytics } from '@kb-labs/shared-command-kit';
+ *
+ * async handler(ctx, argv, flags) {
+ *   const analytics = useAnalytics();
+ *
+ *   if (analytics) {
+ *     await analytics.track('release_started', { version: '1.0.0' });
+ *     analytics.metric('release_duration_ms', 1234);
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Access global analytics adapter
+ *
+ * Returns the platform analytics adapter for tracking events and metrics.
+ * Returns undefined if analytics is not configured (graceful degradation).
+ *
+ * **Methods:**
+ * - `analytics.track(event, properties?)` - Track events
+ * - `analytics.metric(name, value, tags?)` - Record metrics
+ *
+ * **Always check availability:**
+ * ```typescript
+ * const analytics = useAnalytics();
+ * if (analytics) {
+ *   await analytics.track('event');
+ * }
+ * ```
+ *
+ * @returns Analytics adapter or undefined if not configured
+ *
+ * @example
+ * ```typescript
+ * const analytics = useAnalytics();
+ *
+ * if (analytics) {
+ *   await analytics.track('command_executed', {
+ *     command: 'release:run',
+ *     duration_ms: 1234,
+ *     success: true,
+ *   });
+ *
+ *   analytics.metric('release_packages_count', 5, {
+ *     project: 'kb-labs',
+ *   });
+ * }
+ * ```
+ */
+declare function useAnalytics(): IAnalytics | undefined;
+/**
+ * Track event with analytics (safe, global singleton)
+ *
+ * Convenience wrapper that uses global platform analytics.
+ * Does nothing if analytics is not configured.
+ *
+ * NOTE: For context-based analytics, use trackEvent() from '../analytics/with-analytics'.
+ * This helper uses global singleton, not request-scoped context.
+ *
+ * @param event - Event name
+ * @param properties - Event properties
+ *
+ * @example
+ * ```typescript
+ * import { trackAnalyticsEvent } from '@kb-labs/shared-command-kit/helpers';
+ *
+ * // No need to check if analytics exists
+ * await trackAnalyticsEvent('release_completed', { version: '1.0.0', packages: 5 });
+ * ```
+ */
+declare function trackAnalyticsEvent(event: string, properties?: Record<string, unknown>): Promise<void>;
+
+/**
+ * @module @kb-labs/shared-command-kit/helpers/use-storage
+ * Global storage access helper
+ *
+ * Provides clean access to file/blob storage adapter.
+ *
+ * @example
+ * ```typescript
+ * import { useStorage } from '@kb-labs/shared-command-kit';
+ *
+ * async handler(ctx, argv, flags) {
+ *   const storage = useStorage();
+ *
+ *   if (storage) {
+ *     await storage.write('path/to/file.txt', 'content');
+ *     const content = await storage.read('path/to/file.txt');
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Access global storage adapter
+ *
+ * Returns the platform storage adapter for file/blob operations.
+ * Returns undefined if storage is not configured (graceful degradation).
+ *
+ * **Methods:**
+ * - `storage.read(path)` - Read file content
+ * - `storage.write(path, content)` - Write file content
+ * - `storage.exists(path)` - Check if file exists
+ * - `storage.delete(path)` - Delete file
+ * - `storage.list(prefix?)` - List files
+ *
+ * **Always check availability:**
+ * ```typescript
+ * const storage = useStorage();
+ * if (storage) {
+ *   await storage.write('file.txt', 'content');
+ * }
+ * ```
+ *
+ * @returns Storage adapter or undefined if not configured
+ *
+ * @example
+ * ```typescript
+ * const storage = useStorage();
+ *
+ * if (storage) {
+ *   // Write file
+ *   await storage.write('releases/v1.0.0.json', JSON.stringify(data));
+ *
+ *   // Read file
+ *   const content = await storage.read('releases/v1.0.0.json');
+ *   const data = JSON.parse(content);
+ *
+ *   // Check existence
+ *   const exists = await storage.exists('releases/v1.0.0.json');
+ *
+ *   // List files
+ *   const files = await storage.list('releases/');
+ * }
+ * ```
+ */
+declare function useStorage(): IStorage | undefined;
+
+/**
+ * @module @kb-labs/shared-command-kit/helpers/use-cache
+ * Global Cache access helper
+ *
+ * Provides clean access to platform cache (Redis, InMemory, or custom adapter).
+ *
+ * @example
+ * ```typescript
+ * import { useCache } from '@kb-labs/shared-command-kit';
+ *
+ * async handler(ctx, argv, flags) {
+ *   const cache = useCache();
+ *
+ *   if (cache) {
+ *     await cache.set('key', { data: 'value' }, 60000); // TTL: 60s
+ *     const value = await cache.get('key');
+ *     console.log(value);
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Access global cache adapter
+ *
+ * Returns the platform cache adapter (Redis, InMemory, or custom).
+ * Returns undefined if cache is not configured (graceful degradation).
+ *
+ * **Methods:**
+ * - `cache.set(key, value, ttlMs?)` - Store value with optional TTL
+ * - `cache.get<T>(key)` - Retrieve value by key
+ * - `cache.delete(key)` - Remove value
+ * - `cache.clear()` - Clear all cached values
+ *
+ * **Always check availability:**
+ * ```typescript
+ * const cache = useCache();
+ * if (cache) {
+ *   await cache.set('query-123', result, 60000);
+ * } else {
+ *   // No caching, compute every time
+ * }
+ * ```
+ *
+ * @returns Cache adapter or undefined if not configured
+ *
+ * @example
+ * ```typescript
+ * const cache = useCache();
+ *
+ * if (cache) {
+ *   // Check cache first
+ *   const cached = await cache.get<QueryResult>('query-123');
+ *   if (cached) {
+ *     return cached;
+ *   }
+ *
+ *   // Compute result
+ *   const result = await expensiveQuery();
+ *
+ *   // Cache for 5 minutes
+ *   await cache.set('query-123', result, 5 * 60 * 1000);
+ *
+ *   return result;
+ * }
+ * ```
+ */
+declare function useCache(): ICache | undefined;
+/**
+ * Check if cache is available
+ *
+ * Useful for conditional logic (cached vs non-cached execution).
+ *
+ * @returns true if cache is configured and ready
+ *
+ * @example
+ * ```typescript
+ * if (isCacheAvailable()) {
+ *   // Use cached results
+ *   const result = await getCachedOrCompute(key);
+ * } else {
+ *   // Compute every time
+ *   const result = await compute();
+ * }
+ * ```
+ */
+declare function isCacheAvailable(): boolean;
+
+export { getLLMTier, isCacheAvailable, isEmbeddingsAvailable, isLLMAvailable, isPlatformConfigured, isVectorStoreAvailable, trackAnalyticsEvent, useAnalytics, useCache, useConfig, useEmbeddings, useLLM, useLogger, useLoggerWithContext, usePlatform, useStorage, useVectorStore };