@polymorphism-tech/morph-spec 3.0.1 → 3.2.0

package/src/types/index.js

@@ -0,0 +1,477 @@
+/**
+ * @fileoverview Type definitions and contracts for CLI Auto Context Detection
+ * @module morph-spec/cli-auto-context-detection
+ *
+ * This file defines the interfaces and types used throughout the CLI Auto Context Detection feature.
+ * Since MORPH-SPEC uses JavaScript (ESM), we use JSDoc for type annotations instead of TypeScript.
+ */
+
+// ============================================================================
+// PROJECT CONTEXT (Scanner Output)
+// ============================================================================
+
+/**
+ * Parsed package.json content
+ * @typedef {Object} PackageJson
+ * @property {string} name - Package name
+ * @property {string} [version] - Package version
+ * @property {string} [description] - Package description
+ * @property {Object.<string, string>} [dependencies] - Production dependencies
+ * @property {Object.<string, string>} [devDependencies] - Development dependencies
+ * @property {Object.<string, string>} [scripts] - NPM scripts
+ * @property {string} [type] - Module type (commonjs | module)
+ * @property {Object} [engines] - Node.js engine requirements
+ */
+
+/**
+ * Directory structure analysis
+ * @typedef {Object} DirectoryStructure
+ * @property {boolean} hasSrc - Has src/ directory
+ * @property {boolean} hasBackend - Has backend/ or server/ directory
+ * @property {boolean} hasFrontend - Has frontend/ or client/ directory
+ * @property {boolean} hasTests - Has test/ or tests/ directory
+ * @property {string[]} topLevelDirs - List of top-level directories
+ * @property {string} pattern - Detected pattern (monorepo | single-project | multi-stack)
+ */
+
+/**
+ * Infrastructure files detected
+ * @typedef {Object} InfraFiles
+ * @property {string[]} dockerfiles - Paths to Dockerfiles
+ * @property {string[]} dockerComposeFiles - Paths to docker-compose.yml files
+ * @property {string[]} bicepFiles - Paths to *.bicep files
+ * @property {string[]} pipelines - Paths to CI/CD pipeline configs
+ * @property {boolean} hasAzure - Has Azure-related files
+ * @property {boolean} hasDocker - Has Docker-related files
+ * @property {boolean} hasDevOps - Has CI/CD configs
+ */
+
+/**
+ * Complete project context collected by scanner
+ * @typedef {Object} ProjectContext
+ * @property {string} cwd - Current working directory (absolute path)
+ * @property {PackageJson|null} packageJson - Parsed package.json (if exists)
+ * @property {string[]} csprojFiles - Paths to *.csproj files
+ * @property {string|null} solutionFile - Path to *.sln file (if exists)
+ * @property {string|null} readme - Content of README.md (if exists)
+ * @property {string|null} claudeMd - Content of CLAUDE.md (if exists)
+ * @property {DirectoryStructure} structure - Detected directory structure
+ * @property {InfraFiles} infraFiles - Detected infrastructure files
+ * @property {string|null} gitRemote - Git remote URL (if in git repo)
+ * @property {Date} scannedAt - Timestamp when scan was performed
+ */
+
+// ============================================================================
+// PROJECT CONFIG (LLM Output)
+// ============================================================================
+
+/**
+ * Technology specification
+ * @typedef {Object} TechSpec
+ * @property {string} tech - Technology name (e.g., "Next.js", ".NET", "PostgreSQL")
+ * @property {string} version - Version (e.g., "15", "10", "16")
+ * @property {string} [details] - Additional details (e.g., "Server Components", "Minimal API")
+ */
+
+/**
+ * Technology stack information
+ * @typedef {Object} StackInfo
+ * @property {TechSpec|null} frontend - Frontend technology (null if backend-only)
+ * @property {TechSpec} backend - Backend technology
+ * @property {TechSpec|null} database - Database technology (null if no persistence)
+ * @property {string|null} hosting - Hosting platform (e.g., "Azure", "Vercel", "Docker")
+ */
+
+/**
+ * Complete project configuration detected by LLM
+ * @typedef {Object} ProjectConfig
+ * @property {string} name - Project name (from package.json or repo)
+ * @property {string} description - Project description (1-2 sentences)
+ * @property {string} type - Project type (monorepo | blazor-server | nextjs | cli-tool | dotnet-api | other)
+ * @property {StackInfo} stack - Technology stack
+ * @property {string} architecture - Architecture pattern (clean-architecture | monolith | microservices | layered | other)
+ * @property {string} projectStructure - Description of folder structure
+ * @property {string} conventions - Detected code conventions (e.g., "ESM modules", "PascalCase for classes")
+ * @property {string|null} repository - Git repository URL
+ * @property {boolean} hasAzure - Uses Azure infrastructure
+ * @property {boolean} hasDocker - Uses Docker containerization
+ * @property {boolean} hasDevOps - Uses CI/CD pipelines
+ * @property {number} confidence - LLM confidence score (0-100)
+ * @property {string[]} warnings - Warnings or uncertainties detected
+ */
+
+// ============================================================================
+// SANITIZED CONTEXT (Input to LLM)
+// ============================================================================
+
+/**
+ * Sanitized project context (safe to send to LLM)
+ * @typedef {Object} SanitizedContext
+ * @property {Object} packageJson - Sanitized package.json (secrets removed)
+ * @property {string[]} csprojFilenames - Filenames only (not full content)
+ * @property {boolean} hasSolution - Whether *.sln exists (no content)
+ * @property {string|null} readmeSummary - First 500 chars of README.md
+ * @property {string|null} claudeMdSummary - First 500 chars of CLAUDE.md
+ * @property {DirectoryStructure} structure - Directory structure (safe)
+ * @property {Object} infraSummary - Infrastructure summary (no secrets)
+ * @property {string|null} gitRemoteDomain - Git remote domain only (e.g., "github.com")
+ * @property {number} totalFiles - Total file count (for context)
+ */
+
+// ============================================================================
+// GENERATED CONFIGS
+// ============================================================================
+
+/**
+ * Generated configuration files
+ * @typedef {Object} GeneratedConfigs
+ * @property {string} projectMd - Rendered project.md content
+ * @property {string} configJson - Rendered config.json content (as string)
+ * @property {Object} configObject - Parsed config.json (as object)
+ */
+
+// ============================================================================
+// USER REVIEW
+// ============================================================================
+
+/**
+ * User approval response
+ * @typedef {Object} ApprovalResponse
+ * @property {'approve'|'edit'|'cancel'} action - User action
+ * @property {GeneratedConfigs} [editedConfigs] - Edited configs (if action === 'edit')
+ * @property {string} [cancelReason] - Reason for cancellation (if action === 'cancel')
+ */
+
+// ============================================================================
+// ERRORS
+// ============================================================================
+
+/**
+ * LLM Analysis Error
+ * @typedef {Error} LLMAnalysisError
+ * @property {string} name - "LLMAnalysisError"
+ * @property {string} message - Error message
+ * @property {number} statusCode - HTTP status code (if API error)
+ * @property {number} attempts - Number of retry attempts made
+ * @property {Error} [originalError] - Original error from API
+ */
+
+/**
+ * Validation Error
+ * @typedef {Error} ValidationError
+ * @property {string} name - "ValidationError"
+ * @property {string} message - Error message
+ * @property {string} field - Field that failed validation
+ * @property {any} value - Invalid value
+ * @property {Object} [schema] - JSON schema that was violated
+ */
+
+// ============================================================================
+// SERVICE INTERFACES
+// ============================================================================
+
+/**
+ * Project Scanner Interface
+ * @interface IProjectScanner
+ */
+export class IProjectScanner {
+  /**
+   * Scan the project directory and collect context
+   * @param {string} cwd - Current working directory
+   * @returns {Promise<ProjectContext>}
+   */
+  async scan(cwd) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Read and parse package.json
+   * @param {string} cwd - Current working directory
+   * @returns {Promise<PackageJson|null>}
+   */
+  async readPackageJson(cwd) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Find all .csproj files recursively
+   * @param {string} cwd - Current working directory
+   * @returns {Promise<string[]>}
+   */
+  async findCsprojFiles(cwd) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Detect directory structure
+   * @param {string} cwd - Current working directory
+   * @returns {Promise<DirectoryStructure>}
+   */
+  async detectDirectoryStructure(cwd) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Find infrastructure files (Docker, Bicep, pipelines)
+   * @param {string} cwd - Current working directory
+   * @returns {Promise<InfraFiles>}
+   */
+  async findInfraFiles(cwd) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Get git remote URL
+   * @param {string} cwd - Current working directory
+   * @returns {Promise<string|null>}
+   */
+  async getGitRemote(cwd) {
+    throw new Error('Not implemented');
+  }
+}
+
+/**
+ * Context Sanitizer Interface
+ * @interface IContextSanitizer
+ */
+export class IContextSanitizer {
+  /**
+   * Sanitize project context (remove secrets, truncate files)
+   * @param {ProjectContext} context - Raw project context
+   * @returns {SanitizedContext}
+   */
+  sanitize(context) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Detect and redact secrets from text
+   * @param {string} text - Text to sanitize
+   * @returns {string} Sanitized text
+   */
+  redactSecrets(text) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Check if file should be excluded from LLM analysis
+   * @param {string} filepath - File path
+   * @returns {boolean} True if file should be excluded
+   */
+  shouldExcludeFile(filepath) {
+    throw new Error('Not implemented');
+  }
+}
+
+/**
+ * LLM Analyzer Interface
+ * @interface ILLMAnalyzer
+ */
+export class ILLMAnalyzer {
+  /**
+   * Analyze project context using Claude Code's LLM
+   * @param {SanitizedContext} context - Sanitized project context
+   * @param {Object} [options] - Analysis options
+   * @param {number} [options.timeout] - Timeout in ms (default: 30000)
+   * @returns {Promise<ProjectConfig>}
+   * @throws {LLMAnalysisError} If analysis fails
+   */
+  async analyze(context, options) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Build structured prompt for LLM
+   * @param {SanitizedContext} context - Sanitized context
+   * @returns {string} Prompt text
+   */
+  buildPrompt(context) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Invoke Claude Code's LLM (via Task tool or internal API)
+   * @param {string} prompt - Prompt text
+   * @param {Object} options - Invocation options
+   * @returns {Promise<string>} JSON response from LLM
+   * @throws {LLMAnalysisError}
+   */
+  async invokeLLM(prompt, options) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Parse and validate LLM JSON response
+   * @param {string} response - Raw LLM response
+   * @returns {ProjectConfig}
+   * @throws {ValidationError} If response doesn't match schema
+   */
+  parseJsonResponse(response) {
+    throw new Error('Not implemented');
+  }
+}
+
+/**
+ * Config Generator Interface
+ * @interface IConfigGenerator
+ */
+export class IConfigGenerator {
+  /**
+   * Generate configuration files from project config
+   * @param {ProjectConfig} projectConfig - Detected project config
+   * @returns {Promise<GeneratedConfigs>}
+   */
+  async generate(projectConfig) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Render project.md template
+   * @param {ProjectConfig} config - Project config
+   * @returns {string} Rendered markdown
+   */
+  renderProjectMd(config) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Render config.json template
+   * @param {ProjectConfig} config - Project config
+   * @returns {string} Rendered JSON string
+   */
+  renderConfigJson(config) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Validate config.json against schema
+   * @param {string} configJson - JSON string
+   * @returns {boolean} True if valid
+   * @throws {ValidationError} If validation fails
+   */
+  validateConfigJson(configJson) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Backup existing configuration files
+   * @param {string} cwd - Current working directory
+   * @returns {Promise<void>}
+   */
+  async backupExisting(cwd) {
+    throw new Error('Not implemented');
+  }
+}
+
+/**
+ * User Review Interface
+ * @interface IUserReview
+ */
+export class IUserReview {
+  /**
+   * Prompt user for approval of generated configs
+   * @param {GeneratedConfigs} configs - Generated configs
+   * @param {ProjectConfig} projectConfig - Detected project config
+   * @returns {Promise<ApprovalResponse>}
+   */
+  async promptForApproval(configs, projectConfig) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Display diff between current and generated configs
+   * @param {string} current - Current config content
+   * @param {string} generated - Generated config content
+   * @returns {void}
+   */
+  displayDiff(current, generated) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Open configs in editor for manual editing
+   * @param {GeneratedConfigs} configs - Configs to edit
+   * @returns {Promise<GeneratedConfigs>} Edited configs
+   */
+  async openInEditor(configs) {
+    throw new Error('Not implemented');
+  }
+}
+
+/**
+ * File Writer Interface
+ * @interface IFileWriter
+ */
+export class IFileWriter {
+  /**
+   * Save generated configs to filesystem
+   * @param {string} cwd - Current working directory
+   * @param {GeneratedConfigs} configs - Configs to save
+   * @returns {Promise<void>}
+   */
+  async save(cwd, configs) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Write project.md file
+   * @param {string} filepath - File path
+   * @param {string} content - File content
+   * @returns {Promise<void>}
+   */
+  async writeProjectMd(filepath, content) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Write config.json file
+   * @param {string} filepath - File path
+   * @param {string} content - File content (JSON string)
+   * @returns {Promise<void>}
+   */
+  async writeConfigJson(filepath, content) {
+    throw new Error('Not implemented');
+  }
+}
+
+// ============================================================================
+// ORCHESTRATOR (Main Flow)
+// ============================================================================
+
+/**
+ * CLI Auto Context Detection Orchestrator
+ * @interface IAutoContextOrchestrator
+ */
+export class IAutoContextOrchestrator {
+  /**
+   * 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
+   * @returns {Promise<{success: boolean, configs: GeneratedConfigs|null}>}
+   */
+  async execute(cwd, options) {
+    throw new Error('Not implemented');
+  }
+}
+
+// ============================================================================
+// EXPORTS
+// ============================================================================
+
+export {
+  // Types
+  PackageJson,
+  DirectoryStructure,
+  InfraFiles,
+  ProjectContext,
+  TechSpec,
+  StackInfo,
+  ProjectConfig,
+  SanitizedContext,
+  GeneratedConfigs,
+  ApprovalResponse,
+  LLMAnalysisError,
+  ValidationError,
+};

