proagents 1.6.13 → 1.6.16

package/lib/commands/ai.js

@@ -24,13 +24,19 @@ export const AI_PLATFORMS = {
   web: {
     label: 'Web-based AI Platforms',
     platforms: [
-      { id: 'chatgpt', name: 'ChatGPT / Codex', file: 'CHATGPT.md', desc: 'OpenAI ChatGPT' },
+      { id: 'chatgpt', name: 'ChatGPT', file: 'CHATGPT.md', desc: 'OpenAI ChatGPT' },
       { id: 'gemini', name: 'Gemini', file: 'GEMINI.md', desc: 'Google Gemini' },
       { id: 'replit', name: 'Replit AI', file: 'REPLIT.md', desc: 'Replit Ghostwriter' },
       { id: 'bolt', name: 'Bolt.new', file: 'BOLT.md', desc: 'StackBlitz Bolt' },
       { id: 'lovable', name: 'Lovable', file: 'LOVABLE.md', desc: 'Lovable (GPT Engineer)' },
       { id: 'groq', name: 'Groq', file: 'GROQ.md', desc: 'Groq fast inference' },
     ]
+  },
+  cli: {
+    label: 'CLI-based AI Agents',
+    platforms: [
+      { id: 'codex', name: 'Codex CLI', file: 'AGENTS.md', desc: 'OpenAI Codex CLI' },
+    ]
   }
 };
 
@@ -39,6 +45,7 @@ export function getAllPlatforms() {
   return [
     ...AI_PLATFORMS.ide.platforms,
     ...AI_PLATFORMS.web.platforms,
+    ...AI_PLATFORMS.cli.platforms,
   ];
 }
 
@@ -47,6 +54,39 @@ export function getPlatformById(id) {
   return getAllPlatforms().find(p => p.id === id);
 }
 
