gsd-opencode 1.9.2 → 1.10.1

package/get-shit-done/workflows/verify-work.md

@@ -46,7 +46,7 @@ Store resolved models for use in Task calls below.
 find .planning/phases -name "*-UAT.md" -type f 2>/dev/null | head -5
 ```
 
-**If active sessions exist AND no $ARGUMENTS provided:**
+**If active sessions exist AND no `$ARGUMENTS` provided:**
 
 read each file's frontmatter (status, phase) and Current Test section.
 
@@ -68,12 +68,12 @@ Wait for user response.
 - If user replies with number (1, 2) → Load that file, go to `resume_from_file`
 - If user replies with phase number → Treat as new session, go to `create_uat_file`
 
-**If active sessions exist AND $ARGUMENTS provided:**
+**If active sessions exist AND `$ARGUMENTS` provided:**
 
 Check if session exists for that phase. If yes, offer to resume or restart.
 If no, continue to `create_uat_file`.
 
-**If no active sessions AND no $ARGUMENTS:**
+**If no active sessions AND no `$ARGUMENTS`:**
 
 ```
 No active UAT sessions.
@@ -81,7 +81,7 @@ No active UAT sessions.
 Provide a phase number to start testing (e.g., /gsd-verify-work 4)
 ```
 
-**If no active sessions AND $ARGUMENTS provided:**
+**If no active sessions AND `$ARGUMENTS` provided:**
 
 Continue to `create_uat_file`.
 </step>
@@ -89,7 +89,7 @@ Continue to `create_uat_file`.
 <step name="find_summaries">
 **Find what to test:**
 
-Parse $ARGUMENTS as phase number (e.g., "4") or plan number (e.g., "04-02").
+Parse `$ARGUMENTS` as phase number (e.g., "4") or plan number (e.g., "04-02").
 
 ```bash
 # Find phase directory (match both zero-padded and unpadded)

package/lib/constants.js

