@polymorphism-tech/morph-spec 2.1.0 → 2.1.2

package/README.md

@@ -67,24 +67,48 @@ morph-spec init
 ```
 
 <details>
-<summary><strong>Windows: Comando não reconhecido?</strong></summary>
+<summary><strong>⚠️ Windows + nvm-windows: Comando não reconhecido?</strong></summary>
 
-Se após instalar globalmente o comando `morph-spec` não for reconhecido, adicione o npm ao PATH:
+Se você usa **nvm-windows** para gerenciar versões do Node.js, o npm **não** adiciona automaticamente os pacotes globais ao PATH. Este é um [problema conhecido do nvm-windows](https://github.com/coreybutler/nvm-windows/issues/391).
+
+### Solução 1: Adicionar ao PATH manualmente
 
 **PowerShell (executar como Administrador):**
 ```powershell
-# Adicionar npm global ao PATH permanentemente
+# Verificar o caminho do npm global
+npm config get prefix
+
+# Adicionar ao PATH (substitua pelo caminho acima)
 $npmPath = "$env:APPDATA\npm"
-[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$npmPath", "User")
+[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$npmPath", "User")
 ```
 
 Depois, **feche e reabra o terminal**.
 
-**Alternativa:** Use `npx` que funciona sem configurar PATH:
+### Solução 2: Use npx (Recomendado)
+
+O `npx` funciona sem configurar PATH:
 ```bash
 npx @polymorphism-tech/morph-spec init
+npx @polymorphism-tech/morph-spec doctor
+```
+
+### Verificar se funcionou
+
+```bash
+morph-spec --version
+# Ou
+npx @polymorphism-tech/morph-spec --version
+```
+
+### Mais Ajuda
+
+```bash
+morph-spec doctor  # Detecta problemas de PATH automaticamente
 ```
 
+Veja também: [Troubleshooting](#troubleshooting)
+
 </details>
 
 ### Comandos CLI
@@ -342,6 +366,111 @@ O MORPH segue a filosofia **"Free tier first"**:
 
 ---
 
+## 🔧 Troubleshooting
+
+### Comando `morph-spec` não encontrado
+
+**Sintoma:** Após `npm install -g`, o comando não é reconhecido.
+
+**Diagnóstico:**
+```bash
+npm config get prefix  # Ver onde npm instala globalmente
+echo $PATH             # Linux/Mac: Verificar se está no PATH
+$env:Path              # Windows: Verificar se está no PATH
+```
+
+**Causa comum:** Você está usando **nvm** ou **nvm-windows**, que não adiciona automaticamente npm global ao PATH.
+
+**Solução 1 - Usar npx (Recomendado):**
+```bash
+npx @polymorphism-tech/morph-spec init
+```
+
+**Solução 2 - Adicionar ao PATH:**
+
+**Linux/Mac:**
+```bash
+# Adicionar ao ~/.bashrc ou ~/.zshrc
+export PATH="$HOME/.npm-global/bin:$PATH"
+```
+
+**Windows (PowerShell como Admin):**
+```powershell
+$npmPath = "$env:APPDATA\npm"
+[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$npmPath", "User")
+```
+
+**Verificar correção:**
+```bash
+morph-spec --version
+```
+
+---
+
+### `morph-spec doctor` reporta problemas
+
+**O que o doctor verifica:**
+- ✓ Versão do CLI (atualizada?)
+- ✓ Versão do MORPH no projeto
+- ✓ Comando morph-spec no PATH
+- ✓ Estrutura de arquivos (.morph/, CLAUDE.md, etc.)
+
+**Se reportar "morph-spec not in PATH":**
+1. Use `npx` como alternativa (sempre funciona)
+2. Ou siga as instruções acima para adicionar ao PATH
+
+**Se reportar arquivos faltando:**
+```bash
+morph-spec init --force  # Reinstala estrutura completa
+```
+
+---
+
+### Erro ao instalar globalmente no Windows
+
+**Erro:** `EPERM: operation not permitted`
+
+**Causa:** Falta de permissões de administrador.
+
+**Solução:**
+1. Abra PowerShell ou CMD **como Administrador**
+2. Execute: `npm install -g @polymorphism-tech/morph-spec`
+
+**Alternativa:** Use `npx` (não requer admin):
+```bash
+npx @polymorphism-tech/morph-spec init
+```
+
+---
+
+### nvm-windows específico
+
+Se você usa **nvm-windows** para gerenciar versões do Node.js:
+
+**Problema conhecido:** npm global não vai para PATH automaticamente
+**Issue oficial:** https://github.com/coreybutler/nvm-windows/issues/391
+
+**Recomendações:**
+1. **Melhor opção:** Use `npx` para todos os comandos
+2. **Alternativa:** Configure PATH manualmente (ver seção de instalação)
+3. **Verificar:** Execute `morph-spec doctor` para diagnosticar
+
+---
+
+### Precisa de mais ajuda?
+
+```bash
+morph-spec doctor          # Diagnóstico automático
+morph-spec --help          # Ver todos os comandos
+morph-spec <comando> --help  # Ajuda de comando específico
+```
+
+**Suporte:**
+- 📧 Email: support@polymorphism.com.br
+- 🐛 Issues: [GitHub](https://github.com/lucasPolymorphism/morph-spec-framework/issues)
+
+---
+
 ## 📄 Licença e Distribuição
 
 **Repositório:** Privado (código fonte protegido)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "MORPH-SPEC v2.0: AI-First development framework with .NET 10, Microsoft Agent Framework, and Fluent UI Blazor",
   "keywords": [
     "claude-code",
@@ -26,6 +26,7 @@
   "files": [
     "bin/",
     "src/",
+    "scripts/",
     "detectors/",
     "content/",
     "docs/",
@@ -38,6 +39,7 @@
     "node": ">=18.0.0"
   },
   "scripts": {
+    "postinstall": "node scripts/postinstall.js",
     "start": "node bin/morph-spec.js",
     "test": "node --test",
     "test:coverage": "c8 --reporter=text --reporter=html --reporter=lcov node --test",

package/scripts/postinstall.js

@@ -0,0 +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();

package/src/commands/doctor.js

@@ -1,4 +1,6 @@
 import { join } from 'path';
+import { execSync } from 'child_process';
+import { platform } from 'os';
 import chalk from 'chalk';
 import { logger } from '../utils/logger.js';
 import { pathExists, readJson } from '../utils/file-copier.js';
@@ -8,6 +10,47 @@ import {
   getInstalledCLIVersion
 } from '../utils/version-checker.js';
 
+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;
+  }
+}
+
 export async function doctorCommand() {
   const targetPath = process.cwd();
 
@@ -68,6 +111,22 @@ export async function doctorCommand() {
     hasWarnings = true;
   }
 
+  // Check if morph-spec is in PATH
+  const inPath = isMorphSpecInPath();
+  if (inPath) {
+    checks.push({
+      name: 'morph-spec in PATH',
+      status: 'ok'
+    });
+  } else {
+    checks.push({
+      name: 'morph-spec in PATH',
+      status: 'warn',
+      msg: 'command not found'
+    });
+    hasWarnings = true;
+  }
+
   // Check CLAUDE.md
   const claudeMd = join(targetPath, 'CLAUDE.md');
   if (await pathExists(claudeMd)) {
@@ -187,6 +246,28 @@ export async function doctorCommand() {
     logger.warn('Some checks need attention.');
     logger.blank();
 
+    if (!inPath) {
+      const usingNvm = isUsingNvmWindows();
+      const prefix = getNpmGlobalPrefix();
+
+      if (usingNvm && prefix) {
+        logger.info('PATH Issue Detected (nvm-windows):');
+        logger.dim(`  Add to PATH: ${prefix}`);
+        logger.blank();
+        logger.dim('  PowerShell (as Administrator):');
+        console.log(chalk.gray(`    [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";${prefix}", "User")`));
+        logger.blank();
+        logger.dim('  Or use npx instead:');
+        logger.dim('    npx @polymorphism-tech/morph-spec init');
+        logger.blank();
+      } else if (!inPath) {
+        logger.info('morph-spec not in PATH:');
+        logger.dim('  Use npx instead:');
+        logger.dim('    npx @polymorphism-tech/morph-spec init');
+        logger.blank();
+      }
+    }
+
     if (cliCheck.isOutdated || projectCheck.isOutdated) {
       logger.info('To update:');
       logger.dim('  1. Update the CLI: npm install -g @polymorphism-tech/morph-spec@latest');

package/src/commands/init.js

@@ -52,16 +52,18 @@ export async function initCommand(options) {
     }
     await copyFile(claudeMdPath, claudeMdDest);
 
-    // 2. Create .morph/project structure
-    spinner.text = 'Creating .morph/project structure...';
+    // 2. Create .morph directory structure
+    spinner.text = 'Creating .morph structure...';
     const projectPath = join(morphPath, 'project');
+    const configDir = join(morphPath, 'config');
     await ensureDir(join(projectPath, 'context'));
     await ensureDir(join(projectPath, 'standards'));
     await ensureDir(join(projectPath, 'outputs'));
+    await ensureDir(configDir);
 
     // 3. Create config.json
     spinner.text = 'Generating config.json...';
-    const configPath = join(morphPath, 'config.json');
+    const configPath = join(configDir, 'config.json');
     const dirName = targetPath.split(/[\\/]/).pop();
 
     const config = {
@@ -99,12 +101,58 @@ Run \`morph-spec detect\` to analyze your project.
 `;
     await writeFile(contextReadme, readmeContent);
 
-    // 5. Save version info
+    // 5. Copy templates from content
+    spinner.text = 'Copying templates...';
+    const contentDir = getContentDir();
+    const templatesSrc = join(contentDir, '.morph', 'templates');
+    const templatesDest = join(morphPath, 'templates');
+    if (await pathExists(templatesSrc)) {
+      await copyDirectory(templatesSrc, templatesDest);
+    }
+
+    // 6. Copy standards from content
+    spinner.text = 'Copying standards...';
+    const standardsSrc = join(contentDir, '.morph', 'standards');
+    const standardsDest = join(morphPath, 'standards');
+    if (await pathExists(standardsSrc)) {
+      await copyDirectory(standardsSrc, standardsDest);
+    }
+
+    // 7. Copy agents.json
+    spinner.text = 'Copying agents configuration...';
+    const agentsSrc = join(contentDir, '.morph', 'config', 'agents.json');
+    const agentsDest = join(configDir, 'agents.json');
+    if (await pathExists(agentsSrc)) {
+      await copyFile(agentsSrc, agentsDest);
+    }
+
+    // 8. Copy azure-pricing files
+    spinner.text = 'Copying Azure pricing data...';
+    const pricingSrc = join(contentDir, '.morph', 'config', 'azure-pricing.json');
+    const pricingDest = join(configDir, 'azure-pricing.json');
+    if (await pathExists(pricingSrc)) {
+      await copyFile(pricingSrc, pricingDest);
+    }
+    const pricingSchemaSrc = join(contentDir, '.morph', 'config', 'azure-pricing.schema.json');
+    const pricingSchemaDest = join(configDir, 'azure-pricing.schema.json');
+    if (await pathExists(pricingSchemaSrc)) {
+      await copyFile(pricingSchemaSrc, pricingSchemaDest);
+    }
+
+    // 9. Copy .claude commands and skills
+    spinner.text = 'Copying Claude commands and skills...';
+    const claudeSrc = join(contentDir, '.claude');
+    const claudeDest = join(targetPath, '.claude');
+    if (await pathExists(claudeSrc)) {
+      await copyDirectory(claudeSrc, claudeDest);
+    }
+
+    // 10. Save version info
     spinner.text = 'Saving version info...';
     const cliVersion = getInstalledCLIVersion();
     await saveProjectMorphVersion(targetPath, cliVersion);
 
-    // 6. Update .gitignore
+    // 11. Update .gitignore
     spinner.text = 'Updating .gitignore...';
     await updateGitignore(targetPath);
 
@@ -126,16 +174,13 @@ Run \`morph-spec detect\` to analyze your project.
     ]);
     logger.blank();
 
-    logger.info('Structure created:');
-    logger.dim(`CLAUDE.md                → ${join(targetPath, 'CLAUDE.md')}`);
-    logger.dim(`.morph/config.json       → Project config`);
-    logger.dim(`.morph/project/context/  → Project context`);
-    logger.dim(`.morph/project/standards/→ Project standards`);
-    logger.dim(`.morph/project/outputs/  → Feature outputs`);
-    logger.blank();
-
-    logger.info('Content (via npm package):');
-    logger.dim(`Templates and standards available via morph-spec update`);
+    logger.info('Files installed:');
+    logger.dim(`  ✓ CLAUDE.md`);
+    logger.dim(`  ✓ .morph/config/ (config.json, agents.json, azure-pricing.json)`);
+    logger.dim(`  ✓ .morph/standards/ (coding.md, architecture.md, azure.md, ...)`);
+    logger.dim(`  ✓ .morph/templates/ (Bicep, integrations, saas, ...)`);
+    logger.dim(`  ✓ .morph/project/ (context, standards, outputs)`);
+    logger.dim(`  ✓ .claude/ (commands, skills)`);
     logger.blank();
 
   } catch (error) {