+/**
+ * Detect current IDE from environment variables
+ * Returns platform ID if detected and it's in our AI_PLATFORMS config, null otherwise
+ * Note: VS Code is NOT an AI platform, so we skip it even if detected
+ */
+export function detectIDE() {
+  // Cursor IDE - check for Cursor-specific env vars
+  if (process.env.CURSOR_TRACE_ID || process.env.CURSOR_CHANNEL || process.env.CURSOR_SESSION_ID) {
+    return 'cursor';
+  }
+
+  // Windsurf IDE - Codeium's IDE
+  if (process.env.WINDSURF_SESSION_ID || process.env.CODEIUM_API_KEY ||
+      (process.env.TERM_PROGRAM && process.env.TERM_PROGRAM.toLowerCase().includes('windsurf'))) {
+    return 'windsurf';
+  }
+
+  // AWS Kiro IDE
+  if (process.env.KIRO_SESSION || process.env.KIRO_API_KEY ||
+      (process.env.TERM_PROGRAM && process.env.TERM_PROGRAM.toLowerCase().includes('kiro'))) {
+    return 'kiro';
+  }
+
+  // VS Code - NOT an AI platform, explicitly return null
+  // This prevents accidental detection as we don't want to create files for plain VS Code
+  if (process.env.TERM_PROGRAM === 'vscode' || process.env.VSCODE_GIT_IPC_HANDLE) {
+    return null;
+  }
+
+  // No AI-powered IDE detected
+  return null;
+}
+
 /**
  * Interactive platform selection using readline
  * @param {string[]} previouslySelected - Previously selected platforms (from interrupted setup)
@@ -59,6 +99,21 @@ export async function selectPlatforms(previouslySelected = []) {
 
   const question = (prompt) => new Promise(resolve => rl.question(prompt, resolve));
 
+  // Auto-detect IDE and pre-select it
+  const detectedIDE = detectIDE();
+  let autoSelected = [];
+
+  if (detectedIDE) {
+    const platform = getPlatformById(detectedIDE);
+    if (platform) {
+      console.log(chalk.green(`\n✓ Detected ${platform.name} IDE - auto-selected`));
+      autoSelected = [detectedIDE];
+    }
+  }
+
+  // Merge auto-detected with previously selected
+  const preselected = [...new Set([...autoSelected, ...(previouslySelected || [])])];
+
   console.log('\n' + chalk.bold('Which AI platform(s) do you use?'));
   console.log(chalk.gray('(Enter numbers separated by commas, or "all" for all platforms)\n'));
 
@@ -69,11 +124,18 @@ export async function selectPlatforms(previouslySelected = []) {
   // IDE-based platforms
   console.log(chalk.cyan.bold(`  ${AI_PLATFORMS.ide.label}:`));
   for (const platform of AI_PLATFORMS.ide.platforms) {
-    const wasSelected = previouslySelected && previouslySelected.includes(platform.id);
-    const marker = wasSelected ? chalk.green(' ✓ (previously selected)') : '';
+    const isAutoDetected = autoSelected.includes(platform.id);
+    const wasPreviouslySelected = previouslySelected && previouslySelected.includes(platform.id);
+    const isPreselected = preselected.includes(platform.id);
+    let marker = '';
+    if (isAutoDetected) {
+      marker = chalk.green(' ✓ (auto-detected)');
+    } else if (wasPreviouslySelected) {
+      marker = chalk.green(' ✓ (previously selected)');
+    }
     console.log(chalk.white(`    ${index}. ${platform.name}`) + chalk.gray(` - ${platform.desc}`) + marker);
     indexMap[index] = platform.id;
-    if (wasSelected) preSelectedIndices.push(index);
+    if (isPreselected) preSelectedIndices.push(index);
     index++;
   }
 
@@ -82,27 +144,42 @@ export async function selectPlatforms(previouslySelected = []) {
   // Web-based platforms
   console.log(chalk.cyan.bold(`  ${AI_PLATFORMS.web.label}:`));
   for (const platform of AI_PLATFORMS.web.platforms) {
-    const wasSelected = previouslySelected && previouslySelected.includes(platform.id);
-    const marker = wasSelected ? chalk.green(' ✓ (previously selected)') : '';
+    const wasPreviouslySelected = previouslySelected && previouslySelected.includes(platform.id);
+    const isPreselected = preselected.includes(platform.id);
+    const marker = wasPreviouslySelected ? chalk.green(' ✓ (previously selected)') : '';
     console.log(chalk.white(`    ${index}. ${platform.name}`) + chalk.gray(` - ${platform.desc}`) + marker);
     indexMap[index] = platform.id;
-    if (wasSelected) preSelectedIndices.push(index);
+    if (isPreselected) preSelectedIndices.push(index);
     index++;
   }
 
   console.log('');
 
-  // Show default based on previous selection
+  // CLI-based platforms
+  console.log(chalk.cyan.bold(`  ${AI_PLATFORMS.cli.label}:`));
+  for (const platform of AI_PLATFORMS.cli.platforms) {
+    const wasPreviouslySelected = previouslySelected && previouslySelected.includes(platform.id);
+    const isPreselected = preselected.includes(platform.id);
+    const marker = wasPreviouslySelected ? chalk.green(' ✓ (previously selected)') : '';
+    console.log(chalk.white(`    ${index}. ${platform.name}`) + chalk.gray(` - ${platform.desc}`) + marker);
+    indexMap[index] = platform.id;
+    if (isPreselected) preSelectedIndices.push(index);
+    index++;
+  }
+
+  console.log('');
+
+  // Show default based on preselected (auto-detected + previously selected)
   const defaultHint = preSelectedIndices.length > 0
-    ? `Enter for previous: ${preSelectedIndices.join(',')}`
+    ? `Enter for selected: ${preSelectedIndices.join(',')}`
     : 'e.g., 1,2,3 or "all"';
 
   const answer = await question(chalk.yellow(`Your selection (${defaultHint}): `));
   rl.close();
 
-  // If user just pressed enter and we have previous selections, use them
+  // If user just pressed enter and we have preselected platforms, use them
   if (answer.trim() === '' && preSelectedIndices.length > 0) {
-    return previouslySelected;
+    return preselected;
   }
 
   if (answer.toLowerCase() === 'all') {
@@ -387,6 +464,21 @@ export function showAvailablePlatforms(currentIds) {
     index++;
   }
 
+  console.log('');
+
+  // CLI-based platforms
+  console.log(chalk.cyan.bold(`  ${AI_PLATFORMS.cli.label}:`));
+  for (const platform of AI_PLATFORMS.cli.platforms) {
+    const status = currentIds.includes(platform.id)
+      ? chalk.green(' ✓ (installed)')
+      : chalk.gray(' (not installed)');
+    console.log(chalk.white(`    ${index}. ${platform.name}`) + status);
+    if (!currentIds.includes(platform.id)) {
+      available.push({ index, platform });
+    }
+    index++;
+  }
+
   return available;
 }
 

package/lib/commands/init.js

@@ -16,8 +16,131 @@ const PRESERVE_PATHS = [
   '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';
 
@@ -90,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
@@ -611,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;
@@ -667,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
  */
