gsd-opencode 1.9.2 → 1.10.2

package/src/utils/hash.js

@@ -0,0 +1,71 @@
+/**
+ * Hash utility for file integrity checking.
+ *
+ * This module provides SHA-256 hashing functions for verifying file integrity
+ * during installation health checks. Uses Node.js built-in crypto module.
+ *
+ * @module hash
+ */
+
+import crypto from 'crypto';
+import fs from 'fs/promises';
+
+/**
+ * Generates SHA-256 hash of a file's contents.
+ *
+ * Reads the file at the specified path and returns its SHA-256 hash.
+ * Returns null if the file doesn't exist or can't be read.
+ *
+ * @param {string} filePath - Absolute or relative path to the file
+ * @returns {Promise<string|null>} Hex-encoded SHA-256 hash, or null if file can't be read
+ *
+ * @example
+ * const hash = await hashFile('/path/to/file.txt');
+ * if (hash) {
+ *   console.log(`File hash: ${hash}`);
+ * } else {
+ *   console.log('File not found or unreadable');
+ * }
+ */
+export async function hashFile(filePath) {
+  try {
+    const content = await fs.readFile(filePath);
+    return crypto.createHash('sha256').update(content).digest('hex');
+  } catch (error) {
+    // Return null for any error (file not found, permission denied, etc.)
+    return null;
+  }
+}
+
+/**
+ * Generates SHA-256 hash of a string.
+ *
+ * Useful for comparing expected content hashes or generating
+ * checksums for verification purposes.
+ *
+ * @param {string} str - String to hash
+ * @returns {string} Hex-encoded SHA-256 hash
+ *
+ * @example
+ * const hash = hashString('hello world');
+ * console.log(hash); // 'b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9'
+ */
+export function hashString(str) {
+  if (typeof str !== 'string') {
+    throw new TypeError('Input must be a string');
+  }
+  return crypto.createHash('sha256').update(str, 'utf-8').digest('hex');
+}
+
+/**
+ * Default export for the hash module.
+ *
+ * @example
+ * import { hashFile, hashString } from './utils/hash.js';
+ * const fileHash = await hashFile('/path/to/file.txt');
+ * const strHash = hashString('test content');
+ */
+export default {
+  hashFile,
+  hashString
+};

package/src/utils/interactive.js

