@pennyfarthing/core 10.0.5 → 10.2.0

package/packages/core/dist/plugins/plugin-discovery.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Plugin Discovery for Commands and Skills from Installed Packages
+ *
+ * Story 93-3: Discover and register commands, skills, and API routers
+ * from installed @pennyfarthing/* packages via their package.json
+ * "pennyfarthing" field.
+ */
+/**
+ * Manifest shape declared in a plugin's package.json under the "pennyfarthing" field.
+ */
+export interface PluginManifest {
+    /** Relative path to commands directory (e.g., "commands/") */
+    commands?: string;
+    /** Relative path to skills directory (e.g., "skills/") */
+    skills?: string;
+    /** API router entry point for Cyclist */
+    api?: {
+        /** Express mount path (e.g., "/api/benchmark") */
+        path: string;
+        /** Module path relative to package root (e.g., "./dist/api/benchmark.js") */
+        module: string;
+        /** Named export that creates the router (e.g., "createBenchmarkRouter") */
+        export: string;
+    };
+}
+/**
+ * A discovered plugin package with its parsed manifest.
+ */
+export interface DiscoveredPlugin {
+    /** Full package name (e.g., "@pennyfarthing/benchmark") */
+    name: string;
+    /** Absolute path to the package directory */
+    path: string;
+    /** Parsed pennyfarthing manifest from package.json */
+    manifest: PluginManifest;
+}
+/**
+ * A command file discovered from a plugin.
+ */
+export interface PluginCommand {
+    /** Command name (filename without .md extension) */
+    name: string;
+    /** Absolute path to the command .md file */
+    path: string;
+    /** Plugin that provides this command */
+    plugin: string;
+}
+/**
+ * A skill directory discovered from a plugin.
+ */
+export interface PluginSkill {
+    /** Skill name (directory name) */
+    name: string;
+    /** Absolute path to the skill directory */
+    path: string;
+    /** Plugin that provides this skill */
+    plugin: string;
+}
+/**
+ * An API router entry point discovered from a plugin.
+ */
+export interface PluginRouter {
+    /** Express mount path (e.g., "/api/benchmark") */
+    mountPath: string;
+    /** Absolute path to the module file */
+    modulePath: string;
+    /** Named export that creates the router */
+    exportName: string;
+    /** Plugin that provides this router */
+    plugin: string;
+}
+/**
+ * Parse the "pennyfarthing" field from a package's package.json.
+ *
+ * @param packageDir - Absolute path to the package directory
+ * @returns Parsed manifest, or null if not a plugin
+ */
+export declare function parsePluginManifest(packageDir: string): PluginManifest | null;
+/**
+ * Discover installed @pennyfarthing/* plugin packages.
+ *
+ * Scans node_modules/@pennyfarthing/ for packages that have a "pennyfarthing"
+ * field in their package.json. Skips core and shared packages.
+ *
+ * @param projectRoot - Absolute path to project root
+ * @returns Array of discovered plugins
+ */
+export declare function discoverPlugins(projectRoot: string): DiscoveredPlugin[];
+/**
+ * Get all command file paths from discovered plugins.
+ *
+ * Scans each plugin's declared commands directory for .md files.
+ *
+ * @param plugins - Array of discovered plugins
+ * @returns Array of command metadata with paths
+ */
+export declare function getPluginCommands(plugins: DiscoveredPlugin[]): PluginCommand[];
+/**
+ * Get all skill directory paths from discovered plugins.
+ *
+ * Scans each plugin's declared skills directory for subdirectories.
+ *
+ * @param plugins - Array of discovered plugins
+ * @returns Array of skill metadata with paths
+ */
+export declare function getPluginSkills(plugins: DiscoveredPlugin[]): PluginSkill[];
+/**
+ * Get all API router entry points from discovered plugins.
+ *
+ * Reads API router definitions from each plugin's manifest.
+ *
+ * @param plugins - Array of discovered plugins
+ * @returns Array of router metadata
+ */
+export declare function getPluginRouters(plugins: DiscoveredPlugin[]): PluginRouter[];
+//# sourceMappingURL=plugin-discovery.d.ts.map

package/packages/core/dist/plugins/plugin-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-discovery.d.ts","sourceRoot":"","sources":["../../src/plugins/plugin-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,GAAG,CAAC,EAAE;QACJ,kDAAkD;QAClD,IAAI,EAAE,MAAM,CAAC;QACb,6EAA6E;QAC7E,MAAM,EAAE,MAAM,CAAC;QACf,2EAA2E;QAC3E,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAmB7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAkCvE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,aAAa,EAAE,CA0B9E;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,WAAW,EAAE,CAkC1E;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,YAAY,EAAE,CAkB5E"}

package/packages/core/dist/plugins/plugin-discovery.js

