mycelia-kernel-plugin 1.2.0 → 1.4.0

package/src/svelte/index.js

@@ -0,0 +1,183 @@
+/**
+ * Mycelia Plugin System - Svelte Bindings
+ * 
+ * Svelte utilities that make the Mycelia Plugin System feel natural
+ * inside Svelte applications using stores and context.
+ * 
+ * @example
+ * ```svelte
+ * <script>
+ *   import { setMyceliaSystem, useFacet, useListener } from 'mycelia-kernel-plugin/svelte';
+ *   import { buildSystem } from './system.js';
+ *   
+ *   let system;
+ *   buildSystem().then(s => {
+ *     system = s;
+ *     setMyceliaSystem(system);
+ *   });
+ * </script>
+ * ```
+ */
+
+import { writable, derived, get } from 'svelte/store';
+import { setContext, getContext } from 'svelte';
+
+// ============================================================================
+// Core Bindings: Context + Basic Stores
+// ============================================================================
+
+const MYCELIA_KEY = Symbol('mycelia');
+
+/**
+ * setMyceliaSystem - Provide Mycelia system to Svelte component tree
+ * 
+ * @param {Object} system - The Mycelia system instance
+ * @returns {Object} Context object with system, loading, and error stores
+ * 
+ * @example
+ * ```svelte
+ * <script>
+ *   import { onMount } from 'svelte';
+ *   import { setMyceliaSystem } from 'mycelia-kernel-plugin/svelte';
+ *   import { buildSystem } from './system.js';
+ *   
+ *   let system;
+ *   
+ *   onMount(async () => {
+ *     system = await buildSystem();
+ *     setMyceliaSystem(system);
+ *   });
+ * </script>
+ * ```
+ */
+export function setMyceliaSystem(system) {
+  const systemStore = writable(system);
+  const loadingStore = writable(false);
+  const errorStore = writable(null);
+  
+  const context = {
+    system: systemStore,
+    loading: loadingStore,
+    error: errorStore
+  };
+  
+  setContext(MYCELIA_KEY, context);
+  
+  return context;
+}
+
+/**
+ * getMyceliaSystem - Get Mycelia system store from context
+ * 
+ * @returns {import('svelte/store').Writable} Writable store containing the system instance
+ * @throws {Error} If used outside setMyceliaSystem context
+ * 
+ * @example
+ * ```svelte
+ * <script>
+ *   import { getMyceliaSystem } from 'mycelia-kernel-plugin/svelte';
+ *   
+ *   const systemStore = getMyceliaSystem();
+ *   $: system = $systemStore;
+ * </script>
+ * ```
+ */
+export function getMyceliaSystem() {
+  const context = getContext(MYCELIA_KEY);
+  if (!context) {
+    throw new Error('getMyceliaSystem must be used within setMyceliaSystem context');
+  }
+  return context.system;
+}
+
+/**
+ * getMyceliaContext - Get the full Mycelia context (system, loading, error stores)
+ * 
+ * @returns {Object} Context object with system, loading, and error stores
+ * @throws {Error} If used outside setMyceliaSystem context
+ * 
+ * @example
+ * ```svelte
+ * <script>
+ *   import { getMyceliaContext } from 'mycelia-kernel-plugin/svelte';
+ *   
+ *   const { system, loading, error } = getMyceliaContext();
+ * </script>
+ * 
+ * {#if $loading}
+ *   <div>Loading...</div>
+ * {:else if $error}
+ *   <div>Error: {$error.message}</div>
+ * {:else}
+ *   <div>System ready: {$system.name}</div>
+ * {/if}
+ * ```
+ */
+export function getMyceliaContext() {
+  const context = getContext(MYCELIA_KEY);
+  if (!context) {
+    throw new Error('getMyceliaContext must be used within setMyceliaSystem context');
+  }
+  return context;
+}
+
+/**
+ * useMycelia - Get Mycelia system store (reactive)
+ * 
+ * @returns {import('svelte/store').Writable} Writable store containing the system instance
+ * 
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useMycelia } from 'mycelia-kernel-plugin/svelte';
+ *   
+ *   const systemStore = useMycelia();
+ *   $: system = $systemStore;
+ *   $: db = system?.find('database');
+ * </script>
+ * ```
+ */
+export function useMycelia() {
+  return getMyceliaSystem();
+}
+
+/**
+ * useFacet - Get a facet by kind from the system (reactive store)
+ * 
+ * @param {string} kind - Facet kind identifier
+ * @returns {import('svelte/store').Readable} Readable store containing the facet instance, or null if not found
+ * 
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useFacet } from 'mycelia-kernel-plugin/svelte';
+ *   
+ *   const dbStore = useFacet('database');
+ *   $: db = $dbStore;
+ * </script>
+ * 
+ * {#if db}
+ *   <div>Database ready</div>
+ * {/if}
+ * ```
+ */
+export function useFacet(kind) {
+  const systemStore = getMyceliaSystem();
+  
+  return derived(systemStore, ($system) => {
+    return $system?.find?.(kind) ?? null;
+  });
+}
+
+// Re-export listener helpers
+export { useListener, useEventStream } from './listeners.js';
+
+// Re-export queue helpers
+export { useQueueStatus, useQueueDrain } from './queues.js';
+
+// Re-export builder helpers
+export { createSvelteSystemBuilder } from './builders.js';
+
+// Re-export store generator
+export { createFacetStore } from './stores.js';
+