@@ -0,0 +1,193 @@
+/**
+ * Shared constants for the GSD-OpenCode CLI.
+ * 
+ * This module centralizes all configuration values, file paths, and error codes
+ * used throughout the CLI to ensure consistency and maintainability.
+ * 
+ * All exports are immutable constants. Do not modify these values at runtime.
+ * 
+ * @module constants
+ */
+
+/**
+ * Default global configuration directory path.
+ * Resolved relative to user's home directory.
+ * @type {string}
+ * @example
+ * // On macOS/Linux: ~/.config/opencode
+ * // On Windows: ~\AppData\Roaming\opencode
+ */
+export const DEFAULT_CONFIG_DIR = '.config/opencode';
+
+/**
+ * Local configuration directory name.
+ * Created in the current working directory for project-specific configuration.
+ * @type {string}
+ * @example
+ * // Creates: ./.opencode/ in project root
+ */
+export const LOCAL_CONFIG_DIR = '.opencode';
+
+/**
+ * Name of the version tracking file.
+ * Used to store the installed version of GSD-OpenCode.
+ * Stored in get-shit-done/ directory since it's fully owned by gsd-opencode.
+ * @type {string}
+ */
+export const VERSION_FILE = 'get-shit-done/VERSION';
+
+/**
+ * Regex patterns for path replacement in markdown files.
+ * These patterns are used to update internal references during installation.
+ * @type {Object.<string, RegExp>}
+ */
+export const PATH_PATTERNS = {
+  /**
+   * Pattern to match @gsd-opencode/ references in markdown files.
+   * Used for replacing package references with actual paths.
+   */
+  gsdReference: /@gsd-opencode\//g
+};
+
+/**
+ * Source directories to copy during installation.
+ * These directories contain the core GSD-OpenCode assets.
+ * 
+ * All directories use the 'commands' (plural) structure consistently
+ * in both source and destination. The FileOperations service copies
+ * files directly from source to target without path transformation.
+ * 
+ * @type {string[]}
+ */
+export const DIRECTORIES_TO_COPY = ['agents', 'commands', 'get-shit-done'];
+
+/**
+ * Command directory mapping for source-to-destination path transformation.
+ * 
+ * Since the source package now uses 'commands/' (plural) and the destination
+ * also uses 'commands/' (plural), this mapping ensures consistency.
+ * This enables future transformations if needed.
+ * 
+ * @type {Object.<string, string>}
+ * @example
+ * // During install, files from sourceDir/commands/gsd/ are copied to targetDir/commands/gsd/
+ * const sourceDirName = COMMAND_DIR_MAPPING[destDirName]; // 'commands'
+ */
+export const COMMAND_DIR_MAPPING = {
+  'commands': 'commands'  // Both source and destination use 'commands/'
+};
+
+/**
+ * Name of the manifest file that tracks all installed files.
+ * Used for safe uninstallation with namespace protection.
+ * Stored in get-shit-done/ directory since it's fully owned by gsd-opencode.
+ * @type {string}
+ */
+export const MANIFEST_FILENAME = 'get-shit-done/INSTALLED_FILES.json';
+
+/**
+ * Directory name for uninstall backups.
+ * Created within the installation directory to store backups before removal.
+ * @type {string}
+ */
+export const UNINSTALL_BACKUP_DIR = '.backups';
+
+/**
+ * Legacy command directory name (singular).
+ * Used for detecting and migrating old installations.
+ * @type {string}
+ */
+export const OLD_COMMAND_DIR = 'command';
+
+/**
+ * New command directory name (plural).
+ * Used as the default for fresh installations.
+ * @type {string}
+ */
+export const NEW_COMMAND_DIR = 'commands';
+
+/**
+ * Structure type constants for directory structure detection.
+ * Used to identify which command directory structure is present.
+ * @type {Object.<string, string>}
+ */
+export const STRUCTURE_TYPES = {
+  /** Legacy structure: command/gsd/ (singular) */
+  OLD: 'old',
+  
+  /** New structure: commands/gsd/ (plural) */
+  NEW: 'new',
+  
+  /** Both structures exist (dual/migration state) */
+  DUAL: 'dual',
+  
+  /** Neither structure exists (fresh install) */
+  NONE: 'none'
+};
+
+/**
+ * Allowed namespace patterns for safe uninstallation.
+ * Files in these namespaces are safe to delete during uninstall.
+ * Files outside these namespaces are NEVER deleted, even if tracked.
+ *
+ * Patterns:
+ * - agents/gsd-* (gsd-opencode specific agents)
+ * - command/gsd/* (gsd-opencode specific commands - legacy)
+ * - commands/gsd/* (gsd-opencode specific commands - new)
+ * - skills/gsd-* (gsd-opencode specific skills)
+ * - get-shit-done/* (fully owned by gsd-opencode)
+ *
+ * @type {RegExp[]}
+ */
+export const ALLOWED_NAMESPACES = [
+  /^agents\/gsd-/,      // agents/gsd-* directories
+  /^command\/gsd\//,    // command/gsd/* files (legacy structure)
+  /^commands\/gsd\//,   // commands/gsd/* files (new structure)
+  /^skills\/gsd-/,      // skills/gsd-* directories
+  /^get-shit-done\//    // get-shit-done/ directory - fully owned
+];
+
+/**
+ * Exit codes for different failure modes.
+ * Follows Unix convention where 0 = success, non-zero = error.
+ * @type {Object.<string, number>}
+ */
+export const ERROR_CODES = {
+  /** Operation completed successfully. */
+  SUCCESS: 0,
+  
+  /** General error occurred (unspecified failure). */
+  GENERAL_ERROR: 1,
+  
+  /** Permission denied (insufficient file system permissions). */
+  PERMISSION_ERROR: 2,
+  
+  /** Path traversal detected (security violation). */
+  PATH_TRAVERSAL: 3,
+  
+  /** Process interrupted by user (SIGINT, Ctrl+C). */
+  INTERRUPTED: 130
+};
+
+/**
+ * Default export combining all constants.
+ * Useful for importing all constants at once.
+ * 
+ * @example
+ * import constants from './lib/constants.js';
+ * console.log(constants.DEFAULT_CONFIG_DIR);
+ */
+export default {
+  DEFAULT_CONFIG_DIR,
+  LOCAL_CONFIG_DIR,
+  VERSION_FILE,
+  PATH_PATTERNS,
+  DIRECTORIES_TO_COPY,
+  MANIFEST_FILENAME,
+  UNINSTALL_BACKUP_DIR,
+  OLD_COMMAND_DIR,
+  NEW_COMMAND_DIR,
+  STRUCTURE_TYPES,
+  ALLOWED_NAMESPACES,
+  ERROR_CODES
+};

