grimoire-framework 1.0.0

package/.grimoire/cli/commands/workers/list.js

@@ -0,0 +1,215 @@
+/**
+ * List Command - List all workers in the registry
+ *
+ * Implements `grimoire workers list` CLI command.
+ * Displays workers grouped by category with filtering and pagination.
+ *
+ * @module cli/commands/workers/list
+ * @version 1.0.0
+ * @story 2.8-2.9 - Discovery CLI Info & List
+ */
+
+const { Command } = require('commander');
+const { getRegistry } = require('../../../core/registry/registry-loader');
+const { formatTree } = require('./formatters/list-tree');
+const { formatList, formatCount } = require('./formatters/list-table');
+const { paginate, formatPaginationHint } = require('./utils/pagination');
+
+/**
+ * Create the list command
+ * @returns {Command} Commander command instance
+ */
+function createListCommand() {
+  const list = new Command('list');
+
+  list
+    .description('List all workers in the service registry')
+    .option('-c, --category <category>', 'Filter by category')
+    .option('-f, --format <format>', 'Output format: tree, table, json, yaml', 'tree')
+    .option('-p, --page <n>', 'Page number for pagination', '1')
+    .option('-l, --limit <n>', 'Items per page', '20')
+    .option('--count', 'Show count summary only')
+    .option('-v, --verbose', 'Show verbose/debug output')
+    .addHelpText('after', `
+Examples:
+  $ grimoire workers list
+  $ grimoire workers list --category=task
+  $ grimoire workers list --format=table
+  $ grimoire workers list --format=json --category=script
+  $ grimoire workers list --page=2 --limit=10
+  $ grimoire workers list --count
+  $ grimoire workers list --verbose
+
+Output Formats:
+  tree     Grouped tree view by category (default)
+  table    Tabular list with columns
+  json     JSON array of workers
+  yaml     YAML list of workers
+
+Categories:
+  task       Executable task workflows for agents
+  template   Document and code templates
+  script     JavaScript utility scripts
+  checklist  Quality validation checklists
+  workflow   Multi-step workflow definitions
+  data       Knowledge base and configuration data
+`)
+    .action(executeList);
+
+  return list;
+}
+
+/**
+ * Execute the list command
+ * @param {object} options - Command options
+ */
+async function executeList(options) {
+  const startTime = Date.now();
+
+  try {
+    const registry = getRegistry();
+
+    if (options.verbose) {
+      console.log('Loading worker registry...');
+      if (options.category) console.log(`Category filter: ${options.category}`);
+      console.log(`Output format: ${options.format}`);
+      console.log(`Page: ${options.page}, Limit: ${options.limit}`);
+      console.log('');
+    }
+
+    // Handle count-only mode
+    if (options.count) {
+      await executeCountMode(registry, options);
+      logPerformance(startTime, options.verbose);
+      return;
+    }
+
+    // Get workers (optionally filtered by category)
+    let workers;
+    if (options.category) {
+      workers = await registry.getByCategory(options.category.toLowerCase());
+
+      if (workers.length === 0) {
+        // Check if category exists
+        const categories = await registry.getCategories();
+        if (!categories[options.category.toLowerCase()]) {
+          console.error(`Error: Category '${options.category}' not found.`);
+          console.log('\nAvailable categories:');
+          Object.keys(categories).forEach(cat => {
+            console.log(`  - ${cat} (${categories[cat].count} workers)`);
+          });
+          process.exit(1);
+        }
+      }
+    } else {
+      workers = await registry.getAll();
+    }
+
+    // Sort workers by category, then name
+    workers.sort((a, b) => {
+      if (a.category !== b.category) {
+        return a.category.localeCompare(b.category);
+      }
+      return a.name.localeCompare(b.name);
+    });
+
+    // Format based on output type
+    const format = (options.format || 'tree').toLowerCase();
+
+    if (format === 'tree') {
+      // Tree format doesn't use pagination (shows all grouped)
+      const output = formatTree(workers, {
+        verbose: options.verbose,
+      });
+      console.log(output);
+    } else {
+      // Table/JSON/YAML formats support pagination
+      const page = parseInt(options.page, 10) || 1;
+      const limit = parseInt(options.limit, 10) || 20;
+
+      const paginatedResult = paginate(workers, { page, limit });
+
+      const output = formatList(paginatedResult.items, {
+        format: format,
+        pagination: paginatedResult.pagination,
+        verbose: options.verbose,
+      });
+
+      console.log(output);
+
+      // Show pagination hint for table format
+      if (format === 'table' && paginatedResult.pagination.totalPages > 1) {
+        const hint = formatPaginationHint(paginatedResult.pagination);
+        if (hint) {
+          console.log(hint);
+        }
+      }
+    }
+
+    logPerformance(startTime, options.verbose);
+
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    if (options.verbose) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Execute count-only mode
+ * @param {ServiceRegistry} registry - Registry instance
+ * @param {object} options - Command options
+ */
+async function executeCountMode(registry, options) {
+  const categories = await registry.getCategories();
+  const totalWorkers = await registry.count();
+
+  // If category filter, show just that category
+  if (options.category) {
+    const category = options.category.toLowerCase();
+    const catData = categories[category];
+
+    if (!catData) {
+      console.error(`Error: Category '${options.category}' not found.`);
+      process.exit(1);
+    }
+
+    console.log(`${category.toUpperCase()}: ${catData.count} workers`);
+
+    if (options.verbose && catData.subcategories) {
+      console.log(`  Subcategories: ${catData.subcategories.join(', ')}`);
+    }
+  } else {
+    // Show all categories
+    const output = formatCount(categories, totalWorkers, {
+      verbose: options.verbose,
+    });
+    console.log(output);
+  }
+}
+
+/**
+ * Log performance metrics
+ * @param {number} startTime - Start timestamp
+ * @param {boolean} verbose - Show verbose output
+ */
+function logPerformance(startTime, verbose) {
+  const duration = Date.now() - startTime;
+
+  if (verbose) {
+    console.log(`\n[Performance: ${duration}ms]`);
+  }
+
+  // Warn if over target (1s for list with 200+ workers)
+  if (duration > 1000) {
+    console.warn(`\nWarning: List command took ${duration}ms (target: < 1000ms)`);
+  }
+}
+
+module.exports = {
+  createListCommand,
+  executeList,
+};
+

package/.grimoire/cli/commands/workers/search-filters.js

@@ -0,0 +1,185 @@
+/**
+ * Search Filters Module
+ *
+ * Implements filtering logic for search results.
+ * Supports category and tag-based filtering.
+ *
+ * @module cli/commands/workers/search-filters
+ * @version 1.0.0
+ * @story 2.7 - Discovery CLI Search
+ */
+
+/**
+ * Apply filters to search results
+ * @param {Array} results - Search results array
+ * @param {object} filters - Filter options
+ * @param {string} [filters.category] - Category filter
+ * @param {string[]} [filters.tags] - Tags filter (AND logic)
+ * @returns {Array} Filtered results
+ */
+function applyFilters(results, filters = {}) {
+  let filtered = [...results];
+
+  // Apply category filter
+  if (filters.category) {
+    const categoryLower = filters.category.toLowerCase();
+    filtered = filtered.filter(worker => {
+      const workerCategory = (worker.category || '').toLowerCase();
+      return workerCategory === categoryLower ||
+             workerCategory.includes(categoryLower);
+    });
+  }
+
+  // Apply tag filters (AND logic - worker must have ALL specified tags)
+  if (filters.tags && filters.tags.length > 0) {
+    filtered = filtered.filter(worker => {
+      const workerTags = (worker.tags || []).map(t => t.toLowerCase());
+      return filters.tags.every(tag =>
+        workerTags.some(wt => wt === tag.toLowerCase() || wt.includes(tag.toLowerCase())),
+      );
+    });
+  }
+
+  return filtered;
+}
+
+/**
+ * Filter by category
+ * @param {Array} results - Search results
+ * @param {string} category - Category to filter by
+ * @returns {Array} Filtered results
+ */
+function filterByCategory(results, category) {
+  if (!category) return results;
+
+  const categoryLower = category.toLowerCase();
+  return results.filter(worker => {
+    const workerCategory = (worker.category || '').toLowerCase();
+    return workerCategory === categoryLower;
+  });
+}
+
+/**
+ * Filter by tags (AND logic)
+ * @param {Array} results - Search results
+ * @param {string[]} tags - Tags to filter by
+ * @returns {Array} Filtered results
+ */
+function filterByTags(results, tags) {
+  if (!tags || tags.length === 0) return results;
+
+  const tagsLower = tags.map(t => t.toLowerCase());
+
+  return results.filter(worker => {
+    const workerTags = new Set((worker.tags || []).map(t => t.toLowerCase()));
+    return tagsLower.every(tag => workerTags.has(tag));
+  });
+}
+
+/**
+ * Filter by tags (OR logic - worker must have at least one tag)
+ * @param {Array} results - Search results
+ * @param {string[]} tags - Tags to filter by
+ * @returns {Array} Filtered results
+ */
+function filterByAnyTag(results, tags) {
+  if (!tags || tags.length === 0) return results;
+
+  const tagsLower = tags.map(t => t.toLowerCase());
+
+  return results.filter(worker => {
+    const workerTags = new Set((worker.tags || []).map(t => t.toLowerCase()));
+    return tagsLower.some(tag => workerTags.has(tag));
+  });
+}
+
+/**
+ * Filter by subcategory
+ * @param {Array} results - Search results
+ * @param {string} subcategory - Subcategory to filter by
+ * @returns {Array} Filtered results
+ */
+function filterBySubcategory(results, subcategory) {
+  if (!subcategory) return results;
+
+  const subcategoryLower = subcategory.toLowerCase();
+  return results.filter(worker => {
+    const workerSubcategory = (worker.subcategory || '').toLowerCase();
+    return workerSubcategory === subcategoryLower;
+  });
+}
+
+/**
+ * Filter by task format
+ * @param {Array} results - Search results
+ * @param {string} taskFormat - Task format (e.g., 'TASK-FORMAT-V1')
+ * @returns {Array} Filtered results
+ */
+function filterByTaskFormat(results, taskFormat) {
+  if (!taskFormat) return results;
+
+  return results.filter(worker =>
+    worker.taskFormat === taskFormat,
+  );
+}
+
+/**
+ * Filter by executor type
+ * @param {Array} results - Search results
+ * @param {string} executorType - Executor type (e.g., 'Worker', 'Agent')
+ * @returns {Array} Filtered results
+ */
+function filterByExecutorType(results, executorType) {
+  if (!executorType) return results;
+
+  return results.filter(worker => {
+    const executorTypes = worker.executorTypes || [];
+    return executorTypes.includes(executorType);
+  });
+}
+
+/**
+ * Combine multiple filters
+ * @param {Array} results - Search results
+ * @param {object[]} filterList - Array of filter objects {type, value}
+ * @returns {Array} Filtered results
+ */
+function applyMultipleFilters(results, filterList) {
+  let filtered = results;
+
+  for (const filter of filterList) {
+    switch (filter.type) {
+      case 'category':
+        filtered = filterByCategory(filtered, filter.value);
+        break;
+      case 'tags':
+        filtered = filterByTags(filtered, filter.value);
+        break;
+      case 'anyTag':
+        filtered = filterByAnyTag(filtered, filter.value);
+        break;
+      case 'subcategory':
+        filtered = filterBySubcategory(filtered, filter.value);
+        break;
+      case 'taskFormat':
+        filtered = filterByTaskFormat(filtered, filter.value);
+        break;
+      case 'executorType':
+        filtered = filterByExecutorType(filtered, filter.value);
+        break;
+    }
+  }
+
+  return filtered;
+}
+
+module.exports = {
+  applyFilters,
+  filterByCategory,
+  filterByTags,
+  filterByAnyTag,
+  filterBySubcategory,
+  filterByTaskFormat,
+  filterByExecutorType,
+  applyMultipleFilters,
+};

package/.grimoire/cli/commands/workers/search-keyword.js

@@ -0,0 +1,310 @@
+/**
+ * Keyword Search Module
+ *
+ * Implements keyword-based search with fuzzy matching.
+ * Used as fallback when semantic search is unavailable.
+ *
+ * @module cli/commands/workers/search-keyword
+ * @version 1.0.0
+ * @story 2.7 - Discovery CLI Search
+ */
+
+const { getRegistry } = require('../../../core/registry/registry-loader');
+
+/**
+ * Calculate Levenshtein distance between two strings
+ * @param {string} a - First string
+ * @param {string} b - Second string
+ * @returns {number} Edit distance
+ */
+function levenshteinDistance(a, b) {
+  const matrix = [];
+
+  // Initialize matrix
+  for (let i = 0; i <= b.length; i++) {
+    matrix[i] = [i];
+  }
+  for (let j = 0; j <= a.length; j++) {
+    matrix[0][j] = j;
+  }
+
+  // Fill matrix
+  for (let i = 1; i <= b.length; i++) {
+    for (let j = 1; j <= a.length; j++) {
+      if (b.charAt(i - 1) === a.charAt(j - 1)) {
+        matrix[i][j] = matrix[i - 1][j - 1];
+      } else {
+        matrix[i][j] = Math.min(
+          matrix[i - 1][j - 1] + 1, // substitution
+          matrix[i][j - 1] + 1,     // insertion
+          matrix[i - 1][j] + 1,      // deletion
+        );
+      }
+    }
+  }
+
+  return matrix[b.length][a.length];
+}
+
+/**
+ * Calculate fuzzy match score (0-100) - Optimized version
+ * @param {string} text - Text to search in
+ * @param {string} query - Search query
+ * @returns {number} Match score
+ */
+function fuzzyMatchScore(text, query) {
+  if (!text || !query) return 0;
+
+  const textLower = text.toLowerCase();
+  const queryLower = query.toLowerCase();
+
+  // Exact match - early exit
+  if (textLower === queryLower) {
+    return 100;
+  }
+
+  // Contains exact query - early exit
+  if (textLower.includes(queryLower)) {
+    // Higher score if at word boundary
+    const wordBoundaryRegex = new RegExp(`\\b${escapeRegex(queryLower)}\\b`);
+    if (wordBoundaryRegex.test(textLower)) {
+      return 95;
+    }
+    return 85;
+  }
+
+  // Check individual words
+  const queryWords = queryLower.split(/\s+/).filter(w => w.length > 0);
+  const textWords = textLower.split(/\s+/).filter(w => w.length > 0);
+
+  // Quick check: if no word overlap possible, return early
+  if (textWords.length === 0 || queryWords.length === 0) {
+    return 0;
+  }
+
+  let wordMatchScore = 0;
+  let matchedWords = 0;
+
+  for (const queryWord of queryWords) {
+    let bestWordScore = 0;
+
+    // Quick exact/contains checks first (avoid Levenshtein when possible)
+    for (const textWord of textWords) {
+      // Exact word match
+      if (textWord === queryWord) {
+        bestWordScore = 100;
+        break; // Can't do better, exit early
+      }
+
+      // Word starts with query
+      if (textWord.startsWith(queryWord)) {
+        bestWordScore = Math.max(bestWordScore, 90);
+        continue; // Might find exact match later
+      }
+
+      // Query starts with text word (partial match)
+      if (queryWord.startsWith(textWord) && textWord.length >= 3) {
+        bestWordScore = Math.max(bestWordScore, 85);
+        continue;
+      }
+
+      // Word contains query
+      if (textWord.includes(queryWord) && queryWord.length >= 3) {
+        bestWordScore = Math.max(bestWordScore, 80);
+        continue;
+      }
+    }
+
+    // Only do Levenshtein for short queries if no good match found
+    // This is the expensive part - skip it when we already have decent score
+    if (bestWordScore < 70 && queryWord.length <= 8) {
+      for (const textWord of textWords) {
+        // Skip very different length words
+        const lenDiff = Math.abs(queryWord.length - textWord.length);
+        if (lenDiff > 3) continue;
+
+        const distance = levenshteinDistance(queryWord, textWord);
+        const maxLen = Math.max(queryWord.length, textWord.length);
+        const similarity = 1 - (distance / maxLen);
+
+        if (similarity >= 0.7) {
+          bestWordScore = Math.max(bestWordScore, Math.round(similarity * 70));
+        }
+      }
+    }
+
+    if (bestWordScore > 0) {
+      matchedWords++;
+      wordMatchScore += bestWordScore;
+    }
+  }
+
+  if (matchedWords === 0) {
+    return 0;
+  }
+
+  // Calculate average word score weighted by matched words ratio
+  const avgWordScore = wordMatchScore / queryWords.length;
+  const matchedRatio = matchedWords / queryWords.length;
+
+  return Math.round(avgWordScore * matchedRatio);
+}
+
+/**
+ * Escape special regex characters
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string
+ */
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Build searchable text fields from worker
+ * @param {object} worker - Worker object
+ * @returns {object} Object with searchable fields
+ */
+function buildSearchFields(worker) {
+  return {
+    id: worker.id || '',
+    name: worker.name || '',
+    description: worker.description || '',
+    category: worker.category || '',
+    subcategory: worker.subcategory || '',
+    tags: (worker.tags || []).join(' '),
+    inputs: (worker.inputs || []).join(' '),
+    outputs: (worker.outputs || []).join(' '),
+    combined: [
+      worker.id,
+      worker.name,
+      worker.description,
+      worker.category,
+      worker.subcategory,
+      ...(worker.tags || []),
+      ...(worker.inputs || []),
+      ...(worker.outputs || []),
+    ].filter(Boolean).join(' '),
+  };
+}
+
+/**
+ * Perform keyword search with fuzzy matching - Optimized version
+ * @param {string} query - Search query
+ * @returns {Promise<Array<{worker: object, score: number}>>} Search results with scores
+ */
+async function searchKeyword(query) {
+  const registry = getRegistry();
+  const workers = await registry.getAll();
+
+  const results = [];
+  const queryLower = query.toLowerCase().trim();
+
+  for (const worker of workers) {
+    // Quick pre-check: does ID or name contain query?
+    const idLower = (worker.id || '').toLowerCase();
+    const nameLower = (worker.name || '').toLowerCase();
+
+    // Fast path: exact ID match
+    if (idLower === queryLower) {
+      results.push({ ...worker, score: 100, matchType: 'id' });
+      continue;
+    }
+
+    // Fast path: ID contains query
+    if (idLower.includes(queryLower)) {
+      results.push({ ...worker, score: 95, matchType: 'id' });
+      continue;
+    }
+
+    // Fast path: name contains query
+    if (nameLower.includes(queryLower)) {
+      results.push({ ...worker, score: 90, matchType: 'name' });
+      continue;
+    }
+
+    // Check tags quickly
+    const tags = (worker.tags || []).map(t => t.toLowerCase());
+    const tagMatch = tags.find(t => t === queryLower || t.includes(queryLower));
+    if (tagMatch) {
+      results.push({ ...worker, score: 85, matchType: 'tags' });
+      continue;
+    }
+
+    // Slower path: full fuzzy search on all fields
+    const fields = buildSearchFields(worker);
+
+    // Only do expensive fuzzy scoring on important fields
+    let bestScore = 0;
+    let matchType = 'combined';
+
+    // Check ID with fuzzy
+    const idScore = fuzzyMatchScore(fields.id, queryLower) * 1.5;
+    if (idScore > bestScore) {
+      bestScore = idScore;
+      matchType = 'id';
+    }
+
+    // Check name with fuzzy
+    const nameScore = fuzzyMatchScore(fields.name, queryLower) * 1.3;
+    if (nameScore > bestScore) {
+      bestScore = nameScore;
+      matchType = 'name';
+    }
+
+    // Check description (skip if we already have good score)
+    if (bestScore < 70) {
+      const descScore = fuzzyMatchScore(fields.description, queryLower) * 0.8;
+      if (descScore > bestScore) {
+        bestScore = descScore;
+        matchType = 'description';
+      }
+    }
+
+    // Include results with score above threshold
+    if (bestScore >= 20) {
+      results.push({
+        ...worker,
+        score: Math.round(Math.min(bestScore, 100)),
+        matchType: matchType,
+      });
+    }
+  }
+
+  // Sort by score descending
+  results.sort((a, b) => b.score - a.score);
+
+  return results;
+}
+
+/**
+ * Search by exact tag match
+ * @param {string[]} tags - Tags to search for
+ * @returns {Promise<Array>} Workers matching any tag
+ */
+async function searchByTags(tags) {
+  const registry = getRegistry();
+  const results = [];
+
+  for (const tag of tags) {
+    const workers = await registry.getByTag(tag);
+    for (const worker of workers) {
+      if (!results.find(r => r.id === worker.id)) {
+        results.push({
+          ...worker,
+          score: 100,
+          matchType: 'tag-exact',
+        });
+      }
+    }
+  }
+
+  return results;
+}
+
+module.exports = {
+  searchKeyword,
+  searchByTags,
+  fuzzyMatchScore,
+  levenshteinDistance,
+  buildSearchFields,
+};