package/src/svelte/listeners.js

@@ -0,0 +1,96 @@
+/**
+ * Mycelia Plugin System - Svelte Listener Helpers
+ * 
+ * Svelte utilities for event listener management.
+ */
+
+import { writable, get } from 'svelte/store';
+import { onDestroy } from 'svelte';
+import { getMyceliaSystem } from './index.js';
+
+/**
+ * useListener - Register an event listener with automatic cleanup
+ * 
+ * @param {string} eventName - Event name/path to listen for
+ * @param {Function} handler - Handler function: (message) => void
+ * 
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useListener } from 'mycelia-kernel-plugin/svelte';
+ *   
+ *   useListener('user:created', (msg) => {
+ *     console.log('User created:', msg.body);
+ *   });
+ * </script>
+ * ```
+ */
+export function useListener(eventName, handler) {
+  const systemStore = getMyceliaSystem();
+  let listeners = null;
+  let unsubscribe = null;
+  
+  const setup = () => {
+    const system = get(systemStore);
+    if (!system) return;
+    
+    listeners = system?.listeners;
+    if (!listeners || !listeners.hasListeners?.()) return;
+    
+    listeners.on(eventName, handler);
+  };
+  
+  // Subscribe to system store to set up listener when system is available
+  unsubscribe = systemStore.subscribe(() => {
+    setup();
+  });
+  
+  // Initial setup
+  setup();
+  
+  onDestroy(() => {
+    if (listeners) {
+      listeners.off?.(eventName, handler);
+    }
+    if (unsubscribe) {
+      unsubscribe();
+    }
+  });
+}
+
+/**
+ * useEventStream - Subscribe to events and keep them in a reactive store
+ * 
+ * @param {string} eventName - Event name/path to listen for
+ * @param {Object} [options={}] - Options
+ * @param {boolean} [options.accumulate=false] - If true, accumulate events in array
+ * @returns {import('svelte/store').Writable} Writable store containing latest event value, array of events, or null
+ * 
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useEventStream } from 'mycelia-kernel-plugin/svelte';
+ *   
+ *   const events = useEventStream('todo:created', { accumulate: true });
+ * </script>
+ * 
+ * {#each $events as event}
+ *   <div>{event.text}</div>
+ * {/each}
+ * ```
+ */
+export function useEventStream(eventName, options = {}) {
+  const { accumulate = false } = options;
+  const store = writable(accumulate ? [] : null);
+  
+  useListener(eventName, (msg) => {
+    if (accumulate) {
+      store.update(events => [...events, msg.body]);
+    } else {
+      store.set(msg.body);
+    }
+  });
+  
+  return store;
+}
+

