mycelia-kernel-plugin 1.0.0

package/src/system/base-subsystem.js

@@ -0,0 +1,416 @@
+import { SubsystemBuilder } from '../builder/subsystem-builder.js';
+import { FacetManager } from '../manager/facet-manager.js';
+import { disposeChildren } from './base-subsystem.utils.js';
+import { createSubsystemLogger } from '../utils/logger.js';
+import { DependencyGraphCache } from '../builder/dependency-graph-cache.js';
+
+// Constants for facet kinds (used if facets are available)
+const HIERARCHY_KIND = 'hierarchy';
+
+export class BaseSubsystem {
+  _isBuilt = false;
+  _buildPromise = null;
+  _disposePromise = null;
+  _builder = null;
+  _initCallbacks = [];
+  _disposeCallbacks = [];
+  _parent = null; // ← parent subsystem
+
+  /**
+   * @param {string} name - Unique name for the subsystem
+   * @param {Object} options - Configuration options
+   * @param {Object} [options.ms] - Optional message system instance (for compatibility, not required for standalone)
+   * @param {Object} [options.config={}] - Optional configuration object keyed by facet kind.
+   *   Each key corresponds to a facet kind (e.g., 'router', 'queue', 'scheduler').
+   *   Each value is the configuration object for that specific hook/facet.
+   * @param {boolean} [options.debug=false] - Enable debug logging
+   */
+  constructor(name, options = {}) {
+    if (!name || typeof name !== 'string')
+      throw new Error('BaseSubsystem: name must be a non-empty string');
+    
+    // ms is optional for standalone plugin system
+    // if (!options.ms)
+    //   throw new Error('BaseSubsystem: options.ms is required');
+
+    this.name = name;
+    this.options = options;
+    this.messageSystem = options.ms || null;
+
+    // create the context object
+    this.ctx = {};
+    this.ctx.ms = options.ms || null; // Optional message system
+    this.ctx.config = options.config || {}; // Optional configuration object keyed by facet kind
+    this.ctx.debug = !!options.debug;
+    
+    // Legacy property for backward compatibility (use ctx.debug instead)
+    this.debug = this.ctx.debug;
+
+    this.defaultHooks = options.defaultHooks;
+    this.hooks = [];
+    this._builder = new SubsystemBuilder(this);
+    this.api = { name, 
+        __facets: new FacetManager(this) };
+    this.coreProcessor = null;
+  }
+
+  // ==== Hierarchy Management ====
+
+  /** Assign a parent subsystem (called during child registration). */
+  setParent(parent) {
+    const hierarchy = this.find(HIERARCHY_KIND);
+    if (hierarchy) {
+      return hierarchy.setParent(parent);
+    }
+    // Fallback if hierarchy facet not present
+    if (parent && typeof parent !== 'object')
+      throw new Error(`${this.name}: parent must be an object or null`);
+    this._parent = parent;
+    return this;
+  }
+
+  /** Retrieve the parent subsystem. */
+  getParent() {
+    const hierarchy = this.find(HIERARCHY_KIND);
+    if (hierarchy) {
+      return hierarchy.getParent();
+    }
+    // Fallback if hierarchy facet not present
+    return this._parent;
+  }
+
+  /** True if this subsystem has no parent (i.e., top-level). */
+  isRoot() {
+    const hierarchy = this.find(HIERARCHY_KIND);
+    if (hierarchy) {
+      return hierarchy.isRoot();
+    }
+    // Fallback if hierarchy facet not present
+    return this._parent === null;
+  }
+
+  /** Returns the root subsystem by traversing up the parent chain. */
+  getRoot() {
+    const hierarchy = this.find(HIERARCHY_KIND);
+    if (hierarchy) {
+      return hierarchy.getRoot();
+    }
+    // Fallback if hierarchy facet not present
+    let current = this;
+    while (current._parent !== null) {
+      current = current._parent;
+    }
+    return current;
+  }
+
+  /**
+   * Returns a fully-qualified subsystem name string.
+   * Example:
+   * Root subsystem "kernel" → "kernel://"
+   * Child subsystem "cache" under "kernel" → "kernel://cache"
+   * Grandchild "manager" → "kernel://cache/manager"
+   */
+  getNameString() {
+    if (this._parent === null) {
+      return `${this.name}://`;
+    }
+    const parentName = this._parent.getNameString();
+    // ensure no accidental trailing "//"
+    return `${parentName.replace(/\/$/, '')}/${this.name}`;
+  }
+
+  // ==== State getters ====
+
+  get isBuilt() { return this._isBuilt; }
+
+  /** Returns an array of all facet kinds (capabilities) available on this subsystem. */
+  get capabilities() { return this.api.__facets.getAllKinds(); }
+
+  // ==== Hook registration ====
+
+  use(hook) {
+    if (this._isBuilt)
+      throw new Error(`${this.name}: cannot add hooks after build()`);
+    if (typeof hook !== 'function')
+      throw new Error(`${this.name}: hook must be a function`);
+    this.hooks.push(hook);
+    return this;
+  }
+
+  onInit(cb) {
+    if (typeof cb !== 'function')
+      throw new Error(`${this.name}: onInit callback must be a function`);
+    this._initCallbacks.push(cb);
+    return this;
+  }
+
+  onDispose(cb) {
+    if (typeof cb !== 'function')
+      throw new Error(`${this.name}: onDispose callback must be a function`);
+    this._disposeCallbacks.push(cb);
+    return this;
+  }
+
+  /**
+   * Find a facet by kind and optional orderIndex
+   * @param {string} kind - Facet kind to find
+   * @param {number} [orderIndex] - Optional order index. If provided, returns facet at that index. If not, returns the last facet (highest orderIndex).
+   * @returns {Object|undefined} Facet instance or undefined if not found
+   */
+  find(kind, orderIndex = undefined) { return this.api.__facets.find(kind, orderIndex); }
+  
+  /**
+   * Get a facet by its index in the array of facets of that kind
+   * @param {string} kind - Facet kind to find
+   * @param {number} index - Zero-based index in the array of facets of this kind
+   * @returns {Object|undefined} Facet instance or undefined if not found
+   */
+  getByIndex(kind, index) { return this.api.__facets.getByIndex(kind, index); }
+
+  // ==== Lifecycle ====
+
+  async build(ctx = {}) {
+    if (this._isBuilt) return this;
+    if (this._buildPromise) return this._buildPromise;
+
+    this._buildPromise = (async () => {
+      try {
+        // Determine graphCache: use provided, inherited from parent, or create new
+        let graphCache = ctx.graphCache || this.ctx?.graphCache || this.ctx?.parent?.graphCache;
+        
+        if (!graphCache) {
+          // Create new cache with default capacity (configurable via ctx.config.graphCache.capacity)
+          const cacheCapacity = ctx.config?.graphCache?.capacity || 100;
+          graphCache = new DependencyGraphCache(cacheCapacity);
+        }
+        
+        // Set graphCache on ctx so it's available after build
+        this.ctx.graphCache = graphCache;
+        
+        this._builder.withCtx(ctx); // any additional context to be passed to the builder
+        await this._builder.build(graphCache); // Pass graphCache explicitly
+        for (const cb of this._initCallbacks)
+          await cb(this.api, this.ctx);
+        this._isBuilt = true;
+        
+        // Note: coreProcessor is not set for standalone plugin system
+        // (no message processing needed)
+        this.coreProcessor = null;
+        
+        const logger = createSubsystemLogger(this);
+        logger.log('Built successfully');
+        return this;
+      } finally {
+        this._buildPromise = null;
+      }
+    })();
+
+    return this._buildPromise;
+  }
+
+  async dispose() {
+    if (!this._isBuilt && !this._buildPromise) return;
+    if (this._disposePromise) return this._disposePromise;
+
+    const waitBuild = this._buildPromise ? this._buildPromise.catch(() => {}) : Promise.resolve();
+
+    this._disposePromise = (async () => {
+      try {
+        await waitBuild;
+        if (!this._isBuilt) return;
+
+        await disposeChildren(this);
+        if (this.api && this.api.__facets) {
+          await this.api.__facets.disposeAll(this);
+        }
+
+        const logger = createSubsystemLogger(this);
+        for (const cb of this._disposeCallbacks) {
+          try { await cb(); }
+          catch (err) { logger.error('Dispose callback error:', err); }
+        }
+
+        this._isBuilt = false;
+        this.coreProcessor = null;
+        this._builder.invalidate();
+
+        logger.log('Disposed');
+      } finally {
+        this._disposePromise = null;
+      }
+    })();
+
+    return this._disposePromise;
+  }
+
+  /**
+   * Reload the subsystem: dispose all facets and reset built state,
+   * while preserving hooks and configuration. Allows adding more hooks
+   * and rebuilding.
+   * 
+   * This method:
+   * - Disposes all facets and child subsystems
+   * - Resets built state (allows use() to work again)
+   * - Preserves hooks, defaultHooks, context, and lifecycle callbacks
+   * 
+   * @returns {Promise<BaseSubsystem>} This subsystem for chaining
+   * 
+   * @example
+   * // Initial build
+   * await system.use(useDatabase).build();
+   * 
+   * // Reload and extend
+   * await system.reload().use(useCache).build();
+   */
+  async reload() {
+    // Wait for any in-progress operations
+    if (this._buildPromise) {
+      await this._buildPromise.catch(() => {}); // Wait even if failed
+    }
+    if (this._disposePromise) {
+      await this._disposePromise.catch(() => {}); // Wait even if failed
+    }
+    
+    // Only proceed if actually built
+    if (!this._isBuilt) {
+      return this; // Already not built, nothing to reload
+    }
+    
+    // Dispose all facets (clean slate)
+    if (this.api?.__facets) {
+      // Remove attached properties before disposing (to allow re-attachment on rebuild)
+      const facetKinds = Array.from(this.api.__facets[Symbol.iterator]?.() || []);
+      for (const [kind] of facetKinds) {
+        if (kind in this && this[kind] !== undefined) {
+          try {
+            delete this[kind];
+          } catch {
+            // Best-effort cleanup (property might be non-configurable)
+          }
+        }
+      }
+      await this.api.__facets.disposeAll(this);
+    }
+    
+    // Dispose child subsystems
+    await disposeChildren(this);
+    
+    // Reset built state (allows use() to work again)
+    this._isBuilt = false;
+    
+    // Invalidate builder cache (force recalculation on next build)
+    this._builder.invalidate();
+    
+    // Clear promises
+    this._buildPromise = null;
+    this._disposePromise = null;
+    
+    // NOTE: Preserved:
+    // - this.hooks (user-added hooks)
+    // - this.defaultHooks (default hooks)
+    // - this.ctx (context/config)
+    // - this._initCallbacks
+    // - this._disposeCallbacks
+    
+    const logger = createSubsystemLogger(this);
+    logger.log('Reloaded - ready for extension and rebuild');
+    
+    return this; // For chaining: system.reload().use(hook).build()
+  }
+
+  // ==== Message flow (No-ops for standalone plugin system) ====
+
+  /**
+   * No-op: Message acceptance is not needed for standalone plugin system.
+   * @param {*} _message - Ignored
+   * @param {*} _options - Ignored
+   * @returns {Promise<boolean>} Always returns true
+   */
+  async accept(_message, _options = {}) {
+    // No-op for standalone plugin system
+    return true;
+  }
+
+  /**
+   * No-op: Message processing is not needed for standalone plugin system.
+   * @param {*} _timeSlice - Ignored
+   * @returns {Promise<null>} Always returns null
+   */
+  async process(_timeSlice) {
+    // No-op for standalone plugin system
+    return null;
+  }
+
+  /**
+   * No-op: Immediate message processing is not needed for standalone plugin system.
+   * @param {*} _message - Ignored
+   * @param {*} _options - Ignored
+   * @returns {Promise<null>} Always returns null
+   */
+  async processImmediately(_message, _options = {}) {
+    // No-op for standalone plugin system
+    return null;
+  }
+
+  /**
+   * No-op: Pause functionality is not needed for standalone plugin system.
+   * @returns {BaseSubsystem} Returns this for chaining
+   */
+  pause() {
+    // No-op for standalone plugin system
+    return this;
+  }
+
+  /**
+   * No-op: Resume functionality is not needed for standalone plugin system.
+   * @returns {BaseSubsystem} Returns this for chaining
+   */
+  resume() {
+    // No-op for standalone plugin system
+    return this;
+  }
+
+  /**
+   * Get queue status (returns default if queue facet not available).
+   * @returns {Object} Queue status object
+   */
+  getQueueStatus() {
+    const queue = this.find('queue');
+    if (!queue?.getStatus) {
+      // Return default status if queue facet is not available
+      return { size: 0, maxSize: 0, isFull: false };
+    }
+    return queue.getStatus();
+  }
+
+  // ==== Routing (Optional - returns null if router not available) ====
+
+  /**
+   * Register a route (optional - returns null if router facet not available).
+   * @param {string} pattern - Route pattern
+   * @param {Function} handler - Route handler
+   * @param {Object} routeOptions - Route options
+   * @returns {boolean|null} True if registered, null if router not available
+   */
+  registerRoute(pattern, handler, routeOptions = {}) {
+    const router = this.find('router');
+    if (!router?.registerRoute) {
+      return null;
+    }
+    return router.registerRoute(pattern, handler, routeOptions);
+  }
+
+  /**
+   * Unregister a route (optional - returns null if router facet not available).
+   * @param {string} pattern - Route pattern
+   * @returns {boolean|null} True if unregistered, null if router not available
+   */
+  unregisterRoute(pattern) {
+    const router = this.find('router');
+    if (!router?.unregisterRoute) {
+      return null; 
+    }
+    return router.unregisterRoute(pattern);
+  }
+}
+

