gsd-opencode 1.9.2 → 1.10.1

package/agents/gsd-debugger.md

@@ -836,17 +836,17 @@ The file IS the debugging brain.
 ls .planning/debug/*.md 2>/dev/null | grep -v resolved
 ```
 
-**If active sessions exist AND no $ARGUMENTS:**
+**If active sessions exist AND no `$ARGUMENTS`:**
 - Display sessions with status, hypothesis, next action
 - Wait for user to select (number) or describe new issue (text)
 
-**If active sessions exist AND $ARGUMENTS:**
+**If active sessions exist AND `$ARGUMENTS`:**
 - Start new session (continue to create_debug_file)
 
-**If no active sessions AND no $ARGUMENTS:**
+**If no active sessions AND no `$ARGUMENTS`:**
 - Prompt: "No active sessions. Describe the issue to start."
 
-**If no active sessions AND $ARGUMENTS:**
+**If no active sessions AND `$ARGUMENTS`:**
 - Continue to create_debug_file
 </step>
 
@@ -857,7 +857,7 @@ ls .planning/debug/*.md 2>/dev/null | grep -v resolved
 2. `mkdir -p .planning/debug`
 3. Create file with initial state:
    - status: gathering
-   - trigger: verbatim $ARGUMENTS
+   - trigger: verbatim `$ARGUMENTS`
    - Current Focus: next_action = "gather symptoms"
    - Symptoms: empty
 4. Proceed to symptom_gathering

package/bin/gsd-install.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+/**
+ * Legacy compatibility shim for GSD-OpenCode CLI.
+ *
+ * This module maintains backward compatibility with the original CLI invocation
+ * patterns. It transforms legacy-style arguments to the new subcommand format
+ * and delegates to the main CLI entry point (gsd.js).
+ *
+ * Legacy patterns supported:
+ * - gsd-opencode --global       -> gsd-opencode install --global
+ * - gsd-opencode --local        -> gsd-opencode install --local
+ * - gsd-opencode -c /custom/path -> gsd-opencode install --config-dir /custom/path
+ * - gsd-opencode (no args)      -> gsd-opencode install (interactive)
+ *
+ * This shim allows existing users and scripts to continue working without
+ * modification while the new subcommand interface is the preferred approach.
+ *
+ * @module gsd-install
+ * @deprecated Use 'gsd-opencode install' directly instead
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+
+/**
+ * Checks if arguments should trigger legacy transformation.
+ *
+ * Legacy patterns are:
+ * - Any flag starting with --global, -g, --local, -l, --config-dir, -c
+ * - No arguments at all (defaults to install)
+ *
+ * @param {string[]} args - Process arguments
+ * @returns {boolean} True if legacy pattern detected
+ * @private
+ */
+function isLegacyPattern(args) {
+  const userArgs = args.slice(2);
+
+  // If no args, treat as legacy (will route to install)
+  if (userArgs.length === 0) {
+    return true;
+  }
+
+  // Check for legacy flags
+  const legacyFlags = ['--global', '-g', '--local', '-l', '--config-dir', '-c'];
+  return userArgs.some(arg =>
+    legacyFlags.some(flag => arg === flag || arg.startsWith(`${flag}=`))
+  );
+}
+
+/**
+ * Transform legacy arguments to new subcommand format.
+ *
+ * Adds 'install' as the first argument after the script path.
+ *
+ * @param {string[]} args - Process arguments
+ * @returns {string[]} Transformed arguments
+ * @private
+ */
+function transformArgs(args) {
+  const userArgs = args.slice(2);
+
+  // If already has 'install', don't transform
+  if (userArgs[0] === 'install') {
+    return args;
+  }
+
+  // Transform: [flags...] -> ['install', flags...]
+  return [...args.slice(0, 2), 'install', ...userArgs];
+}
+
+/**
+ * Main shim function.
+ *
+ * Detects legacy patterns, transforms arguments if needed,
+ * and requires the main CLI entry point.
+ *
+ * @returns {void}
+ * @private
+ */
+function main() {
+  const args = process.argv;
+
+  if (isLegacyPattern(args)) {
+    // Transform legacy args to new format
+    process.argv = transformArgs(args);
+
+    // In verbose mode, log the transformation
+    if (args.includes('--verbose') || args.includes('-v')) {
+      const __filename = fileURLToPath(import.meta.url);
+      console.error(`[legacy-shim] Transforming to: ${process.argv.slice(2).join(' ')}`);
+    }
+  }
+
+  // Delegate to main CLI
+  // Use dynamic import to handle ESM properly
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = path.dirname(__filename);
+
+  import(path.join(__dirname, 'gsd.js'));
+}
+
+// Execute shim
+main();

