@polymorphism-tech/morph-spec 3.1.0 → 4.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/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;
+    }
+  }
+}

package/src/sanitizer/patterns.js

@@ -0,0 +1,163 @@
+/**
+ * @fileoverview Sanitization patterns - Whitelists, Blacklists, Secret patterns
+ * @module morph-spec/sanitizer/patterns
+ */
+
+/**
+ * Whitelist: Files explicitly allowed to be read and sent to LLM
+ */
+export const WHITELIST_FILES = [
+  'package.json',
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  '*.csproj',
+  '*.sln',
+  'README.md',
+  'CLAUDE.md',
+  'Dockerfile',
+  'docker-compose.yml',
+  'docker-compose.*.yml',
+  '*.bicep',
+  'azure-pipelines.yml',
+  '.github/workflows/*.yml',
+  '.gitlab-ci.yml',
+  'tsconfig.json',
+  'jsconfig.json',
+  '.eslintrc*',
+  '.prettierrc*',
+  'vite.config.*',
+  'next.config.*',
+  'nuxt.config.*'
+];
+
+/**
+ * Blacklist: Directories to NEVER scan or read
+ */
+export const BLACKLIST_DIRECTORIES = [
+  'node_modules',
+  '.git',
+  '.svn',
+  '.hg',
+  'bin',
+  'obj',
+  'dist',
+  'build',
+  'out',
+  '.next',
+  '.nuxt',
+  'coverage',
+  '__pycache__',
+  '.pytest_cache',
+  'venv',
+  'env',
+  '.venv',
+  '.env.*',
+  'temp',
+  'tmp',
+  '.cache'
+];
+
+/**
+ * Blacklist: File patterns to NEVER read (even if matched by whitelist)
+ */
+export const BLACKLIST_FILES = [
+  '.env',
+  '.env.local',
+  '.env.*.local',
+  '.env.production',
+  '*.key',
+  '*.pem',
+  '*.pfx',
+  '*.p12',
+  '*.cert',
+  '*.crt',
+  '*secret*',
+  '*password*',
+  '*credentials*',
+  '*token*',
+  'secrets.json',
+  'appsettings.Production.json',
+  'appsettings.Staging.json',
+  '*.log',
+  '*.sqlite',
+  '*.db'
+];
+
+/**
+ * Secret patterns to redact from file contents
+ * Each pattern has: regex, replacement text, description
+ */
+export const SECRET_PATTERNS = [
+  {
+    name: 'api-key',
+    regex: /(?:api[_-]?key|apikey|api[_-]?secret)[\s:=]+["']?([a-zA-Z0-9_\-]{20,})["']?/gi,
+    replacement: 'API_KEY=***REDACTED***',
+    description: 'API keys'
+  },
+  {
+    name: 'bearer-token',
+    regex: /(?:bearer|authorization)[\s:=]+["']?([a-zA-Z0-9_\-\.]{20,})["']?/gi,
+    replacement: 'Bearer ***REDACTED***',
+    description: 'Bearer tokens'
+  },
+  {
+    name: 'connection-string',
+    regex: /(?:connection[_-]?string|connectionstring)[\s:=]+["']?([^"'\n]{30,})["']?/gi,
+    replacement: 'ConnectionString=***REDACTED***',
+    description: 'Connection strings'
+  },
+  {
+    name: 'sql-password',
+    regex: /(?:password|pwd)=([^;"\s]{6,})/gi,
+    replacement: 'Password=***REDACTED***',
+    description: 'SQL passwords in connection strings'
+  },
+  {
+    name: 'azure-key',
+    regex: /(?:account[_-]?key|accountkey)[\s:=]+["']?([a-zA-Z0-9+/=]{40,})["']?/gi,
+    replacement: 'AccountKey=***REDACTED***',
+    description: 'Azure Storage Account Keys'
+  },
+  {
+    name: 'jwt-secret',
+    regex: /(?:jwt[_-]?secret|jwtsecret)[\s:=]+["']?([a-zA-Z0-9_\-]{16,})["']?/gi,
+    replacement: 'JwtSecret=***REDACTED***',
+    description: 'JWT secrets'
+  },
+  {
+    name: 'private-key',
+    regex: /-----BEGIN (?:RSA |EC )?PRIVATE KEY-----[\s\S]+?-----END (?:RSA |EC )?PRIVATE KEY-----/gi,
+    replacement: '-----BEGIN PRIVATE KEY-----\n***REDACTED***\n-----END PRIVATE KEY-----',
+    description: 'Private keys (PEM format)'
+  },
+  {
+    name: 'github-token',
+    regex: /gh[pousr]_[a-zA-Z0-9]{36,}/gi,
+    replacement: 'ghp_***REDACTED***',
+    description: 'GitHub personal access tokens'
+  },
+  {
+    name: 'npm-token',
+    regex: /npm_[a-zA-Z0-9]{36,}/gi,
+    replacement: 'npm_***REDACTED***',
+    description: 'NPM tokens'
+  },
+  {
+    name: 'generic-secret',
+    regex: /(?:secret|password|pwd|pass|token)[\s:=]+["']([^"'\n]{8,})["']/gi,
+    replacement: 'secret=***REDACTED***',
+    description: 'Generic secrets'
+  }
+];
+
+/**
+ * Maximum file size to include (50KB)
+ * Files larger than this are truncated with a summary
+ */
+export const MAX_FILE_SIZE = 50 * 1024; // 50KB
+
+/**
+ * Maximum content length for README/CLAUDE.md summaries
+ */
+export const MAX_SUMMARY_LENGTH = 500; // 500 chars