@@ -0,0 +1,165 @@
+/**
+ * Plugin Discovery for Commands and Skills from Installed Packages
+ *
+ * Story 93-3: Discover and register commands, skills, and API routers
+ * from installed @pennyfarthing/* packages via their package.json
+ * "pennyfarthing" field.
+ */
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+/** Packages that are part of the framework, not plugins */
+const EXCLUDED_PACKAGES = ['core', 'shared'];
+/**
+ * Parse the "pennyfarthing" field from a package's package.json.
+ *
+ * @param packageDir - Absolute path to the package directory
+ * @returns Parsed manifest, or null if not a plugin
+ */
+export function parsePluginManifest(packageDir) {
+    const pkgJsonPath = join(packageDir, 'package.json');
+    if (!existsSync(pkgJsonPath)) {
+        return null;
+    }
+    try {
+        const raw = readFileSync(pkgJsonPath, 'utf-8');
+        const pkg = JSON.parse(raw);
+        if (!pkg.pennyfarthing || typeof pkg.pennyfarthing !== 'object') {
+            return null;
+        }
+        return pkg.pennyfarthing;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Discover installed @pennyfarthing/* plugin packages.
+ *
+ * Scans node_modules/@pennyfarthing/ for packages that have a "pennyfarthing"
+ * field in their package.json. Skips core and shared packages.
+ *
+ * @param projectRoot - Absolute path to project root
+ * @returns Array of discovered plugins
+ */
+export function discoverPlugins(projectRoot) {
+    const scopeDir = join(projectRoot, 'node_modules/@pennyfarthing');
+    if (!existsSync(scopeDir)) {
+        return [];
+    }
+    let entries;
+    try {
+        entries = readdirSync(scopeDir);
+    }
+    catch {
+        return [];
+    }
+    const plugins = [];
+    for (const entry of entries) {
+        if (EXCLUDED_PACKAGES.includes(entry)) {
+            continue;
+        }
+        const pkgDir = resolve(join(scopeDir, entry));
+        const manifest = parsePluginManifest(pkgDir);
+        if (manifest) {
+            plugins.push({
+                name: `@pennyfarthing/${entry}`,
+                path: pkgDir,
+                manifest,
+            });
+        }
+    }
+    return plugins;
+}
+/**
+ * Get all command file paths from discovered plugins.
+ *
+ * Scans each plugin's declared commands directory for .md files.
+ *
+ * @param plugins - Array of discovered plugins
+ * @returns Array of command metadata with paths
+ */
+export function getPluginCommands(plugins) {
+    const commands = [];
+    for (const plugin of plugins) {
+        if (!plugin.manifest.commands) {
+            continue;
+        }
+        const commandsDir = join(plugin.path, plugin.manifest.commands);
+        if (!existsSync(commandsDir)) {
+            continue;
+        }
+        const files = readdirSync(commandsDir).filter(f => f.endsWith('.md'));
+        for (const file of files) {
+            commands.push({
+                name: file.replace(/\.md$/, ''),
+                path: join(commandsDir, file),
+                plugin: plugin.name,
+            });
+        }
+    }
+    return commands;
+}
+/**
+ * Get all skill directory paths from discovered plugins.
+ *
+ * Scans each plugin's declared skills directory for subdirectories.
+ *
+ * @param plugins - Array of discovered plugins
+ * @returns Array of skill metadata with paths
+ */
+export function getPluginSkills(plugins) {
+    const skills = [];
+    for (const plugin of plugins) {
+        if (!plugin.manifest.skills) {
+            continue;
+        }
+        const skillsDir = join(plugin.path, plugin.manifest.skills);
+        if (!existsSync(skillsDir)) {
+            continue;
+        }
+        const entries = readdirSync(skillsDir).filter(f => {
+            if (f.startsWith('.'))
+                return false;
+            const fullPath = join(skillsDir, f);
+            try {
+                return statSync(fullPath).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+        for (const entry of entries) {
+            skills.push({
+                name: entry,
+                path: join(skillsDir, entry),
+                plugin: plugin.name,
+            });
+        }
+    }
+    return skills;
+}
+/**
+ * Get all API router entry points from discovered plugins.
+ *
+ * Reads API router definitions from each plugin's manifest.
+ *
+ * @param plugins - Array of discovered plugins
+ * @returns Array of router metadata
+ */
+export function getPluginRouters(plugins) {
+    const routers = [];
+    for (const plugin of plugins) {
+        if (!plugin.manifest.api) {
+            continue;
+        }
+        const api = plugin.manifest.api;
+        routers.push({
+            mountPath: api.path,
+            modulePath: join(plugin.path, api.module),
+            exportName: api.export,
+            plugin: plugin.name,
+        });
+    }
+    return routers;
+}
+//# sourceMappingURL=plugin-discovery.js.map

package/packages/core/dist/plugins/plugin-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-discovery.js","sourceRoot":"","sources":["../../src/plugins/plugin-discovery.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/plugins/plugin-discovery.test.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Tests for Story 93-3: Plugin Discovery for Commands and Skills
+ *
+ * These tests define the contract for discovering and registering
+ * commands, skills, and API routers from installed @pennyfarthing/* packages.
+ *
+ * The plugin system reads a "pennyfarthing" field from package.json of
+ * installed @pennyfarthing/* packages (excluding core and shared).
+ *
+ * Test categories:
+ * 1. discoverPlugins() - Scan node_modules for plugin packages
+ * 2. parsePluginManifest() - Parse "pennyfarthing" field from package.json
+ * 3. getPluginCommands() - Aggregate command paths from all plugins
+ * 4. getPluginSkills() - Aggregate skill paths from all plugins
+ * 5. getPluginRouters() - Aggregate API router entry points
+ * 6. Graceful degradation - Missing packages, malformed manifests
+ * 7. Integration - Init hooks for commands/skills from plugins
+ *
+ * Run with: npm test
+ */
+export {};
+//# sourceMappingURL=plugin-discovery.test.d.ts.map

package/packages/core/dist/plugins/plugin-discovery.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-discovery.test.d.ts","sourceRoot":"","sources":["../../src/plugins/plugin-discovery.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG"}