gencode-ai 0.4.1 → 0.5.0

package/src/base/discovery/types.ts

@@ -0,0 +1,159 @@
+/**
+ * Unified Resource Discovery System - Core Types
+ *
+ * This module provides the foundational types for a unified resource discovery
+ * system that eliminates code duplication across Commands, Skills, Subagents, and MCP.
+ *
+ * All resources follow the same merge strategy:
+ * - Load from all levels and namespaces
+ * - Priority: user < project < local < managed
+ * - Within each level: claude < gen
+ * - Higher priority resources override lower priority ones (by name)
+ */
+
+/**
+ * Resource level - hierarchical configuration levels
+ */
+export type ResourceLevel = 'user' | 'project' | 'local' | 'managed';
+
+/**
+ * Resource namespace - identifies the config system (.gen or .claude)
+ */
+export type ResourceNamespace = 'gen' | 'claude';
+
+/**
+ * Source metadata for discovered resources
+ *
+ * Tracks where a resource was loaded from, following the priority:
+ * .gen > .claude and project > user
+ */
+export interface ResourceSource {
+  /** User or project level */
+  level: ResourceLevel;
+
+  /** Gen or Claude namespace */
+  namespace: ResourceNamespace;
+
+  /** Absolute path to the resource file */
+  path: string;
+}
+
+/**
+ * Base interface for all discoverable resources
+ *
+ * Any resource type (Command, Skill, Subagent) must extend this interface
+ * to be compatible with the unified discovery system.
+ */
+export interface DiscoverableResource {
+  /** Unique resource name */
+  name: string;
+
+  /** Source metadata */
+  source: ResourceSource;
+}
+
+/**
+ * File pattern matching strategy
+ */
+export type FilePattern =
+  | {
+      /** Flat structure - files directly in directory (e.g., commands/*.md) */
+      type: 'flat';
+      /** File extension including dot (e.g., '.md') */
+      extension: string;
+    }
+  | {
+      /** Nested structure - files in subdirectories (e.g., skills/star/SKILL.md) */
+      type: 'nested';
+      /** Exact filename to match (e.g., 'SKILL.md') */
+      filename: string;
+    }
+  | {
+      /** Multiple extensions - supports various file types (e.g., agents/star.{json,md}) */
+      type: 'multiple';
+      /** Array of extensions including dots (e.g., ['.json', '.md']) */
+      extensions: string[];
+    }
+  | {
+      /** Single file - a specific file at the root (e.g., .mcp.json) */
+      type: 'single';
+      /** Exact filename (e.g., '.mcp.json') */
+      filename: string;
+    }
+  | {
+      /** Recursive structure - files in directory and all subdirectories (e.g., commands/**\/*.md) */
+      type: 'recursive';
+      /** File extension including dot (e.g., '.md') */
+      extension: string;
+    };
+
+/**
+ * Resource parser interface
+ *
+ * Each resource type must implement this interface to handle
+ * file parsing and validation.
+ */
+export interface ResourceParser<T extends DiscoverableResource> {
+  /**
+   * Parse a resource file
+   *
+   * @param filePath Absolute path to the resource file
+   * @param level Resource level (user or project)
+   * @param namespace Resource namespace (gen or claude)
+   * @returns Parsed resource or null if parsing fails
+   */
+  parse(
+    filePath: string,
+    level: ResourceLevel,
+    namespace: ResourceNamespace
+  ): Promise<T | null>;
+
+  /**
+   * Validate a resource name
+   *
+   * @param name Resource name to validate
+   * @returns true if the name is valid
+   */
+  isValidName(name: string): boolean;
+}
+
+/**
+ * Discovery configuration
+ *
+ * Configures the unified discovery system for a specific resource type.
+ */
+export interface DiscoveryConfig<T extends DiscoverableResource> {
+  /** Resource type name for logging (e.g., "Command", "Skill", "MCP Server") */
+  resourceType: string;
+
+  /** Subdirectory name within .gen/.claude (e.g., "commands", "skills"), or empty for root */
+  subdirectory: string;
+
+  /** File pattern matching strategy */
+  filePattern: FilePattern;
+
+  /** Parser implementation for this resource type */
+  parser: ResourceParser<T>;
+
+  /** Which levels to include (default: ['user', 'project']) */
+  levels?: ResourceLevel[];
+}
+
+/**
+ * Resource directory metadata
+ *
+ * Used internally by the discovery system to track search paths.
+ */
+export interface ResourceDirectory {
+  /** Absolute path to the directory */
+  path: string;
+
+  /** Resource level */
+  level: ResourceLevel;
+
+  /** Resource namespace */
+  namespace: ResourceNamespace;
+
+  /** Whether the directory exists */
+  exists?: boolean;
+}

