### Listing Tasks Examples

Source: https://github.com/eduardocruz/phpx/blob/main/scripts/README.md

Provides examples of how to use the `list` command to display tasks, filter by status, and include subtasks in the output.

```bash
# List all tasks
task-master list

# List tasks with a specific status
task-master list --status=pending

# List tasks and include their subtasks
task-master list --with-subtasks

# List tasks with a specific status and include their subtasks
task-master list --status=pending --with-subtasks
```

--------------------------------

### Manual Installation

Source: https://github.com/eduardocruz/phpx/blob/main/README.md

Provides steps for manually installing PHPX by cloning the repository, installing dependencies via Composer, and setting up the executable script.

```bash
git clone https://github.com/eduardocruz/phpx.git
cd phpx

composer install

# Make the script executable
chmod +x bin/phpx

# Add to PATH (choose one):
# Temporary: Add to current session
export PATH="$PATH:$(pwd)/bin"

# Permanent: Add to your shell configuration (~/.bashrc, ~/.zshrc, etc.)
echo 'export PATH="$PATH:/path/to/phpx/bin"' >> ~/.zshrc
```

--------------------------------

### Updating Tasks Examples

Source: https://github.com/eduardocruz/phpx/blob/main/scripts/README.md

Illustrates how to use the `update` command to modify tasks, specifying a starting task ID and providing a new prompt for the update.

```bash
# Update tasks starting from ID 4 with a new prompt
task-master update --from=4 --prompt="Refactor tasks from ID 4 onward to use Express instead of Fastify"

# Update all tasks (default from=1)
task-master update --prompt="Add authentication to all relevant tasks"
```

--------------------------------

### CLI Commands Usage

Source: https://github.com/eduardocruz/phpx/blob/main/scripts/README.md

Demonstrates how to execute the meta-development script commands either globally installed or locally within the project. It lists the available commands for task management.

```bash
# If installed globally
task-master [command] [options]

# If using locally within the project
node scripts/dev.js [command] [options]

Available commands:

- init: Initialize a new project
- parse-prd: Generate tasks from a PRD document
- list: Display all tasks with their status
- update: Update tasks based on new information
- generate: Create individual task files
- set-status: Change a task's status
- expand: Add subtasks to a task or all tasks
- clear-subtasks: Remove subtasks from specified tasks
- next: Determine the next task to work on based on dependencies
- show: Display detailed information about a specific task
- analyze-complexity: Analyze task complexity and generate recommendations
- complexity-report: Display the complexity analysis in a readable format
- add-dependency: Add a dependency between tasks
- remove-dependency: Remove a dependency from a task
- validate-dependencies: Check for invalid dependencies
- fix-dependencies: Fix invalid dependencies automatically
- add-task: Add a new task using AI

Run task-master --help or node scripts/dev.js --help to see detailed usage information.
```

--------------------------------

### Composer Project Creation and Dependency Installation

Source: https://github.com/eduardocruz/phpx/blob/main/specification.md

Manages Composer projects by creating new projects with specified packages and versions, and installing dependencies. It locates the Composer executable and handles command execution.

```php
namespace PHPX;

class ComposerClient {
    private $composerPath;
    
    public function __construct() {
        // Find composer executable
        $this->composerPath = $this->findComposerPath();
    }
    
    private function findComposerPath(): string {
        // Check if composer is in PATH
        $composerPath = shell_exec('which composer 2>/dev/null');
        if ($composerPath) {
            return trim($composerPath);
        }
        
        // Check common locations
        $commonLocations = [
            '/usr/local/bin/composer',
            '/usr/bin/composer',
            getenv('HOME') . '/composer.phar',
        ];
        
        foreach ($commonLocations as $location) {
            if (file_exists($location) && is_executable($location)) {
                return $location;
            }
        }
        
        // As a last resort, download composer.phar
        $tempPath = sys_get_temp_dir() . '/composer.phar';
        if (!file_exists($tempPath)) {
            file_put_contents(
                $tempPath, 
                file_get_contents('https://getcomposer.org/composer.phar')
            );
            chmod($tempPath, 0755);
        }
        
        return $tempPath;
    }
    
    public function createProject(string $packageName, string $version, string $targetDir): bool {
        $command = sprintf(
            '%s create-project %s:%s %s --prefer-dist --no-dev --no-interaction',
            escapeshellarg($this->composerPath),
            escapeshellarg($packageName),
            escapeshellarg($version),
            escapeshellarg($targetDir)
        );
        
        exec($command, $output, $returnCode);
        
        return $returnCode === 0;
    }
    
    public function installDependencies(string $projectDir): bool {
        $command = sprintf(
            'cd %s && %s install --no-dev --no-interaction',
            escapeshellarg($projectDir),
            escapeshellarg($this->composerPath)
        );
        
        exec($command, $output, $returnCode);
        
        return $returnCode === 0;
    }
}
```

--------------------------------

### PHPX Configuration and Caching Setup

Source: https://github.com/eduardocruz/phpx/blob/main/specification.md

This snippet outlines the configuration management for PHPX. It sets up configuration and cache directories based on XDG Base Directory specifications or defaults to standard user directories. It also ensures these directories exist and loads configuration from a JSON file, providing default values if the file is not found.