package/package.json

@@ -1,14 +1,9 @@
 {
   "name": "gsd-opencode",
-  "version": "1.9.2",
-  "description": "A meta-prompting, context engineering and spec-driven development system for OpenCode by TÂCHES.",
-  "keywords": [
-    "opencode",
-    "ai",
-    "meta-prompting",
-    "context-engineering",
-    "spec-driven-development"
-  ],
+  "version": "1.10.1",
+  "description": "GSD-OpenCode distribution manager - install, verify, and maintain your GSD-OpenCode installation",
+  "type": "module",
+  "main": "bin/gsd.js",
   "homepage": "https://github.com/rokicool/gsd-opencode#readme",
   "bugs": {
     "url": "https://github.com/rokicool/gsd-opencode/issues"
@@ -17,23 +12,42 @@
     "type": "git",
     "url": "git+https://github.com/rokicool/gsd-opencode.git"
   },
-  "license": "MIT",
-  "author": "TÂCHES & rokicool",
-  "type": "commonjs",
-  "main": "index.js",
   "bin": {
-    "gsd-opencode": "bin/install.js"
+    "gsd-opencode": "bin/gsd.js",
+    "gsd-install": "bin/gsd-install.js"
   },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "opencode",
+    "ai",
+    "meta-prompting",
+    "context-engineering",
+    "spec-driven-development"
+  ],
+  "author": "TÂCHES & rokicool",
+  "license": "MIT",
   "files": [
     "agents",
     "bin",
-    "command",
-    "get-shit-done"
+    "commands",
+    "get-shit-done",
+    "src",
+    "lib"
   ],
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
   "engines": {
-    "node": ">=16.7.0"
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@iarna/toml": "^2.2.5",
+    "@inquirer/prompts": "^8.2.0",
+    "chalk": "^5.6.2",
+    "commander": "^12.1.0",
+    "ora": "^9.3.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.0"
   }
 }

package/src/commands/check.js

