forge-workflow 0.0.1

package/lib/plugin-catalog.js

@@ -0,0 +1,360 @@
+/**
+ * Plugin Catalog
+ *
+ * Static, frozen catalog of tools for the Forge workflow.
+ * Read-only data — no installations, no side effects.
+ */
+
+const TIERS = Object.freeze({
+  FREE: 'free',
+  FREE_PUBLIC: 'free-public',
+  FREE_LIMITED: 'free-limited',
+  PAID: 'paid',
+});
+
+const TOOL_TYPES = Object.freeze({
+  CLI: 'cli',
+  SKILL: 'skill',
+  MCP: 'mcp',
+  CONFIG: 'config',
+  LSP: 'lsp',
+});
+
+const STAGES = Object.freeze({
+  RESEARCH: 'research',
+  PLAN: 'plan',
+  DEV: 'dev',
+  CHECK: 'check',
+  SHIP: 'ship',
+  REVIEW: 'review',
+  MERGE: 'merge',
+});
+
+const BUDGET_MODES = Object.freeze({
+  free: { label: 'Free only', includes: ['free'] },
+  'open-source': { label: 'Open source', includes: ['free', 'free-public'] },
+  startup: { label: 'Startup', includes: ['free', 'free-public', 'free-limited'] },
+  professional: { label: 'Professional', includes: ['free', 'free-public', 'free-limited', 'paid'] },
+  custom: { label: 'Custom', includes: [] },
+});
+
+const PREREQUISITES = Object.freeze({
+  node: { check: 'node --version', installUrl: 'https://nodejs.org' },
+  git: { check: 'git --version', installUrl: 'https://git-scm.com' },
+  gh: { check: 'gh --version', installUrl: 'https://cli.github.com' },
+  bun: { check: 'bun --version', installUrl: 'https://bun.sh' },
+  jq: { check: 'jq --version', installUrl: 'https://jqlang.github.io/jq/download/' },
+  go: { check: 'go version', installUrl: 'https://go.dev/dl/' },
+  curl: { check: 'curl --version', installUrl: null },
+  'parallel-cli': {
+    check: 'parallel-cli --version',
+    installUrl: 'https://parallel.ai/install.sh',
+  },
+});
+
+const CATALOG = Object.freeze({
+  // ── Research ──
+  'context7-mcp': {
+    name: 'Context7',
+    type: 'mcp',
+    tier: 'free',
+    stage: 'research',
+    description: 'Up-to-date library documentation via MCP',
+    detectWhen: [],
+    install: { method: 'add-mcp', cmd: 'bunx add-mcp context7' },
+    mcpJustified: true,
+  },
+  'grep-app-mcp': {
+    name: 'grep.app',
+    type: 'mcp',
+    tier: 'free',
+    stage: 'research',
+    description: 'Search 1M+ GitHub repos for real-world code examples',
+    detectWhen: [],
+    install: { method: 'add-mcp', cmd: 'bunx add-mcp grep-app' },
+    mcpJustified: true,
+  },
+
+  'parallel-deep-research': {
+    name: 'Parallel Deep Research',
+    type: 'skill',
+    tier: 'paid',
+    stage: 'research',
+    description: 'Comprehensive research reports via Parallel AI pro/ultra processors (3-25 min)',
+    detectWhen: [],
+    install: {
+      method: 'skills',
+      cmd: 'bunx skills add parallel-web/parallel-agent-skills --skill parallel-deep-research',
+      cmdCurl: 'bunx skills add harshanandak/forge --skill parallel-deep-research',
+    },
+    prerequisites: ['parallel-cli'],
+    alternatives: [{ tool: 'WebSearch', tier: 'free', tradeoff: 'Shallow — only a few queries vs deep multi-source synthesis' }],
+  },
+
+  // ── Plan ──
+  beads: {
+    name: 'Beads',
+    type: 'cli',
+    tier: 'free',
+    stage: 'plan',
+    description: 'Git-backed issue tracking',
+    detectWhen: [],
+    install: { method: 'npm', cmd: 'bun add -g @beads/bd' },
+  },
+  openspec: {
+    name: 'OpenSpec',
+    type: 'cli',
+    tier: 'free',
+    stage: 'plan',
+    description: 'Spec-driven development proposals',
+    detectWhen: [],
+    install: { method: 'npm', cmd: 'bun add -g @fission-ai/openspec' },
+  },
+
+  // ── Dev ──
+  'typescript-lsp': {
+    name: 'TypeScript LSP',
+    type: 'lsp',
+    tier: 'free',
+    stage: 'dev',
+    description: 'TypeScript language server for IDE integration',
+    detectWhen: ['dep:typescript', 'file:tsconfig.json'],
+    install: { method: 'lsp', cmd: '.lsp.json config' },
+  },
+  'supabase-cli': {
+    name: 'Supabase CLI',
+    type: 'cli',
+    tier: 'free-limited',
+    stage: 'dev',
+    description: 'Local Supabase development and migrations',
+    detectWhen: ['dep:@supabase/supabase-js'],
+    install: { method: 'npm', cmd: 'bun add -D supabase', dev: true },
+    alternatives: [{ tool: 'postgresql-client', tier: 'free', tradeoff: 'No Supabase-specific features' }],
+  },
+  'stripe-cli': {
+    name: 'Stripe CLI',
+    type: 'cli',
+    tier: 'free',
+    stage: 'dev',
+    description: 'Stripe webhook testing and API interaction',
+    detectWhen: ['dep:stripe'],
+    install: { method: 'binary', cmd: 'https://stripe.com/docs/stripe-cli' },
+  },
+  'vercel-agent-skills': {
+    name: 'Vercel Agent Skills',
+    type: 'skill',
+    tier: 'free',
+    stage: 'dev',
+    description: 'Vercel deployment and preview management',
+    detectWhen: ['dep:next'],
+    install: { method: 'skills', cmd: 'bunx skills add vercel-labs/agent-skills' },
+  },
+
+  // ── Check ──
+  eslint: {
+    name: 'ESLint',
+    type: 'cli',
+    tier: 'free',
+    stage: 'check',
+    description: 'JavaScript/TypeScript linting',
+    detectWhen: ['file:eslint.config.js', 'dep:eslint'],
+    install: { method: 'npm', cmd: 'bun add -D eslint', dev: true },
+  },
+  biome: {
+    name: 'Biome',
+    type: 'cli',
+    tier: 'free',
+    stage: 'check',
+    description: 'Fast formatter and linter',
+    detectWhen: ['file:biome.json'],
+    install: { method: 'npm', cmd: 'bun add -D @biomejs/biome', dev: true },
+  },
+  prettier: {
+    name: 'Prettier',
+    type: 'cli',
+    tier: 'free',
+    stage: 'check',
+    description: 'Opinionated code formatter',
+    detectWhen: ['file:.prettierrc'],
+    install: { method: 'npm', cmd: 'bun add -D prettier', dev: true },
+  },
+  'eslint-plugin-security': {
+    name: 'ESLint Security Plugin',
+    type: 'config',
+    tier: 'free',
+    stage: 'check',
+    description: 'Security-focused ESLint rules',
+    detectWhen: ['dep:express', 'dep:fastify'],
+    install: { method: 'npm', cmd: 'bun add -D eslint-plugin-security', dev: true },
+  },
+  'sonarcloud-analysis': {
+    name: 'SonarCloud Analysis',
+    type: 'skill',
+    tier: 'free-public',
+    stage: 'check',
+    description: 'Code quality and security analysis via SonarCloud REST API',
+    detectWhen: [],
+    install: {
+      method: 'skills',
+      cmd: 'bunx skills add harshanandak/forge --skill sonarcloud-analysis',
+    },
+    alternatives: [{ tool: 'eslint', tier: 'free', tradeoff: 'Less comprehensive analysis' }],
+  },
+  'sonar-scanner': {
+    name: 'Sonar Scanner',
+    type: 'cli',
+    tier: 'free-public',
+    stage: 'check',
+    description: 'SonarCloud/SonarQube CLI scanner',
+    detectWhen: ['file:sonar-project.properties'],
+    install: { method: 'npm', cmd: 'bun add -D sonarqube-scanner', dev: true },
+    alternatives: [{ tool: 'eslint', tier: 'free', tradeoff: 'No centralized dashboard' }],
+  },
+  codeql: {
+    name: 'CodeQL',
+    type: 'cli',
+    tier: 'free-public',
+    stage: 'check',
+    description: 'Semantic code analysis by GitHub',
+    detectWhen: [],
+    install: { method: 'binary', cmd: 'GitHub-provided (github.com/github/codeql-action)' },
+    alternatives: [{ tool: 'eslint-plugin-security', tier: 'free', tradeoff: 'Less deep analysis' }],
+  },
+  'npm-audit': {
+    name: 'npm audit',
+    type: 'cli',
+    tier: 'free',
+    stage: 'check',
+    description: 'Dependency vulnerability scanning',
+    detectWhen: [],
+    install: { method: 'npm', cmd: 'built-in (bun pm audit)' },
+  },
+  vitest: {
+    name: 'Vitest',
+    type: 'cli',
+    tier: 'free',
+    stage: 'check',
+    description: 'Vite-native test runner',
+    detectWhen: ['dep:vitest', 'file:vitest.config.ts'],
+    install: { method: 'npm', cmd: 'bun add -D vitest', dev: true },
+  },
+  jest: {
+    name: 'Jest',
+    type: 'cli',
+    tier: 'free',
+    stage: 'check',
+    description: 'Delightful JavaScript testing',
+    detectWhen: ['dep:jest', 'file:jest.config.js'],
+    install: { method: 'npm', cmd: 'bun add -D jest', dev: true },
+  },
+  playwright: {
+    name: 'Playwright',
+    type: 'cli',
+    tier: 'free',
+    stage: 'check',
+    description: 'End-to-end browser testing',
+    detectWhen: ['dep:@playwright/test'],
+    install: { method: 'npm', cmd: 'bun add -D @playwright/test', dev: true },
+  },
+  c8: {
+    name: 'c8',
+    type: 'cli',
+    tier: 'free',
+    stage: 'check',
+    description: 'Native V8 code coverage',
+    detectWhen: [],
+    install: { method: 'npm', cmd: 'bun add -D c8', dev: true },
+  },
+  stryker: {
+    name: 'Stryker',
+    type: 'cli',
+    tier: 'free',
+    stage: 'check',
+    description: 'Mutation testing for JavaScript',
+    detectWhen: [],
+    install: { method: 'npm', cmd: 'bun add -D @stryker-mutator/core', dev: true },
+  },
+  oxlint: {
+    name: 'Oxlint',
+    type: 'cli',
+    tier: 'free',
+    stage: 'check',
+    description: 'Blazing-fast Rust-based linter',
+    detectWhen: [],
+    install: { method: 'npm', cmd: 'bun add -D oxlint', dev: true },
+  },
+
+  // ── Ship ──
+  'gh-cli': {
+    name: 'GitHub CLI',
+    type: 'cli',
+    tier: 'free',
+    stage: 'ship',
+    description: 'GitHub PR and issue management',
+    detectWhen: [],
+    install: { method: 'binary', cmd: 'https://cli.github.com' },
+    prerequisites: ['gh'],
+  },
+  lefthook: {
+    name: 'Lefthook',
+    type: 'cli',
+    tier: 'free',
+    stage: 'ship',
+    description: 'Fast git hooks manager',
+    detectWhen: [],
+    install: { method: 'npm', cmd: 'bun add -D lefthook', dev: true },
+  },
+
+  // ── Review ──
+  coderabbit: {
+    name: 'CodeRabbit',
+    type: 'config',
+    tier: 'free-public',
+    stage: 'review',
+    description: 'AI-powered code review',
+    detectWhen: [],
+    install: { method: 'config', cmd: 'GitHub App (coderabbit.ai)' },
+    alternatives: [{ tool: 'qodo-merge', tier: 'free', tradeoff: 'Self-hosted, more setup' }],
+  },
+  greptile: {
+    name: 'Greptile',
+    type: 'config',
+    tier: 'paid',
+    stage: 'review',
+    description: 'AI code review with codebase context',
+    detectWhen: [],
+    install: { method: 'config', cmd: 'GitHub App (greptile.com)' },
+    alternatives: [{ tool: 'coderabbit', tier: 'free-public', tradeoff: 'Less codebase awareness' }],
+  },
+  'qodo-merge': {
+    name: 'Qodo Merge',
+    type: 'cli',
+    tier: 'free',
+    stage: 'review',
+    description: 'AI-assisted code review (self-hosted)',
+    detectWhen: [],
+    install: { method: 'config', cmd: 'Self-hosted (qodo.ai)' },
+  },
+
+  // ── Merge ──
+  changesets: {
+    name: 'Changesets',
+    type: 'cli',
+    tier: 'free',
+    stage: 'merge',
+    description: 'Versioning and changelog management',
+    detectWhen: ['file:package.json'],
+    install: { method: 'npm', cmd: 'bun add -D @changesets/cli', dev: true },
+  },
+  'release-please': {
+    name: 'Release Please',
+    type: 'config',
+    tier: 'free',
+    stage: 'merge',
+    description: 'Automated release PRs by Google',
+    detectWhen: [],
+    install: { method: 'config', cmd: 'GitHub Action (google-github-actions/release-please-action)' },
+  },
+});
+
+module.exports = { CATALOG, TIERS, TOOL_TYPES, STAGES, BUDGET_MODES, PREREQUISITES };

package/lib/plugin-manager.js

@@ -0,0 +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;

package/lib/plugin-recommender.js

@@ -0,0 +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 };