```php
<?php
namespace PHPX;

class Config {
    private $configDir;
    private $cacheDir;
    
    public function __construct() {
        // Use XDG Base Directory spec if possible
        $this->configDir = getenv('XDG_CONFIG_HOME') ?: (getenv('HOME') . '/.config/phpx');
        $this->cacheDir = getenv('XDG_CACHE_HOME') ?: (getenv('HOME') . '/.cache/phpx');
        
        $this->ensureDirectories();
        $this->loadConfig();
    }
    
    private function ensureDirectories(): void {
        if (!is_dir($this->configDir)) {
            mkdir($this->configDir, 0755, true);
        }
        
        if (!is_dir($this->cacheDir)) {
            mkdir($this->cacheDir, 0755, true);
        }
        
        if (!is_dir($this->cacheDir . '/packages')) {
            mkdir($this->cacheDir . '/packages', 0755, true);
        }
    }
    
    private function loadConfig(): void {
        $configFile = $this->configDir . '/config.json';
        if (file_exists($configFile)) {
            $this->config = json_decode(file_get_contents($configFile), true);
        } else {
            // Default configuration
            $this->config = [
                'cache_ttl' => 86400, // 24 hours
                'packagist_url' => 'https://packagist.org',
                'prefer_dist' => true,
            ];
            
            // Save default config
            $this->saveConfig();
        }
    }
    
    private function saveConfig(): void {
        file_put_contents(
            $this->configDir . '/config.json',
            json_encode($this->config, JSON_PRETTY_PRINT)
        );
    }
    
    public function getCacheDir(): string {
        return $this->cacheDir;
    }
    
    public function getPackageCacheDir(): string {
        return $this->cacheDir . '/packages';
    }
    
    public function getConfigValue(string $key, $default = null) {

```

--------------------------------

### Project Initialization

Source: https://github.com/eduardocruz/phpx/blob/main/README-task-master.md

Installs and initializes the Task Master project, either globally or locally within a project. This sets up the necessary files and structure for managing AI-driven development tasks.

```bash
# Install globally
npm install -g task-master-ai

# OR install locally within your project
npm install task-master-ai
```

```bash
# If installed globally
task-master init

# If installed locally
npx task-master-init
```

--------------------------------

### AI-Driven Development Workflow Examples

Source: https://github.com/eduardocruz/phpx/blob/main/README-task-master.md

Examples of interactions with an AI agent (like Cursor) for managing AI-driven development projects, covering project initialization, task management, implementation guidance, subtask handling, change management, and complexity analysis.

```bash
# Starting a new project
# User: I've just initialized a new project with Claude Task Master. I have a PRD at scripts/prd.txt.
# User: Can you help me parse it and set up the initial tasks?

# Working on tasks
# User: What's the next task I should work on? Please consider dependencies and priorities.

# Implementing a specific task
# User: I'd like to implement task 4. Can you help me understand what needs to be done and how to approach it?

# Managing subtasks
# User: I need to regenerate the subtasks for task 3 with a different approach. Can you help me clear and regenerate them?

# Handling changes
# User: We've decided to use MongoDB instead of PostgreSQL. Can you update all future tasks to reflect this change?

# Completing work
# User: I've finished implementing the authentication system described in task 2. All tests are passing.
# User: Please mark it as complete and tell me what I should work on next.

# Analyzing complexity
# User: Can you analyze the complexity of our tasks to help me understand which ones need to be broken down further?

# Viewing complexity report
# User: Can you show me the complexity report in a more readable format?
```

--------------------------------

### Troubleshooting Initialization

Source: https://github.com/eduardocruz/phpx/blob/main/README-task-master.md

Provides alternative methods to run the `task-master init` script if it fails to respond. This involves running the script directly using Node.js, either from the installed `node_modules` or after cloning the repository.

```bash
node node_modules/claude-task-master/scripts/init.js
```

```bash
git clone https://github.com/eyaltoledano/claude-task-master.git
cd claude-task-master
node scripts/init.js
```

--------------------------------

### Global Installation

Source: https://github.com/eduardocruz/phpx/blob/main/README.md

Installs PHPX globally using Composer. This makes the `phpx` command available in your system's PATH if the global Composer bin directory is configured correctly.

```bash
# Ensure you have PHP 8.1 or higher installed
php -v

# Install PHPX globally
composer global require eduardocruz/phpx
```

--------------------------------

### Task Master MCP Setup in Cursor

Source: https://github.com/eduardocruz/phpx/blob/main/README-task-master.md

Instructions for configuring the Task Master MCP server within Cursor settings to enable integrated task management.

```text
Name: "Task Master"
Type: "Command"
Command: "npx -y task-master-mcp"
```

--------------------------------

### Command Runner - Run Command

Source: https://github.com/eduardocruz/phpx/blob/main/specification.md

Executes a command within the context of a resolved package and its dependencies. It handles argument parsing, package resolution, dependency resolution, environment setup, and executable finding.

