pmpt-cli 1.10.0 → 1.11.1

package/dist/commands/clone.js

@@ -4,6 +4,7 @@ import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync } from
 import { isInitialized, getConfigDir, getHistoryDir, getDocsDir, initializeProject } from '../lib/config.js';
 import { validatePmptFile, isSafeFilename } from '../lib/pmptFile.js';
 import { fetchPmptFile, trackClone } from '../lib/api.js';
+import { copyToClipboard } from '../lib/clipboard.js';
 /**
  * Restore history from .pmpt data (shared with import command)
  */
@@ -147,6 +148,19 @@ export async function cmdClone(slug) {
         '',
         '---',
         '',
+        `## Documentation Rule`,
+        '',
+        `**Important:** When you make progress, update \`.pmpt/docs/pmpt.md\` (the human-facing project document) 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`,
+        '',
+        `Keep the Progress and Snapshot Log sections in pmpt.md up to date.`,
+        `After significant milestones, run \`pmpt save\` to create a snapshot.`,
+        '',
+        '---',
+        '',
         originalAiMd,
     ].join('\n');
     writeFileSync(aiMdPath, cloneGuide, 'utf-8');
@@ -170,9 +184,38 @@ export async function cmdClone(slug) {
         `Versions: ${versionCount}`,
         `Location: ${pmptDir}`,
     ].join('\n'), 'Clone Summary');
-    p.log.info('Next steps:');
+    // Copy AI prompt to clipboard
+    const aiContent = readFileSync(aiMdPath, 'utf-8');
+    const copied = copyToClipboard(aiContent);
+    if (copied) {
+        p.log.message('');
+        p.log.success('AI prompt copied to clipboard!');
+        p.log.message('');
+        const banner = [
+            '',
+            '┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓',
+            '┃                                                        ┃',
+            '┃   📋  NEXT STEP                                        ┃',
+            '┃                                                        ┃',
+            '┃   Open your AI coding tool and press:           ┃',
+            '┃                                                        ┃',
+            '┃              ⌘ + V  (Mac)                              ┃',
+            '┃             Ctrl + V (Windows/Linux)                   ┃',
+            '┃                                                        ┃',
+            '┃   Your cloned project context is ready! 🚀             ┃',
+            '┃                                                        ┃',
+            '┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛',
+            '',
+        ];
+        console.log(banner.join('\n'));
+    }
+    else {
+        p.log.warn('Could not copy to clipboard.');
+        p.log.info(`Read it at: ${aiMdPath}`);
+    }
+    p.log.info('Tips:');
     p.log.message('  pmpt history    — view version history');
-    p.log.message('  pmpt plan       — view AI prompt');
+    p.log.message('  pmpt plan       — view or edit AI prompt');
     p.log.message('  pmpt save       — save a new snapshot');
     p.outro('Project cloned!');
 }

package/dist/commands/edit.js

@@ -79,6 +79,47 @@ export async function cmdEdit() {
         p.cancel('Cancelled');
         process.exit(0);
     }
+    // Product link (optional)
+    const linkTypeInput = await p.select({
+        message: 'Product link (optional):',
+        initialValue: project.productUrlType || 'none',
+        options: [
+            { value: 'none', label: 'No link' },
+            { value: 'git', label: 'Git Repository' },
+            { value: 'url', label: 'Website / URL' },
+        ],
+    });
+    if (p.isCancel(linkTypeInput)) {
+        p.cancel('Cancelled');
+        process.exit(0);
+    }
+    let productUrl = '';
+    let productUrlType = '';
+    if (linkTypeInput !== 'none') {
+        productUrlType = linkTypeInput;
+        const productUrlInput = await p.text({
+            message: 'Product URL:',
+            placeholder: linkTypeInput === 'git'
+                ? `https://github.com/${auth.username}/${slug}`
+                : 'https://...',
+            defaultValue: project.productUrl || '',
+            validate: (v) => {
+                if (!v.trim())
+                    return 'URL is required when link type is selected.';
+                try {
+                    new URL(v);
+                }
+                catch {
+                    return 'Invalid URL format.';
+                }
+            },
+        });
+        if (p.isCancel(productUrlInput)) {
+            p.cancel('Cancelled');
+            process.exit(0);
+        }
+        productUrl = productUrlInput;
+    }
     const s2 = p.spinner();
     s2.start('Updating...');
     try {
@@ -86,6 +127,8 @@ export async function cmdEdit() {
             description: description,
             tags,
             category: category,
+            productUrl,
+            productUrlType,
         });
         s2.stop('Updated!');
         p.log.success(`Project "${slug}" has been updated.`);

