Launch Behaviors
Relevant source files
The following files were used as context for generating this wiki page:
Launch behaviors in vscli define the logic and strategies used to open Visual Studio Code (or compatible editors) within specific environments, primarily focusing on the transition between local host development and Dev Container environments. The system encapsulates user preferences, environment detection, and the technical execution of editor commands.
The core of this system is the Behavior struct and the ContainerStrategy enum, which determine whether the application should automatically detect a Dev Container, force a containerized launch, or remain on the host system.
Launch Strategies
The ContainerStrategy is the primary driver for how vscli handles a project path. It supports three distinct modes that dictate the search and execution path.
| Strategy | Description | Command-line Value |
|---|---|---|
| Detect | Automatically searches for .devcontainer.json or .devcontainer/devcontainer.json. Launches in container if found, otherwise launches on host. | detect |
| Force Container | Explicitly requires a Dev Container. If no configuration is found, the launch fails with an error. | force-container |
| Force Classic | Ignores any existing Dev Container configurations and launches the editor directly on the host system. | force-classic |
Sources: src/launch.rs:17-41, README.md:167-171
The following diagram illustrates the decision logic based on these strategies:
rust
pub struct Behavior {
pub strategy: ContainerStrategy,
pub args: Vec,
pub command: String,
}
Sources: [src/launch.rs:60-67](https://github.com/michidk/vscli/blob/HEAD/src/launch.rs#L60-L67)
### Setup Logic
The `Setup` struct acts as the orchestrator. It holds the workspace context, the desired behavior, and a `dry_run` flag to prevent actual execution during testing or preview.
* **`Setup::new`**: Initializes the configuration.
* **`Setup::detect`**: Performs the filesystem scan to find dev container configurations. If multiple are found, it triggers an interactive prompt for the user.
* **`Setup::launch`**: Executes the final editor command based on the resolved strategy.
Sources: [src/launch.rs:90-123](https://github.com/michidk/vscli/blob/HEAD/src/launch.rs#L90-L123)
## Dev Container Detection Algorithm
When the strategy is set to `Detect` or `ForceContainer`, `vscli` implements a specific search order to find configuration files, mirroring the behavior of Visual Studio Code.
1. **Direct File**: Checks for `.devcontainer.json` in the root of the workspace.
2. **Standard Folder**: Checks for `.devcontainer/devcontainer.json`.
3. **Subfolder Discovery**: Searches `.devcontainer/**/devcontainer.json` one level deep to support projects with multiple container definitions.
Sources: [src/workspace.rs:136-166](https://github.com/michidk/vscli/blob/HEAD/src/workspace.rs#L136-L166)
If multiple configurations are discovered, the Setup::detect function utilizes the inquire crate to present a selection UI to the user.
Sources: src/launch.rs:108-121, src/workspace.rs:151-160
Execution and URI Generation
Launching a Dev Container requires more than a simple file path; it involves generating a specific vscode-remote URI.
URI Structure
The URI is composed of:
- The protocol:
vscode-remote://dev-container - A hex-encoded JSON object containing the
hostPathand aconfigFileURI. - The target workspace folder path inside the container.
Sources: src/workspace.rs:252-257, src/uri.rs:43-50
Environment Handling (WSL)
vscli detects if it is running within Windows Subsystem for Linux (WSL). If detected, it converts Linux paths to Windows-style paths (using wslpath2) before encoding them into the URI, as the host editor is typically a Windows process.
Sources: src/workspace.rs:213-242
Sources: src/workspace.rs:194-265
Integration with History
Launch behaviors are not just transient; they are persisted in the history tracker. When a workspace is opened, the specific Behavior (strategy, command, and args) is saved. This allows the recent UI to restore the exact environment the user previously selected.
- Upserting: When opening via CLI,
vscliupdates the timestamp and behavior for the path inhistory.json. - Restoration: The
recentcommand loads these behaviors, though they can be overridden by new CLI flags during the call.
Sources: src/main.rs:65-74, src/main.rs:90-107, src/history.rs:22-35
Summary
The launch behavior system in vscli provides a robust abstraction for editor initialization. By combining automated discovery of Dev Container configurations with flexible strategies (Detect, ForceContainer, ForceClassic), it streamlines the workflow of moving between different development environments while ensuring compatibility across WSL and native Windows/Unix systems.