@polymorphism-tech/morph-spec 3.0.1 → 3.2.0

package/src/llm/prompt-builder.js

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview Prompt Builder - Builds LLM prompt with few-shot examples
+ * @module morph-spec/llm/prompt-builder
+ */
+
+import { getFewShotExamples } from './few-shot-examples.js';
+
+/**
+ * @typedef {import('../types/index.js').SanitizedContext} SanitizedContext
+ */
+
+/**
+ * Build structured prompt for LLM with few-shot examples
+ * @param {SanitizedContext} context - Sanitized project context
+ * @returns {string} Formatted prompt
+ */
+export function buildPrompt(context) {
+  const examples = getFewShotExamples();
+
+  return `You are a project analysis AI. Analyze the following project context and return a JSON configuration.
+
+## Task
+Analyze the project structure, dependencies, and files to determine:
+- Project name, description, and type
+- Technology stack (frontend, backend, database, hosting)
+- Architecture pattern
+- Project structure description
+- Code conventions
+
+Return ONLY valid JSON matching the schema below. Do not include any explanatory text outside the JSON.
+
+## Few-Shot Examples
+
+${examples.map((ex, i) => `
+### Example ${i + 1}
+
+**Input:**
+\`\`\`json
+${JSON.stringify(ex.input, null, 2)}
+\`\`\`
+
+**Output:**
+\`\`\`json
+${JSON.stringify(ex.output, null, 2)}
+\`\`\`
+`).join('\n')}
+
+## Project Context to Analyze
+
+\`\`\`json
+${JSON.stringify(context, null, 2)}
+\`\`\`
+
+## JSON Schema (Output Format)
+
+\`\`\`json
+{
+  "name": "string (project name)",
+  "description": "string (1-2 sentences)",
+  "type": "monorepo | blazor-server | nextjs | cli-tool | dotnet-api | other",
+  "stack": {
+    "frontend": { "tech": "string", "version": "string", "details": "string" } | null,
+    "backend": { "tech": "string", "version": "string", "details": "string" },
+    "database": { "tech": "string", "version": "string", "details": "string" } | null,
+    "hosting": "string | null"
+  },
+  "architecture": "clean-architecture | monolith | microservices | layered | other",
+  "projectStructure": "string (describe folder structure)",
+  "conventions": "string (coding conventions detected)",
+  "repository": "string | null",
+  "hasAzure": boolean,
+  "hasDocker": boolean,
+  "hasDevOps": boolean,
+  "confidence": number (0-100),
+  "warnings": ["string"] (uncertainties or issues)
+}
+\`\`\`
+
+## Rules
+1. Return ONLY the JSON object, no additional text
+2. Infer missing information from context (package.json, .csproj files, directory structure)
+3. Set \`confidence\` based on how clear the project structure is (90-100 = very clear, 70-89 = moderate, <70 = unclear)
+4. Add \`warnings\` for any uncertainties or missing critical information
+5. If no frontend is detected, set \`stack.frontend\` to null
+6. If no database is detected, set \`stack.database\` to null
+7. Detect project type based on:
+   - \`nextjs\`: package.json has "next" dependency
+   - \`blazor-server\`: .csproj files with Blazor.Server references
+   - \`dotnet-api\`: .csproj files without Blazor
+   - \`cli-tool\`: package.json with bin field or .csproj with OutputType=Exe
+   - \`monorepo\`: multiple top-level directories like frontend/, backend/, packages/
+   - \`other\`: if none of the above match
+
+## Response
+Return the JSON analysis now:`;
+}

package/src/llm/schema-validator.js

