proagents 1.6.12 → 1.6.13

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,6 +14,8 @@ 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)
 ];
 
 // Config file is handled specially - merged not preserved
@@ -41,7 +43,6 @@ const FRAMEWORK_FOLDERS = [
   'api-versioning',
   'approval-workflows',
   'automation',
-  'changelog',
   'cicd',
   'collaboration',
   'compliance',

package/lib/commands/open.js

@@ -0,0 +1,188 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { execSync } from 'child_process';
+import chalk from 'chalk';
+
+// File shortcuts mapping
+const FILE_SHORTCUTS = {
+  // Main config
+  'config': 'proagents.config.yaml',
+  'cfg': 'proagents.config.yaml',
+
+  // Changelog files
+  'changelog': '.proagents/changelog/_recent.md',
+  'changes': '.proagents/changelog/_recent.md',
+  'recent': '.proagents/changelog/_recent.md',
+
+  // Activity and logs
+  'activity': '.proagents/activity.log',
+  'log': '.proagents/activity.log',
+  'logs': '.proagents/activity.log',
+
+  // Context and worklog
+  'context': '.proagents/worklog/_context.md',
+  'ctx': '.proagents/worklog/_context.md',
+  'worklog': '.proagents/worklog/',
+
+  // AI instructions
+  'instructions': '.proagents/AI_INSTRUCTIONS.md',
+  'ai': '.proagents/AI_INSTRUCTIONS.md',
+
+  // Learning and feedback
+  'feedback': '.proagents/feedback.md',
+  'errors': '.proagents/errors.md',
+  'decisions': '.proagents/decisions.md',
+
+  // Watchlist
+  'watchlist': '.proagents/watchlist.yaml',
+  'watch': '.proagents/watchlist.yaml',
+
+  // Handoff
+  'handoff': '.proagents/handoff.md',
+
+  // Features
+  'features': '.proagents/active-features/',
+
+  // Standards and rules
+  'standards': '.proagents/config/standards/',
+  'rules': '.proagents/config/rules/',
+  'integrations': '.proagents/config/integrations/',
+
+  // Quick reference
+  'commands': '.proagents/PROAGENTS.md',
+  'help': '.proagents/PROAGENTS.md',
+  'workflow': '.proagents/WORKFLOW.md',
+};
+
+/**
+ * Get the editor command based on environment
+ */
+function getEditorCommand() {
+  // Check for common environment variables
+  const editor = process.env.EDITOR || process.env.VISUAL;
+  if (editor) return editor;
+
+  // Platform-specific defaults
+  const platform = process.platform;
+  if (platform === 'darwin') {
+    // macOS - try code, then open
+    try {
+      execSync('which code', { stdio: 'ignore' });
+      return 'code';
+    } catch {
+      return 'open';
+    }
+  } else if (platform === 'win32') {
+    return 'notepad';
+  } else {
+    // Linux - try code, vim, nano
+    try {
+      execSync('which code', { stdio: 'ignore' });
+      return 'code';
+    } catch {
+      try {
+        execSync('which vim', { stdio: 'ignore' });
+        return 'vim';
+      } catch {
+        return 'nano';
+      }
+    }
+  }
+}
+
+/**
+ * Open a file or directory in the default editor
+ */
+function openInEditor(path) {
+  const editor = getEditorCommand();
+
+  try {
+    if (editor === 'open') {
+      // macOS open command
+      execSync(`open "${path}"`, { stdio: 'inherit' });
+    } else if (editor === 'code') {
+      // VS Code
+      execSync(`code "${path}"`, { stdio: 'inherit' });
+    } else {
+      // Other editors
+      execSync(`${editor} "${path}"`, { stdio: 'inherit' });
+    }
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Command: proagents open <shortcut|path>
+ * Open ProAgents files quickly
+ */
+export function openCommand(target, options = {}) {
+  const targetDir = process.cwd();
+
+  // If no target, show available shortcuts
+  if (!target) {
+    console.log(chalk.bold('\nProAgents Open - Quick File Access'));
+    console.log(chalk.gray('══════════════════════════════════════════════════════════\n'));
+
+    console.log(chalk.cyan('Usage:'));
+    console.log(chalk.white('  proagents open <shortcut>'));
+    console.log(chalk.white('  proagents open <file-path>\n'));
+
+    console.log(chalk.cyan('Shortcuts:'));
+    console.log(chalk.gray('─────────────────────────────────────────────────'));
+
+    const categories = {
+      'Configuration': ['config', 'watchlist', 'standards', 'rules'],
+      'Changelog & Logs': ['changelog', 'activity', 'context'],
+      'AI & Workflow': ['instructions', 'commands', 'workflow'],
+      'Learning': ['feedback', 'errors', 'decisions'],
+      'Collaboration': ['handoff', 'features', 'worklog'],
+    };
+
+    for (const [category, shortcuts] of Object.entries(categories)) {
+      console.log(chalk.yellow(`\n  ${category}:`));
+      for (const shortcut of shortcuts) {
+        const path = FILE_SHORTCUTS[shortcut];
+        if (path) {
+          const exists = existsSync(join(targetDir, path));
+          const status = exists ? chalk.green('✓') : chalk.gray('○');
+          console.log(`    ${status} ${chalk.white(shortcut.padEnd(15))} → ${chalk.gray(path)}`);
+        }
+      }
+    }
+
+    console.log(chalk.gray('\n─────────────────────────────────────────────────'));
+    console.log(chalk.gray('Legend: ') + chalk.green('✓ exists  ') + chalk.gray('○ not created yet\n'));
+    return;
+  }
+
+  // Check if target is a shortcut
+  let filePath = FILE_SHORTCUTS[target.toLowerCase()];
+
+  if (filePath) {
+    filePath = join(targetDir, filePath);
+  } else {
+    // Treat as direct path
+    filePath = target.startsWith('/') ? target : join(targetDir, target);
+  }
+
+  // Check if file/directory exists
+  if (!existsSync(filePath)) {
+    console.log(chalk.red(`\nFile not found: ${filePath}`));
+    console.log(chalk.gray('Run "proagents open" to see available shortcuts.\n'));
+    return;
+  }
+
+  // Open the file
+  console.log(chalk.cyan(`\nOpening: ${filePath}`));
+
+  const success = openInEditor(filePath);
+
+  if (success) {
+    console.log(chalk.green('✓ Opened in editor\n'));
+  } else {
+    console.log(chalk.yellow(`\nCould not open automatically.`));
+    console.log(chalk.gray(`Path: ${filePath}\n`));
+  }
+}