forge-workflow 0.0.3 → 0.0.5

package/lib/plugin-manager.js

@@ -1,166 +1,166 @@
-/**
- * Plugin Manager
- *
- * Handles loading, validating, and managing agent plugin JSON files.
- * Provides discoverable plugin architecture for AI coding agents.
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-class PluginManager {
-  constructor() {
-    this.plugins = new Map();
-    this.loadPlugins();
-  }
-
-  /**
-   * Load all plugin files from lib/agents/ directory
-   */
-  loadPlugins() {
-    const pluginDir = path.join(__dirname, 'agents');
-
-    // Create directory if it doesn't exist (for first-time setup)
-    if (!fs.existsSync(pluginDir)) {
-      fs.mkdirSync(pluginDir, { recursive: true });
-      return;
-    }
-
-    const files = fs.readdirSync(pluginDir)
-      .filter(f => f.endsWith('.plugin.json'));
-
-    files.forEach(file => {
-      try {
-        const content = fs.readFileSync(path.join(pluginDir, file), 'utf-8');
-        const plugin = JSON.parse(content);
-        this.validatePlugin(plugin);
-
-        // Check for duplicate IDs
-        if (this.plugins.has(plugin.id)) {
-          throw new Error(`Plugin with ID "${plugin.id}" already exists`);
-        }
-
-        this.plugins.set(plugin.id, plugin);
-      } catch (error) {
-        // Re-throw with file context
-        throw new Error(`Failed to load plugin ${file}: ${error.message}`);
-      }
-    });
-  }
-
-  /**
-   * Validate plugin schema
-   * @param {Object} plugin - Plugin object to validate
-   * @throws {Error} If validation fails
-   */
-  validatePlugin(plugin) {
-    const required = ['id', 'name', 'version', 'directories'];
-
-    // Check required fields exist
-    required.forEach(field => {
-      if (!plugin[field]) {
-        throw new Error(`Plugin validation failed: missing required field "${field}"`);
-      }
-    });
-
-    // Validate field types
-    if (typeof plugin.id !== 'string') {
-      throw new TypeError('Plugin validation failed: "id" must be a string');
-    }
-    if (typeof plugin.name !== 'string') {
-      throw new TypeError('Plugin validation failed: "name" must be a string');
-    }
-    if (typeof plugin.version !== 'string') {
-      throw new TypeError('Plugin validation failed: "version" must be a string');
-    }
-    if (typeof plugin.directories !== 'object' || Array.isArray(plugin.directories)) {
-      throw new TypeError('Plugin validation failed: "directories" must be an object');
-    }
-
-    // Validate optional fields if present
-    if (plugin.description && typeof plugin.description !== 'string') {
-      throw new TypeError('Plugin validation failed: "description" must be a string');
-    }
-    if (plugin.homepage && typeof plugin.homepage !== 'string') {
-      throw new TypeError('Plugin validation failed: "homepage" must be a string');
-    }
-  }
-
-  /**
-   * Get plugin by ID
-   * @param {string} id - Plugin ID
-   * @returns {Object|undefined} Plugin object or undefined if not found
-   */
-  getPlugin(id) {
-    return this.plugins.get(id);
-  }
-
-  /**
-   * Get all plugins as a Map
-   * @returns {Map} Map of plugin ID to plugin object
-   */
-  getAllPlugins() {
-    return this.plugins;
-  }
-
-  /**
-   * Get list of all agent IDs
-   * @returns {Array<string>} Array of plugin IDs
-   */
-  listAgents() {
-    return Array.from(this.plugins.keys());
-  }
-}
-
-/**
- * Standalone plugin schema validator (for testing and external use)
- * @param {Object} plugin - Plugin object to validate
- * @returns {{valid: boolean, errors: Array<string>}}
- */
-function validatePluginSchema(plugin) {
-  const errors = [];
-
-  // Check if plugin is an object
-  if (!plugin || typeof plugin !== 'object' || Array.isArray(plugin)) {
-    return { valid: false, errors: ['Plugin must be a non-null object'] };
-  }
-
-  // Check required fields
-  const required = ['id', 'name', 'version', 'directories'];
-  required.forEach(field => {
-    if (!plugin[field]) {
-      errors.push(`Missing required field "${field}"`);
-    }
-  });
-
-  // Validate field types
-  if (plugin.id !== undefined && typeof plugin.id !== 'string') {
-    errors.push('"id" must be a string');
-  }
-  if (plugin.name !== undefined && typeof plugin.name !== 'string') {
-    errors.push('"name" must be a string');
-  }
-  if (plugin.version !== undefined && typeof plugin.version !== 'string') {
-    errors.push('"version" must be a string');
-  }
-  if (plugin.directories !== undefined) {
-    if (typeof plugin.directories !== 'object' || Array.isArray(plugin.directories)) {
-      errors.push('"directories" must be an object');
-    } else if (Object.keys(plugin.directories).length === 0) {
-      errors.push('"directories" must not be empty');
-    }
-  }
-
-  // Validate optional fields if present
-  if (plugin.description !== undefined && typeof plugin.description !== 'string') {
-    errors.push('"description" must be a string');
-  }
-  if (plugin.homepage !== undefined && typeof plugin.homepage !== 'string') {
-    errors.push('"homepage" must be a string');
-  }
-
-  return { valid: errors.length === 0, errors };
-}
-
-module.exports = PluginManager;
-module.exports.validatePluginSchema = validatePluginSchema;
+/**
+ * Plugin Manager
+ *
+ * Handles loading, validating, and managing agent plugin JSON files.
+ * Provides discoverable plugin architecture for AI coding agents.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+class PluginManager {
+  constructor() {
+    this.plugins = new Map();
+    this.loadPlugins();
+  }
+
+  /**
+   * Load all plugin files from lib/agents/ directory
+   */
+  loadPlugins() {
+    const pluginDir = path.join(__dirname, 'agents');
+
+    // Create directory if it doesn't exist (for first-time setup)
+    if (!fs.existsSync(pluginDir)) {
+      fs.mkdirSync(pluginDir, { recursive: true });
+      return;
+    }
+
+    const files = fs.readdirSync(pluginDir)
+      .filter(f => f.endsWith('.plugin.json'));
+
+    files.forEach(file => {
+      try {
+        const content = fs.readFileSync(path.join(pluginDir, file), 'utf-8');
+        const plugin = JSON.parse(content);
+        this.validatePlugin(plugin);
+
+        // Check for duplicate IDs
+        if (this.plugins.has(plugin.id)) {
+          throw new Error(`Plugin with ID "${plugin.id}" already exists`);
+        }
+
+        this.plugins.set(plugin.id, plugin);
+      } catch (error) {
+        // Re-throw with file context
+        throw new Error(`Failed to load plugin ${file}: ${error.message}`);
+      }
+    });
+  }
+
+  /**
+   * Validate plugin schema
+   * @param {Object} plugin - Plugin object to validate
+   * @throws {Error} If validation fails
+   */
+  validatePlugin(plugin) {
+    const required = ['id', 'name', 'version', 'directories'];
+
+    // Check required fields exist
+    required.forEach(field => {
+      if (!plugin[field]) {
+        throw new Error(`Plugin validation failed: missing required field "${field}"`);
+      }
+    });
+
+    // Validate field types
+    if (typeof plugin.id !== 'string') {
+      throw new TypeError('Plugin validation failed: "id" must be a string');
+    }
+    if (typeof plugin.name !== 'string') {
+      throw new TypeError('Plugin validation failed: "name" must be a string');
+    }
+    if (typeof plugin.version !== 'string') {
+      throw new TypeError('Plugin validation failed: "version" must be a string');
+    }
+    if (typeof plugin.directories !== 'object' || Array.isArray(plugin.directories)) {
+      throw new TypeError('Plugin validation failed: "directories" must be an object');
+    }
+
+    // Validate optional fields if present
+    if (plugin.description && typeof plugin.description !== 'string') {
+      throw new TypeError('Plugin validation failed: "description" must be a string');
+    }
+    if (plugin.homepage && typeof plugin.homepage !== 'string') {
+      throw new TypeError('Plugin validation failed: "homepage" must be a string');
+    }
+  }
+
+  /**
+   * Get plugin by ID
+   * @param {string} id - Plugin ID
+   * @returns {Object|undefined} Plugin object or undefined if not found
+   */
+  getPlugin(id) {
+    return this.plugins.get(id);
+  }
+
+  /**
+   * Get all plugins as a Map
+   * @returns {Map} Map of plugin ID to plugin object
+   */
+  getAllPlugins() {
+    return this.plugins;
+  }
+
+  /**
+   * Get list of all agent IDs
+   * @returns {Array<string>} Array of plugin IDs
+   */
+  listAgents() {
+    return Array.from(this.plugins.keys());
+  }
+}
+
+/**
+ * Standalone plugin schema validator (for testing and external use)
+ * @param {Object} plugin - Plugin object to validate
+ * @returns {{valid: boolean, errors: Array<string>}}
+ */
+function validatePluginSchema(plugin) {
+  const errors = [];
+
+  // Check if plugin is an object
+  if (!plugin || typeof plugin !== 'object' || Array.isArray(plugin)) {
+    return { valid: false, errors: ['Plugin must be a non-null object'] };
+  }
+
+  // Check required fields
+  const required = ['id', 'name', 'version', 'directories'];
+  required.forEach(field => {
+    if (!plugin[field]) {
+      errors.push(`Missing required field "${field}"`);
+    }
+  });
+
+  // Validate field types
+  if (plugin.id !== undefined && typeof plugin.id !== 'string') {
+    errors.push('"id" must be a string');
+  }
+  if (plugin.name !== undefined && typeof plugin.name !== 'string') {
+    errors.push('"name" must be a string');
+  }
+  if (plugin.version !== undefined && typeof plugin.version !== 'string') {
+    errors.push('"version" must be a string');
+  }
+  if (plugin.directories !== undefined) {
+    if (typeof plugin.directories !== 'object' || Array.isArray(plugin.directories)) {
+      errors.push('"directories" must be an object');
+    } else if (Object.keys(plugin.directories).length === 0) {
+      errors.push('"directories" must not be empty');
+    }
+  }
+
+  // Validate optional fields if present
+  if (plugin.description !== undefined && typeof plugin.description !== 'string') {
+    errors.push('"description" must be a string');
+  }
+  if (plugin.homepage !== undefined && typeof plugin.homepage !== 'string') {
+    errors.push('"homepage" must be a string');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+module.exports = PluginManager;
+module.exports.validatePluginSchema = validatePluginSchema;

package/lib/plugin-recommender.js

@@ -1,141 +1,141 @@
-/**
- * Plugin Recommender
- *
- * Filters and sorts tools from the catalog based on tech stack detection
- * and budget mode. Pure logic — no I/O, no side effects.
- */
-
-const { CATALOG, BUDGET_MODES, STAGES } = require('./plugin-catalog');
-
-const STAGE_ORDER = Object.values(STAGES);
-
-// Dependency-to-detection-field mapping for matchesDetection
-const DEP_FIELD_MAP = {
-  // Frameworks
-  next: 'frameworks:nextjs', react: 'frameworks:react', vue: 'frameworks:vue',
-  '@angular/core': 'frameworks:angular', express: 'frameworks:express',
-  fastify: 'frameworks:fastify', '@nestjs/core': 'frameworks:nestjs',
-  // Databases
-  '@supabase/supabase-js': 'databases:supabase', '@prisma/client': 'databases:prisma',
-  // Payments
-  stripe: 'payments:stripe',
-  // Testing
-  vitest: 'testing:vitest', jest: 'testing:jest', '@playwright/test': 'testing:playwright',
-  // Auth
-  '@clerk/nextjs': 'auth:clerk',
-  // Misc
-  typescript: 'languages:typescript', eslint: 'linting:eslint',
-};
-
-// File-to-detection-field mapping
-const FILE_FIELD_MAP = {
-  'tsconfig.json': 'lsps:typescript',
-  'biome.json': 'linting:biome',
-  '.prettierrc': 'linting:prettier',
-  'eslint.config.js': 'linting:eslint',
-  'vitest.config.ts': 'testing:vitest',
-  'jest.config.js': 'testing:jest',
-  'sonar-project.properties': 'linting:sonar',
-  'package.json': null, // universal, always matches
-};
-
-/**
- * Check if detection conditions match the tech stack.
- * Empty conditions = universal (always matches).
- * Multiple conditions use OR logic.
- */
-function matchesDetection(conditions, techStack) {
-  if (!conditions || conditions.length === 0) return true;
-
-  return conditions.some((condition) => {
-    const [type, value] = condition.split(':');
-    if (type === 'dep') {
-      // Check if the dependency maps to a detected field
-      const mapping = DEP_FIELD_MAP[value];
-      if (mapping) {
-        const [field, name] = mapping.split(':');
-        return techStack[field]?.includes(name);
-      }
-      // Fallback: check all array fields for the value
-      return Object.values(techStack).some(
-        (arr) => Array.isArray(arr) && arr.includes(value)
-      );
-    }
-    if (type === 'file') {
-      const mapping = FILE_FIELD_MAP[value];
-      if (mapping === null) return true; // package.json always matches
-      if (mapping) {
-        const [field, name] = mapping.split(':');
-        return techStack[field]?.includes(name);
-      }
-      return false;
-    }
-    if (type === 'framework') {
-      return techStack.frameworks?.includes(value);
-    }
-    return false;
-  });
-}
-
-/**
- * Recommend tools based on tech stack and budget.
- * @param {Object} techStack - Output from detectTechStack()
- * @param {string} budgetMode - Budget mode key
- * @param {Object} [options] - Additional options
- * @param {string[]} [options.customTiers] - Tiers to include for 'custom' mode
- * @returns {{ recommended: Object[], skipped: Object[] }}
- */
-function recommend(techStack, budgetMode, options = {}) {
-  const mode = BUDGET_MODES[budgetMode];
-  if (!mode) {
-    throw new Error(`Invalid budget mode: '${budgetMode}'. Valid modes: ${Object.keys(BUDGET_MODES).join(', ')}`);
-  }
-
-  const allowedTiers = budgetMode === 'custom'
-    ? (options.customTiers || [])
-    : mode.includes;
-
-  const recommended = [];
-  const skipped = [];
-
-  for (const [id, tool] of Object.entries(CATALOG)) {
-    // Check detection match
-    if (!matchesDetection(tool.detectWhen, techStack)) {
-      continue; // Not relevant to this project
-    }
-
-    // Check tier
-    if (!allowedTiers.includes(tool.tier)) {
-      skipped.push({
-        id,
-        ...tool,
-        reason: `Tier '${tool.tier}' not included in '${budgetMode}' budget`,
-      });
-      continue;
-    }
-
-    // CLI-first: skip unjustified MCPs
-    if (tool.type === 'mcp' && !tool.mcpJustified) {
-      skipped.push({
-        id,
-        ...tool,
-        reason: 'MCP not justified — prefer CLI alternative',
-      });
-      continue;
-    }
-
-    recommended.push({ id, ...tool });
-  }
-
-  // Sort: free first, then by stage order
-  recommended.sort((a, b) => {
-    const aFree = a.tier === 'free' ? 0 : 1;
-    const bFree = b.tier === 'free' ? 0 : 1;
-    if (aFree !== bFree) return aFree - bFree;
-    return STAGE_ORDER.indexOf(a.stage) - STAGE_ORDER.indexOf(b.stage);
-  });
-
-  return { recommended, skipped };
-}
-
-module.exports = { recommend, matchesDetection };
+/**
+ * Plugin Recommender
+ *
+ * Filters and sorts tools from the catalog based on tech stack detection
+ * and budget mode. Pure logic — no I/O, no side effects.
+ */
+
+const { CATALOG, BUDGET_MODES, STAGES } = require('./plugin-catalog');
+
+const STAGE_ORDER = Object.values(STAGES);
+
+// Dependency-to-detection-field mapping for matchesDetection
+const DEP_FIELD_MAP = {
+  // Frameworks
+  next: 'frameworks:nextjs', react: 'frameworks:react', vue: 'frameworks:vue',
+  '@angular/core': 'frameworks:angular', express: 'frameworks:express',
+  fastify: 'frameworks:fastify', '@nestjs/core': 'frameworks:nestjs',
+  // Databases
+  '@supabase/supabase-js': 'databases:supabase', '@prisma/client': 'databases:prisma',
+  // Payments
+  stripe: 'payments:stripe',
+  // Testing
+  vitest: 'testing:vitest', jest: 'testing:jest', '@playwright/test': 'testing:playwright',
+  // Auth
+  '@clerk/nextjs': 'auth:clerk',
+  // Misc
+  typescript: 'languages:typescript', eslint: 'linting:eslint',
+};
+
+// File-to-detection-field mapping
+const FILE_FIELD_MAP = {
+  'tsconfig.json': 'lsps:typescript',
+  'biome.json': 'linting:biome',
+  '.prettierrc': 'linting:prettier',
+  'eslint.config.js': 'linting:eslint',
+  'vitest.config.ts': 'testing:vitest',
+  'jest.config.js': 'testing:jest',
+  'sonar-project.properties': 'linting:sonar',
+  'package.json': null, // universal, always matches
+};
+
+/**
+ * Check if detection conditions match the tech stack.
+ * Empty conditions = universal (always matches).
+ * Multiple conditions use OR logic.
+ */
+function matchesDetection(conditions, techStack) {
+  if (!conditions || conditions.length === 0) return true;
+
+  return conditions.some((condition) => {
+    const [type, value] = condition.split(':');
+    if (type === 'dep') {
+      // Check if the dependency maps to a detected field
+      const mapping = DEP_FIELD_MAP[value];
+      if (mapping) {
+        const [field, name] = mapping.split(':');
+        return techStack[field]?.includes(name);
+      }
+      // Fallback: check all array fields for the value
+      return Object.values(techStack).some(
+        (arr) => Array.isArray(arr) && arr.includes(value)
+      );
+    }
+    if (type === 'file') {
+      const mapping = FILE_FIELD_MAP[value];
+      if (mapping === null) return true; // package.json always matches
+      if (mapping) {
+        const [field, name] = mapping.split(':');
+        return techStack[field]?.includes(name);
+      }
+      return false;
+    }
+    if (type === 'framework') {
+      return techStack.frameworks?.includes(value);
+    }
+    return false;
+  });
+}
+
+/**
+ * Recommend tools based on tech stack and budget.
+ * @param {Object} techStack - Output from detectTechStack()
+ * @param {string} budgetMode - Budget mode key
+ * @param {Object} [options] - Additional options
+ * @param {string[]} [options.customTiers] - Tiers to include for 'custom' mode
+ * @returns {{ recommended: Object[], skipped: Object[] }}
+ */
+function recommend(techStack, budgetMode, options = {}) {
+  const mode = BUDGET_MODES[budgetMode];
+  if (!mode) {
+    throw new Error(`Invalid budget mode: '${budgetMode}'. Valid modes: ${Object.keys(BUDGET_MODES).join(', ')}`);
+  }
+
+  const allowedTiers = budgetMode === 'custom'
+    ? (options.customTiers || [])
+    : mode.includes;
+
+  const recommended = [];
+  const skipped = [];
+
+  for (const [id, tool] of Object.entries(CATALOG)) {
+    // Check detection match
+    if (!matchesDetection(tool.detectWhen, techStack)) {
+      continue; // Not relevant to this project
+    }
+
+    // Check tier
+    if (!allowedTiers.includes(tool.tier)) {
+      skipped.push({
+        id,
+        ...tool,
+        reason: `Tier '${tool.tier}' not included in '${budgetMode}' budget`,
+      });
+      continue;
+    }
+
+    // CLI-first: skip unjustified MCPs
+    if (tool.type === 'mcp' && !tool.mcpJustified) {
+      skipped.push({
+        id,
+        ...tool,
+        reason: 'MCP not justified — prefer CLI alternative',
+      });
+      continue;
+    }
+
+    recommended.push({ id, ...tool });
+  }
+
+  // Sort: free first, then by stage order
+  recommended.sort((a, b) => {
+    const aFree = a.tier === 'free' ? 0 : 1;
+    const bFree = b.tier === 'free' ? 0 : 1;
+    if (aFree !== bFree) return aFree - bFree;
+    return STAGE_ORDER.indexOf(a.stage) - STAGE_ORDER.indexOf(b.stage);
+  });
+
+  return { recommended, skipped };
+}
+
+module.exports = { recommend, matchesDetection };