@@ -0,0 +1,222 @@
+/**
+ * Interactive prompt utilities for GSD-OpenCode CLI
+ *
+ * Provides user-friendly prompts for installation scope selection,
+ * confirmations, and repair decisions. All prompts handle Ctrl+C
+ * gracefully to ensure clean aborts with no side effects.
+ *
+ * @module interactive
+ */
+
+import { select, confirm, input } from '@inquirer/prompts';
+
+/**
+ * Prompts user to select installation scope
+ *
+ * Displays a select prompt with "Global" as the default option.
+ * Global installs to ~/.config/opencode/, local installs to ./.opencode/
+ *
+ * @returns {Promise<string|null>} 'global', 'local', or null if cancelled
+ * @example
+ * const scope = await promptInstallScope();
+ * if (scope === null) {
+ *   console.log('Installation cancelled');
+ *   process.exit(0);
+ * }
+ */
+export async function promptInstallScope() {
+  try {
+    const answer = await select({
+      message: 'Where would you like to install GSD-OpenCode?',
+      choices: [
+        {
+          name: 'Global (~/.config/opencode/)',
+          value: 'global',
+          description: 'Install globally for all projects'
+        },
+        {
+          name: 'Local (./.opencode/)',
+          value: 'local',
+          description: 'Install locally in current directory'
+        }
+      ],
+      default: 'global'
+    });
+
+    return answer;
+  } catch (error) {
+    // Handle Ctrl+C (SIGINT) - user cancelled
+    if (error.name === 'AbortPromptError' || error.message?.includes('cancel')) {
+      return null;
+    }
+    // Re-throw unexpected errors
+    throw error;
+  }
+}
+
+/**
+ * Prompts user for a yes/no confirmation
+ *
+ * @param {string} message - The confirmation message to display
+ * @param {boolean} [defaultValue=true] - Default value if user just presses Enter
+ * @returns {Promise<boolean|null>} true/false, or null if cancelled
+ * @example
+ * const confirmed = await promptConfirmation('Remove existing installation?', true);
+ * if (confirmed === null) {
+ *   console.log('Operation cancelled');
+ *   process.exit(0);
+ * }
+ * if (confirmed) {
+ *   // Proceed with removal
+ * }
+ */
+export async function promptConfirmation(message, defaultValue = true) {
+  try {
+    const answer = await confirm({
+      message,
+      default: defaultValue
+    });
+
+    return answer;
+  } catch (error) {
+    // Handle Ctrl+C (SIGINT) - user cancelled
+    if (error.name === 'AbortPromptError' || error.message?.includes('cancel')) {
+      return null;
+    }
+    // Re-throw unexpected errors
+    throw error;
+  }
+}
+
+/**
+ * Prompts user to choose between repairing existing installation,
+ * performing a fresh install, or cancelling
+ *
+ * Called when a partial or broken installation is detected.
+ *
+ * @returns {Promise<string|null>} 'repair', 'fresh', 'cancel', or null if cancelled
+ * @example
+ * const choice = await promptRepairOrFresh();
+ * if (choice === null || choice === 'cancel') {
+ *   console.log('Installation cancelled');
+ *   process.exit(0);
+ * }
+ * if (choice === 'repair') {
+ *   // Repair existing installation
+ * } else if (choice === 'fresh') {
+ *   // Remove existing and perform fresh install
+ * }
+ */
+export async function promptRepairOrFresh() {
+  try {
+    const answer = await select({
+      message: 'Existing installation detected. What would you like to do?',
+      choices: [
+        {
+          name: 'Repair existing installation',
+          value: 'repair',
+          description: 'Fix the existing installation without data loss'
+        },
+        {
+          name: 'Fresh install (remove existing)',
+          value: 'fresh',
+          description: 'Remove existing and start fresh'
+        },
+        {
+          name: 'Cancel',
+          value: 'cancel',
+          description: 'Abort installation'
+        }
+      ],
+      default: 'repair'
+    });
+
+    return answer;
+  } catch (error) {
+    // Handle Ctrl+C (SIGINT) - user cancelled
+    if (error.name === 'AbortPromptError' || error.message?.includes('cancel')) {
+      return 'cancel';
+    }
+    // Re-throw unexpected errors
+    throw error;
+  }
+}
+
+/**
+ * Prompts the user to type a confirmation word to proceed.
+ *
+ * The user must type the exact confirmation word to proceed. No retries - if the
+ * user enters anything else, the function immediately returns false.
+ *
+ * @param {string} message - The message to display before the prompt
+ * @param {string} confirmWord - The word user must type to confirm
+ * @returns {Promise<boolean|null>} true if confirmed, false if rejected, null if cancelled
+ * @example
+ * const confirmed = await promptTypedConfirmation(
+ *   'This will uninstall GSD-OpenCode. Type "yes" to confirm',
+ *   'yes'
+ * );
+ * if (confirmed === null) {
+ *   console.log('Operation cancelled');
+ *   process.exit(130);
+ * }
+ * if (!confirmed) {
+ *   console.log('Confirmation failed');
+ *   process.exit(0);
+ * }
+ */
+export async function promptTypedConfirmation(message, confirmWord) {
+  const normalizedConfirmWord = confirmWord.toLowerCase();
+
+  try {
+    const answer = await input({
+      message: `${message} (type "${confirmWord}")`,
+      validate: (value) => {
+        if (!value || value.trim() === '') {
+          return 'Please enter the confirmation word';
+        }
+        return true;
+      }
+    });
+
+    const normalizedAnswer = answer.trim().toLowerCase();
+
+    if (normalizedAnswer === normalizedConfirmWord) {
+      return true;
+    }
+
+    // Wrong word entered - immediately return false
+    return false;
+  } catch (error) {
+    // Handle Ctrl+C (SIGINT) - user cancelled
+    if (error.name === 'AbortPromptError' || error.message?.includes('cancel')) {
+      return null;
+    }
+    // Re-throw unexpected errors
+    throw error;
+  }
+}
+
+/**
+ * Checks if the current environment supports interactive prompts
+ *
+ * Returns false if stdin is not a TTY (e.g., piped input, CI environment)
+ *
+ * @returns {boolean} true if interactive prompts are supported
+ */
+export function isInteractive() {
+  return process.stdin.isTTY && process.stdout.isTTY;
+}
+
+/**
+ * Helper to handle prompt cancellation consistently
+ *
+ * Logs cancellation message and exits cleanly if prompts are cancelled.
+ *
+ * @param {string} [message='Operation cancelled'] - Message to display
+ * @param {number} [exitCode=0] - Exit code (0 for clean abort)
+ */
+export function handleCancellation(message = 'Operation cancelled', exitCode = 0) {
+  console.log(message);
+  process.exit(exitCode);
+}

