@terrymooreii/sia 2.2.0 → 2.3.1

package/lib/hooks.js

@@ -0,0 +1,188 @@
+/**
+ * Hook system for plugins
+ * Manages hook registration and execution
+ */
+
+class HookRegistry {
+  constructor() {
+    this.hooks = new Map();
+    this.pluginHooks = new Map(); // Track which plugin registered which hooks
+  }
+  
+  /**
+   * Register hooks from a plugin
+   */
+  registerPluginHooks(plugin) {
+    if (!plugin.hooks || typeof plugin.hooks !== 'object') {
+      return;
+    }
+    
+    const pluginName = plugin.name;
+    
+    for (const [hookName, hookFunction] of Object.entries(plugin.hooks)) {
+      if (typeof hookFunction !== 'function') {
+        console.warn(`⚠️  Plugin ${pluginName}: Hook "${hookName}" is not a function, skipping`);
+        continue;
+      }
+      
+      if (!this.hooks.has(hookName)) {
+        this.hooks.set(hookName, []);
+      }
+      
+      this.hooks.get(hookName).push({
+        plugin: pluginName,
+        fn: hookFunction
+      });
+      
+      // Track plugin hooks
+      if (!this.pluginHooks.has(pluginName)) {
+        this.pluginHooks.set(pluginName, []);
+      }
+      this.pluginHooks.get(pluginName).push(hookName);
+    }
+  }
+  
+  /**
+   * Execute a hook with given arguments
+   */
+  async executeHook(hookName, ...args) {
+    const hooks = this.hooks.get(hookName) || [];
+    
+    if (hooks.length === 0) {
+      return;
+    }
+    
+    const results = [];
+    
+    for (const { plugin, fn } of hooks) {
+      try {
+        const result = await fn(...args);
+        results.push({ plugin, result, error: null });
+      } catch (err) {
+        results.push({ plugin, result: null, error: err });
+        console.error(`❌ Plugin ${plugin} hook "${hookName}" failed:`, err.message);
+        if (process.env.VERBOSE || process.env.DEBUG) {
+          console.error(err.stack);
+        }
+      }
+    }
+    
+    return results;
+  }
+  
+  /**
+   * Execute a hook and return the last result (for hooks that modify data)
+   */
+  async executeHookWithResult(hookName, initialValue, ...args) {
+    const hooks = this.hooks.get(hookName) || [];
+    
+    let value = initialValue;
+    
+    for (const { plugin, fn } of hooks) {
+      try {
+        const result = await fn(value, ...args);
+        // If hook returns a value, use it as the new value
+        if (result !== undefined && result !== null) {
+          value = result;
+        }
+      } catch (err) {
+        console.error(`❌ Plugin ${plugin} hook "${hookName}" failed:`, err.message);
+        if (process.env.VERBOSE || process.env.DEBUG) {
+          console.error(err.stack);
+        }
+      }
+    }
+    
+    return value;
+  }
+  
+  /**
+   * Get all registered hooks for a plugin
+   */
+  getPluginHooks(pluginName) {
+    return this.pluginHooks.get(pluginName) || [];
+  }
+  
+  /**
+   * Clear all hooks
+   */
+  clear() {
+    this.hooks.clear();
+    this.pluginHooks.clear();
+  }
+}
+
+// Global hook registry instance
+let hookRegistry = null;
+
+/**
+ * Initialize the hook system
+ */
+export function initializeHooks() {
+  hookRegistry = new HookRegistry();
+  return hookRegistry;
+}
+
+/**
+ * Get the hook registry instance
+ */
+export function getHookRegistry() {
+  if (!hookRegistry) {
+    hookRegistry = new HookRegistry();
+  }
+  return hookRegistry;
+}
+
+/**
+ * Register hooks from all plugins
+ */
+export function registerPluginHooks(plugins) {
+  const registry = getHookRegistry();
+  
+  for (const plugin of plugins) {
+    registry.registerPluginHooks(plugin);
+  }
+}
+
+/**
+ * Execute a hook
+ */
+export async function executeHook(hookName, ...args) {
+  const registry = getHookRegistry();
+  return registry.executeHook(hookName, ...args);
+}
+
+/**
+ * Execute a hook and return the result (for data transformation hooks)
+ */
+export async function executeHookWithResult(hookName, initialValue, ...args) {
+  const registry = getHookRegistry();
+  return registry.executeHookWithResult(hookName, initialValue, ...args);
+}
+
+/**
+ * Check if a hook has any registered handlers
+ */
+export function hasHook(hookName) {
+  const registry = getHookRegistry();
+  return registry.hooks.has(hookName) && registry.hooks.get(hookName).length > 0;
+}
+
+/**
+ * Clear all hooks (useful for testing)
+ */
+export function clearHooks() {
+  const registry = getHookRegistry();
+  registry.clear();
+}
+
+export default {
+  initializeHooks,
+  getHookRegistry,
+  registerPluginHooks,
+  executeHook,
+  executeHookWithResult,
+  hasHook,
+  clearHooks
+};
+