package/bin/gsd.js

@@ -0,0 +1,352 @@
+#!/usr/bin/env node
+
+/**
+ * Main CLI entry point for GSD-OpenCode package manager.
+ *
+ * This is the primary executable that routes commands to their respective
+ * handlers using Commander.js. Supports both new subcommand-based interface
+ * and legacy argument patterns for backward compatibility.
+ *
+ * Commands:
+ * - install: Install GSD-OpenCode distribution
+ * - list: Show installation status
+ *
+ * Legacy compatibility:
+ * - Direct flags like --global, --local are routed to install command
+ * - No arguments defaults to interactive install
+ *
+ * @module gsd
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { installCommand } from '../src/commands/install.js';
+import { listCommand } from '../src/commands/list.js';
+import { uninstallCommand } from '../src/commands/uninstall.js';
+import { configGetCommand, configSetCommand, configResetCommand, configListCommand } from '../src/commands/config.js';
+import { checkCommand } from '../src/commands/check.js';
+import { repairCommand } from '../src/commands/repair.js';
+import { updateCommand } from '../src/commands/update.js';
+import { logger, setVerbose } from '../src/utils/logger.js';
+import { ERROR_CODES } from '../lib/constants.js';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import path from 'path';
+
+/**
+ * Gets the package version from package.json.
+ *
+ * @returns {string} The package version
+ * @private
+ */
+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 = readFileSync(packageJsonPath, 'utf-8');
+    const pkg = JSON.parse(content);
+    return pkg.version || '1.0.0';
+  } catch (error) {
+    return '1.0.0';
+  }
+}
+
+/**
+ * Checks if arguments are legacy-style (direct flags without subcommand).
+ *
+ * Legacy patterns:
+ * - --global, -g
+ * - --local, -l
+ * - --config-dir, -c
+ * - (no args)
+ *
+ * @param {string[]} args - Process arguments
+ * @returns {boolean} True if legacy pattern detected
+ * @private
+ */
+function isLegacyArgs(args) {
+  // If no args beyond node and script, it's legacy (default to install)
+  if (args.length <= 2) {
+    return true;
+  }
+
+  const userArgs = args.slice(2);
+
+  // Check for any known command
+  const knownCommands = ['install', 'list', 'uninstall', 'config', 'check', 'repair', 'update', '--help', '-h', '--version', '-V'];
+  const hasKnownCommand = knownCommands.some(cmd => userArgs.includes(cmd));
+
+  if (hasKnownCommand) {
+    return false;
+  }
+
+  // Check for legacy flags
+  const legacyFlags = ['--global', '-g', '--local', '-l', '--config-dir', '-c'];
+  const hasLegacyFlags = legacyFlags.some(flag =>
+    userArgs.some(arg => arg.startsWith(flag))
+  );
+
+  return hasLegacyFlags || userArgs.length === 0;
+}
+
+/**
+ * Transform legacy arguments to new subcommand format.
+ *
+ * @param {string[]} args - Process arguments
+ * @returns {string[]} Transformed arguments
+ * @private
+ */
+function transformLegacyArgs(args) {
+  const userArgs = args.slice(2);
+
+  // If no args, transform to 'install'
+  if (userArgs.length === 0) {
+    return [...args.slice(0, 2), 'install'];
+  }
+
+  // Check if already has 'install' subcommand
+  if (userArgs[0] === 'install') {
+    return args;
+  }
+
+  // Transform: [flags...] -> ['install', flags...]
+  // But don't add 'install' if the first arg starts with a flag
+  const firstArg = userArgs[0];
+  if (firstArg.startsWith('-')) {
+    return [...args.slice(0, 2), 'install', ...userArgs];
+  }
+
+  return args;
+}
+
+/**
+ * Main CLI function.
+ *
+ * Sets up Commander program, registers commands, handles legacy
+ * compatibility, and executes the appropriate command.
+ *
+ * @returns {Promise<void>}
+ * @private
+ */
+async function main() {
+  const program = new Command();
+
+  // Basic program setup
+  program
+    .name('gsd-opencode')
+    .description('GSD-OpenCode distribution manager')
+    .version(getPackageVersion(), '-v, --version', 'Display version number')
+    .helpOption('-h, --help', 'Display help for command')
+    .configureOutput({
+      writeErr: (str) => logger.error(str.trim()),
+      outputError: (str, write) => write(chalk.red(str))
+    });
+
+  // Global options (available to all subcommands)
+  program.option('--verbose', 'Enable verbose output for debugging', false);
+
+  // Install command
+  program
+    .command('install')
+    .description('Install GSD-OpenCode distribution to your system')
+    .option('-g, --global', 'Install globally to ~/.config/opencode/')
+    .option('-l, --local', 'Install locally to ./.opencode/')
+    .option('-c, --config-dir <path>', 'Specify custom configuration directory')
+    .action(async (options, command) => {
+      // Get global verbose option from parent
+      const globalOptions = command.parent.opts();
+      const fullOptions = {
+        ...options,
+        verbose: globalOptions.verbose || options.verbose
+      };
+
+      const exitCode = await installCommand(fullOptions);
+      process.exit(exitCode);
+    });
+
+  // List command
+  program
+    .command('list')
+    .alias('ls')
+    .description('Show GSD-OpenCode installation status and version')
+    .option('-g, --global', 'Show global installation only')
+    .option('-l, --local', 'Show local installation only')
+    .action(async (options, command) => {
+      // Get global verbose option from parent
+      const globalOptions = command.parent.opts();
+      const fullOptions = {
+        ...options,
+        verbose: globalOptions.verbose || options.verbose
+      };
+
+      const exitCode = await listCommand(fullOptions);
+      process.exit(exitCode);
+    });
+
+  // Check command
+  program
+    .command('check')
+    .alias('verify')
+    .description('Verify GSD-OpenCode installation health')
+    .option('-g, --global', 'Check global installation only')
+    .option('-l, --local', 'Check local installation only')
+    .action(async (options, command) => {
+      const globalOptions = command.parent.opts();
+      const fullOptions = {
+        ...options,
+        verbose: globalOptions.verbose || options.verbose
+      };
+
+      const exitCode = await checkCommand(fullOptions);
+      process.exit(exitCode);
+    });
+
+  // Repair command
+  program
+    .command('repair')
+    .description('Repair broken GSD-OpenCode installation')
+    .option('-g, --global', 'Repair global installation only')
+    .option('-l, --local', 'Repair local installation only')
+    .action(async (options, command) => {
+      const globalOptions = command.parent.opts();
+      const fullOptions = {
+        ...options,
+        verbose: globalOptions.verbose || options.verbose
+      };
+
+      const exitCode = await repairCommand(fullOptions);
+      process.exit(exitCode);
+    });
+
+  // Update command
+  program
+    .command('update [version]')
+    .description('Update GSD-OpenCode to latest or specified version')
+    .option('-g, --global', 'Update global installation only')
+    .option('-l, --local', 'Update local installation only')
+    .option('--beta', 'Update to beta version from @rokicool/gsd-opencode')
+    .option('-f, --force', 'Skip confirmation prompt')
+    .option('--dry-run', 'Show what would be updated without making changes')
+    .option('--skip-migration', 'Skip automatic structure migration (not recommended)')
+    .action(async (version, options, command) => {
+      const globalOptions = command.parent.opts();
+      const fullOptions = {
+        ...options,
+        version,
+        verbose: globalOptions.verbose || options.verbose
+      };
+
+      const exitCode = await updateCommand(fullOptions);
+      process.exit(exitCode);
+    });
+
+  // Uninstall command
+  program
+    .command('uninstall')
+    .alias('rm')
+    .description('Remove GSD-OpenCode installation')
+    .option('-g, --global', 'Remove global installation')
+    .option('-l, --local', 'Remove local installation')
+    .option('-f, --force', 'Skip confirmation prompt')
+    .option('--dry-run', 'Show what would be removed without removing')
+    .option('--no-backup', 'Skip backup creation before removal')
+    .action(async (options, command) => {
+      const globalOptions = command.parent.opts();
+      const fullOptions = {
+        ...options,
+        verbose: globalOptions.verbose || options.verbose
+      };
+
+      const exitCode = await uninstallCommand(fullOptions);
+      process.exit(exitCode);
+    });
+
+  // Config command with subcommands
+  const configCmd = program
+    .command('config')
+    .description('Manage GSD-OpenCode configuration');
+
+  configCmd
+    .command('get <key>')
+    .description('Get a configuration value')
+    .action(async (key, options, command) => {
+      const globalOptions = command.parent.parent.opts();
+      const fullOptions = {
+        verbose: globalOptions.verbose || options.verbose
+      };
+
+      const exitCode = await configGetCommand(key, fullOptions);
+      process.exit(exitCode);
+    });
+
+  configCmd
+    .command('set <key> <value>')
+    .description('Set a configuration value')
+    .action(async (key, value, options, command) => {
+      const globalOptions = command.parent.parent.opts();
+      const fullOptions = {
+        verbose: globalOptions.verbose || options.verbose
+      };
+
+      const exitCode = await configSetCommand(key, value, fullOptions);
+      process.exit(exitCode);
+    });
+
+  configCmd
+    .command('reset [key]')
+    .description('Reset configuration to defaults')
+    .option('--all', 'Reset all settings')
+    .action(async (key, options, command) => {
+      const globalOptions = command.parent.parent.opts();
+      const fullOptions = {
+        ...options,
+        verbose: globalOptions.verbose || options.verbose
+      };
+
+      const exitCode = await configResetCommand(key, fullOptions);
+      process.exit(exitCode);
+    });
+
+  configCmd
+    .command('list')
+    .alias('ls')
+    .description('List all configuration settings')
+    .option('--json', 'Output as JSON')
+    .action(async (options, command) => {
+      const globalOptions = command.parent.parent.opts();
+      const fullOptions = {
+        ...options,
+        verbose: globalOptions.verbose || options.verbose
+      };
+
+      const exitCode = await configListCommand(fullOptions);
+      process.exit(exitCode);
+    });
+
+  // Handle legacy argument patterns
+  const args = process.argv;
+
+  if (isLegacyArgs(args)) {
+    // Transform legacy args to new format
+    process.argv = transformLegacyArgs(args);
+
+    // Show deprecation notice in verbose mode
+    const userArgs = args.slice(2);
+    if (userArgs.some(arg => arg === '--verbose' || arg === '-v')) {
+      setVerbose(true);
+      logger.debug('Legacy argument pattern detected, routing to install command');
+    }
+  }
+
+  // Parse and execute
+  await program.parseAsync(process.argv);
+}
+
+// Run CLI
+main().catch((error) => {
+  logger.error('Unexpected error:', error);
+  process.exit(ERROR_CODES.GENERAL_ERROR);
+});

