prjct-cli 0.10.14 → 0.11.1

package/core/plugin/hooks.js

@@ -0,0 +1,313 @@
+/**
+ * HookSystem - Plugin Lifecycle Hooks for prjct-cli
+ *
+ * Provides hook points for plugins to extend prjct functionality.
+ * Hooks can modify data, add side effects, or integrate with external services.
+ *
+ * @version 1.0.0
+ */
+
+const { eventBus, EventTypes } = require('../bus')
+
+/**
+ * Hook Points - Where plugins can intercept
+ */
+const HookPoints = {
+  // Before hooks (can modify data)
+  BEFORE_SESSION_START: 'before:session.start',
+  BEFORE_SESSION_COMPLETE: 'before:session.complete',
+  BEFORE_TASK_CREATE: 'before:task.create',
+  BEFORE_FEATURE_SHIP: 'before:feature.ship',
+  BEFORE_SNAPSHOT_CREATE: 'before:snapshot.create',
+  BEFORE_COMMIT: 'before:git.commit',
+
+  // After hooks (for side effects)
+  AFTER_SESSION_START: 'after:session.start',
+  AFTER_SESSION_COMPLETE: 'after:session.complete',
+  AFTER_TASK_CREATE: 'after:task.create',
+  AFTER_TASK_COMPLETE: 'after:task.complete',
+  AFTER_FEATURE_SHIP: 'after:feature.ship',
+  AFTER_IDEA_CAPTURE: 'after:idea.capture',
+  AFTER_SNAPSHOT_CREATE: 'after:snapshot.create',
+  AFTER_SNAPSHOT_RESTORE: 'after:snapshot.restore',
+  AFTER_COMMIT: 'after:git.commit',
+  AFTER_PUSH: 'after:git.push',
+  AFTER_SYNC: 'after:project.sync',
+
+  // Transform hooks (must return modified data)
+  TRANSFORM_COMMIT_MESSAGE: 'transform:commit.message',
+  TRANSFORM_TASK_DATA: 'transform:task.data',
+  TRANSFORM_METRICS: 'transform:metrics'
+}
+
+class HookSystem {
+  constructor() {
+    this.hooks = new Map()
+    this.pluginHooks = new Map() // Track hooks by plugin
+  }
+
+  /**
+   * Register a hook handler
+   * @param {string} hookPoint - Hook point from HookPoints
+   * @param {Function} handler - Handler function
+   * @param {Object} options
+   * @param {string} options.pluginName - Name of the plugin
+   * @param {number} options.priority - Execution order (lower = first)
+   * @returns {Function} Unregister function
+   */
+  register(hookPoint, handler, options = {}) {
+    const { pluginName = 'anonymous', priority = 10 } = options
+
+    if (!this.hooks.has(hookPoint)) {
+      this.hooks.set(hookPoint, [])
+    }
+
+    const hookEntry = {
+      handler,
+      pluginName,
+      priority,
+      id: `${pluginName}:${Date.now()}`
+    }
+
+    this.hooks.get(hookPoint).push(hookEntry)
+
+    // Sort by priority
+    this.hooks.get(hookPoint).sort((a, b) => a.priority - b.priority)
+
+    // Track by plugin
+    if (!this.pluginHooks.has(pluginName)) {
+      this.pluginHooks.set(pluginName, [])
+    }
+    this.pluginHooks.get(pluginName).push({ hookPoint, id: hookEntry.id })
+
+    // Return unregister function
+    return () => this.unregister(hookPoint, hookEntry.id)
+  }
+
+  /**
+   * Unregister a hook handler
+   * @param {string} hookPoint
+   * @param {string} id
+   */
+  unregister(hookPoint, id) {
+    const hooks = this.hooks.get(hookPoint)
+    if (hooks) {
+      const index = hooks.findIndex(h => h.id === id)
+      if (index !== -1) {
+        hooks.splice(index, 1)
+      }
+    }
+  }
+
+  /**
+   * Unregister all hooks from a plugin
+   * @param {string} pluginName
+   */
+  unregisterPlugin(pluginName) {
+    const pluginEntries = this.pluginHooks.get(pluginName)
+    if (pluginEntries) {
+      for (const entry of pluginEntries) {
+        this.unregister(entry.hookPoint, entry.id)
+      }
+      this.pluginHooks.delete(pluginName)
+    }
+  }
+
+  /**
+   * Execute a "before" hook (can modify data)
+   * @param {string} hookPoint
+   * @param {Object} data - Data that can be modified
+   * @returns {Promise<Object>} Modified data
+   */
+  async executeBefore(hookPoint, data) {
+    const hooks = this.hooks.get(hookPoint) || []
+    let result = { ...data }
+
+    for (const hook of hooks) {
+      try {
+        const modified = await hook.handler(result)
+        if (modified !== undefined) {
+          result = { ...result, ...modified }
+        }
+      } catch (error) {
+        console.error(`Hook error [${hook.pluginName}] at ${hookPoint}:`, error.message)
+        // Continue with other hooks
+      }
+    }
+
+    return result
+  }
+
+  /**
+   * Execute an "after" hook (side effects only)
+   * @param {string} hookPoint
+   * @param {Object} data - Read-only data
+   * @returns {Promise<void>}
+   */
+  async executeAfter(hookPoint, data) {
+    const hooks = this.hooks.get(hookPoint) || []
+
+    // Execute all hooks in parallel for after hooks
+    await Promise.allSettled(
+      hooks.map(async hook => {
+        try {
+          await hook.handler(data)
+        } catch (error) {
+          console.error(`Hook error [${hook.pluginName}] at ${hookPoint}:`, error.message)
+        }
+      })
+    )
+
+    // Emit corresponding event for plugins listening via EventBus
+    const eventType = this.hookToEvent(hookPoint)
+    if (eventType) {
+      await eventBus.emit(eventType, data)
+    }
+  }
+
+  /**
+   * Execute a "transform" hook (must return modified value)
+   * @param {string} hookPoint
+   * @param {*} value - Value to transform
+   * @param {Object} context - Additional context
+   * @returns {Promise<*>} Transformed value
+   */
+  async executeTransform(hookPoint, value, context = {}) {
+    const hooks = this.hooks.get(hookPoint) || []
+    let result = value
+
+    for (const hook of hooks) {
+      try {
+        const transformed = await hook.handler(result, context)
+        if (transformed !== undefined) {
+          result = transformed
+        }
+      } catch (error) {
+        console.error(`Transform hook error [${hook.pluginName}] at ${hookPoint}:`, error.message)
+        // Keep previous value on error
+      }
+    }
+
+    return result
+  }
+
+  /**
+   * Map hook point to event type
+   * @param {string} hookPoint
+   * @returns {string|null}
+   */
+  hookToEvent(hookPoint) {
+    const mapping = {
+      [HookPoints.AFTER_SESSION_START]: EventTypes.SESSION_STARTED,
+      [HookPoints.AFTER_SESSION_COMPLETE]: EventTypes.SESSION_COMPLETED,
+      [HookPoints.AFTER_TASK_CREATE]: EventTypes.TASK_CREATED,
+      [HookPoints.AFTER_TASK_COMPLETE]: EventTypes.TASK_COMPLETED,
+      [HookPoints.AFTER_FEATURE_SHIP]: EventTypes.FEATURE_SHIPPED,
+      [HookPoints.AFTER_IDEA_CAPTURE]: EventTypes.IDEA_CAPTURED,
+      [HookPoints.AFTER_SNAPSHOT_CREATE]: EventTypes.SNAPSHOT_CREATED,
+      [HookPoints.AFTER_SNAPSHOT_RESTORE]: EventTypes.SNAPSHOT_RESTORED,
+      [HookPoints.AFTER_COMMIT]: EventTypes.COMMIT_CREATED,
+      [HookPoints.AFTER_PUSH]: EventTypes.PUSH_COMPLETED,
+      [HookPoints.AFTER_SYNC]: EventTypes.PROJECT_SYNCED
+    }
+    return mapping[hookPoint] || null
+  }
+
+  /**
+   * Get all registered hooks for a point
+   * @param {string} hookPoint
+   * @returns {Object[]}
+   */
+  getHooks(hookPoint) {
+    return (this.hooks.get(hookPoint) || []).map(h => ({
+      pluginName: h.pluginName,
+      priority: h.priority
+    }))
+  }
+
+  /**
+   * Get all hooks registered by a plugin
+   * @param {string} pluginName
+   * @returns {string[]} Hook points
+   */
+  getPluginHooks(pluginName) {
+    const entries = this.pluginHooks.get(pluginName) || []
+    return entries.map(e => e.hookPoint)
+  }
+
+  /**
+   * Check if a hook point has any handlers
+   * @param {string} hookPoint
+   * @returns {boolean}
+   */
+  hasHooks(hookPoint) {
+    const hooks = this.hooks.get(hookPoint)
+    return hooks && hooks.length > 0
+  }
+
+  /**
+   * Clear all hooks
+   */
+  clear() {
+    this.hooks.clear()
+    this.pluginHooks.clear()
+  }
+}
+
+// Singleton instance
+const hookSystem = new HookSystem()
+
+// Convenience wrapper for common hook patterns
+const hooks = {
+  /**
+   * Register a before hook
+   */
+  before: (point, handler, options) => {
+    const hookPoint = `before:${point}`
+    return hookSystem.register(hookPoint, handler, options)
+  },
+
+  /**
+   * Register an after hook
+   */
+  after: (point, handler, options) => {
+    const hookPoint = `after:${point}`
+    return hookSystem.register(hookPoint, handler, options)
+  },
+
+  /**
+   * Register a transform hook
+   */
+  transform: (point, handler, options) => {
+    const hookPoint = `transform:${point}`
+    return hookSystem.register(hookPoint, handler, options)
+  },
+
+  /**
+   * Execute before hooks
+   */
+  runBefore: (point, data) => {
+    return hookSystem.executeBefore(`before:${point}`, data)
+  },
+
+  /**
+   * Execute after hooks
+   */
+  runAfter: (point, data) => {
+    return hookSystem.executeAfter(`after:${point}`, data)
+  },
+
+  /**
+   * Execute transform hooks
+   */
+  runTransform: (point, value, context) => {
+    return hookSystem.executeTransform(`transform:${point}`, value, context)
+  }
+}
+
+module.exports = {
+  HookSystem,
+  HookPoints,
+  hookSystem,
+  hooks
+}

