pmpt-cli 1.14.6 → 1.14.7

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

@@ -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).'),

package/package.json

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