@@ -981,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
@@ -1026,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
@@ -1398,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'));
 }
 

package/lib/commands/version.js

@@ -9,7 +9,7 @@ const __dirname = dirname(__filename);
 /**
  * Get CLI version from package.json
  */
-function getCliVersion() {
+export function getCliVersion() {
   try {
     const packagePath = join(__dirname, '..', '..', 'package.json');
     const packageJson = JSON.parse(readFileSync(packagePath, 'utf-8'));
@@ -41,7 +41,7 @@ function getProjectVersion(targetDir) {
 /**
  * Fetch latest version from npm
  */
-async function getLatestVersion() {
+export async function getLatestVersion() {
   try {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), 5000);
@@ -66,7 +66,7 @@ async function getLatestVersion() {
  * Compare semantic versions
  * Returns: -1 if v1 < v2, 0 if equal, 1 if v1 > v2
  */
-function compareVersions(v1, v2) {
+export function compareVersions(v1, v2) {
   const parts1 = v1.split('.').map(Number);
   const parts2 = v2.split('.').map(Number);
 
@@ -79,6 +79,27 @@ function compareVersions(v1, v2) {
   return 0;
 }
 
+/**
+ * Check for updates and display notification if available
+ * Non-blocking - runs asynchronously
+ */
+export async function checkForUpdates() {
+  try {
+    const cliVersion = getCliVersion();
+    const latestVersion = await getLatestVersion();
+
+    if (latestVersion && compareVersions(cliVersion, latestVersion) < 0) {
+      console.log('');
+      console.log(chalk.yellow(`  ╭───────────────────────────────────────────────╮`));
+      console.log(chalk.yellow(`  │  Update available: ${chalk.gray('v' + cliVersion)} → ${chalk.green('v' + latestVersion)}              │`));
+      console.log(chalk.yellow(`  │  Run: ${chalk.cyan('npx proagents init')} to update         │`));
+      console.log(chalk.yellow(`  ╰───────────────────────────────────────────────╯`));
+    }
+  } catch (error) {
+    // Silently ignore update check errors
+  }
+}
+
 /**
  * Version command - show detailed version information
  */
@@ -118,7 +139,7 @@ export async function versionCommand(options = {}) {
         console.log(chalk.green('v' + latestVersion + ' (up to date)'));
       } else {
         console.log(chalk.yellow('v' + latestVersion + ' (update available)'));
-        console.log(chalk.yellow(`                    ↳ Run 'npm update -g proagents' to update`));
+        console.log(chalk.yellow(`                    ↳ Run 'npx proagents init' to update`));
       }
     } else {
       console.log(chalk.gray('Could not fetch (offline or npm unavailable)'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proagents",
-  "version": "1.6.13",
+  "version": "1.6.16",
   "description": "AI-agnostic development workflow framework that automates the full software development lifecycle",
   "type": "module",
   "main": "lib/index.js",