pmpt-cli 1.14.6 → 1.14.8

package/dist/commands/save.js

@@ -1,8 +1,8 @@
 import * as p from '@clack/prompts';
-import { resolve } from 'path';
-import { existsSync, statSync } from 'fs';
+import { resolve, join } from 'path';
+import { existsSync, statSync, readFileSync, writeFileSync } from 'fs';
 import { isInitialized, getDocsDir } from '../lib/config.js';
-import { createFullSnapshot, getTrackedFiles } from '../lib/history.js';
+import { createFullSnapshot, getTrackedFiles, getAllSnapshots } from '../lib/history.js';
 export async function cmdSave(fileOrPath) {
     const projectPath = fileOrPath && existsSync(fileOrPath) && statSync(fileOrPath).isDirectory()
         ? resolve(fileOrPath)
@@ -21,10 +21,46 @@ export async function cmdSave(fileOrPath) {
         p.outro('');
         return;
     }
+    // Ask for summary
+    const summary = await p.text({
+        message: 'What did you accomplish? (this is shown on your project page)',
+        placeholder: 'e.g. Added user auth with JWT, built login/signup pages',
+    });
+    if (p.isCancel(summary)) {
+        p.cancel('Save cancelled.');
+        process.exit(0);
+    }
+    const note = summary.trim() || undefined;
+    // Write summary to pmpt.md Snapshot Log before snapshot
+    if (note) {
+        const pmptMdPath = join(docsDir, 'pmpt.md');
+        if (existsSync(pmptMdPath)) {
+            let content = readFileSync(pmptMdPath, 'utf-8');
+            const snapshots = getAllSnapshots(projectPath);
+            const nextVersion = snapshots.length + 1;
+            const date = new Date().toISOString().slice(0, 10);
+            const noteLines = note.split(/(?:\.\s+|\n)/).filter(s => s.trim()).map(s => {
+                const trimmed = s.trim().replace(/\.?$/, '');
+                return `- ${trimmed}`;
+            });
+            const entry = `\n### v${nextVersion} — ${date}\n${noteLines.join('\n')}\n`;
+            const logIndex = content.indexOf('## Snapshot Log');
+            if (logIndex !== -1) {
+                const afterHeader = content.indexOf('\n', logIndex);
+                const nextSection = content.indexOf('\n## ', afterHeader + 1);
+                const insertPos = nextSection !== -1 ? nextSection : content.length;
+                content = content.slice(0, insertPos) + entry + content.slice(insertPos);
+            }
+            else {
+                content += `\n## Snapshot Log${entry}`;
+            }
+            writeFileSync(pmptMdPath, content, 'utf-8');
+        }
+    }
     const s = p.spinner();
     s.start(`Creating snapshot of ${files.length} file(s)...`);
     try {
-        const entry = createFullSnapshot(projectPath);
+        const entry = createFullSnapshot(projectPath, { note });
         s.stop('Snapshot saved');
         let msg = `v${entry.version} saved`;
         if (entry.git) {
@@ -38,11 +74,8 @@ export async function cmdSave(fileOrPath) {
             msg += ` (${changedCount} changed, ${unchangedCount} skipped)`;
         }
         p.log.success(msg);
-        // Warn if pmpt.md was not updated since last save
-        if (entry.version > 1 && entry.changedFiles && !entry.changedFiles.includes('pmpt.md')) {
-            p.log.message('');
-            p.log.warn('pmpt.md has not been updated since the last save.');
-            p.log.message('  Tip: Mark completed features and update the Snapshot Log before saving.');
+        if (note) {
+            p.log.info(`Summary: ${note}`);
         }
         p.log.message('');
         p.log.info('Files included:');

package/dist/commands/watch.js

@@ -14,7 +14,7 @@ export function cmdWatch(path) {
     p.log.info('Auto-saving snapshots on MD file changes.');
     p.log.info('Press Ctrl+C to stop.');
     p.log.message('');
-    const watcher = startWatching(projectPath, (version, files, git) => {
+    const watcher = startWatching(projectPath, (version, files, git, note) => {
         let msg = `v${version} saved (${files.length} file(s))`;
         if (git) {
             msg += ` · ${git.commit}`;
@@ -22,6 +22,9 @@ export function cmdWatch(path) {
                 msg += ' (uncommitted)';
         }
         p.log.success(msg);
+        if (note) {
+            p.log.info(`  ${note}`);
+        }
     });
     process.on('SIGINT', () => {
         p.log.message('');

package/dist/lib/watcher.js

@@ -2,7 +2,7 @@ import chokidar from 'chokidar';
 import { loadConfig, getDocsDir } from './config.js';
 import { createFullSnapshot } from './history.js';
 import { readFileSync } from 'fs';
-import { join } from 'path';
+import { join, relative } from 'path';
 export function startWatching(projectPath, onSnapshot) {
     const config = loadConfig(projectPath);
     if (!config) {
@@ -19,11 +19,18 @@ export function startWatching(projectPath, onSnapshot) {
         },
     });
     const fileContents = new Map();
+    const pendingChanges = new Set();
     let debounceTimer = null;
     const saveSnapshot = () => {
-        const entry = createFullSnapshot(projectPath);
+        // Build auto-note from changed file names
+        const changedNames = [...pendingChanges].map(p => relative(docsDir, p));
+        const note = changedNames.length > 0
+            ? `Updated ${changedNames.join(', ')}`
+            : undefined;
+        pendingChanges.clear();
+        const entry = createFullSnapshot(projectPath, { note });
         if (onSnapshot) {
-            onSnapshot(entry.version, entry.files, entry.git);
+            onSnapshot(entry.version, entry.files, entry.git, note);
         }
     };
     // Debounced snapshot save (1 second)
@@ -37,6 +44,7 @@ export function startWatching(projectPath, onSnapshot) {
         try {
             const content = readFileSync(path, 'utf-8');
             fileContents.set(path, content);
+            pendingChanges.add(path);
             debouncedSave();
         }
         catch {
@@ -50,6 +58,7 @@ export function startWatching(projectPath, onSnapshot) {
             // Only snapshot if content actually changed
             if (oldContent !== newContent) {
                 fileContents.set(path, newContent);
+                pendingChanges.add(path);
                 debouncedSave();
             }
         }

package/dist/mcp.js

@@ -15,7 +15,7 @@ import { createRequire } from 'module';
 import { isInitialized, loadConfig, saveConfig, getDocsDir, getHistoryDir } from './lib/config.js';
 import { createFullSnapshot, getAllSnapshots, getTrackedFiles, resolveFullSnapshot } from './lib/history.js';
 import { computeQuality } from './lib/quality.js';
-import { getPlanProgress, savePlanProgress, savePlanDocuments, PLAN_QUESTIONS } from './lib/plan.js';
+import { getPlanProgress, savePlanProgress, savePlanDocuments, PLAN_QUESTIONS, generatePlanDocument, generateAIPrompt } from './lib/plan.js';
 import { isGitRepo } from './lib/git.js';
 import { diffSnapshots } from './lib/diff.js';
 import { loadAuth } from './lib/auth.js';
@@ -98,9 +98,9 @@ function formatDiffs(diffs) {
     return lines.join('\n');
 }
 // ── Tools ───────────────────────────────────────────
-server.tool('pmpt_save', 'Save a snapshot of .pmpt/docs/ files. Call after completing features, fixes, or milestones. CRITICAL: Always provide a summary parameter — it becomes the version description shown on pmptwiki.com. Without a summary, the version appears empty on the project page. Write a concise description of what was accomplished (e.g. "Added user authentication with JWT").', {
+server.tool('pmpt_save', 'Save a snapshot of .pmpt/docs/ files. Call after completing features, fixes, or milestones. CRITICAL: Always provide a detailed summary parameter — it becomes the version description shown publicly on pmptwiki.com. Without a summary, the version appears empty on the project page. Write a DETAILED summary (3-5 sentences) that explains: (1) WHAT was built or changed, (2) WHY it matters, (3) key technical decisions made. Think of it as a mini dev blog entry that helps others learn from your journey.', {
     projectPath: z.string().optional().describe('Project root path. Defaults to cwd.'),
-    summary: z.string().optional().describe('What was accomplished since the last save. This is recorded in pmpt.md as a development log entry. Examples: "Implemented user auth with JWT", "Fixed responsive layout on mobile", "Added search filtering by category".'),
+    summary: z.string().optional().describe('Detailed description of what was accomplished since the last save. Write 3-5 sentences that tell the story: what you built, why, and how. This is shown publicly on the project page. BAD example: "Added auth" — too vague. GOOD example: "Implemented user authentication using JWT with refresh token rotation. Chose JWT over session-based auth for stateless API compatibility. Added login/signup pages with form validation and error handling. Protected routes now redirect unauthenticated users to login."'),
 }, async ({ projectPath, summary }) => {
     try {
         const pp = resolveProjectPath(projectPath);
@@ -118,7 +118,11 @@ server.tool('pmpt_save', 'Save a snapshot of .pmpt/docs/ files. Call after compl
                 const snapshots = getAllSnapshots(pp);
                 const nextVersion = snapshots.length + 1;
                 const date = new Date().toISOString().slice(0, 10);
-                const entry = `\n### v${nextVersion} — ${date}\n- ${summary}\n`;
+                const summaryLines = summary.split(/(?:\.\s+|\n)/).filter(s => s.trim()).map(s => {
+                    const trimmed = s.trim().replace(/\.?$/, '');
+                    return `- ${trimmed}`;
+                });
+                const entry = `\n### v${nextVersion} — ${date}\n${summaryLines.join('\n')}\n`;
                 const logIndex = content.indexOf('## Snapshot Log');
                 if (logIndex !== -1) {
                     const afterHeader = content.indexOf('\n', logIndex);
@@ -476,11 +480,11 @@ server.tool('pmpt_read_context', 'Read project context to understand current sta
         return { content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
     }
 });
-server.tool('pmpt_update_doc', 'Update pmpt.md: check off completed features, add progress notes, or backfill missing version summaries. Use after completing work OR before publishing to fill in empty Snapshot Log entries. To backfill: set snapshotVersion="v2 — Description" and progressNote="What was done in this version".', {
+server.tool('pmpt_update_doc', 'Update pmpt.md: check off completed features, add progress notes, or backfill missing version summaries. Use after completing work OR before publishing to fill in empty Snapshot Log entries. To backfill: use pmpt_diff to understand what changed, then set snapshotVersion="v2 — Short Title" and progressNote with DETAILED multi-sentence description. Write as if explaining to another developer what happened in this version and why.', {
     projectPath: z.string().optional().describe('Project root path. Defaults to cwd.'),
     completedFeatures: z.array(z.string()).optional().describe('Feature names to mark as done (matches against checkbox items in pmpt.md).'),
-    progressNote: z.string().optional().describe('Progress note to append to the Snapshot Log section.'),
-    snapshotVersion: z.string().optional().describe('Version label for the snapshot log entry (e.g. "v3 - Auth Complete"). Auto-generated if omitted.'),
+    progressNote: z.string().optional().describe('Detailed progress note (3-5 sentences) to append to the Snapshot Log. Explain what was done, why, and any key decisions. Each sentence becomes a bullet point. BAD: "Fixed bugs". GOOD: "Fixed authentication redirect loop caused by token expiry race condition. Added token refresh middleware that silently renews expired tokens. Users no longer get logged out unexpectedly during long sessions."'),
+    snapshotVersion: z.string().optional().describe('Version label for the snapshot log entry (e.g. "v3 — Auth Complete"). Auto-generated if omitted.'),
 }, async ({ projectPath, completedFeatures, progressNote, snapshotVersion }) => {
     try {
         const pp = resolveProjectPath(projectPath);
@@ -507,7 +511,11 @@ server.tool('pmpt_update_doc', 'Update pmpt.md: check off completed features, ad
         if (progressNote) {
             const snapshots = getAllSnapshots(pp);
             const label = snapshotVersion || `v${snapshots.length} - Progress`;
-            const entry = `\n### ${label}\n- ${progressNote}\n`;
+            const noteLines = progressNote.split(/(?:\.\s+|\n)/).filter(s => s.trim()).map(s => {
+                const trimmed = s.trim().replace(/\.?$/, '');
+                return `- ${trimmed}`;
+            });
+            const entry = `\n### ${label}\n${noteLines.join('\n')}\n`;
             const logIndex = content.indexOf('## Snapshot Log');
             if (logIndex !== -1) {
                 // Find the end of the Snapshot Log header line
@@ -582,7 +590,7 @@ server.tool('pmpt_log_decision', 'Record an architectural or technical decision
         return { content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
     }
 });
-server.tool('pmpt_publish', 'Publish the project to pmptwiki.com. Non-interactive — just provide slug and optional metadata. MANDATORY pre-publish checklist: (1) Run pmpt_history — if ANY version lacks a note/summary, you MUST fix it before publishing. (2) For each empty version, run pmpt_diff for that version to understand changes, then use pmpt_update_doc with progressNote and snapshotVersion (e.g. snapshotVersion="v2 — Tech stack migration to Cloudflare") to add Snapshot Log entries to pmpt.md. (3) After backfilling all versions, run pmpt_save with a summary. (4) Run pmpt_quality to verify readiness. DO NOT publish with empty versions — they display poorly on the project page. Note: user must have run `pmpt login` once before.', {
+server.tool('pmpt_publish', 'Publish the project to pmptwiki.com. Non-interactive — just provide slug and optional metadata. MANDATORY pre-publish checklist: (1) Run pmpt_history — if ANY version lacks a note/summary, you MUST fix it before publishing. (2) For each empty version, run pmpt_diff for that version to understand what changed, then use pmpt_update_doc with a DETAILED progressNote (3-5 sentences explaining what, why, and key decisions) and snapshotVersion. Write like a dev blog — others will read this to learn from your journey. (3) After backfilling all versions, run pmpt_save with a detailed summary. (4) Run pmpt_quality to verify readiness. DO NOT publish with empty or vague single-line versions — they display poorly on the project page. Note: user must have run `pmpt login` once before.', {
     projectPath: z.string().optional().describe('Project root path. Defaults to cwd.'),
     slug: z.string().describe('Project slug (3-50 chars, lowercase alphanumeric and hyphens).'),
     description: z.string().optional().describe('Project description (max 500 chars).'),
@@ -681,6 +689,134 @@ server.tool('pmpt_publish', 'Publish the project to pmptwiki.com. Non-interactiv
         return { content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
     }
 });
+server.tool('pmpt_edit_plan', 'Edit existing plan fields (productIdea, coreFeatures, techStack, additionalContext, projectName). Use this to update plan content — e.g., translate productIdea to English, add new features, change tech stack. Only provided fields are updated; others stay unchanged. Regenerates plan.md and pmpt.ai.md automatically. pmpt.md progress/log sections are preserved — only the plan-derived sections (Product Idea, Features, Tech Stack, Additional Context) are updated.', {
+    projectPath: z.string().optional().describe('Project root path. Defaults to cwd.'),
+    projectName: z.string().optional().describe('New project name.'),
+    productIdea: z.string().optional().describe('New product idea description.'),
+    coreFeatures: z.string().optional().describe('New core features (comma or semicolon separated).'),
+    techStack: z.string().optional().describe('New tech stack preference.'),
+    additionalContext: z.string().optional().describe('New additional context.'),
+}, async ({ projectPath, projectName, productIdea, coreFeatures, techStack, additionalContext }) => {
+    try {
+        const pp = resolveProjectPath(projectPath);
+        assertInitialized(pp);
+        const progress = getPlanProgress(pp);
+        if (!progress?.completed || !progress.answers) {
+            return { content: [{ type: 'text', text: 'No plan found. Run pmpt_plan first to create a plan.' }], isError: true };
+        }
+        // Track what changed
+        const changes = [];
+        const answers = { ...progress.answers };
+        if (projectName !== undefined) {
+            answers.projectName = projectName;
+            changes.push(`projectName → "${projectName}"`);
+        }
+        if (productIdea !== undefined) {
+            answers.productIdea = productIdea;
+            changes.push(`productIdea updated`);
+        }
+        if (coreFeatures !== undefined) {
+            answers.coreFeatures = coreFeatures;
+            changes.push(`coreFeatures updated`);
+        }
+        if (techStack !== undefined) {
+            answers.techStack = techStack;
+            changes.push(`techStack → "${techStack}"`);
+        }
+        if (additionalContext !== undefined) {
+            answers.additionalContext = additionalContext;
+            changes.push(`additionalContext updated`);
+        }
+        if (changes.length === 0) {
+            return { content: [{ type: 'text', text: 'No fields provided. Pass at least one field to update.' }] };
+        }
+        // Update plan-progress.json
+        savePlanProgress(pp, { ...progress, answers });
+        // Regenerate plan.md and pmpt.ai.md
+        const docsDir = getDocsDir(pp);
+        const planPath = join(docsDir, 'plan.md');
+        writeFileSync(planPath, generatePlanDocument(answers), 'utf-8');
+        const aiMdPath = join(docsDir, 'pmpt.ai.md');
+        writeFileSync(aiMdPath, generateAIPrompt(answers), 'utf-8');
+        // Update pmpt.md plan-derived sections (preserve progress, log, decisions)
+        const pmptMdPath = join(docsDir, 'pmpt.md');
+        if (existsSync(pmptMdPath)) {
+            let content = readFileSync(pmptMdPath, 'utf-8');
+            // Update title (first # heading)
+            content = content.replace(/^# .+$/m, `# ${answers.projectName}`);
+            // Update Product Idea section
+            const ideaRegex = /## Product Idea\n[\s\S]*?(?=\n## )/;
+            if (ideaRegex.test(content)) {
+                content = content.replace(ideaRegex, `## Product Idea\n${answers.productIdea}\n`);
+            }
+            // Update Features section (only unchecked items get replaced; checked items are preserved)
+            const featuresRegex = /## Features\n[\s\S]*?(?=\n## )/;
+            if (featuresRegex.test(content)) {
+                const existingMatch = content.match(featuresRegex);
+                if (existingMatch) {
+                    // Extract already-checked features
+                    const checked = existingMatch[0]
+                        .split('\n')
+                        .filter(line => line.startsWith('- [x]'))
+                        .join('\n');
+                    const newFeatures = answers.coreFeatures
+                        .split(/[,;\n]/)
+                        .map((f) => f.trim())
+                        .filter((f) => f)
+                        .map((f) => `- [ ] ${f}`)
+                        .join('\n');
+                    const featuresSection = checked
+                        ? `## Features\n${checked}\n${newFeatures}\n`
+                        : `## Features\n${newFeatures}\n`;
+                    content = content.replace(featuresRegex, featuresSection);
+                }
+            }
+            // Update Tech Stack section
+            if (answers.techStack) {
+                const techRegex = /## Tech Stack\n[\s\S]*?(?=\n## )/;
+                if (techRegex.test(content)) {
+                    content = content.replace(techRegex, `## Tech Stack\n${answers.techStack}\n`);
+                }
+                else {
+                    // Insert before Progress section
+                    const progressIdx = content.indexOf('\n## Progress');
+                    if (progressIdx !== -1) {
+                        content = content.slice(0, progressIdx) + `\n## Tech Stack\n${answers.techStack}\n` + content.slice(progressIdx);
+                    }
+                }
+            }
+            // Update Additional Context section
+            if (answers.additionalContext) {
+                const ctxRegex = /## Additional Context\n[\s\S]*?(?=\n## )/;
+                if (ctxRegex.test(content)) {
+                    content = content.replace(ctxRegex, `## Additional Context\n${answers.additionalContext}\n`);
+                }
+                else {
+                    const ideaEnd = content.indexOf('\n## ', content.indexOf('## Product Idea') + 1);
+                    if (ideaEnd !== -1) {
+                        content = content.slice(0, ideaEnd) + `\n## Additional Context\n${answers.additionalContext}\n` + content.slice(ideaEnd);
+                    }
+                }
+            }
+            writeFileSync(pmptMdPath, content, 'utf-8');
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: [
+                        `Plan updated:`,
+                        ...changes.map(c => `  - ${c}`),
+                        '',
+                        'Regenerated: plan.md, pmpt.ai.md, pmpt.md (progress preserved)',
+                        'Run pmpt_save to snapshot this change.',
+                    ].join('\n'),
+                }],
+        };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
+    }
+});
 server.tool('pmpt_graduate', 'Graduate a project on pmptwiki — archives it with a Hall of Fame badge. The project can no longer be updated. Non-interactive. User must have run `pmpt login` once before.', {
     slug: z.string().describe('Project slug to graduate.'),
     note: z.string().optional().describe('Graduation note (e.g., "Reached 1000 users!").'),

package/package.json

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