package/src/system/base-subsystem.utils.js

@@ -0,0 +1,106 @@
+/**
+ * base-subsystem.utils.js
+ * 
+ * Hierarchy lifecycle utilities for collecting, building, and disposing child subsystems.
+ * These are read-only helpers that work with or without the useHierarchy facet.
+ */
+
+// Constant for hierarchy facet kind (used if hierarchy facet is available)
+const HIERARCHY_KIND = 'hierarchy';
+
+/**
+ * Collects all children from a parent subsystem.
+ * 
+ * Prefers useHierarchy facet → registry, with fallbacks to Map or array.
+ * 
+ * @param {object} parent - The parent subsystem
+ * @returns {object[]} Array of child subsystem instances
+ * 
+ * @example
+ * const children = collectChildren(parent);
+ * console.log(`Parent has ${children.length} children`);
+ */
+export function collectChildren(parent) {
+  if (!parent || typeof parent !== 'object') {
+    return [];
+  }
+
+  // Prefer useHierarchy facet → registry
+  const hierarchy = parent.find?.(HIERARCHY_KIND);
+  const reg = hierarchy?.children || parent.children;
+  
+  if (!reg) {
+    return [];
+  }
+
+  // Try registry's list() method (ChildSubsystemRegistry)
+  if (typeof reg.list === 'function') {
+    return reg.list();
+  }
+
+  // Fallback to Map
+  if (reg instanceof Map) {
+    return Array.from(reg.values());
+  }
+
+  // Fallback to array
+  if (Array.isArray(reg)) {
+    return reg;
+  }
+
+  return [];
+}
+
+/**
+ * Builds all child subsystems of a parent.
+ * 
+ * Iterates through children and calls build() on each if not already built.
+ * Parent's ctx should already be fully resolved.
+ * 
+ * @param {object} parent - The parent subsystem
+ * @returns {Promise<void>}
+ * 
+ * @example
+ * await buildChildren(parent);
+ * console.log('All children built');
+ */
+export async function buildChildren(parent) {
+  const children = collectChildren(parent);
+  
+  for (const child of children) {
+    if (child && typeof child.build === 'function' && !child._isBuilt) {
+      // Merge parent context into child context
+      if (!child.ctx) {
+        child.ctx = {};
+      }
+      child.ctx.parent = parent.ctx;
+      child.ctx.graphCache = parent.ctx.graphCache;
+      await child.build(); // parent.ctx is now accessible via child.ctx.parent
+    }
+  }
+}
+
+/**
+ * Disposes all child subsystems of a parent.
+ * 
+ * Disposes children in reverse order (bottom-up) for proper cleanup.
+ * Deep trees recurse via child.dispose().
+ * 
+ * @param {object} parent - The parent subsystem
+ * @returns {Promise<void>}
+ * 
+ * @example
+ * await disposeChildren(parent);
+ * console.log('All children disposed');
+ */
+export async function disposeChildren(parent) {
+  const children = collectChildren(parent);
+  
+  // Bottom-up: reverse shallow order; deep trees recurse via child.dispose()
+  for (const child of [...children].reverse()) {
+    if (child && typeof child.dispose === 'function') {
+      await child.dispose();
+    }
+  }
+}
+

