@fermindi/pwn-cli 0.2.0 → 0.3.0

package/cli/index.js

@@ -21,7 +21,9 @@ if (!command || command === '--help' || command === '-h') {
   console.log('Usage: pwn <command> [options]\n');
   console.log('Commands:');
   console.log('  inject              Inject .ai/ workspace into current project');
+  console.log('  update              Update PWN framework files to latest version');
   console.log('  migrate             Migrate existing AI files to PWN structure');
+  console.log('  save                Save session context to memory');
   console.log('  status              Show workspace status');
   console.log('  validate            Validate workspace structure');
   console.log('  notify              Send notifications (test, send, config)');
@@ -33,7 +35,9 @@ if (!command || command === '--help' || command === '-h') {
   console.log('  --help, -h          Show help\n');
   console.log('Options:');
   console.log('  inject --force      Overwrite existing .ai/ directory');
+  console.log('  update --dry-run    Preview update without changes');
   console.log('  migrate --dry-run   Preview migration without changes');
+  console.log('  save --message=X    Save with custom summary');
   console.log('  validate --verbose  Show detailed structure report');
   console.log('  notify test [ch]    Test notification channel');
   console.log('  batch --count 5     Execute 5 tasks');
@@ -51,11 +55,21 @@ switch (command) {
     await inject(args);
     break;
 
+  case 'update':
+    const { default: update } = await import('./update.js');
+    await update(args);
+    break;
+
   case 'migrate':
     const { default: migrate } = await import('./migrate.js');
     await migrate(args);
     break;
 
+  case 'save':
+    const { default: save } = await import('./save.js');
+    await save(args);
+    break;
+
   case 'status':
     const { default: status } = await import('./status.js');
     await status();

package/cli/inject.js

@@ -46,6 +46,18 @@ export default async function injectCommand(args = []) {
   }
 
   console.log('\n✅ PWN workspace injected successfully!\n');
+
+  // Show backup info
+  if (result.backed_up && result.backed_up.length > 0) {
+    console.log('📦 Backed up existing AI files:');
+    for (const b of result.backed_up) {
+      console.log(`   ${b.from} → ${b.to}`);
+    }
+    console.log('');
+    console.log('   💡 Merge your custom instructions into CLAUDE.md');
+    console.log('   🗑️  Delete the backup files (~CLAUDE.md, etc.) when done\n');
+  }
+
   console.log('📁 Created structure:');
   console.log('   .ai/');
   console.log('   ├── memory/         (decisions, patterns, dead-ends)');

package/cli/save.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { createInterface } from 'readline';
+
+/**
+ * Interactive prompt helper
+ */
+function prompt(question) {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+/**
+ * Generate timestamp-based filename
+ */
+function generateFilename() {
+  const now = new Date();
+  const date = now.toISOString().split('T')[0]; // YYYY-MM-DD
+  return `${date}-session.md`;
+}
+
+/**
+ * Format current date
+ */
+function formatDate() {
+  return new Date().toISOString().split('T')[0];
+}
+
+export default async function saveCommand(args = []) {
+  const cwd = process.cwd();
+  const aiDir = join(cwd, '.ai');
+
+  // Check if .ai/ exists
+  if (!existsSync(aiDir)) {
+    console.log('❌ No .ai/ directory found');
+    console.log('   Run "pwn inject" first to initialize workspace');
+    process.exit(1);
+  }
+
+  console.log('💾 PWN Save - Persist session context\n');
+
+  const isInteractive = !args.includes('--no-input') && process.stdin.isTTY;
+  const messageArg = args.find(a => a.startsWith('--message=') || a.startsWith('-m='));
+  let summary = messageArg ? messageArg.split('=')[1] : null;
+
+  // Paths
+  const archiveDir = join(aiDir, 'memory', 'archive');
+  const decisionsPath = join(aiDir, 'memory', 'decisions.md');
+  const patternsPath = join(aiDir, 'memory', 'patterns.md');
+  const deadendsPath = join(aiDir, 'memory', 'deadends.md');
+  const activePath = join(aiDir, 'tasks', 'active.md');
+  const statePath = join(aiDir, 'state.json');
+
+  // Ensure archive directory exists
+  if (!existsSync(archiveDir)) {
+    mkdirSync(archiveDir, { recursive: true });
+  }
+
+  // Get summary
+  if (!summary && isInteractive) {
+    console.log('📝 What did you accomplish in this session?');
+    console.log('   (Brief summary - press Enter twice to finish)\n');
+    summary = await prompt('> ');
+  }
+
+  if (!summary) {
+    summary = 'Session checkpoint';
+  }
+
+  // Create archive entry
+  const filename = generateFilename();
+  const archivePath = join(archiveDir, filename);
+
+  // Check if file already exists, append number if needed
+  let finalPath = archivePath;
+  let counter = 1;
+  while (existsSync(finalPath)) {
+    finalPath = join(archiveDir, filename.replace('.md', `-${counter}.md`));
+    counter++;
+  }
+
+  // Gather current state
+  const sections = [];
+
+  sections.push(`# Session: ${formatDate()}\n`);
+  sections.push(`## Summary\n\n${summary}\n`);
+
+  // Capture active tasks
+  if (existsSync(activePath)) {
+    const active = readFileSync(activePath, 'utf8');
+    const completedTasks = active.match(/- \[x\].*/g) || [];
+    const pendingTasks = active.match(/- \[ \].*/g) || [];
+
+    if (completedTasks.length > 0 || pendingTasks.length > 0) {
+      sections.push(`## Tasks\n`);
+      if (completedTasks.length > 0) {
+        sections.push(`### Completed\n${completedTasks.join('\n')}\n`);
+      }
+      if (pendingTasks.length > 0) {
+        sections.push(`### In Progress\n${pendingTasks.join('\n')}\n`);
+      }
+    }
+  }
+
+  // Prompt for decisions
+  if (isInteractive) {
+    console.log('\n🎯 Any decisions made? (DEC-XXX format, or press Enter to skip)');
+    const decision = await prompt('> ');
+    if (decision.trim()) {
+      sections.push(`## Decisions Made\n\n${decision}\n`);
+
+      // Optionally append to decisions.md
+      if (existsSync(decisionsPath)) {
+        const decContent = readFileSync(decisionsPath, 'utf8');
+        // Find next DEC number
+        const decMatches = decContent.match(/DEC-(\d+)/g) || [];
+        const maxNum = decMatches.reduce((max, match) => {
+          const num = parseInt(match.replace('DEC-', ''));
+          return num > max ? num : max;
+        }, 0);
+        const nextNum = String(maxNum + 1).padStart(3, '0');
+
+        const newDecision = `\n## DEC-${nextNum}: ${decision.split(':')[0] || 'Decision'}\n**Date:** ${formatDate()}\n**Context:** Session save\n**Decision:** ${decision}\n`;
+        writeFileSync(decisionsPath, decContent + newDecision);
+        console.log(`   → Added DEC-${nextNum} to decisions.md`);
+      }
+    }
+  }
+
+  // Prompt for patterns
+  if (isInteractive) {
+    console.log('\n🔄 Any patterns discovered? (press Enter to skip)');
+    const pattern = await prompt('> ');
+    if (pattern.trim()) {
+      sections.push(`## Patterns Learned\n\n${pattern}\n`);
+
+      // Optionally append to patterns.md
+      if (existsSync(patternsPath)) {
+        const patContent = readFileSync(patternsPath, 'utf8');
+        const newPattern = `\n### ${formatDate()} Pattern\n${pattern}\n`;
+        writeFileSync(patternsPath, patContent + newPattern);
+        console.log('   → Added to patterns.md');
+      }
+    }
+  }
+
+  // Prompt for dead-ends
+  if (isInteractive) {
+    console.log('\n❌ Any dead-ends to avoid? (press Enter to skip)');
+    const deadend = await prompt('> ');
+    if (deadend.trim()) {
+      sections.push(`## Dead-ends\n\n${deadend}\n`);
+
+      // Optionally append to deadends.md
+      if (existsSync(deadendsPath)) {
+        const deContent = readFileSync(deadendsPath, 'utf8');
+        // Find next DE number
+        const deMatches = deContent.match(/DE-(\d+)/g) || [];
+        const maxNum = deMatches.reduce((max, match) => {
+          const num = parseInt(match.replace('DE-', ''));
+          return num > max ? num : max;
+        }, 0);
+        const nextNum = String(maxNum + 1).padStart(3, '0');
+
+        const newDeadend = `\n## DE-${nextNum}: ${deadend.split(':')[0] || 'Dead-end'}\n**Date:** ${formatDate()}\n**Attempted:** ${deadend}\n**Problem:** See above\n**Solution:** TBD\n`;
+        writeFileSync(deadendsPath, deContent + newDeadend);
+        console.log(`   → Added DE-${nextNum} to deadends.md`);
+      }
+    }
+  }
+
+  // Add timestamp
+  sections.push(`\n---\n*Saved: ${new Date().toISOString()}*\n`);
+
+  // Write archive file
+  writeFileSync(finalPath, sections.join('\n'));
+
+  // Update state.json
+  if (existsSync(statePath)) {
+    try {
+      const state = JSON.parse(readFileSync(statePath, 'utf8'));
+      state.last_save = new Date().toISOString();
+      state.last_save_file = finalPath.replace(cwd, '').replace(/^[\/\\]/, '');
+      writeFileSync(statePath, JSON.stringify(state, null, 2));
+    } catch {
+      // Ignore state errors
+    }
+  }
+
+  console.log(`\n✅ Session saved to ${finalPath.replace(cwd, '').replace(/^[\/\\]/, '')}`);
+  console.log('\n📖 Next session will have access to:');
+  console.log('   - .ai/memory/archive/ (session history)');
+  console.log('   - .ai/memory/decisions.md');
+  console.log('   - .ai/memory/patterns.md');
+  console.log('   - .ai/memory/deadends.md\n');
+}

package/cli/update.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, writeFileSync, cpSync, renameSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Files that should be updated (framework files)
+ * These are safe to overwrite - they don't contain user data
+ */
+const FRAMEWORK_FILES = [
+  'agents/claude.md',
+  'agents/README.md',
+  'patterns/index.md',
+  'patterns/frontend/README.md',
+  'patterns/backend/README.md',
+  'patterns/universal/README.md',
+  'workflows/batch-task.md',
+  'config/README.md',
+  'README.md',
+];
+
+/**
+ * Files that should NOT be updated (user data)
+ * These contain user customizations
+ */
+const USER_FILES = [
+  'memory/decisions.md',
+  'memory/patterns.md',
+  'memory/deadends.md',
+  'memory/archive/',
+  'tasks/active.md',
+  'tasks/backlog.md',
+  'state.json',
+  'config/notifications.json',
+];
+
+export default async function updateCommand(args = []) {
+  const cwd = process.cwd();
+  const aiDir = join(cwd, '.ai');
+  const dryRun = args.includes('--dry-run');
+
+  console.log('🔄 PWN Update\n');
+
+  // Check if .ai/ exists
+  if (!existsSync(aiDir)) {
+    console.log('❌ No .ai/ directory found');
+    console.log('   Run "pwn inject" first to initialize workspace');
+    process.exit(1);
+  }
+
+  // Get template path
+  const templateDir = join(__dirname, '../templates/workspace/.ai');
+
+  if (!existsSync(templateDir)) {
+    console.log('❌ Template directory not found');
+    process.exit(1);
+  }
+
+  // Get installed version from state.json or README
+  let currentVersion = 'unknown';
+  const statePath = join(aiDir, 'state.json');
+  if (existsSync(statePath)) {
+    try {
+      const state = JSON.parse(readFileSync(statePath, 'utf8'));
+      currentVersion = state.pwn_version || 'unknown';
+    } catch {
+      // Ignore
+    }
+  }
+
+  // Get new version from package.json
+  const packagePath = join(__dirname, '../package.json');
+  const pkg = JSON.parse(readFileSync(packagePath, 'utf8'));
+  const newVersion = pkg.version;
+
+  console.log(`   Current: ${currentVersion}`);
+  console.log(`   New:     ${newVersion}\n`);
+
+  if (dryRun) {
+    console.log('📋 Dry run - showing what would be updated:\n');
+  }
+
+  const updated = [];
+  const skipped = [];
+  const backed_up = [];
+
+  // Update framework files in .ai/
+  for (const file of FRAMEWORK_FILES) {
+    const templateFile = join(templateDir, file);
+    const targetFile = join(aiDir, file);
+
+    if (!existsSync(templateFile)) {
+      continue;
+    }
+
+    const templateContent = readFileSync(templateFile, 'utf8');
+    const targetExists = existsSync(targetFile);
+    const targetContent = targetExists ? readFileSync(targetFile, 'utf8') : '';
+
+    if (templateContent !== targetContent) {
+      if (dryRun) {
+        console.log(`   📝 Would update: .ai/${file}`);
+      } else {
+        // Ensure directory exists
+        const dir = dirname(targetFile);
+        if (!existsSync(dir)) {
+          const { mkdirSync } = await import('fs');
+          mkdirSync(dir, { recursive: true });
+        }
+        writeFileSync(targetFile, templateContent);
+        console.log(`   📝 Updated: .ai/${file}`);
+      }
+      updated.push(file);
+    } else {
+      skipped.push(file);
+    }
+  }
+
+  // Update CLAUDE.md in root
+  const claudeMdPath = join(cwd, 'CLAUDE.md');
+  const templateClaudeMd = join(templateDir, 'agents', 'claude.md');
+  const backupClaudeMdPath = join(cwd, '~CLAUDE.md');
+
+  if (existsSync(templateClaudeMd)) {
+    const templateContent = readFileSync(templateClaudeMd, 'utf8');
+    const currentContent = existsSync(claudeMdPath) ? readFileSync(claudeMdPath, 'utf8') : '';
+
+    if (templateContent !== currentContent) {
+      if (dryRun) {
+        console.log(`   📝 Would update: CLAUDE.md`);
+        if (currentContent) {
+          console.log(`   📦 Would backup: CLAUDE.md → ~CLAUDE.md`);
+        }
+      } else {
+        // Backup existing CLAUDE.md
+        if (existsSync(claudeMdPath) && currentContent) {
+          renameSync(claudeMdPath, backupClaudeMdPath);
+          console.log(`   📦 Backed up: CLAUDE.md → ~CLAUDE.md`);
+          backed_up.push('CLAUDE.md');
+        }
+        // Copy new template
+        writeFileSync(claudeMdPath, templateContent);
+        console.log(`   📝 Updated: CLAUDE.md`);
+      }
+      updated.push('CLAUDE.md');
+    }
+  }
+
+  // Update state.json with new version
+  if (!dryRun && existsSync(statePath)) {
+    try {
+      const state = JSON.parse(readFileSync(statePath, 'utf8'));
+      state.pwn_version = newVersion;
+      state.last_updated = new Date().toISOString();
+      writeFileSync(statePath, JSON.stringify(state, null, 2));
+    } catch {
+      // Ignore
+    }
+  }
+
+  // Summary
+  console.log('');
+  if (updated.length === 0) {
+    console.log('✅ Already up to date!\n');
+  } else if (dryRun) {
+    console.log(`📋 Would update ${updated.length} file(s)\n`);
+    console.log('   Run without --dry-run to apply updates');
+  } else {
+    console.log(`✅ Updated ${updated.length} file(s)\n`);
+
+    if (backed_up.length > 0) {
+      console.log('📦 Backed up files:');
+      for (const f of backed_up) {
+        console.log(`   ${f} → ~${f}`);
+      }
+      console.log('');
+      console.log('   💡 Merge your custom instructions into CLAUDE.md');
+      console.log('   🗑️  Delete backup files when done\n');
+    }
+  }
+
+  // Show what was preserved
+  console.log('🔒 Preserved (user data):');
+  console.log('   .ai/memory/     (decisions, patterns, deadends)');
+  console.log('   .ai/tasks/      (active, backlog)');
+  console.log('   .ai/state.json  (session state)\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fermindi/pwn-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Professional AI Workspace - Inject structured memory and automation into any project for AI-powered development",
   "type": "module",
   "bin": {

package/src/core/inject.js

@@ -1,4 +1,4 @@
-import { existsSync, cpSync, renameSync, readFileSync, appendFileSync, writeFileSync, readdirSync } from 'fs';
+import { existsSync, cpSync, renameSync, readFileSync, appendFileSync, writeFileSync, readdirSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { randomUUID } from 'crypto';
@@ -121,6 +121,22 @@ export async function inject(options = {}) {
     };
   }
 
+  // Backup existing AI files content before overwriting
+  const backedUpContent = {};
+  if (detectedFiles.length > 0 && detectedFiles.some(f => f.migratable)) {
+    log('📋 Backing up existing AI files...');
+    for (const file of detectedFiles.filter(f => f.migratable)) {
+      try {
+        backedUpContent[file.file] = {
+          content: readFileSync(file.path, 'utf8'),
+          type: file.type
+        };
+      } catch {
+        // Ignore read errors
+      }
+    }
+  }
+
   try {
     // Copy workspace template
     log('📦 Copying workspace template...');
@@ -149,11 +165,49 @@ export async function inject(options = {}) {
     // Update .gitignore
     updateGitignore(cwd, silent);
 
+    // Handle CLAUDE.md: backup existing and copy PWN template to root
+    let backupInfo = { backed_up: [] };
+    const claudeMdPath = join(cwd, 'CLAUDE.md');
+    const backupClaudeMdPath = join(cwd, '~CLAUDE.md');
+    const templateClaudeMd = join(targetDir, 'agents', 'claude.md');
+
+    // Backup existing CLAUDE.md if present
+    if (backedUpContent['CLAUDE.md'] || backedUpContent['claude.md']) {
+      const originalName = backedUpContent['CLAUDE.md'] ? 'CLAUDE.md' : 'claude.md';
+      const originalPath = join(cwd, originalName);
+
+      if (existsSync(originalPath)) {
+        renameSync(originalPath, backupClaudeMdPath);
+        backupInfo.backed_up.push({ from: originalName, to: '~CLAUDE.md' });
+        if (!silent) {
+          console.log(`📦 Backed up ${originalName} → ~CLAUDE.md`);
+        }
+      }
+    }
+
+    // Copy PWN template to CLAUDE.md in root
+    if (existsSync(templateClaudeMd)) {
+      cpSync(templateClaudeMd, claudeMdPath);
+      if (!silent) {
+        console.log('📝 Created CLAUDE.md with PWN template');
+      }
+    }
+
+    // Backup other AI files (not CLAUDE.md) to .ai/
+    const otherFiles = Object.fromEntries(
+      Object.entries(backedUpContent).filter(([k]) => k.toLowerCase() !== 'claude.md')
+    );
+    if (Object.keys(otherFiles).length > 0) {
+      const otherBackups = backupExistingAIFiles(targetDir, otherFiles, silent);
+      backupInfo.backed_up.push(...otherBackups.backed_up);
+    }
+
     return {
       success: true,
       message: 'PWN workspace injected successfully',
       path: targetDir,
-      detected: detectedFiles
+      detected: detectedFiles,
+      backed_up: backupInfo.backed_up
     };
 
   } catch (error) {
@@ -185,6 +239,44 @@ function initNotifications(notifyFile) {
   }
 }
 
+/**
+ * Backup existing AI files to .ai/ root with ~ prefix
+ * - PWN template stays as the base (it's the correct one)
+ * - User's existing files are backed up for manual merge
+ * @param {string} targetDir - Path to .ai/ directory
+ * @param {Object} backedUpContent - Map of filename -> {content, type}
+ * @param {boolean} silent - Suppress output
+ * @returns {Object} Backup info
+ */
+function backupExistingAIFiles(targetDir, backedUpContent, silent = false) {
+  const result = { backed_up: [] };
+
+  try {
+    // Backup all existing AI files with ~ prefix
+    for (const [filename, data] of Object.entries(backedUpContent)) {
+      // Convert filename to backup name: CLAUDE.md -> ~CLAUDE.md, .cursorrules -> ~cursorrules.md
+      const safeName = filename.replace(/^\./, '').replace(/[\/\\]/g, '-');
+      const backupName = `~${safeName}${safeName.endsWith('.md') ? '' : '.md'}`;
+      const backupPath = join(targetDir, backupName);
+
+      writeFileSync(backupPath, data.content);
+
+      result.backed_up.push({ from: filename, to: backupName });
+
+      if (!silent) {
+        console.log(`📦 Backed up ${filename} → .ai/${backupName}`);
+      }
+    }
+
+  } catch (error) {
+    if (!silent) {
+      console.error('⚠️  Backup warning:', error.message);
+    }
+  }
+
+  return result;
+}
+
 /**
  * Update .gitignore to exclude PWN personal files
  * @param {string} cwd - Working directory