Laravel Altitude Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require mischasigtermans/laravel-altitude --dev
   

   Register the service provider in config/app.php (handled automatically by Laravel Boost).

2. First Sync Run the sync command to pull the latest agents:

   php artisan altitude:sync
   

   Or integrate with Laravel Boost for automatic updates:

   // composer.json
   {
     "scripts": {
       "post-update-cmd": [
         "@php artisan boost:update --quiet"
       ]
     }
   }
   

3. First Use Case Trigger an agent via TALL stack commands. For example, generate a Livewire component:

   php artisan altitude:livewire
   

   Or use the altitude Artisan command to interactively select an agent:

   php artisan altitude
   

Where to Look First

• Agent Commands: Browse available agents in app/Altitude/Agents (auto-generated by sync).
• Documentation: Run php artisan boost:docs to access version-specific guides.
• Configuration: Check config/altitude.php for customization options (e.g., agent behavior, output paths).

Implementation Patterns

Usage Patterns

1. Agent Workflows Use agents for repetitive TALL stack tasks:

   • Livewire: Generate components, scaffolding, or test files.

     php artisan altitude:livewire:component UserProfile
     

   • Tailwind: Optimize or generate utility classes.

     php artisan altitude:tailwind:optimize
     

   • Filament/Flux: Create admin panels or UI components.

     php artisan altitude:filament:resource Post
     

2. Interactive Mode Launch the interactive CLI for guided agent selection:

   php artisan altitude
   

   Follow prompts to customize outputs (e.g., naming conventions, paths).

3. Integration with Laravel Boost Leverage Boost’s MCP (Model-Controller-Provider) for version-aware documentation:

   php artisan boost:docs --agent=livewire
   

Workflows

1. Development Loop

   • Sync Agents: Run altitude:sync after updating dependencies.
   • Generate Code: Use agents to scaffold features (e.g., altitude:livewire:test).
   • Review/Refine: Agents provide suggestions; manually adjust as needed.

2. Testing Use Pest integration (if enabled) to validate agent outputs:

   php artisan altitude:pest UserProfileTest
   

3. CI/CD Add to your pipeline to auto-generate boilerplate:

   # .github/workflows/ci.yml
   - run: php artisan altitude:sync
   - run: php artisan altitude:livewire:component AdminDashboard
   

Integration Tips

• Custom Agents: Extend existing agents by creating subclasses in app/Altitude/Agents/Custom.
• Output Paths: Configure config/altitude.php to override default output directories (e.g., resources/views/livewire).
• Filament/Flux: Pair with altitude:filament:resource to auto-generate admin panels with pre-configured policies/validation.
• Tailwind: Use altitude:tailwind:purge to optimize CSS during deployments.

Gotchas and Tips

Pitfalls

1. Stack Mismatch

   • Issue: Agents assume TALL stack (Livewire, Tailwind, etc.). Non-TALL projects may break.
   • Fix: Review agent outputs and override defaults in config/altitude.php.

2. Sync Conflicts

   • Issue: Manual file edits in app/Altitude/Agents may be overwritten during sync.
   • Fix: Use altitude:sync --dry-run to preview changes or stash customizations.

3. Agent Overrides

   • Issue: Custom agents in app/Altitude/Agents/Custom may not inherit latest updates.
   • Fix: Merge changes manually after syncing or use altitude:sync --force.

4. Boost Dependency

   • Issue: Requires Laravel Boost (v1.0+). Missing Boost may cause errors.
   • Fix: Install Boost first:

     composer require laravel/boost
     php artisan boost:install
     

Debugging

1. Verbose Output Enable debug mode for agent logs:

   php artisan altitude --verbose
   

2. Agent-Specific Debugging Check storage/logs/altitude.log for errors during generation.

3. Dry Runs Test agent outputs without writing files:

   php artisan altitude:livewire:component UserProfile --dry-run
   

Tips

1. Configuration Customize agent behavior via config/altitude.php:

   'agents' => [
       'livewire' => [
           'default_namespace' => 'App\\Livewire\\Custom',
           'test_stubs' => true,
       ],
   ],
   

2. Pest Integration Enable Pest test generation for agents:

   // config/altitude.php
   'testing' => [
       'enable_pest' => true,
       'test_path' => 'tests/Altitude',
   ],
   

3. Performance

   • Cache agent outputs for repeated use (e.g., in bootstrap/app.php):

     $app->singleton(\MischaSigtermans\Altitude\Agents\LivewireAgent::class, fn() => new \MischaSigtermans\Altitude\Agents\LivewireAgent(cache()->remember(...)));
     

4. Extending Agents Override agent methods in app/Altitude/Agents/Custom:

   namespace App\Altitude\Agents\Custom;
   
   use MischaSigtermans\Altitude\Agents\LivewireAgent;
   
   class CustomLivewireAgent extends LivewireAgent {
       protected function generateTestStub(): string {
           return '// Custom test stub logic';
       }
   }
   

5. CI/CD Optimization Skip sync in CI if agents are pre-synced:

   - run: php artisan altitude:livewire:component --skip-sync
   

6. Tailwind JIT Ensure Tailwind JIT is configured if using altitude:tailwind agents to avoid CSS conflicts.

7. Filament Policies Agents auto-generate policies. Extend them in app/Policies for custom logic:

   namespace App\Policies;
   
   use MischaSigtermans\Altitude\Agents\Filament\GeneratedPolicy;
   
   class CustomPostPolicy extends GeneratedPolicy {
       public function updateAny(): bool {
           return true; // Custom logic
       }
   }