@polymorphism-tech/morph-spec 3.0.1 → 3.2.0

package/docs/troubleshooting.md

@@ -0,0 +1,269 @@
+# Troubleshooting - CLI Auto Context Detection
+
+Common issues and solutions for MORPH-SPEC auto-detection.
+
+## Claude Code Issues
+
+### Issue: "Claude Code environment not detected"
+
+**Cause**: Auto-detection requires Claude Code CLI to be installed and active.
+
+**Solutions**:
+
+1. **Use wizard mode** (recommended for first-time setup):
+   ```bash
+   morph-spec init --wizard
+   ```
+
+2. **Install Claude Code** and retry:
+   - Download from https://claude.ai/claude-code
+   - Ensure `claude` command is in PATH
+   - Retry `morph-spec init`
+
+3. **Skip auto-detection** and configure manually later:
+   ```bash
+   morph-spec init --skip-detection
+   # Later: morph-spec update --wizard
+   ```
+
+### Issue: "LLM analysis timeout"
+
+**Cause**: Analysis taking longer than 60 seconds (default timeout for interactive mode).
+
+**Solutions**:
+
+1. **Clean project before analysis**:
+   ```bash
+   rm -rf node_modules dist build .next
+   morph-spec init
+   ```
+
+2. **Use wizard mode** (instant):
+   ```bash
+   morph-spec init --wizard
+   ```
+
+3. **Check Claude Code performance**:
+   - Restart Claude Code
+   - Check system resources (CPU, memory)
+
+## LLM Analysis Errors
+
+### Issue: "Schema validation failed"
+
+**Cause**: LLM returned JSON that doesn't match the expected schema.
+
+**Diagnosis**:
+```bash
+# Enable debug mode to see LLM response
+DEBUG=1 morph-spec init
+```
+
+**Solutions**:
+
+1. **Use wizard mode** to provide manual input:
+   ```bash
+   morph-spec init --wizard
+   ```
+
+2. **Report issue** if recurring:
+   - Include project type in issue report
+   - Share anonymized `package.json` or `.csproj` structure
+
+### Issue: "LLM response is not valid JSON"
+
+**Cause**: LLM returned malformed JSON (rare).
+
+**Solutions**:
+
+1. **Retry** - may be a one-time error:
+   ```bash
+   morph-spec init
+   ```
+
+2. **Use wizard mode**:
+   ```bash
+   morph-spec init --wizard
+   ```
+
+## File System Issues
+
+### Issue: "Permission denied" when creating .morph/
+
+**Cause**: Insufficient permissions in project directory.
+
+**Solutions**:
+
+1. **Run with correct permissions**:
+   ```bash
+   sudo morph-spec init  # Unix/Mac
+   # Or run as administrator on Windows
+   ```
+
+2. **Check directory ownership**:
+   ```bash
+   ls -la .  # Should show your user as owner
+   ```
+
+### Issue: Config files getting overwritten
+
+**Cause**: Running `morph-spec update` without reviewing changes.
+
+**Protection**: Auto-detection creates backups:
+- `.morph/project.md.YYYY-MM-DDTHH-MM-SS.backup`
+- `.morph/config/config.json.YYYY-MM-DDTHH-MM-SS.backup`
+
+**Solutions**:
+
+1. **Review diff before approving**:
+   - Auto-detection shows diff when updating
+   - Choose "Edit" to modify before saving
+
+2. **Restore from backup** if needed:
+   ```bash
+   cp .morph/project.md.2026-02-14T10-30-00.backup .morph/project.md
+   ```
+
+3. **Skip auto-detection** during update:
+   ```bash
+   morph-spec update --skip-detection
+   ```
+
+## Detection Accuracy Issues
+
+### Issue: Wrong project type detected
+
+**Example**: Monorepo detected as `nextjs` instead of `monorepo`.
+
+**Solutions**:
+
+1. **Use wizard mode** for accurate manual input:
+   ```bash
+   morph-spec init --wizard
+   ```
+
+2. **Edit config after generation**:
+   - Choose "Edit" during review
+   - Manually correct `type` field in config.json
+
+3. **Report detection issue**:
+   - Helps improve LLM prompt and examples
+
+### Issue: Missing dependencies detected
+
+**Cause**: Auto-detection only reads whitelisted files (package.json, .csproj).
+
+**Solution**:
+
+- This is by design (privacy/security)
+- If critical dependency is missed, manually edit `.morph/project.md`
+
+### Issue: Low confidence score (<70%)
+
+**Cause**: Project structure is unclear or non-standard.
+
+**Solutions**:
+
+1. **Add README.md or CLAUDE.md** with project description
+2. **Use wizard mode** for manual configuration
+3. **Accept low confidence** - configs can be edited later
+
+## Edge Case Handling
+
+### Empty Project (no package.json or .csproj)
+
+**Behavior**: Auto-fallback to wizard mode.
+
+**Solution**: Answer 7 wizard questions to configure manually.
+
+### Monorepo with Multiple Stacks
+
+**Behavior**: Detects all stacks, sets `type: "monorepo"`.
+
+**Example Output**:
+```json
+{
+  "type": "monorepo",
+  "stack": {
+    "frontend": { "tech": "Next.js", "version": "15" },
+    "backend": { "tech": ".NET", "version": "10" }
+  }
+}
+```
+
+### Project with No Database
+
+**Behavior**: `stack.database` set to `null`.
+
+**Warning**: May show "Database technology not detected" in warnings.
+
+### Git Repo Without Remote
+
+**Behavior**: `gitRemote` set to `null`.
+
+**Not an error** - local repos are valid.
+
+## Privacy & Security Concerns
+
+### Question: What data is sent to LLM?
+
+**Answer**: Only sanitized, whitelisted data:
+- package.json (dependencies only, secrets removed)
+- .csproj filenames (not contents)
+- First 500 chars of README.md and CLAUDE.md
+- Directory structure (folder names only)
+- Infrastructure file counts (not contents)
+
+**Never sent**:
+- `.env` files
+- Secrets/passwords/API keys
+- File contents (except whitelisted files)
+- node_modules/
+- Source code
+
+### Question: Is data sent to Anthropic servers?
+
+**Answer**: No. LLM analysis runs locally in Claude Code. No external API calls.
+
+### Question: What if sensitive data is detected?
+
+**Behavior**: Secret redaction removes:
+- API keys (10+ patterns detected)
+- Passwords in connection strings
+- Bearer tokens
+- Private keys (PEM format)
+- GitHub/NPM tokens
+
+**Verification**: Review sanitized context in debug mode:
+```bash
+DEBUG=1 morph-spec init
+```
+
+## Getting Help
+
+### Enable Debug Mode
+
+```bash
+DEBUG=1 morph-spec init
+```
+
+Shows:
+- Full LLM prompts
+- Raw LLM responses
+- Schema validation errors
+- File read operations
+
+### Report Issues
+
+GitHub: https://github.com/polymorphism-tech/morph-spec-framework/issues
+
+Include:
+- MORPH-SPEC version (`morph-spec --version`)
+- Claude Code version
+- Project type (Next.js, Blazor, etc.)
+- Error message (with DEBUG=1 output if possible)
+- Anonymized `package.json` or `.csproj` structure
+
+---
+
+**Need more help?** Check the [CLI Auto Detection Guide](./cli-auto-detection.md).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "3.0.1",
-  "description": "MORPH-SPEC v2.0: AI-First development framework with .NET 10, Microsoft Agent Framework, and Fluent UI Blazor",
+  "version": "3.2.0",
+  "description": "MORPH-SPEC v3: AI-First development framework with validation pipeline, .NET 10, Microsoft Agent Framework, and Fluent UI Blazor",
   "keywords": [
     "claude-code",
     "claude",
@@ -27,7 +27,7 @@
     "bin/",
     "src/",
     "scripts/",
-    "content/",
+    "stacks/",
     "docs/",
     "README.md",
     "LICENSE",
@@ -52,8 +52,12 @@
     "ajv-formats": "^3.0.1",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
+    "diff": "^5.2.0",
     "fs-extra": "^11.2.0",
     "glob": "^10.3.0",
+    "handlebars": "^4.7.8",
+    "inquirer": "^9.2.0",
+    "minimatch": "^9.0.5",
     "ora": "^8.0.0",
     "yaml": "^2.3.4"
   },

