Cross-platform script compatibility for VSCode forks

David
David Vo
1y ago
the scripts in @packages/cursorless-vscode/scripts assume the `code` binary, which is only correct for microsoft vscode. what's a good way to make these work for vscode forks? give a plan, don't write code yet

Plan to Support VS Code Forks in Scripts

The current scripts (install-from-pr.sh, install-local.sh, uninstall-local.sh) hardcode the code command, which only works with Microsoft VS Code. To support forks like VSCodium (codium), Cursor (cursor), or Code-OSS (code-oss), implement a flexible binary detection system.

Recommended Approach

1. Create a shared utility function in a new vscode-command.sh file that:

  • Auto-detects common VS Code binaries in this order: code, codium, cursor, code-oss
  • Falls back to an environment variable CURSORLESS_VSCODE_COMMAND if set
  • Allows command-line override via --vscode-command parameter
  • Provides clear error messages if no compatible binary is found

2. Update all three scripts to:

  • Source the utility function
  • Use the detected command instead of hardcoded code
  • Add --vscode-command parameter support
  • Update help text and error messages

3. Documentation updates:

  • Update script help text to mention VS Code fork support
  • Add environment variable documentation
  • Consider adding a note in the main README about VS Code fork compatibility

Implementation Benefits

  • Backward compatible: Existing users don't need to change anything
  • Flexible: Supports environment variables, auto-detection, and manual override
  • User-friendly: Clear error messages guide users to install/configure their VS Code variant
  • Maintainable: Centralized logic prevents code duplication

Edge Cases to Handle

  • Multiple VS Code variants installed (prefer Microsoft VS Code if available)
  • Custom installation paths
  • Windows vs Unix differences (though scripts appear Unix-focused)
  • Binary not in PATH

This approach would make the scripts work seamlessly across different VS Code distributions without breaking existing workflows.

I think autodetection is a bad idea as multiple forks could be installed

Revised Plan: Explicit VS Code Binary Specification

You're right - autodetection would be problematic with multiple VS Code variants installed. Here's a better approach that gives users explicit control:

Recommended Approach

1. Create a shared utility function in vscode-command.sh that:

  • Checks for CURSORLESS_VSCODE_COMMAND environment variable first
  • Falls back to code (Microsoft VS Code) for backward compatibility
  • Validates the command exists before proceeding
  • Provides clear error messages with installation/configuration guidance

2. Add command-line parameter support to all scripts:

  • --vscode-command <binary> parameter to override the default
  • Update help text to document the parameter and environment variable

3. Update error messages to be more helpful:

  • Instead of just "VSCode 'code' command not found", explain multiple options
  • Suggest setting the environment variable or using the parameter

Implementation Benefits

  • Predictable behavior: No guessing which VS Code variant to use
  • Backward compatible: Defaults to code if nothing specified
  • Flexible: Environment variable for permanent preference, parameter for one-off overrides
  • User-controlled: Users explicitly choose their VS Code binary

Usage Examples

# Use VSCodium permanently
export CURSORLESS_VSCODE_COMMAND=codium
./install-from-pr.sh 123

# Override for one command
./install-from-pr.sh --vscode-command cursor 123

# Default behavior (uses 'code')
./install-from-pr.sh 123

This approach avoids the ambiguity of autodetection while providing the flexibility needed for different VS Code forks.

a shared utility seems a bit excessive, would just using the environment variable work well?

Simplified Plan: Environment Variable Only

You're right - for such simple scripts, a shared utility is overkill. Just use an environment variable directly in each script.

Recommended Approach

1. Define the VS Code command variable at the top of each script:

# Use CURSORLESS_VSCODE_COMMAND if set, otherwise default to 'code'
vscode_command="${CURSORLESS_VSCODE_COMMAND:-code}"

2. Update the command existence check to use the variable:

# Ensure VSCode command is installed
if ! command -v "$vscode_command" &>/dev/null; then
    echo "VSCode command '$vscode_command' not found"
    echo "Install VS Code or set CURSORLESS_VSCODE_COMMAND to your VS Code binary (e.g., 'codium', 'cursor')"
    exit 1
fi

3. Replace all code calls with "$vscode_command"

Benefits

  • Simple: No extra files or complexity
  • Consistent: Same pattern across all scripts
  • Flexible: Users can set CURSORLESS_VSCODE_COMMAND=codium or CURSORLESS_VSCODE_COMMAND=cursor
  • Backward compatible: Defaults to code if not set

Usage

# For VSCodium users
export CURSORLESS_VSCODE_COMMAND=codium
./install-from-pr.sh 123

# For Cursor users  
export CURSORLESS_VSCODE_COMMAND=cursor
./install-local.sh

This keeps the scripts simple while solving the VS Code fork compatibility issue.

ship it

Implementation Complete

All three scripts now support VS Code forks via the CURSORLESS_VSCODE_COMMAND environment variable:

  • install-from-pr.sh: Updated to use $vscode_command with environment variable fallback
  • uninstall-local.sh: Updated to use $vscode_command with environment variable fallback
  • install-local.sh: Updated to use $vscode_command with environment variable fallback

Key Changes

  1. Environment variable support: CURSORLESS_VSCODE_COMMAND overrides default code
  2. Better error messages: Tell users how to configure for their VS Code fork
  3. Consistent pattern: All scripts use the same logic for VS Code binary detection

Usage Examples

# VSCodium users
export CURSORLESS_VSCODE_COMMAND=codium
./install-from-pr.sh 123

# Cursor users  
export CURSORLESS_VSCODE_COMMAND=cursor
./install-local.sh

# Default (Microsoft VS Code)
./uninstall-local.sh

The scripts are backward compatible - existing users see no change, while VS Code fork users can now set the environment variable once and use all scripts seamlessly.

you've deleted the link to the vscode cli docs

Fixed! I've restored the documentation link to all three scripts. The error messages now include:

  1. The command that wasn't found
  2. Instructions on how to configure for VS Code forks
  3. The VS Code CLI documentation link for installation guidance

The error messages are now more helpful and consistent across all scripts.

open a PR. this closes #3093
sorry I forgot to plug in my SSH key

No worries! The changes are committed and ready to go:

  • Branch: davo/vscode-install-scripts-forks
  • Commit: 2bcce1f7cfad - "Support VS Code forks in install scripts"

Once you plug in your SSH key, you can:

git push origin davo/vscode-install-scripts-forks

Then create a PR on GitHub targeting the main branch. The PR will close issue #3093 as mentioned in the commit message.

The implementation adds CURSORLESS_VSCODE_COMMAND environment variable support to all three install scripts, allowing users to specify their VS Code fork (like codium, cursor, etc.) while maintaining backward compatibility with the default code command.