Environment Detection and Adaptation

This page documents the environment detection mechanisms and command path adaptation logic that enables the laravel-boost-copilot-cli package to function correctly across different execution environments. It explains how the package automatically detects system and project-specific configurations, converts command paths for different environments (Standard Laravel, Laravel Sail, Orchestra Testbench), and generates appropriate MCP configuration files.

For information about the structure and content of generated MCP configuration files, see MCP Configuration File. For details about the MCP protocol implementation, see MCP Protocol Integration.

Purpose and Scope

The CopilotCli class implements sophisticated detection and adaptation logic to support multiple execution environments without requiring manual configuration changes. This system addresses three primary challenges:

1. System Detection: Determining if GitHub Copilot CLI is installed on the developer's system
2. Project Detection: Identifying if a project is already configured for Copilot CLI usage
3. Command Path Adaptation: Converting generic PHP execution commands to environment-specific wrappers

Sources: src/CopilotCli.php1-164

Detection Mechanisms

System Detection Configuration

The package provides a system-level detection mechanism that checks if GitHub Copilot CLI is installed on the developer's machine. This detection runs during the boost:install command to determine available code environments.

Detection Method

Property	Value	Purpose
Command	command -v copilot	Checks if copilot binary is available in system PATH
Platform Support	All (macOS, Linux, WSL)	Uses POSIX-compliant shell command
Return Type	array{command: string}	Configuration array for detection strategy

The detection configuration is defined in the systemDetectionConfig() method:

Method: systemDetectionConfig(Platform $platform): array
Location: src/CopilotCli.php:31-36
Returns: ['command' => 'command -v copilot']

Detection Flow

Sources: src/CopilotCli.php31-36 tests/Feature/CopilotCliTest.php30-38

Project Detection Configuration

Project-level detection identifies whether a Laravel project is already configured to use GitHub Copilot CLI with custom instructions. This prevents duplicate configuration and helps maintain existing setups.

Detection File

Property	Value	Purpose
Detection File	.github/copilot-instructions.md	Marker file indicating Copilot CLI configuration exists
Location	Project root	Standard GitHub Copilot custom instructions location
Return Type	array{files: string[]}	Configuration array for detection strategy

The detection configuration is defined in the projectDetectionConfig() method:

Method: projectDetectionConfig(): array
Location: src/CopilotCli.php:43-48
Returns: ['files' => ['.github/copilot-instructions.md']]

Detection Logic

Sources: src/CopilotCli.php43-48 tests/Feature/CopilotCliTest.php40-48

Command Path Conversion

The convertCommandToPhpPath() method transforms generic PHP execution commands into environment-specific wrappers. This adaptation is critical for generating correct MCP server configuration that works in different execution contexts.

Conversion Logic

Method Signature

Method: convertCommandToPhpPath(string $command): string
Location: src/CopilotCli.php:76-87

Conversion Rules

Sources: src/CopilotCli.php76-87

Environment-Specific Conversions

Input Command	Environment	Output Command	Reason
php	Testbench	./vendor/bin/testbench	Testbench wrapper required
wsl	WSL	php	WSL already provides PHP context
wsl.exe	WSL	php	WSL executable variant
/usr/bin/wsl	WSL	php	Full path to WSL
./vendor/bin/sail	Laravel Sail	./vendor/bin/sail	Docker wrapper preserved
/home/user/vendor/bin/sail	Laravel Sail	./vendor/bin/sail	Normalized to relative path
php	Standard	php	Default PHP command
/usr/bin/php8.3	Standard	/usr/bin/php8.3	Custom PHP binary preserved

Example Conversions

Sources: src/CopilotCli.php76-87 tests/Feature/CopilotCliTest.php141-164

Testbench Environment Detection

Orchestra Testbench is a minimal Laravel environment used for package development. The package detects this environment and applies specific adaptations to ensure MCP server functionality.

Detection Method

Constant Check

Method: isRunningInTestbench(): bool
Location: src/CopilotCli.php:160-163
Logic: return defined('TESTBENCH_CORE');

The TESTBENCH_CORE constant is automatically defined by Orchestra Testbench when running commands through ./vendor/bin/testbench. This provides a reliable detection mechanism without additional configuration.

Detection Flow

Sources: src/CopilotCli.php160-163 tests/Feature/CopilotCliTest.php166-178

Testbench-Specific Adaptations

When running in Orchestra Testbench, two critical adaptations occur:

1. Command Path Override

All command paths are forced to ./vendor/bin/testbench regardless of input:

Input: php → Output: ./vendor/bin/testbench
Input: wsl → Output: ./vendor/bin/testbench
Input: ./vendor/bin/sail → Output: ./vendor/bin/testbench