```php
<?php
namespace PHPX;

class CommandRunner {
    private $packageManager;
    private $dependencyResolver;
    
    public function __construct(
        PackageManager $packageManager, 
        DependencyResolver $dependencyResolver
    ) {
        $this->packageManager = $packageManager;
        $this->dependencyResolver = $dependencyResolver;
    }
    
    public function run(array $args): int {
        // Split package spec from command arguments
        $packageSpec = $args[0];
        $commandArgs = $this->extractCommandArgs($args);
        
        // Resolve package
        $package = $this->packageManager->resolvePackage($packageSpec);
        
        // Resolve dependencies
        $dependencies = $this->dependencyResolver->resolveDependencies($package);
        
        // Create execution environment
        $environment = new ExecutionEnvironment($package, $dependencies);
        
        // Find executable
        $executable = $this->findExecutable($package, $commandArgs);
        
        // Execute command
        return $environment->execute($executable, $commandArgs);
    }
    
    private function extractCommandArgs(array $args): array {
        $doubleDashPos = array_search('--', $args);
        if ($doubleDashPos !== false) {
            return array_slice($args, $doubleDashPos + 1);
        }
        return array_slice($args, 1);
    }
    
    private function findExecutable(Package $package, array $commandArgs): string {
        // First check bin in composer.json
        $composerJson = $package->getComposerJson();
        
        if (isset($composerJson['bin'])) {
            if (is_array($composerJson['bin'])) {
                // If multiple bin entries and first arg matches one, use that
                if (!empty($commandArgs) && in_array($commandArgs[0], $composerJson['bin'])) {
                    return $commandArgs[0];
                }
                // Otherwise use first bin entry
                return $composerJson['bin'][0];
            } else {
                return $composerJson['bin'];
            }
        }
        
        // Next check for common entry points
        $commonEntryPoints = [
            $package->getPath() . '/bin/' . $package->getName(),
            $package->getPath() . '/bin/run',
            $package->getPath() . '/bin/console',
        ];
        
        foreach ($commonEntryPoints as $entryPoint) {
            if (file_exists($entryPoint) && is_executable($entryPoint)) {
                return $entryPoint;
            }
        }
        
        throw new RuntimeException("Could not find executable in package " . $package->getName());
    }
}

```

--------------------------------

### CLI Commands

Source: https://github.com/eduardocruz/phpx/blob/main/README-task-master.md

Provides essential command-line interface commands for interacting with Task Master after installation. These commands cover project initialization, task parsing, listing, and generation.

```bash
# Initialize a new project
task-master init

# Parse a PRD and generate tasks
task-master parse-prd your-prd.txt

# List all tasks
task-master list

# Show the next task to work on
task-master next

# Generate task files
task-master generate
```

--------------------------------

### Update Tasks

Source: https://github.com/eduardocruz/phpx/blob/main/scripts/README.md

Updates tasks based on specified criteria. Allows specifying a custom tasks file, a starting task ID for updates, and a prompt to guide the changes. Only tasks not marked as 'done' and with IDs greater than or equal to the `--from` value are updated.

```bash
task-master update --file=custom-tasks.json --from=5 --prompt="Change database from MongoDB to PostgreSQL"
```

--------------------------------

### Configuration Management

Source: https://github.com/eduardocruz/phpx/blob/main/specification.md

Provides methods to get and set configuration values within the PHPX application. It uses a default value if a key is not found and saves the configuration after modification.

```php
namespace PHPX;

class Config {
    private array $config;

    public function __construct(array $config = []) {
        $this->config = $config;
    }

    public function getConfigValue(string $key, $default = null) {
        return $this->config[$key] ?? $default;
    }
    
    public function setConfigValue(string $key, $value): void {
        $this->config[$key] = $value;
        $this->saveConfig();
    }

    private function saveConfig(): void {
        // Placeholder for saving configuration
    }
}
```

--------------------------------

### Troubleshooting Autoloader Issues

Source: https://github.com/eduardocruz/phpx/blob/main/README.md

Steps to resolve 'autoloader not found' errors by ensuring Composer dependencies are installed or updated.

```bash
composer install
composer global update
```

--------------------------------

### PHPX CLI Entry Point

Source: https://github.com/eduardocruz/phpx/blob/main/specification.md

The main entry point for the PHPX command-line tool. It initializes core components like configuration, package manager, dependency resolver, and command runner, then parses and executes user arguments.

```php
#!/usr/bin/env php
<?php
// phpx.php - Main entry point
require_once __DIR__ . '/vendor/autoload.php';

use PHPX\CommandRunner;
use PHPX\DependencyResolver;
use PHPX\PackageManager;
use PHPX\Config;

$config = new Config();
$packageManager = new PackageManager($config);
$dependencyResolver = new DependencyResolver($packageManager);
$commandRunner = new CommandRunner($packageManager, $dependencyResolver);

// Parse and validate arguments
$args = array_slice($argv, 1);
if (empty($args)) {
    echo "Usage: phpx [options] <package-name>[:<version>] [-- <args>...]\n";
    exit(1);
}

// Execute command
try {
    $exitCode = $commandRunner->run($args);
    exit($exitCode);
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
    exit(1);
}

```

--------------------------------

### Execution Environment - Constructor

Source: https://github.com/eduardocruz/phpx/blob/main/specification.md

