wogiflow 1.0.0

package/lib/upgrader.js

@@ -0,0 +1,401 @@
+#!/usr/bin/env node
+
+/**
+ * Wogi Flow Upgrader
+ *
+ * Handles project upgrades with `flow upgrade`.
+ * Migrates projects from older versions to the current version,
+ * preserving user data while updating configuration and scripts.
+ *
+ * @module lib/upgrader
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Shared utilities
+const { findProjectRoot, copyDir, safeReadJson } = require('./utils');
+
+// Package info
+const packageJson = require('../package.json');
+const CURRENT_VERSION = packageJson.version;
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+
+/**
+ * Parse command line arguments
+ * @param {string[]} args - Command line arguments
+ * @returns {Object} Parsed options
+ */
+function parseArgs(args) {
+  const options = {
+    force: false,
+    dryRun: false,
+    help: false
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--force' || arg === '-f') {
+      options.force = true;
+    } else if (arg === '--dry-run' || arg === '-n') {
+      options.dryRun = true;
+    } else if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    }
+  }
+
+  return options;
+}
+
+/**
+ * Show help message
+ */
+function showHelp() {
+  console.log(`
+Usage: flow upgrade [options]
+
+Upgrade Wogi Flow in the current project.
+
+Options:
+  --force, -f         Force upgrade even if versions match
+  --dry-run, -n       Show what would be changed without making changes
+  --help, -h          Show this help message
+
+The upgrade process:
+  1. Backs up current configuration
+  2. Updates scripts to latest version
+  3. Migrates configuration if needed
+  4. Updates templates and agents
+  5. Preserves user state files
+
+Examples:
+  flow upgrade                 # Upgrade current project
+  flow upgrade --dry-run       # Preview changes
+  flow upgrade --force         # Force re-upgrade
+`);
+}
+
+// findProjectRoot is imported from ./utils
+
+/**
+ * Get current project version
+ * @param {string} projectRoot - Project root directory
+ * @returns {string|null} Version string or null
+ */
+function getProjectVersion(projectRoot) {
+  const configPath = path.join(projectRoot, '.workflow', 'config.json');
+  const config = safeReadJson(configPath);
+  return config?.version || null;
+}
+
+/**
+ * Compare versions
+ * @param {string} v1 - First version
+ * @param {string} v2 - Second version
+ * @returns {number} -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 < Math.max(parts1.length, parts2.length); i++) {
+    const p1 = parts1[i] || 0;
+    const p2 = parts2[i] || 0;
+    if (p1 < p2) return -1;
+    if (p1 > p2) return 1;
+  }
+
+  return 0;
+}
+
+/**
+ * Create a backup of the current configuration
+ * @param {string} projectRoot - Project root directory
+ * @param {boolean} dryRun - If true, only show what would be done
+ * @returns {string|null} Backup directory path or null
+ */
+function createBackup(projectRoot, dryRun) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupDir = path.join(projectRoot, '.workflow', 'backups', timestamp);
+
+  if (dryRun) {
+    console.log(`  Would create backup at: ${backupDir}`);
+    return backupDir;
+  }
+
+  fs.mkdirSync(backupDir, { recursive: true });
+
+  // Backup config.json
+  const configPath = path.join(projectRoot, '.workflow', 'config.json');
+  if (fs.existsSync(configPath)) {
+    fs.copyFileSync(configPath, path.join(backupDir, 'config.json'));
+  }
+
+  console.log(`  Created backup at: ${backupDir}`);
+  return backupDir;
+}
+
+// copyDir is imported from ./utils (with dryRun support)
+
+/**
+ * Update scripts directory
+ * @param {string} projectRoot - Project root directory
+ * @param {boolean} dryRun - If true, only show what would be done
+ */
+function updateScripts(projectRoot, dryRun) {
+  const packageScripts = path.join(PACKAGE_ROOT, 'scripts');
+  const projectScripts = path.join(projectRoot, 'scripts');
+
+  if (!fs.existsSync(packageScripts)) {
+    console.log('  Warning: Package scripts not found');
+    return;
+  }
+
+  if (dryRun) {
+    console.log(`  Would update: scripts/`);
+    return;
+  }
+
+  // Copy all scripts
+  copyDir(packageScripts, projectScripts, false);
+
+  // Make flow script executable
+  const flowScript = path.join(projectScripts, 'flow');
+  if (fs.existsSync(flowScript)) {
+    fs.chmodSync(flowScript, '755');
+  }
+
+  console.log('  Updated scripts/');
+}
+
+/**
+ * Update templates
+ * @param {string} projectRoot - Project root directory
+ * @param {boolean} dryRun - If true, only show what would be done
+ */
+function updateTemplates(projectRoot, dryRun) {
+  const packageTemplates = path.join(PACKAGE_ROOT, '.workflow', 'templates');
+  const projectTemplates = path.join(projectRoot, '.workflow', 'templates');
+
+  if (fs.existsSync(packageTemplates)) {
+    if (dryRun) {
+      console.log('  Would update: .workflow/templates/');
+    } else {
+      copyDir(packageTemplates, projectTemplates, false);
+      console.log('  Updated .workflow/templates/');
+    }
+  }
+}
+
+/**
+ * Update agents
+ * @param {string} projectRoot - Project root directory
+ * @param {boolean} dryRun - If true, only show what would be done
+ */
+function updateAgents(projectRoot, dryRun) {
+  const packageAgents = path.join(PACKAGE_ROOT, '.workflow', 'agents');
+  const projectAgents = path.join(projectRoot, '.workflow', 'agents');
+
+  if (fs.existsSync(packageAgents)) {
+    if (dryRun) {
+      console.log('  Would update: .workflow/agents/');
+    } else {
+      copyDir(packageAgents, projectAgents, false);
+      console.log('  Updated .workflow/agents/');
+    }
+  }
+}
+
+/**
+ * Update bridges
+ * @param {string} projectRoot - Project root directory
+ * @param {boolean} dryRun - If true, only show what would be done
+ */
+function updateBridges(projectRoot, dryRun) {
+  const packageBridges = path.join(PACKAGE_ROOT, '.workflow', 'bridges');
+  const projectBridges = path.join(projectRoot, '.workflow', 'bridges');
+
+  if (fs.existsSync(packageBridges)) {
+    if (dryRun) {
+      console.log('  Would update: .workflow/bridges/');
+    } else {
+      copyDir(packageBridges, projectBridges, false);
+      console.log('  Updated .workflow/bridges/');
+    }
+  }
+}
+
+/**
+ * Update configuration version
+ * @param {string} projectRoot - Project root directory
+ * @param {boolean} dryRun - If true, only show what would be done
+ */
+function updateConfigVersion(projectRoot, dryRun) {
+  const configPath = path.join(projectRoot, '.workflow', 'config.json');
+
+  const config = safeReadJson(configPath);
+  if (!config) {
+    console.log('  Warning: config.json not found or invalid');
+    return;
+  }
+
+  if (dryRun) {
+    console.log(`  Would update version in config.json to ${CURRENT_VERSION}`);
+    return;
+  }
+
+  try {
+    config.version = CURRENT_VERSION;
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+    console.log(`  Updated config.json version to ${CURRENT_VERSION}`);
+  } catch (err) {
+    console.log(`  Warning: Could not update config.json: ${err.message}`);
+  }
+}
+
+/**
+ * Run version-specific migrations
+ * @param {string} projectRoot - Project root directory
+ * @param {string} fromVersion - Current version
+ * @param {string} toVersion - Target version
+ * @param {boolean} dryRun - If true, only show what would be done
+ */
+function runMigrations(projectRoot, fromVersion, toVersion, dryRun) {
+  // Define migrations for specific version ranges
+  const migrations = [
+    {
+      from: '1.0.0',
+      to: '1.5.0',
+      name: 'Add state directory',
+      run: (root) => {
+        const stateDir = path.join(root, '.workflow', 'state');
+        if (!fs.existsSync(stateDir)) {
+          fs.mkdirSync(stateDir, { recursive: true });
+        }
+      }
+    },
+    {
+      from: '1.5.0',
+      to: '1.9.0',
+      name: 'Add models directory',
+      run: (root) => {
+        const modelsDir = path.join(root, '.workflow', 'models');
+        if (!fs.existsSync(modelsDir)) {
+          fs.mkdirSync(modelsDir, { recursive: true });
+        }
+      }
+    }
+    // Add more migrations as needed
+  ];
+
+  // Find applicable migrations
+  const applicable = migrations.filter(m => {
+    return compareVersions(fromVersion, m.from) >= 0 &&
+           compareVersions(fromVersion, m.to) < 0 &&
+           compareVersions(toVersion, m.to) >= 0;
+  });
+
+  if (applicable.length === 0) {
+    console.log('  No migrations needed');
+    return;
+  }
+
+  console.log(`  Running ${applicable.length} migration(s):`);
+
+  for (const migration of applicable) {
+    if (dryRun) {
+      console.log(`    Would run: ${migration.name}`);
+    } else {
+      try {
+        migration.run(projectRoot);
+        console.log(`    ✓ ${migration.name}`);
+      } catch (err) {
+        console.log(`    ✗ ${migration.name}: ${err.message}`);
+      }
+    }
+  }
+}
+
+/**
+ * Main upgrade function
+ * @param {string[]} args - Command line arguments
+ */
+async function upgrade(args) {
+  const options = parseArgs(args);
+
+  if (options.help) {
+    showHelp();
+    return;
+  }
+
+  const projectRoot = findProjectRoot();
+
+  if (!projectRoot) {
+    console.error('Error: Not in a Wogi Flow project');
+    console.error('Use `flow init` to initialize a new project');
+    process.exit(1);
+  }
+
+  const currentVersion = getProjectVersion(projectRoot);
+
+  if (!currentVersion) {
+    console.error('Error: Could not determine project version');
+    console.error('The .workflow/config.json may be missing or invalid');
+    process.exit(1);
+  }
+
+  console.log('\n🔄 Wogi Flow Upgrader\n');
+  console.log(`  Current version: ${currentVersion}`);
+  console.log(`  Target version:  ${CURRENT_VERSION}`);
+
+  if (options.dryRun) {
+    console.log('\n  (Dry run - no changes will be made)\n');
+  }
+
+  // Check if upgrade is needed
+  const comparison = compareVersions(currentVersion, CURRENT_VERSION);
+
+  if (comparison === 0 && !options.force) {
+    console.log('\n✓ Project is already at the latest version');
+    return;
+  }
+
+  if (comparison > 0) {
+    console.log('\n⚠ Project version is newer than package version');
+    console.log('  This may indicate a development version.');
+    if (!options.force) {
+      console.log('  Use --force to downgrade');
+      return;
+    }
+  }
+
+  console.log('\nUpgrading...\n');
+
+  // Create backup
+  createBackup(projectRoot, options.dryRun);
+
+  // Run migrations
+  runMigrations(projectRoot, currentVersion, CURRENT_VERSION, options.dryRun);
+
+  // Update components
+  updateScripts(projectRoot, options.dryRun);
+  updateTemplates(projectRoot, options.dryRun);
+  updateAgents(projectRoot, options.dryRun);
+  updateBridges(projectRoot, options.dryRun);
+
+  // Update version in config
+  updateConfigVersion(projectRoot, options.dryRun);
+
+  if (options.dryRun) {
+    console.log('\n✓ Dry run complete - no changes made');
+  } else {
+    console.log('\n✅ Upgrade complete!\n');
+    console.log('Next steps:');
+    console.log('  1. Review changes in .workflow/');
+    console.log('  2. Run `./scripts/flow health` to verify installation');
+    console.log('  3. Commit the upgraded files');
+  }
+}
+
+module.exports = { upgrade };

