mycelia-kernel-plugin 1.0.0

package/src/core/create-hook.js

@@ -0,0 +1,63 @@
+import { isValidSemver, getDefaultVersion } from '../utils/semver.js';
+
+/**
+ * Hook Factory Function
+ * 
+ * Creates a hook function with attached metadata describing its behavior.
+ * 
+ * @param {Object} options - Hook configuration
+ * @param {string} options.kind - Facet kind identifier (e.g., 'router', 'queue')
+ * @param {string} [options.version='0.0.0'] - Semantic version (e.g., '1.0.0', '2.1.3-alpha')
+ * @param {boolean} [options.overwrite=false] - Whether this hook can overwrite an existing hook of the same kind
+ * @param {Array<string>} [options.required=[]] - Array of facet kinds this hook depends on
+ * @param {boolean} [options.attach=false] - Whether the resulting facet should be attached to the subsystem
+ * @param {string} options.source - File location/URL where the hook is defined (e.g., import.meta.url)
+ * @param {Function} options.fn - Hook function: (ctx, api, subsystem) => Facet
+ * @param {string} [options.contract=null] - Optional contract name (string) for this hook
+ * @returns {Function} Hook function with attached metadata
+ */
+export function createHook({ kind, version, overwrite = false, required = [], attach = false, source, fn, contract = null }) {
+  if (!kind || typeof kind !== 'string') {
+    throw new Error('createHook: kind must be a non-empty string');
+  }
+  if (!source || typeof source !== 'string') {
+    throw new Error('createHook: source must be a non-empty string');
+  }
+  if (typeof fn !== 'function') {
+    throw new Error('createHook: fn must be a function');
+  }
+  if (contract !== null && (typeof contract !== 'string' || !contract.trim())) {
+    throw new Error('createHook: contract must be a non-empty string or null');
+  }
+
+  // Validate version if provided, otherwise use default
+  const hookVersion = version || getDefaultVersion();
+  if (!isValidSemver(hookVersion)) {
+    throw new Error(
+      `createHook: invalid semver version "${hookVersion}" for hook "${kind}". ` +
+      'Must follow format: MAJOR.MINOR.PATCH (e.g., "1.0.0", "2.1.3-alpha")'
+    );
+  }
+
+  const hook = function(ctx, api, subsystem) {
+    // Pass contract name and version to hook function via context
+    const hookCtx = { 
+      ...ctx, 
+      __contract: contract || null,
+      __version: hookVersion
+    };
+    return fn(hookCtx, api, subsystem);
+  };
+
+  // Attach metadata to the hook function
+  hook.kind = kind;
+  hook.version = hookVersion;
+  hook.overwrite = overwrite;
+  hook.required = Array.isArray(required) ? [...required] : [];
+  hook.attach = attach;
+  hook.source = source;
+  hook.contract = contract || null;
+
+  return hook;
+}
+

package/src/core/facet.js