package/lib/index.js

@@ -34,6 +34,25 @@ export { build, buildCommand } from './build.js';
 export { startServer, devCommand } from './server.js';
 export { newCommand } from './new.js';
 export { initSite, initCommand } from './init.js';
+export {
+  discoverPlugins,
+  loadPlugins,
+  loadPlugin,
+  validatePlugin,
+  discoverLocalPlugins,
+  discoverNpmPlugins,
+  orderPlugins
+} from './plugins.js';
+export {
+  initializeHooks,
+  getHookRegistry,
+  registerPluginHooks,
+  executeHook,
+  executeHookWithResult,
+  hasHook,
+  clearHooks
+} from './hooks.js';
+export { addMarkedExtension } from './content.js';
 
 // Default export with version
 import { readFileSync } from 'fs';

package/lib/plugins.js

@@ -0,0 +1,350 @@
+import { readdirSync, statSync, existsSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Validate plugin structure
+ */
+export function validatePlugin(plugin, pluginPath) {
+  if (!plugin) {
+    throw new Error('Plugin is null or undefined');
+  }
+  
+  if (!plugin.name || typeof plugin.name !== 'string') {
+    throw new Error('Plugin must have a "name" property (string)');
+  }
+  
+  if (!plugin.version || typeof plugin.version !== 'string') {
+    throw new Error('Plugin must have a "version" property (string)');
+  }
+  
+  // Validate hooks if present
+  if (plugin.hooks && typeof plugin.hooks !== 'object') {
+    throw new Error('Plugin "hooks" must be an object');
+  }
+  
+  // Validate configSchema if present
+  if (plugin.configSchema && typeof plugin.configSchema !== 'object') {
+    throw new Error('Plugin "configSchema" must be an object');
+  }
+  
+  // Validate dependencies if present
+  if (plugin.dependencies && !Array.isArray(plugin.dependencies)) {
+    throw new Error('Plugin "dependencies" must be an array');
+  }
+  
+  return true;
+}
+
+/**
+ * Load a plugin from a file path
+ */
+export async function loadPlugin(pluginPath, config) {
+  try {
+    // Support both .js and .mjs files
+    // Add cache busting query parameter to ensure fresh reloads during dev
+    // This prevents Node.js from using cached versions of plugins during hot reload
+    const cacheBuster = `?t=${Date.now()}`;
+    let module;
+    
+    // Normalize path to use file:// protocol for consistent cache busting
+    // All plugin paths from discovery are absolute, so we can safely use file://
+    const normalizedPath = pluginPath.startsWith('file://') 
+      ? pluginPath 
+      : pluginPath.startsWith('/') || /^[A-Za-z]:/.test(pluginPath) // Unix absolute or Windows drive
+        ? `file://${pluginPath}`
+        : pluginPath; // Relative path (shouldn't happen, but handle it)
+    
+    // Import with cache busting to ensure fresh reloads during dev
+    module = await import(`${normalizedPath}${cacheBuster}`);
+    
+    // Support both default export and named export
+    const plugin = module.default || module;
+    
+    if (!plugin) {
+      throw new Error('Plugin file does not export a plugin object');
+    }
+    
+    // Validate plugin structure
+    validatePlugin(plugin, pluginPath);
+    
+    // Add metadata
+    plugin._path = pluginPath;
+    plugin._loaded = true;
+    
+    return plugin;
+  } catch (err) {
+    throw new Error(`Failed to load plugin from ${pluginPath}: ${err.message}`);
+  }
+}
+
+/**
+ * Discover local plugins from _plugins directory
+ */
+export function discoverLocalPlugins(rootDir) {
+  const pluginsDir = join(rootDir, '_plugins');
+  const plugins = [];
+  
+  if (!existsSync(pluginsDir)) {
+    return plugins;
+  }
+  
+  try {
+    const items = readdirSync(pluginsDir);
+    console.log(`🔍 Scanning _plugins directory: found ${items.length} item(s)`);
+    
+    for (const item of items) {
+      const itemPath = join(pluginsDir, item);
+      const stat = statSync(itemPath);
+      
+      // Check extension case-insensitively
+      const lowerItem = item.toLowerCase();
+      const isJsFile = lowerItem.endsWith('.js') || lowerItem.endsWith('.mjs');
+      
+      // Debug: log what we found
+      if (stat.isFile()) {
+        console.log(`  📄 Found file: ${item} (${isJsFile ? 'plugin candidate' : 'skipped - not .js/.mjs'})`);
+      } else if (stat.isDirectory()) {
+        console.log(`  📁 Found directory: ${item} (skipped - plugins must be files)`);
+      }
+      
+      // Only process .js and .mjs files (case-insensitive)
+      if (stat.isFile() && isJsFile) {
+        plugins.push({
+          type: 'local',
+          path: itemPath,
+          name: item.replace(/\.(js|mjs)$/i, '') // Case-insensitive replacement
+        });
+        console.log(`  ✓ Added plugin: ${item}`);
+      }
+    }
+  } catch (err) {
+    console.warn(`⚠️  Error reading _plugins directory: ${err.message}`);
+  }
+  
+  return plugins;
+}
+
+/**
+ * Discover npm plugins from node_modules
+ */
+export function discoverNpmPlugins(rootDir) {
+  const nodeModulesDir = join(rootDir, 'node_modules');
+  const plugins = [];
+  
+  if (!existsSync(nodeModulesDir)) {
+    return plugins;
+  }
+  
+  try {
+    const packages = readdirSync(nodeModulesDir);
+    
+    for (const pkg of packages) {
+      // Look for sia-plugin-* packages
+      if (pkg.startsWith('sia-plugin-')) {
+        const pkgPath = join(nodeModulesDir, pkg);
+        const pkgJsonPath = join(pkgPath, 'package.json');
+        
+        if (existsSync(pkgJsonPath)) {
+          try {
+            const pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+            const mainFile = pkgJson.main || 'index.js';
+            const pluginPath = join(pkgPath, mainFile);
+            
+            if (existsSync(pluginPath)) {
+              plugins.push({
+                type: 'npm',
+                path: pluginPath,
+                name: pkg,
+                packageName: pkg,
+                version: pkgJson.version
+              });
+            }
+          } catch (err) {
+            console.warn(`⚠️  Error reading package.json for ${pkg}: ${err.message}`);
+          }
+        }
+      }
+    }
+  } catch (err) {
+    console.warn(`⚠️  Error reading node_modules: ${err.message}`);
+  }
+  
+  return plugins;
+}
+
+/**
+ * Resolve plugin dependencies and order
+ */
+export function orderPlugins(plugins, config) {
+  // If explicit order is provided in config, use it
+  const explicitOrder = config.plugins?.order;
+  if (explicitOrder && Array.isArray(explicitOrder)) {
+    const ordered = [];
+    const pluginMap = new Map(plugins.map(p => [p.name, p]));
+    const added = new Set();
+    
+    // Add plugins in explicit order
+    for (const name of explicitOrder) {
+      const plugin = pluginMap.get(name);
+      if (plugin) {
+        ordered.push(plugin);
+        added.add(name);
+      }
+    }
+    
+    // Add remaining plugins
+    for (const plugin of plugins) {
+      if (!added.has(plugin.name)) {
+        ordered.push(plugin);
+      }
+    }
+    
+    return ordered;
+  }
+  
+  // Otherwise, resolve dependencies
+  const pluginMap = new Map(plugins.map(p => [p.name, p]));
+  const ordered = [];
+  const added = new Set();
+  const visiting = new Set();
+  
+  function visit(plugin) {
+    if (added.has(plugin.name)) {
+      return;
+    }
+    
+    if (visiting.has(plugin.name)) {
+      console.warn(`⚠️  Circular dependency detected involving plugin: ${plugin.name}`);
+      return;
+    }
+    
+    visiting.add(plugin.name);
+    
+    // Visit dependencies first
+    if (plugin.dependencies && Array.isArray(plugin.dependencies)) {
+      for (const depName of plugin.dependencies) {
+        const dep = pluginMap.get(depName);
+        if (dep) {
+          visit(dep);
+        } else {
+          console.warn(`⚠️  Plugin ${plugin.name} depends on ${depName}, but it's not found`);
+        }
+      }
+    }
+    
+    visiting.delete(plugin.name);
+    ordered.push(plugin);
+    added.add(plugin.name);
+  }
+  
+  // Visit all plugins
+  for (const plugin of plugins) {
+    visit(plugin);
+  }
+  
+  return ordered;
+}
+
+/**
+ * Discover and load all plugins
+ */
+export async function discoverPlugins(config) {
+  // Check if plugins are enabled
+  if (config.plugins?.enabled === false) {
+    return [];
+  }
+  
+  const rootDir = config.rootDir || process.cwd();
+  const discovered = [];
+  
+  // Discover local plugins
+  const localPlugins = discoverLocalPlugins(rootDir);
+  discovered.push(...localPlugins);
+  
+  // Discover npm plugins
+  const npmPlugins = discoverNpmPlugins(rootDir);
+  discovered.push(...npmPlugins);
+  
+  // Filter by explicit plugin list if provided
+  const explicitPlugins = config.plugins?.plugins;
+  if (explicitPlugins && Array.isArray(explicitPlugins) && explicitPlugins.length > 0) {
+    console.log(`🔍 Filtering plugins: only loading ${explicitPlugins.join(', ')}`);
+    const explicitSet = new Set(explicitPlugins);
+    const filtered = discovered.filter(p => explicitSet.has(p.name));
+    const filteredOut = discovered.filter(p => !explicitSet.has(p.name));
+    if (filteredOut.length > 0) {
+      console.log(`  ⚠️  Filtered out ${filteredOut.length} plugin(s): ${filteredOut.map(p => p.name).join(', ')}`);
+    }
+    return filtered;
+  }
+  
+  return discovered;
+}
+
+/**
+ * Load all discovered plugins
+ */
+export async function loadPlugins(config) {
+  // Check if plugins are disabled
+  if (config.plugins?.enabled === false) {
+    console.log('🔌 Plugins are disabled in config');
+    return [];
+  }
+  
+  const rootDir = config.rootDir || process.cwd();
+  const discovered = await discoverPlugins(config);
+  
+  if (discovered.length === 0) {
+    // Log that we checked but found nothing (helps with debugging)
+    const pluginsDir = join(rootDir, '_plugins');
+    const hasPluginsDir = existsSync(pluginsDir);
+    if (hasPluginsDir) {
+      console.log('🔌 No plugins discovered (directory exists but no valid plugins found)');
+    } else {
+      console.log('🔌 No plugins directory found, skipping plugin discovery');
+    }
+    return [];
+  }
+  
+  console.log(`🔌 Found ${discovered.length} plugin(s)`);
+  
+  const loaded = [];
+  const errors = [];
+  
+  for (const pluginInfo of discovered) {
+    try {
+      const plugin = await loadPlugin(pluginInfo.path, config);
+      plugin._type = pluginInfo.type;
+      plugin._packageName = pluginInfo.packageName;
+      loaded.push(plugin);
+      console.log(`  ✓ Loaded ${plugin.name}@${plugin.version} (${pluginInfo.type})`);
+    } catch (err) {
+      errors.push({ name: pluginInfo.name, error: err.message });
+      console.warn(`  ✗ Failed to load ${pluginInfo.name}: ${err.message}`);
+    }
+  }
+  
+  if (errors.length > 0 && config.plugins?.strictMode) {
+    throw new Error(`Plugin loading failed in strict mode. ${errors.length} plugin(s) failed to load.`);
+  }
+  
+  // Order plugins
+  const ordered = orderPlugins(loaded, config);
+  
+  return ordered;
+}
+
+export default {
+  discoverPlugins,
+  loadPlugins,
+  loadPlugin,
+  validatePlugin,
+  discoverLocalPlugins,
+  discoverNpmPlugins,
+  orderPlugins
+};
+

package/lib/server.js

@@ -166,7 +166,8 @@ function setupWatcher(config, wss) {
     config.includesDir,
     join(config.rootDir, '_config.yml'),
     join(config.rootDir, '_config.json'),
-    join(config.rootDir, 'styles')
+    join(config.rootDir, 'styles'),
+    join(config.rootDir, '_plugins')
   ].filter(p => existsSync(p));
   
   const watcher = chokidar.watch(watchPaths, {

package/lib/templates.js

@@ -3,6 +3,7 @@ import { join, dirname } from 'path';
 import { existsSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { resolveTheme, getBuiltInThemesDir } from './theme-resolver.js';
+import { executeHook } from './hooks.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -195,7 +196,7 @@ function createUrlFilter(basePath) {
  * @param {object} config - Site configuration
  * @param {object} [resolvedTheme] - Pre-resolved theme info from resolveTheme()
  */
-export function createTemplateEngine(config, resolvedTheme = null) {
+export async function createTemplateEngine(config, resolvedTheme = null) {
   // Set up template paths - user layouts first, then defaults
   const templatePaths = [];
   
@@ -247,6 +248,11 @@ export function createTemplateEngine(config, resolvedTheme = null) {
   // Add URL filter with basePath support
   env.addFilter('url', createUrlFilter(config.site.basePath));
   
+  // Execute addTemplateFilter and addTemplateFunction hooks
+  // These hooks allow plugins to register custom filters and functions
+  const filterResults = await executeHook('addTemplateFilter', env, config);
+  const functionResults = await executeHook('addTemplateFunction', env, config);
+  
   return env;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terrymooreii/sia",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "description": "A simple, powerful static site generator with markdown, front matter, and Nunjucks templates",
   "main": "lib/index.js",
   "bin": {