@@ -0,0 +1,121 @@
+/**
+ * @fileoverview Schema Validator - Validates LLM JSON responses
+ * @module morph-spec/llm/schema-validator
+ */
+
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+import projectConfigSchema from './project-config-schema.json' with { type: 'json' };
+
+/**
+ * Validation Error with detailed information
+ */
+export class ValidationError extends Error {
+  constructor(message, field, value, errors = []) {
+    super(message);
+    this.name = 'ValidationError';
+    this.field = field;
+    this.value = value;
+    this.errors = errors;
+  }
+}
+
+/**
+ * SchemaValidator - Validates JSON responses against schema
+ * @class
+ */
+export class SchemaValidator {
+  constructor() {
+    this.ajv = new Ajv({
+      allErrors: true,
+      verbose: true,
+      strict: false
+    });
+
+    // Add format validators (uri, email, etc.)
+    addFormats(this.ajv);
+
+    // Compile schema
+    this.validateProjectConfig = this.ajv.compile(projectConfigSchema);
+  }
+
+  /**
+   * Validate ProjectConfig JSON
+   * @param {Object|string} data - JSON object or string
+   * @returns {Object} Validated object
+   * @throws {ValidationError} If validation fails
+   */
+  validate(data) {
+    // Parse if string
+    let parsed = data;
+    if (typeof data === 'string') {
+      try {
+        parsed = JSON.parse(data);
+      } catch (error) {
+        throw new ValidationError(
+          `Invalid JSON: ${error.message}`,
+          'json',
+          data,
+          []
+        );
+      }
+    }
+
+    // Validate against schema
+    const valid = this.validateProjectConfig(parsed);
+
+    if (!valid) {
+      const errors = this.validateProjectConfig.errors || [];
+      const errorMessages = errors
+        .map(err => {
+          const path = err.instancePath || err.dataPath || 'root';
+          const message = err.message || 'unknown error';
+          return `${path}: ${message}`;
+        })
+        .join('; ');
+
+      throw new ValidationError(
+        `Schema validation failed: ${errorMessages}`,
+        'schema',
+        parsed,
+        errors
+      );
+    }
+
+    return parsed;
+  }
+
+  /**
+   * Validate with fallback - returns null instead of throwing
+   * @param {Object|string} data - JSON object or string
+   * @returns {Object|null} Validated object or null if invalid
+   */
+  validateSafe(data) {
+    try {
+      return this.validate(data);
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Get human-readable error messages
+   * @param {Object|string} data - JSON object or string
+   * @returns {string[]} Array of error messages
+   */
+  getErrors(data) {
+    try {
+      this.validate(data);
+      return [];
+    } catch (error) {
+      if (error instanceof ValidationError) {
+        return error.errors.map(err => {
+          const path = err.instancePath || err.dataPath || 'root';
+          const message = err.message || 'unknown error';
+          return `${path}: ${message}`;
+        });
+      }
+      return [error.message];
+    }
+  }
+}

package/src/orchestrator.js

@@ -0,0 +1,206 @@
+/**
+ * @fileoverview AutoContextOrchestrator - Main orchestrator for CLI auto-detection
+ * @module morph-spec/orchestrator
+ */
+
+import chalk from 'chalk';
+import { ProjectScanner } from './scanner/project-scanner.js';
+import { ContextSanitizer } from './sanitizer/context-sanitizer.js';
+import { LLMAnalyzer } from './llm/analyzer.js';
+import { ConfigGenerator } from './generator/config-generator.js';
+import { UserReview } from './ui/user-review.js';
+import { InteractiveWizard } from './ui/interactive-wizard.js';
+import { FileWriter } from './writer/file-writer.js';
+import { readFile, access } from 'fs/promises';
+import { join } from 'path';
+
+/**
+ * @typedef {import('./types/index.js').GeneratedConfigs} GeneratedConfigs
+ */
+
+/**
+ * AutoContextOrchestrator - Orchestrates the complete auto-detection flow
+ * @class
+ */
+export class AutoContextOrchestrator {
+  constructor() {
+    this.scanner = new ProjectScanner();
+    this.sanitizer = new ContextSanitizer();
+    this.llmAnalyzer = new LLMAnalyzer();
+    this.configGenerator = new ConfigGenerator();
+    this.userReview = new UserReview();
+    this.wizard = new InteractiveWizard();
+    this.fileWriter = new FileWriter();
+
+    // Handle Ctrl+C gracefully
+    this.setupSignalHandlers();
+  }
+
+  /**
+   * Execute the complete auto-detection flow
+   * @param {string} cwd - Current working directory
+   * @param {Object} [options] - Orchestration options
+   * @param {boolean} [options.skipReview] - Skip user review (auto-approve)
+   * @param {boolean} [options.fallbackOnError] - Fallback to wizard on LLM error (default: true)
+   * @param {boolean} [options.wizardMode] - Force wizard mode (skip LLM)
+   * @returns {Promise<{success: boolean, configs: GeneratedConfigs|null}>}
+   */
+  async execute(cwd, options = {}) {
+    const {
+      skipReview = false,
+      fallbackOnError = true,
+      wizardMode = false
+    } = options;
+
+    try {
+      console.log(chalk.bold.cyan('\n🔍 MORPH-SPEC Auto Context Detection\n'));
+
+      let projectConfig;
+
+      // Step 1: Decide between LLM or Wizard mode
+      if (wizardMode) {
+        console.log(chalk.yellow('  Using interactive wizard mode (--wizard flag)\n'));
+        projectConfig = await this.wizard.run();
+      } else {
+        try {
+          // Step 1a: Scan project
+          console.log(chalk.dim('  [1/6] Scanning project directory...'));
+          const projectContext = await this.scanner.scan(cwd);
+
+          // Step 1b: Sanitize context
+          console.log(chalk.dim('  [2/6] Sanitizing context (removing secrets)...'));
+          const sanitizedContext = this.sanitizer.sanitize(projectContext);
+
+          // Step 1c: Analyze with LLM
+          console.log(chalk.dim('  [3/6] Analyzing with Claude Code LLM...'));
+          projectConfig = await this.llmAnalyzer.analyze(sanitizedContext);
+
+          console.log(chalk.green('  ✓ Auto-detection successful\n'));
+        } catch (error) {
+          // LLM failed
+          console.log(chalk.yellow(`\n  ⚠️  Auto-detection failed: ${error.message}\n`));
+
+          if (!fallbackOnError) {
+            throw error;
+          }
+
+          // Fallback to wizard
+          console.log(chalk.cyan('  Falling back to interactive wizard...\n'));
+          projectConfig = await this.wizard.run();
+        }
+      }
+
+      // Step 2: Generate configs
+      console.log(chalk.dim('  [4/6] Generating configuration files...'));
+      const configs = await this.configGenerator.generate(projectConfig);
+
+      // Step 3: User review (unless skipped)
+      let finalConfigs = configs;
+
+      if (!skipReview) {
+        console.log(chalk.dim('  [5/6] Requesting user approval...'));
+
+        // Check if updating existing configs
+        const existingConfigs = await this.readExistingConfigs(cwd);
+
+        const approvalResponse = await this.userReview.promptForApproval(
+          configs,
+          projectConfig,
+          existingConfigs
+        );
+
+        if (approvalResponse.action === 'cancel') {
+          console.log(chalk.yellow('\n❌ Operation canceled by user\n'));
+          console.log(chalk.dim(`   Reason: ${approvalResponse.cancelReason || 'User canceled'}\n`));
+          return { success: false, configs: null };
+        }
+
+        if (approvalResponse.editedConfigs) {
+          finalConfigs = approvalResponse.editedConfigs;
+        }
+      } else {
+        console.log(chalk.dim('  [5/6] Skipping user review (auto-approve)'));
+      }
+
+      // Step 4: Save configs
+      console.log(chalk.dim('  [6/6] Saving configuration files...'));
+
+      // Backup existing configs if they exist
+      await this.configGenerator.backupExisting(cwd);
+
+      // Write new configs
+      await this.fileWriter.save(cwd, finalConfigs);
+
+      console.log(chalk.bold.green('🎉 Auto-detection complete!\n'));
+
+      return { success: true, configs: finalConfigs };
+    } catch (error) {
+      console.log(chalk.bold.red('\n❌ Auto-detection failed\n'));
+      console.log(chalk.red(`   Error: ${error.message}\n`));
+
+      if (error.stack && process.env.DEBUG) {
+        console.log(chalk.dim(error.stack));
+      }
+
+      return { success: false, configs: null };
+    }
+  }
+
+  /**
+   * Read existing configs (if they exist)
+   * @param {string} cwd - Current working directory
+   * @returns {Promise<Object|null>} Existing configs or null
+   */
+  async readExistingConfigs(cwd) {
+    try {
+      const projectMdPath = join(cwd, '.morph', 'project.md');
+      const configJsonPath = join(cwd, '.morph', 'config', 'config.json');
+
+      const [projectMdExists, configJsonExists] = await Promise.all([
+        this.fileExists(projectMdPath),
+        this.fileExists(configJsonPath)
+      ]);
+
+      if (!projectMdExists && !configJsonExists) {
+        return null; // No existing configs
+      }
+
+      const [projectMd, configJson] = await Promise.all([
+        projectMdExists ? readFile(projectMdPath, 'utf-8') : null,
+        configJsonExists ? readFile(configJsonPath, 'utf-8') : null
+      ]);
+
+      return { projectMd, configJson };
+    } catch (error) {
+      return null; // Error reading configs, treat as non-existent
+    }
+  }
+
+  /**
+   * Check if file exists
+   * @param {string} filepath - File path
+   * @returns {Promise<boolean>}
+   */
+  async fileExists(filepath) {
+    try {
+      await access(filepath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Setup signal handlers for graceful shutdown
+   */
+  setupSignalHandlers() {
+    const handleExit = () => {
+      console.log(chalk.yellow('\n\n⚠️  Operation interrupted by user (Ctrl+C)\n'));
+      console.log(chalk.dim('   No files were modified\n'));
+      process.exit(0);
+    };
+
+    process.on('SIGINT', handleExit);
+    process.on('SIGTERM', handleExit);
+  }
+}

package/src/sanitizer/context-sanitizer.js

@@ -0,0 +1,221 @@
+/**
+ * @fileoverview ContextSanitizer - Sanitizes project context before sending to LLM
+ * @module morph-spec/sanitizer/context-sanitizer
+ */
+
+import { minimatch } from 'minimatch';
+import {
+  WHITELIST_FILES,
+  BLACKLIST_DIRECTORIES,
+  BLACKLIST_FILES,
+  SECRET_PATTERNS,
+  MAX_FILE_SIZE,
+  MAX_SUMMARY_LENGTH
+} from './patterns.js';
+
+/**
+ * @typedef {import('../types/index.js').ProjectContext} ProjectContext
+ * @typedef {import('../types/index.js').SanitizedContext} SanitizedContext
+ */
+
+/**
+ * ContextSanitizer - Removes secrets and sensitive data before LLM analysis
+ * Implements hybrid whitelist/blacklist approach per ADR-004
+ * @class
+ */
+export class ContextSanitizer {
+  /**
+   * Sanitize project context (remove secrets, truncate files)
+   * @param {ProjectContext} context - Raw project context
+   * @returns {SanitizedContext}
+   */
+  sanitize(context) {
+    // Sanitize package.json (remove private fields, redact secrets)
+    const sanitizedPackageJson = this.sanitizePackageJson(context.packageJson);
+
+    // Extract only filenames from .csproj paths (not full content)
+    const csprojFilenames = context.csprojFiles.map(path => path.split('/').pop());
+
+    // Truncate README and CLAUDE.md to first 500 chars
+    const readmeSummary = context.readme
+      ? this.truncateText(context.readme, MAX_SUMMARY_LENGTH)
+      : null;
+
+    const claudeMdSummary = context.claudeMd
+      ? this.truncateText(context.claudeMd, MAX_SUMMARY_LENGTH)
+      : null;
+
+    // Sanitize infrastructure summary (remove secrets, just count files)
+    const infraSummary = {
+      dockerfilesCount: context.infraFiles.dockerfiles.length,
+      dockerComposeCount: context.infraFiles.dockerComposeFiles.length,
+      bicepFilesCount: context.infraFiles.bicepFiles.length,
+      pipelinesCount: context.infraFiles.pipelines.length,
+      hasAzure: context.infraFiles.hasAzure,
+      hasDocker: context.infraFiles.hasDocker,
+      hasDevOps: context.infraFiles.hasDevOps
+    };
+
+    // Extract git remote domain only (not full URL with credentials)
+    const gitRemoteDomain = context.gitRemote
+      ? this.extractDomain(context.gitRemote)
+      : null;
+
+    // Estimate total files (approximate)
+    const totalFiles = context.structure.topLevelDirs.length * 10; // rough estimate
+
+    return {
+      packageJson: sanitizedPackageJson,
+      csprojFilenames,
+      hasSolution: context.solutionFile !== null,
+      readmeSummary,
+      claudeMdSummary,
+      structure: context.structure,
+      infraSummary,
+      gitRemoteDomain,
+      totalFiles
+    };
+  }
+
+  /**
+   * Sanitize package.json - remove private fields and redact secrets
+   * @param {Object|null} packageJson - Raw package.json
+   * @returns {Object}
+   */
+  sanitizePackageJson(packageJson) {
+    if (!packageJson) {
+      return {};
+    }
+
+    // Keep only safe fields
+    const safe = {
+      name: packageJson.name || 'unknown',
+      version: packageJson.version,
+      description: packageJson.description,
+      type: packageJson.type,
+      engines: packageJson.engines
+    };
+
+    // Include dependencies (names only, no versions for simplicity)
+    if (packageJson.dependencies) {
+      safe.dependencies = Object.keys(packageJson.dependencies);
+    }
+
+    if (packageJson.devDependencies) {
+      safe.devDependencies = Object.keys(packageJson.devDependencies);
+    }
+
+    // Include scripts (but redact any that might contain secrets)
+    if (packageJson.scripts) {
+      safe.scripts = {};
+      for (const [key, value] of Object.entries(packageJson.scripts)) {
+        safe.scripts[key] = this.redactSecrets(value);
+      }
+    }
+
+    return safe;
+  }
+
+  /**
+   * Detect and redact secrets from text
+   * @param {string} text - Text to sanitize
+   * @returns {string} Sanitized text
+   */
+  redactSecrets(text) {
+    if (!text || typeof text !== 'string') {
+      return text;
+    }
+
+    let sanitized = text;
+
+    // Apply all secret patterns
+    for (const pattern of SECRET_PATTERNS) {
+      sanitized = sanitized.replace(pattern.regex, pattern.replacement);
+    }
+
+    return sanitized;
+  }
+
+  /**
+   * Check if file should be excluded from LLM analysis
+   * @param {string} filepath - File path (relative or absolute)
+   * @returns {boolean} True if file should be excluded
+   */
+  shouldExcludeFile(filepath) {
+    const normalizedPath = filepath.replace(/\\/g, '/');
+
+    // Check if path contains blacklisted directory
+    for (const blacklistDir of BLACKLIST_DIRECTORIES) {
+      if (normalizedPath.includes(`/${blacklistDir}/`) || normalizedPath.startsWith(`${blacklistDir}/`)) {
+        return true;
+      }
+    }
+
+    // Check if filename matches blacklist pattern
+    const filename = normalizedPath.split('/').pop();
+    for (const pattern of BLACKLIST_FILES) {
+      if (minimatch(filename, pattern, { nocase: true })) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Check if file is whitelisted for reading
+   * @param {string} filepath - File path
+   * @returns {boolean} True if file is whitelisted
+   */
+  isWhitelisted(filepath) {
+    const normalizedPath = filepath.replace(/\\/g, '/');
+    const filename = normalizedPath.split('/').pop();
+
+    for (const pattern of WHITELIST_FILES) {
+      if (minimatch(filename, pattern, { nocase: true })) {
+        return true;
+      }
+      // Also check full path for patterns like ".github/workflows/*.yml"
+      if (minimatch(normalizedPath, pattern, { nocase: true })) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Truncate text to maximum length
+   * @param {string} text - Text to truncate
+   * @param {number} maxLength - Maximum length
+   * @returns {string} Truncated text
+   */
+  truncateText(text, maxLength) {
+    if (!text || text.length <= maxLength) {
+      return text;
+    }
+
+    return text.substring(0, maxLength) + '... [truncated]';
+  }
+
+  /**
+   * Extract domain from git remote URL
+   * @param {string} url - Git remote URL
+   * @returns {string|null} Domain only (e.g., "github.com")
+   */
+  extractDomain(url) {
+    try {
+      // Handle SSH format: git@github.com:user/repo.git
+      if (url.startsWith('git@')) {
+        const match = url.match(/git@([^:]+):/);
+        return match ? match[1] : null;
+      }
+
+      // Handle HTTPS format: https://github.com/user/repo.git
+      const urlObj = new URL(url);
+      return urlObj.hostname;
+    } catch (error) {
+      return null;
+    }
+  }
+}