VSCode is installed but 'code' is not available in the PATH - should be detected by init/config

[rexsilex]

Diagnostic Information

Property	Value
CLI Version	0.4.1
Node.js Version	v24.9.0
OS	darwin
OS Version	24.5.0
Architecture	arm64
Capabilities	web
Claude CLI Version	2.0.73 (Claude Code)

VSCode is installed but 'code' is not available in the PATH - should be detected by init/config

---

Enhancement Request Analysis

Questions for Reporter

Question	Answer
Is VSCode installed via the standard installer, from homebrew, or another method?	@rexsilex, to reply, please edit this issue to answer these questions.
When you run which code in terminal, what output do you get?
Does VSCode's "Shell Command: Install 'code' command in PATH" option work when run from inside VSCode?
Are you able to manually add the code command to PATH, and if so, what path works?

Problem Summary
VSCode is installed and functional on the system but the code command is not available in the terminal PATH, preventing iloom from launching the IDE when starting a loom workspace. The il init command should detect this situation and provide guidance to resolve it.

User Impact
Users with VSCode installed cannot take advantage of the automatic IDE launch feature during il start, reducing the seamless workflow experience that iloom provides. They must manually open their loom workspace in VSCode after creation.

Enhancement Goal
The il init configuration wizard should detect when VSCode is installed but the code command is missing from PATH, then provide platform-specific instructions or automated fixes to resolve the PATH issue.

Next Steps

• Reporter to answer questions above for full context
• Investigate VSCode installation detection methods beyond PATH checking
• Consider adding automatic PATH configuration or clear user guidance in init wizard

---

📋 Complete Context & Details (click to expand)

Current Behavior
According to the TECHNICAL_ARCHITECTURE.md, iloom detects VS Code using which code (line 598). If the command is not in PATH, iloom silently skips IDE launch. The il init command configures IDE preferences but doesn't validate that the chosen IDE is actually accessible.

Proposed Solution

1. Enhanced detection in il init:

   • Check for VS Code installation in common locations:
     • macOS: /Applications/Visual Studio Code.app/Contents/Resources/app/bin/code
     • Windows: %LOCALAPPDATA%\\Programs\\Microsoft VS Code\\bin\\code.cmd
     • Linux: /usr/bin/code or /usr/local/bin/code

2. When VS Code is found but code command is missing:

   • Display clear instructions for adding to PATH
   • Offer to create symlink/alias automatically (with user permission)
   • Provide VS Code's built-in PATH installation command instructions

3. Update SettingsManager to validate IDE accessibility during configuration

4. Consider adding a diagnostic command like il doctor to check all dependencies

Benefits

• Smoother onboarding experience for new users
• Reduced friction when VS Code is installed but not properly configured
• Better error messages when IDE launch fails
• Proactive problem detection during initial setup

[acreeger]

Complexity Assessment

Classification: SIMPLE

Metrics:

• Estimated files affected: 3
• Estimated lines of code: 120
• Breaking changes: No
• Database migrations: No
• Cross-cutting changes: No
• File architecture quality: Good - Well-structured utility functions with clean separation of concerns
• Overall risk level: Low

Reasoning: The fix requires enhancing IDE detection logic (isIdeAvailable function in ide.ts) to check common installation paths before falling back to PATH check, and adding validation in init command (~50 LOC new code). Error messages with fix instructions already exist. Changes are localized to ide.ts and init.ts with no cross-layer impact.

[acreeger]

Combined Analysis & Plan - Issue #372

Executive Summary

VSCode may be installed but code command not in PATH. Current implementation only validates at launch time (after workspace creation), causing poor UX. The fix adds early validation in il start to fail fast when IDE is configured but not accessible.

Implementation Overview

High-Level Execution Phases

1. Export isIdeAvailable: Make existing function accessible from ide.ts
2. Add validateIdeAvailability: Create helper in cli.ts for pre-command validation
3. Integrate validation: Call validation in preAction hook for start command
4. Add tests: Test the new validation logic

Quick Stats

• 2 files to modify (src/utils/ide.ts, src/cli.ts)
• 0 new files to create
• 0 files to delete
• Dependencies: None

---