package/src/ui/diff-display.js

@@ -0,0 +1,91 @@
+/**
+ * @fileoverview Diff Display - Shows diff between current and generated configs
+ * @module morph-spec/ui/diff-display
+ */
+
+import { diffLines } from 'diff';
+import chalk from 'chalk';
+
+/**
+ * Display diff between two text strings
+ * @param {string} oldContent - Original content
+ * @param {string} newContent - New content
+ * @param {string} filename - Filename for display
+ */
+export function displayDiff(oldContent, newContent, filename) {
+  console.log(chalk.bold(`\n📝 Changes in ${filename}:\n`));
+
+  const diff = diffLines(oldContent, newContent);
+
+  diff.forEach(part => {
+    const color = part.added ? chalk.green : part.removed ? chalk.red : chalk.gray;
+    const prefix = part.added ? '+ ' : part.removed ? '- ' : '  ';
+
+    part.value.split('\n').forEach((line, index) => {
+      if (line || index < part.value.split('\n').length - 1) {
+        console.log(color(prefix + line));
+      }
+    });
+  });
+
+  console.log(); // Empty line after diff
+}
+
+/**
+ * Display side-by-side summary of changes
+ * @param {Object} oldConfig - Old config object
+ * @param {Object} newConfig - New config object
+ */
+export function displayConfigSummary(oldConfig, newConfig) {
+  console.log(chalk.bold('\n📊 Configuration Summary:\n'));
+
+  const fields = [
+    { key: 'name', label: 'Project Name' },
+    { key: 'type', label: 'Project Type' },
+    { key: 'description', label: 'Description' },
+    { key: 'stack.backend.tech', label: 'Backend' },
+    { key: 'stack.frontend.tech', label: 'Frontend' },
+    { key: 'stack.database.tech', label: 'Database' },
+    { key: 'architecture', label: 'Architecture' }
+  ];
+
+  fields.forEach(({ key, label }) => {
+    const oldValue = getNestedValue(oldConfig, key) || chalk.gray('(not set)');
+    const newValue = getNestedValue(newConfig, key) || chalk.gray('(not set)');
+
+    const changed = oldValue !== newValue;
+    const color = changed ? chalk.yellow : chalk.white;
+
+    console.log(
+      color(`  ${label.padEnd(20)}: `) +
+      chalk.dim(String(oldValue).padEnd(30)) +
+      chalk.bold(' → ') +
+      color(newValue)
+    );
+  });
+
+  console.log();
+}
+
+/**
+ * Get nested value from object by dot notation key
+ * @param {Object} obj - Object to query
+ * @param {string} key - Dot notation key (e.g., 'stack.backend.tech')
+ * @returns {any} Value or null
+ */
+function getNestedValue(obj, key) {
+  if (!obj) return null;
+
+  const keys = key.split('.');
+  let current = obj;
+
+  for (const k of keys) {
+    if (current && typeof current === 'object' && k in current) {
+      current = current[k];
+    } else {
+      return null;
+    }
+  }
+
+  return current;
+}

