gencode-ai 0.4.1 → 0.5.0

package/src/base/discovery/base-loader.ts

@@ -0,0 +1,241 @@
+/**
+ * Base Loader - Unified resource loading with merge strategy
+ *
+ * Provides a generic resource discovery system that:
+ * 1. Scans all configured levels and namespaces
+ * 2. Merges resources from all sources
+ * 3. Applies priority rules (gen > claude, higher level > lower level)
+ */
+
+import type { DiscoverableResource, DiscoveryConfig, ResourceDirectory } from './types.js';
+import { getResourceDirectories, findProjectRoot } from './path-resolver.js';
+import { scanDirectory, extractResourceName } from './file-scanner.js';
+import { logger } from '../utils/logger.js';
+import { isDebugEnabled } from '../utils/debug.js';
+
+/**
+ * Discover resources from all configured sources
+ *
+ * This is the main entry point for resource discovery. It:
+ * - Scans all directories in priority order (low to high)
+ * - Parses each file using the provided parser
+ * - Merges resources into a Map, with higher priority overriding lower
+ *
+ * @param projectRoot Project root directory (pass process.cwd() if unsure)
+ * @param config Discovery configuration
+ * @returns Map of resource name to resource
+ */
+export async function discoverResources<T extends DiscoverableResource>(
+  projectRoot: string,
+  config: DiscoveryConfig<T>
+): Promise<Map<string, T>> {
+  // Resolve project root if needed
+  const resolvedRoot = await findProjectRoot(projectRoot);
+
+  // Get all resource directories in priority order (low to high)
+  const levels = config.levels || ['user', 'project'];
+  const directories = await getResourceDirectories(
+    resolvedRoot,
+    config.subdirectory,
+    levels
+  );
+
+  if (isDebugEnabled('commands') || isDebugEnabled('discovery')) {
+    logger.debug(
+      config.resourceType,
+      'Starting discovery',
+      {
+        projectRoot: resolvedRoot,
+        subdirectory: config.subdirectory,
+        levels,
+        searchPaths: directories.map(d => `${d.path} (${d.level}/${d.namespace})`),
+      }
+    );
+  }
+
+  // Load resources from all directories
+  const resources = new Map<string, T>();
+
+  for (const directory of directories) {
+    // Skip non-existent directories
+    if (!directory.exists) {
+      continue;
+    }
+
+    // Scan directory for matching files
+    const files = await scanDirectory(directory.path, config.filePattern);
+
+    if (isDebugEnabled('commands') || isDebugEnabled('discovery')) {
+      logger.debug(
+        config.resourceType,
+        `Found ${files.length} file(s) in ${directory.path}`,
+        {
+          level: directory.level,
+          namespace: directory.namespace,
+          files: files.length > 0 ? files.slice(0, 5) : [], // Show first 5 files
+        }
+      );
+    }
+
+    // Parse each file
+    for (const filePath of files) {
+      try {
+        // Extract resource name
+        const name = extractResourceName(
+          filePath,
+          directory.path,
+          config.filePattern
+        );
+
+        if (!name) {
+          logger.warn(
+            config.resourceType,
+            `Failed to extract name from file`,
+            {
+              file: filePath,
+              level: directory.level,
+              namespace: directory.namespace,
+              hint: 'Check file naming convention',
+            }
+          );
+          continue;
+        }
+
+        // Validate name
+        if (!config.parser.isValidName(name)) {
+          logger.warn(
+            config.resourceType,
+            `Invalid name "${name}"`,
+            {
+              file: filePath,
+              level: directory.level,
+              namespace: directory.namespace,
+              hint: 'Name must match allowed pattern',
+            }
+          );
+          continue;
+        }
+
+        // Parse the file
+        const resource = await config.parser.parse(
+          filePath,
+          directory.level,
+          directory.namespace
+        );
+
+        if (resource) {
+          // Override the name with the extracted name (which includes path structure)
+          // This is important for recursive patterns where name should be "email:digest" not just "digest"
+          resource.name = name;
+
+          // Add or override resource (higher priority overwrites lower)
+          resources.set(name, resource);
+
+          if (isDebugEnabled('discovery')) {
+            logger.debug(
+              config.resourceType,
+              `Loaded "${name}"`,
+              {
+                file: filePath,
+                level: directory.level,
+                namespace: directory.namespace,
+              }
+            );
+          }
+        }
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        logger.warn(
+          config.resourceType,
+          `Failed to parse file`,
+          {
+            file: filePath,
+            error: errorMsg,
+            level: directory.level,
+            namespace: directory.namespace,
+            hint: 'Check file syntax and required fields',
+          }
+        );
+      }
+    }
+  }
+
+  if (isDebugEnabled('commands') || isDebugEnabled('discovery')) {
+    logger.debug(
+      config.resourceType,
+      'Discovery complete',
+      {
+        totalResources: resources.size,
+        resourceNames: Array.from(resources.keys()),
+      }
+    );
+  }
+
+  return resources;
+}
+
+/**
+ * Optional Resource Manager class
+ *
+ * Provides a convenient wrapper around discoverResources with
+ * lazy initialization and query methods.
+ */
+export class ResourceManager<T extends DiscoverableResource> {
+  private resources: Map<string, T> = new Map();
+  private initialized: boolean = false;
+
+  constructor(private config: DiscoveryConfig<T>) {}
+
+  /**
+   * Discover all resources (lazy initialization)
+   */
+  async discover(projectRoot: string): Promise<void> {
+    if (this.initialized) return;
+
+    this.resources = await discoverResources(projectRoot, this.config);
+    this.initialized = true;
+  }
+
+  /**
+   * Get all resources
+   */
+  getAll(): T[] {
+    return Array.from(this.resources.values());
+  }
+
+  /**
+   * Get a specific resource by name
+   */
+  get(name: string): T | undefined {
+    return this.resources.get(name);
+  }
+
+  /**
+   * Check if a resource exists
+   */
+  has(name: string): boolean {
+    return this.resources.has(name);
+  }
+
+  /**
+   * Get the number of resources
+   */
+  count(): number {
+    return this.resources.size;
+  }
+
+  /**
+   * Get all resource names
+   */
+  names(): string[] {
+    return Array.from(this.resources.keys());
+  }
+
+  /**
+   * Reload all resources
+   */
+  async reload(projectRoot: string): Promise<void> {
+    this.initialized = false;
+    await this.discover(projectRoot);
+  }
+}

