@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/managers/PersonManager.d.ts

@@ -0,0 +1,48 @@
+import BaseManager, { type ManagerStats } from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { Person, PersonUpdate } from '../types/Person.js';
+import type { PersonProvider } from '../types/PersonProvider.js';
+/**
+ * PersonManager — canonical core record for persons (#617).
+ *
+ * Each User has at most one paired Person record. UserManager calls
+ * `create`/`update`/`delete` here on the matching user lifecycle events.
+ * `getByUserIdentifier(username)` remains as a lazy-migration entry point
+ * for legacy users that pre-date the sync wiring.
+ */
+declare class PersonManager extends BaseManager {
+    readonly description = "Canonical Person records (#617)";
+    private provider;
+    private providerClass?;
+    private byIdentifierCache;
+    private byIdCache;
+    private metricsRef;
+    constructor(engine: WikiEngine);
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    getProvider(): PersonProvider | null;
+    getById(id: string): Promise<Person | null>;
+    getByIdentifier(identifier: string): Promise<Person | null>;
+    /** #1006: how many people this instance holds. Count only, never records. */
+    getManagerStats(): Promise<ManagerStats>;
+    list(): Promise<Person[]>;
+    create(person: Person): Promise<Person>;
+    update(id: string, patch: PersonUpdate): Promise<Person | null>;
+    delete(id: string): Promise<boolean>;
+    /**
+     * Clear all caches. Called on every write — the simplest correct
+     * invalidation. Per-key invalidation can come later if needed.
+     */
+    invalidateCache(): void;
+    /**
+     * Lazy-migration entry point.
+     *
+     * Returns the Person paired to `username`. If none exists and a matching
+     * User does, a Person is created from the User's email/displayName and
+     * persisted. Subsequent calls return the persisted record.
+     */
+    getByUserIdentifier(username: string): Promise<Person | null>;
+    private requireProvider;
+    private getMetrics;
+    private normalizeProviderName;
+}
+export default PersonManager;

package/lib/src/managers/PluginManager.d.ts