Initializes the execution environment with a package and its resolved dependencies.

```php
<?php
namespace PHPX;

class ExecutionEnvironment {
    private $package;
    private $dependencies;
    private $workDir;
    
    public function __construct(Package $package, array $dependencies) {
        // ... implementation details ...
    }
    // ... other methods ...
}

```

--------------------------------

### Configuration - Environment Variables

Source: https://github.com/eduardocruz/phpx/blob/main/scripts/README.md

Lists the environment variables used to configure the meta-development script, including required API keys and optional parameters for model selection, token limits, and logging.

```env
# Required Configuration
# ANTHROPIC_API_KEY: Your Anthropic API key for Claude

# Optional Configuration
# MODEL: Specify which Claude model to use (default: "claude-3-7-sonnet-20250219")
# MAX_TOKENS: Maximum tokens for model responses (default: 4000)
# TEMPERATURE: Temperature for model responses (default: 0.7)
# PERPLEXITY_API_KEY: Your Perplexity API key for research-backed subtask generation
# PERPLEXITY_MODEL: Specify which Perplexity model to use (default: "sonar-medium-online")
# DEBUG: Enable debug logging (default: false)
# LOG_LEVEL: Log level - debug, info, warn, error (default: info)
# DEFAULT_SUBTASKS: Default number of subtasks when expanding (default: 3)
# DEFAULT_PRIORITY: Default priority for generated tasks (default: medium)
# PROJECT_NAME: Override default project name in tasks.json
# PROJECT_VERSION: Override default version in tasks.json
```

--------------------------------

### Non-Interactive Mode Execution

Source: https://github.com/eduardocruz/phpx/blob/main/README.md

Example of running PHPX commands in a non-interactive mode, suitable for CI/CD pipelines or scripting.

```bash
phpx --no-interaction phpunit/phpunit:^9.0 --version
```

--------------------------------

### Update Tasks

Source: https://github.com/eduardocruz/phpx/blob/main/README-task-master.md

Updates tasks, allowing specification of a starting point using an ID and providing context via a prompt.

```bash
# Update tasks from a specific ID and provide context
task-master update --from=<id> --prompt="<prompt>"
```

--------------------------------

### Command Execution and Sandboxing

Source: https://github.com/eduardocruz/phpx/blob/main/specification.md

Demonstrates how PHPX executes commands within a secure sandbox environment. It sets up a temporary directory, configures PHP settings to disable dangerous functions, and manages the execution process with input/output streams.

```php
class CommandRunner {
    // ... other methods ...
    public function createSandbox(): Sandbox {
        return new Sandbox();
    }
}

class Sandbox {
    private $workDir;
    
    public function __construct() {
        $this->workDir = sys_get_temp_dir() . '/phpx_sandbox_' . uniqid();
        mkdir($this->workDir, 0755, true);
    }
    
    public function execute(string $command, array $env = []): int {
        // Set up environment with restrictions
        $fullEnv = array_merge($_ENV, $env);
        $fullEnv['PHPX_SANDBOX'] = '1';
        
        // Disable dangerous PHP functions if possible
        $disableFunctions = [
            'exec', 'shell_exec', 'system', 'passthru', 'proc_open', 
            'popen', 'curl_exec', 'curl_multi_exec', 'parse_ini_file', 
            'show_source'
        ];
        
        $iniContent = 'disable_functions=' . implode(',', $disableFunctions) . "\n";
        $iniPath = $this->workDir . '/php.ini';
        file_put_contents($iniPath, $iniContent);
        
        $fullEnv['PHPRC'] = $iniPath;
        
        // Execute command
        $descriptorSpec = [
            0 => STDIN,
            1 => STDOUT,
            2 => STDERR,
        ];
        
        $process = proc_open($command, $descriptorSpec, $pipes, $this->workDir, $fullEnv);
        return proc_close($process);
    }
    
    public function __destruct() {
        // Clean up
        $this->recursiveRemoveDirectory($this->workDir);
    }
    
    private function recursiveRemoveDirectory(string $dir): void {
        $files = array_diff(scandir($dir), ['.', '..']);
        foreach ($files as $file) {
            $path = "$dir/$file";
            is_dir($path) ? $this->recursiveRemoveDirectory($path) : unlink($path);
        }
        rmdir($dir);
    }
}
```

--------------------------------

### Task Complexity Analysis

Source: https://github.com/eduardocruz/phpx/blob/main/scripts/README.md

Command to analyze task complexity and generate expansion recommendations.

```bash
# Analyze all tasks and generate expansion recommendations
task-master analyze-complexity

# Specify a custom output file
task-master analyze-complexity --output=custom-report.json

# Override the model used for analysis
task-master analyze-complexity --model=claude-3-opus-20240229

# Set a custom complexity threshold (1-10)
task-master analyze-complexity --threshold=6

# Use Perplexity AI for research-backed complexity analysis
task-master analyze-complexity --research
```

--------------------------------

### Using symfony/console for Lightweight CLI

Source: https://github.com/eduardocruz/phpx/blob/main/specification.md

Demonstrates how to use the standalone symfony/console package for creating polished CLI experiences with minimal dependencies. This approach is ideal when the full Symfony framework is not required.

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Symfony\Component\Console\Application;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

