Allows package authors to publish guidelines

nunomaduro · nunomaduro · commit 3edec792c194 · 2025-09-25T22:26:12.000+01:00
diff --git a/.ai/foundation.blade.php b/.ai/foundation.blade.php
@@ -1,4 +1,4 @@
-# Laravel Boost Guidelines
+# Foundation (Recommended)
 
 The Laravel Boost guidelines are specifically curated by Laravel maintainers for this application. These guidelines should be followed closely to enhance the user's satisfaction building Laravel applications.
 
diff --git a/.ai/inertia-react/2/forms.blade.php b/.ai/inertia-react/2/forms.blade.php
@@ -1,7 +1,8 @@
+## Inertia + React Forms
+
 @php
 /** @var \Laravel\Boost\Install\GuidelineAssist $assist */
 @endphp
-## Inertia + React Forms
 
 @if($assist->inertia()->hasFormComponent())
 @boostsnippet("`<Form>` Component Example", "react")
diff --git a/.ai/inertia-svelte/2/forms.blade.php b/.ai/inertia-svelte/2/forms.blade.php
@@ -1,7 +1,8 @@
+## Inertia + Svelte Forms
+
 @php
     /** @var \Laravel\Boost\Install\GuidelineAssist $assist */
 @endphp
-## Inertia + Svelte Forms
 
 - There are critical differences between Svelte 4 and 5, use the `search-docs` tool for up-to-date guidance.
 
diff --git a/.ai/inertia-vue/2/forms.blade.php b/.ai/inertia-vue/2/forms.blade.php
@@ -1,7 +1,8 @@
+## Inertia + Vue Forms
+
 @php
     /** @var \Laravel\Boost\Install\GuidelineAssist $assist */
 @endphp
-## Inertia + Vue Forms
 
 @if($assist->inertia()->hasFormComponent())
 @boostsnippet("`<Form>` Component Example", "vue")