package/{command → commands}/gsd/add-phase.md

@@ -25,7 +25,7 @@ Purpose: Add planned work discovered during execution that belongs at the end of
 
 <step name="parse_arguments">
 Parse the command arguments:
-- $ARGUMENTS the phase description
+- `$ARGUMENTS` the phase description
 - Example: `/gsd-add-phase Add authentication` → description = "Add authentication"
 - Example: `/gsd-add-phase Fix critical performance issues` → description = "Fix critical performance issues"
 

package/{command → commands}/gsd/audit-milestone.md

@@ -22,7 +22,7 @@ Verify milestone achieved its definition of done. Check requirements coverage, c
 </execution_context>
 
 <context>
-Version: $ARGUMENTS (optional — defaults to current milestone)
+Version: `$ARGUMENTS` (optional — defaults to current milestone)
 
 **Original Intent:**
 @.planning/PROJECT.md

package/{command → commands}/gsd/debug.md

@@ -18,7 +18,7 @@ Debug issues using scientific method with subagent isolation.
 </objective>
 
 <context>
-User's issue: $ARGUMENTS
+User's issue: `$ARGUMENTS`
 
 Check for active sessions:
 ```bash
@@ -48,11 +48,11 @@ Store resolved model for use in Task calls below.
 
 ## 1. Check Active Sessions
 
-If active sessions exist AND no $ARGUMENTS:
+If active sessions exist AND no `$ARGUMENTS`:
 - List sessions with status, hypothesis, next action
 - User picks number to resume OR describes new issue
 
-If $ARGUMENTS provided OR user describes new issue:
+If `$ARGUMENTS` provided OR user describes new issue:
 - Continue to symptom gathering
 
 ## 2. Gather Symptoms (if new issue)

package/{command → commands}/gsd/discuss-phase.md

@@ -29,7 +29,7 @@ Extract implementation decisions that downstream agents need — researcher and
 </execution_context>
 
 <context>
-Phase number: $ARGUMENTS (required)
+Phase number: `$ARGUMENTS` (required)
 
 **Load project state:**
 @.planning/STATE.md

package/{command → commands}/gsd/execute-phase.md

@@ -28,7 +28,7 @@ Context budget: ~15% orchestrator, 100% fresh per subagent.
 </execution_context>
 
 <context>
-Phase: $ARGUMENTS
+Phase: `$ARGUMENTS`
 
 **Flags:**
 - `--gaps-only` — Execute only gap closure plans (plans with `gap_closure: true` in frontmatter). Use after verify-work creates fix plans.

package/{command → commands}/gsd/list-phase-assumptions.md

@@ -21,7 +21,7 @@ Output: Conversational output only (no file creation) - ends with "What do you t
 </execution_context>
 
 <context>
-Phase number: $ARGUMENTS (required)
+Phase number: `$ARGUMENTS` (required)
 
 **Load project state first:**
 @.planning/STATE.md

package/{command → commands}/gsd/map-codebase.md

@@ -24,7 +24,7 @@ Output: .planning/codebase/ folder with 7 structured documents about the codebas
 </execution_context>
 
 <context>
-Focus area: $ARGUMENTS (optional - if provided, tells agents to focus on specific subsystem)
+Focus area: `$ARGUMENTS` (optional - if provided, tells agents to focus on specific subsystem)
 
 **Load project state if exists:**
 Check for .planning/STATE.md - loads context if project already initialized

package/{command → commands}/gsd/new-milestone.md

@@ -33,7 +33,7 @@ This is the brownfield equivalent of new-project. The project exists, PROJECT.md
 </execution_context>
 
 <context>
-Milestone name: $ARGUMENTS (optional - will prompt if not provided)
+Milestone name: `$ARGUMENTS` (optional - will prompt if not provided)
 
 **Load project context:**
 @.planning/PROJECT.md

package/{command → commands}/gsd/new-project.md

@@ -1014,14 +1014,14 @@ Present completion with next steps:
 
 **Phase 1: [Phase Name]** — [Goal from ROADMAP.md]
 
-`/gsd-discuss-phase 1` — gather context and clarify approach
+/gsd-discuss-phase 1 — gather context and clarify approach
 
-*`/new` first → fresh context window*
+*/new first → fresh context window*
 
 ---
 
 **Also available:**
-- `/gsd-plan-phase 1` — skip discussion, plan directly
+- /gsd-plan-phase 1 — skip discussion, plan directly
 
 ───────────────────────────────────────────────────────────────
 ```