@@ -0,0 +1,179 @@
+import BaseManager from './BaseManager.js';
+import * as pluginFormatters from '../utils/pluginFormatters.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+/**
+ * Plugin function type - old-style callable function plugin
+ */
+export type PluginFunction = (pageName: string, params: PluginParams, linkGraph: Record<string, unknown>) => Promise<string> | string;
+/**
+ * Plugin object interface - new-style plugin with execute method
+ */
+export interface PluginObject {
+    name?: string;
+    description?: string;
+    author?: string;
+    version?: string;
+    initialize?: (engine: WikiEngine) => Promise<void> | void;
+    fetch?: (engine: WikiEngine) => Promise<void> | void;
+    execute: (context: PluginContext, params: PluginParams) => Promise<string> | string;
+    /**
+     * Its output changes with nothing written (a clock): a page that runs it is
+     * not kept in the page cache (#1751). Data a plugin reads from a manager is
+     * declared with `context.dependsOn(topic)` instead, which keeps the page
+     * cached until that data changes.
+     */
+    volatile?: boolean;
+}
+/**
+ * Plugin type - can be either a function or an object with execute method
+ */
+export type Plugin = PluginFunction | PluginObject;
+/**
+ * The plugin formatter helpers PluginManager owns (#1820): the functions and
+ * constants `src/utils/pluginFormatters.ts` exports, as the same objects.
+ * Their types stay importable from that module with `import type`.
+ */
+export type PluginFormatters = Readonly<typeof pluginFormatters>;
+export declare const formatters: PluginFormatters;
+/**
+ * Plugin context passed to plugins during execution
+ */
+export interface PluginContext {
+    engine: WikiEngine;
+    pageName: string;
+    linkGraph: Record<string, unknown>;
+    /** #1820: PluginManager's formatter helpers, e.g. `context.formatters.escapeHtml(s)`. */
+    formatters: PluginFormatters;
+    /**
+     * #1751: this render reads `topic`'s data (by convention the owning
+     * manager's name, e.g. 'LedgerManager'). Call before reading; the cached
+     * page is re-rendered once the manager bumps that topic.
+     */
+    dependsOn?: (topic: string) => void;
+    /** #1751: this render's output changes on its own; do not cache the page. */
+    markVolatile?: () => void;
+    [key: string]: unknown;
+}
+/**
+ * Plugin parameters (parsed from plugin syntax)
+ */
+export interface PluginParams {
+    [key: string]: string | number | boolean;
+}
+/**
+ * Plugin information returned by getPluginInfo
+ */
+export interface PluginInfo {
+    name: string;
+    description: string;
+    author: string;
+    version: string;
+}
+/**
+ * PluginManager - Handles plugin discovery, registration, and execution
+ *
+ * Similar to JSPWiki's PluginManager, this manager provides a plugin system
+ * for extending wiki functionality. Plugins are discovered from configured
+ * search paths and executed during markup parsing.
+ *
+ * Key features:
+ * - Dynamic plugin discovery from search paths
+ * - Plugin registration and metadata management
+ * - Secure plugin execution with sandboxing
+ * - Configurable plugin search paths
+ *
+ * @class PluginManager
+ * @extends BaseManager
+ *
+ * @property {Map<string, Plugin>} plugins - Registered plugins
+ * @property {string[]} searchPaths - Directories to search for plugins
+ * @property {string[]} allowedRoots - Allowed root paths for security
+ *
+ * @see {@link BaseManager} for base functionality
+ *
+ * @example
+ * const pluginManager = engine.getManager('PluginManager');
+ * const result = await pluginManager.execute('CurrentTimePlugin', params);
+ */
+declare class PluginManager extends BaseManager {
+    private plugins;
+    private allowedRoots;
+    /**
+     * The plugin formatter helpers this manager owns (#1820), frozen. Plugins
+     * receive them as `context.formatters`; other callers read them here.
+     */
+    readonly formatters: PluginFormatters;
+    /**
+     * Creates a new PluginManager instance
+     *
+     * @constructor
+     * @param {any} engine - The wiki engine instance
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the PluginManager and discover plugins
+     *
+     * @async
+     * @param {Record<string, unknown>} [config={}] - Configuration object (unused, reads from ConfigurationManager)
+     * @returns {Promise<void>}
+     */
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /**
+     * Register all plugins from search paths obtained ONLY from
+     * ConfigurationManager at key: ngdpbase.managers.plugin-manager.search-paths
+     */
+    registerPlugins(): Promise<void>;
+    /**
+     * Load a single plugin from a validated, allowed root
+     * @param {string} pluginPath - Path to the plugin file
+     */
+    loadPlugin(pluginPath: string): Promise<void>;
+    /**
+     * Find plugin by name (case-insensitive)
+     * Supports JSPWiki-style plugin naming where you can use either:
+     * - "Search" or "SearchPlugin"
+     * - "Index" or "IndexPlugin"
+     *
+     * @param {string} pluginName - Name of the plugin to find
+     * @returns {Plugin|null} Plugin object or null if not found
+     */
+    findPlugin(pluginName: string): Plugin | null;
+    /**
+     * Execute a plugin
+     * @param {string} pluginName - Name of the plugin
+     * @param {string} pageName - Current page name
+     * @param {PluginParams} params - Plugin parameters (parsed object)
+     * @param {Record<string, unknown>} context - Additional context
+     * @returns {Promise<string>} Plugin output
+     */
+    execute(pluginName: string, pageName: string, params: PluginParams, context?: Record<string, unknown>): Promise<string>;
+    /**
+     * Get list of all registered plugins
+     * @returns {string[]} Array of plugin names
+     */
+    getPluginNames(): string[];
+    /**
+     * Get plugin info
+     * @param {string} pluginName - Name of the plugin
+     * @returns {PluginInfo | null} Plugin information
+     */
+    getPluginInfo(pluginName: string): PluginInfo | null;
+    /**
+     * Check if plugin exists
+     * @param {string} pluginName - Name of the plugin
+     * @returns {boolean} True if plugin exists
+     */
+    hasPlugin(pluginName: string): boolean;
+    /**
+     * Programmatically register a plugin object (for use by add-ons).
+     *
+     * Skips the file-path security check used by loadPlugin() — the caller is
+     * responsible for providing a trusted Plugin instance.  Calls
+     * plugin.initialize(engine) if present, consistent with loadPlugin().
+     *
+     * @param {string} name - Plugin name (used for [{name ...}] invocation)
+     * @param {Plugin} plugin - Plugin function or PluginObject
+     */
+    registerPlugin(name: string, plugin: Plugin): Promise<void>;
+}
+export default PluginManager;