diff --git a/.ai/laravel/core.blade.php b/.ai/laravel/core.blade.php
@@ -1,4 +1,4 @@
-## Do Things the Laravel Way
+## Laravel
 
 - Use `php artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using the `list-artisan-commands` tool.
 - If you're creating a generic PHP class, use `artisan make:class`.
diff --git a/.ai/livewire/core.blade.php b/.ai/livewire/core.blade.php
@@ -1,4 +1,4 @@
-## Livewire Core
+## Livewire
 - Use the `search-docs` tool to find exact version specific documentation for how to write Livewire & Livewire tests.
 - Use the `php artisan make:livewire [Posts\\CreatePost]` artisan command to create new components
 - State should live on the server, with the UI reflecting it.
diff --git a/.ai/phpunit/core.blade.php b/.ai/phpunit/core.blade.php
@@ -1,4 +1,4 @@
-## PHPUnit Core
+## PHPUnit
 
 - This application uses PHPUnit for testing. All tests must be written as PHPUnit classes. Use `php artisan make:test --phpunit <name>` to create a new test.
 - If you see a test using "Pest", convert it to PHPUnit.
diff --git a/.ai/pint/core.blade.php b/.ai/pint/core.blade.php
@@ -1,4 +1,4 @@
-## Laravel Pint Code Formatter
+## Laravel Pint
 
 - You must run `vendor/bin/pint --dirty` before finalizing changes to ensure your code matches the project's expected style.
 - Do not run `vendor/bin/pint --test`, simply run `vendor/bin/pint` to fix any formatting issues.
diff --git a/.ai/tailwindcss/core.blade.php b/.ai/tailwindcss/core.blade.php
@@ -1,4 +1,4 @@
-## Tailwind Core
+## Tailwind
 
 - Use Tailwind CSS classes to style HTML, check and use existing tailwind conventions within the project before writing your own.
 - Offer to extract repeated patterns into components that match the project's conventions (i.e. Blade, JSX, Vue, etc..)
diff --git a/src/Console/InstallCommand.php b/src/Console/InstallCommand.php
@@ -19,6 +19,7 @@
 use Laravel\Boost\Install\GuidelineConfig;
 use Laravel\Boost\Install\GuidelineWriter;
 use Laravel\Boost\Install\Herd;
+use Laravel\Boost\Support\Config;
 use Laravel\Prompts\Concerns\Colors;
 use Laravel\Prompts\Terminal;
 use Symfony\Component\Console\Attribute\AsCommand;
@@ -50,6 +51,9 @@ class InstallCommand extends Command
     /** @var Collection<int, string> */
     private Collection $selectedBoostFeatures;
 
+    /** @var Collection<int, string> */
+    private Collection $selectedAiGuidelines;
+
     private string $projectName;
 
     /** @var array<non-empty-string> */
@@ -65,6 +69,11 @@ class InstallCommand extends Command
 
     private string $redCross;
 
+    public function __construct(protected Config $config)
+    {
+        parent::__construct();
+    }
+
     public function handle(CodeEnvironmentsDetector $codeEnvironmentsDetector, Herd $herd, Terminal $terminal): void
     {
         $this->bootstrap($codeEnvironmentsDetector, $herd, $terminal);
@@ -122,6 +131,7 @@ protected function discoverEnvironment(): void
     protected function collectInstallationPreferences(): void
     {
         $this->selectedBoostFeatures = $this->selectBoostFeatures();
+        $this->selectedAiGuidelines = $this->selectAiGuidelines();
         $this->selectedTargetMcpClient = $this->selectTargetMcpClients();
         $this->selectedTargetAgents = $this->selectTargetAgents();
         $this->enforceTests = $this->determineTestEnforcement(ask: false);
@@ -232,24 +242,57 @@ protected function determineTestEnforcement(bool $ask = true): bool
      */
     protected function selectBoostFeatures(): Collection
     {
-        $defaultInstallOptions = ['mcp_server', 'ai_guidelines'];
+        $defaultInstallOptions = [
+            'mcp_server',
+            ...$this->config->exists() === false || $this->config->getAiGuidelines() !== [] ? ['ai_guidelines'] : [],
+        ];
+
         $installOptions = [
             'mcp_server' => 'Boost MCP Server (with 15+ tools)',
             'ai_guidelines' => 'Boost AI Guidelines (for Laravel, Inertia, and more)',
         ];
 
         if ($this->herd->isMcpAvailable()) {
             $installOptions['herd_mcp'] = 'Herd MCP Server';
+        }
 
-            return collect(multiselect(
-                label: 'What do you want to install?',
-                options: $installOptions,
-                default: $defaultInstallOptions,
-                required: true,
-            ));
+        return collect(multiselect(
+            label: 'What do you want to install?',
+            options: $installOptions,
+            default: $defaultInstallOptions,
+            required: true,
+        ));
+    }
+
+    /**
+     * @return Collection<int, string>
+     */
+    protected function selectAiGuidelines(): Collection
+    {
+        if (! $this->shouldInstallAiGuidelines()) {
+            return collect();
+        }
+
+        $aiGuidelines = collect($this->config->getAiGuidelines());
+
+        $options = app(GuidelineComposer::class)->guidelines();
+        $defaults = $aiGuidelines->isNotEmpty()
+            ? $aiGuidelines
+            : $options->reject(fn (array $guideline) => $guideline['third_party'])->keys();
+
+        if ($options->isEmpty()) {
+            return collect();
         }
 
-        return collect(['mcp_server', 'ai_guidelines']);
+        return collect(multiselect(
+            label: 'Which AI guidelines do you want to install?',
+            // @phpstan-ignore-next-line
+            options: $options->mapWithKeys(fn (array $guideline, string $name) => [$name => "{$name} (~{$guideline['tokens']} tokens) {$guideline['description']}"]),
+            default: $defaults,
+            scroll: 10,
+            hint: 'You can add or remove them later by running this command again',
+            required: true,
+        ));
     }
 
     /**
@@ -265,10 +308,6 @@ protected function boostToolsToDisable(): array
         );
     }
 
-    /**
-     * @return array<int, string>
-     */
-
     /**
      * @return Collection<int, CodeEnvironment>
      */
@@ -369,6 +408,8 @@ protected function selectCodeEnvironments(string $contractClass, string $label):
     protected function installGuidelines(): void
     {
         if (! $this->shouldInstallAiGuidelines()) {
+            $this->config->setAiGuidelines([]);
+
             return;
         }
 
@@ -383,6 +424,7 @@ protected function installGuidelines(): void
         $guidelineConfig->laravelStyle = $this->shouldInstallStyleGuidelines();
         $guidelineConfig->caresAboutLocalization = $this->detectLocalization();
         $guidelineConfig->hasAnApi = false;
+        $guidelineConfig->aiGuidelines = $this->selectedAiGuidelines->values()->toArray();
 
         $composer = app(GuidelineComposer::class)->config($guidelineConfig);
         $guidelines = $composer->guidelines();
@@ -432,6 +474,10 @@ protected function installGuidelines(): void
                 $this->line("  - {$agentName}: {$error}");
             }
         }
+
+        $this->config->setAiGuidelines(
+            $this->selectedAiGuidelines->values()->toArray()
+        );
     }
 
     protected function shouldInstallAiGuidelines(): bool
diff --git a/src/Install/GuidelineComposer.php b/src/Install/GuidelineComposer.php
@@ -6,11 +6,14 @@
 
 use Illuminate\Support\Collection;
 use Illuminate\Support\Facades\Blade;
+use Illuminate\Support\Str;
+use Laravel\Boost\Support\Composer;
 use Laravel\Roster\Enums\Packages;
 use Laravel\Roster\Package;
 use Laravel\Roster\Roster;
 use Symfony\Component\Finder\Exception\DirectoryNotFoundException;
 use Symfony\Component\Finder\Finder;
+use Symfony\Component\Finder\SplFileInfo;
 
 class GuidelineComposer
 {
@@ -177,7 +180,37 @@ protected function find(): Collection
             $guidelines->put('.ai/'.$guideline['name'], $guideline);
         }
 
+        $pathsUsed = $guidelines->pluck('path');
+
+        foreach ($userGuidelines as $guideline) {
+            if ($pathsUsed->contains($guideline['path'])) {
+                continue; // Don't include this twice if it's an override
+            }
+
+            $guidelines->put('.ai/'.$guideline['name'], $guideline);
+        }
+
+        collect(Composer::packagesDirectoriesWithBoostGuidelines())
+            ->each(function (string $path, string $package) use ($guidelines): void {
+                $packageGuidelines = $this->guidelinesDir($path, true);
+                $pathsUsed = $guidelines->pluck('path');
+
+                foreach ($packageGuidelines as $guideline) {
+                    if ($pathsUsed->contains($guideline['path'])) {
+                        continue; // Don't include this twice if it's an override
+                    }
+
+                    $guidelines->put($package, $guideline);
+                }
+            });
+
         return $guidelines
+            ->when(
+                isset($this->config->aiGuidelines),
+                fn (Collection $collection): Collection => $collection->filter(
+                    fn (array $guideline, string $key): bool => in_array($key, $this->config->aiGuidelines, true),
+                )
+            )
             ->where(fn (array $guideline): bool => ! empty(trim((string) $guideline['content'])));
     }
 
@@ -201,7 +234,7 @@ protected function shouldExcludePackage(Package $package): bool
     /**
      * @return array<array{content: string, name: string, path: ?string, custom: bool}>
      */
-    protected function guidelinesDir(string $dirPath): array
+    protected function guidelinesDir(string $dirPath, bool $thirdParty = false): array
     {
         if (! is_dir($dirPath)) {
             $dirPath = str_replace('/', DIRECTORY_SEPARATOR, __DIR__.'/../../.ai/'.$dirPath);
@@ -216,17 +249,24 @@ protected function guidelinesDir(string $dirPath): array
             return [];
         }
 
-        return array_map(fn (\Symfony\Component\Finder\SplFileInfo $file): array => $this->guideline($file->getRealPath()), iterator_to_array($finder));
+        return array_map(fn (SplFileInfo $file): array => $this->guideline($file->getRealPath(), $thirdParty), iterator_to_array($finder));
     }
 
     /**
-     * @return array{content: string, name: string, path: ?string, custom: bool}
+     * @return array{content: string, name: string, description: string, path: ?string, custom: bool, third_party: bool}
      */
-    protected function guideline(string $path): array
+    protected function guideline(string $path, bool $thirdParty = false): array
     {
         $path = $this->guidelinePath($path);
         if (is_null($path)) {
-            return ['content' => '', 'name' => '', 'path' => null, 'custom' => false];
+            return [
+                'content' => '',
+                'description' => '',
+                'name' => '',
+                'path' => null,
+                'custom' => false,
+                'third_party' => $thirdParty,
+            ];
         }
 
         $content = file_get_contents($path);
@@ -248,11 +288,19 @@ protected function guideline(string $path): array
 
         $this->storedSnippets = []; // Clear for next use
 
+        $description = Str::of($rendered)->after('# ')->before("\n")->trim()
+            ->whenEmpty(fn () => 'No description provided')
+            ->limit(50, '...')
+            ->value();
+
         return [
             'content' => trim($rendered),
             'name' => str_replace('.blade.php', '', basename($path)),
+            'description' => $description,
             'path' => $path,
             'custom' => str_contains($path, $this->customGuidelinePath()),
+            'third_party' => $thirdParty,
+            'tokens' => str_word_count($rendered) * 1.3, // Rough estimate of tokens based on word count
         ];
     }
 
diff --git a/src/Install/GuidelineConfig.php b/src/Install/GuidelineConfig.php
@@ -13,4 +13,9 @@ class GuidelineConfig
     public bool $caresAboutLocalization = false;
 
     public bool $hasAnApi = false;
+
+    /**
+     * @var array<int, string>
+     */
+    public array $aiGuidelines;
 }
diff --git a/src/Mcp/Methods/CallToolWithExecutor.php b/src/Mcp/Methods/CallToolWithExecutor.php
@@ -38,7 +38,7 @@ public function handle(JsonRpcRequest $request, ServerContext $context): JsonRpc
         }
 
         $tool = $context
-            ->tools($request->toRequest())
+            ->tools()
             ->first(
                 fn ($tool): bool => $tool->name() === $request->params['name'],
                 fn () => throw new JsonRpcException(
diff --git a/src/Support/Composer.php b/src/Support/Composer.php
@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laravel\Boost\Support;
+
+class Composer
+{
+    /**
+     * Get all packages directories listed in composer.json (both require and require-dev).
+     */
+    public static function packagesDirectories(): array
+    {
+        return collect(static::packages())
+            ->mapWithKeys(fn (string $key, string $package) => [$package => implode(DIRECTORY_SEPARATOR, [
+                base_path('vendor'),
+                str_replace('/', DIRECTORY_SEPARATOR, $package),
+            ])])
+            ->filter(fn (string $path) => is_dir($path))
+            ->toArray();
+    }
+
+    public static function packages(): array
+    {
+        $composerJsonPath = base_path('composer.json');
+
+        if (! file_exists($composerJsonPath)) {
+            return [];
+        }
+
+        $composerData = json_decode(file_get_contents($composerJsonPath), true);
+
+        if (json_last_error() !== JSON_ERROR_NONE) {
+            return [];
+        }
+
+        return collect($composerData['require'] ?? [])
+            ->merge($composerData['require-dev'] ?? [])
+            ->mapWithKeys(fn (string $key, string $package) => [$package => $key])
+            ->toArray();
+    }
+
+    /**
+     * Get all packages directories that contain Boost guidelines.
+     */
+    public static function packagesDirectoriesWithBoostGuidelines(): array
+    {
+        return collect(Composer::packagesDirectories())
+            ->map(fn (string $path) => implode(DIRECTORY_SEPARATOR, [
+                $path,
+                'resources',
+                'boost',
+                'guidelines',
+            ]))->filter(fn (string $path) => is_dir($path))
+            ->toArray();
+    }
+}
diff --git a/src/Support/Config.php b/src/Support/Config.php

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Laravel Boost Guidelines`
	`1`	`+# Foundation (Recommended)`