package/src/utils/logger.js

@@ -0,0 +1,128 @@
+/**
+ * Logger utility for consistent terminal output styling.
+ * 
+ * Uses chalk for color support and automatically respects NO_COLOR environment variable.
+ * All output goes to stderr to avoid polluting piped output.
+ * 
+ * @module logger
+ */
+
+import chalk from 'chalk';
+
+/**
+ * Module-level verbose flag.
+ * When true, debug messages and full stack traces are shown.
+ * @type {boolean}
+ */
+let verboseMode = false;
+
+/**
+ * Set verbose mode for debug output.
+ * @param {boolean} enabled - Whether to enable verbose output
+ */
+export function setVerbose(enabled) {
+  verboseMode = Boolean(enabled);
+}
+
+/**
+ * Get current verbose mode status.
+ * @returns {boolean} Current verbose mode
+ */
+export function isVerbose() {
+  return verboseMode;
+}
+
+/**
+ * Logger object with styled output methods.
+ * All methods output to stderr to avoid breaking piped output.
+ */
+export const logger = {
+  /**
+   * Print blue info message with ℹ symbol.
+   * @param {string} message - Message to display
+   */
+  info(message) {
+    console.error(chalk.blue('ℹ'), message);
+  },
+
+  /**
+   * Print green success message with ✓ symbol.
+   * @param {string} message - Message to display
+   */
+  success(message) {
+    console.error(chalk.green('✓'), message);
+  },
+
+  /**
+   * Print yellow warning message with ⚠ symbol.
+   * @param {string} message - Message to display
+   */
+  warning(message) {
+    console.error(chalk.yellow('⚠'), message);
+  },
+
+  /**
+   * Print red error message with ✗ symbol.
+   * In verbose mode, includes full stack trace if error object provided.
+   * @param {string} message - Error message to display
+   * @param {Error} [error] - Optional error object for stack trace
+   */
+  error(message, error) {
+    console.error(chalk.red('✗'), message);
+    
+    if (verboseMode && error?.stack) {
+      console.error(chalk.dim(error.stack));
+    }
+  },
+
+  /**
+   * Print gray debug message (only shown in verbose mode).
+   * @param {string} message - Debug message to display
+   */
+  debug(message) {
+    if (verboseMode) {
+      console.error(chalk.gray('[debug]'), message);
+    }
+  },
+
+  /**
+   * Print bold white heading for sections.
+   * @param {string} text - Heading text
+   */
+  heading(text) {
+    console.error(chalk.bold.white(text));
+  },
+
+  /**
+   * Print dimmed text for secondary information.
+   * @param {string} text - Text to dim
+   */
+  dim(text) {
+    console.error(chalk.dim(text));
+  },
+
+  /**
+   * Print cyan inline code formatting.
+   * @param {string} text - Code text to format
+   */
+  code(text) {
+    console.error(chalk.cyan(text));
+  }
+};
+
+/**
+ * Colorize utility for inline color formatting.
+ * Returns chalk instance for flexible color usage.
+ * @type {object}
+ */
+export const colorize = chalk;
+
+/**
+ * Default export combining logger and utilities.
+ */
+export default {
+  logger,
+  colorize,
+  setVerbose,
+  isVerbose
+};

package/src/utils/npm-registry.js