package/lib/src/managers/PluginManager.js

@@ -0,0 +1,393 @@
+import CacheDependencies from '../cache/CacheDependencies.js';
+import BaseManager from './BaseManager.js';
+import fs from 'fs-extra';
+import path from 'path';
+import logger from '../utils/logger.js';
+import * as pluginFormatters from '../utils/pluginFormatters.js';
+import { enabledEntries } from '../utils/configFiles.js';
+/**
+ * Type guard to check if plugin is an object with execute method
+ */
+function isPluginObject(obj) {
+    return typeof obj === 'object' && obj !== null && typeof obj.execute === 'function';
+}
+/**
+ * Type guard to check if an unknown value is a valid Plugin
+ */
+function isPlugin(obj) {
+    return typeof obj === 'function' || isPluginObject(obj);
+}
+/**
+ * The render's dependency collector (#1751): on the parse context the plugin
+ * handlers pass as `wikiContext`, or on the context itself.
+ */
+/**
+ * The engine a plugin sees while its render is being cached (#1751): each
+ * `getManager(name)` also records `name` as data this render read, so the page
+ * re-renders when that manager bumps its topic. One path for every plugin,
+ * core or add-on — none declares what it reads.
+ */
+function trackedEngine(engine, deps) {
+    return new Proxy(engine, {
+        get(target, prop) {
+            if (prop === 'getManager') {
+                return (name) => {
+                    deps.dependsOn(name);
+                    return target.getManager(name);
+                };
+            }
+            const value = Reflect.get(target, prop, target);
+            return typeof value === 'function' ? value.bind(target) : value;
+        }
+    });
+}
+function cacheDependenciesOf(context) {
+    const own = context.cacheDependencies;
+    if (own instanceof CacheDependencies)
+        return own;
+    const parse = context.wikiContext?.cacheDependencies;
+    return parse instanceof CacheDependencies ? parse : undefined;
+}
+/**
+ * Type guard to check if a module export has a default export
+ */
+function hasDefaultExport(obj) {
+    return typeof obj === 'object' && obj !== null && 'default' in obj;
+}
+export const formatters = Object.freeze({ ...pluginFormatters });
+/**
+ * PluginManager - Handles plugin discovery, registration, and execution
+ *
+ * Similar to JSPWiki's PluginManager, this manager provides a plugin system
+ * for extending wiki functionality. Plugins are discovered from configured
+ * search paths and executed during markup parsing.
+ *
+ * Key features:
+ * - Dynamic plugin discovery from search paths
+ * - Plugin registration and metadata management
+ * - Secure plugin execution with sandboxing
+ * - Configurable plugin search paths
+ *
+ * @class PluginManager
+ * @extends BaseManager
+ *
+ * @property {Map<string, Plugin>} plugins - Registered plugins
+ * @property {string[]} searchPaths - Directories to search for plugins
+ * @property {string[]} allowedRoots - Allowed root paths for security
+ *
+ * @see {@link BaseManager} for base functionality
+ *
+ * @example
+ * const pluginManager = engine.getManager('PluginManager');
+ * const result = await pluginManager.execute('CurrentTimePlugin', params);
+ */
+class PluginManager extends BaseManager {
+    plugins;
+    allowedRoots;
+    /**
+     * The plugin formatter helpers this manager owns (#1820), frozen. Plugins
+     * receive them as `context.formatters`; other callers read them here.
+     */
+    formatters = formatters;
+    /**
+     * Creates a new PluginManager instance
+     *
+     * @constructor
+     * @param {any} engine - The wiki engine instance
+     */
+    constructor(engine) {
+        super(engine);
+        this.plugins = new Map();
+        this.allowedRoots = [];
+    }
+    /**
+     * Initialize the PluginManager and discover plugins
+     *
+     * @async
+     * @param {Record<string, unknown>} [config={}] - Configuration object (unused, reads from ConfigurationManager)
+     * @returns {Promise<void>}
+     */
+    async initialize(config = {}) {
+        await super.initialize(config);
+        // Do NOT read search paths from config here; only ConfigurationManager controls them
+        await this.registerPlugins();
+        this.engine.logger?.info?.('PluginManager initialized');
+    }
+    /**
+     * Register all plugins from search paths obtained ONLY from
+     * ConfigurationManager at key: ngdpbase.managers.plugin-manager.search-paths
+     */
+    async registerPlugins() {
+        const cfgMgr = this.engine.getManager('ConfigurationManager');
+        if (!cfgMgr || typeof cfgMgr.getProperty !== 'function') {
+            this.engine.logger?.warn?.('PluginManager: ConfigurationManager not available; no plugins will be loaded.');
+            return;
+        }
+        // MUST come only from config; no fallbacks
+        const raw = cfgMgr.getProperty('ngdpbase.managers.plugin-manager.search-paths');
+        this.engine.logger?.debug?.(`PluginManager: raw searchPaths type=${typeof raw} value=${JSON.stringify(raw)}`);
+        // Accept a set map, an array, or a comma-separated string
+        let configured = enabledEntries(raw);
+        if (typeof raw === 'string')
+            configured = raw
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean);
+        if (!Array.isArray(configured) || configured.length === 0) {
+            this.engine.logger?.info?.('PluginManager: No plugin search paths configured; skipping plugin load.');
+            return;
+        }
+        // Resolve and validate configured roots
+        const roots = [];
+        for (const p of configured) {
+            try {
+                const abs = path.resolve(process.cwd(), String(p));
+                if (!(await fs.pathExists(abs))) {
+                    this.engine.logger?.debug?.(`PluginManager: configured path does not exist: ${abs}`);
+                    continue;
+                }
+                const st = await fs.lstat(abs);
+                if (!st.isDirectory()) {
+                    this.engine.logger?.warn?.(`PluginManager: configured path is not a directory: ${abs}`);
+                    continue;
+                }
+                // Use realpath to collapse symlinks for later prefix checks
+                const real = await fs.realpath(abs);
+                roots.push(real);
+            }
+            catch (e) {
+                this.engine.logger?.warn?.(`PluginManager: failed to validate configured path "${p}": ${e.message}`);
+            }
+        }
+        this.allowedRoots = roots;
+        if (this.allowedRoots.length === 0) {
+            this.engine.logger?.info?.('PluginManager: No valid plugin roots after validation; skipping plugin load.');
+            return;
+        }
+        // Enumerate .js and .ts files in allowed roots only
+        for (const root of this.allowedRoots) {
+            try {
+                const entries = await fs.readdir(root, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (!entry.isFile())
+                        continue;
+                    // Skip test files and non-plugin files
+                    const isJsPlugin = entry.name.endsWith('.js') && !entry.name.endsWith('.test.js');
+                    const isTsPlugin = entry.name.endsWith('.ts') && !entry.name.endsWith('.test.ts') && !entry.name.endsWith('.d.ts');
+                    if (!isJsPlugin && !isTsPlugin)
+                        continue;
+                    const candidate = path.join(root, entry.name);
+                    await this.loadPlugin(candidate); // loadPlugin re-validates path is under an allowed root
+                }
+            }
+            catch (err) {
+                this.engine.logger?.warn?.(`PluginManager: Failed to load plugins from ${root}: ${err.message}`);
+            }
+        }
+    }
+    /**
+     * Load a single plugin from a validated, allowed root
+     * @param {string} pluginPath - Path to the plugin file
+     */
+    async loadPlugin(pluginPath) {
+        try {
+            // Resolve and validate canonical path
+            const realFile = await fs.realpath(path.resolve(pluginPath));
+            const isAllowed = this.allowedRoots.some((root) => realFile === root || realFile.startsWith(root + path.sep));
+            if (!isAllowed) {
+                this.engine.logger?.warn?.(`PluginManager: blocked plugin outside allowed roots: ${realFile}`);
+                return;
+            }
+            const mod = await import(realFile);
+            // Extract the plugin from the module (handle both default and direct exports)
+            const rawPlugin = hasDefaultExport(mod) ? mod.default : mod;
+            // Validate the plugin is executable
+            if (!isPlugin(rawPlugin)) {
+                const fileName = path.parse(realFile).name;
+                this.engine.logger?.warn?.(`PluginManager: "${fileName}" is not an executable plugin; skipping.`);
+                return;
+            }
+            // Now we know rawPlugin is a valid Plugin
+            const plugin = rawPlugin;
+            // Get plugin name from metadata or filename
+            const pluginName = (isPluginObject(plugin) && plugin.name) || path.parse(realFile).name;
+            // Initialize the plugin if it has an initialize method (only object plugins have this)
+            if (isPluginObject(plugin) && typeof plugin.initialize === 'function') {
+                await plugin.initialize(this.engine);
+            }
+            this.plugins.set(pluginName, plugin);
+            this.engine.logger?.info?.(`PluginManager: Loaded plugin "${pluginName}" from ${realFile}`);
+        }
+        catch (err) {
+            this.engine.logger?.error?.(`PluginManager: Failed to load plugin ${pluginPath}: ${err.message}`);
+        }
+    }
+    /**
+     * Find plugin by name (case-insensitive)
+     * Supports JSPWiki-style plugin naming where you can use either:
+     * - "Search" or "SearchPlugin"
+     * - "Index" or "IndexPlugin"
+     *
+     * @param {string} pluginName - Name of the plugin to find
+     * @returns {Plugin|null} Plugin object or null if not found
+     */
+    findPlugin(pluginName) {
+        // Try exact match first (for performance)
+        if (this.plugins.has(pluginName)) {
+            return this.plugins.get(pluginName) ?? null;
+        }
+        // Try case-insensitive match
+        const lowerName = pluginName.toLowerCase();
+        for (const [key, plugin] of this.plugins) {
+            if (key.toLowerCase() === lowerName) {
+                return plugin;
+            }
+        }
+        // JSPWiki compatibility: Try with "Plugin" suffix if not already present
+        if (!pluginName.toLowerCase().endsWith('plugin')) {
+            const withSuffix = pluginName + 'Plugin';
+            if (this.plugins.has(withSuffix)) {
+                return this.plugins.get(withSuffix) ?? null;
+            }
+            // Try case-insensitive with suffix
+            const lowerWithSuffix = withSuffix.toLowerCase();
+            for (const [key, plugin] of this.plugins) {
+                if (key.toLowerCase() === lowerWithSuffix) {
+                    return plugin;
+                }
+            }
+        }
+        // Try without "Plugin" suffix if it's present
+        if (pluginName.toLowerCase().endsWith('plugin')) {
+            const withoutSuffix = pluginName.slice(0, -6); // Remove "Plugin"
+            if (this.plugins.has(withoutSuffix)) {
+                return this.plugins.get(withoutSuffix) ?? null;
+            }
+            // Try case-insensitive without suffix
+            const lowerWithoutSuffix = withoutSuffix.toLowerCase();
+            for (const [key, plugin] of this.plugins) {
+                if (key.toLowerCase() === lowerWithoutSuffix) {
+                    return plugin;
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Execute a plugin
+     * @param {string} pluginName - Name of the plugin
+     * @param {string} pageName - Current page name
+     * @param {PluginParams} params - Plugin parameters (parsed object)
+     * @param {Record<string, unknown>} context - Additional context
+     * @returns {Promise<string>} Plugin output
+     */
+    async execute(pluginName, pageName, params, context = {}) {
+        const plugin = this.findPlugin(pluginName);
+        if (!plugin) {
+            return `Plugin '${pluginName}' not found`;
+        }
+        try {
+            // Pass the full context through to plugins
+            // Plugins expect the full ParseContext/WikiContext with all properties
+            // #1751: what this render reads, for the page cache's read-through.
+            const deps = cacheDependenciesOf(context);
+            if (isPluginObject(plugin) && plugin.volatile)
+                deps?.markVolatile();
+            const pluginContext = {
+                ...context, // Spread all context properties
+                // Always the manager's engine; while the page cache is collecting, every
+                // manager the plugin fetches is recorded as data this render read (#1751).
+                engine: deps ? trackedEngine(this.engine, deps) : this.engine,
+                pageName: pageName,
+                linkGraph: context.linkGraph || {},
+                formatters: this.formatters,
+                dependsOn: (topic) => deps?.dependsOn(topic),
+                markVolatile: () => deps?.markVolatile()
+            };
+            // Check if it's a new-style plugin with execute method
+            if (isPluginObject(plugin)) {
+                if (typeof plugin.fetch === 'function') {
+                    // #1751: fetch reads data for this render, so it sees the same tracked engine.
+                    await plugin.fetch(pluginContext.engine);
+                }
+                const result = await plugin.execute(pluginContext, params);
+                return result;
+            }
+            // Check if it's an old-style function plugin
+            if (typeof plugin === 'function') {
+                const result = await plugin(pageName, params, context.linkGraph || {});
+                return result;
+            }
+            // This should never happen due to type narrowing, but satisfies TypeScript
+            return `Plugin '${pluginName}' is not executable`;
+        }
+        catch (err) {
+            logger.error(`Plugin '${pluginName}' execution failed:`, err);
+            return `Plugin '${pluginName}' error: ${err.message}`;
+        }
+    }
+    /**
+     * Get list of all registered plugins
+     * @returns {string[]} Array of plugin names
+     */
+    getPluginNames() {
+        return Array.from(this.plugins.keys());
+    }
+    /**
+     * Get plugin info
+     * @param {string} pluginName - Name of the plugin
+     * @returns {PluginInfo | null} Plugin information
+     */
+    getPluginInfo(pluginName) {
+        const plugin = this.findPlugin(pluginName);
+        if (!plugin) {
+            return null;
+        }
+        // Only PluginObject has metadata properties
+        if (isPluginObject(plugin)) {
+            return {
+                name: pluginName,
+                description: plugin.description || 'No description available',
+                author: plugin.author || 'Unknown',
+                version: plugin.version || '1.0.0'
+            };
+        }
+        // Function plugins have no metadata
+        return {
+            name: pluginName,
+            description: 'No description available',
+            author: 'Unknown',
+            version: '1.0.0'
+        };
+    }
+    /**
+     * Check if plugin exists
+     * @param {string} pluginName - Name of the plugin
+     * @returns {boolean} True if plugin exists
+     */
+    hasPlugin(pluginName) {
+        return this.findPlugin(pluginName) !== null;
+    }
+    /**
+     * Programmatically register a plugin object (for use by add-ons).
+     *
+     * Skips the file-path security check used by loadPlugin() — the caller is
+     * responsible for providing a trusted Plugin instance.  Calls
+     * plugin.initialize(engine) if present, consistent with loadPlugin().
+     *
+     * @param {string} name - Plugin name (used for [{name ...}] invocation)
+     * @param {Plugin} plugin - Plugin function or PluginObject
+     */
+    async registerPlugin(name, plugin) {
+        if (!isPlugin(plugin)) {
+            logger.warn(`[PluginManager] registerPlugin('${name}'): argument is not a valid Plugin — skipped`);
+            return;
+        }
+        if (isPluginObject(plugin) && typeof plugin.initialize === 'function') {
+            await plugin.initialize(this.engine);
+        }
+        this.plugins.set(name, plugin);
+        logger.info(`[PluginManager] Registered plugin: ${name}`);
+    }
+}
+export default PluginManager;