$application = new Application();

$application->add(new class extends Command {
    protected static $defaultName = 'greet';

    protected function configure()
    {
        $this
            ->setDescription('Greets a user')
            ->setHelp('This command greets a user by name.');
    }

    protected function execute(InputInterface $input, OutputInterface $output)
    {
        $output->writeln('Hello World!');
        return Command::SUCCESS;
    }
});

$application->run();

```

--------------------------------

### Laravel Prompts Integration for PHPX

Source: https://github.com/eduardocruz/phpx/blob/main/PRD.txt

This section outlines the integration of Laravel Prompts into the PHPX project to enhance the command-line interface with interactive forms and user-friendly prompts. It details the steps required for the Minimum Viable Product (MVP) release, focusing on dependency management, prompt handling, and updating core commands.

```APIDOC
Project: /eduardocruz/phpx

# MVP Requirements (Laravel Prompts Integration)

1.  **Add Laravel Prompts as a dependency to the project**
    -   Action: Include `laravel/prompts` in the `composer.json` file.
    -   Verification: Run `composer install` to confirm the dependency is added.

2.  **Create a PromptManager class to handle user interactions**
    -   Purpose: Encapsulate all logic related to displaying prompts and collecting user input.
    -   Methods:
        -   `select(string $question, array $options): string`
        -   `text(string $question): string`
        -   `confirm(string $question): bool`
        -   `progress(string $message): void`

3.  **Update core command classes to use Laravel Prompts**
    -   Goal: Replace existing CLI input methods with calls to the `PromptManager`.
    -   Examples:
        -   Package selection prompts.
        -   Confirmation prompts for actions like cache clearing.

4.  **Implement interactive package selection with search and filtering**
    -   Functionality: Allow users to search and filter available packages interactively.
    -   Dependencies: Requires integration with Composer API or a package registry.

5.  **Add progress indicators for long-running processes**
    -   Use Case: Package downloads, installations, and PHAR verification.
    -   Implementation: Utilize the `progress` method from `PromptManager`.

6.  **Enhance error handling with user-friendly error messages**
    -   Strategy: Display errors using `PromptManager::error()` or similar.
    -   Content: Provide clear explanations and potential solutions.

7.  **Add confirmation prompts for destructive actions**
    -   Examples: Clearing the cache, removing installed packages.
    -   Method: `PromptManager::confirm()`

8.  **Implement interactive cache management**
    -   Features:
        -   View cache status.
        -   Clear specific cache entries or all cache.
        -   Confirmation prompts for clearing.
```

--------------------------------

### Build, Lint, and Test Commands (PHP)

Source: https://github.com/eduardocruz/phpx/blob/main/CLAUDE.md

Common commands for managing PHP project dependencies, running tests, and enforcing code style using Composer, PHPUnit, and PHP-CS-Fixer.

```bash
composer install
vendor/bin/phpunit
vendor/bin/phpunit --filter TestName
vendor/bin/php-cs-fixer fix --dry-run
vendor/bin/php-cs-fixer fix
vendor/bin/phpstan analyse src
```

--------------------------------

### Task Master CLI Configuration and AI Integration

Source: https://github.com/eduardocruz/phpx/blob/main/scripts/README.md

Details on configuring logging levels and integrating with AI services like Anthropic Claude and Perplexity AI. Perplexity integration requires setting `PERPLEXITY_API_KEY` and optionally `PERPLEXITY_MODEL` in the `.env` file.

```APIDOC
Logging:
  Environment Variable: LOG_LEVEL
  Levels:
    - debug: Detailed information for troubleshooting.
    - info: Confirmation of expected behavior (default).
    - warn: Warning messages that do not prevent execution.
    - error: Error messages that may prevent execution.
  Debug File: When DEBUG=true, logs are written to dev-debug.log.

AI Integration:
  Services:
    - Anthropic Claude: Used for PRD parsing, task generation, and subtask creation.
    - Perplexity AI: Used for research-backed subtask generation via the --research flag.
  Perplexity Setup:
    1. Obtain Perplexity API key.
    2. Add PERPLEXITY_API_KEY to .env file.
    3. Optionally set PERPLEXITY_MODEL in .env (default: "sonar-medium-online").
  Fallback: If Perplexity API fails, the script defaults to Anthropic Claude.
```

--------------------------------

### Task Expansion

Source: https://github.com/eduardocruz/phpx/blob/main/scripts/README.md

Command to expand tasks, optionally using complexity analysis recommendations.

```bash
# Expand a task, using complexity report recommendations if available
task-master expand --id=8

# Expand all tasks, prioritizing by complexity score if a report exists
task-master expand --all
```

--------------------------------

### Dependency Management

Source: https://github.com/eduardocruz/phpx/blob/main/scripts/README.md

Commands for adding, removing, and managing dependencies between tasks.

```bash
# Remove a dependency from a task
task-master remove-dependency --id=<id> --depends-on=<id>
```

--------------------------------

### PHPX Package Execution and Autoloader

Source: https://github.com/eduardocruz/phpx/blob/main/specification.md

This snippet demonstrates the core execution logic of PHPX. It prepares a temporary working directory, creates a custom autoloader that includes the main package and its dependencies, and then executes a specified executable with provided arguments. It also handles cleanup of the temporary directory.

```php
<?php
namespace PHPX;

