proagents 1.6.12 → 1.6.15

package/lib/commands/doctor.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
+import { execSync } from 'child_process';
 import chalk from 'chalk';
 import yaml from 'js-yaml';
 
@@ -98,7 +99,9 @@ function checkPlatformSync(targetDir) {
       const content = readFileSync(configPath, 'utf-8');
       const config = yaml.load(content);
       configPlatforms = config?.platforms || config?.ai_platforms || [];
-    } catch { }
+    } catch {
+      // Config file unreadable - will be caught by other checks
+    }
   }
 
   // Check each platform file
@@ -134,7 +137,7 @@ function checkPlatformSync(targetDir) {
  * Check for lock file
  */
 function checkLockFile(targetDir) {
-  const lockPath = join(targetDir, 'proagents', '.lock');
+  const lockPath = join(targetDir, '.proagents', '.lock');
   const checks = [];
 
   if (existsSync(lockPath)) {
@@ -163,18 +166,187 @@ function checkLockFile(targetDir) {
 }
 
 /**
- * Check version
+ * Extended checks for --full mode
  */
-async function checkVersion() {
+function checkExtended(targetDir) {
   const checks = [];
 
+  // Check changelog size
+  const recentPath = join(targetDir, '.proagents', 'changelog', '_recent.md');
+  if (existsSync(recentPath)) {
+    try {
+      const content = readFileSync(recentPath, 'utf-8');
+      const entries = (content.match(/^### /gm) || []).length;
+      if (entries > 50) {
+        checks.push({ name: 'Changelog size', status: 'warning', message: `${entries} entries (consider archiving)` });
+      } else {
+        checks.push({ name: 'Changelog size', status: 'ok', message: `${entries} entries` });
+      }
+    } catch {
+      checks.push({ name: 'Changelog size', status: 'skip', message: 'Could not read' });
+    }
+  } else {
+    checks.push({ name: 'Changelog', status: 'info', message: 'No recent changelog' });
+  }
+
+  // Check activity log freshness
+  const activityPath = join(targetDir, '.proagents', 'activity.log');
+  if (existsSync(activityPath)) {
+    try {
+      const content = readFileSync(activityPath, 'utf-8');
+      const lines = content.trim().split('\n').filter(l => l && !l.startsWith('#') && !l.includes('Activity Log'));
+      if (lines.length > 0) {
+        const lastLine = lines[lines.length - 1];
+        const dateMatch = lastLine.match(/^\[?(\d{4}-\d{2}-\d{2})/);
+        if (dateMatch) {
+          const lastDate = new Date(dateMatch[1]);
+          const daysAgo = Math.floor((Date.now() - lastDate.getTime()) / (1000 * 60 * 60 * 24));
+          if (daysAgo > 7) {
+            checks.push({ name: 'Activity log', status: 'warning', message: `Last entry ${daysAgo} days ago` });
+          } else if (daysAgo > 0) {
+            checks.push({ name: 'Activity log', status: 'ok', message: `Last entry ${daysAgo} day(s) ago` });
+          } else {
+            checks.push({ name: 'Activity log', status: 'ok', message: 'Activity today' });
+          }
+        } else {
+          checks.push({ name: 'Activity log', status: 'ok', message: `${lines.length} entries` });
+        }
+      } else {
+        checks.push({ name: 'Activity log', status: 'info', message: 'No entries yet' });
+      }
+    } catch {
+      checks.push({ name: 'Activity log', status: 'skip', message: 'Could not read' });
+    }
+  } else {
+    checks.push({ name: 'Activity log', status: 'info', message: 'No activity log' });
+  }
+
+  // Check for stale feature branches
   try {
-    // Get current version from package.json
+    const branches = execSync('git branch --list "feature/*" 2>/dev/null', { encoding: 'utf-8' }).trim();
+    if (branches) {
+      const branchCount = branches.split('\n').filter(b => b.trim()).length;
+      if (branchCount > 5) {
+        checks.push({ name: 'Feature branches', status: 'warning', message: `${branchCount} branches (consider cleanup)` });
+      } else if (branchCount > 0) {
+        checks.push({ name: 'Feature branches', status: 'ok', message: `${branchCount} active` });
+      }
+    } else {
+      checks.push({ name: 'Feature branches', status: 'ok', message: 'None' });
+    }
+  } catch {
+    checks.push({ name: 'Feature branches', status: 'skip', message: 'Not a git repo or no feature branches' });
+  }
+
+  // Check active features
+  const featuresPath = join(targetDir, '.proagents', 'active-features', '_index.json');
+  if (existsSync(featuresPath)) {
+    try {
+      const content = readFileSync(featuresPath, 'utf-8');
+      const index = JSON.parse(content);
+      const activeCount = index.active_features?.length || 0;
+      const completedCount = index.completed_features?.length || 0;
+
+      if (activeCount > 0) {
+        checks.push({ name: 'Active features', status: 'ok', message: `${activeCount} active, ${completedCount} completed` });
+      } else {
+        checks.push({ name: 'Active features', status: 'info', message: `None active, ${completedCount} completed` });
+      }
+    } catch {
+      checks.push({ name: 'Active features', status: 'skip', message: 'Could not read index' });
+    }
+  } else {
+    checks.push({ name: 'Active features', status: 'info', message: 'No features tracked' });
+  }
+
+  // Check worklog context
+  const contextPath = join(targetDir, '.proagents', 'worklog', '_context.md');
+  if (existsSync(contextPath)) {
+    checks.push({ name: 'Worklog context', status: 'ok', message: 'Present' });
+  } else {
+    checks.push({ name: 'Worklog context', status: 'warning', message: 'Missing (cross-AI sync may be affected)' });
+  }
+
+  // Check for required folders
+  const requiredFolders = [
+    { path: '.proagents/prompts', name: 'Prompts folder' },
+    { path: '.proagents/templates', name: 'Templates folder' },
+    { path: '.proagents/changelog', name: 'Changelog folder' },
+    { path: '.proagents/worklog', name: 'Worklog folder' }
+  ];
+
+  for (const folder of requiredFolders) {
+    if (existsSync(join(targetDir, folder.path))) {
+      checks.push({ name: folder.name, status: 'ok', message: 'Present' });
+    } else {
+      checks.push({ name: folder.name, status: 'warning', message: 'Missing' });
+    }
+  }
+
+  return checks;
+}
+
+/**
+ * Compare semantic versions
+ * Returns: -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+ */
+function compareVersions(v1, v2) {
+  const parts1 = v1.split('.').map(Number);
+  const parts2 = v2.split('.').map(Number);
+
+  for (let i = 0; i < 3; i++) {
+    const p1 = parts1[i] || 0;
+    const p2 = parts2[i] || 0;
+    if (p1 < p2) return -1;
+    if (p1 > p2) return 1;
+  }
+  return 0;
+}
+
+/**
+ * Check version (CLI, project, and npm)
+ */
+async function checkVersion(targetDir) {
+  const checks = [];
+  const recommendations = [];
+
+  try {
+    // Get CLI version from package.json
     const packagePath = new URL('../../package.json', import.meta.url);
     const packageJson = JSON.parse(readFileSync(packagePath, 'utf-8'));
-    const currentVersion = packageJson.version;
-
-    checks.push({ name: 'Installed version', status: 'info', message: `v${currentVersion}` });
+    const cliVersion = packageJson.version;
+
+    checks.push({ name: 'CLI version', status: 'info', message: `v${cliVersion}` });
+
+    // Get project version from .proagents/.version
+    const projectVersionPath = join(targetDir, '.proagents', '.version');
+    let projectVersion = null;
+
+    if (existsSync(projectVersionPath)) {
+      try {
+        projectVersion = readFileSync(projectVersionPath, 'utf-8').trim();
+
+        if (projectVersion === cliVersion) {
+          checks.push({ name: 'Project version', status: 'ok', message: `v${projectVersion} (synced with CLI)` });
+        } else if (compareVersions(projectVersion, cliVersion) < 0) {
+          checks.push({ name: 'Project version', status: 'warning', message: `v${projectVersion} (outdated)` });
+          recommendations.push({
+            issue: 'Project framework is outdated',
+            action: 'Run `npx proagents init` to update framework files'
+          });
+        } else {
+          checks.push({ name: 'Project version', status: 'info', message: `v${projectVersion}` });
+        }
+      } catch {
+        checks.push({ name: 'Project version', status: 'warning', message: 'Could not read version file' });
+      }
+    } else {
+      checks.push({ name: 'Project version', status: 'warning', message: 'No version marker (older installation)' });
+      recommendations.push({
+        issue: 'No version tracking',
+        action: 'Run `npx proagents init` to update and add version tracking'
+      });
+    }
 
     // Try to fetch latest version from npm (with timeout)
     try {
@@ -190,20 +362,24 @@ async function checkVersion() {
         const data = await response.json();
         const latestVersion = data.version;
 
-        if (currentVersion === latestVersion) {
-          checks.push({ name: 'Latest version', status: 'ok', message: 'Up to date' });
+        if (compareVersions(cliVersion, latestVersion) >= 0) {
+          checks.push({ name: 'npm registry', status: 'ok', message: `v${latestVersion} (up to date)` });
         } else {
-          checks.push({ name: 'Latest version', status: 'warning', message: `v${latestVersion} available. Run: npm update -g proagents` });
+          checks.push({ name: 'npm registry', status: 'warning', message: `v${latestVersion} available` });
+          recommendations.push({
+            issue: 'CLI update available',
+            action: 'Run `npm update -g proagents` to update CLI'
+          });
         }
       }
     } catch {
-      checks.push({ name: 'Version check', status: 'skip', message: 'Could not check npm registry' });
+      checks.push({ name: 'npm registry', status: 'skip', message: 'Could not check (offline?)' });
     }
-  } catch {
-    checks.push({ name: 'Version', status: 'error', message: 'Could not read version' });
+  } catch (error) {
+    checks.push({ name: 'Version', status: 'error', message: `Could not read version: ${error.message}` });
   }
 
-  return checks;
+  return { checks, recommendations };
 }
 
 /**
@@ -248,16 +424,14 @@ function printChecks(title, checks) {
 /**
  * Doctor command - check health of ProAgents installation
  */
-export async function doctorCommand() {
+export async function doctorCommand(options = {}) {
   const targetDir = process.cwd();
+  const isFullMode = options.full || false;
 
-  console.log(chalk.bold('\nProAgents Doctor'));
-  console.log(chalk.gray('================'));
+  console.log(chalk.bold('\nProAgents Doctor' + (isFullMode ? ' (Full)' : '')));
+  console.log(chalk.gray('═'.repeat(40)));
   console.log(chalk.gray(`Checking: ${targetDir}\n`));
 
-  let hasErrors = false;
-  let hasWarnings = false;
-
   // Run all checks
   const installChecks = checkInstallation(targetDir);
   printChecks('Installation', installChecks);
@@ -271,14 +445,32 @@ export async function doctorCommand() {
   const lockChecks = checkLockFile(targetDir);
   printChecks('Lock Status', lockChecks);
 
-  const versionChecks = await checkVersion();
-  printChecks('Version', versionChecks);
+  const versionResult = await checkVersion(targetDir);
+  printChecks('Version', versionResult.checks);
+
+  // Extended checks for --full mode
+  let extendedChecks = [];
+  if (isFullMode) {
+    extendedChecks = checkExtended(targetDir);
+    printChecks('Extended Health Checks', extendedChecks);
+  }
 
   // Count issues
-  const allChecks = [...installChecks, ...configChecks, ...platformChecks, ...lockChecks, ...versionChecks];
+  const allChecks = [...installChecks, ...configChecks, ...platformChecks, ...lockChecks, ...versionResult.checks, ...extendedChecks];
   const errors = allChecks.filter(c => c.status === 'error').length;
   const warnings = allChecks.filter(c => c.status === 'warning').length;
 
+  // Recommendations section (if any)
+  if (versionResult.recommendations && versionResult.recommendations.length > 0) {
+    console.log(chalk.bold('\nRecommendations'));
+    console.log(chalk.gray('─'.repeat(40)));
+
+    for (const rec of versionResult.recommendations) {
+      console.log(chalk.yellow(`  ⚡ ${rec.issue}`));
+      console.log(chalk.cyan(`     → ${rec.action}`));
+    }
+  }
+
   // Summary
   console.log(chalk.bold('\nSummary'));
   console.log(chalk.gray('─'.repeat(40)));
@@ -298,8 +490,13 @@ export async function doctorCommand() {
       console.log(chalk.gray('Run `npx proagents init` to fix installation issues.'));
     }
     if (platformChecks.some(c => c.status === 'warning')) {
-      console.log(chalk.gray('Run `pa:ai-sync` to fix platform sync issues.'));
+      console.log(chalk.gray('Run `npx proagents ai add` to fix platform sync issues.'));
     }
     console.log('');
   }
+
+  // Hint for full mode
+  if (!isFullMode) {
+    console.log(chalk.gray('Run `proagents doctor --full` for extended health checks.\n'));
+  }
 }

package/lib/commands/help.js

@@ -53,10 +53,30 @@ export async function helpCommand() {
   console.log(chalk.bold.white('Status & Info'));
   console.log(chalk.gray('─'.repeat(40)));
   console.log(chalk.cyan('proagents status') + '            Show ProAgents status');
+  console.log(chalk.cyan('proagents version') + '           Show detailed version info');
+  console.log(chalk.cyan('proagents doctor') + '            Health check installation');
   console.log(chalk.cyan('proagents docs') + '              Open documentation');
   console.log(chalk.cyan('proagents commands') + '          Show this help');
-  console.log(chalk.cyan('proagents uninstall') + '         Remove ProAgents from project');
-  console.log(chalk.cyan('proagents --version') + '         Show version');
+  console.log('');
+
+  // Release & Maintenance
+  console.log(chalk.bold.white('Release & Maintenance'));
+  console.log(chalk.gray('─'.repeat(40)));
+  console.log(chalk.cyan('proagents release') + '               Interactive release notes');
+  console.log(chalk.gray('  Types: -t detailed | short | client | developer | hotfix | prerelease'));
+  console.log(chalk.gray('  Filters:'));
+  console.log(chalk.cyan('    --include fixes') + '          Only include bug fixes');
+  console.log(chalk.cyan('    --include features') + '       Only include features');
+  console.log(chalk.cyan('    --exclude docs,deps') + '      Exclude docs and deps');
+  console.log(chalk.cyan('    --module auth') + '            Filter by module name');
+  console.log(chalk.cyan('    --path src/lib') + '           Filter by file path');
+  console.log(chalk.gray('  Options:'));
+  console.log(chalk.cyan('    --append') + '                 Append to existing notes');
+  console.log(chalk.cyan('    --bump') + '                   Suggest version bump');
+  console.log(chalk.cyan('    --prerelease beta') + '        Mark as beta/rc/alpha');
+  console.log(chalk.cyan('    --since v1.0.0') + '           From specific tag');
+  console.log(chalk.cyan('proagents upgrade') + '               Upgrade .proagents folder');
+  console.log(chalk.cyan('proagents uninstall') + '             Remove ProAgents from project');
   console.log('');
 
   // Commands for AI Assistants

package/lib/commands/init.js

@@ -14,8 +14,133 @@ const PRESERVE_PATHS = [
   'active-features',           // User's work in progress
   '.learning',                 // Learned patterns
   'cache',                     // Cached analysis
+  'changelog',                 // Change history (user data)
+  'worklog',                   // Work context (user data)
+  'sessions',                  // Session data
+  'backups',                   // User backups
 ];
 
+// Files within PRESERVE_PATHS that should always be UPDATED (framework files)
+// These patterns match files that should be overwritten with latest framework version
+const UPDATE_WITHIN_PRESERVED = [
+  'README.md',                 // Documentation
+  'entry-template.md',         // Changelog entry template
+  '*.template.md',             // All template markdown files
+  '*.template.json',           // All template JSON files
+  'schemas',                   // Schema folders
+];
+
+/**
+ * Backup user data before fresh install
+ * Returns object mapping path to temp backup location
+ */
+function backupUserData(proagentsDir) {
+  const preserved = {};
+  for (const path of PRESERVE_PATHS) {
+    const fullPath = join(proagentsDir, path);
+    if (existsSync(fullPath)) {
+      const tempPath = join(proagentsDir, '..', `.proagents-backup-${path.replace(/\//g, '-')}`);
+      try {
+        cpSync(fullPath, tempPath, { recursive: true });
+        preserved[path] = tempPath;
+      } catch (err) {
+        // Silently continue if backup fails
+      }
+    }
+  }
+  return preserved;
+}
+
+/**
+ * Restore user data after fresh install
+ */
+function restoreUserData(proagentsDir, preserved) {
+  for (const [path, tempPath] of Object.entries(preserved)) {
+    const fullPath = join(proagentsDir, path);
+    if (existsSync(tempPath)) {
+      try {
+        // Remove the framework's empty/default version
+        if (existsSync(fullPath)) {
+          rmSync(fullPath, { recursive: true, force: true });
+        }
+        // Restore user's data
+        cpSync(tempPath, fullPath, { recursive: true });
+        // Clean up temp backup
+        rmSync(tempPath, { recursive: true, force: true });
+      } catch (err) {
+        // Silently continue if restore fails
+      }
+    }
+  }
+}
+
+/**
+ * Update framework files within preserved paths
+ * After restoring user data, this copies framework files like README.md, *.template.*, schemas/
+ */
+function updateFrameworkInPreserved(sourceDir, proagentsDir) {
+  for (const preservedPath of PRESERVE_PATHS) {
+    const sourcePath = join(sourceDir, preservedPath);
+    const targetPath = join(proagentsDir, preservedPath);
+
+    if (!existsSync(sourcePath) || !existsSync(targetPath)) continue;
+
+    try {
+      // Update README.md if exists
+      const sourceReadme = join(sourcePath, 'README.md');
+      const targetReadme = join(targetPath, 'README.md');
+      if (existsSync(sourceReadme)) {
+        cpSync(sourceReadme, targetReadme, { force: true });
+      }
+
+      // Update entry-template.md (for changelog)
+      const sourceEntryTemplate = join(sourcePath, 'entry-template.md');
+      const targetEntryTemplate = join(targetPath, 'entry-template.md');
+      if (existsSync(sourceEntryTemplate)) {
+        cpSync(sourceEntryTemplate, targetEntryTemplate, { force: true });
+      }
+
+      // Update schemas folder if exists
+      const sourceSchemas = join(sourcePath, 'schemas');
+      const targetSchemas = join(targetPath, 'schemas');
+      if (existsSync(sourceSchemas)) {
+        if (existsSync(targetSchemas)) {
+          rmSync(targetSchemas, { recursive: true, force: true });
+        }
+        cpSync(sourceSchemas, targetSchemas, { recursive: true });
+      }
+
+      // Update all *.template.md and *.template.json files
+      if (existsSync(sourcePath)) {
+        const entries = readdirSync(sourcePath, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.isFile() && (entry.name.endsWith('.template.md') || entry.name.endsWith('.template.json'))) {
+            cpSync(join(sourcePath, entry.name), join(targetPath, entry.name), { force: true });
+          }
+          // Also check subdirectories (like .learning/global/)
+          if (entry.isDirectory()) {
+            const subPath = join(sourcePath, entry.name);
+            const subTargetPath = join(targetPath, entry.name);
+            if (existsSync(subPath)) {
+              const subEntries = readdirSync(subPath, { withFileTypes: true });
+              for (const subEntry of subEntries) {
+                if (subEntry.isFile() && (subEntry.name.endsWith('.template.md') || subEntry.name.endsWith('.template.json'))) {
+                  if (!existsSync(subTargetPath)) {
+                    mkdirSync(subTargetPath, { recursive: true });
+                  }
+                  cpSync(join(subPath, subEntry.name), join(subTargetPath, subEntry.name), { force: true });
+                }
+              }
+            }
+          }
+        }
+      }
+    } catch (err) {
+      // Silently continue if update fails
+    }
+  }
+}
+
 // Config file is handled specially - merged not preserved
 const CONFIG_FILE = 'proagents.config.yaml';
 
@@ -41,7 +166,6 @@ const FRAMEWORK_FOLDERS = [
   'api-versioning',
   'approval-workflows',
   'automation',
-  'changelog',
   'cicd',
   'collaboration',
   'compliance',
@@ -89,6 +213,7 @@ const FRAMEWORK_FILES = [
   'GETTING-STARTED-STORY.md',
   'slash-commands.json',
   'AI_INSTRUCTIONS.md',  // Universal instructions kept for reference
+  'AGENTS.md',           // Universal AI instruction file (works with most AI platforms)
 ];
 
 // Project type definitions for detection
@@ -610,7 +735,7 @@ function checkIncompleteSetup(targetDir) {
   }
 
   // Check 2: No AI instruction files at all = incomplete
-  const aiFiles = ['CLAUDE.md', '.cursorrules', '.windsurfrules', 'CHATGPT.md', 'GEMINI.md'];
+  const aiFiles = ['AGENTS.md', 'CLAUDE.md', '.cursorrules', '.windsurfrules', 'CHATGPT.md', 'GEMINI.md'];
   const hasAnyAiFile = aiFiles.some(f => existsSync(join(targetDir, f)));
   if (!hasAnyAiFile) {
     return true;
@@ -666,6 +791,27 @@ async function promptIncompleteSetupChoice() {
   return 'continue';
 }
 
+/**
+ * Confirm destructive "Restart fresh" action
+ */
+async function confirmRestartFresh() {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  const question = (prompt) => new Promise(resolve => rl.question(prompt, resolve));
+
+  console.log(chalk.red.bold('\n⚠️  WARNING: This will DELETE all data in .proagents/'));
+  console.log(chalk.yellow('   Including: changelog, worklog, sessions, learning data, etc.'));
+  console.log(chalk.gray('   This action cannot be undone.\n'));
+
+  const answer = await question(chalk.red('Type "DELETE" to confirm, or press Enter to cancel: '));
+  rl.close();
+
+  return answer.trim().toUpperCase() === 'DELETE';
+}
+
 /**
  * Prompt user for .gitignore preference
  */
@@ -980,6 +1126,12 @@ export async function initCommand(options = {}) {
         console.log(chalk.cyan('\nContinuing setup...\n'));
         // Fall through to fresh install (but keep .proagents folder)
       } else if (choice === 'restart') {
+        // Confirm destructive action
+        const confirmed = await confirmRestartFresh();
+        if (!confirmed) {
+          console.log(chalk.yellow('\nCancelled. No changes made.\n'));
+          return;
+        }
         console.log(chalk.cyan('\nRestarting fresh setup...\n'));
         rmSync(proagentsDir, { recursive: true, force: true });
         // Fall through to fresh install
@@ -1025,7 +1177,21 @@ export async function initCommand(options = {}) {
 
     // Fresh install or force overwrite
     console.log(chalk.gray('Copying framework files...'));
+
+    // Backup user data if .proagents exists (to preserve changelog, worklog, etc.)
+    const userDataBackup = existsSync(proagentsDir) ? backupUserData(proagentsDir) : {};
+
     cpSync(sourceDir, proagentsDir, { recursive: true, force: true });
+
+    // Restore user data after framework copy
+    if (Object.keys(userDataBackup).length > 0) {
+      restoreUserData(proagentsDir, userDataBackup);
+      // Update framework files within preserved paths (README.md, templates, schemas)
+      updateFrameworkInPreserved(sourceDir, proagentsDir);
+      console.log(chalk.green('✓ Preserved user data (changelog, worklog, sessions, etc.)'));
+      console.log(chalk.green('✓ Updated templates and documentation in preserved folders'));
+    }
+
     console.log(chalk.green('✓ Framework files copied to ./.proagents/'));
 
     // Create config if not skipped
@@ -1397,6 +1563,9 @@ async function smartUpdate(sourceDir, targetDir) {
     }
   }
 
+  // Update framework files within preserved paths (templates, README, schemas)
+  updateFrameworkInPreserved(sourceDir, targetDir);
+
   console.log(chalk.gray('\nTip: Use "proagents ai add" to add more AI platforms'));
 }