package/src/base/utils/config-validator.ts

@@ -0,0 +1,191 @@
+/**
+ * Configuration Validator
+ *
+ * Provides Zod schemas for validating various configuration files:
+ * - SKILL.md frontmatter
+ * - Command markdown frontmatter
+ * - Custom agent JSON/MD files
+ * - Hooks configuration
+ */
+
+import { z } from 'zod';
+import { logger } from './logger.js';
+
+/**
+ * SKILL.md frontmatter schema
+ */
+export const SkillFrontmatterSchema = z.object({
+  name: z.string().min(1, 'Skill name is required'),
+  description: z.string().min(1, 'Skill description is required'),
+  'allowed-tools': z
+    .union([z.string(), z.array(z.string())])
+    .optional()
+    .describe('Tools allowed for this skill (string or array)'),
+  version: z.string().optional(),
+  author: z.string().optional(),
+  tags: z.array(z.string()).optional(),
+});
+
+export type SkillFrontmatter = z.infer<typeof SkillFrontmatterSchema>;
+
+/**
+ * Command markdown frontmatter schema
+ */
+export const CommandFrontmatterSchema = z.object({
+  name: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Command name (optional, defaults to filename)'),
+  description: z.string().min(1, 'Command description is required'),
+  'allowed-tools': z
+    .union([z.string(), z.array(z.string())])
+    .optional()
+    .describe('Tools allowed for this command'),
+  'argument-hint': z.string().optional().describe('Hint for command arguments'),
+  model: z.string().optional().describe('Preferred model for this command'),
+  includes: z
+    .union([z.string(), z.array(z.string())])
+    .optional()
+    .describe('Files to include inline (relative paths)'),
+});
+
+export type CommandFrontmatter = z.infer<typeof CommandFrontmatterSchema>;
+
+/**
+ * Custom agent schema (JSON format)
+ */
+export const CustomAgentSchema = z.object({
+  name: z.string().min(1, 'Agent name is required'),
+  description: z.string().min(1, 'Agent description is required'),
+  allowedTools: z
+    .array(z.string())
+    .min(1, 'At least one allowed tool is required'),
+  defaultModel: z.string().default('claude-sonnet-4'),
+  maxTurns: z.number().positive().default(20),
+  permissionMode: z.enum(['strict', 'permissive']).default('strict').optional(),
+  systemPrompt: z.string().min(1, 'System prompt is required'),
+});
+
+export type CustomAgent = z.infer<typeof CustomAgentSchema>;
+
+/**
+ * Hook configuration schema
+ */
+export const HookSchema = z.object({
+  event: z.enum([
+    'ToolCall',
+    'AgentStart',
+    'AgentEnd',
+    'UserPromptSubmit',
+    'Notification',
+    'Stop',
+  ]),
+  matcher: z
+    .object({
+      tool: z.string().optional(),
+      pattern: z.string().optional(),
+    })
+    .optional(),
+  command: z.string().min(1, 'Hook command is required'),
+  blocking: z.boolean().default(false).optional(),
+  timeout: z.number().positive().default(5000).optional(),
+});
+
+export type Hook = z.infer<typeof HookSchema>;
+
+/**
+ * Hooks configuration schema
+ */
+export const HooksConfigSchema = z.object({
+  hooks: z.array(HookSchema),
+});
+
+export type HooksConfig = z.infer<typeof HooksConfigSchema>;
+
+/**
+ * Validation result
+ */
+export interface ValidationResult<T> {
+  valid: boolean;
+  data?: T;
+  errors?: string[];
+}
+
+/**
+ * Validate configuration data against a Zod schema
+ *
+ * @param schema - Zod schema to validate against
+ * @param data - Data to validate
+ * @param context - Context for error messages (e.g., file path)
+ * @returns Validation result with parsed data or errors
+ */
+export function validateConfig<T>(
+  schema: z.ZodSchema<T>,
+  data: unknown,
+  context: string
+): ValidationResult<T> {
+  try {
+    const validated = schema.parse(data);
+    return { valid: true, data: validated };
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      const errors = error.issues.map((e: z.ZodIssue) => {
+        const path = e.path.join('.');
+        return path ? `${path}: ${e.message}` : e.message;
+      });
+
+      logger.error('Validator', `Invalid configuration in ${context}`, { errors });
+
+      return { valid: false, errors };
+    }
+
+    // Unknown error
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    logger.error('Validator', `Validation failed for ${context}`, {
+      error: errorMsg,
+    });
+
+    return { valid: false, errors: [errorMsg] };
+  }
+}
+
+/**
+ * Validate skill frontmatter
+ */
+export function validateSkillFrontmatter(
+  data: unknown,
+  filePath: string
+): ValidationResult<SkillFrontmatter> {
+  return validateConfig(SkillFrontmatterSchema, data, filePath);
+}
+
+/**
+ * Validate command frontmatter
+ */
+export function validateCommandFrontmatter(
+  data: unknown,
+  filePath: string
+): ValidationResult<CommandFrontmatter> {
+  return validateConfig(CommandFrontmatterSchema, data, filePath);
+}
+
+/**
+ * Validate custom agent configuration
+ */
+export function validateCustomAgent(
+  data: unknown,
+  filePath: string
+): ValidationResult<CustomAgent> {
+  return validateConfig(CustomAgentSchema, data, filePath);
+}
+
+/**
+ * Validate hooks configuration
+ */
+export function validateHooksConfig(
+  data: unknown,
+  filePath: string
+): ValidationResult<HooksConfig> {
+  return validateConfig(HooksConfigSchema, data, filePath);
+}