class Executor {
    private $package;
    private $dependencies;
    private $workDir;
    
    public function __construct($package, $dependencies) {
        $this->package = $package;
        $this->dependencies = $dependencies;
        $this->workDir = sys_get_temp_dir() . '/phpx_' . uniqid();
        
        $this->prepare();
    }
    
    private function prepare(): void {
        // Create working directory
        if (!is_dir($this->workDir)) {
            mkdir($this->workDir, 0755, true);
        }
        
        // Create autoloader that includes package and dependencies
        $this->createAutoloader();
    }
    
    private function createAutoloader(): void {
        $autoloaderContent = '<?php' . PHP_EOL;
        $autoloaderContent .= '// Generated by PHPX' . PHP_EOL;
        
        // Add package's autoloader
        $packageAutoloader = $this->package->getPath() . '/vendor/autoload.php';
        if (file_exists($packageAutoloader)) {
            $autoloaderContent .= 'require_once ' . var_export($packageAutoloader, true) . ';' . PHP_EOL;
        }
        
        // Add dependency autoloaders
        foreach ($this->dependencies as $dependency) {
            $depAutoloader = $dependency->getPath() . '/vendor/autoload.php';
            if (file_exists($depAutoloader)) {
                $autoloaderContent .= 'require_once ' . var_export($depAutoloader, true) . ';' . PHP_EOL;
            }
        }
        
        file_put_contents($this->workDir . '/autoload.php', $autoloaderContent);
    }
    
    public function execute(string $executable, array $args): int {
        // Prepare environment variables
        $env = $_ENV;
        $env['PHPX_PACKAGE_PATH'] = $this->package->getPath();
        $env['PHPX_AUTOLOADER'] = $this->workDir . '/autoload.php';
        
        // Build command
        if (strtolower(substr($executable, -5)) === '.phar') {
            $command = 'php ' . escapeshellarg($executable);
        } elseif (strtolower(substr($executable, -4)) === '.php') {
            $command = 'php ' . escapeshellarg($executable);
        } else {
            $command = escapeshellarg($executable);
        }
        
        // Add arguments
        foreach ($args as $arg) {
            $command .= ' ' . escapeshellarg($arg);
        }
        
        // Execute
        $descriptorSpec = [
            0 => STDIN,
            1 => STDOUT,
            2 => STDERR,
        ];
        
        $process = proc_open($command, $descriptorSpec, $pipes, $this->workDir, $env);
        return proc_close($process);
    }
    
    public function __destruct() {
        // Clean up temporary directory
        $this->cleanup();
    }
    
    private function cleanup(): void {
        // Remove temporary directory and its contents
        if (is_dir($this->workDir)) {
            $this->recursiveRemoveDirectory($this->workDir);
        }
    }
    
    private function recursiveRemoveDirectory(string $dir): void {
        $files = array_diff(scandir($dir), ['.', '..']);
        foreach ($files as $file) {
            $path = "$dir/$file";
            is_dir($path) ? $this->recursiveRemoveDirectory($path) : unlink($path);
        }
        rmdir($dir);
    }
}

```

--------------------------------

### Listing Available PHARs

Source: https://github.com/eduardocruz/phpx/blob/main/README.md

Command to view the list of available PHAR versions that PHPX can manage.

```bash
phpx list-phars
```

--------------------------------

### GitHub Repository Handling

Source: https://github.com/eduardocruz/phpx/blob/main/specification.md

Manages interactions with GitHub, including parsing GitHub URLs, downloading repositories as zip archives, extracting them, and caching them locally.

```php
namespace PHPX;

class GitHubHandler {
    private $config;
    private $cacheDir;
    
    public function __construct(Config $config) {
        $this->config = $config;
        $this->cacheDir = $config->getCacheDir() . '/github';
        
        if (!is_dir($this->cacheDir)) {
            mkdir($this->cacheDir, 0755, true);
        }
    }
    
    public function isGitHubUrl(string $url): bool {
        return (strpos($url, 'github.com/') !== false);
    }
    
    public function parseGitHubUrl(string $url): array {
        // Handle different GitHub URL formats
        if (preg_match('#github.com/([^/]+)/([^/]+)(?:/tree/([^/]+))?#', $url, $matches)) {
            $owner = $matches[1];
            $repo = $matches[2];
            $ref = $matches[3] ?? 'master';
            
            return [
                'owner' => $owner,
                'repo' => $repo,
                'ref' => $ref,
            ];
        }
        
        throw new \RuntimeException("Invalid GitHub URL: $url");
    }
    