package/src/base/discovery/file-scanner.ts

@@ -0,0 +1,221 @@
+/**
+ * File Scanner - Scan directories for resource files
+ *
+ * Supports multiple file patterns:
+ * - flat: Files directly in directory
+ * - nested: Files in subdirectories
+ * - multiple: Files with various extensions
+ * - single: A single specific file
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import type { FilePattern } from './types.js';
+import { pathExists } from '../utils/path-utils.js';
+
+/**
+ * Scan directory for files matching the pattern
+ *
+ * @param dirPath Absolute path to the directory to scan
+ * @param pattern File pattern to match
+ * @returns Array of absolute file paths
+ */
+export async function scanDirectory(
+  dirPath: string,
+  pattern: FilePattern
+): Promise<string[]> {
+  // Check if directory exists
+  if (!(await pathExists(dirPath))) {
+    return [];
+  }
+
+  switch (pattern.type) {
+    case 'single':
+      return scanSingleFile(dirPath, pattern.filename);
+
+    case 'flat':
+      return scanFlatDirectory(dirPath, pattern.extension);
+
+    case 'nested':
+      return scanNestedDirectory(dirPath, pattern.filename);
+
+    case 'multiple':
+      return scanMultipleExtensions(dirPath, pattern.extensions);
+
+    case 'recursive':
+      return scanRecursiveDirectory(dirPath, pattern.extension);
+
+    default:
+      return [];
+  }
+}
+
+/**
+ * Scan for a single specific file
+ */
+async function scanSingleFile(dirPath: string, filename: string): Promise<string[]> {
+  const filePath = path.join(dirPath, filename);
+  const exists = await pathExists(filePath);
+  return exists ? [filePath] : [];
+}
+
+/**
+ * Scan flat directory for files with specific extension
+ */
+async function scanFlatDirectory(
+  dirPath: string,
+  extension: string
+): Promise<string[]> {
+  try {
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    const files: string[] = [];
+
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith(extension)) {
+        files.push(path.join(dirPath, entry.name));
+      }
+    }
+
+    return files;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Scan nested directory for files with specific filename
+ */
+async function scanNestedDirectory(
+  dirPath: string,
+  filename: string
+): Promise<string[]> {
+  try {
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    const files: string[] = [];
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const filePath = path.join(dirPath, entry.name, filename);
+        if (await pathExists(filePath)) {
+          files.push(filePath);
+        }
+      }
+    }
+
+    return files;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Scan directory for files with multiple extensions
+ */
+async function scanMultipleExtensions(
+  dirPath: string,
+  extensions: string[]
+): Promise<string[]> {
+  try {
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    const files: string[] = [];
+
+    for (const entry of entries) {
+      if (entry.isFile()) {
+        const hasMatchingExtension = extensions.some((ext) =>
+          entry.name.endsWith(ext)
+        );
+        if (hasMatchingExtension) {
+          files.push(path.join(dirPath, entry.name));
+        }
+      }
+    }
+
+    return files;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Recursively scan directory and subdirectories for files with specific extension
+ */
+async function scanRecursiveDirectory(
+  dirPath: string,
+  extension: string
+): Promise<string[]> {
+  const files: string[] = [];
+
+  async function scanDir(currentPath: string): Promise<void> {
+    try {
+      const entries = await fs.readdir(currentPath, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = path.join(currentPath, entry.name);
+
+        if (entry.isFile() && entry.name.endsWith(extension)) {
+          files.push(fullPath);
+        } else if (entry.isDirectory()) {
+          // Recursively scan subdirectories
+          await scanDir(fullPath);
+        }
+      }
+    } catch {
+      // Ignore errors for individual directories
+    }
+  }
+
+  await scanDir(dirPath);
+  return files;
+}
+
+/**
+ * Extract resource name from file path based on pattern
+ *
+ * @param filePath Absolute file path
+ * @param dirPath Directory path (for relative calculation)
+ * @param pattern File pattern
+ * @returns Resource name or null if extraction fails
+ */
+export function extractResourceName(
+  filePath: string,
+  dirPath: string,
+  pattern: FilePattern
+): string | null {
+  const basename = path.basename(filePath);
+  const relativePath = path.relative(dirPath, filePath);
+
+  switch (pattern.type) {
+    case 'single':
+      // For single files, remove leading dot and .json extension
+      return pattern.filename.replace(/^\./g, '').replace(/\.json$/g, '') || 'default';
+
+    case 'flat':
+      // For flat files, use filename without extension
+      return basename.slice(0, -pattern.extension.length);
+
+    case 'nested':
+      // For nested files, use the parent directory name
+      const parentDir = path.dirname(relativePath);
+      return parentDir !== '.' ? parentDir : null;
+
+    case 'multiple':
+      // For multiple extensions, find and remove the matching extension
+      for (const ext of pattern.extensions) {
+        if (basename.endsWith(ext)) {
+          return basename.slice(0, -ext.length);
+        }
+      }
+      return null;
+
+    case 'recursive':
+      // For recursive files, convert path to colon-separated name
+      // Examples:
+      //   commands/email/digest.md → email:digest
+      //   commands/foo.md → foo
+      const nameWithoutExt = relativePath.slice(0, -pattern.extension.length);
+      return nameWithoutExt.replace(/\//g, ':').replace(/\\/g, ':');
+
+    default:
+      return null;
+  }
+}

package/src/base/discovery/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Unified Resource Discovery System
+ *
+ * Public API exports for resource discovery across Commands, Skills, Subagents, and MCP.
+ */
+
+// Core types
+export type {
+  ResourceLevel,
+  ResourceNamespace,
+  ResourceSource,
+  DiscoverableResource,
+  FilePattern,
+  ResourceParser,
+  DiscoveryConfig,
+  ResourceDirectory,
+} from './types.js';
+
+// Path resolution
+export { findProjectRoot, getResourceDirectories, GEN_DIR, CLAUDE_DIR } from './path-resolver.js';
+
+// File scanning
+export { scanDirectory, extractResourceName } from './file-scanner.js';
+
+// Resource loading
+export { discoverResources, ResourceManager } from './base-loader.js';

package/src/base/discovery/path-resolver.ts

@@ -0,0 +1,130 @@
+/**
+ * Path Resolver - Unified path resolution for resource discovery
+ *
+ * Provides consistent path resolution across all resource types (Commands, Skills,
+ * Subagents, MCP) with configurable levels and namespaces.
+ *
+ * Priority rules:
+ * - Level: user < project < local < managed (ascending priority)
+ * - Namespace: claude < gen (gen has higher priority within same level)
+ */
+
+import * as path from 'path';
+import * as os from 'os';
+import type { ResourceLevel, ResourceNamespace, ResourceDirectory } from './types.js';
+import {
+  GEN_DIR,
+  CLAUDE_DIR,
+  getManagedPaths,
+  pathExists,
+  findProjectRoot,
+} from '../utils/path-utils.js';
+
+// Re-export for backward compatibility
+export { GEN_DIR, CLAUDE_DIR, findProjectRoot };
+
+/**
+ * Get resource directories for discovery
+ *
+ * Returns directories in priority order (lowest first) for proper fallback:
+ * - Lower priority directories are processed first
+ * - Higher priority resources override lower priority ones
+ *
+ * @param projectRoot Project root directory
+ * @param subdirectory Subdirectory name (e.g., "commands", "skills") or empty string for root
+ * @param levels Which levels to include (default: ['user', 'project'])
+ * @returns Array of resource directories in priority order
+ */
+export async function getResourceDirectories(
+  projectRoot: string,
+  subdirectory: string,
+  levels: ResourceLevel[] = ['user', 'project']
+): Promise<ResourceDirectory[]> {
+  const home = os.homedir();
+  const managedPaths = getManagedPaths();
+  const directories: ResourceDirectory[] = [];
+
+  // Level priority map
+  const levelPriority: Record<ResourceLevel, number> = {
+    user: 10,
+    project: 30,
+    local: 40,
+    managed: 100,
+  };
+
+  // Process each requested level
+  for (const level of levels) {
+    const baseDirs: Array<{ dir: string; namespace: ResourceNamespace }> = [];
+
+    // Determine base directories for this level
+    switch (level) {
+      case 'user':
+        baseDirs.push(
+          { dir: path.join(home, CLAUDE_DIR), namespace: 'claude' },
+          { dir: path.join(home, GEN_DIR), namespace: 'gen' }
+        );
+        break;
+
+      case 'project':
+        baseDirs.push(
+          { dir: path.join(projectRoot, CLAUDE_DIR), namespace: 'claude' },
+          { dir: path.join(projectRoot, GEN_DIR), namespace: 'gen' }
+        );
+        break;
+
+      case 'local':
+        // Local level uses .local suffix directories for override purposes
+        // These are git-ignored local-only configurations
+        baseDirs.push(
+          { dir: path.join(projectRoot, `${CLAUDE_DIR}.local`), namespace: 'claude' },
+          { dir: path.join(projectRoot, `${GEN_DIR}.local`), namespace: 'gen' }
+        );
+        break;
+
+      case 'managed':
+        baseDirs.push(
+          { dir: managedPaths.claude, namespace: 'claude' },
+          { dir: managedPaths.gen, namespace: 'gen' }
+        );
+        break;
+    }
+
+    // Add subdirectory and create ResourceDirectory entries
+    for (const { dir, namespace } of baseDirs) {
+      const fullPath = subdirectory ? path.join(dir, subdirectory) : dir;
+      const exists = await pathExists(fullPath);
+
+      directories.push({
+        path: fullPath,
+        level,
+        namespace,
+        exists,
+      });
+    }
+  }
+
+  // Sort by level priority (ascending), then by namespace (claude < gen)
+  directories.sort((a, b) => {
+    const priorityDiff = levelPriority[a.level] - levelPriority[b.level];
+    if (priorityDiff !== 0) return priorityDiff;
+
+    // Within same level, claude < gen
+    if (a.namespace === 'claude' && b.namespace === 'gen') return -1;
+    if (a.namespace === 'gen' && b.namespace === 'claude') return 1;
+    return 0;
+  });
+
+  return directories;
+}
+
+/**
+ * Get only existing resource directories
+ */
+export async function getExistingResourceDirectories(
+  projectRoot: string,
+  subdirectory: string,
+  levels: ResourceLevel[] = ['user', 'project']
+): Promise<ResourceDirectory[]> {
+  const all = await getResourceDirectories(projectRoot, subdirectory, levels);
+  return all.filter((dir) => dir.exists === true);
+}