documcp

import { promises as fs } from "fs"; import { join } from "path"; export interface ProjectContext { projectType: string; languages: string[]; frameworks: string[]; hasTests: boolean; hasCI: boolean; readmeExists: boolean; packageManager?: string; documentationGaps: string[]; } export interface PromptMessage { role: "user" | "assistant" | "system"; content: { type: "text"; text: string; }; } export async function analyzeProjectContext( projectPath: string, ): Promise<ProjectContext> { const context: ProjectContext = { projectType: "unknown", languages: [], frameworks: [], hasTests: false, hasCI: false, readmeExists: false, documentationGaps: [], }; // Check for README context.readmeExists = await fileExists(join(projectPath, "README.md")); // Analyze package.json for Node.js projects const packageJsonPath = join(projectPath, "package.json"); if (await fileExists(packageJsonPath)) { try { const packageJson = JSON.parse( await fs.readFile(packageJsonPath, "utf-8"), ); const deps = { ...packageJson.dependencies, ...packageJson.devDependencies, }; context.projectType = "node_application"; context.languages.push("JavaScript"); // Detect frameworks if (deps["react"]) context.frameworks.push("React"); if (deps["vue"]) context.frameworks.push("Vue"); if (deps["angular"]) context.frameworks.push("Angular"); if (deps["express"]) context.frameworks.push("Express"); if (deps["next"]) context.frameworks.push("Next.js"); if (deps["nuxt"]) context.frameworks.push("Nuxt.js"); if (deps["svelte"]) context.frameworks.push("Svelte"); if (deps["typescript"]) context.languages.push("TypeScript"); // Detect package manager if (await fileExists(join(projectPath, "yarn.lock"))) { context.packageManager = "yarn"; } else if (await fileExists(join(projectPath, "pnpm-lock.yaml"))) { context.packageManager = "pnpm"; } else { context.packageManager = "npm"; } } catch (error) { // If package.json exists but can't be parsed, continue with other detections console.warn("Failed to parse package.json:", error); } } // Check for Python projects if ( (await fileExists(join(projectPath, "requirements.txt"))) || (await fileExists(join(projectPath, "pyproject.toml"))) || (await fileExists(join(projectPath, "setup.py"))) ) { context.projectType = "python_application"; context.languages.push("Python"); } // Check for Go projects if (await fileExists(join(projectPath, "go.mod"))) { context.projectType = "go_application"; context.languages.push("Go"); } // Check for Rust projects if (await fileExists(join(projectPath, "Cargo.toml"))) { context.projectType = "rust_application"; context.languages.push("Rust"); } // Check for tests context.hasTests = await hasTestFiles(projectPath); // Check for CI/CD context.hasCI = await hasCIConfig(projectPath); // Identify documentation gaps context.documentationGaps = await identifyDocumentationGaps( projectPath, context, ); return context; } export async function generateTechnicalWriterPrompts( promptType: string, projectPath: string, args: Record<string, any> = {}, ): Promise<PromptMessage[]> { const context = await analyzeProjectContext(projectPath); switch (promptType) { case "tutorial-writer": return generateTutorialWriterPrompt(context, args); case "howto-guide-writer": return generateHowToGuideWriterPrompt(context, args); case "reference-writer": return generateReferenceWriterPrompt(context, args); case "explanation-writer": return generateExplanationWriterPrompt(context, args); case "diataxis-organizer": return generateDiataxisOrganizerPrompt(context, args); case "readme-optimizer": return generateReadmeOptimizerPrompt(context, args); case "analyze-and-recommend": return generateAnalyzeAndRecommendPrompt(context, args); case "setup-documentation": return generateSetupDocumentationPrompt(context, args); case "troubleshoot-deployment": return generateTroubleshootDeploymentPrompt(context, args); default: throw new Error(`Unknown prompt type: ${promptType}`); } } function generateTutorialWriterPrompt( context: ProjectContext, args: Record<string, any>, ): PromptMessage[] { const targetAudience = args.target_audience || "beginners"; const learningGoal = args.learning_goal || "get started with the project"; return [ { role: "user", content: { type: "text", text: `Create a comprehensive tutorial for a ${ context.projectType } project following Diataxis framework principles. **Project Context:** - Type: ${context.projectType} - Languages: ${context.languages.join(", ")} - Frameworks: ${context.frameworks.join(", ")} - Package Manager: ${context.packageManager || "N/A"} - Target Audience: ${targetAudience} - Learning Goal: ${learningGoal} **Diataxis Tutorial Requirements:** 1. Learning-oriented: Focus on helping users learn by doing 2. Step-by-step progression from simple to complex 3. Practical exercises with clear outcomes 4. Safe-to-fail environment for experimentation 5. Minimal explanation - focus on action **Tutorial Structure:** 1. Prerequisites and setup 2. Step-by-step guided exercises 3. What you'll build/learn 4. Hands-on activities with immediate feedback 5. Next steps for continued learning **Integration Hints:** - Use analyze_repository for project structure insights - Reference setup_development_environment for environment setup - Consider validate_tutorial_steps for step verification Please create a tutorial that teaches through guided practice:`, }, }, ]; } function generateHowToGuideWriterPrompt( context: ProjectContext, args: Record<string, any>, ): PromptMessage[] { const problemToSolve = args.problem || "common development task"; const userExperience = args.user_experience || "intermediate"; return [ { role: "user", content: { type: "text", text: `Create a practical how-to guide for a ${ context.projectType } project following Diataxis framework principles. **Project Context:** - Type: ${context.projectType} - Languages: ${context.languages.join(", ")} - Frameworks: ${context.frameworks.join(", ")} - Problem to Solve: ${problemToSolve} - User Experience Level: ${userExperience} **Diataxis How-to Guide Requirements:** 1. Problem-oriented: Address specific real-world problems 2. Goal-focused: Clear objective and success criteria 3. Action-oriented: Direct, actionable steps 4. Assume prior knowledge appropriate to user level 5. Practical and immediately applicable **How-to Guide Structure:** 1. Problem statement and context 2. Prerequisites and assumptions 3. Step-by-step solution 4. Verification and testing 5. Troubleshooting common issues 6. Related tasks and variations **Integration Hints:** - Use analyze_codebase for understanding current implementation - Reference best_practices for recommended approaches - Consider validate_solution for testing guidance Please create a how-to guide that solves real problems:`, }, }, ]; } function generateReferenceWriterPrompt( context: ProjectContext, args: Record<string, any>, ): PromptMessage[] { const referenceType = args.reference_type || "API"; const completeness = args.completeness || "comprehensive"; return [ { role: "user", content: { type: "text", text: `Create comprehensive reference documentation for a ${ context.projectType } project following Diataxis framework principles. **Project Context:** - Type: ${context.projectType} - Languages: ${context.languages.join(", ")} - Frameworks: ${context.frameworks.join(", ")} - Reference Type: ${referenceType} - Completeness Level: ${completeness} **Diataxis Reference Requirements:** 1. Information-oriented: Provide complete, accurate information 2. Structured and consistent organization 3. Comprehensive coverage of all features/APIs 4. Neutral tone - describe what is, not how to use 5. Easy to scan and search **Reference Structure:** 1. Overview and organization 2. Complete feature/API listings 3. Parameters, return values, examples 4. Technical specifications 5. Cross-references and relationships 6. Version compatibility information **Integration Hints:** - Use analyze_api_endpoints for API documentation - Reference code_analysis for implementation details - Consider validate_completeness for coverage verification Please create reference documentation that serves as the authoritative source:`, }, }, ]; } function generateExplanationWriterPrompt( context: ProjectContext, args: Record<string, any>, ): PromptMessage[] { const conceptToExplain = args.concept || "system architecture"; const depth = args.depth || "detailed"; return [ { role: "user", content: { type: "text", text: `Create in-depth explanation documentation for a ${ context.projectType } project following Diataxis framework principles. **Project Context:** - Type: ${context.projectType} - Languages: ${context.languages.join(", ")} - Frameworks: ${context.frameworks.join(", ")} - Concept to Explain: ${conceptToExplain} - Depth Level: ${depth} **Diataxis Explanation Requirements:** 1. Understanding-oriented: Help users understand concepts 2. Theoretical and conceptual focus 3. Provide context and background 4. Explain why things work the way they do 5. Connect ideas and show relationships **Explanation Structure:** 1. Introduction and context 2. Core concepts and principles 3. How components relate and interact 4. Design decisions and trade-offs 5. Historical context and evolution 6. Implications and consequences **Integration Hints:** - Use analyze_architecture for system understanding - Reference design_patterns for architectural insights - Consider validate_understanding for comprehension checks Please create explanatory content that builds deep understanding:`, }, }, ]; } function generateDiataxisOrganizerPrompt( context: ProjectContext, args: Record<string, any>, ): PromptMessage[] { const currentDocs = args.current_docs || "mixed documentation"; const priority = args.priority || "user needs"; return [ { role: "user", content: { type: "text", text: `Organize existing documentation for a ${ context.projectType } project using Diataxis framework principles. **Project Context:** - Type: ${context.projectType} - Languages: ${context.languages.join(", ")} - Current Documentation: ${currentDocs} - Organization Priority: ${priority} **Diataxis Organization Requirements:** 1. Categorize content into four types: Tutorials, How-to guides, Reference, Explanation 2. Ensure each piece serves its intended purpose 3. Create clear navigation between content types 4. Identify gaps and overlaps 5. Establish content relationships and cross-references **Organization Structure:** 1. Content audit and classification 2. Diataxis quadrant mapping 3. Navigation and information architecture 4. Content gap analysis 5. Cross-reference strategy 6. Migration and improvement plan **Integration Hints:** - Use analyze_existing_docs for current state assessment - Reference content_classification for categorization - Consider validate_organization for structure verification Please organize documentation according to Diataxis principles:`, }, }, ]; } function generateReadmeOptimizerPrompt( context: ProjectContext, args: Record<string, any>, ): PromptMessage[] { const optimizationFocus = args.optimization_focus || "general"; return [ { role: "user", content: { type: "text", text: `Optimize existing README content for a ${ context.projectType } project using Diataxis-aware principles. **Project Context:** - Type: ${context.projectType} - Languages: ${context.languages.join(", ")} - README Exists: ${context.readmeExists} - Documentation Gaps: ${ context.documentationGaps.join(", ") || "None identified" } - Optimization Focus: ${optimizationFocus} **Diataxis-Aware README Requirements:** 1. Clear content type identification (tutorial, how-to, reference, explanation) 2. Appropriate depth for each content type 3. Logical flow from learning to doing to understanding 4. Clear navigation to detailed documentation 5. Audience-appropriate entry points **README Structure (Diataxis-organized):** 1. Quick start (tutorial-style for beginners) 2. Common tasks (how-to style for users) 3. API/feature overview (reference-style for developers) 4. Architecture overview (explanation-style for understanding) 5. Links to detailed Diataxis-organized documentation **Integration Hints:** - Use analyze_readme for current content analysis - Reference diataxis_principles for content organization - Consider validate_readme_structure for optimization verification Please optimize the README with Diataxis awareness:`, }, }, ]; } // Helper functions async function fileExists(path: string): Promise<boolean> { try { await fs.access(path); return true; } catch { return false; } } async function hasTestFiles(projectPath: string): Promise<boolean> { try { const files = await fs.readdir(projectPath, { recursive: true }); return files.some( (file) => typeof file === "string" && (file.includes("test") || file.includes("spec") || file.endsWith(".test.js") || file.endsWith(".test.ts") || file.endsWith(".spec.js") || file.endsWith(".spec.ts")), ); } catch { return false; } } async function hasCIConfig(projectPath: string): Promise<boolean> { const ciFiles = [ ".github/workflows", ".gitlab-ci.yml", "circle.yml", ".circleci/config.yml", "travis.yml", ".travis.yml", ]; for (const file of ciFiles) { if (await fileExists(join(projectPath, file))) { return true; } } return false; } async function identifyDocumentationGaps( projectPath: string, context: ProjectContext, ): Promise<string[]> { const gaps: string[] = []; if (!context.readmeExists) { gaps.push("readme"); } // Check for common documentation files const docFiles = [ "CONTRIBUTING.md", "CHANGELOG.md", "LICENSE", "docs/api.md", "docs/tutorial.md", "docs/installation.md", ]; for (const docFile of docFiles) { if (!(await fileExists(join(projectPath, docFile)))) { gaps.push(docFile.toLowerCase().replace(".md", "").replace("docs/", "")); } } return gaps; } // Guided workflow prompt generators (ADR-007) function generateAnalyzeAndRecommendPrompt( context: ProjectContext, args: Record<string, any>, ): PromptMessage[] { const analysisDepth = args.analysis_depth || "standard"; const preferences = args.preferences || "balanced approach with good community support"; return [ { role: "user", content: { type: "text", text: `Execute a complete repository analysis and SSG recommendation workflow for this project. **Project Context:** - Type: ${context.projectType} - Languages: ${context.languages.join(", ")} - Frameworks: ${context.frameworks.join(", ")} - Package Manager: ${context.packageManager || "N/A"} - Has Tests: ${context.hasTests} - Has CI: ${context.hasCI} - Documentation Gaps: ${context.documentationGaps.join(", ")} **Workflow Parameters:** - Analysis Depth: ${analysisDepth} - Preferences: ${preferences} **Expected Workflow:** 1. **Repository Analysis**: Analyze project structure, dependencies, and complexity 2. **SSG Recommendation**: Recommend the best static site generator based on project characteristics 3. **Implementation Guidance**: Provide step-by-step setup instructions 4. **Best Practices**: Include security, performance, and maintenance recommendations **Required Output Format:** - Executive summary with key findings - Detailed analysis results with metrics - SSG recommendation with justification - Implementation roadmap with priorities - Resource requirements and timeline estimates Please execute this workflow systematically and provide actionable recommendations.`, }, }, ]; } function generateSetupDocumentationPrompt( context: ProjectContext, args: Record<string, any>, ): PromptMessage[] { const ssgType = args.ssg_type || "recommended based on project analysis"; const includeExamples = args.include_examples !== false; return [ { role: "user", content: { type: "text", text: `Create a comprehensive documentation structure with best practices for this project. **Project Context:** - Type: ${context.projectType} - Languages: ${context.languages.join(", ")} - Frameworks: ${context.frameworks.join(", ")} - Current Documentation Gaps: ${context.documentationGaps.join(", ")} **Setup Parameters:** - SSG Type: ${ssgType} - Include Examples: ${includeExamples} **Documentation Structure Requirements:** 1. **Diataxis Framework Implementation**: - Tutorials: Learning-oriented content - How-to Guides: Problem-solving content - Reference: Information-oriented content - Explanations: Understanding-oriented content 2. **Configuration Setup**: - SSG configuration files - GitHub Pages deployment - Automated workflows - Security best practices 3. **Content Guidelines**: - Writing style guide - Contribution guidelines - Review processes - Maintenance procedures 4. **Development Integration**: - Build pipeline integration - Automated testing for docs - Performance monitoring - Analytics setup **Required Deliverables:** - Complete directory structure - Configuration files with comments - Sample content ${includeExamples ? "with examples" : "templates"} - Deployment automation - Maintenance runbook Please create a production-ready documentation system that scales with the project.`, }, }, ]; } function generateTroubleshootDeploymentPrompt( context: ProjectContext, args: Record<string, any>, ): PromptMessage[] { const repository = args.repository; const deploymentUrl = args.deployment_url || "GitHub Pages URL"; const issueDescription = args.issue_description || "deployment not working as expected"; return [ { role: "user", content: { type: "text", text: `Diagnose and fix GitHub Pages deployment issues for this documentation project. **Repository Information:** - Repository: ${repository} - Expected URL: ${deploymentUrl} - Issue Description: ${issueDescription} **Project Context:** - Type: ${context.projectType} - Languages: ${context.languages.join(", ")} - Has CI: ${context.hasCI} **Troubleshooting Checklist:** 1. **Repository Settings**: - GitHub Pages source configuration - Branch and folder settings - Custom domain setup (if applicable) - Repository visibility and permissions 2. **Build Configuration**: - GitHub Actions workflow validation - Build dependencies and versions - Output directory configuration - Asset and link path issues 3. **Content Issues**: - Markdown syntax validation - Link and image path verification - YAML frontmatter validation - Special character handling 4. **Deployment Workflow**: - Action permissions and secrets - Deployment job configuration - Artifact handling - Cache and dependency issues 5. **Performance and Security**: - Build time optimization - Security policy compliance - CDN and caching configuration - SSL certificate validation **Diagnostic Approach:** 1. **Immediate Assessment**: Check current status and error messages 2. **Systematic Testing**: Validate each component step-by-step 3. **Fix Implementation**: Apply targeted solutions with validation 4. **Prevention Setup**: Implement monitoring and automated checks **Required Output:** - Root cause analysis - Step-by-step fix instructions - Validation procedures - Prevention recommendations - Monitoring setup guide Please provide a comprehensive troubleshooting guide with specific, actionable solutions.`, }, }, ]; }