    public function downloadFromGitHub(string $url): string {
        $info = $this->parseGitHubUrl($url);
        
        // Create directory for repo
        $repoDir = $this->cacheDir . '/' . $info['owner'] . '_' . $info['repo'] . '_' . $info['ref'];
        
        if (!is_dir($repoDir)) {
            mkdir($repoDir, 0755, true);
            
            // Download zip from GitHub
            $zipUrl = sprintf(
                'https://github.com/%s/%s/archive/%s.zip',
                $info['owner'],
                $info['repo'],
                $info['ref']
            );
            
            $zipPath = $repoDir . '.zip';
            file_put_contents($zipPath, file_get_contents($zipUrl));
            
            // Extract zip
            $zip = new \ZipArchive();
            if ($zip->open($zipPath) === true) {
                $zip->extractTo($this->cacheDir);
                $zip->close();
                
                // Find extracted directory
                $extractedDir = glob($this->cacheDir . '/' . $info['repo'] . '-*', GLOB_ONLYDIR);
                if (!empty($extractedDir)) {
                    // Rename to our standard format
                    rename($extractedDir[0], $repoDir);
                }
                
                // Remove zip file
                unlink($zipPath);
            } else {
                throw new \RuntimeException("Failed to extract GitHub repository");
            }
        }
        
        return $repoDir;
    }
}
```

--------------------------------

### Show Task Details

Source: https://github.com/eduardocruz/phpx/blob/main/scripts/README.md

The `show` command displays comprehensive information about a specific task or subtask, including its details, status, dependencies, and related actions. It supports different syntaxes for specifying the task ID and can use a custom tasks file.

```bash
# Show details for a specific task
task-master show 1

# Alternative syntax with --id option
task-master show --id=1

# Show details for a subtask
task-master show --id=1.2

# Specify a different tasks file
task-master show 3 --file=custom-tasks.json
```

--------------------------------

### Basic Command Execution with Aliases

Source: https://github.com/eduardocruz/phpx/blob/main/README.md

Demonstrates how to execute common PHP tools like PHP CS Fixer and PHPUnit using PHPX with version specification and filtering.

```bash
phpx cs-fixer:3.26 fix src/
phpx phpunit:9 --filter MyTest
```

--------------------------------

### Task Master CLI Commands

Source: https://github.com/eduardocruz/phpx/blob/main/scripts/README.md

Provides an overview of the Task Master CLI commands for managing task dependencies and complexity.

```bash
task-master remove-dependency --id=<id> --depends-on=<id>
task-master validate-dependencies [--file=<tasks.json>]
task-master fix-dependencies [--file=<tasks.json>]
task-master analyze-complexity [--output=<report.json>] [--model=<model_name>] [--threshold=<1-10>] [--research]
task-master expand --id=<id>
task-master expand --all
```

--------------------------------

### Package Manager - Resolve Package

Source: https://github.com/eduardocruz/phpx/blob/main/specification.md

Handles the resolution of a package, including parsing specifications, checking cache, fetching from Packagist, and downloading/installing.

```php
<?php
namespace PHPX;

class PackageManager {
    // ... constructor and other methods ...
    
    public function resolvePackage(string $packageSpec): Package {
        // Parse package name and version constraint
        list($name, $version) = $this->parsePackageSpec($packageSpec);
        
        // Check if already cached
        if ($this->isPackageCached($name, $version)) {
            return $this->getCachedPackage($name, $version);
        }
        
        // Fetch from Packagist
        $packageInfo = $this->packagistClient->getPackageInfo($name);
        $bestVersion = $this->findBestVersion($packageInfo, $version);
        
        // Download and install
        $package = $this->installPackage($name, $bestVersion);
        
        return $package;
    }
    
    private function parsePackageSpec(string $spec): array {
        // Handle package:version format or just package name
        if (strpos($spec, ':') !== false) {
            list($name, $version) = explode(':', $spec, 2);
            return [$name, $version];
        }
        
        return [$spec, null]; // null means latest
    }
    
    // Additional methods for caching, installation, etc.
}

```

--------------------------------

### Expand Task with Custom Prompt

Source: https://github.com/eduardocruz/phpx/blob/main/scripts/README.md

The `expand` command allows you to expand a task, optionally overriding default recommendations with custom values for the number of subtasks and the expansion prompt. It respects flags like `--all` for sorting by complexity and preserves the `--research` flag from complexity analysis.

```bash
task-master expand --id=8 --num=5 --prompt="Custom prompt"
```

--------------------------------

### Dependency Fixing

Source: https://github.com/eduardocruz/phpx/blob/main/scripts/README.md

Command to find and fix all invalid dependencies.

```bash
# Find and fix all invalid dependencies
task-master fix-dependencies

# Specify a different tasks file
task-master fix-dependencies --file=custom-tasks.json
```

--------------------------------

### Pattern Matching in Files

Source: https://github.com/eduardocruz/phpx/blob/main/specification.md

This code snippet iterates through files, reads their content, and uses regular expressions to match predefined patterns. If a pattern is found, it records the file path and the associated warning message.

```php
$content = file_get_contents($file);

foreach ($patterns as $pattern => $warning) {
    if (preg_match('/' . $pattern . '/i', $content)) {
        $relPath = str_replace($path . '/', '', $file);
        $warnings[] = [
            'file' => $relPath,
            'warning' => $warning,
        ];
    }
}

