claude-code-workflow 6.1.4 → 6.2.2

package/ccw/src/tools/{generate-module-docs.js → generate-module-docs.ts}

@@ -3,10 +3,13 @@
  * Generate documentation for modules and projects with multiple strategies
  */
 
+import { z } from 'zod';
+import type { ToolSchema, ToolResult } from '../types/tool.js';
 import { readdirSync, statSync, existsSync, readFileSync, mkdirSync, writeFileSync, unlinkSync } from 'fs';
 import { join, resolve, basename, extname, relative } from 'path';
 import { execSync } from 'child_process';
 import { tmpdir } from 'os';
+import { getSecondaryModel } from './cli-config-manager.js';
 
 // Directories to exclude
 const EXCLUDE_DIRS = [
@@ -21,7 +24,7 @@ const CODE_EXTENSIONS = [
 ];
 
 // Default models for each tool
-const DEFAULT_MODELS = {
+const DEFAULT_MODELS: Record<string, string> = {
   gemini: 'gemini-2.5-flash',
   qwen: 'coder-model',
   codex: 'gpt5-codex'
@@ -30,10 +33,35 @@ const DEFAULT_MODELS = {
 // Template paths (relative to user home directory)
 const TEMPLATE_BASE = '.claude/workflows/cli-templates/prompts/documentation';
 
+// Define Zod schema for validation
+const ParamsSchema = z.object({
+  strategy: z.enum(['full', 'single', 'project-readme', 'project-architecture', 'http-api']),
+  sourcePath: z.string().min(1, 'Source path is required'),
+  projectName: z.string().min(1, 'Project name is required'),
+  tool: z.enum(['gemini', 'qwen', 'codex']).default('gemini'),
+  model: z.string().optional(),
+});
+
+type Params = z.infer<typeof ParamsSchema>;
+
+interface ToolOutput {
+  success: boolean;
+  strategy: string;
+  source_path: string;
+  project_name: string;
+  output_path?: string;
+  folder_type?: 'code' | 'navigation';
+  tool: string;
+  model?: string;
+  duration_seconds?: number;
+  message?: string;
+  error?: string;
+}
+
 /**
  * Detect folder type (code vs navigation)
  */
-function detectFolderType(dirPath) {
+function detectFolderType(dirPath: string): 'code' | 'navigation' {
   try {
     const entries = readdirSync(dirPath, { withFileTypes: true });
     const codeFiles = entries.filter(e => {
@@ -47,22 +75,10 @@ function detectFolderType(dirPath) {
   }
 }
 
-/**
- * Count files in directory
- */
-function countFiles(dirPath) {
-  try {
-    const entries = readdirSync(dirPath, { withFileTypes: true });
-    return entries.filter(e => e.isFile() && !e.name.startsWith('.')).length;
-  } catch (e) {
-    return 0;
-  }
-}
-
 /**
  * Calculate output path
  */
-function calculateOutputPath(sourcePath, projectName, projectRoot) {
+function calculateOutputPath(sourcePath: string, projectName: string, projectRoot: string): string {
   const absSource = resolve(sourcePath);
   const normRoot = resolve(projectRoot);
   let relPath = relative(normRoot, absSource);
@@ -74,16 +90,26 @@ function calculateOutputPath(sourcePath, projectName, projectRoot) {
 /**
  * Load template content
  */
-function loadTemplate(templateName) {
+function loadTemplate(templateName: string): string {
   const homePath = process.env.HOME || process.env.USERPROFILE;
+  if (!homePath) {
+    return getDefaultTemplate(templateName);
+  }
+
   const templatePath = join(homePath, TEMPLATE_BASE, `${templateName}.txt`);
 
   if (existsSync(templatePath)) {
     return readFileSync(templatePath, 'utf8');
   }
 
-  // Fallback templates
-  const fallbacks = {
+  return getDefaultTemplate(templateName);
+}
+
+/**
+ * Get default template content
+ */
+function getDefaultTemplate(templateName: string): string {
+  const fallbacks: Record<string, string> = {
     'api': 'Generate API documentation with function signatures, parameters, return values, and usage examples.',
     'module-readme': 'Generate README documentation with purpose, usage, configuration, and examples.',
     'folder-navigation': 'Generate navigation README with overview of subdirectories and their purposes.',
@@ -97,7 +123,7 @@ function loadTemplate(templateName) {
 /**
  * Create temporary prompt file and return path
  */
-function createPromptFile(prompt) {
+function createPromptFile(prompt: string): string {
   const timestamp = Date.now();
   const randomSuffix = Math.random().toString(36).substring(2, 8);
   const promptFile = join(tmpdir(), `docs-prompt-${timestamp}-${randomSuffix}.txt`);
@@ -108,13 +134,13 @@ function createPromptFile(prompt) {
 /**
  * Build CLI command using stdin piping (avoids shell escaping issues)
  */
-function buildCliCommand(tool, promptFile, model) {
+function buildCliCommand(tool: string, promptFile: string, model: string): string {
   const normalizedPath = promptFile.replace(/\\/g, '/');
   const isWindows = process.platform === 'win32';
-  
+
   // Build the cat/read command based on platform
   const catCmd = isWindows ? `Get-Content -Raw "${normalizedPath}" | ` : `cat "${normalizedPath}" | `;
-  
+
   switch (tool) {
     case 'qwen':
       return model === 'coder-model'
@@ -135,14 +161,17 @@ function buildCliCommand(tool, promptFile, model) {
 /**
  * Scan directory structure
  */
-function scanDirectoryStructure(targetPath, strategy) {
-  const lines = [];
+function scanDirectoryStructure(targetPath: string): {
+  info: string;
+  folderType: 'code' | 'navigation';
+} {
+  const lines: string[] = [];
   const dirName = basename(targetPath);
 
   let totalFiles = 0;
   let totalDirs = 0;
 
-  function countRecursive(dir) {
+  function countRecursive(dir: string): void {
     try {
       const entries = readdirSync(dir, { withFileTypes: true });
       entries.forEach(e => {
@@ -172,63 +201,101 @@ function scanDirectoryStructure(targetPath, strategy) {
   };
 }
 
-/**
- * Main execute function
- */
-async function execute(params) {
-  const { strategy, sourcePath, projectName, tool = 'gemini', model } = params;
+// Tool schema for MCP
+export const schema: ToolSchema = {
+  name: 'generate_module_docs',
+  description: `Generate documentation for modules and projects.
 
-  // Validate parameters
-  const validStrategies = ['full', 'single', 'project-readme', 'project-architecture', 'http-api'];
+Module-Level Strategies:
+- full: Full documentation (API.md + README.md for all directories)
+- single: Single-layer documentation (current directory only)
 
-  if (!strategy) {
-    throw new Error(`Parameter "strategy" is required. Valid: ${validStrategies.join(', ')}`);
-  }
+Project-Level Strategies:
+- project-readme: Project overview from module docs
+- project-architecture: System design documentation
+- http-api: HTTP API documentation
 
-  if (!validStrategies.includes(strategy)) {
-    throw new Error(`Invalid strategy '${strategy}'. Valid: ${validStrategies.join(', ')}`);
+Output: .workflow/docs/{projectName}/...`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      strategy: {
+        type: 'string',
+        enum: ['full', 'single', 'project-readme', 'project-architecture', 'http-api'],
+        description: 'Documentation strategy'
+      },
+      sourcePath: {
+        type: 'string',
+        description: 'Source module directory path'
+      },
+      projectName: {
+        type: 'string',
+        description: 'Project name for output path'
+      },
+      tool: {
+        type: 'string',
+        enum: ['gemini', 'qwen', 'codex'],
+        description: 'CLI tool to use (default: gemini)',
+        default: 'gemini'
+      },
+      model: {
+        type: 'string',
+        description: 'Model name (optional, uses tool defaults)'
+      }
+    },
+    required: ['strategy', 'sourcePath', 'projectName']
   }
+};
 
-  if (!sourcePath) {
-    throw new Error('Parameter "sourcePath" is required');
+// Handler function
+export async function handler(params: Record<string, unknown>): Promise<ToolResult<ToolOutput>> {
+  const parsed = ParamsSchema.safeParse(params);
+  if (!parsed.success) {
+    return { success: false, error: `Invalid params: ${parsed.error.message}` };
   }
 
-  if (!projectName) {
-    throw new Error('Parameter "projectName" is required');
-  }
+  const { strategy, sourcePath, projectName, tool, model } = parsed.data;
 
-  const targetPath = resolve(process.cwd(), sourcePath);
+  try {
+    const targetPath = resolve(process.cwd(), sourcePath);
 
-  if (!existsSync(targetPath)) {
-    throw new Error(`Directory not found: ${targetPath}`);
-  }
+    if (!existsSync(targetPath)) {
+      return { success: false, error: `Directory not found: ${targetPath}` };
+    }
 
-  if (!statSync(targetPath).isDirectory()) {
-    throw new Error(`Not a directory: ${targetPath}`);
-  }
+    if (!statSync(targetPath).isDirectory()) {
+      return { success: false, error: `Not a directory: ${targetPath}` };
+    }
 
-  // Set model
-  const actualModel = model || DEFAULT_MODELS[tool] || DEFAULT_MODELS.gemini;
+    // Set model (use secondaryModel from config for internal calls)
+    let actualModel = model;
+    if (!actualModel) {
+      try {
+        actualModel = getSecondaryModel(process.cwd(), tool);
+      } catch {
+        actualModel = DEFAULT_MODELS[tool] || DEFAULT_MODELS.gemini;
+      }
+    }
 
-  // Scan directory
-  const { info: structureInfo, folderType } = scanDirectoryStructure(targetPath, strategy);
+    // Scan directory
+    const { info: structureInfo, folderType } = scanDirectoryStructure(targetPath);
 
-  // Calculate output path
-  const outputPath = calculateOutputPath(targetPath, projectName, process.cwd());
+    // Calculate output path
+    const outputPath = calculateOutputPath(targetPath, projectName, process.cwd());
 
-  // Ensure output directory exists
-  mkdirSync(outputPath, { recursive: true });
+    // Ensure output directory exists
+    mkdirSync(outputPath, { recursive: true });
 
-  // Build prompt based on strategy
-  let prompt;
-  let templateContent;
+    // Build prompt based on strategy
+    let prompt: string;
+    let templateContent: string;
 
-  switch (strategy) {
-    case 'full':
-    case 'single':
-      if (folderType === 'code') {
-        templateContent = loadTemplate('api');
-        prompt = `Directory Structure Analysis:
+    switch (strategy) {
+      case 'full':
+      case 'single':
+        if (folderType === 'code') {
+          templateContent = loadTemplate('api');
+          prompt = `Directory Structure Analysis:
 ${structureInfo}
 
 Read: ${strategy === 'full' ? '@**/*' : '@*.ts @*.tsx @*.js @*.jsx @*.py @*.sh @*.md @*.json'}
@@ -241,9 +308,9 @@ Output directory: ${outputPath}
 
 Template Guidelines:
 ${templateContent}`;
-      } else {
-        templateContent = loadTemplate('folder-navigation');
-        prompt = `Directory Structure Analysis:
+        } else {
+          templateContent = loadTemplate('folder-navigation');
+          prompt = `Directory Structure Analysis:
 ${structureInfo}
 
 Read: @*/API.md @*/README.md
@@ -255,12 +322,12 @@ Output directory: ${outputPath}
 
 Template Guidelines:
 ${templateContent}`;
-      }
-      break;
+        }
+        break;
 
-    case 'project-readme':
-      templateContent = loadTemplate('project-readme');
-      prompt = `Read all module documentation:
+      case 'project-readme':
+        templateContent = loadTemplate('project-readme');
+        prompt = `Read all module documentation:
 @.workflow/docs/${projectName}/**/API.md
 @.workflow/docs/${projectName}/**/README.md
 
@@ -269,11 +336,11 @@ Generate project-level documentation:
 
 Template Guidelines:
 ${templateContent}`;
-      break;
+        break;
 
-    case 'project-architecture':
-      templateContent = loadTemplate('project-architecture');
-      prompt = `Read project documentation:
+      case 'project-architecture':
+        templateContent = loadTemplate('project-architecture');
+        prompt = `Read project documentation:
 @.workflow/docs/${projectName}/README.md
 @.workflow/docs/${projectName}/**/API.md
 
@@ -285,10 +352,10 @@ Output directory: .workflow/docs/${projectName}/
 
 Template Guidelines:
 ${templateContent}`;
-      break;
+        break;
 
-    case 'http-api':
-      prompt = `Read API route files:
+      case 'http-api':
+        prompt = `Read API route files:
 @**/routes/**/*.ts @**/routes/**/*.js
 @**/api/**/*.ts @**/api/**/*.js
 
@@ -296,121 +363,76 @@ Generate HTTP API documentation:
 - api/README.md: REST API endpoints documentation
 
 Output directory: .workflow/docs/${projectName}/api/`;
-      break;
-  }
+        break;
+    }
 
-  // Create temporary prompt file (avoids shell escaping issues)
-  const promptFile = createPromptFile(prompt);
-  
-  // Build command using file-based prompt
-  const command = buildCliCommand(tool, promptFile, actualModel);
+    // Create temporary prompt file (avoids shell escaping issues)
+    const promptFile = createPromptFile(prompt);
 
-  // Log execution info
-  console.log(`📚 Generating docs: ${sourcePath}`);
-  console.log(`   Strategy: ${strategy} | Tool: ${tool} | Model: ${actualModel}`);
-  console.log(`   Output: ${outputPath}`);
-  console.log(`   Prompt file: ${promptFile}`);
+    // Build command using file-based prompt
+    const command = buildCliCommand(tool, promptFile, actualModel);
 
-  try {
-    const startTime = Date.now();
-
-    execSync(command, {
-      cwd: targetPath,
-      encoding: 'utf8',
-      stdio: 'inherit',
-      timeout: 600000, // 10 minutes
-      shell: process.platform === 'win32' ? 'powershell.exe' : '/bin/bash'
-    });
-
-    const duration = Math.round((Date.now() - startTime) / 1000);
+    // Log execution info
+    console.log(`📚 Generating docs: ${sourcePath}`);
+    console.log(`   Strategy: ${strategy} | Tool: ${tool} | Model: ${actualModel}`);
+    console.log(`   Output: ${outputPath}`);
 
-    // Cleanup prompt file
     try {
-      unlinkSync(promptFile);
-    } catch (e) {
-      // Ignore cleanup errors
-    }
+      const startTime = Date.now();
+
+      execSync(command, {
+        cwd: targetPath,
+        encoding: 'utf8',
+        stdio: 'inherit',
+        timeout: 600000, // 10 minutes
+        shell: process.platform === 'win32' ? 'powershell.exe' : '/bin/bash'
+      });
 
-    console.log(`   ✅ Completed in ${duration}s`);
+      const duration = Math.round((Date.now() - startTime) / 1000);
 
-    return {
-      success: true,
-      strategy,
-      source_path: sourcePath,
-      project_name: projectName,
-      output_path: outputPath,
-      folder_type: folderType,
-      tool,
-      model: actualModel,
-      duration_seconds: duration,
-      message: `Documentation generated successfully in ${duration}s`
-    };
-  } catch (error) {
-    // Cleanup prompt file on error
-    try {
-      unlinkSync(promptFile);
-    } catch (e) {
-      // Ignore cleanup errors
-    }
+      // Cleanup prompt file
+      try {
+        unlinkSync(promptFile);
+      } catch (e) {
+        // Ignore cleanup errors
+      }
 
-    console.log(`   ❌ Generation failed: ${error.message}`);
+      console.log(`   ✅ Completed in ${duration}s`);
+
+      return {
+        success: true,
+        result: {
+          success: true,
+          strategy,
+          source_path: sourcePath,
+          project_name: projectName,
+          output_path: outputPath,
+          folder_type: folderType,
+          tool,
+          model: actualModel,
+          duration_seconds: duration,
+          message: `Documentation generated successfully in ${duration}s`
+        }
+      };
+    } catch (error) {
+      // Cleanup prompt file on error
+      try {
+        unlinkSync(promptFile);
+      } catch (e) {
+        // Ignore cleanup errors
+      }
 
+      console.log(`   ❌ Generation failed: ${(error as Error).message}`);
+
+      return {
+        success: false,
+        error: `Documentation generation failed: ${(error as Error).message}`
+      };
+    }
+  } catch (error) {
     return {
       success: false,
-      strategy,
-      source_path: sourcePath,
-      project_name: projectName,
-      tool,
-      error: error.message
+      error: `Tool execution failed: ${(error as Error).message}`
     };
   }
 }
-
-/**
- * Tool Definition
- */
-export const generateModuleDocsTool = {
-  name: 'generate_module_docs',
-  description: `Generate documentation for modules and projects.
-
-Module-Level Strategies:
-- full: Full documentation (API.md + README.md for all directories)
-- single: Single-layer documentation (current directory only)
-
-Project-Level Strategies:
-- project-readme: Project overview from module docs
-- project-architecture: System design documentation
-- http-api: HTTP API documentation
-
-Output: .workflow/docs/{projectName}/...`,
-  parameters: {
-    type: 'object',
-    properties: {
-      strategy: {
-        type: 'string',
-        enum: ['full', 'single', 'project-readme', 'project-architecture', 'http-api'],
-        description: 'Documentation strategy'
-      },
-      sourcePath: {
-        type: 'string',
-        description: 'Source module directory path'
-      },
-      projectName: {
-        type: 'string',
-        description: 'Project name for output path'
-      },
-      tool: {
-        type: 'string',
-        enum: ['gemini', 'qwen', 'codex'],
-        description: 'CLI tool to use (default: gemini)',
-        default: 'gemini'
-      },
-      model: {
-        type: 'string',
-        description: 'Model name (optional, uses tool defaults)'
-      }
-    },
-    required: ['strategy', 'sourcePath', 'projectName']
-  },
-  execute
-};