@kb-labs/shared 1.1.0

package/packages/shared-command-kit/src/helpers/platform.ts

@@ -0,0 +1,335 @@
+/**
+ * @module @kb-labs/shared-command-kit/helpers/platform
+ * Platform service access helpers with graceful error handling.
+ *
+ * These helpers provide convenient access to platform services with automatic
+ * configuration checks and helpful error messages.
+ */
+
+import type { PluginContextV3 as PluginContext } from '@kb-labs/plugin-runtime';
+import type {
+  ILLM,
+  IEmbeddings,
+  IVectorStore,
+  ICache,
+  IStorage,
+  ILogger,
+  IAnalytics,
+  IEventBus,
+  LLMOptions,
+  LLMResponse,
+  VectorSearchResult,
+} from '@kb-labs/core-platform';
+
+/**
+ * Error thrown when required platform service is not configured.
+ */
+export class ServiceNotConfiguredError extends Error {
+  constructor(
+    public readonly service: string,
+    public readonly requiredAdapter?: string
+  ) {
+    super(
+      requiredAdapter
+        ? `Service '${service}' is not configured. Add "${requiredAdapter}" to kb.config.json adapters.`
+        : `Service '${service}' is not configured. Configure it in kb.config.json.`
+    );
+    this.name = 'ServiceNotConfiguredError';
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ADAPTERS (Replaceable Services)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Get LLM service with configuration check.
+ * Throws if LLM is not configured (using NoOp/Mock).
+ *
+ * @param ctx - Plugin context
+ * @returns LLM service
+ * @throws {ServiceNotConfiguredError} If LLM not configured
+ *
+ * @example
+ * ```typescript
+ * const llm = useLLM(ctx);
+ * const response = await llm.complete('Hello, world!');
+ * ```
+ */
+export function useLLM(ctx: PluginContext): ILLM {
+  if (!ctx.platform.llm) {
+    throw new ServiceNotConfiguredError('llm', '@kb-labs/shared-openai');
+  }
+  return ctx.platform.llm;
+}
+
+/**
+ * Get embeddings service with configuration check.
+ * Throws if embeddings are not configured.
+ *
+ * @param ctx - Plugin context
+ * @returns Embeddings service
+ * @throws {ServiceNotConfiguredError} If embeddings not configured
+ *
+ * @example
+ * ```typescript
+ * const embeddings = useEmbeddings(ctx);
+ * const vector = await embeddings.embed('text to embed');
+ * ```
+ */
+export function useEmbeddings(ctx: PluginContext): IEmbeddings {
+  if (!ctx.platform.embeddings) {
+    throw new ServiceNotConfiguredError('embeddings', '@kb-labs/shared-openai');
+  }
+  return ctx.platform.embeddings;
+}
+
+/**
+ * Get vector store with configuration check.
+ * Throws if vector store is not configured (using in-memory fallback).
+ *
+ * @param ctx - Plugin context
+ * @returns Vector store service
+ * @throws {ServiceNotConfiguredError} If vectorStore not configured
+ *
+ * @example
+ * ```typescript
+ * const vectorStore = useVectorStore(ctx);
+ * const results = await vectorStore.search(queryVector, 10);
+ * ```
+ */
+export function useVectorStore(ctx: PluginContext): IVectorStore {
+  if (!ctx.platform.vectorStore) {
+    throw new ServiceNotConfiguredError('vectorStore', '@kb-labs/mind-qdrant');
+  }
+  return ctx.platform.vectorStore;
+}
+
+/**
+ * Get cache service.
+ * Safe to use even without configuration (falls back to in-memory).
+ *
+ * @param ctx - Plugin context
+ * @returns Cache service (always available)
+ *
+ * @example
+ * ```typescript
+ * const cache = useCache(ctx);
+ * await cache.set('key', value, 3600000); // TTL 1 hour
+ * const cached = await cache.get('key');
+ * ```
+ */
+export function useCache(ctx: PluginContext): ICache {
+  return ctx.platform.cache!;
+}
+
+/**
+ * Get storage service.
+ * Safe to use even without configuration (falls back to in-memory).
+ *
+ * @param ctx - Plugin context
+ * @returns Storage service (always available)
+ *
+ * @example
+ * ```typescript
+ * const storage = useStorage(ctx);
+ * await storage.write('path/to/file.txt', Buffer.from('content'));
+ * const content = await storage.read('path/to/file.txt');
+ * ```
+ */
+export function useStorage(ctx: PluginContext): IStorage {
+  return ctx.platform.storage!;
+}
+
+/**
+ * Get logger service.
+ * Always available (falls back to console logger).
+ *
+ * @param ctx - Plugin context
+ * @returns Logger service (always available)
+ *
+ * @example
+ * ```typescript
+ * const logger = useLogger(ctx);
+ * logger.info('Processing started', { itemCount: 10 });
+ * logger.error('Failed to process', error);
+ * ```
+ */
+export function useLogger(ctx: PluginContext): ILogger {
+  return ctx.platform.logger!;
+}
+
+/**
+ * Get analytics service.
+ * Safe to use even without configuration (falls back to NoOp).
+ *
+ * @param ctx - Plugin context
+ * @returns Analytics service (always available)
+ *
+ * @example
+ * ```typescript
+ * const analytics = useAnalytics(ctx);
+ * await analytics.track('feature.used', { feature: 'search' });
+ * ```
+ */
+export function useAnalytics(ctx: PluginContext): IAnalytics {
+  return ctx.platform.analytics!;
+}
+
+/**
+ * Get event bus service.
+ * Safe to use even without configuration (falls back to in-memory).
+ *
+ * @param ctx - Plugin context
+ * @returns Event bus service (always available)
+ *
+ * @example
+ * ```typescript
+ * const events = useEventBus(ctx);
+ * await events.publish('user.created', { userId: '123' });
+ * const unsubscribe = events.subscribe('user.created', async (event) => {
+ *   console.log('User created:', event);
+ * });
+ * ```
+ */
+export function useEventBus(ctx: PluginContext): IEventBus {
+  return ctx.platform.eventBus;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SHORTCUT FUNCTIONS (High-level operations)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate embedding for text.
+ * Shortcut for embeddings.embed().
+ *
+ * @param ctx - Plugin context
+ * @param text - Text to embed
+ * @returns Embedding vector
+ * @throws {ServiceNotConfiguredError} If embeddings not configured
+ *
+ * @example
+ * ```typescript
+ * const vector = await embedText(ctx, 'Hello, world!');
+ * console.log(vector.length); // e.g., 1536 for OpenAI ada-002
+ * ```
+ */
+export async function embedText(ctx: PluginContext, text: string): Promise<number[]> {
+  const embeddings = useEmbeddings(ctx);
+  return embeddings.embed(text);
+}
+
+/**
+ * Generate embeddings for multiple texts.
+ * Shortcut for embeddings.embedBatch().
+ *
+ * @param ctx - Plugin context
+ * @param texts - Array of texts to embed
+ * @returns Array of embedding vectors
+ * @throws {ServiceNotConfiguredError} If embeddings not configured
+ *
+ * @example
+ * ```typescript
+ * const vectors = await embedBatch(ctx, ['text 1', 'text 2', 'text 3']);
+ * ```
+ */
+export async function embedBatch(ctx: PluginContext, texts: string[]): Promise<number[][]> {
+  const embeddings = useEmbeddings(ctx);
+  return embeddings.embedBatch(texts);
+}
+
+/**
+ * Perform vector search.
+ * Shortcut for vectorStore.search().
+ *
+ * @param ctx - Plugin context
+ * @param query - Query vector
+ * @param limit - Maximum results (default: 10)
+ * @returns Search results
+ * @throws {ServiceNotConfiguredError} If vectorStore not configured
+ *
+ * @example
+ * ```typescript
+ * const queryVector = await embedText(ctx, 'search query');
+ * const results = await searchVectors(ctx, queryVector, 5);
+ *
+ * for (const result of results) {
+ *   console.log(`Score: ${result.score}, ID: ${result.id}`);
+ * }
+ * ```
+ */
+export async function searchVectors(
+  ctx: PluginContext,
+  query: number[],
+  limit = 10
+): Promise<VectorSearchResult[]> {
+  const vectorStore = useVectorStore(ctx);
+  return vectorStore.search(query, limit);
+}
+
+/**
+ * Call LLM with text prompt.
+ * Shortcut for llm.complete().
+ *
+ * @param ctx - Plugin context
+ * @param prompt - Prompt text
+ * @param options - LLM options
+ * @returns LLM response
+ * @throws {ServiceNotConfiguredError} If LLM not configured
+ *
+ * @example
+ * ```typescript
+ * const response = await completeLLM(ctx, 'Explain quantum computing', {
+ *   temperature: 0.7,
+ *   maxTokens: 500,
+ * });
+ * console.log(response.content);
+ * ```
+ */
+export async function completeLLM(
+  ctx: PluginContext,
+  prompt: string,
+  options?: LLMOptions
+): Promise<LLMResponse> {
+  const llm = useLLM(ctx);
+  return llm.complete(prompt, options);
+}
+
+/**
+ * Stream LLM response.
+ * Shortcut for llm.stream().
+ *
+ * @param ctx - Plugin context
+ * @param prompt - Prompt text
+ * @param options - LLM options
+ * @returns Async iterable of response chunks
+ * @throws {ServiceNotConfiguredError} If LLM not configured
+ *
+ * @example
+ * ```typescript
+ * for await (const chunk of streamLLM(ctx, 'Write a story')) {
+ *   ctx.ui.message(chunk);
+ * }
+ * ```
+ */
+export function streamLLM(
+  ctx: PluginContext,
+  prompt: string,
+  options?: LLMOptions
+): AsyncIterable<string> {
+  const llm = useLLM(ctx);
+  return llm.stream(prompt, options);
+}
+
+/**
+ * Check if a service is configured.
+ * Non-throwing alternative to use* functions.
+ *
+ * @param ctx - Plugin context
+ * @param service - Service name to check ('llm' | 'embeddings' | 'vectorStore' | 'cache' | 'storage' | 'analytics' | 'eventBus')
+ * @returns true if service is configured, false otherwise
+ */
+export function isServiceConfigured(ctx: PluginContext, service: keyof typeof ctx.platform): boolean {
+  return !!ctx.platform[service];
+}

package/packages/shared-command-kit/src/helpers/use-analytics.ts

@@ -0,0 +1,95 @@
+/**
+ * @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);
+ *   }
+ * }
+ * ```
+ */
+
+import { usePlatform } from './use-platform';
+import type { IAnalytics } from '@kb-labs/core-platform';
+
+/**
+ * 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',
+ *   });
+ * }
+ * ```
+ */
+export function useAnalytics(): IAnalytics | undefined {
+  const platform = usePlatform();
+  return platform.analytics;
+}
+
+/**
+ * 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 });
+ * ```
+ */
+export async function trackAnalyticsEvent(
+  event: string,
+  properties?: Record<string, unknown>
+): Promise<void> {
+  const analytics = useAnalytics();
+  if (analytics) {
+    await analytics.track(event, properties);
+  }
+}

package/packages/shared-command-kit/src/helpers/use-cache.ts

@@ -0,0 +1,97 @@
+/**
+ * @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);
+ *   }
+ * }
+ * ```
+ */
+
+import { usePlatform } from './use-platform.js';
+import type { ICache } from '@kb-labs/core-platform';
+
+/**
+ * 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;
+ * }
+ * ```
+ */
+export function useCache(): ICache | undefined {
+  const platform = usePlatform();
+  return platform.cache;
+}
+
+/**
+ * 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();
+ * }
+ * ```
+ */
+export function isCacheAvailable(): boolean {
+  const cache = useCache();
+  return !!cache;
+}

package/packages/shared-command-kit/src/helpers/use-config.ts

@@ -0,0 +1,99 @@
+/**
+ * @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');
+ * ```
+ */
+export async function useConfig<T = any>(productId?: string, profileId?: string): Promise<T | undefined> {
+  // Auto-detect productId from manifest.configSection if not provided
+  let effectiveProductId = productId;
+  if (!effectiveProductId) {
+    effectiveProductId = (globalThis as any).__KB_CONFIG_SECTION__;
+  }
+
+  if (!effectiveProductId) {
+    return undefined;
+  }
+
+  const { usePlatform } = await import('./use-platform.js');
+  const platform = usePlatform();
+
+  if (!platform) {
+    return undefined;
+  }
+
+  // Returns ONLY the product-specific config, not the entire kb.config.json
+  return await platform.config.getConfig(effectiveProductId, profileId) as T | undefined;
+}

package/packages/shared-command-kit/src/helpers/use-embeddings.ts

@@ -0,0 +1,49 @@
+/**
+ * @module @kb-labs/shared-command-kit/helpers/use-embeddings
+ * Global Embeddings access helper
+ */
+
+import { usePlatform } from './use-platform';
+import type { IEmbeddings } from '@kb-labs/core-platform';
+
+/**
+ * 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
+ * }
+ * ```
+ */
+export function useEmbeddings(): IEmbeddings | undefined {
+  const platform = usePlatform();
+  return platform.embeddings;
+}
+
+/**
+ * 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
+ * }
+ * ```
+ */
+export function isEmbeddingsAvailable(): boolean {
+  const embeddings = useEmbeddings();
+  return !!embeddings;
+}