package/scripts/postinstall.js

@@ -1,132 +1,132 @@
-#!/usr/bin/env node
-
-/**
- * Postinstall script for @polymorphism-tech/morph-spec
- *
- * Checks if morph-spec is accessible in PATH and warns users
- * if it's not (common issue with nvm-windows).
- */
-
-import { execSync } from 'child_process';
-import { platform } from 'os';
-import chalk from 'chalk';
-
-const isWindows = platform() === 'win32';
-
-/**
- * Check if morph-spec command is in PATH
- */
-function isMorphSpecInPath() {
-  try {
-    const command = isWindows ? 'where morph-spec' : 'which morph-spec';
-    execSync(command, { stdio: 'ignore' });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Detect if nvm-windows is installed
- */
-function isUsingNvmWindows() {
-  if (!isWindows) return false;
-
-  try {
-    const path = process.env.PATH || '';
-    return path.includes('nvm4w') || path.includes('\\nvm\\');
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Get npm global prefix
- */
-function getNpmGlobalPrefix() {
-  try {
-    const prefix = execSync('npm config get prefix', { encoding: 'utf8' }).trim();
-    return prefix;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Show installation success message
- */
-function showSuccessMessage() {
-  console.log('');
-  console.log(chalk.green('✓ @polymorphism-tech/morph-spec installed successfully!'));
-  console.log('');
-  console.log(chalk.cyan('Quick start:'));
-  console.log(chalk.white('  morph-spec init'));
-  console.log(chalk.white('  morph-spec --help'));
-  console.log('');
-}
-
-/**
- * Show PATH warning for nvm-windows users
- */
-function showPathWarning() {
-  console.log('');
-  console.log(chalk.yellow('⚠ Warning: morph-spec command not found in PATH'));
-  console.log('');
-
-  if (isUsingNvmWindows()) {
-    console.log(chalk.white('You are using nvm-windows, which does not automatically add'));
-    console.log(chalk.white('npm global packages to your PATH.'));
-    console.log('');
-    console.log(chalk.cyan('Solution 1: Add npm global directory to PATH'));
-
-    const prefix = getNpmGlobalPrefix();
-    if (prefix) {
-      console.log(chalk.white(`  Add this to your PATH: ${chalk.yellow(prefix)}`));
-      console.log('');
-      console.log(chalk.gray('  PowerShell (as Administrator):'));
-      console.log(chalk.white(`    [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";${prefix}", "User")`));
-      console.log('');
-      console.log(chalk.gray('  Or manually via System Properties > Environment Variables'));
-    }
-
-    console.log('');
-    console.log(chalk.cyan('Solution 2: Use npx (recommended)'));
-    console.log(chalk.white('  npx @polymorphism-tech/morph-spec init'));
-    console.log(chalk.white('  npx @polymorphism-tech/morph-spec --help'));
-  } else {
-    console.log(chalk.white('The morph-spec command was not found in your PATH.'));
-    console.log('');
-    console.log(chalk.cyan('Solution: Use npx instead'));
-    console.log(chalk.white('  npx @polymorphism-tech/morph-spec init'));
-    console.log(chalk.white('  npx @polymorphism-tech/morph-spec --help'));
-  }
-
-  console.log('');
-  console.log(chalk.gray('For more help, see: https://github.com/lucasPolymorphism/morph-spec-framework#troubleshooting'));
-  console.log('');
-}
-
-/**
- * Main postinstall check
- */
-function main() {
-  // Only show messages for global installs
-  // Skip for local installs (when used as dependency)
-  const isGlobalInstall = process.env.npm_config_global === 'true';
-
-  if (!isGlobalInstall) {
-    // Silent exit for local installs
-    return;
-  }
-
-  // Give npm a moment to set up the symlinks
-  setTimeout(() => {
-    if (isMorphSpecInPath()) {
-      showSuccessMessage();
-    } else {
-      showPathWarning();
-    }
-  }, 100);
-}
-
-main();
+#!/usr/bin/env node
+
+/**
+ * Postinstall script for @polymorphism-tech/morph-spec
+ *
+ * Checks if morph-spec is accessible in PATH and warns users
+ * if it's not (common issue with nvm-windows).
+ */
+
+import { execSync } from 'child_process';
+import { platform } from 'os';
+import chalk from 'chalk';
+
+const isWindows = platform() === 'win32';
+
+/**
+ * Check if morph-spec command is in PATH
+ */
+function isMorphSpecInPath() {
+  try {
+    const command = isWindows ? 'where morph-spec' : 'which morph-spec';
+    execSync(command, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detect if nvm-windows is installed
+ */
+function isUsingNvmWindows() {
+  if (!isWindows) return false;
+
+  try {
+    const path = process.env.PATH || '';
+    return path.includes('nvm4w') || path.includes('\\nvm\\');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get npm global prefix
+ */
+function getNpmGlobalPrefix() {
+  try {
+    const prefix = execSync('npm config get prefix', { encoding: 'utf8' }).trim();
+    return prefix;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Show installation success message
+ */
+function showSuccessMessage() {
+  console.log('');
+  console.log(chalk.green('✓ @polymorphism-tech/morph-spec installed successfully!'));
+  console.log('');
+  console.log(chalk.cyan('Quick start:'));
+  console.log(chalk.white('  morph-spec init'));
+  console.log(chalk.white('  morph-spec --help'));
+  console.log('');
+}
+
+/**
+ * Show PATH warning for nvm-windows users
+ */
+function showPathWarning() {
+  console.log('');
+  console.log(chalk.yellow('⚠ Warning: morph-spec command not found in PATH'));
+  console.log('');
+
+  if (isUsingNvmWindows()) {
+    console.log(chalk.white('You are using nvm-windows, which does not automatically add'));
+    console.log(chalk.white('npm global packages to your PATH.'));
+    console.log('');
+    console.log(chalk.cyan('Solution 1: Add npm global directory to PATH'));
+
+    const prefix = getNpmGlobalPrefix();
+    if (prefix) {
+      console.log(chalk.white(`  Add this to your PATH: ${chalk.yellow(prefix)}`));
+      console.log('');
+      console.log(chalk.gray('  PowerShell (as Administrator):'));
+      console.log(chalk.white(`    [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";${prefix}", "User")`));
+      console.log('');
+      console.log(chalk.gray('  Or manually via System Properties > Environment Variables'));
+    }
+
+    console.log('');
+    console.log(chalk.cyan('Solution 2: Use npx (recommended)'));
+    console.log(chalk.white('  npx @polymorphism-tech/morph-spec init'));
+    console.log(chalk.white('  npx @polymorphism-tech/morph-spec --help'));
+  } else {
+    console.log(chalk.white('The morph-spec command was not found in your PATH.'));
+    console.log('');
+    console.log(chalk.cyan('Solution: Use npx instead'));
+    console.log(chalk.white('  npx @polymorphism-tech/morph-spec init'));
+    console.log(chalk.white('  npx @polymorphism-tech/morph-spec --help'));
+  }
+
+  console.log('');
+  console.log(chalk.gray('For more help, see: https://github.com/lucasPolymorphism/morph-spec-framework#troubleshooting'));
+  console.log('');
+}
+
+/**
+ * Main postinstall check
+ */
+function main() {
+  // Only show messages for global installs
+  // Skip for local installs (when used as dependency)
+  const isGlobalInstall = process.env.npm_config_global === 'true';
+
+  if (!isGlobalInstall) {
+    // Silent exit for local installs
+    return;
+  }
+
+  // Give npm a moment to set up the symlinks
+  setTimeout(() => {
+    if (isMorphSpecInPath()) {
+      showSuccessMessage();
+    } else {
+      showPathWarning();
+    }
+  }, 100);
+}
+
+main();

package/scripts/reorganize-skills.cjs

@@ -63,7 +63,7 @@ const skillMapping = {
   'level-4-patterns': []
 };
 
-const baseDir = 'content/.claude/skills';
+const baseDir = 'stacks/blazor-azure/.claude/skills';
 
 // Create new directory structure
 console.log('📁 Creating new 5-level directory structure...\n');

package/scripts/validate-agents-structure.cjs

@@ -1,6 +1,6 @@
 const fs = require('fs');
 
-const agents = JSON.parse(fs.readFileSync('content/.morph/config/agents.json', 'utf8'));
+const agents = JSON.parse(fs.readFileSync('stacks/blazor-azure/.morph/config/agents.json', 'utf8'));
 
 console.log('✅ Version:', agents.version);
 console.log('✅ Total agents:', Object.keys(agents.agents || {}).length);

package/scripts/validate-skills.cjs

@@ -1,8 +1,8 @@
 const fs = require('fs');
 const path = require('path');
 
-const skillsBase = 'content/.claude/skills';
-const agentsPath = 'content/.morph/config/agents.json';
+const skillsBase = 'stacks/blazor-azure/.claude/skills';
+const agentsPath = 'stacks/blazor-azure/.morph/config/agents.json';
 
 console.log('🧪 Validating MORPH 3.0 Skills Structure\n');