Complete Analysis & Implementation Details (click to expand)

Research Findings

Problem Space

• Problem: IDE validation happens at launch time after workspace creation, causing frustration when VSCode is installed but code not in PATH
• Architectural context: CLI has preAction hook pattern for pre-command validation (see validateSettingsForCommand and validateGhCliForCommand in cli.ts:90-139)
• Edge cases: User might have --no-code flag set, in which case validation should be skipped

Codebase Research

• Entry point: src/utils/ide.ts:36-43 - isIdeAvailable() already exists and works correctly using command -v
• Dependencies: Used by openIdeWindow() at runtime; needs to be used earlier in CLI validation
• Similar patterns: validateGhCliForCommand() in src/cli.ts:135-167 validates gh CLI availability before commands
• Install hint exists: src/utils/ide.ts:47-49 already has the exact message user requested

Affected Files

• /src/utils/ide.ts:36-43 - Need to export isIdeAvailable (already exported) and getIdeConfig (already exported)
• /src/cli.ts:83-131 - Add IDE validation in preAction hook, similar to gh CLI validation pattern

Integration Points

• validateSettingsForCommand() loads settings which includes ide.type configuration
• getIdeConfig() returns command name for any configured IDE type
• isIdeAvailable() checks if command exists in PATH

Implementation Plan

Automated Test Cases to Create

Test File: src/cli.test.ts (MODIFY - add IDE validation tests)

describe('validateIdeForStartCommand', () => {
  it('should not validate IDE when --no-code flag is used')
  it('should not validate IDE when startIde is false in settings')
  it('should throw error when configured IDE command not found')
  it('should pass when configured IDE is available')
  it('should skip validation for non-start commands')
})

Files to Modify

1. /src/cli.ts:83-131

Change: Add IDE validation for start command in preAction hook

The validation should:

1. Only run for start command
2. Check if user wants to start IDE (either via CLI flag or settings)
3. Get configured IDE type from settings
4. Call isIdeAvailable() with the IDE command
5. If unavailable, throw error with install hint

Insert after line 86 (after validateGhCliForCommand):

// Validate IDE availability for start command
await validateIdeForStartCommand(thisCommand)

Add new function after validateGhCliForCommand (around line 167):

async function validateIdeForStartCommand(command: Command): Promise<void> {
  const commandName = command.args[0] ?? ''
  
  // Only validate for start command
  if (commandName !== 'start') {
    return
  }
  
  // Check if --no-code flag was passed (Commander stores as 'code' option)
  const codeOption = command.opts()['code']
  if (codeOption === false) {
    return // User explicitly disabled IDE launch
  }
  
  // Load settings to check IDE configuration and startIde default
  const settingsManager = new SettingsManager()
  const settings = await settingsManager.loadSettings()
  
  // If startIde is explicitly false in workflow config, skip validation
  const workflowConfig = settings.workflows?.issue
  if (workflowConfig?.startIde === false && codeOption !== true) {
    return
  }
  
  // Get configured IDE (defaults to vscode)
  const ideConfig = getIdeConfig(settings.ide)
  const available = await isIdeAvailable(ideConfig.command)
  
  if (!available) {
    const hint = getInstallHint(settings.ide?.type ?? 'vscode')
    throw new Error(
      `${ideConfig.name} is configured as your IDE but "${ideConfig.command}" command was not found.\n\n` +
      `${hint}\n\n` +
      `Alternatively, use --no-code to skip IDE launch or configure a different IDE in settings.`
    )
  }
}

Also need to add imports at top of cli.ts:

import { getIdeConfig, isIdeAvailable } from './utils/ide.js'

2. /src/utils/ide.ts:46-62

Change: Export getInstallHint function so cli.ts can use it

Change line 46 from:

function getInstallHint(type: string): string {

to:

export function getInstallHint(type: string): string {

Detailed Execution Order

Phase 1: Export getInstallHint

1. Edit src/utils/ide.ts:46 to add export keyword -> Verify: TypeScript compiles

Phase 2: Add CLI validation

1. Add imports at top of src/cli.ts -> Verify: No import errors
2. Add validateIdeForStartCommand call after line 86 -> Verify: Hook is called
3. Add validateIdeForStartCommand function after validateGhCliForCommand -> Verify: TypeScript compiles

Phase 3: Add tests

1. Add test cases to src/cli.test.ts -> Verify: Tests pass
2. Run pnpm build -> Verify: Build succeeds
3. Manual test: il start 123 --no-code should skip validation
4. Manual test: il start 123 with vscode configured but code not in PATH should fail with helpful message

Dependencies and Configuration

None

[acreeger]

Implementation Complete - Issue #372

Summary

Added early IDE validation to the il start command that fails fast when VSCode (or other configured IDE) is not accessible. The validation runs before workspace creation and provides clear instructions on how to fix the issue.

Changes Made

• src/utils/ide.ts: Exported getInstallHint() function for use in CLI validation
• src/cli.ts: Added validateIdeForStartCommand() function that validates IDE availability before workspace creation
• src/cli.test.ts: Added comprehensive unit tests for IDE validation covering all edge cases

Validation Results

• Tests: 3026 passed / 3027 total (1 skipped)
• Typecheck: Passed
• Lint: Passed

---

Detailed Changes by File (click to expand)

Files Modified

/src/utils/ide.ts

Changes: Added export keyword to getInstallHint() function (line 46)

/src/cli.ts

Changes: Added IDE validation for start command

• Added import for getIdeConfig, isIdeAvailable, getInstallHint from ./utils/ide.js
• Added call to validateIdeForStartCommand(thisCommand) in preAction hook (after gh CLI validation)
• Implemented validateIdeForStartCommand() function (lines 220-267) that:
  • Only runs for start command
  • Skips validation when --no-code flag is used
  • Skips validation when startIde: false in settings (unless --code flag overrides)
  • Checks IDE availability using existing isIdeAvailable() function
  • Exits with clear error message and install instructions when IDE not found

/src/cli.test.ts

Changes: Added comprehensive test suite for IDE validation

• Added import for validateIdeForStartCommand and ide module
• Added describe('IDE validation') test block with 10 test cases covering:
  • Command filtering (skips non-start commands)
  • --no-code flag handling
  • startIde setting handling
  • IDE availability checking (exit on unavailable, pass on available)
  • Correct IDE command based on settings
  • Default to vscode when not configured
  • Settings loading error handling

Test Coverage Added

• src/cli.test.ts: 10 new test cases for validateIdeForStartCommand()

Dependencies Added

None

[acreeger]

iloom Session Summary

Key Themes:

• Validation logic already existed in the codebase - solution reused existing patterns rather than rebuilding
• Early validation at command entry point prevents wasted workspace creation when IDE is unavailable
• Test-first approach with 10 comprehensive test cases ensured robust error handling across all edge cases

---

Session Details (click to expand)

Key Insights

• The getInstallHint() function in src/utils/ide.ts:46-62 already contained the exact VS Code PATH installation instructions needed
• The CLI already had a validateGhCliForCommand() preAction hook pattern that could be copied for IDE validation
• The isIdeAvailable() utility function was already checking command execution correctly - no need to detect installation paths

Decisions Made

• Validate at command entry, not workspace creation: Added validation in the preAction hook for the start command to fail fast before creating worktrees/branches
• Skip validation when IDE won't be launched: Validation is bypassed when --no-code flag is used or startIde: false in settings (unless --code explicitly overrides)
• Reuse existing patterns: Followed the exact structure of validateGhCliForCommand() for consistency and maintainability

Challenges Resolved

• User clarification needed: Initial assumption was to detect VS Code installation paths, but user feedback clarified that simple code command execution check was sufficient (installation method irrelevant)
• Scope definition: Determined that automatic PATH fixes were out of scope - solution should provide clear instructions to use VS Code's built-in "Install 'code' command in PATH" option

Lessons Learned

• Always check existing codebase patterns before implementing new solutions - the preAction hook pattern saved significant development time
• Simple validation approaches are often better than complex detection heuristics - checking command availability is more reliable than guessing installation paths
• Early validation prevents user frustration - failing before workspace creation is better than discovering IDE issues after git operations complete

---

Generated with 🤖❤️ by iloom.ai