pmpt-cli 1.7.0 → 1.8.0

package/README.md

@@ -20,30 +20,9 @@ No coding required. No complex setup. Just answer 5 questions.
 
 ## Demo
 
-```
-$ pmpt plan
-
-┌  pmpt — Let's plan your product!
-│
-◆  What should we call your project?
-│  my-budget-app
-│
-◆  What would you like to build with AI?
-│  A personal budget tracking app for freelancers
-│
-◆  Any additional context AI should know? (optional)
-│  Simple UI, mobile-friendly, works offline
-│
-◆  Key features to include?
-│  Expense tracking; Income categories; Monthly reports; Export to CSV
-│
-◆  Preferred tech stack? (optional)
-│  React, Node.js
-│
-└  Done! AI prompt copied to clipboard.
-
-→ Open Claude / ChatGPT / Cursor → Ctrl+V → Start building!
-```
+<img src="./demo.gif" alt="pmpt plan demo" width="600" />
+
+> Answer 5 questions → AI prompt auto-generated & copied to clipboard → Paste into Claude Code / Codex / Cursor → Start building!
 
 ---
 
@@ -69,7 +48,7 @@ pmpt init
 # 3. Answer 5 questions → AI prompt auto-generated & copied
 pmpt plan
 
-# 4. Paste into Claude / ChatGPT / Cursor → Build your product!
+# 4. Paste into Claude Code / Codex / Cursor → Build your product!
 
 # 5. Save your progress anytime
 pmpt save
@@ -124,13 +103,14 @@ The generated prompt is **automatically copied to your clipboard**. Just paste i
 | `pmpt squash v2 v5` | Merge versions v2–v5 into one |
 | `pmpt export` | Export project as `.pmpt` file |
 | `pmpt import <file>` | Import from `.pmpt` file |
+| `pmpt recover` | Recover damaged pmpt.md via AI-generated prompt |
 
 ### Platform
 
 | Command | Description |
 |---------|-------------|
 | `pmpt login` | Authenticate via GitHub (one-time) |
-| `pmpt publish` | Publish your project for others to discover |
+| `pmpt publish` | Publish your project (requires pmpt.md) |
 | `pmpt edit` | Edit published project metadata (description, tags, category) |
 | `pmpt unpublish` | Remove a published project from pmptwiki |
 | `pmpt clone <slug>` | Clone and reproduce someone's project |

package/dist/commands/browse.js