package/core/plugin/index.js

@@ -0,0 +1,52 @@
+/**
+ * Plugin System - Main Entry Point
+ *
+ * Exports all plugin-related functionality.
+ *
+ * @version 1.0.0
+ */
+
+const { HookSystem, HookPoints, hookSystem, hooks } = require('./hooks')
+const { PluginLoader, pluginLoader } = require('./loader')
+const { PluginRegistry, pluginRegistry } = require('./registry')
+
+/**
+ * Initialize the complete plugin system
+ * @param {string} projectPath
+ * @param {Object} config
+ */
+async function initializePlugins(projectPath, config = {}) {
+  await pluginRegistry.initialize()
+  await pluginLoader.initialize(projectPath, config)
+}
+
+/**
+ * Shutdown the plugin system
+ */
+async function shutdownPlugins() {
+  const plugins = pluginLoader.getAllPlugins()
+
+  for (const plugin of plugins) {
+    await pluginLoader.unloadPlugin(plugin.name)
+  }
+}
+
+module.exports = {
+  // Hook system
+  HookSystem,
+  HookPoints,
+  hookSystem,
+  hooks,
+
+  // Plugin loader
+  PluginLoader,
+  pluginLoader,
+
+  // Plugin registry
+  PluginRegistry,
+  pluginRegistry,
+
+  // Convenience functions
+  initializePlugins,
+  shutdownPlugins
+}

