pmpt-cli 1.14.21 → 1.15.0

package/dist/commands/doctor.js

@@ -0,0 +1,220 @@
+import * as p from '@clack/prompts';
+import { execSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { detectPmptMcpPath, getWrapperStatus } from './mcp-setup.js';
+function checkNodeVersion() {
+    const version = process.versions.node;
+    const major = parseInt(version.split('.')[0], 10);
+    if (major >= 18) {
+        return { label: 'Node.js', status: 'ok', detail: `v${version}` };
+    }
+    return {
+        label: 'Node.js',
+        status: 'fail',
+        detail: `v${version} (requires ≥18)`,
+        fix: 'Update Node.js: https://nodejs.org',
+    };
+}
+function checkNvm() {
+    const nvmDir = process.env.NVM_DIR || join(homedir(), '.nvm');
+    const isNvm = !!process.env.NVM_DIR || process.argv[1]?.includes('.nvm/');
+    if (!isNvm && !existsSync(nvmDir)) {
+        return { label: 'nvm', status: 'ok', detail: 'Not using nvm (no PATH issues)' };
+    }
+    // Check if default alias is set
+    let defaultAlias = '';
+    try {
+        const aliasFile = join(nvmDir, 'alias', 'default');
+        if (existsSync(aliasFile)) {
+            defaultAlias = readFileSync(aliasFile, 'utf-8').trim();
+        }
+    }
+    catch { /* ignore */ }
+    if (defaultAlias) {
+        return {
+            label: 'nvm',
+            status: 'warn',
+            detail: `Active (default: ${defaultAlias}). MCP clients may not load nvm in non-interactive shells.`,
+            fix: 'Use "pmpt mcp-setup" to create a stable wrapper, or consider volta/fnm.',
+        };
+    }
+    return {
+        label: 'nvm',
+        status: 'warn',
+        detail: 'Active, no default alias set. MCP path may break across sessions.',
+        fix: 'Run "nvm alias default <version>" and "pmpt mcp-setup".',
+    };
+}
+function checkPmptMcpBinary() {
+    const path = detectPmptMcpPath();
+    if (path) {
+        return { label: 'pmpt-mcp binary', status: 'ok', detail: path };
+    }
+    return {
+        label: 'pmpt-mcp binary',
+        status: 'fail',
+        detail: 'Not found in PATH or sibling directory',
+        fix: 'Run "npm install -g pmpt-cli" to install.',
+    };
+}
+function checkWrapper() {
+    const wrapper = getWrapperStatus();
+    if (!wrapper.exists) {
+        const isNvm = !!process.env.NVM_DIR || process.argv[1]?.includes('.nvm/');
+        if (isNvm) {
+            return {
+                label: 'Wrapper script',
+                status: 'warn',
+                detail: 'Not created (recommended for nvm users)',
+                fix: 'Run "pmpt mcp-setup" to create ~/.pmpt/bin/pmpt-mcp wrapper.',
+            };
+        }
+        return { label: 'Wrapper script', status: 'ok', detail: 'Not needed (not using nvm)' };
+    }
+    if (wrapper.targetValid) {
+        return { label: 'Wrapper script', status: 'ok', detail: `OK → ${wrapper.targetPath}` };
+    }
+    return {
+        label: 'Wrapper script',
+        status: 'fail',
+        detail: `Stale — target binary missing: ${wrapper.targetPath}`,
+        fix: 'Run "pmpt mcp-setup" to update the wrapper after Node version change.',
+    };
+}
+function checkMcpClients() {
+    const results = [];
+    // Claude Code
+    try {
+        execSync('which claude', { stdio: ['pipe', 'pipe', 'pipe'] });
+        try {
+            const list = execSync('claude mcp list', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+            if (list.includes('pmpt')) {
+                results.push({ label: 'Claude Code MCP', status: 'ok', detail: 'pmpt registered' });
+            }
+            else {
+                results.push({
+                    label: 'Claude Code MCP',
+                    status: 'warn',
+                    detail: 'Claude Code found but pmpt not registered',
+                    fix: 'Run "pmpt mcp-setup" and select Claude Code.',
+                });
+            }
+        }
+        catch {
+            results.push({
+                label: 'Claude Code MCP',
+                status: 'warn',
+                detail: 'Claude Code found but "claude mcp list" failed',
+                fix: 'Make sure Claude Code is up to date.',
+            });
+        }
+    }
+    catch {
+        // Claude Code not installed — skip
+    }
+    // Cursor
+    const cursorConfig = join(homedir(), '.cursor', 'mcp.json');
+    if (existsSync(join(homedir(), '.cursor'))) {
+        try {
+            if (existsSync(cursorConfig)) {
+                const content = JSON.parse(readFileSync(cursorConfig, 'utf-8'));
+                if (content?.mcpServers?.pmpt) {
+                    const cmd = content.mcpServers.pmpt.command;
+                    if (existsSync(cmd)) {
+                        results.push({ label: 'Cursor MCP', status: 'ok', detail: `pmpt → ${cmd}` });
+                    }
+                    else {
+                        results.push({
+                            label: 'Cursor MCP',
+                            status: 'fail',
+                            detail: `pmpt registered but binary missing: ${cmd}`,
+                            fix: 'Run "pmpt mcp-setup" to update the path.',
+                        });
+                    }
+                }
+                else {
+                    results.push({
+                        label: 'Cursor MCP',
+                        status: 'warn',
+                        detail: 'Cursor found but pmpt not in mcp.json',
+                        fix: 'Run "pmpt mcp-setup" and select Cursor.',
+                    });
+                }
+            }
+        }
+        catch {
+            results.push({ label: 'Cursor MCP', status: 'warn', detail: 'Could not parse ~/.cursor/mcp.json' });
+        }
+    }
+    // Project .mcp.json
+    const projectMcp = join(process.cwd(), '.mcp.json');
+    if (existsSync(projectMcp)) {
+        try {
+            const content = JSON.parse(readFileSync(projectMcp, 'utf-8'));
+            if (content?.mcpServers?.pmpt) {
+                const cmd = content.mcpServers.pmpt.command;
+                if (existsSync(cmd)) {
+                    results.push({ label: '.mcp.json', status: 'ok', detail: `pmpt → ${cmd}` });
+                }
+                else {
+                    results.push({
+                        label: '.mcp.json',
+                        status: 'fail',
+                        detail: `pmpt registered but binary missing: ${cmd}`,
+                        fix: 'Run "pmpt mcp-setup" to update the path.',
+                    });
+                }
+            }
+        }
+        catch {
+            results.push({ label: '.mcp.json', status: 'warn', detail: 'Could not parse .mcp.json' });
+        }
+    }
+    if (results.length === 0) {
+        results.push({
+            label: 'MCP clients',
+            status: 'warn',
+            detail: 'No MCP client configuration found',
+            fix: 'Run "pmpt mcp-setup" to configure an AI tool.',
+        });
+    }
+    return results;
+}
+const icons = { ok: '✓', warn: '⚠', fail: '✗' };
+const colors = { ok: '\x1b[32m', warn: '\x1b[33m', fail: '\x1b[31m' };
+const reset = '\x1b[0m';
+export async function cmdDoctor() {
+    p.intro('pmpt doctor');
+    const s = p.spinner();
+    s.start('Running diagnostics...');
+    const checks = [
+        checkNodeVersion(),
+        checkNvm(),
+        checkPmptMcpBinary(),
+        checkWrapper(),
+        ...checkMcpClients(),
+    ];
+    s.stop('Diagnostics complete');
+    // Display results
+    const lines = [];
+    let hasIssues = false;
+    for (const check of checks) {
+        const icon = icons[check.status];
+        const color = colors[check.status];
+        lines.push(`${color}${icon}${reset} ${check.label}: ${check.detail}`);
+        if (check.fix) {
+            lines.push(`  → ${check.fix}`);
+            hasIssues = true;
+        }
+    }
+    p.note(lines.join('\n'), 'Diagnostic Results');
+    if (hasIssues) {
+        p.log.warn('Some issues found. Run the suggested fixes above.');
+    }
+    else {
+        p.log.success('Everything looks good!');
+    }
+    p.outro('');
+}

package/dist/commands/init.js

@@ -5,7 +5,7 @@ import { initializeProject, isInitialized, getDocsDir, ensurePmptClaudeMd, ensur
 import { isGitRepo, getGitInfo, formatGitInfo, getCommitCount } from '../lib/git.js';
 import { cmdPlan } from './plan.js';
 import { scanProject, scanResultToAnswers } from '../lib/scanner.js';
-import { savePlanDocuments, initPlanProgress, savePlanProgress } from '../lib/plan.js';
+import { savePlanDocuments, initPlanProgress, savePlanProgress, generateAnswersTemplate } from '../lib/plan.js';
 import { copyToClipboard } from '../lib/clipboard.js';
 export async function cmdInit(path, options) {
     p.intro('pmpt init');
@@ -155,6 +155,7 @@ export async function cmdInit(path, options) {
                 options: [
                     { value: 'auto', label: 'Auto-generate plan', hint: 'Recommended — instant AI prompt from project analysis' },
                     { value: 'manual', label: 'Manual planning', hint: '5 questions interactive flow' },
+                    { value: 'file', label: 'Fill in answers file', hint: 'Windows/PowerShell friendly — edit a JSON file then run pmpt plan --answers-file' },
                     { value: 'skip', label: 'Skip for now' },
                 ],
             });
@@ -162,6 +163,17 @@ export async function cmdInit(path, options) {
                 p.cancel('Cancelled');
                 process.exit(0);
             }
+            if (scanChoice === 'file') {
+                const outFile = 'answers.json';
+                const template = generateAnswersTemplate();
+                writeFileSync(resolve(projectPath, outFile), JSON.stringify(template, null, 2), 'utf-8');
+                p.log.success(`Template created: ${outFile}`);
+                p.log.info('Next steps:');
+                p.log.message(`  1. Open and fill in ${outFile}`);
+                p.log.message(`  2. pmpt plan --answers-file ${outFile}`);
+                p.outro('Ready!');
+                return;
+            }
             if (scanChoice === 'auto') {
                 // Ask for project description
                 const defaultDesc = scanResult.readmeDescription
@@ -236,23 +248,41 @@ export async function cmdInit(path, options) {
             }
             else {
                 ensureMinimalDocs(projectPath);
+                p.log.info('Tip: On Windows/PowerShell, use a template file to avoid paste issues:');
+                p.log.message('  pmpt plan --template   # creates answers.json');
+                p.log.message('  pmpt plan --answers-file answers.json');
                 p.outro('Ready! Run `pmpt plan` when you want to start.');
             }
         }
         else {
             // New/empty project — original flow
-            const startPlan = await p.confirm({
-                message: 'Start planning? (Generate AI prompt with 5 quick questions)',
-                initialValue: true,
+            const startPlan = await p.select({
+                message: 'Start planning?',
+                options: [
+                    { value: 'yes', label: 'Yes — answer 5 questions now', hint: 'Interactive flow' },
+                    { value: 'file', label: 'Fill in answers file', hint: 'Windows/PowerShell friendly — edit a JSON file then run pmpt plan --answers-file' },
+                    { value: 'no', label: 'Skip for now' },
+                ],
             });
-            if (!p.isCancel(startPlan) && startPlan) {
-                p.log.message('');
-                await cmdPlan(projectPath);
-            }
-            else {
+            if (p.isCancel(startPlan) || startPlan === 'no') {
                 ensureMinimalDocs(projectPath);
                 p.outro('Ready! Run `pmpt plan` when you want to start.');
             }
+            else if (startPlan === 'file') {
+                const outFile = 'answers.json';
+                const template = generateAnswersTemplate();
+                writeFileSync(resolve(projectPath, outFile), JSON.stringify(template, null, 2), 'utf-8');
+                ensureMinimalDocs(projectPath);
+                p.log.success(`Template created: ${outFile}`);
+                p.log.info('Next steps:');
+                p.log.message(`  1. Open and fill in ${outFile}`);
+                p.log.message(`  2. pmpt plan --answers-file ${outFile}`);
+                p.outro('Ready!');
+            }
+            else {
+                p.log.message('');
+                await cmdPlan(projectPath);
+            }
         }
     }
     catch (error) {

package/dist/commands/mcp-setup.js

@@ -1,9 +1,12 @@
 import * as p from '@clack/prompts';
 import { execSync } from 'child_process';
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'fs';
 import { join, dirname } from 'path';
 import { homedir } from 'os';
-function detectPmptMcpPath() {
+/** Stable wrapper path that survives nvm version switches */
+const WRAPPER_DIR = join(homedir(), '.pmpt', 'bin');
+const WRAPPER_PATH = join(WRAPPER_DIR, 'pmpt-mcp');
+export function detectPmptMcpPath() {
     // Strategy 1: sibling to the current pmpt binary (same bin directory)
     const pmptBin = process.argv[1];
     const siblingPath = join(dirname(pmptBin), 'pmpt-mcp');
@@ -24,6 +27,51 @@ function detectPmptMcpPath() {
     }
     return null;
 }
+/** Detect if nvm is in use */
+function isNvmEnvironment() {
+    return !!process.env.NVM_DIR || process.argv[1]?.includes('.nvm/');
+}
+/**
+ * Create a wrapper script at ~/.pmpt/bin/pmpt-mcp that:
+ * 1. Loads nvm if available
+ * 2. Executes the real pmpt-mcp binary
+ * This makes the MCP path stable across Node version changes.
+ */
+function createWrapperScript(realBinaryPath) {
+    mkdirSync(WRAPPER_DIR, { recursive: true });
+    const nvmDir = process.env.NVM_DIR || join(homedir(), '.nvm');
+    const script = `#!/bin/bash
+# pmpt-mcp wrapper — loads nvm then runs the real binary
+# Auto-generated by pmpt mcp-setup. Re-run "pmpt mcp-setup" to update.
+
+export NVM_DIR="${nvmDir}"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+
+exec "${realBinaryPath}" "$@"
+`;
+    writeFileSync(WRAPPER_PATH, script, { mode: 0o755 });
+    chmodSync(WRAPPER_PATH, 0o755);
+    return WRAPPER_PATH;
+}
+/** Check if wrapper exists and the target binary it points to is still valid */
+export function getWrapperStatus() {
+    if (!existsSync(WRAPPER_PATH)) {
+        return { exists: false, targetValid: false, targetPath: null };
+    }
+    try {
+        const content = readFileSync(WRAPPER_PATH, 'utf-8');
+        const match = content.match(/exec "(.+?)"/);
+        const targetPath = match?.[1] || null;
+        return {
+            exists: true,
+            targetValid: targetPath ? existsSync(targetPath) : false,
+            targetPath,
+        };
+    }
+    catch {
+        return { exists: true, targetValid: false, targetPath: null };
+    }
+}
 function isCommandAvailable(cmd) {
     try {
         const which = process.platform === 'win32' ? 'where' : 'which';
@@ -55,14 +103,15 @@ function isJsonConfigured(configPath) {
     }
 }
 function configureClaudeCode(mcpBinaryPath) {
-    // Remove existing entry first (ignore errors if not found)
-    try {
-        execSync('claude mcp remove pmpt', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
-    }
-    catch {
-        // not configured yet — that's fine
+    // Remove existing entry at any scope first (ignore errors if not found)
+    for (const scope of ['user', 'local', 'project']) {
+        try {
+            execSync(`claude mcp remove --scope ${scope} pmpt`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+        }
+        catch { /* not configured at this scope */ }
     }
-    execSync(`claude mcp add --transport stdio pmpt -- "${mcpBinaryPath}"`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+    // Register at user scope so it works across all projects
+    execSync(`claude mcp add --scope user --transport stdio pmpt -- "${mcpBinaryPath}"`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
 }
 function configureJsonFile(configPath, mcpBinaryPath) {
     let config = {};
@@ -93,6 +142,21 @@ export async function cmdMcpSetup() {
     let mcpPath = detectPmptMcpPath();
     if (mcpPath) {
         s.stop(`Found: ${mcpPath}`);
+        // If nvm environment, offer to create a stable wrapper
+        if (isNvmEnvironment()) {
+            p.log.warn('nvm detected — the binary path may break when you switch Node versions.');
+            const useWrapper = await p.confirm({
+                message: 'Create a stable wrapper at ~/.pmpt/bin/pmpt-mcp? (recommended for nvm users)',
+                initialValue: true,
+            });
+            if (!p.isCancel(useWrapper) && useWrapper) {
+                const wrapperPath = createWrapperScript(mcpPath);
+                p.log.success(`Wrapper created: ${wrapperPath}`);
+                p.log.info(`Points to: ${mcpPath}`);
+                p.log.info('After switching Node versions, run "pmpt mcp-setup" to update the wrapper.');
+                mcpPath = wrapperPath;
+            }
+        }
     }
     else {
         s.stop('Could not auto-detect pmpt-mcp path');

package/dist/commands/plan.js

@@ -1,10 +1,10 @@
 import * as p from '@clack/prompts';
 import { resolve } from 'path';
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { isInitialized, loadConfig } from '../lib/config.js';
 import { copyToClipboard } from '../lib/clipboard.js';
 import { cmdWatch } from './watch.js';
-import { PLAN_QUESTIONS, getPlanProgress, initPlanProgress, savePlanProgress, savePlanDocuments, } from '../lib/plan.js';
+import { PLAN_QUESTIONS, getPlanProgress, initPlanProgress, savePlanProgress, savePlanDocuments, generateAnswersTemplate, } from '../lib/plan.js';
 function loadAnswersFromFile(projectPath, inputPath) {
     const filePath = resolve(projectPath, inputPath);
     if (!existsSync(filePath)) {
@@ -27,6 +27,16 @@ function loadAnswersFromFile(projectPath, inputPath) {
 }
 export async function cmdPlan(path, options) {
     const projectPath = path ? resolve(path) : process.cwd();
+    // Template generation (no init check needed)
+    if (options?.template) {
+        const outFile = resolve(projectPath, options.template);
+        const template = generateAnswersTemplate();
+        writeFileSync(outFile, JSON.stringify(template, null, 2), 'utf-8');
+        p.log.success(`Template created: ${outFile}`);
+        p.log.info('Fill in the fields and run:');
+        p.log.message(`  pmpt plan --answers-file ${options.template}`);
+        return;
+    }
     // Check initialization
     if (!isInitialized(projectPath)) {
         p.intro('pmpt plan');

package/dist/index.js

@@ -45,6 +45,7 @@ import { cmdRecover } from './commands/recover.js';
 import { cmdDiff } from './commands/diff.js';
 import { cmdInternalSeed } from './commands/internal-seed.js';
 import { cmdMcpSetup } from './commands/mcp-setup.js';
+import { cmdDoctor } from './commands/doctor.js';
 import { trackCommand } from './lib/api.js';
 import { checkForUpdates } from './lib/update-check.js';
 import { createRequire } from 'module';
@@ -85,6 +86,7 @@ Examples:
   $ pmpt graduate                Graduate a project (Hall of Fame)
   $ pmpt recover                 Recover damaged pmpt.md via AI
   $ pmpt mcp-setup                Configure MCP for AI tools
+  $ pmpt doctor (doc)            Diagnose MCP & environment issues
   $ pmpt feedback (fb)           Share ideas or report bugs
 
 Workflow:
@@ -146,7 +148,11 @@ program
     .description('Quick product planning with 5 questions — auto-generate AI prompt')
     .option('--reset', 'Restart plan from scratch')
     .option('--answers-file <file>', 'Load plan answers from JSON file (non-interactive)')
-    .action(cmdPlan);
+    .option('--template [file]', 'Generate a fillable answers template (default: answers.json)')
+    .action((path, options) => cmdPlan(path, {
+    ...options,
+    template: options.template === true ? 'answers.json' : options.template,
+}));
 program
     .command('logout')
     .description('Clear saved GitHub authentication')
@@ -214,6 +220,11 @@ program
     .command('mcp-setup')
     .description('Configure pmpt MCP server for AI tools (Claude Code, Cursor, etc.)')
     .action(cmdMcpSetup);
+program
+    .command('doctor')
+    .alias('doc')
+    .description('Diagnose MCP connection, PATH issues, and environment health')
+    .action(cmdDoctor);
 program
     .command('feedback')
     .alias('fb')

package/dist/lib/plan.js

@@ -200,6 +200,19 @@ ${techSection}
 *Generated by pmpt plan*
 `;
 }
+export function generateAnswersTemplate() {
+    const questions = {};
+    const fields = {};
+    for (const q of PLAN_QUESTIONS) {
+        questions[q.key] = `[${PLAN_QUESTIONS.indexOf(q) + 1}/${PLAN_QUESTIONS.length}] ${q.question}`;
+        fields[q.key] = '';
+    }
+    return {
+        _help: 'Fill in the fields below, then run: pmpt plan --answers-file <this-file>',
+        _questions: questions,
+        ...fields,
+    };
+}
 export function getPlanProgress(projectPath) {
     const planPath = join(getConfigDir(projectPath), PLAN_FILE);
     if (!existsSync(planPath))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmpt-cli",
-  "version": "1.14.21",
+  "version": "1.15.0",
   "description": "Record and share your AI-driven product development journey",
   "type": "module",
   "bin": {