package/src/base/utils/debug.ts

@@ -0,0 +1,103 @@
+/**
+ * Debug configuration module
+ * Controls debug output for various GenCode components
+ *
+ * Debug Levels:
+ * - GEN_DEBUG=0 or unset: No debug output (default)
+ * - GEN_DEBUG=1: Standard debug output (component loading, key operations)
+ * - GEN_DEBUG=2: Verbose debug output (detailed execution, parameters, results)
+ */
+
+export type DebugLevel = 0 | 1 | 2;
+
+export interface DebugConfig {
+  level: DebugLevel;
+  enabled: boolean; // level >= 1
+  verbose: boolean; // level >= 2
+  components: {
+    skills: DebugLevel;
+    commands: DebugLevel;
+    subagents: DebugLevel;
+    hooks: DebugLevel;
+    mcp: DebugLevel;
+    tools: DebugLevel;
+    discovery: DebugLevel;
+  };
+}
+
+let cachedConfig: DebugConfig | null = null;
+
+/**
+ * Parse debug level from environment variable
+ */
+function parseDebugLevel(value: string | undefined): DebugLevel {
+  if (!value) return 0;
+  const level = parseInt(value, 10);
+  if (level === 2) return 2;
+  if (level === 1) return 1;
+  return 0;
+}
+
+/**
+ * Get debug configuration based on environment variables
+ *
+ * - GEN_DEBUG=0 or unset: No debug output (default)
+ * - GEN_DEBUG=1: Standard debug output (loading, key operations)
+ * - GEN_DEBUG=2: Verbose debug output (detailed execution, parameters)
+ * - GEN_DEBUG_<COMPONENT>=1|2: Component-specific debug level
+ */
+export function getDebugConfig(): DebugConfig {
+  if (cachedConfig) {
+    return cachedConfig;
+  }
+
+  const globalLevel = parseDebugLevel(process.env.GEN_DEBUG);
+
+  cachedConfig = {
+    level: globalLevel,
+    enabled: globalLevel >= 1,
+    verbose: globalLevel >= 2,
+    components: {
+      skills: parseDebugLevel(process.env.GEN_DEBUG_SKILLS) || globalLevel,
+      commands: parseDebugLevel(process.env.GEN_DEBUG_COMMANDS) || globalLevel,
+      subagents: parseDebugLevel(process.env.GEN_DEBUG_SUBAGENTS) || globalLevel,
+      hooks: parseDebugLevel(process.env.GEN_DEBUG_HOOKS) || globalLevel,
+      mcp: parseDebugLevel(process.env.GEN_DEBUG_MCP) || globalLevel,
+      tools: parseDebugLevel(process.env.GEN_DEBUG_TOOLS) || globalLevel,
+      discovery: parseDebugLevel(process.env.GEN_DEBUG_DISCOVERY) || globalLevel,
+    },
+  };
+
+  return cachedConfig;
+}
+
+/**
+ * Check if debug is enabled for a specific component (level >= 1)
+ */
+export function isDebugEnabled(component: keyof DebugConfig['components']): boolean {
+  const config = getDebugConfig();
+  return config.components[component] >= 1;
+}
+
+/**
+ * Check if verbose debug is enabled for a specific component (level >= 2)
+ */
+export function isVerboseDebugEnabled(component: keyof DebugConfig['components']): boolean {
+  const config = getDebugConfig();
+  return config.components[component] >= 2;
+}
+
+/**
+ * Get debug level for a specific component
+ */
+export function getDebugLevel(component: keyof DebugConfig['components']): DebugLevel {
+  const config = getDebugConfig();
+  return config.components[component];
+}
+
+/**
+ * Reset cached config (useful for testing)
+ */
+export function resetDebugConfig(): void {
+  cachedConfig = null;
+}