package/src/system/index.js

@@ -0,0 +1,4 @@
+export { BaseSubsystem } from './base-subsystem.js';
+export { StandalonePluginSystem } from './standalone-plugin-system.js';
+export { collectChildren, buildChildren, disposeChildren } from './base-subsystem.utils.js';
+

package/src/system/standalone-plugin-system.js

@@ -0,0 +1,70 @@
+import { BaseSubsystem } from './base-subsystem.js';
+
+/**
+ * StandalonePluginSystem
+ * 
+ * A specialized BaseSubsystem designed for standalone plugin systems without message processing.
+ * Automatically overrides message-specific methods as no-ops.
+ * 
+ * This class is ideal for:
+ * - Plugin architectures
+ * - Modular applications
+ * - Component systems
+ * - Service containers
+ * 
+ * @example
+ * ```javascript
+ * import { StandalonePluginSystem } from './standalone-plugin-system.js';
+ * import { useDatabase } from './plugins/use-database.js';
+ * 
+ * const system = new StandalonePluginSystem('my-app', {
+ *   config: {
+ *     database: { host: 'localhost' }
+ *   }
+ * });
+ * 
+ * system
+ *   .use(useDatabase)
+ *   .build();
+ * 
+ * const db = system.find('database');
+ * ```
+ */
+export class StandalonePluginSystem extends BaseSubsystem {
+  /**
+   * @param {string} name - Unique name for the plugin system
+   * @param {Object} options - Configuration options
+   * @param {Object} [options.config={}] - Optional configuration object keyed by facet kind.
+   *   Each key corresponds to a facet kind (e.g., 'database', 'cache').
+   *   Each value is the configuration object for that specific hook/facet.
+   * @param {boolean} [options.debug=false] - Enable debug logging
+   * @param {Array} [options.defaultHooks=[]] - Optional default hooks to install
+   */
+  constructor(name, options = {}) {
+    // Pass null for message system - not needed for standalone plugin system
+    super(name, { ...options, ms: null });
+    
+    // No default hooks by default (can be set via options.defaultHooks)
+    // Users can add hooks via .use() method
+    this.defaultHooks = options.defaultHooks || [];
+  }
+
+  // ==== Message Flow Methods (No-Ops) ====
+  // Inherited from BaseSubsystem - already no-ops
+
+  // ==== Routing Methods (No-Ops) ====
+  // Inherited from BaseSubsystem - already returns null if router not available
+
+  // ==== Lifecycle Methods (Kept from BaseSubsystem) ====
+  // build(), dispose(), onInit(), onDispose() are inherited and work as expected
+  
+  // ==== Plugin Management Methods (Kept from BaseSubsystem) ====
+  // use(), find() are inherited and work as expected
+  
+  // ==== Hierarchy Methods (Kept from BaseSubsystem) ====
+  // setParent(), getParent(), isRoot(), getRoot(), getNameString() are inherited
+  
+  // ==== State Getters (Kept from BaseSubsystem) ====
+  // isBuilt getter is inherited
+}
+