return $warnings;
```

--------------------------------

### Release Workflow (.github/workflows/release.yml)

Source: https://github.com/eduardocruz/phpx/blob/main/README.md

This workflow automates the release process. It is triggered by version tags (e.g., 'v*'). The process includes building a PHAR archive and creating a GitHub release with downloadable artifacts.

```yaml
name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Setup PHP
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.1'
    - name: Install dependencies
      run: composer install --prefer-dist --no-progress
    - name: Build PHAR
      run: composer build-phar
    - name: Create GitHub Release
      uses: softprops/action-gh-release@v1
      with:
        files: '*.phar'
```

--------------------------------

### Task Implementation and Verification

Source: https://github.com/eduardocruz/phpx/blob/main/README-task-master.md

Workflow for implementing tasks, referencing details, considering dependencies, and verifying against test strategies.

```text
Ask the agent: "Let's implement task 3. What does it involve?"
Verify according to the task's specified testStrategy, automated tests, and manual verification.
```

--------------------------------

### PHAR File Handling and Execution

Source: https://github.com/eduardocruz/phpx/blob/main/specification.md

Provides functions to verify the integrity of a PHAR file, execute it with given arguments, and handle file downloads and content retrieval.

```php
namespace PHPX;

class PHARHandler {
    public function downloadAndExtractPhar(string $url, string $destination): bool {
        $content = file_get_contents($url);
        
        if ($content === false) {
            return false;
        }
        
        return file_put_contents($destination, $content) !== false;
    }
    
    public function verifyPhar(string $pharPath): bool {
        try {
            // Try to open the PHAR
            $phar = new \Phar($pharPath);
            return true;
        } catch (\Exception $e) {
            return false;
        }
    }
    
    public function executePhar(string $pharPath, array $args): int {
        $command = 'php ' . escapeshellarg($pharPath);
        
        foreach ($args as $arg) {
            $command .= ' ' . escapeshellarg($arg);
        }
        
        passthru($command, $exitCode);
        return $exitCode;
    }
}
```

--------------------------------

### Execute Composer Package

Source: https://github.com/eduardocruz/phpx/blob/main/README.md

Demonstrates how to execute a Composer package using PHPX. You can specify the package name and optionally a version, followed by any arguments for the package's executable.

```bash
phpx vendor/package[:version] [arguments]

# Example:
# Run PHPUnit without installing it globally
phpx phpunit/phpunit:^9.0 --version
```

--------------------------------

### PHP Code Style Guidelines

Source: https://github.com/eduardocruz/phpx/blob/main/CLAUDE.md

Defines the coding standards for PHP files within the project, including naming conventions, type hinting, error handling, and documentation practices.

```php
declare(strict_types=1);

// Classes: PascalCase (e.g., PackageManager)
class PackageManager {}

// Methods/functions: camelCase (e.g., resolvePackage())
function resolvePackage() {}

// Variables: camelCase (e.g., $packageSpec)
$packageSpec = [];

// Constants: UPPERCASE_WITH_UNDERSCORES
const MAX_RETRIES = 3;

// Namespaces: follow PSR-4 autoloading standard
namespace App\Services;

// Error handling: use exceptions with descriptive messages
try {
    // some operation
} catch (Exception $e) {
    throw new Exception('Operation failed: ' . $e->getMessage());
}

// Documentation: PHPDoc blocks for classes and methods
/**
 * Represents a package.
 */
class Package {}

/**
 * Resolves a package.
 * @param string $packageName The name of the package.
 * @return Package The resolved package.
 */
function resolvePackage(string $packageName): Package {}

// Types: use type hints and return types for all methods
// Imports: one use statement per line, alphabetically ordered
use App\Services\PackageManager;
use Exception;

```

--------------------------------

### Phpx CLI 'show' Command

Source: https://github.com/eduardocruz/phpx/blob/main/README-task-master.md

The 'show' command displays detailed information for a specific task or subtask. It includes status, priority, dependencies, implementation notes, and parent/subtask relationships. Contextual actions are also suggested based on the task's state.

```APIDOC
show:
  description: Displays comprehensive details about a specific task or subtask.
  functionality:
    - Shows task status, priority, dependencies, and detailed implementation notes.
    - For parent tasks, displays all subtasks and their status.
    - For subtasks, shows parent task relationship.
    - Provides contextual action suggestions.
    - Works with both regular tasks and subtasks (format: taskId.subtaskId).
  dependencies: None explicitly mentioned, assumes task management system is operational.
  inputs:
    - taskId: The ID of the task or subtask to display (e.g., '4' or '3.1').
  outputs: Detailed information about the specified task or subtask.
  limitations: None explicitly mentioned.
```

--------------------------------

### Task Dependency Management

Source: https://github.com/eduardocruz/phpx/blob/main/scripts/README.md

Commands for managing dependencies between tasks. Allows adding and removing dependencies using task IDs.

```bash
# Add a dependency to a task
task-master add-dependency --id=<id> --depends-on=<id>

# Remove a dependency from a task (example not provided, but assumed similar structure)
```

--------------------------------

### Troubleshooting Permission Issues

Source: https://github.com/eduardocruz/phpx/blob/main/README.md

Instructions to fix 'permission denied' errors by checking and adjusting script execution permissions.

```bash
ls -l bin/phpx
chmod +x bin/phpx
```