package/src/ui/interactive-wizard.js

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview Interactive Wizard - Manual configuration when LLM fails
+ * @module morph-spec/ui/interactive-wizard
+ */
+
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import { getWizardQuestions, mapAnswersToConfig } from './wizard-questions.js';
+
+/**
+ * @typedef {import('../types/index.js').ProjectConfig} ProjectConfig
+ */
+
+/**
+ * InteractiveWizard - Guides user through manual project configuration
+ * @class
+ */
+export class InteractiveWizard {
+  /**
+   * Run interactive wizard to collect project configuration
+   * @returns {Promise<ProjectConfig>}
+   */
+  async run() {
+    console.log(chalk.bold.cyan('\n🧙 Interactive Project Configuration Wizard\n'));
+    console.log(chalk.dim('  Answer 7 questions to configure your project\n'));
+
+    const questions = getWizardQuestions();
+    const answers = await inquirer.prompt(questions);
+
+    // Map answers to ProjectConfig
+    const config = mapAnswersToConfig(answers);
+
+    // Show summary
+    this.displaySummary(config);
+
+    // Confirm before proceeding
+    const { confirmed } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'confirmed',
+        message: 'Is this configuration correct?',
+        default: true
+      }
+    ]);
+
+    if (!confirmed) {
+      console.log(chalk.yellow('\n❌ Configuration canceled. Please run the wizard again.\n'));
+      process.exit(0);
+    }
+
+    return config;
+  }
+
+  /**
+   * Display summary of collected configuration
+   * @param {ProjectConfig} config - Project configuration
+   */
+  displaySummary(config) {
+    console.log(chalk.bold.green('\n✅ Configuration Summary:\n'));
+
+    console.log(chalk.bold('  Name:        ') + chalk.cyan(config.name));
+    console.log(chalk.bold('  Type:        ') + chalk.yellow(config.type));
+    console.log(chalk.bold('  Description: ') + chalk.white(config.description));
+    console.log();
+
+    console.log(chalk.bold('  Stack:'));
+    if (config.stack.frontend) {
+      console.log(chalk.gray('    Frontend:  ') + chalk.white(`${config.stack.frontend.tech} ${config.stack.frontend.version}`));
+    } else {
+      console.log(chalk.gray('    Frontend:  ') + chalk.dim('None (backend-only)'));
+    }
+    console.log(chalk.gray('    Backend:   ') + chalk.white(`${config.stack.backend.tech} ${config.stack.backend.version}`));
+    if (config.stack.database) {
+      console.log(chalk.gray('    Database:  ') + chalk.white(`${config.stack.database.tech} ${config.stack.database.version}`));
+    } else {
+      console.log(chalk.gray('    Database:  ') + chalk.dim('None'));
+    }
+    if (config.stack.hosting) {
+      console.log(chalk.gray('    Hosting:   ') + chalk.white(config.stack.hosting));
+    }
+    console.log();
+
+    console.log(chalk.bold('  Architecture: ') + chalk.magenta(config.architecture));
+    console.log();
+
+    // Infrastructure flags
+    const flags = [];
+    if (config.hasAzure) flags.push(chalk.blue('Azure'));
+    if (config.hasDocker) flags.push(chalk.cyan('Docker'));
+
+    if (flags.length > 0) {
+      console.log(chalk.bold('  Infrastructure: ') + flags.join(' • '));
+      console.log();
+    }
+  }
+}