package/{command → commands}/gsd/plan-phase.md

@@ -29,7 +29,7 @@ Create executable phase prompts (PLAN.md files) for a roadmap phase with integra
 </objective>
 
 <context>
-Phase number: $ARGUMENTS (optional - auto-detects next unplanned phase if not provided)
+Phase number: `$ARGUMENTS` (optional - auto-detects next unplanned phase if not provided)
 
 **Flags:**
 - `--research` — Force re-research even if RESEARCH.md exists
@@ -70,7 +70,7 @@ Store resolved models for use in Task calls below.
 
 ## 2. Parse and Normalize Arguments
 
-Extract from $ARGUMENTS:
+Extract from `$ARGUMENTS`:
 
 - Phase number (integer or decimal like `2.1`)
 - `--research` flag to force re-research

package/{command → commands}/gsd/research-phase.md

@@ -24,7 +24,7 @@ Research how to implement a phase. Spawns gsd-phase-researcher agent with phase
 </objective>
 
 <context>
-Phase number: $ARGUMENTS (required)
+Phase number: `$ARGUMENTS` (required)
 
 Normalize phase input in step 1 before any directory lookups.
 </context>

package/{command → commands}/gsd/verify-work.md

@@ -26,7 +26,7 @@ Output: {phase}-UAT.md tracking all test results. If issues found: diagnosed gap
 </execution_context>
 
 <context>
-Phase: $ARGUMENTS (optional)
+Phase: `$ARGUMENTS` (optional)
 - If provided: Test specific phase (e.g., "4")
 - If not provided: Check for active sessions or prompt for phase
 

package/get-shit-done/workflows/list-phase-assumptions.md

@@ -7,7 +7,7 @@ Key difference from discuss-phase: This is ANALYSIS of what OpenCode thinks, not
 <process>
 
 <step name="validate_phase" priority="first">
-Phase number: $ARGUMENTS (required)
+Phase number: `$ARGUMENTS` (required)
 
 **If argument missing:**