package/src/svelte/queues.js

@@ -0,0 +1,114 @@
+/**
+ * Mycelia Plugin System - Svelte Queue Helpers
+ * 
+ * Svelte utilities for queue management.
+ */
+
+import { writable, get } from 'svelte/store';
+import { onMount, onDestroy } from 'svelte';
+import { useFacet } from './index.js';
+
+/**
+ * useQueueStatus - Get queue status with reactive updates
+ * 
+ * @returns {import('svelte/store').Writable} Writable store containing queue status object
+ * @returns {number} size - Current queue size
+ * @returns {number} capacity - Maximum queue capacity
+ * @returns {number} utilization - Utilization ratio (0-1)
+ * @returns {boolean} isFull - Whether queue is full
+ * 
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useQueueStatus } from 'mycelia-kernel-plugin/svelte';
+ *   
+ *   const status = useQueueStatus();
+ * </script>
+ * 
+ * <div>Queue: {$status.size}/{$status.capacity}</div>
+ * ```
+ */
+export function useQueueStatus() {
+  const queueStore = useFacet('queue');
+  const statusStore = writable({
+    size: 0,
+    capacity: 0,
+    utilization: 0,
+    isFull: false
+  });
+  
+  let intervalId = null;
+  
+  const updateStatus = () => {
+    const queue = get(queueStore);
+    if (!queue?.getQueueStatus) return;
+    
+    const newStatus = queue.getQueueStatus();
+    statusStore.set({
+      size: newStatus.size || 0,
+      capacity: newStatus.maxSize || 0,
+      utilization: newStatus.utilization || 0,
+      isFull: newStatus.isFull || false
+    });
+  };
+  
+  onMount(() => {
+    updateStatus();
+    intervalId = setInterval(updateStatus, 100); // Poll every 100ms
+  });
+  
+  onDestroy(() => {
+    if (intervalId) {
+      clearInterval(intervalId);
+    }
+  });
+  
+  return statusStore;
+}
+
+/**
+ * useQueueDrain - Automatically drain queue on mount
+ * 
+ * @param {Object} [options={}] - Options
+ * @param {number} [options.interval=100] - Polling interval in ms
+ * @param {Function} [options.onMessage] - Callback for each message: (msg, options) => void
+ * 
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useQueueDrain } from 'mycelia-kernel-plugin/svelte';
+ *   
+ *   useQueueDrain({
+ *     interval: 50,
+ *     onMessage: (msg) => console.log('Processed:', msg)
+ *   });
+ * </script>
+ * ```
+ */
+export function useQueueDrain(options = {}) {
+  const { interval = 100, onMessage } = options;
+  const queueStore = useFacet('queue');
+  let processInterval = null;
+  
+  onMount(() => {
+    const queue = get(queueStore);
+    if (!queue || !queue.hasMessagesToProcess) return;
+    
+    processInterval = setInterval(() => {
+      const currentQueue = get(queueStore);
+      if (currentQueue?.hasMessagesToProcess()) {
+        const next = currentQueue.selectNextMessage();
+        if (next && onMessage) {
+          onMessage(next.msg, next.options);
+        }
+      }
+    }, interval);
+  });
+  
+  onDestroy(() => {
+    if (processInterval) {
+      clearInterval(processInterval);
+    }
+  });
+}
+

package/src/svelte/stores.js

@@ -0,0 +1,36 @@
+/**
+ * Mycelia Plugin System - Svelte Store Generator
+ * 
+ * Utility for generating custom stores for specific facets.
+ */
+
+import { useFacet } from './index.js';
+
+/**
+ * createFacetStore - Generate a custom store for a specific facet kind
+ * 
+ * @param {string} kind - Facet kind identifier
+ * @returns {Function} Custom store function: () => import('svelte/store').Readable
+ * 
+ * @example
+ * ```js
+ * // stores/todos.js
+ * import { createFacetStore } from 'mycelia-kernel-plugin/svelte';
+ * 
+ * export const useTodos = createFacetStore('todos');
+ * 
+ * // In component
+ * <script>
+ *   import { useTodos } from './stores/todos.js';
+ *   
+ *   const todosStore = useTodos();
+ *   $: todos = $todosStore;
+ * </script>
+ * ```
+ */
+export function createFacetStore(kind) {
+  return function useNamedFacet() {
+    return useFacet(kind);
+  };
+}
+