@@ -0,0 +1,255 @@
+/**
+ * NPM Registry query utility for fetching package version information.
+ *
+ * Provides a clean abstraction for querying npm registry versions, supporting
+ * both public packages (gsd-opencode) and scoped packages (@rokicool/gsd-opencode).
+ * This utility is the foundation for the update command's version checking capabilities.
+ *
+ * @module npm-registry
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+/**
+ * Valid npm package name pattern.
+ * Supports scoped packages like @scope/name and regular packages.
+ * @type {RegExp}
+ */
+const VALID_PACKAGE_NAME = /^(?:@([^/]+)\/)?([^/]+)$/;
+
+/**
+ * Utility class for querying npm registry version information.
+ *
+ * @example
+ * const npm = new NpmRegistry();
+ * const version = await npm.getLatestVersion('gsd-opencode');
+ * const allVersions = await npm.getAllVersions('@rokicool/gsd-opencode');
+ */
+export class NpmRegistry {
+  /**
+   * Creates a new NpmRegistry instance.
+   * @param {Object} [options={}] - Configuration options
+   * @param {Object} [options.logger] - Logger instance for output (defaults to console)
+   */
+  constructor(options = {}) {
+    this.logger = options.logger || console;
+  }
+
+  /**
+   * Validates a package name to prevent command injection.
+   *
+   * @param {string} packageName - The package name to validate
+   * @returns {boolean} True if valid, false otherwise
+   * @private
+   */
+  _validatePackageName(packageName) {
+    if (!packageName || typeof packageName !== 'string') {
+      return false;
+    }
+    return VALID_PACKAGE_NAME.test(packageName);
+  }
+
+  /**
+   * Escapes a package name for safe use in shell commands.
+   *
+   * @param {string} packageName - The package name to escape
+   * @returns {string} Escaped package name
+   * @private
+   */
+  _escapePackageName(packageName) {
+    // Replace any potentially dangerous characters
+    return packageName.replace(/[^a-zA-Z0-9@._/-]/g, '');
+  }
+
+  /**
+   * Gets the latest version of a package from npm registry.
+   *
+   * @param {string} packageName - The package name (e.g., 'gsd-opencode' or '@rokicool/gsd-opencode')
+   * @returns {Promise<string|null>} The latest version string (e.g., '1.9.2') or null on error
+   * @example
+   * const npm = new NpmRegistry();
+   * const version = await npm.getLatestVersion('gsd-opencode');
+   * console.log(version); // '1.9.2'
+   */
+  async getLatestVersion(packageName) {
+    if (!this._validatePackageName(packageName)) {
+      this.logger.error(`Invalid package name: ${packageName}`);
+      return null;
+    }
+
+    const escapedName = this._escapePackageName(packageName);
+
+    try {
+      const { stdout } = await execAsync(`npm view ${escapedName} version`);
+      const version = stdout.trim();
+      return version;
+    } catch (error) {
+      this._handleError('getLatestVersion', packageName, error);
+      return null;
+    }
+  }
+
+  /**
+   * Gets all available versions of a package from npm registry.
+   *
+   * @param {string} packageName - The package name (e.g., 'gsd-opencode' or '@rokicool/gsd-opencode')
+   * @returns {Promise<string[]>} Array of version strings sorted newest first, empty array on error
+   * @example
+   * const npm = new NpmRegistry();
+   * const versions = await npm.getAllVersions('gsd-opencode');
+   * console.log(versions); // ['1.9.2', '1.9.1', '1.9.0', ...]
+   */
+  async getAllVersions(packageName) {
+    if (!this._validatePackageName(packageName)) {
+      this.logger.error(`Invalid package name: ${packageName}`);
+      return [];
+    }
+
+    const escapedName = this._escapePackageName(packageName);
+
+    try {
+      const { stdout } = await execAsync(`npm view ${escapedName} versions --json`);
+      const versions = JSON.parse(stdout);
+
+      if (!Array.isArray(versions)) {
+        this.logger.error(`Unexpected response format for ${packageName}`);
+        return [];
+      }
+
+      // Sort versions newest first using compareVersions
+      return versions.sort((a, b) => -this.compareVersions(a, b));
+    } catch (error) {
+      this._handleError('getAllVersions', packageName, error);
+      return [];
+    }
+  }
+
+  /**
+   * Checks if a specific version of a package exists in npm registry.
+   *
+   * @param {string} packageName - The package name
+   * @param {string} version - The version to check (e.g., '1.9.2')
+   * @returns {Promise<boolean>} True if the version exists, false otherwise
+   * @example
+   * const npm = new NpmRegistry();
+   * const exists = await npm.versionExists('gsd-opencode', '1.9.2');
+   * console.log(exists); // true
+   */
+  async versionExists(packageName, version) {
+    if (!this._validatePackageName(packageName)) {
+      this.logger.error(`Invalid package name: ${packageName}`);
+      return false;
+    }
+
+    if (!version || typeof version !== 'string') {
+      this.logger.error(`Invalid version: ${version}`);
+      return false;
+    }
+
+    const escapedName = this._escapePackageName(packageName);
+    const escapedVersion = version.replace(/[^0-9.a-zA-Z-]/g, '');
+
+    try {
+      // Try to view the specific version - if it exists, npm returns the version
+      await execAsync(`npm view ${escapedName}@${escapedVersion} version`);
+      return true;
+    } catch (error) {
+      // Version doesn't exist or other error
+      return false;
+    }
+  }
+
+  /**
+   * Compares two semantic version strings.
+   *
+   * Supports standard semver (e.g., '1.9.2') and pre-release versions
+   * (e.g., '1.9.2-dev-8a05'). Pre-release versions are considered
+   * lower than their release counterparts.
+   *
+   * @param {string} v1 - First version string
+   * @param {string} v2 - Second version string
+   * @returns {number} -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+   * @example
+   * const npm = new NpmRegistry();
+   * npm.compareVersions('1.9.2', '1.9.1'); // 1
+   * npm.compareVersions('1.9.2-dev-8a05', '1.9.2'); // -1
+   * npm.compareVersions('1.9.2', '1.9.2'); // 0
+   */
+  compareVersions(v1, v2) {
+    if (!v1 || !v2) {
+      return 0;
+    }
+
+    // Parse version strings into components
+    const parseVersion = (v) => {
+      // Remove 'v' prefix if present
+      const clean = v.replace(/^v/, '');
+
+      // Split into main version and pre-release parts
+      const [main, prerelease] = clean.split('-');
+      const parts = main.split('.').map(Number);
+
+      return {
+        parts: parts.length >= 3 ? parts : [...parts, 0, 0, 0].slice(0, 3),
+        prerelease: prerelease || null,
+        hasPrerelease: !!prerelease
+      };
+    };
+
+    const v1Parsed = parseVersion(v1);
+    const v2Parsed = parseVersion(v2);
+
+    // Compare main version parts
+    for (let i = 0; i < 3; i++) {
+      const p1 = v1Parsed.parts[i] || 0;
+      const p2 = v2Parsed.parts[i] || 0;
+
+      if (p1 > p2) return 1;
+      if (p1 < p2) return -1;
+    }
+
+    // Main versions are equal, check pre-release status
+    // A version without pre-release is greater than one with pre-release
+    if (!v1Parsed.hasPrerelease && v2Parsed.hasPrerelease) return 1;
+    if (v1Parsed.hasPrerelease && !v2Parsed.hasPrerelease) return -1;
+
+    // Both have pre-release, compare lexicographically
+    if (v1Parsed.hasPrerelease && v2Parsed.hasPrerelease) {
+      if (v1Parsed.prerelease > v2Parsed.prerelease) return 1;
+      if (v1Parsed.prerelease < v2Parsed.prerelease) return -1;
+    }
+
+    return 0;
+  }
+
+  /**
+   * Handles errors from npm commands with appropriate logging.
+   *
+   * @param {string} operation - The operation that failed
+   * @param {string} packageName - The package being queried
+   * @param {Error} error - The error object
+   * @private
+   */
+  _handleError(operation, packageName, error) {
+    const errorMessage = error.message || '';
+
+    if (errorMessage.includes('E404') || errorMessage.includes('not found')) {
+      this.logger.error(`Package not found: ${packageName}`);
+    } else if (errorMessage.includes('ENOTFOUND') || errorMessage.includes('ECONNREFUSED')) {
+      this.logger.error(`Network error: Unable to reach npm registry`);
+    } else if (errorMessage.includes('npm ERR!') && errorMessage.includes('not in the npm registry')) {
+      this.logger.error(`Package not in npm registry: ${packageName}`);
+    } else {
+      this.logger.error(`Failed to ${operation} for ${packageName}: ${errorMessage}`);
+    }
+  }
+}
+
+/**
+ * Default export of NpmRegistry class.
+ * @type {typeof NpmRegistry}
+ */
+export default NpmRegistry;