2. Argument List Modification

The artisan argument is removed from the command arguments, as Testbench does not use the standard Laravel artisan command structure:

Environment	Command	Args	Result
Standard Laravel	php	['artisan', 'boost:mcp']	php artisan boost:mcp
Orchestra Testbench	./vendor/bin/testbench	['boost:mcp']	./vendor/bin/testbench boost:mcp

Argument Filtering Logic

Location: src/CopilotCli.php:116-119
Logic: array_values(array_filter([
 ! $this->isRunningInTestbench() ? 'artisan' : false,
 'boost:mcp',
]))

Sources: src/CopilotCli.php116-119 tests/Feature/CopilotCliTest.php239-272

MCP Configuration Generation

The installFileMcp() method generates environment-specific MCP server configuration files based on the detected environment and converted command paths.

Configuration Structure

Base Configuration Template

Environment Variations

Standard Laravel Application

Generated when: isRunningInTestbench() = false and command is php

Laravel Sail (Docker)

Generated when: isRunningInTestbench() = false and command ends with sail

Orchestra Testbench

Generated when: isRunningInTestbench() = true

Note the absence of "artisan" in the args array for Testbench.

Sources: src/CopilotCli.php95-139 tests/Feature/CopilotCliTest.php58-98

Complete Adaptation Process

The following diagram shows the end-to-end process of environment detection and adaptation during MCP configuration generation:

Configuration Object Construction

Method: installFileMcp()
Location: src/CopilotCli.php:95-139

Steps:
1. Resolve config file path: .github/mcp-config.json
2. Ensure directory exists
3. Load existing configuration if present
4. Detect environment (Testbench or not)
5. Convert command path using convertCommandToPhpPath()
6. Build args array based on environment
7. Construct serverConfig object with type, command, args, tools
8. Merge with existing config at mcpServers.laravel-boost
9. Remove empty arrays to avoid compatibility issues
10. Write formatted JSON with Unix line endings

Sources: src/CopilotCli.php95-139

Empty Array Removal

The removeEmptyArrays() method recursively removes empty arrays from the configuration object to prevent compatibility issues with certain MCP tools that fail when encountering empty arrays (e.g., "headers": []).

Removal Logic

Method: removeEmptyArrays(array $data): array
Location: src/CopilotCli.php:145-158

Algorithm:
- Recursively traverse configuration array
- For each value:
 - If array and empty: unset the key
 - If array and not empty: recursively process
 - If not array: preserve as-is
- Return cleaned array

Example Transformation

Before	After
{"headers": []}	(key removed)
{"headers": ["X-Custom: value"]}	{"headers": ["X-Custom: value"]}
{"env": {}}	(key removed)
{"env": {"APP_ENV": "local"}}	{"env": {"APP_ENV": "local"}}

Sources: src/CopilotCli.php145-158

Configuration Preservation

When generating MCP configuration, the installFileMcp() method preserves existing server configurations, allowing multiple MCP servers to coexist in the same configuration file.

Preservation Behavior

Example Configuration Merge

Sources: src/CopilotCli.php104-108 tests/Feature/CopilotCliTest.php100-139

Detection and Adaptation Summary

The following table summarizes all detection mechanisms and their corresponding adaptations:

Detection Type	Mechanism	Result	Impact
System Detection	command -v copilot	Binary exists/missing	Enable/disable copilot-cli option
Project Detection	.github/copilot-instructions.md	File exists/missing	Skip/proceed with setup
Testbench Detection	defined('TESTBENCH_CORE')	Constant defined/undefined	Force testbench wrapper + modified args
WSL Detection	Command ends with wsl	Match found	Convert to php
Sail Detection	Command ends with sail	Match found	Preserve ./vendor/bin/sail
Standard Detection	Default case	No special match	Use command as-is

Key Implementation Classes

Class	File	Methods	Purpose
CopilotCli	src/CopilotCli.php	systemDetectionConfig()	Define system detection strategy
CopilotCli	src/CopilotCli.php	projectDetectionConfig()	Define project detection strategy
CopilotCli	src/CopilotCli.php	convertCommandToPhpPath()	Convert commands for environments
CopilotCli	src/CopilotCli.php	isRunningInTestbench()	Detect Testbench environment
CopilotCli	src/CopilotCli.php	installFileMcp()	Generate environment-specific config
CopilotCli	src/CopilotCli.php	removeEmptyArrays()	Clean configuration for compatibility

Sources: src/CopilotCli.php1-164 tests/Feature/CopilotCliTest.php1-273