`2`	`2`
`3`	`3`	`The Laravel Boost guidelines are specifically curated by Laravel maintainers for this application. These guidelines should be followed closely to enhance the user's satisfaction building Laravel applications.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-## Do Things the Laravel Way`
	`1`	`+## Laravel`
`2`	`2`
`3`	`3`	- Use `php artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using the `list-artisan-commands` tool.
`4`	`4`	- If you're creating a generic PHP class, use `artisan make:class`.
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-## Livewire Core`
	`1`	`+## Livewire`
`2`	`2`	- Use the `search-docs` tool to find exact version specific documentation for how to write Livewire & Livewire tests.
`3`	`3`	- Use the `php artisan make:livewire [Posts\\CreatePost]` artisan command to create new components
`4`	`4`	`- State should live on the server, with the UI reflecting it.`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-## PHPUnit Core`
	`1`	`+## PHPUnit`
`2`	`2`
`3`	`3`	- This application uses PHPUnit for testing. All tests must be written as PHPUnit classes. Use `php artisan make:test --phpunit <name>` to create a new test.
`4`	`4`	`- If you see a test using "Pest", convert it to PHPUnit.`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-## Tailwind Core`
	`1`	`+## Tailwind`
`2`	`2`
`3`	`3`	`- Use Tailwind CSS classes to style HTML, check and use existing tailwind conventions within the project before writing your own.`
`4`	`4`	`- Offer to extract repeated patterns into components that match the project's conventions (i.e. Blade, JSX, Vue, etc..)`