@@ -0,0 +1,189 @@
+import { getDefaultVersion, isValidSemver } from '../utils/semver.js';
+
+export class Facet {
+  #kind;
+  #version;
+  #attach;
+  #required;
+  #isInit = false;
+  #initCallback = null;
+  #disposeCallback = null;
+  #source;
+  #overwrite;
+  #contract = null;
+  orderIndex = null; // Public property: index in the orderedKinds array when added via addMany
+
+  constructor(kind, { attach = false, required = [], source, overwrite = false, contract = null, version } = {}) {
+    if (!kind || typeof kind !== 'string') {
+      throw new Error('Facet: kind must be a non-empty string');
+    }
+    if (contract !== null && (typeof contract !== 'string' || !contract.trim())) {
+      throw new Error('Facet: contract must be a non-empty string or null');
+    }
+    
+    // Validate version if provided, otherwise use default
+    const facetVersion = version || getDefaultVersion();
+    if (!isValidSemver(facetVersion)) {
+      throw new Error(
+        `Facet: invalid semver version "${facetVersion}" for facet "${kind}". ` +
+        'Must follow format: MAJOR.MINOR.PATCH (e.g., "1.0.0", "2.1.3-alpha")'
+      );
+    }
+    
+    this.#kind = kind;
+    this.#version = facetVersion;
+    this.#attach = !!attach;
+    this.#required = Array.isArray(required) ? [...new Set(required)] : [];
+    this.#source = source;
+    this.#overwrite = !!overwrite;
+    this.#contract = contract || null;
+    this.orderIndex = null;
+  }
+
+  add(object) {
+    if (!object || typeof object !== 'object') {
+      throw new Error('Facet.add: object must be a non-null object');
+    }
+    if (this.#isInit) {
+      throw new Error(`Facet '${this.#kind}': cannot mutate after init()`);
+    }
+    // Use Object.getOwnPropertyDescriptors to properly copy getters, setters, and other property descriptors
+    const descriptors = Object.getOwnPropertyDescriptors(object);
+    
+    // Filter out properties that already exist on this instance
+    const filteredDescriptors = {};
+    for (const key of Reflect.ownKeys(descriptors)) {
+      const descriptor = descriptors[key];
+      // Skip if property already exists on this instance (own property)
+      if (Object.prototype.hasOwnProperty.call(this, key)) {
+        continue;
+      }
+      
+      // Also check if it exists on the prototype and is non-configurable
+      const protoDescriptor = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(this), key);
+      if (protoDescriptor && !protoDescriptor.configurable) {
+        // Skip non-configurable properties from prototype (like Function.prototype.name)
+        continue;
+      }
+      // Create a new descriptor, preserving getters/setters but making it configurable
+      const newDescriptor = {
+        configurable: true,
+        enumerable: descriptor.enumerable !== false
+      };
+      
+      // Copy the appropriate property descriptor fields
+      if (descriptor.get || descriptor.set) {
+        // It's a getter/setter
+        if (descriptor.get) newDescriptor.get = descriptor.get;
+        if (descriptor.set) newDescriptor.set = descriptor.set;
+      } else {
+        // It's a value property
+        newDescriptor.value = descriptor.value;
+        newDescriptor.writable = descriptor.writable !== false;
+      }
+      
+      filteredDescriptors[key] = newDescriptor;
+    }
+    
+    // Define properties one by one, skipping any that fail (e.g., non-configurable existing properties)
+    for (const key of Reflect.ownKeys(filteredDescriptors)) {
+      const descriptor = filteredDescriptors[key];
+      try {
+        Object.defineProperty(this, key, descriptor);
+      } catch {
+        // Skip properties that can't be defined (e.g., read-only properties like 'name')
+        // This can happen if a property exists on the prototype chain and is non-configurable
+        continue;
+      }
+    }
+    
+    return this;
+  }
+
+  onInit(cb) {
+    if (typeof cb !== 'function') {
+      throw new Error(`Facet '${this.#kind}': onInit callback must be a function`);
+    }
+    if (this.#isInit) {
+      throw new Error(`Facet '${this.#kind}': onInit must be set before init()`);
+    }
+    this.#initCallback = cb;
+    return this;
+  }
+
+  onDispose(cb) {
+    if (typeof cb !== 'function') {
+      throw new Error(`Facet '${this.#kind}': onDispose callback must be a function`);
+    }
+    this.#disposeCallback = cb;
+    return this;
+  }
+
+  async init(ctx, api, subsystem) {
+    if (this.#isInit) return;
+    if (this.#initCallback) {
+      await this.#initCallback({ ctx, api, subsystem, facet: this });
+    }
+    this.#isInit = true;
+    Object.freeze(this);
+  }
+
+  async dispose() {
+    if (this.#disposeCallback) {
+      await this.#disposeCallback(this);
+    }
+  }
+
+  // ---- Dependency management ----
+
+  /** Add a dependency before initialization. */
+  addDependency(dep) {
+    if (this.#isInit) {
+      throw new Error(`Facet '${this.#kind}': cannot modify dependencies after init()`);
+    }
+    if (typeof dep !== 'string' || !dep.trim()) {
+      throw new Error(`Facet '${this.#kind}': dependency must be a non-empty string`);
+    }
+    if (!this.#required.includes(dep)) {
+      this.#required.push(dep);
+    }
+    return this;
+  }
+
+  /** Remove a dependency before initialization. */
+  removeDependency(dep) {
+    if (this.#isInit) {
+      throw new Error(`Facet '${this.#kind}': cannot modify dependencies after init()`);
+    }
+    const idx = this.#required.indexOf(dep);
+    if (idx !== -1) this.#required.splice(idx, 1);
+    return this;
+  }
+
+  // ---- Order index management ----
+
+  /** Set the order index (position in orderedKinds array). Can only be set before init(). */
+  setOrderIndex(index) {
+    if (this.#isInit) {
+      throw new Error(`Facet '${this.#kind}': cannot set order index after init()`);
+    }
+    if (typeof index !== 'number' || index < 0 || !Number.isInteger(index)) {
+      throw new Error(`Facet '${this.#kind}': order index must be a non-negative integer`);
+    }
+    this.orderIndex = index;
+    return this;
+  }
+
+  // ---- Introspection ----
+
+  getKind() { return this.#kind; }
+  getVersion() { return this.#version; }
+  shouldAttach() { return this.#attach; }
+  shouldOverwrite() { return this.#overwrite; }
+  getDependencies() { return this.#required.slice(); }
+  hasDependency(dep) { return this.#required.includes(dep); }
+  hasDependencies() { return this.#required.length > 0; }
+  getSource() { return this.#source; }
+  getContract() { return this.#contract; }
+}
+

package/src/core/index.js

@@ -0,0 +1,3 @@
+export { createHook } from './create-hook.js';
+export { Facet } from './facet.js';
+

package/src/hooks/listeners/handler-group-manager.js

@@ -0,0 +1,88 @@
+/**
+ * HandlerGroupManager Class
+ * 
+ * Manages handler groups (onSuccess, onFailure, onTimeout callbacks).
+ * Wraps handler groups into functions that can be registered as listeners.
+ * 
+ * @example
+ * const manager = new HandlerGroupManager();
+ * const wrapped = manager.wrap({
+ *   onSuccess: (msg) => console.log('Success'),
+ *   onFailure: (msg) => console.error('Failure'),
+ *   onTimeout: (msg) => console.warn('Timeout')
+ * });
+ */
+export class HandlerGroupManager {
+  /**
+   * Create a new HandlerGroupManager instance
+   */
+  constructor() {
+    // No state needed
+  }
+
+  /**
+   * Wrap a handler group into a function with attached properties
+   * Handler groups contain onSuccess, onFailure, and onTimeout callbacks.
+   * 
+   * @param {Object} handlers - Handler group object with onSuccess, onFailure, onTimeout
+   * @returns {Function} Wrapped handler function with attached properties
+   * 
+   * @example
+   * const wrapped = manager.wrap({
+   *   onSuccess: (message) => console.log('Success:', message),
+   *   onFailure: (message) => console.error('Failure:', message),
+   *   onTimeout: (message) => console.warn('Timeout:', message)
+   * });
+   */
+  wrap(handlers) {
+    if (!handlers || typeof handlers !== 'object') {
+      throw new Error('Handler group must be an object');
+    }
+
+    // Wrap handler group into a function with attached properties
+    // eslint-disable-next-line no-unused-vars
+    const wrappedHandler = function(_message, ..._args) {
+      // This function will be called by ListenerManager
+      // Subsystems can access individual callbacks via properties
+    };
+    
+    // Attach handler group properties
+    wrappedHandler.onSuccess = handlers.onSuccess;
+    wrappedHandler.onFailure = handlers.onFailure;
+    wrappedHandler.onTimeout = handlers.onTimeout;
+    wrappedHandler._isHandlerGroup = true;
+    
+    return wrappedHandler;
+  }
+
+  /**
+   * Find a wrapped handler that matches the provided handler group
+   * 
+   * @param {Array<Function>} listeners - Array of listener functions
+   * @param {Object} handlers - Handler group object to match
+   * @returns {Function|null} Matching wrapped handler or null
+   */
+  find(listeners, handlers) {
+    if (!handlers || typeof handlers !== 'object') {
+      return null;
+    }
+
+    return listeners.find(listener => 
+      listener._isHandlerGroup &&
+      listener.onSuccess === handlers.onSuccess &&
+      listener.onFailure === handlers.onFailure &&
+      listener.onTimeout === handlers.onTimeout
+    ) || null;
+  }
+
+  /**
+   * Check if a handler is a handler group
+   * 
+   * @param {Function} handler - Handler function to check
+   * @returns {boolean} True if handler is a handler group
+   */
+  isHandlerGroup(handler) {
+    return handler && handler._isHandlerGroup === true;
+  }
+}
+

package/src/hooks/listeners/listener-manager-policies.js

@@ -0,0 +1,229 @@
+/**
+ * Listener Manager Policies
+ * 
+ * Pure functions that implement different listener registration policies.
+ * Each policy function takes existing listeners and returns new listener state.
+ * 
+ * @example
+ * // Multiple listeners allowed
+ * const result = multiplePolicy([handler1], 'layers/create', handler2, options);
+ * // result.listeners = [handler1, handler2]
+ * 
+ * @example
+ * // Only one listener allowed
+ * const result = singlePolicy([handler1], 'layers/create', handler2, options);
+ * // result.success = false, result.error = "Only one listener allowed..."
+ */
+
+/**
+ * Multiple Policy - Allow multiple listeners per path
+ * @param {Array<Function>} existingListeners - Current handlers for this path
+ * @param {string} path - Message path
+ * @param {Function} handler - New handler to register
+ * @param {Object} options - Policy options
+ * @param {string} options.policy - Policy name
+ * @param {boolean} options.debug - Debug flag
+ * @returns {Object} Registration result
+ */
+export function multiplePolicy(existingListeners, path, handler, options) {
+  return {
+    success: true,
+    listeners: [...existingListeners, handler],
+    error: null
+  };
+}
+
+/**
+ * Single Policy - Only allow one listener per path
+ * @param {Array<Function>} existingListeners - Current handlers for this path
+ * @param {string} path - Message path
+ * @param {Function} handler - New handler to register
+ * @param {Object} options - Policy options
+ * @param {string} options.policy - Policy name
+ * @param {boolean} options.debug - Debug flag
+ * @returns {Object} Registration result
+ */
+export function singlePolicy(existingListeners, path, handler, options) {
+  if (existingListeners.length > 0) {
+    return {
+      success: false,
+      listeners: existingListeners,
+      error: `Only one listener allowed for path '${path}' with 'single' policy`
+    };
+  }
+  
+  return {
+    success: true,
+    listeners: [handler],
+    error: null
+  };
+}
+
+/**
+ * Replace Policy - Replace all existing listeners with new one
+ * @param {Array<Function>} existingListeners - Current handlers for this path
+ * @param {string} path - Message path
+ * @param {Function} handler - New handler to register
+ * @param {Object} options - Policy options
+ * @param {string} options.policy - Policy name
+ * @param {boolean} options.debug - Debug flag
+ * @returns {Object} Registration result
+ */
+export function replacePolicy(existingListeners, path, handler, options) {
+  return {
+    success: true,
+    listeners: [handler], // Replace all existing
+    error: null
+  };
+}
+
+/**
+ * Append Policy - Always add new listener to end (same as multiple)
+ * @param {Array<Function>} existingListeners - Current handlers for this path
+ * @param {string} path - Message path
+ * @param {Function} handler - New handler to register
+ * @param {Object} options - Policy options
+ * @param {string} options.policy - Policy name
+ * @param {boolean} options.debug - Debug flag
+ * @returns {Object} Registration result
+ */
+export function appendPolicy(existingListeners, path, handler, options) {
+  return {
+    success: true,
+    listeners: [...existingListeners, handler],
+    error: null
+  };
+}
+
+/**
+ * Prepend Policy - Always add new listener to beginning
+ * @param {Array<Function>} existingListeners - Current handlers for this path
+ * @param {string} path - Message path
+ * @param {Function} handler - New handler to register
+ * @param {Object} options - Policy options
+ * @param {string} options.policy - Policy name
+ * @param {boolean} options.debug - Debug flag
+ * @returns {Object} Registration result
+ */
+export function prependPolicy(existingListeners, path, handler, options) {
+  return {
+    success: true,
+    listeners: [handler, ...existingListeners],
+    error: null
+  };
+}
+
+/**
+ * Priority Policy - Add listener with priority, sort by priority
+ * @param {Array<Function>} existingListeners - Current handlers for this path
+ * @param {string} path - Message path
+ * @param {Function} handler - New handler to register
+ * @param {Object} options - Policy options
+ * @param {string} options.policy - Policy name
+ * @param {boolean} options.debug - Debug flag
+ * @param {number} options.priority - Handler priority (higher = first)
+ * @returns {Object} Registration result
+ */
+export function priorityPolicy(existingListeners, path, handler, options) {
+  const priority = options.priority || 0;
+  
+  // Add priority metadata to handler
+  const prioritizedHandler = {
+    handler,
+    priority,
+    path
+  };
+  
+  // Add to existing listeners
+  const newListeners = [...existingListeners, prioritizedHandler];
+  
+  // Sort by priority (highest first)
+  newListeners.sort((a, b) => b.priority - a.priority);
+  
+  return {
+    success: true,
+    listeners: newListeners,
+    error: null
+  };
+}
+
+/**
+ * Limited Policy - Allow only up to maxListeners per path
+ * @param {Array<Function>} existingListeners - Current handlers for this path
+ * @param {string} path - Message path
+ * @param {Function} handler - New handler to register
+ * @param {Object} options - Policy options
+ * @param {string} options.policy - Policy name
+ * @param {boolean} options.debug - Debug flag
+ * @param {number} options.maxListeners - Maximum listeners allowed
+ * @returns {Object} Registration result
+ */
+export function limitedPolicy(existingListeners, path, handler, options) {
+  const maxListeners = options.maxListeners || 10;
+  
+  if (existingListeners.length >= maxListeners) {
+    return {
+      success: false,
+      listeners: existingListeners,
+      error: `Maximum ${maxListeners} listeners allowed for path '${path}' with 'limited' policy`
+    };
+  }
+  
+  return {
+    success: true,
+    listeners: [...existingListeners, handler],
+    error: null
+  };
+}
+
+/**
+ * Default policy registry
+ */
+export const DEFAULT_POLICIES = new Map([
+  ['multiple', multiplePolicy],
+  ['single', singlePolicy],
+  ['replace', replacePolicy],
+  ['append', appendPolicy],
+  ['prepend', prependPolicy],
+  ['priority', priorityPolicy],
+  ['limited', limitedPolicy]
+]);
+
+/**
+ * Get available policy names
+ * @returns {Array<string>} Array of policy names
+ */
+export function getAvailablePolicies() {
+  return Array.from(DEFAULT_POLICIES.keys());
+}
+
+/**
+ * Validate policy options
+ * @param {string} policyName - Policy name
+ * @param {Object} options - Policy options
+ * @returns {Object} Validation result
+ */
+export function validatePolicyOptions(policyName, options) {
+  const errors = [];
+  
+  switch (policyName) {
+    case 'priority':
+      if (options.priority !== undefined) {
+        if (typeof options.priority !== 'number') {
+          errors.push('priority must be a number');
+        }
+      }
+      break;
+      
+    case 'limited':
+      if (options.maxListeners !== undefined) {
+        if (typeof options.maxListeners !== 'number' || options.maxListeners < 1) {
+          errors.push('maxListeners must be a positive number');
+        }
+      }
+      break;
+  }
+  
+  return { valid: errors.length === 0, errors };
+}
+