@@ -64,7 +64,7 @@ export async function cmdBrowse() {
         return;
     }
     if (action === 'url') {
-        const url = `https://pmptwiki.com/ko/p/${project.slug}`;
+        const url = `https://pmptwiki.com/p/${project.slug}`;
         p.log.info(`URL: ${url}`);
         p.log.message(`Download: ${project.downloadUrl}`);
         p.log.message(`\npmpt clone ${project.slug}  — clone via terminal`);

package/dist/commands/clone.js

@@ -1,9 +1,9 @@
 import * as p from '@clack/prompts';
-import { join, dirname } from 'path';
+import { join, dirname, resolve, sep } from 'path';
 import { existsSync, mkdirSync, writeFileSync, readdirSync } from 'fs';
 import { isInitialized, getConfigDir, getHistoryDir, getDocsDir, initializeProject } from '../lib/config.js';
-import { validatePmptFile } from '../lib/pmptFile.js';
-import { fetchPmptFile } from '../lib/api.js';
+import { validatePmptFile, isSafeFilename } from '../lib/pmptFile.js';
+import { fetchPmptFile, trackClone } from '../lib/api.js';
 /**
  * Restore history from .pmpt data (shared with import command)
  */
@@ -15,7 +15,12 @@ export function restoreHistory(historyDir, history) {
         const snapshotDir = join(historyDir, snapshotName);
         mkdirSync(snapshotDir, { recursive: true });
         for (const [filename, content] of Object.entries(version.files)) {
+            if (!isSafeFilename(filename))
+                continue; // skip unsafe filenames
             const filePath = join(snapshotDir, filename);
+            // Double-check resolved path stays within snapshot dir
+            if (!resolve(filePath).startsWith(resolve(snapshotDir) + sep))
+                continue;
             const fileDir = dirname(filePath);
             if (fileDir !== snapshotDir) {
                 mkdirSync(fileDir, { recursive: true });
@@ -36,7 +41,11 @@ export function restoreHistory(historyDir, history) {
 export function restoreDocs(docsDir, docs) {
     mkdirSync(docsDir, { recursive: true });
     for (const [filename, content] of Object.entries(docs)) {
+        if (!isSafeFilename(filename))
+            continue; // skip unsafe filenames
         const filePath = join(docsDir, filename);
+        if (!resolve(filePath).startsWith(resolve(docsDir) + sep))
+            continue;
         const fileDir = dirname(filePath);
         if (fileDir !== docsDir) {
             mkdirSync(fileDir, { recursive: true });
@@ -114,6 +123,8 @@ export async function cmdClone(slug) {
         versionCount = readdirSync(historyDir).filter((d) => d.startsWith('v')).length;
     }
     importSpinner.stop('Restore complete!');
+    // Track clone event (fire-and-forget)
+    trackClone(slug);
     p.note([
         `Project: ${pmptData.meta.projectName}`,
         `Versions: ${versionCount}`,

package/dist/commands/diff.js

@@ -0,0 +1,173 @@
+import * as p from '@clack/prompts';
+import { resolve, join } from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { isInitialized, getDocsDir } from '../lib/config.js';
+import { getAllSnapshots, resolveFullSnapshot } from '../lib/history.js';
+import { diffSnapshots } from '../lib/diff.js';
+import pc from 'picocolors';
+import glob from 'fast-glob';
+/** Read current .pmpt/docs/ as Record<filename, content>. */
+function readWorkingCopy(projectPath) {
+    const docsDir = getDocsDir(projectPath);
+    const files = {};
+    if (!existsSync(docsDir))
+        return files;
+    const mdFiles = glob.sync('**/*.md', { cwd: docsDir });
+    for (const file of mdFiles) {
+        try {
+            files[file] = readFileSync(join(docsDir, file), 'utf-8');
+        }
+        catch {
+            // skip unreadable
+        }
+    }
+    return files;
+}
+/** Format unified diff hunk header. */
+function formatHunkHeader(hunk) {
+    const oldRange = hunk.oldCount === 1 ? `${hunk.oldStart}` : `${hunk.oldStart},${hunk.oldCount}`;
+    const newRange = hunk.newCount === 1 ? `${hunk.newStart}` : `${hunk.newStart},${hunk.newCount}`;
+    return `@@ -${oldRange} +${newRange} @@`;
+}
+/** Print one file's diff to stdout with colors. */
+function printFileDiff(fd) {
+    console.log(pc.bold(`--- a/${fd.fileName}`));
+    console.log(pc.bold(`+++ b/${fd.fileName}`));
+    for (const hunk of fd.hunks) {
+        console.log(pc.cyan(formatHunkHeader(hunk)));
+        for (const line of hunk.lines) {
+            if (line.type === 'add')
+                console.log(pc.green(`+${line.content}`));
+            else if (line.type === 'remove')
+                console.log(pc.red(`-${line.content}`));
+            else
+                console.log(pc.dim(` ${line.content}`));
+        }
+    }
+    console.log('');
+}
+/** Print summary statistics. */
+function printSummary(diffs) {
+    const modified = diffs.filter(d => d.status === 'modified').length;
+    const added = diffs.filter(d => d.status === 'added').length;
+    const removed = diffs.filter(d => d.status === 'removed').length;
+    const parts = [];
+    if (modified > 0)
+        parts.push(`${modified} modified`);
+    if (added > 0)
+        parts.push(`${added} added`);
+    if (removed > 0)
+        parts.push(`${removed} removed`);
+    let additions = 0;
+    let deletions = 0;
+    for (const fd of diffs) {
+        for (const hunk of fd.hunks) {
+            for (const line of hunk.lines) {
+                if (line.type === 'add')
+                    additions++;
+                if (line.type === 'remove')
+                    deletions++;
+            }
+        }
+    }
+    p.log.info(`${diffs.length} file(s) changed: ${parts.join(', ')}`);
+    p.log.info(`${pc.green(`+${additions}`)} additions, ${pc.red(`-${deletions}`)} deletions`);
+}
+export function cmdDiff(v1, v2, pathOrOptions, maybeOptions) {
+    // Commander passes args differently depending on how many positionals are given.
+    // pmpt diff v1 --file x       → (v1, options)
+    // pmpt diff v1 v2             → (v1, v2, options)
+    // pmpt diff v1 v2 /path       → (v1, v2, path, options)
+    let v2Str;
+    let path;
+    let options = {};
+    if (typeof v2 === 'object') {
+        options = v2;
+    }
+    else {
+        v2Str = v2;
+        if (typeof pathOrOptions === 'object') {
+            options = pathOrOptions;
+        }
+        else {
+            path = pathOrOptions;
+            if (maybeOptions)
+                options = maybeOptions;
+        }
+    }
+    const projectPath = path ? resolve(path) : process.cwd();
+    if (!isInitialized(projectPath)) {
+        p.log.error('Project not initialized. Run `pmpt init` first.');
+        process.exit(1);
+    }
+    const fromVersion = parseInt(v1.replace(/^v/, ''), 10);
+    if (isNaN(fromVersion)) {
+        p.log.error('Invalid version format. Use: pmpt diff v1 v2');
+        process.exit(1);
+    }
+    const diffAgainstWorking = v2Str === undefined;
+    let toVersion;
+    if (!diffAgainstWorking) {
+        toVersion = parseInt(v2Str.replace(/^v/, ''), 10);
+        if (isNaN(toVersion)) {
+            p.log.error('Invalid version format. Use: pmpt diff v1 v2');
+            process.exit(1);
+        }
+    }
+    const snapshots = getAllSnapshots(projectPath);
+    if (snapshots.length === 0) {
+        p.log.error('No snapshots found.');
+        process.exit(1);
+    }
+    const fromIndex = snapshots.findIndex(s => s.version === fromVersion);
+    if (fromIndex === -1) {
+        p.log.error(`Version v${fromVersion} not found.`);
+        process.exit(1);
+    }
+    let toIndex;
+    if (!diffAgainstWorking) {
+        toIndex = snapshots.findIndex(s => s.version === toVersion);
+        if (toIndex === -1) {
+            p.log.error(`Version v${toVersion} not found.`);
+            process.exit(1);
+        }
+    }
+    // Resolve file contents
+    const oldFiles = resolveFullSnapshot(snapshots, fromIndex);
+    const newFiles = diffAgainstWorking
+        ? readWorkingCopy(projectPath)
+        : resolveFullSnapshot(snapshots, toIndex);
+    // Optional file filter
+    let filteredOld = oldFiles;
+    let filteredNew = newFiles;
+    if (options.file) {
+        filteredOld = oldFiles[options.file] !== undefined ? { [options.file]: oldFiles[options.file] } : {};
+        filteredNew = newFiles[options.file] !== undefined ? { [options.file]: newFiles[options.file] } : {};
+        if (Object.keys(filteredOld).length === 0 && Object.keys(filteredNew).length === 0) {
+            p.log.error(`File "${options.file}" not found in either version.`);
+            process.exit(1);
+        }
+    }
+    const diffs = diffSnapshots(filteredOld, filteredNew);
+    const targetLabel = diffAgainstWorking ? 'working copy' : `v${toVersion}`;
+    p.intro(`pmpt diff v${fromVersion} → ${targetLabel}`);
+    if (diffs.length === 0) {
+        p.log.info('No differences found.');
+        p.outro('');
+        return;
+    }
+    // Changed files list
+    const fileList = diffs.map(d => {
+        const icon = d.status === 'added' ? pc.green('A')
+            : d.status === 'removed' ? pc.red('D')
+                : pc.yellow('M');
+        return `  ${icon}  ${d.fileName}`;
+    }).join('\n');
+    p.note(fileList, 'Changed files');
+    console.log('');
+    for (const fd of diffs) {
+        printFileDiff(fd);
+    }
+    printSummary(diffs);
+    p.outro('');
+}

package/dist/commands/import.js

@@ -1,8 +1,8 @@
 import * as p from '@clack/prompts';
-import { resolve, join, dirname } from 'path';
-import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'fs';
+import { resolve, join, dirname, sep } from 'path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, rmSync } from 'fs';
 import { isInitialized, getConfigDir, getHistoryDir, getDocsDir, initializeProject } from '../lib/config.js';
-import { validatePmptFile } from '../lib/pmptFile.js';
+import { validatePmptFile, isSafeFilename } from '../lib/pmptFile.js';
 /**
  * Restore history from .pmpt file
  */
@@ -13,9 +13,13 @@ function restoreHistory(historyDir, history) {
         const snapshotName = `v${version.version}-${timestamp}`;
         const snapshotDir = join(historyDir, snapshotName);
         mkdirSync(snapshotDir, { recursive: true });
-        // Write files
+        // Write files (with path traversal protection)
         for (const [filename, content] of Object.entries(version.files)) {
+            if (!isSafeFilename(filename))
+                continue;
             const filePath = join(snapshotDir, filename);
+            if (!resolve(filePath).startsWith(resolve(snapshotDir) + sep))
+                continue;
             const fileDir = dirname(filePath);
             if (fileDir !== snapshotDir) {
                 mkdirSync(fileDir, { recursive: true });
@@ -38,7 +42,11 @@ function restoreHistory(historyDir, history) {
 function restoreDocs(docsDir, docs) {
     mkdirSync(docsDir, { recursive: true });
     for (const [filename, content] of Object.entries(docs)) {
+        if (!isSafeFilename(filename))
+            continue;
         const filePath = join(docsDir, filename);
+        if (!resolve(filePath).startsWith(resolve(docsDir) + sep))
+            continue;
         const fileDir = dirname(filePath);
         if (fileDir !== docsDir) {
             mkdirSync(fileDir, { recursive: true });
@@ -112,13 +120,23 @@ export async function cmdImport(pmptFile, options) {
     }
     const importSpinner = p.spinner();
     importSpinner.start('Importing project...');
+    const pmptDir = getConfigDir(projectPath);
+    const historyDir = getHistoryDir(projectPath);
+    const docsDir = getDocsDir(projectPath);
+    // --force: clean existing history and docs before restoring
+    if (options?.force && isInitialized(projectPath)) {
+        if (existsSync(historyDir))
+            rmSync(historyDir, { recursive: true, force: true });
+        if (existsSync(docsDir))
+            rmSync(docsDir, { recursive: true, force: true });
+        const planPath = join(pmptDir, 'plan-progress.json');
+        if (existsSync(planPath))
+            rmSync(planPath, { force: true });
+    }
     // Initialize project if not exists
     if (!isInitialized(projectPath)) {
         initializeProject(projectPath, { trackGit: true });
     }
-    const pmptDir = getConfigDir(projectPath);
-    const historyDir = getHistoryDir(projectPath);
-    const docsDir = getDocsDir(projectPath);
     // Restore history
     restoreHistory(historyDir, pmptData.history);
     // Restore docs

package/dist/commands/init.js

@@ -185,7 +185,7 @@ export async function cmdInit(path, options) {
                     `   Location: ${planPath}`,
                     '',
                     `2. pmpt.md — AI prompt (THE IMPORTANT ONE!)`,
-                    `   Copy this to Claude/ChatGPT/Codex`,
+                    `   Copy this to Claude Code / Codex / Cursor`,
                     `   Location: ${promptPath}`,
                 ];
                 p.note(docExplanation.join('\n'), 'Auto-generated from project scan');

package/dist/commands/plan.js

@@ -160,7 +160,7 @@ export async function cmdPlan(path, options) {
         `   Location: ${planPath}`,
         '',
         `2. pmpt.md — AI prompt (THE IMPORTANT ONE!)`,
-        `   • Copy this to Claude/ChatGPT/Codex`,
+        `   • Copy this to Claude Code / Codex / Cursor`,
         `   • AI will help you build step by step`,
         `   • AI will update this doc as you progress`,
         `   Location: ${promptPath}`,

package/dist/commands/publish.js

@@ -7,6 +7,8 @@ import { getPlanProgress } from '../lib/plan.js';
 import { createPmptFile } from '../lib/pmptFile.js';
 import { loadAuth } from '../lib/auth.js';
 import { publishProject, fetchProjects } from '../lib/api.js';
+import { computeQuality } from '../lib/quality.js';
+import pc from 'picocolors';
 import glob from 'fast-glob';
 import { join } from 'path';
 function readDocsFolder(docsDir) {
@@ -22,7 +24,7 @@ function readDocsFolder(docsDir) {
     }
     return files;
 }
-export async function cmdPublish(path) {
+export async function cmdPublish(path, options) {
     const projectPath = path ? resolve(path) : process.cwd();
     if (!isInitialized(projectPath)) {
         p.log.error('Project not initialized. Run `pmpt init` first.');
@@ -42,6 +44,50 @@ export async function cmdPublish(path) {
         p.outro('');
         return;
     }
+    // Validate pmpt.md exists and has content
+    const pmptMdPath = join(getDocsDir(projectPath), 'pmpt.md');
+    if (!existsSync(pmptMdPath)) {
+        p.log.error('pmpt.md not found. Run `pmpt plan` to generate it first.');
+        process.exit(1);
+    }
+    const pmptMdContent = readFileSync(pmptMdPath, 'utf-8').trim();
+    if (pmptMdContent.length === 0) {
+        p.log.error('pmpt.md is empty. Run `pmpt plan` to generate content.');
+        process.exit(1);
+    }
+    // Quality gate
+    const docsDir = getDocsDir(projectPath);
+    const trackedFiles = glob.sync('**/*.md', { cwd: docsDir });
+    const hasGit = snapshots.some(s => !!s.git);
+    const quality = computeQuality({
+        pmptMd: pmptMdContent,
+        planAnswers: planProgress?.answers ?? null,
+        versionCount: snapshots.length,
+        docFiles: trackedFiles,
+        hasGit,
+    });
+    const gradeColor = quality.grade === 'A' ? pc.green
+        : quality.grade === 'B' ? pc.blue
+            : quality.grade === 'C' ? pc.yellow
+                : pc.red;
+    const qLines = [`Score: ${gradeColor(`${quality.score}/100`)} (Grade ${gradeColor(quality.grade)})`];
+    for (const item of quality.details) {
+        const icon = item.score === item.maxScore ? pc.green('✓') : pc.red('✗');
+        qLines.push(`${icon}  ${item.label.padEnd(20)} ${item.score}/${item.maxScore}`);
+    }
+    p.note(qLines.join('\n'), 'Quality Score');
+    if (!quality.passesMinimum) {
+        const tips = quality.details.filter(d => d.tip).map(d => `  → ${d.tip}`);
+        p.log.warn(`Quality score ${quality.score}/100 is below minimum (40).`);
+        if (tips.length > 0) {
+            p.log.info('How to improve:\n' + tips.join('\n'));
+        }
+        if (!options?.force) {
+            p.log.error('Use `pmpt publish --force` to publish anyway.');
+            process.exit(1);
+        }
+        p.log.warn('Publishing with --force despite low quality score.');
+    }
     const projectName = planProgress?.answers?.projectName || basename(projectPath);
     // Try to load existing published data for prefill
     let existing;
@@ -117,7 +163,6 @@ export async function cmdPublish(path) {
         files: resolveFullSnapshot(snapshots, i),
         git: snapshot.git,
     }));
-    const docsDir = getDocsDir(projectPath);
     const docs = readDocsFolder(docsDir);
     const meta = {
         projectName,

package/dist/commands/recover.js

@@ -0,0 +1,222 @@
+import * as p from '@clack/prompts';
+import { resolve, basename } from 'path';
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import { isInitialized, getDocsDir } from '../lib/config.js';
+import { getAllSnapshots, resolveFileContent } from '../lib/history.js';
+import { getPlanProgress } from '../lib/plan.js';
+import { copyToClipboard } from '../lib/clipboard.js';
+export async function cmdRecover(path) {
+    const projectPath = path ? resolve(path) : process.cwd();
+    if (!isInitialized(projectPath)) {
+        p.log.error('Project not initialized. Run `pmpt init` first.');
+        process.exit(1);
+    }
+    p.intro('pmpt recover');
+    const docsDir = getDocsDir(projectPath);
+    const pmptMdPath = join(docsDir, 'pmpt.md');
+    const planMdPath = join(docsDir, 'plan.md');
+    // Check current state
+    const currentExists = existsSync(pmptMdPath);
+    const currentContent = currentExists ? readFileSync(pmptMdPath, 'utf-8').trim() : '';
+    if (currentExists && currentContent.length > 100) {
+        const proceed = await p.confirm({
+            message: `pmpt.md exists (${currentContent.length} chars). Overwrite with recovered version?`,
+            initialValue: false,
+        });
+        if (p.isCancel(proceed) || !proceed) {
+            p.cancel('Cancelled');
+            process.exit(0);
+        }
+    }
+    // Gather all available context
+    const context = [];
+    // 1. Plan progress answers
+    const planProgress = getPlanProgress(projectPath);
+    if (planProgress?.answers) {
+        const a = planProgress.answers;
+        context.push('## Project Plan Answers');
+        if (a.projectName)
+            context.push(`- **Project Name**: ${a.projectName}`);
+        if (a.productIdea)
+            context.push(`- **Product Idea**: ${a.productIdea}`);
+        if (a.coreFeatures)
+            context.push(`- **Core Features**: ${a.coreFeatures}`);
+        if (a.techStack)
+            context.push(`- **Tech Stack**: ${a.techStack}`);
+        if (a.additionalContext)
+            context.push(`- **Additional Context**: ${a.additionalContext}`);
+        context.push('');
+    }
+    // 2. plan.md content
+    if (existsSync(planMdPath)) {
+        const planMd = readFileSync(planMdPath, 'utf-8').trim();
+        if (planMd) {
+            context.push('## Current plan.md');
+            context.push('```markdown');
+            context.push(planMd);
+            context.push('```');
+            context.push('');
+        }
+    }
+    // 3. Last known good pmpt.md from history
+    const snapshots = getAllSnapshots(projectPath);
+    let lastPmptMd = null;
+    let lastPmptVersion = 0;
+    if (snapshots.length > 0) {
+        for (let i = snapshots.length - 1; i >= 0; i--) {
+            const content = resolveFileContent(snapshots, i, 'pmpt.md');
+            if (content && content.trim().length > 50) {
+                lastPmptMd = content;
+                lastPmptVersion = snapshots[i].version;
+                break;
+            }
+        }
+    }
+    if (lastPmptMd) {
+        context.push(`## Last Known pmpt.md (from v${lastPmptVersion})`);
+        context.push('```markdown');
+        context.push(lastPmptMd);
+        context.push('```');
+        context.push('');
+    }
+    // 4. package.json info
+    const pkgPath = join(projectPath, 'package.json');
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+            context.push('## package.json');
+            const fields = [];
+            if (pkg.name)
+                fields.push(`- **name**: ${pkg.name}`);
+            if (pkg.description)
+                fields.push(`- **description**: ${pkg.description}`);
+            if (pkg.dependencies)
+                fields.push(`- **dependencies**: ${Object.keys(pkg.dependencies).join(', ')}`);
+            if (pkg.devDependencies)
+                fields.push(`- **devDependencies**: ${Object.keys(pkg.devDependencies).join(', ')}`);
+            if (pkg.scripts)
+                fields.push(`- **scripts**: ${Object.keys(pkg.scripts).join(', ')}`);
+            context.push(fields.join('\n'));
+            context.push('');
+        }
+        catch { /* skip */ }
+    }
+    // 5. Directory structure
+    const dirEntries = readdirTopLevel(projectPath);
+    if (dirEntries.length > 0) {
+        context.push('## Project Structure');
+        context.push(dirEntries.join('\n'));
+        context.push('');
+    }
+    if (context.length === 0) {
+        p.log.error('No project context found. Nothing to recover from.');
+        process.exit(1);
+    }
+    // Show what we found
+    const sources = [];
+    if (planProgress?.answers)
+        sources.push('plan answers');
+    if (existsSync(planMdPath))
+        sources.push('plan.md');
+    if (lastPmptMd)
+        sources.push(`history v${lastPmptVersion}`);
+    if (existsSync(pkgPath))
+        sources.push('package.json');
+    p.log.info(`Found context: ${sources.join(', ')}`);
+    // Build recovery prompt
+    const projectName = planProgress?.answers?.projectName || basename(projectPath);
+    const prompt = `# pmpt.md Recovery Request
+
+I need you to regenerate the \`.pmpt/docs/pmpt.md\` file for my project "${projectName}".
+
+This file is the main AI prompt document — it contains the product development context that gets pasted into AI tools (Claude Code, Codex, Cursor, etc.) to continue development.
+
+## Available Context
+
+${context.join('\n')}
+
+## Instructions
+
+Based on the context above, regenerate \`.pmpt/docs/pmpt.md\` with the following structure:
+
+\`\`\`
+# {Project Name} — Product Development Request
+
+## What I Want to Build
+{describe the product idea}
+
+## Key Features
+- {feature 1}
+- {feature 2}
+...
+
+## Tech Stack Preferences
+{detected or specified tech stack}
+
+## Additional Context
+{any extra context}
+
+---
+
+Please help me build this product based on the requirements above.
+
+1. First, review the requirements and ask if anything is unclear.
+2. Propose a technical architecture.
+3. Outline the implementation steps.
+4. Start coding from the first step.
+
+I'll confirm progress at each step before moving to the next.
+
+## Documentation Rule
+
+**Important:** Update this document (located at \`.pmpt/docs/pmpt.md\`) at these moments:
+- When architecture or tech decisions are finalized
+- When a feature is implemented (mark as done)
+- When a development phase is completed
+- When requirements change or new decisions are made
+\`\`\`
+
+${lastPmptMd ? 'Use the "Last Known pmpt.md" as the primary reference — update it rather than starting from scratch.' : 'Generate a fresh pmpt.md based on the available context.'}
+
+Write the content directly to \`.pmpt/docs/pmpt.md\`. After writing, run \`pmpt save\` to create a snapshot.`;
+    // Copy to clipboard
+    const copied = copyToClipboard(prompt);
+    if (copied) {
+        p.log.success('Recovery prompt copied to clipboard!');
+    }
+    else {
+        p.log.warn('Could not copy to clipboard. Prompt printed below:');
+        console.log('\n' + prompt + '\n');
+    }
+    p.note([
+        '1. Paste the prompt into your AI tool (Claude Code, Cursor, etc.)',
+        '2. The AI will regenerate .pmpt/docs/pmpt.md',
+        '3. Run `pmpt save` to snapshot the recovered file',
+    ].join('\n'), 'Next Steps');
+    p.outro('');
+}
+function readdirTopLevel(projectPath) {
+    const ignore = new Set([
+        'node_modules', '.git', '.pmpt', 'dist', 'build', '.next',
+        '.nuxt', '.astro', '.vercel', '.cache', 'coverage', '.turbo',
+    ]);
+    try {
+        const entries = readdirSync(projectPath, { encoding: 'utf-8' });
+        return entries
+            .filter(e => !ignore.has(e) && !e.startsWith('.'))
+            .slice(0, 30)
+            .map(e => {
+            try {
+                const stat = statSync(join(projectPath, e));
+                return stat.isDirectory() ? `${e}/` : e;
+            }
+            catch {
+                return e;
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}

package/dist/commands/status.js

@@ -1,7 +1,11 @@
 import * as p from '@clack/prompts';
-import { resolve } from 'path';
-import { isInitialized, loadConfig } from '../lib/config.js';
+import { resolve, join } from 'path';
+import { readFileSync, existsSync } from 'fs';
+import { isInitialized, loadConfig, getDocsDir } from '../lib/config.js';
 import { getTrackedFiles, getAllSnapshots } from '../lib/history.js';
+import { getPlanProgress } from '../lib/plan.js';
+import { computeQuality } from '../lib/quality.js';
+import pc from 'picocolors';
 export function cmdStatus(path) {
     const projectPath = path ? resolve(path) : process.cwd();
     if (!isInitialized(projectPath)) {
@@ -31,5 +35,39 @@ export function cmdStatus(path) {
         notes.push('  (none - start with pmpt plan)');
     }
     p.note(notes.join('\n'), 'Project Info');
+    // Quality Score
+    const docsDir = getDocsDir(projectPath);
+    const pmptMdPath = join(docsDir, 'pmpt.md');
+    const pmptMd = existsSync(pmptMdPath) ? readFileSync(pmptMdPath, 'utf-8') : null;
+    const planProgress = getPlanProgress(projectPath);
+    const hasGit = snapshots.some(s => !!s.git);
+    const quality = computeQuality({
+        pmptMd,
+        planAnswers: planProgress?.answers ?? null,
+        versionCount: snapshots.length,
+        docFiles: tracked,
+        hasGit,
+    });
+    const gradeColor = quality.grade === 'A' ? pc.green
+        : quality.grade === 'B' ? pc.blue
+            : quality.grade === 'C' ? pc.yellow
+                : pc.red;
+    const qLines = [
+        `Score: ${gradeColor(`${quality.score}/100`)} (Grade ${gradeColor(quality.grade)})`,
+        '',
+    ];
+    for (const item of quality.details) {
+        const icon = item.score === item.maxScore ? pc.green('✓') : pc.red('✗');
+        const scoreStr = `${item.score}/${item.maxScore}`.padStart(5);
+        qLines.push(`${icon}  ${item.label.padEnd(20)} ${scoreStr}`);
+    }
+    const tips = quality.details.filter(d => d.tip).map(d => d.tip);
+    if (tips.length > 0) {
+        qLines.push('');
+        for (const tip of tips) {
+            qLines.push(`${pc.dim('→')} ${tip}`);
+        }
+    }
+    p.note(qLines.join('\n'), 'Quality Score');
     p.outro('');
 }

package/dist/index.js

@@ -15,6 +15,8 @@ import { cmdEdit } from './commands/edit.js';
 import { cmdUnpublish } from './commands/unpublish.js';
 import { cmdClone } from './commands/clone.js';
 import { cmdBrowse } from './commands/browse.js';
+import { cmdRecover } from './commands/recover.js';
+import { cmdDiff } from './commands/diff.js';
 const program = new Command();
 program
     .name('pmpt')
@@ -27,6 +29,8 @@ Examples:
   $ pmpt save                    Save snapshot of docs folder
   $ pmpt watch                   Auto-detect file changes
   $ pmpt history                 View version history
+  $ pmpt diff v1 v2              Compare two versions
+  $ pmpt diff v3                 Compare v3 to working copy
   $ pmpt squash v2 v5            Merge versions v2-v5 into v2
   $ pmpt export                  Export as .pmpt file (single JSON)
   $ pmpt import <file.pmpt>      Import from .pmpt file
@@ -34,6 +38,7 @@ Examples:
   $ pmpt publish                 Publish project to pmptwiki
   $ pmpt clone <slug>            Clone a project from pmptwiki
   $ pmpt browse                  Browse published projects
+  $ pmpt recover                 Recover damaged pmpt.md via AI
 
 Documentation: https://pmptwiki.com
 `);
@@ -60,18 +65,23 @@ program
     .description('View saved version history')
     .option('-c, --compact', 'Show compact history (hide small changes)')
     .action(cmdHistory);
+program
+    .command('diff <v1> [v2] [path]')
+    .description('Compare two versions (or version vs working copy)')
+    .option('-f, --file <name>', 'Compare specific file only')
+    .action(cmdDiff);
 program
     .command('squash <from> <to> [path]')
     .description('Squash multiple versions into one (e.g., pmpt squash v2 v5)')
     .action(cmdSquash);
 program
     .command('export [path]')
-    .description('Export project history as a shareable zip archive')
+    .description('Export project history as a shareable .pmpt file')
     .option('-o, --output <file>', 'Output file path')
     .action(cmdExport);
 program
     .command('import <file>')
-    .description('Import project from exported zip archive')
+    .description('Import project from .pmpt file')
     .option('-f, --force', 'Overwrite existing project')
     .action(cmdImport);
 program
@@ -95,6 +105,7 @@ program
 program
     .command('publish [path]')
     .description('Publish project to pmptwiki platform')
+    .option('--force', 'Publish even if quality score is below minimum')
     .action(cmdPublish);
 program
     .command('edit')
@@ -112,4 +123,8 @@ program
     .command('browse')
     .description('Browse and search published projects')
     .action(cmdBrowse);
+program
+    .command('recover [path]')
+    .description('Generate a recovery prompt to regenerate pmpt.md via AI')
+    .action(cmdRecover);
 program.parse();

package/dist/lib/api.js

@@ -81,3 +81,14 @@ export async function fetchPmptFile(slug) {
     }
     return res.text();
 }
+/**
+ * Fire-and-forget clone tracking ping.
+ * Never throws — failures are silently ignored.
+ */
+export function trackClone(slug) {
+    fetch(`${API_BASE}/metrics/clone`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ slug }),
+    }).catch(() => { });
+}

package/dist/lib/diff.js

@@ -0,0 +1,143 @@
+/**
+ * Simple unified diff implementation using LCS (Longest Common Subsequence).
+ * Pure functions — no file I/O, no UI.
+ */
+/** LCS DP table — O(n*m), fine for markdown files (<500 lines). */
+function lcsTable(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            if (a[i - 1] === b[j - 1]) {
+                dp[i][j] = dp[i - 1][j - 1] + 1;
+            }
+            else {
+                dp[i][j] = Math.max(dp[i - 1][j], dp[i][j - 1]);
+            }
+        }
+    }
+    return dp;
+}
+/** Backtrack LCS table → ordered DiffLine array. */
+function backtrack(dp, a, b) {
+    const result = [];
+    let i = a.length;
+    let j = b.length;
+    while (i > 0 || j > 0) {
+        if (i > 0 && j > 0 && a[i - 1] === b[j - 1]) {
+            result.push({ type: 'context', content: a[i - 1] });
+            i--;
+            j--;
+        }
+        else if (j > 0 && (i === 0 || dp[i][j - 1] >= dp[i - 1][j])) {
+            result.push({ type: 'add', content: b[j - 1] });
+            j--;
+        }
+        else {
+            result.push({ type: 'remove', content: a[i - 1] });
+            i--;
+        }
+    }
+    return result.reverse();
+}
+/** Build a DiffHunk from a slice of diff lines. */
+function buildHunk(lines, start, end) {
+    const hunkLines = lines.slice(start, end + 1);
+    let oldLine = 1;
+    let newLine = 1;
+    for (let i = 0; i < start; i++) {
+        if (lines[i].type === 'context' || lines[i].type === 'remove')
+            oldLine++;
+        if (lines[i].type === 'context' || lines[i].type === 'add')
+            newLine++;
+    }
+    let oldCount = 0;
+    let newCount = 0;
+    for (const line of hunkLines) {
+        if (line.type === 'context' || line.type === 'remove')
+            oldCount++;
+        if (line.type === 'context' || line.type === 'add')
+            newCount++;
+    }
+    return { oldStart: oldLine, oldCount, newStart: newLine, newCount, lines: hunkLines };
+}
+/** Group diff lines into hunks with context (default 3 lines, like git). */
+function groupIntoHunks(lines, contextLines = 3) {
+    const changeIndices = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].type !== 'context')
+            changeIndices.push(i);
+    }
+    if (changeIndices.length === 0)
+        return [];
+    const hunks = [];
+    let hunkStart = Math.max(0, changeIndices[0] - contextLines);
+    let hunkEnd = Math.min(lines.length - 1, changeIndices[0] + contextLines);
+    for (let k = 1; k < changeIndices.length; k++) {
+        const nextStart = Math.max(0, changeIndices[k] - contextLines);
+        const nextEnd = Math.min(lines.length - 1, changeIndices[k] + contextLines);
+        if (nextStart <= hunkEnd + 1) {
+            hunkEnd = nextEnd;
+        }
+        else {
+            hunks.push(buildHunk(lines, hunkStart, hunkEnd));
+            hunkStart = nextStart;
+            hunkEnd = nextEnd;
+        }
+    }
+    hunks.push(buildHunk(lines, hunkStart, hunkEnd));
+    return hunks;
+}
+/** Normalize trailing newline from split. */
+function splitLines(content) {
+    const lines = content.split('\n');
+    if (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    return lines;
+}
+/** Compute unified diff hunks between two strings. */
+export function computeDiff(oldContent, newContent) {
+    const oldLines = splitLines(oldContent);
+    const newLines = splitLines(newContent);
+    const dp = lcsTable(oldLines, newLines);
+    const diffLines = backtrack(dp, oldLines, newLines);
+    return groupIntoHunks(diffLines);
+}
+/** Diff a single file between two versions. */
+export function diffFile(fileName, oldContent, newContent) {
+    if (oldContent === null && newContent === null) {
+        return { fileName, status: 'unchanged', hunks: [] };
+    }
+    if (oldContent === null) {
+        const lines = splitLines(newContent).map(l => ({ type: 'add', content: l }));
+        return {
+            fileName,
+            status: 'added',
+            hunks: lines.length > 0 ? [{ oldStart: 0, oldCount: 0, newStart: 1, newCount: lines.length, lines }] : [],
+        };
+    }
+    if (newContent === null) {
+        const lines = splitLines(oldContent).map(l => ({ type: 'remove', content: l }));
+        return {
+            fileName,
+            status: 'removed',
+            hunks: lines.length > 0 ? [{ oldStart: 1, oldCount: lines.length, newStart: 0, newCount: 0, lines }] : [],
+        };
+    }
+    if (oldContent === newContent) {
+        return { fileName, status: 'unchanged', hunks: [] };
+    }
+    return { fileName, status: 'modified', hunks: computeDiff(oldContent, newContent) };
+}
+/** Diff all files between two snapshots (Record<filename, content>). */
+export function diffSnapshots(oldFiles, newFiles) {
+    const allNames = new Set([...Object.keys(oldFiles), ...Object.keys(newFiles)]);
+    const diffs = [];
+    for (const name of [...allNames].sort()) {
+        const fd = diffFile(name, oldFiles[name] ?? null, newFiles[name] ?? null);
+        if (fd.status !== 'unchanged')
+            diffs.push(fd);
+    }
+    return diffs;
+}

package/dist/lib/pmptFile.js

@@ -4,9 +4,36 @@
  * Single JSON file format for sharing pmpt projects.
  */
 import { z } from 'zod';
+import { resolve, relative } from 'path';
 // Schema version
 export const SCHEMA_VERSION = '1.0';
 export const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
+/**
+ * Validate that a filename is safe (no path traversal).
+ * Rejects absolute paths, ".." components, and backslash paths.
+ */
+export function isSafeFilename(filename) {
+    if (!filename || filename.length === 0)
+        return false;
+    // Reject absolute paths and backslashes
+    if (/^[/\\]/.test(filename) || /\\/.test(filename))
+        return false;
+    // Reject .. path components
+    const parts = filename.split('/');
+    if (parts.some(p => p === '..' || p === '.'))
+        return false;
+    // Double check: resolve and verify it stays within parent
+    const base = '/safe';
+    const resolved = resolve(base, filename);
+    const rel = relative(base, resolved);
+    if (rel.startsWith('..') || resolve(rel) !== resolve(base, rel))
+        return false;
+    return true;
+}
+// Safe filename zod refinement
+const safeFilenameKey = z.string().refine(isSafeFilename, {
+    message: 'Unsafe filename detected (path traversal)',
+});
 // Git info schema
 const GitInfoSchema = z.object({
     commit: z.string(),
@@ -20,7 +47,7 @@ const VersionSchema = z.object({
     version: z.number().min(1),
     timestamp: z.string(),
     summary: z.string().optional(),
-    files: z.record(z.string(), z.string()), // filename -> content
+    files: z.record(safeFilenameKey, z.string()), // filename -> content
     git: GitInfoSchema,
 });
 // Plan answers schema
@@ -46,7 +73,7 @@ export const PmptFileSchema = z.object({
     guide: z.string().optional(),
     meta: MetaSchema,
     plan: PlanSchema,
-    docs: z.record(z.string(), z.string()).optional(), // current docs
+    docs: z.record(safeFilenameKey, z.string()).optional(), // current docs
     history: z.array(VersionSchema),
 });
 /**

package/dist/lib/quality.js

@@ -0,0 +1,103 @@
+/**
+ * Project quality score calculation.
+ * Pure functions — no I/O, reusable in CLI and API.
+ */
+const MIN_PUBLISH_SCORE = 40;
+export function computeQuality(data) {
+    const details = [];
+    // 1. pmpt.md content (30 points)
+    {
+        let score = 0;
+        let tip;
+        const len = data.pmptMd?.trim().length ?? 0;
+        if (len > 0)
+            score += 10;
+        if (len >= 200)
+            score += 10;
+        if (len >= 500)
+            score += 10;
+        if (score < 30) {
+            tip = len === 0
+                ? 'Run `pmpt plan` to generate pmpt.md'
+                : `pmpt.md is ${len} chars — expand to 500+ for full score`;
+        }
+        details.push({ label: 'pmpt.md content', score, maxScore: 30, tip });
+    }
+    // 2. Plan completeness (25 points)
+    {
+        let score = 0;
+        let tip;
+        if (data.planAnswers?.productIdea?.trim())
+            score += 10;
+        if (data.planAnswers?.coreFeatures?.trim())
+            score += 10;
+        if (data.planAnswers?.techStack?.trim())
+            score += 5;
+        if (score < 25) {
+            const missing = [];
+            if (!data.planAnswers?.productIdea?.trim())
+                missing.push('product idea');
+            if (!data.planAnswers?.coreFeatures?.trim())
+                missing.push('core features');
+            if (!data.planAnswers?.techStack?.trim())
+                missing.push('tech stack');
+            tip = `Complete plan: add ${missing.join(', ')}`;
+        }
+        details.push({ label: 'Plan completeness', score, maxScore: 25, tip });
+    }
+    // 3. Version history (20 points)
+    {
+        let score = 0;
+        let tip;
+        if (data.versionCount >= 2)
+            score += 10;
+        if (data.versionCount >= 3)
+            score += 10;
+        if (score < 20) {
+            tip = data.versionCount < 2
+                ? 'Save more versions with `pmpt save`'
+                : 'One more version for full score';
+        }
+        details.push({ label: 'Version history', score, maxScore: 20, tip });
+    }
+    // 4. Documentation files (15 points)
+    {
+        let score = 0;
+        let tip;
+        if (data.docFiles.includes('plan.md'))
+            score += 5;
+        if (data.docFiles.includes('pmpt.md'))
+            score += 5;
+        if (data.docFiles.length > 2)
+            score += 5;
+        if (score < 15) {
+            const missing = [];
+            if (!data.docFiles.includes('plan.md'))
+                missing.push('plan.md');
+            if (!data.docFiles.includes('pmpt.md'))
+                missing.push('pmpt.md');
+            if (data.docFiles.length <= 2)
+                missing.push('additional docs');
+            tip = `Add: ${missing.join(', ')}`;
+        }
+        details.push({ label: 'Documentation', score, maxScore: 15, tip });
+    }
+    // 5. Git integration (10 points)
+    {
+        let score = 0;
+        let tip;
+        if (data.hasGit)
+            score = 10;
+        else
+            tip = 'Initialize git repo for commit tracking';
+        details.push({ label: 'Git integration', score, maxScore: 10, tip });
+    }
+    const total = details.reduce((sum, d) => sum + d.score, 0);
+    const grade = total >= 80 ? 'A' : total >= 60 ? 'B' : total >= 40 ? 'C' : total >= 20 ? 'D' : 'F';
+    return {
+        score: total,
+        details,
+        grade,
+        passesMinimum: total >= MIN_PUBLISH_SCORE,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmpt-cli",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Record and share your AI-driven product development journey",
   "type": "module",
   "bin": {
@@ -39,6 +39,7 @@
     "commander": "^12.0.0",
     "fast-glob": "^3.3.0",
     "open": "^11.0.0",
+    "picocolors": "^1.0.0",
     "zod": "^3.22.0"
   },
   "devDependencies": {