package/src/utils/instrumentation.js

@@ -0,0 +1,204 @@
+/**
+ * Instrumentation Utilities
+ * 
+ * Provides timing instrumentation for debugging build, initialization, and disposal phases.
+ * Helps identify slow hooks and facets when debugging performance issues.
+ */
+
+import { createSubsystemLogger } from './logger.js';
+
+/**
+ * Default thresholds for timing warnings (in milliseconds)
+ */
+const DEFAULT_THRESHOLDS = {
+  hookExecution: 50,    // Warn if hook execution takes > 50ms
+  facetInit: 100,       // Warn if facet init takes > 100ms
+  facetDispose: 50,      // Warn if facet dispose takes > 50ms
+};
+
+/**
+ * Check if instrumentation is enabled
+ * 
+ * @param {BaseSubsystem} subsystem - Subsystem instance
+ * @returns {boolean} True if instrumentation is enabled
+ */
+export function isInstrumentationEnabled(subsystem) {
+  // Enable if debug is on, or if instrumentation is explicitly enabled
+  return subsystem?.debug === true || subsystem?.ctx?.instrumentation === true;
+}
+
+/**
+ * Get timing thresholds from config or use defaults
+ * 
+ * @param {BaseSubsystem} subsystem - Subsystem instance
+ * @returns {Object} Thresholds object
+ */
+function getThresholds(subsystem) {
+  const config = subsystem?.ctx?.config?.instrumentation || {};
+  return {
+    hookExecution: config.hookExecutionThreshold ?? DEFAULT_THRESHOLDS.hookExecution,
+    facetInit: config.facetInitThreshold ?? DEFAULT_THRESHOLDS.facetInit,
+    facetDispose: config.facetDisposeThreshold ?? DEFAULT_THRESHOLDS.facetDispose,
+  };
+}
+
+/**
+ * Time a hook execution and log if it exceeds threshold
+ * 
+ * @param {Function} hook - Hook function to execute
+ * @param {Object} resolvedCtx - Resolved context
+ * @param {Object} api - Subsystem API
+ * @param {BaseSubsystem} subsystem - Subsystem instance
+ * @returns {*} Result of hook execution
+ */
+export function instrumentHookExecution(hook, resolvedCtx, api, subsystem) {
+  if (!isInstrumentationEnabled(subsystem)) {
+    // No instrumentation - just execute
+    return hook(resolvedCtx, api, subsystem);
+  }
+
+  const logger = createSubsystemLogger(subsystem);
+  const hookKind = hook.kind || '<unknown>';
+  const hookSource = hook.source || '<unknown>';
+  const thresholds = getThresholds(subsystem);
+
+  const start = performance.now();
+  let result;
+  try {
+    result = hook(resolvedCtx, api, subsystem);
+  } finally {
+    const duration = performance.now() - start;
+    
+    if (duration > thresholds.hookExecution) {
+      logger.warn(
+        `⚠️  Slow hook execution: '${hookKind}' took ${duration.toFixed(2)}ms ` +
+        `(threshold: ${thresholds.hookExecution}ms) [${hookSource}]`
+      );
+    } else {
+      logger.log(`✓ Hook '${hookKind}' executed in ${duration.toFixed(2)}ms [${hookSource}]`);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Time a facet initialization callback and log if it exceeds threshold
+ * 
+ * @param {Facet} facet - Facet instance
+ * @param {Object} ctx - Context object
+ * @param {Object} api - Subsystem API
+ * @param {BaseSubsystem} subsystem - Subsystem instance
+ * @param {Function} initCallback - The init callback to execute
+ * @returns {Promise<void>}
+ */
+export async function instrumentFacetInit(facet, ctx, api, subsystem, initCallback) {
+  if (!initCallback) {
+    return;
+  }
+
+  if (!isInstrumentationEnabled(subsystem)) {
+    // No instrumentation - call callback directly
+    return initCallback({ ctx, api, subsystem, facet });
+  }
+
+  const logger = createSubsystemLogger(subsystem);
+  const facetKind = facet.getKind?.() || '<unknown>';
+  const facetSource = facet.getSource?.() || '<unknown>';
+  const thresholds = getThresholds(subsystem);
+
+  const start = performance.now();
+  try {
+    await initCallback({ ctx, api, subsystem, facet });
+  } finally {
+    const duration = performance.now() - start;
+    
+    if (duration > thresholds.facetInit) {
+      logger.warn(
+        `⚠️  Slow facet initialization: '${facetKind}' took ${duration.toFixed(2)}ms ` +
+        `(threshold: ${thresholds.facetInit}ms) [${facetSource}]`
+      );
+    } else {
+      logger.log(`✓ Facet '${facetKind}' initialized in ${duration.toFixed(2)}ms [${facetSource}]`);
+    }
+  }
+}
+
+/**
+ * Time a facet disposal callback and warn if it exceeds threshold
+ * 
+ * @param {Facet} facet - Facet instance
+ * @param {BaseSubsystem} subsystem - Subsystem instance
+ * @param {Function} disposeCallback - The dispose callback to execute
+ * @returns {Promise<void>}
+ */
+export async function instrumentDisposeCallback(facet, subsystem, disposeCallback) {
+  if (!disposeCallback) {
+    return;
+  }
+
+  if (!isInstrumentationEnabled(subsystem)) {
+    // No instrumentation - call callback directly
+    return disposeCallback(facet);
+  }
+
+  const logger = createSubsystemLogger(subsystem);
+  const facetKind = facet.getKind?.() || '<unknown>';
+  const facetSource = facet.getSource?.() || '<unknown>';
+  const thresholds = getThresholds(subsystem);
+
+  const start = performance.now();
+  let errorOccurred = false;
+  try {
+    await disposeCallback(facet);
+    const duration = performance.now() - start;
+    
+    if (duration > thresholds.facetDispose) {
+      logger.warn(
+        `⚠️  Slow facet disposal: '${facetKind}' took ${duration.toFixed(2)}ms ` +
+        `(threshold: ${thresholds.facetDispose}ms) [${facetSource}]`
+      );
+    } else {
+      logger.log(`✓ Facet '${facetKind}' disposed in ${duration.toFixed(2)}ms [${facetSource}]`);
+    }
+  } catch (error) {
+    errorOccurred = true;
+    const duration = performance.now() - start;
+    logger.warn(
+      `⚠️  Facet disposal error: '${facetKind}' failed after ${duration.toFixed(2)}ms ` +
+      `[${facetSource}]: ${error.message}`
+    );
+    // Re-throw so disposeAll can catch and handle it
+    throw error;
+  } finally {
+    // Ensure timing is logged even if error occurred
+    if (!errorOccurred) {
+      // Already logged in try block
+    }
+  }
+}
+
+/**
+ * Time the entire build phase and log summary
+ * 
+ * @param {BaseSubsystem} subsystem - Subsystem instance
+ * @param {Function} buildFn - Build function to execute
+ * @returns {Promise<void>}
+ */
+export async function instrumentBuildPhase(subsystem, buildFn) {
+  if (!isInstrumentationEnabled(subsystem)) {
+    // No instrumentation - just build
+    return buildFn();
+  }
+
+  const logger = createSubsystemLogger(subsystem);
+  const start = performance.now();
+  
+  try {
+    await buildFn();
+  } finally {
+    const duration = performance.now() - start;
+    logger.log(`📦 Build phase completed in ${duration.toFixed(2)}ms`);
+  }
+}
+