package/src/utils/debug-flag.js

@@ -0,0 +1,34 @@
+/**
+ * Debug Flag Utilities
+ * 
+ * Provides standardized debug flag extraction from configuration and context.
+ */
+
+/**
+ * Extract debug flag from config and context with proper fallback chain.
+ * 
+ * Checks in order:
+ * 1. config.debug (if explicitly set, including false)
+ * 2. ctx.debug (if available)
+ * 3. false (default)
+ * 
+ * @param {Object} config - Facet-specific configuration object (may be undefined)
+ * @param {Object} ctx - Context object with debug flag (may be undefined)
+ * @returns {boolean} Debug flag value
+ * 
+ * @example
+ * ```javascript
+ * const config = ctx.config?.router || {};
+ * const debug = getDebugFlag(config, ctx);
+ * ```
+ */
+export function getDebugFlag(config, ctx) {
+  if (config?.debug !== undefined) {
+    return !!config.debug;
+  }
+  if (ctx?.debug !== undefined) {
+    return !!ctx.debug;
+  }
+  return false;
+}
+

package/src/utils/find-facet.js

@@ -0,0 +1,30 @@
+/**
+ * findFacet Utility
+ * 
+ * Safely finds a facet by kind from a FacetManager.
+ * 
+ * @param {FacetManager} facetManager - The FacetManager instance (e.g., api.__facets)
+ * @param {string} kind - The facet kind to find
+ * @returns {false|{result: true, facet: Object}} - Returns false if not found, or an object with result and facet if found
+ * 
+ * @example
+ * const found = findFacet(api.__facets, 'router');
+ * if (found) {
+ *   const routerFacet = found.facet;
+ *   // Use routerFacet...
+ * }
+ */
+export function findFacet(facetManager, kind) {
+  if (!facetManager || typeof facetManager.find !== 'function') {
+    return false;
+  }
+  
+  const facet = facetManager.find(kind);
+  
+  if (!facet) {
+    return false;
+  }
+  
+  return { result: true, facet };
+}
+