package/lib/utils.js

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+
+/**
+ * Wogi Flow Shared Utilities
+ *
+ * Common utility functions used across lib modules.
+ * Extracted to reduce duplication and standardize behavior.
+ *
+ * @module lib/utils
+ */
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+
+// Constants
+const MAX_REDIRECTS = 5;
+const REQUEST_TIMEOUT = 10000; // 10 seconds
+const MAX_RESPONSE_SIZE = 10 * 1024 * 1024; // 10MB
+
+/**
+ * Find the project root by looking for .workflow directory
+ * @returns {string|null} Project root path or null if not in a project
+ */
+function findProjectRoot() {
+  let dir = process.cwd();
+  const root = path.parse(dir).root;
+
+  while (dir !== root) {
+    if (fs.existsSync(path.join(dir, '.workflow'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+
+  return null;
+}
+
+/**
+ * Safely parse JSON with prototype pollution protection
+ * @param {string} content - JSON string to parse
+ * @param {*} defaultValue - Default value if parsing fails
+ * @returns {Object} Parsed object or default value
+ */
+function safeJsonParse(content, defaultValue = null) {
+  try {
+    const parsed = JSON.parse(content);
+
+    // Protect against prototype pollution
+    // Only check for __proto__ and prototype as own properties (not inherited)
+    if (parsed && typeof parsed === 'object') {
+      if (Object.prototype.hasOwnProperty.call(parsed, '__proto__') ||
+          Object.prototype.hasOwnProperty.call(parsed, 'prototype')) {
+        console.warn('Warning: Potentially malicious JSON detected');
+        return defaultValue;
+      }
+    }
+
+    return parsed;
+  } catch (err) {
+    return defaultValue;
+  }
+}
+
+/**
+ * Safely read and parse JSON file
+ * @param {string} filePath - Path to JSON file
+ * @param {*} defaultValue - Default value if reading/parsing fails
+ * @returns {Object} Parsed object or default value
+ */
+function safeReadJson(filePath, defaultValue = null) {
+  try {
+    if (!fs.existsSync(filePath)) {
+      return defaultValue;
+    }
+    const content = fs.readFileSync(filePath, 'utf8');
+    return safeJsonParse(content, defaultValue);
+  } catch (err) {
+    return defaultValue;
+  }
+}
+
+/**
+ * Make an HTTPS GET request with safety limits
+ * @param {string} url - URL to fetch
+ * @param {Object} options - Options
+ * @param {number} options.timeout - Request timeout in ms
+ * @param {number} options.maxRedirects - Maximum redirects to follow
+ * @param {number} options.redirectCount - Current redirect count (internal)
+ * @returns {Promise<string>} Response body
+ */
+function httpsGet(url, options = {}) {
+  const timeout = options.timeout || REQUEST_TIMEOUT;
+  const maxRedirects = options.maxRedirects || MAX_REDIRECTS;
+  const redirectCount = options.redirectCount || 0;
+
+  return new Promise((resolve, reject) => {
+    // Validate URL
+    let parsedUrl;
+    try {
+      parsedUrl = new URL(url);
+      if (parsedUrl.protocol !== 'https:') {
+        reject(new Error('Only HTTPS URLs are allowed'));
+        return;
+      }
+    } catch (err) {
+      reject(new Error(`Invalid URL: ${url}`));
+      return;
+    }
+
+    const req = https.get(url, { timeout }, (res) => {
+      // Handle redirects
+      if (res.statusCode === 301 || res.statusCode === 302) {
+        if (redirectCount >= maxRedirects) {
+          reject(new Error('Too many redirects'));
+          return;
+        }
+
+        const location = res.headers.location;
+        if (!location) {
+          reject(new Error('Redirect without location header'));
+          return;
+        }
+
+        // Validate redirect URL (same-origin or absolute HTTPS)
+        let redirectUrl;
+        try {
+          redirectUrl = new URL(location, url);
+          if (redirectUrl.protocol !== 'https:') {
+            reject(new Error('Redirect to non-HTTPS URL not allowed'));
+            return;
+          }
+        } catch (err) {
+          reject(new Error(`Invalid redirect URL: ${location}`));
+          return;
+        }
+
+        return httpsGet(redirectUrl.href, {
+          ...options,
+          redirectCount: redirectCount + 1
+        }).then(resolve).catch(reject);
+      }
+
+      if (res.statusCode !== 200) {
+        reject(new Error(`HTTP ${res.statusCode}`));
+        return;
+      }
+
+      let data = '';
+      let size = 0;
+
+      res.on('data', chunk => {
+        size += chunk.length;
+        if (size > MAX_RESPONSE_SIZE) {
+          req.destroy();
+          reject(new Error('Response too large'));
+          return;
+        }
+        data += chunk;
+      });
+
+      res.on('end', () => resolve(data));
+      res.on('error', reject);
+    });
+
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error('Request timeout'));
+    });
+
+    req.on('error', reject);
+  });
+}
+
+/**
+ * Copy directory recursively with optional dry-run
+ * @param {string} src - Source directory
+ * @param {string} dest - Destination directory
+ * @param {boolean} dryRun - If true, only show what would be done
+ */
+function copyDir(src, dest, dryRun = false) {
+  if (!fs.existsSync(src)) return;
+
+  if (dryRun) {
+    console.log(`  Would copy: ${src} -> ${dest}`);
+    return;
+  }
+
+  try {
+    fs.mkdirSync(dest, { recursive: true });
+
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+
+      if (entry.isDirectory()) {
+        copyDir(srcPath, destPath, dryRun);
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+      }
+    }
+  } catch (err) {
+    console.error(`  Error copying ${src}: ${err.message}`);
+  }
+}
+
+/**
+ * Parse CLI arguments with bounds checking
+ * @param {string[]} args - Command line arguments
+ * @param {Object} spec - Argument specification { flags: { '--flag': 'key' }, withValue: ['--flag'] }
+ * @returns {Object} Parsed options
+ */
+function parseArgs(args, spec = {}) {
+  const options = {};
+  const flags = spec.flags || {};
+  const withValue = new Set(spec.withValue || []);
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (flags[arg]) {
+      const key = flags[arg];
+      if (withValue.has(arg)) {
+        // Bounds check before accessing next argument
+        if (i + 1 >= args.length) {
+          console.error(`Error: ${arg} requires a value`);
+          options._error = true;
+          continue;
+        }
+        options[key] = args[++i];
+      } else {
+        options[key] = true;
+      }
+    } else if (!arg.startsWith('-')) {
+      // Positional argument
+      if (!options._positional) options._positional = [];
+      options._positional.push(arg);
+    }
+  }
+
+  return options;
+}
+
+/**
+ * Validate a path is within a base directory (prevents path traversal)
+ * @param {string} basePath - Base directory path
+ * @param {string} targetPath - Target path to validate
+ * @returns {string|null} Resolved path if valid, null if traversal detected
+ */
+function validatePath(basePath, targetPath) {
+  const resolved = path.resolve(basePath, targetPath);
+  const normalizedBase = path.resolve(basePath);
+
+  if (!resolved.startsWith(normalizedBase + path.sep) && resolved !== normalizedBase) {
+    return null;
+  }
+
+  return resolved;
+}
+
+/**
+ * Safely write file with path validation
+ * @param {string} basePath - Base directory (file must be within this)
+ * @param {string} relativePath - Relative path within base
+ * @param {string} content - File content
+ * @returns {boolean} True if written successfully
+ */
+function safeWriteFile(basePath, relativePath, content) {
+  // Validate path to prevent traversal
+  const safePath = validatePath(basePath, relativePath);
+  if (!safePath) {
+    console.error(`Error: Invalid path '${relativePath}' (path traversal detected)`);
+    return false;
+  }
+
+  try {
+    // Ensure parent directory exists
+    const dir = path.dirname(safePath);
+    fs.mkdirSync(dir, { recursive: true });
+
+    fs.writeFileSync(safePath, content);
+    return true;
+  } catch (err) {
+    console.error(`Error writing file: ${err.message}`);
+    return false;
+  }
+}
+
+module.exports = {
+  findProjectRoot,
+  safeJsonParse,
+  safeReadJson,
+  httpsGet,
+  copyDir,
+  parseArgs,
+  validatePath,
+  safeWriteFile,
+
+  // Constants
+  MAX_REDIRECTS,
+  REQUEST_TIMEOUT,
+  MAX_RESPONSE_SIZE
+};