@@ -0,0 +1,329 @@
+/**
+ * Check command for GSD-OpenCode CLI.
+ *
+ * This module provides the check functionality to verify installation health,
+ * showing detailed pass/fail results for file existence, version matching,
+ * and file integrity checks.
+ *
+ * Implements requirements:
+ * - CLI-03: User can run gsd-opencode check to verify installation health
+ * - CHECK-01: Check verifies all required files exist
+ * - CHECK-02: Check verifies installed version matches expected version
+ * - CHECK-03: Check detects corrupted or modified files
+ * - CHECK-04: Check provides clear pass/fail output for each verification
+ * - CHECK-05: Check returns appropriate exit codes (0 for healthy, non-zero for issues)
+ * - ERROR-03: All commands support --verbose flag for detailed debugging output
+ * - ERROR-06: CLI shows consistent branding and formatted output using colors
+ *
+ * @module check
+ */
+
+import { ScopeManager } from '../services/scope-manager.js';
+import { HealthChecker } from '../services/health-checker.js';
+import { logger, setVerbose } from '../utils/logger.js';
+import { ERROR_CODES } from '../../lib/constants.js';
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+/**
+ * Gets the package version from package.json.
+ *
+ * @returns {Promise<string>} The package version
+ * @private
+ */
+async function getPackageVersion() {
+  try {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
+    const packageRoot = path.resolve(__dirname, '../..');
+    const packageJsonPath = path.join(packageRoot, 'package.json');
+
+    const content = await fs.readFile(packageJsonPath, 'utf-8');
+    const pkg = JSON.parse(content);
+    return pkg.version || '1.0.0';
+  } catch (error) {
+    logger.warning('Could not read package version, using 1.0.0');
+    return '1.0.0';
+  }
+}
+
+/**
+ * Displays health check results with pass/fail indicators.
+ *
+ * @param {Object} results - Health check results from HealthChecker
+ * @param {string} scopeLabel - Label for this scope
+ * @private
+ */
+function displayCheckResults(results, scopeLabel) {
+  logger.heading(`${scopeLabel} Installation Health`);
+  logger.dim('================================');
+
+  if (!results) {
+    logger.info('Not installed');
+    logger.dim('');
+    return;
+  }
+
+  const { categories } = results;
+
+  // Files check section
+  logger.dim('');
+  logger.info('Required Files');
+  if (categories.files && categories.files.checks) {
+    for (const check of categories.files.checks) {
+      const status = check.passed ? 'OK' : (check.error || 'Missing');
+      if (check.passed) {
+        logger.success(`${check.name}: ${status}`);
+      } else {
+        logger.error(`${check.name}: ${status}`);
+      }
+    }
+  }
+
+  // Version check section
+  if (categories.version) {
+    logger.dim('');
+    logger.info('Version Verification');
+    const versionCheck = categories.version.checks[0];
+    if (versionCheck.passed) {
+      logger.success(`Version: ${versionCheck.installed} - OK`);
+    } else {
+      const errorMsg = versionCheck.error
+        ? `Version check failed - ${versionCheck.error}`
+        : `Version mismatch (installed: ${versionCheck.installed || 'none'}, expected: ${versionCheck.expected})`;
+      logger.error(errorMsg);
+    }
+  }
+
+  // Integrity check section
+  logger.dim('');
+  logger.info('File Integrity');
+  if (categories.integrity && categories.integrity.checks) {
+    for (const check of categories.integrity.checks) {
+      const relativePath = check.relative || path.basename(check.file);
+      const message = check.passed
+        ? `${relativePath} - OK`
+        : `${relativePath} - ${check.error || 'Corrupted or missing'}`;
+
+      if (check.passed) {
+        logger.success(message);
+      } else {
+        logger.error(message);
+      }
+    }
+  }
+
+  // Structure check section (NEW)
+  if (categories.structure) {
+    logger.dim('');
+    logger.info('Directory Structure');
+    const structure = categories.structure;
+    const statusText = structure.label;
+
+    if (structure.type === 'dual') {
+      logger.error(`${statusText} - Action required`);
+      logger.dim('  Both old (command/gsd/) and new (commands/gsd/) structures detected.');
+      logger.dim('  This can happen if an update was interrupted.');
+      logger.dim("  Run 'gsd-opencode update' to complete migration");
+    } else if (structure.needsMigration) {
+      logger.warning(`${statusText} - Migration recommended`);
+      logger.dim("  Run 'gsd-opencode update' to migrate to new structure");
+    } else if (structure.type === 'new') {
+      logger.success(`${statusText} - OK`);
+    } else if (structure.type === 'none') {
+      logger.info(`${statusText}`);
+    } else {
+      logger.info(statusText);
+    }
+  }
+
+  // Overall status
+  logger.dim('');
+  if (results.passed) {
+    logger.success('All checks passed - Installation is healthy');
+  } else {
+    logger.error('Some checks failed - Issues detected');
+  }
+  logger.dim('');
+}
+
+/**
+ * Checks health for a single scope.
+ *
+ * @param {string} scope - 'global' or 'local'
+ * @param {Object} options - Options
+ * @param {boolean} options.verbose - Enable verbose output
+ * @returns {Promise<Object>} Health check results
+ * @private
+ */
+async function checkScope(scope, options = {}) {
+  const scopeManager = new ScopeManager({ scope });
+  const scopeLabel = scope.charAt(0).toUpperCase() + scope.slice(1);
+
+  logger.debug(`Checking ${scope} installation...`);
+
+  const isInstalled = await scopeManager.isInstalled();
+  if (!isInstalled) {
+    logger.debug(`No ${scope} installation found`);
+    return {
+      installed: false,
+      scope,
+      scopeLabel,
+      results: null,
+      passed: false
+    };
+  }
+
+  logger.debug(`${scope} installation detected, running health checks...`);
+
+  const healthChecker = new HealthChecker(scopeManager);
+  const expectedVersion = await getPackageVersion();
+
+  try {
+    const results = await healthChecker.checkAll({
+      expectedVersion,
+      verbose: options.verbose
+    });
+
+    return {
+      installed: true,
+      scope,
+      scopeLabel,
+      results,
+      passed: results.passed
+    };
+  } catch (error) {
+    logger.debug(`Error during health check: ${error.message}`);
+    return {
+      installed: true,
+      scope,
+      scopeLabel,
+      results: null,
+      passed: false,
+      error: error.message
+    };
+  }
+}
+
+/**
+ * Handles errors with helpful messages.
+ *
+ * @param {Error} error - The error to handle
+ * @param {boolean} verbose - Whether verbose mode is enabled
+ * @returns {number} Exit code for the error
+ * @private
+ */
+function handleError(error, verbose) {
+  if (verbose) {
+    logger.debug(`Error details: ${error.stack || error.message}`);
+    logger.debug(`Error code: ${error.code}`);
+  }
+
+  if (error.code === 'EACCES') {
+    logger.error('Permission denied: Cannot access installation directory');
+    logger.dim('');
+    logger.dim('Suggestion: Check directory permissions or run with appropriate privileges.');
+    return ERROR_CODES.PERMISSION_ERROR;
+  }
+
+  logger.error(`Failed to check installation health: ${error.message}`);
+
+  if (!verbose) {
+    logger.dim('');
+    logger.dim('Suggestion: Run with --verbose for detailed error information');
+  }
+
+  return ERROR_CODES.GENERAL_ERROR;
+}
+
+/**
+ * Main check command function.
+ *
+ * @param {Object} options - Command options
+ * @param {boolean} [options.global] - Check global installation only
+ * @param {boolean} [options.local] - Check local installation only
+ * @param {boolean} [options.verbose] - Enable verbose output
+ * @returns {Promise<number>} Exit code
+ */
+export async function checkCommand(options = {}) {
+  const verbose = options.verbose || false;
+  setVerbose(verbose);
+
+  logger.debug('Starting check command');
+  logger.debug(`Options: global=${options.global}, local=${options.local}, verbose=${verbose}`);
+
+  try {
+    logger.heading('GSD-OpenCode Installation Health');
+    logger.dim('================================');
+
+    const scopesToCheck = [];
+    if (options.global) {
+      scopesToCheck.push('global');
+    } else if (options.local) {
+      scopesToCheck.push('local');
+    } else {
+      scopesToCheck.push('global', 'local');
+    }
+
+    let anyInstalled = false;
+    let allPassed = true;
+
+    for (const scope of scopesToCheck) {
+      try {
+        const result = await checkScope(scope, options);
+
+        if (result.installed) {
+          anyInstalled = true;
+          if (!result.passed) {
+            allPassed = false;
+          }
+        }
+
+        if (scopesToCheck.length > 1) {
+          logger.dim('');
+        }
+
+        displayCheckResults(result.results, result.scopeLabel);
+
+        if (verbose && result.error) {
+          logger.debug(`Error checking ${scope}: ${result.error}`);
+        }
+      } catch (error) {
+        logger.error(`Failed to check ${scope} installation: ${error.message}`);
+        allPassed = false;
+
+        if (verbose) {
+          logger.debug(error.stack);
+        }
+      }
+    }
+
+    if (!anyInstalled) {
+      logger.dim('');
+      logger.dim('Not installed anywhere');
+      logger.dim('');
+      logger.info("Run 'gsd-opencode install' to install");
+      logger.dim('');
+      return ERROR_CODES.SUCCESS;
+    }
+
+    const exitCode = allPassed ? ERROR_CODES.SUCCESS : ERROR_CODES.GENERAL_ERROR;
+
+    if (verbose) {
+      logger.debug(`Check complete. Exit code: ${exitCode}`);
+    }
+
+    return exitCode;
+
+  } catch (error) {
+    if (error.name === 'AbortPromptError' || error.message?.includes('cancel')) {
+      logger.info('Command cancelled by user');
+      return ERROR_CODES.INTERRUPTED;
+    }
+
+    return handleError(error, verbose);
+  }
+}
+
+export default checkCommand;