package/src/base/utils/format-utils.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared Formatting Utilities
+ *
+ * Common utilities for formatting output, messages, and status indicators.
+ */
+
+/**
+ * Format a boxed message with title and metadata fields
+ *
+ * Creates a visually distinct box with header and key-value pairs:
+ * ```
+ * ┌─ Title ─────────────────────────────────────────
+ * │ Key1: Value1
+ * │ Key2: Value2
+ * └─────────────────────────────────────────────────
+ * ```
+ *
+ * @param title - Box title
+ * @param fields - Key-value pairs to display
+ * @param width - Total box width (default: 52)
+ * @returns Formatted boxed message
+ */
+export function formatBoxedMessage(
+  title: string,
+  fields: Record<string, string>,
+  width: number = 52
+): string {
+  const lines: string[] = [];
+
+  // Calculate padding for title
+  const titleText = ` ${title} `;
+  const dashCount = Math.max(0, width - titleText.length - 2);
+  const titleLine = `┌─${titleText}${'─'.repeat(dashCount)}`;
+
+  lines.push(titleLine);
+
+  // Add fields
+  for (const [key, value] of Object.entries(fields)) {
+    lines.push(`│ ${key}: ${value}`);
+  }
+
+  // Bottom border
+  lines.push(`└${'─'.repeat(width - 1)}`);
+
+  return lines.join('\n');
+}
+
+/**
+ * Status indicator symbols (text-based, no emojis)
+ */
+export const STATUS_SYMBOLS = {
+  BLOCKED: '[BLOCKED]',
+  SUCCESS: '[SUCCESS]',
+  FAILED: '[FAILED]',
+  INFO: '[INFO]',
+  WARNING: '[WARNING]',
+} as const;
+
+/**
+ * Format a status message with symbol prefix
+ *
+ * @param status - Status type
+ * @param message - Status message
+ * @returns Formatted status string
+ */
+export function formatStatus(
+  status: keyof typeof STATUS_SYMBOLS,
+  message: string
+): string {
+  return `${STATUS_SYMBOLS[status]} ${message}`;
+}

package/src/base/utils/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Common Utilities
+ */
+
+export * from './logger.js';
+export * from './validation.js';
+export * from './debug.js';
+export * from './path-utils.js';
+export * from './format-utils.js';
+export * from './stream-utils.js';
+export * from './config-validator.js';
+export * from './loading-reporter.js';