package/dist/commands/hist.js

@@ -75,8 +75,12 @@ export function cmdHistory(path, options) {
             if (snapshot.git.dirty)
                 header += ' (dirty)';
         }
-        const files = snapshot.files.map((f) => `  - ${f}`).join('\n');
-        p.note(files || '  (no files)', header);
+        const lines = [];
+        if (snapshot.note) {
+            lines.push(`  ${snapshot.note}`, '');
+        }
+        lines.push(...snapshot.files.map((f) => `  - ${f}`));
+        p.note(lines.join('\n') || '  (no files)', header);
     }
     if (options?.compact && hiddenVersions.length > 0) {
         p.log.info(`Hidden versions (minor changes): ${hiddenVersions.map(v => `v${v}`).join(', ')}`);

package/dist/commands/internal-seed.js

@@ -84,9 +84,9 @@ export async function cmdInternalSeed(options) {
             const content = readFileSync(resolve(specDir, fromPath), 'utf-8');
             writeDocFile(docsDir, fileName, content);
         }
-        const entry = createFullSnapshot(projectPath);
-        const note = step.saveNote ? ` — ${step.saveNote}` : '';
-        p.log.success(`v${entry.version} saved${note}`);
+        const entry = createFullSnapshot(projectPath, { note: step.saveNote });
+        const noteStr = entry.note ? ` — ${entry.note}` : '';
+        p.log.success(`v${entry.version} saved${noteStr}`);
     }
     if (spec.publish?.enabled) {
         await cmdPublish(projectPath, {

package/dist/commands/publish.js

@@ -148,6 +148,8 @@ export async function cmdPublish(path, options) {
     let description;
     let tags;
     let category;
+    let productUrl = '';
+    let productUrlType = '';
     if (options?.nonInteractive) {
         let metaFromFile = {};
         if (options.metaFile) {
@@ -170,6 +172,8 @@ export async function cmdPublish(path, options) {
             ?? '').trim();
         tags = normalizeTags(options.tags ?? metaFromFile.tags ?? existing?.tags ?? []);
         category = String(options.category ?? metaFromFile.category ?? existing?.category ?? 'other').trim();
+        productUrl = String(options.productUrl ?? metaFromFile.productUrl ?? existing?.productUrl ?? '').trim();
+        productUrlType = String(options.productUrlType ?? metaFromFile.productUrlType ?? existing?.productUrlType ?? '').trim();
         if (!/^[a-z0-9][a-z0-9-]{1,48}[a-z0-9]$/.test(slug)) {
             p.log.error('Invalid slug. Use 3-50 chars, lowercase letters, numbers, and hyphens only.');
             process.exit(1);
@@ -230,6 +234,45 @@ export async function cmdPublish(path, options) {
             process.exit(0);
         }
         category = categoryInput;
+        // Product link (optional)
+        const linkTypeInput = await p.select({
+            message: 'Product link (optional):',
+            initialValue: existing?.productUrlType || 'none',
+            options: [
+                { value: 'none', label: 'No link' },
+                { value: 'git', label: 'Git Repository' },
+                { value: 'url', label: 'Website / URL' },
+            ],
+        });
+        if (p.isCancel(linkTypeInput)) {
+            p.cancel('Cancelled');
+            process.exit(0);
+        }
+        if (linkTypeInput !== 'none') {
+            productUrlType = linkTypeInput;
+            const productUrlInput = await p.text({
+                message: 'Product URL:',
+                placeholder: linkTypeInput === 'git'
+                    ? `https://github.com/${auth.username}/${slug}`
+                    : 'https://...',
+                defaultValue: existing?.productUrl || '',
+                validate: (v) => {
+                    if (!v.trim())
+                        return 'URL is required when link type is selected.';
+                    try {
+                        new URL(v);
+                    }
+                    catch {
+                        return 'Invalid URL format.';
+                    }
+                },
+            });
+            if (p.isCancel(productUrlInput)) {
+                p.cancel('Cancelled');
+                process.exit(0);
+            }
+            productUrl = productUrlInput;
+        }
     }
     // Build .pmpt content (resolve from optimized snapshots)
     const history = snapshots.map((snapshot, i) => ({
@@ -265,6 +308,7 @@ export async function cmdPublish(path, options) {
         `Author: @${auth.username}`,
         `Category: ${category}`,
         tags.length ? `Tags: ${tags.join(', ')}` : '',
+        productUrl ? `Product: ${productUrl} (${productUrlType})` : '',
     ].filter(Boolean).join('\n'), 'Publish Preview');
     if (options?.nonInteractive) {
         if (!options.yes) {
@@ -292,6 +336,7 @@ export async function cmdPublish(path, options) {
             description,
             tags,
             category,
+            ...(productUrl && { productUrl, productUrlType }),
         });
         s.stop('Published!');
         // Update config

package/dist/commands/save.js

@@ -38,6 +38,12 @@ 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.');
+        }
         p.log.message('');
         p.log.info('Files included:');
         for (const file of entry.files) {

package/dist/index.js

@@ -140,6 +140,8 @@ program
     .option('--description <text>', 'Project description')
     .option('--tags <csv>', 'Comma-separated tags')
     .option('--category <id>', 'Project category')
+    .option('--product-url <url>', 'Product link URL')
+    .option('--product-url-type <type>', 'Product link type: git or url')
     .option('--yes', 'Skip confirmation prompt')
     .action(cmdPublish);
 program

package/dist/lib/config.js

@@ -37,6 +37,11 @@ export function initializeProject(projectPath, options) {
         trackGit: options?.trackGit ?? true,
     };
     saveConfig(projectPath, config);
+    // Create README.md if it doesn't exist
+    const readmePath = join(configDir, 'README.md');
+    if (!existsSync(readmePath)) {
+        writeFileSync(readmePath, PMPT_README, 'utf-8');
+    }
     return config;
 }
 export function loadConfig(projectPath) {
@@ -54,3 +59,55 @@ export function saveConfig(projectPath, config) {
     const configPath = join(getConfigDir(projectPath), CONFIG_FILE);
     writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
 }
+const PMPT_README = `# .pmpt — Your Project's Development Journal
+
+This folder is managed by [pmpt](https://pmptwiki.com). It records your product development journey with AI.
+
+## What's Inside
+
+\`\`\`
+.pmpt/
+├── config.json     ← Project settings (auto-generated)
+├── docs/
+│   ├── pmpt.md     ← Human-facing project document (YOU update this)
+│   ├── pmpt.ai.md  ← AI-facing prompt (paste into your AI tool)
+│   └── plan.md     ← Original plan from pmpt plan
+└── .history/       ← Version snapshots (auto-managed)
+\`\`\`
+
+## Quick Reference
+
+| Command | What it does |
+|---------|-------------|
+| \`pmpt plan\` | Create or view your AI prompt |
+| \`pmpt save\` | Save a snapshot of current docs |
+| \`pmpt history\` | View version history |
+| \`pmpt diff\` | Compare versions side by side |
+| \`pmpt publish\` | Share your journey on pmptwiki.com |
+
+## How to Get the Most Out of pmpt
+
+1. **Paste \`pmpt.ai.md\` into your AI tool** to start building
+2. **Update \`pmpt.md\` as you go** — mark features done, log decisions
+3. **Run \`pmpt save\` at milestones** — after setup, after each feature, after big changes
+4. **Publish when ready** — others can clone your journey and learn from it
+
+## When Things Go Wrong
+
+| Problem | Solution |
+|---------|----------|
+| Lost your AI prompt | \`pmpt plan\` to regenerate or view it |
+| Messed up docs | \`pmpt history\` → \`pmpt diff\` to find the good version |
+| Need to start over | \`pmpt recover\` rebuilds context from history |
+| Accidentally deleted .pmpt | Re-clone from pmptwiki.com if published |
+
+## One Request
+
+Please keep \`pmpt.md\` updated as you build. It's the human-readable record of your journey — what you tried, what worked, what you decided. When you publish, this is what others will learn from.
+
+Your snapshots tell a story. Make it a good one.
+
+---
+
+*Learn more at [pmptwiki.com](https://pmptwiki.com)*
+`;

package/dist/lib/history.js

@@ -3,18 +3,31 @@ import { basename, join, relative } from 'path';
 import { getHistoryDir, getDocsDir, loadConfig } from './config.js';
 import { getGitInfo, isGitRepo } from './git.js';
 import glob from 'fast-glob';
+/** Generate compact timestamp for snapshot dir names: 20260225T163000 */
+function compactTimestamp() {
+    return new Date().toISOString().replace(/[-:\.]/g, '').slice(0, 15);
+}
+/** Parse snapshot dir timestamp (compact or legacy) to ISO string */
+function parseTimestamp(raw) {
+    // Compact: 20260225T163000
+    if (/^\d{8}T\d{6}$/.test(raw)) {
+        return `${raw.slice(0, 4)}-${raw.slice(4, 6)}-${raw.slice(6, 8)}T${raw.slice(9, 11)}:${raw.slice(11, 13)}:${raw.slice(13, 15)}`;
+    }
+    // Legacy: 2026-02-25T16-30-00
+    return raw.replace(/T(.+)$/, (_, time) => 'T' + time.replace(/-/g, ':'));
+}
 /**
  * Save .pmpt/docs MD files as snapshot
  * Copy only changed files to optimize storage
  */
-export function createFullSnapshot(projectPath) {
+export function createFullSnapshot(projectPath, options) {
     const historyDir = getHistoryDir(projectPath);
     const docsDir = getDocsDir(projectPath);
     mkdirSync(historyDir, { recursive: true });
     // Find next version number
     const existing = getAllSnapshots(projectPath);
     const version = existing.length + 1;
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    const timestamp = compactTimestamp();
     const snapshotName = `v${version}-${timestamp}`;
     const snapshotDir = join(historyDir, snapshotName);
     mkdirSync(snapshotDir, { recursive: true });
@@ -63,12 +76,14 @@ export function createFullSnapshot(projectPath) {
         }
     }
     // Save metadata
+    const note = options?.note;
     const metaPath = join(snapshotDir, '.meta.json');
     writeFileSync(metaPath, JSON.stringify({
         version,
         timestamp,
         files,
         changedFiles,
+        ...(note ? { note } : {}),
         git: gitData,
     }, null, 2), 'utf-8');
     return {
@@ -77,6 +92,7 @@ export function createFullSnapshot(projectPath) {
         snapshotDir,
         files,
         changedFiles,
+        note,
         git: gitData,
     };
 }
@@ -98,7 +114,7 @@ export function createSnapshot(projectPath, filePath) {
 }
 function createSingleFileSnapshot(projectPath, filePath, relPath) {
     const historyDir = getHistoryDir(projectPath);
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    const timestamp = compactTimestamp();
     // Check existing version count for this file
     const existing = getFileHistory(projectPath, relPath);
     const version = existing.length + 1;
@@ -168,10 +184,11 @@ export function getAllSnapshots(projectPath) {
         }
         entries.push({
             version: parseInt(match[1], 10),
-            timestamp: match[2].replace(/-/g, ':'),
+            timestamp: parseTimestamp(match[2]),
             snapshotDir,
             files: meta.files || [],
             changedFiles: meta.changedFiles,
+            note: meta.note,
             git: meta.git,
         });
     }
@@ -210,7 +227,7 @@ export function getFileHistory(projectPath, relPath) {
         }
         entries.push({
             version: parseInt(match[1], 10),
-            timestamp: match[2].replace(/-/g, ':'),
+            timestamp: parseTimestamp(match[2]),
             filePath: relPath,
             historyPath: filePath,
             git: gitData,

package/dist/lib/plan.js

@@ -88,6 +88,12 @@ I'll confirm progress at each step before moving to the next.
 
 Keep the Progress and Snapshot Log sections in pmpt.md up to date.
 After significant milestones, run \`pmpt save\` to create a snapshot.
+
+### Per-Feature Checklist
+After completing each feature above:
+1. Mark the feature done in \`.pmpt/docs/pmpt.md\` (change \`- [ ]\` to \`- [x]\`)
+2. Add a brief note to the Snapshot Log section
+3. Run \`pmpt save\` in terminal
 `;
 }
 // Generate human-facing project document (pmpt.md)

package/package.json

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