package/core/plugin/loader.js

@@ -0,0 +1,331 @@
+/**
+ * PluginLoader - Dynamic Plugin Loading for prjct-cli
+ *
+ * Loads plugins from:
+ * 1. Built-in plugins (core/plugins/*)
+ * 2. Global plugins (~/.prjct-cli/plugins/*)
+ * 3. Project plugins (configured in prjct.config.json)
+ *
+ * @version 1.0.0
+ */
+
+const fs = require('fs').promises
+const path = require('path')
+const { hookSystem } = require('./hooks')
+const { eventBus } = require('../bus')
+const pathManager = require('../infrastructure/path-manager')
+
+/**
+ * Plugin Interface
+ * @typedef {Object} Plugin
+ * @property {string} name - Unique plugin name
+ * @property {string} version - Semver version
+ * @property {string} [description] - Plugin description
+ * @property {Object} [hooks] - Hook handlers
+ * @property {Object} [commands] - Custom commands
+ * @property {Function} [activate] - Called when plugin loads
+ * @property {Function} [deactivate] - Called when plugin unloads
+ */
+
+class PluginLoader {
+  constructor() {
+    this.plugins = new Map()
+    this.pluginPaths = new Map()
+    this.initialized = false
+  }
+
+  /**
+   * Initialize plugin system
+   * @param {string} projectPath - Project root path
+   * @param {Object} config - Project config
+   */
+  async initialize(projectPath, config = {}) {
+    if (this.initialized) return
+
+    this.projectPath = projectPath
+    this.config = config
+
+    // Load plugins in order
+    await this.loadBuiltinPlugins()
+    await this.loadGlobalPlugins()
+    await this.loadProjectPlugins(config.plugins || [])
+
+    this.initialized = true
+  }
+
+  /**
+   * Load built-in plugins from core/plugins
+   */
+  async loadBuiltinPlugins() {
+    const builtinPath = path.join(__dirname, '..', 'plugins')
+
+    try {
+      const files = await fs.readdir(builtinPath)
+
+      for (const file of files) {
+        if (file.endsWith('.js')) {
+          const pluginPath = path.join(builtinPath, file)
+          await this.loadPlugin(pluginPath, 'builtin')
+        }
+      }
+    } catch {
+      // No built-in plugins directory yet
+    }
+  }
+
+  /**
+   * Load global plugins from ~/.prjct-cli/plugins
+   */
+  async loadGlobalPlugins() {
+    const globalPath = path.join(pathManager.getGlobalStoragePath(), 'plugins')
+
+    try {
+      const files = await fs.readdir(globalPath)
+
+      for (const file of files) {
+        if (file.endsWith('.js') || (await this.isDirectory(path.join(globalPath, file)))) {
+          const pluginPath = file.endsWith('.js')
+            ? path.join(globalPath, file)
+            : path.join(globalPath, file, 'index.js')
+          await this.loadPlugin(pluginPath, 'global')
+        }
+      }
+    } catch {
+      // No global plugins directory
+    }
+  }
+
+  /**
+   * Load project-specific plugins from config
+   * @param {Array<string|Object>} plugins - Plugin specs from config
+   */
+  async loadProjectPlugins(plugins) {
+    for (const spec of plugins) {
+      try {
+        if (typeof spec === 'string') {
+          // Simple name or path
+          if (spec.startsWith('file://')) {
+            // Local file path
+            const filePath = spec.replace('file://', '')
+            const fullPath = path.resolve(this.projectPath, filePath)
+            await this.loadPlugin(fullPath, 'project')
+          } else if (spec.startsWith('./') || spec.startsWith('../')) {
+            // Relative path
+            const fullPath = path.resolve(this.projectPath, spec)
+            await this.loadPlugin(fullPath, 'project')
+          } else {
+            // Plugin name - check if already loaded
+            if (!this.plugins.has(spec)) {
+              console.warn(`Plugin not found: ${spec}`)
+            }
+          }
+        } else if (typeof spec === 'object' && spec.path) {
+          // Object with path and config
+          const fullPath = path.resolve(this.projectPath, spec.path)
+          await this.loadPlugin(fullPath, 'project', spec.config)
+        }
+      } catch (error) {
+        console.error(`Failed to load plugin: ${spec}`, error.message)
+      }
+    }
+  }
+
+  /**
+   * Load a single plugin
+   * @param {string} pluginPath - Path to plugin file
+   * @param {string} source - 'builtin', 'global', or 'project'
+   * @param {Object} config - Plugin-specific config
+   */
+  async loadPlugin(pluginPath, source, config = {}) {
+    try {
+      // Check if file exists
+      await fs.access(pluginPath)
+
+      // Require the plugin
+      const plugin = require(pluginPath)
+
+      // Validate plugin structure
+      if (!plugin.name) {
+        throw new Error('Plugin must have a name property')
+      }
+
+      if (this.plugins.has(plugin.name)) {
+        console.warn(`Plugin already loaded: ${plugin.name}`)
+        return
+      }
+
+      // Store plugin
+      this.plugins.set(plugin.name, {
+        ...plugin,
+        source,
+        config: { ...config, ...this.config[plugin.name] }
+      })
+      this.pluginPaths.set(plugin.name, pluginPath)
+
+      // Register hooks
+      if (plugin.hooks) {
+        this.registerPluginHooks(plugin)
+      }
+
+      // Register event listeners
+      if (plugin.events) {
+        this.registerPluginEvents(plugin)
+      }
+
+      // Call activate if exists
+      if (typeof plugin.activate === 'function') {
+        await plugin.activate({
+          config: this.plugins.get(plugin.name).config,
+          eventBus,
+          hookSystem,
+          projectPath: this.projectPath
+        })
+      }
+
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        // File not found - skip silently
+      } else if (error.code === 'MODULE_NOT_FOUND') {
+        console.error(`Plugin module not found: ${pluginPath}`)
+      } else {
+        console.error(`Failed to load plugin from ${pluginPath}:`, error.message)
+      }
+    }
+  }
+
+  /**
+   * Register plugin hooks
+   * @param {Plugin} plugin
+   */
+  registerPluginHooks(plugin) {
+    for (const [hookPoint, handler] of Object.entries(plugin.hooks)) {
+      hookSystem.register(hookPoint, handler, {
+        pluginName: plugin.name,
+        priority: plugin.priority || 10
+      })
+    }
+  }
+
+  /**
+   * Register plugin event listeners
+   * @param {Plugin} plugin
+   */
+  registerPluginEvents(plugin) {
+    for (const [eventType, handler] of Object.entries(plugin.events)) {
+      eventBus.on(eventType, handler)
+    }
+  }
+
+  /**
+   * Unload a plugin
+   * @param {string} name - Plugin name
+   */
+  async unloadPlugin(name) {
+    const plugin = this.plugins.get(name)
+    if (!plugin) return
+
+    // Call deactivate if exists
+    if (typeof plugin.deactivate === 'function') {
+      await plugin.deactivate()
+    }
+
+    // Unregister hooks
+    hookSystem.unregisterPlugin(name)
+
+    // Remove from loaded plugins
+    this.plugins.delete(name)
+    this.pluginPaths.delete(name)
+
+    // Clear require cache
+    const pluginPath = this.pluginPaths.get(name)
+    if (pluginPath) {
+      delete require.cache[require.resolve(pluginPath)]
+    }
+  }
+
+  /**
+   * Reload a plugin
+   * @param {string} name - Plugin name
+   */
+  async reloadPlugin(name) {
+    const pluginPath = this.pluginPaths.get(name)
+    const plugin = this.plugins.get(name)
+
+    if (!pluginPath || !plugin) {
+      throw new Error(`Plugin not found: ${name}`)
+    }
+
+    await this.unloadPlugin(name)
+    await this.loadPlugin(pluginPath, plugin.source, plugin.config)
+  }
+
+  /**
+   * Get a loaded plugin
+   * @param {string} name
+   * @returns {Plugin|null}
+   */
+  getPlugin(name) {
+    return this.plugins.get(name) || null
+  }
+
+  /**
+   * Get all loaded plugins
+   * @returns {Plugin[]}
+   */
+  getAllPlugins() {
+    return Array.from(this.plugins.values())
+  }
+
+  /**
+   * Get plugins by source
+   * @param {string} source - 'builtin', 'global', or 'project'
+   * @returns {Plugin[]}
+   */
+  getPluginsBySource(source) {
+    return this.getAllPlugins().filter(p => p.source === source)
+  }
+
+  /**
+   * Get custom commands from all plugins
+   * @returns {Object} Map of command name to handler
+   */
+  getPluginCommands() {
+    const commands = {}
+
+    for (const plugin of this.plugins.values()) {
+      if (plugin.commands) {
+        for (const [name, handler] of Object.entries(plugin.commands)) {
+          commands[name] = {
+            handler,
+            plugin: plugin.name,
+            description: handler.description || `Command from ${plugin.name}`
+          }
+        }
+      }
+    }
+
+    return commands
+  }
+
+  /**
+   * Check if path is a directory
+   * @param {string} p
+   * @returns {Promise<boolean>}
+   */
+  async isDirectory(p) {
+    try {
+      const stat = await fs.stat(p)
+      return stat.isDirectory()
+    } catch {
+      return false
+    }
+  }
+}
+
+// Singleton instance
+const pluginLoader = new PluginLoader()
+
+module.exports = {
+  PluginLoader,
+  pluginLoader
+}