From 43715855be762b7346f79336b84842ac30b9f1a0 Mon Sep 17 00:00:00 2001 From: DariusIII Date: Tue, 11 Aug 2026 13:17:54 +0200 Subject: [PATCH] Update AU instruction files --- .ai/guidelines/sail/core.blade.php | 33 +++ .ai/rules/command-execution.md | 8 + .ai/rules/index.md | 9 + .env.example | 12 + .../laravel-boost.instructions.md | 239 ++++++++++++++++++ .../nntmux-command-execution.instructions.md | 32 +++ AGENTS.md | 93 ++++--- config/boost.php | 115 +++++++++ 8 files changed, 507 insertions(+), 34 deletions(-) create mode 100644 .ai/guidelines/sail/core.blade.php create mode 100644 .ai/rules/command-execution.md create mode 100644 .ai/rules/index.md create mode 100644 .github/instructions/laravel-boost.instructions.md create mode 100644 .github/instructions/nntmux-command-execution.instructions.md create mode 100644 config/boost.php diff --git a/.ai/guidelines/sail/core.blade.php b/.ai/guidelines/sail/core.blade.php new file mode 100644 index 000000000..d96387cc8 --- /dev/null +++ b/.ai/guidelines/sail/core.blade.php @@ -0,0 +1,33 @@ +@php +/** @var \Laravel\Boost\Install\GuidelineAssist $assist */ +@endphp +# Laravel Sail (project override) + +> **This guideline OVERRULES Boost's built-in Sail rules.** Do not require `{{ $assist->sailBinaryPath() }}` for day-to-day PHP, Artisan, Composer, Node, Pint, PHPStan, or tests. + +## Default: run on the WSL host + +Prefer host commands (as in the Quick Reference at the top of `AGENTS.md`): + +- Artisan: `{{ $assist->artisanCommand('[command]') }}` (e.g. `php artisan test --compact --filter=TestName`) +- Composer: `{{ $assist->composerCommand('install') }}` +- Node/npm: `{{ $assist->nodePackageManagerCommand('run build') }}` +- Vendor bins: `{{ $assist->binCommand('pint --dirty') }}`, `{{ $assist->binCommand('phpstan analyse --memory-limit=2G') }}` + +Do **not** prefix every command with Sail. Ignore any conflicting Boost text that says you MUST execute all commands through Sail. + +## When Sail / Docker is appropriate + +Use Sail or `Makefile` targets only when: + +- Starting/stopping the stack (`make up` / `{{ $assist->sailBinaryPath() }} up -d`, `make down` / `{{ $assist->sailBinaryPath() }} stop`) +- The user explicitly asks for containerized commands +- A task needs services only available inside Compose (e.g. aligning container UIDs via `make fix-permissions`) + +## WSL2 + Windows Docker Desktop + +Local development is often done in WSL2 while Docker runs via **Windows Docker Desktop** (WSL integration), not a native Linux Docker install inside the distro. + +- If `docker` / `docker compose` cannot be found, or Sail fails with "Docker is not running" / cannot connect to the daemon, do **not** assume Docker must be installed inside WSL. Check that Docker Desktop is running on Windows and that WSL integration is enabled for this distro. +- Prefer diagnosing through Docker Desktop (engine status, WSL integration settings) before suggesting `apt install docker` or similar host installs. +- Host PHP/Artisan/tests remain valid even when the Docker engine is down. diff --git a/.ai/rules/command-execution.md b/.ai/rules/command-execution.md new file mode 100644 index 000000000..767757e73 --- /dev/null +++ b/.ai/rules/command-execution.md @@ -0,0 +1,8 @@ +# Host commands overrule Boost Sail + +NNTmux agents must prefer WSL-host commands (`php artisan`, `./vendor/bin/pint`, `npm run build`, etc.) over Laravel Boost's built-in Sail rule that says every command must go through Sail. + +- Official Boost override: `.ai/guidelines/sail/core.blade.php` (wins on `boost:install` / `boost:update`). +- Host binaries for generated guidelines: `config/boost.php` → `executable_paths` defaults (`php`, `composer`, `npm`, `vendor/bin/`). +- Use Sail / `Makefile` only for Compose lifecycle or when the user asks for containerized runs. +- On WSL2, Docker often comes from Windows Docker Desktop; missing `docker` usually means Desktop/WSL integration, not a missing apt package. diff --git a/.ai/rules/index.md b/.ai/rules/index.md new file mode 100644 index 000000000..23a0dba07 --- /dev/null +++ b/.ai/rules/index.md @@ -0,0 +1,9 @@ +# Project rules index + +Path-scoped and standing agent rules for NNTmux. Hand-written entries live here; Boost may also write under `.ai/rules/boost/` when scoped guidelines are enabled. + +| Glob | File | Summary | +|------|------|---------| +| `**` | [command-execution.md](./command-execution.md) | Host WSL commands overrule Boost Sail “must use Sail” | + +Before editing, also `grep -rin 'keyword' .ai/rules` for related notes. diff --git a/.env.example b/.env.example index 901036c30..6a85ef929 100644 --- a/.env.example +++ b/.env.example @@ -352,6 +352,18 @@ TMUX_TERMINAL=tmux-256color TMUX_MONITOR_DELAY=10 TMUX_REFRESH_INTERVAL=60 +# ────────────────────────────────────────────────────────────── +# Laravel Boost (AI guidelines) +# ────────────────────────────────────────────────────────────── +# Defaults force host binaries in generated guidelines so agents are not +# steered into Sail for every Artisan/Composer/npm command. Leave blank / +# unset to keep the config/boost.php host defaults. Set to Sail wrappers +# only if you intentionally want Sail-prefixed Boost guidance again. +# BOOST_PHP_EXECUTABLE_PATH=php +# BOOST_COMPOSER_EXECUTABLE_PATH=composer +# BOOST_NPM_EXECUTABLE_PATH=npm +# BOOST_VENDOR_BIN_EXECUTABLE_PATH=vendor/bin/ + # ────────────────────────────────────────────────────────────── # Docker / Sail # ────────────────────────────────────────────────────────────── diff --git a/.github/instructions/laravel-boost.instructions.md b/.github/instructions/laravel-boost.instructions.md new file mode 100644 index 000000000..0d84627cb --- /dev/null +++ b/.github/instructions/laravel-boost.instructions.md @@ -0,0 +1,239 @@ + +=== foundation rules === + +# Laravel Boost Guidelines + +The Laravel Boost guidelines are specifically curated by Laravel maintainers for this application. These guidelines should be followed closely to ensure the best experience when building Laravel applications. + +## Foundational Context + +This application is a Laravel application running on PHP 8.5. You are an expert with the Laravel ecosystem. Always use the APIs that match the installed major version of each package — do not assume a version. + +Before relying on a package's API, confirm its installed version: +- PHP packages: run `composer show --direct` to list direct dependencies with versions, or `composer show ` for a single package. +- JS packages: check `package.json` for the installed versions. + +## Conventions + +- You must follow all existing code conventions used in this application. When creating or editing a file, check sibling files for the correct structure, approach, and naming. +- Use descriptive names for variables and methods. For example, `isRegisteredForDiscounts`, not `discount()`. +- Check for existing components to reuse before writing a new one. + +## Verification Scripts + +- Do not create verification scripts or tinker when tests cover that functionality and prove they work. Unit and feature tests are more important. + +## Application Structure & Architecture + +- Stick to existing directory structure; don't create new base folders without approval. +- Do not change the application's dependencies without approval. + +## Frontend Bundling + +- If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `npm run build`, `npm run dev`, or `composer run dev`. Ask them. + +## Documentation Files + +- You must only create documentation files if explicitly requested by the user. + +## Replies + +- Be concise in your explanations - focus on what's important rather than explaining obvious details. + +=== boost rules === + +# Laravel Boost + +## Tools + +- Laravel Boost is an MCP server with tools designed specifically for this application. Prefer Boost tools over manual alternatives like shell commands or file reads. +- Use `database-query` to run read-only queries against the database instead of writing raw SQL in tinker. +- Use `database-schema` to inspect table structure before writing migrations or models. +- Use `get-absolute-url` to resolve the correct scheme, domain, and port for project URLs. Always use this before sharing a URL with the user. +- Use `browser-logs` to read browser logs, errors, and exceptions. Only recent logs are useful, ignore old entries. + +## Searching Documentation (IMPORTANT) + +- Always use `search-docs` before making code changes. Do not skip this step. It returns version-specific docs based on installed packages automatically. +- Pass a `packages` array to scope results when you know which packages are relevant. +- Use multiple broad, topic-based queries: `['rate limiting', 'routing rate limiting', 'routing']`. Expect the most relevant results first. +- Do not add package names to queries because package info is already shared. Use `test resource table`, not `filament 4 test resource table`. + +### Search Syntax + +1. Use words for auto-stemmed AND logic: `rate limit` matches both "rate" AND "limit". +2. Use `"quoted phrases"` for exact position matching: `"infinite scroll"` requires adjacent words in order. +3. Combine words and phrases for mixed queries: `middleware "rate limit"`. +4. Use multiple queries for OR logic: `queries=["authentication", "middleware"]`. + +## Project Rules + +- This project contains committed, area-grouped rules in `.ai/rules` when that directory exists (settled decisions, non-obvious traps, standing constraints). Framework and package guidelines that only apply to specific paths (testing, frontend, components) also live there, under `.ai/rules/boost` — this is not just recorded decisions, it is load-bearing guidance you have not seen inline. Before you enter plan mode or create/edit any file, you MUST first: open @.ai/rules/index.md (it maps file globs to rule files), read every rule file whose globs cover the path(s) in scope, and run `grep -rin 'keyword' .ai/rules` to catch what a path match alone misses. Do not write code until you have read and are following every matching rule. If `.ai/rules` does not exist, continue without it. +- Record durable rules with `record-rule` so the next agent or teammate inherits them instead of working them out again. Pass a `glob` (e.g. `app/Http/Controllers/**`), a short `title`, and a few-line `note`. Always use `record-rule`, never your native memory or notes tool — native memory is personal and session-scoped; only `.ai/rules` is shared with the team and persists in the repo. + +## Artisan + +- Run Artisan commands directly via the command line (e.g., `php artisan route:list`). Use `php artisan list` to discover available commands and `php artisan [command] --help` to check parameters. +- Inspect routes with `php artisan route:list`. Filter with: `--method=GET`, `--name=users`, `--path=api`, `--except-vendor`, `--only-vendor`. +- Read configuration values using dot notation: `php artisan config:show app.name`, `php artisan config:show database.default`. Or read config files directly from the `config/` directory. + +## Tinker + +- Execute PHP in app context for debugging and testing code. Do not create models without user approval, prefer tests with factories instead. Prefer existing Artisan commands over custom tinker code. +- Always use single quotes to prevent shell expansion: `php artisan tinker --execute 'Your::code();'` + - Double quotes for PHP strings inside: `php artisan tinker --execute 'User::where("active", true)->count();'` + +=== php rules === + +# PHP + +- Always use curly braces for control structures, even for single-line bodies. +- Use PHP 8 constructor property promotion: `public function __construct(public GitHub $github) { }`. Do not leave empty zero-parameter `__construct()` methods unless the constructor is private. +- Use explicit return type declarations and type hints for all method parameters: `function isAccessible(User $user, ?string $path = null): bool` +- Follow existing application Enum naming conventions. +- Prefer PHPDoc blocks over inline comments. Only add inline comments for exceptionally complex logic. +- Use array shape type definitions in PHPDoc blocks. + +=== deployments rules === + +# Deployment + +- Laravel can be deployed using [Laravel Cloud](https://cloud.laravel.com/), which is the fastest way to deploy and scale production Laravel applications. + +=== sail rules === + +# Laravel Sail (project override) + +> **This guideline OVERRULES Boost's built-in Sail rules.** Do not require `vendor/bin/sail` for day-to-day PHP, Artisan, Composer, Node, Pint, PHPStan, or tests. + +## Default: run on the WSL host + +Prefer host commands (as in the Quick Reference at the top of `AGENTS.md`): + +- Artisan: `php artisan [command]` (e.g. `php artisan test --compact --filter=TestName`) +- Composer: `composer install` +- Node/npm: `npm run build` +- Vendor bins: `vendor/bin/pint --dirty`, `vendor/bin/phpstan analyse --memory-limit=2G` + +Do **not** prefix every command with Sail. Ignore any conflicting Boost text that says you MUST execute all commands through Sail. + +## When Sail / Docker is appropriate + +Use Sail or `Makefile` targets only when: + +- Starting/stopping the stack (`make up` / `vendor/bin/sail up -d`, `make down` / `vendor/bin/sail stop`) +- The user explicitly asks for containerized commands +- A task needs services only available inside Compose (e.g. aligning container UIDs via `make fix-permissions`) + +## WSL2 + Windows Docker Desktop + +Local development is often done in WSL2 while Docker runs via **Windows Docker Desktop** (WSL integration), not a native Linux Docker install inside the distro. + +- If `docker` / `docker compose` cannot be found, or Sail fails with "Docker is not running" / cannot connect to the daemon, do **not** assume Docker must be installed inside WSL. Check that Docker Desktop is running on Windows and that WSL integration is enabled for this distro. +- Prefer diagnosing through Docker Desktop (engine status, WSL integration settings) before suggesting `apt install docker` or similar host installs. +- Host PHP/Artisan/tests remain valid even when the Docker engine is down. + +=== tests rules === + +# Test Enforcement + +- Every change must be programmatically tested. Write a new test or update an existing test, then run the affected tests to make sure they pass. +- Run the minimum number of tests needed to ensure code quality and speed. Use `php artisan test --compact` with a specific filename or filter. + +=== laravel/core rules === + +# Do Things the Laravel Way + +- Use `php artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using `php artisan list` and check their parameters with `php artisan [command] --help`. +- If you're creating a generic PHP class, use `php artisan make:class`. +- Pass `--no-interaction` to all Artisan commands to ensure they work without user input. You should also pass the correct `--options` to ensure correct behavior. + +### Model Creation + +- When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `php artisan make:model --help` to check the available options. + +## APIs & Eloquent Resources + +- For APIs, default to using Eloquent API Resources and API versioning unless existing API routes do not, then you should follow existing application convention. + +## URL Generation + +- When generating links to other pages, prefer named routes and the `route()` function. + +## Testing + +- When creating models for tests, use the factories for the models. Check if the factory has custom states that can be used before manually setting up the model. +- Faker: Use methods such as `$this->faker->word()` or `fake()->randomDigit()`. Follow existing conventions whether to use `$this->faker` or `fake()`. +- When creating tests, make use of `php artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests. + +## Vite Error + +- If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `npm run build` or ask the user to run `npm run dev` or `composer run dev`. + +=== livewire/core rules === + +# Livewire + +- Livewire allow to build dynamic, reactive interfaces in PHP without writing JavaScript. +- You can use Alpine.js for client-side interactions instead of JavaScript frameworks. +- Keep state server-side so the UI reflects it. Validate and authorize in actions as you would in HTTP requests. + +=== pint/core rules === + +# Laravel Pint Code Formatter + +- If you have modified any PHP files, you must run `vendor/bin/pint --dirty --format agent` before finalizing changes to ensure your code matches the project's expected style. +- Do not run `vendor/bin/pint --test --format agent`, simply run `vendor/bin/pint --format agent` to fix any formatting issues. + +=== phpunit/core rules === + +# 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. +- Every time a test has been updated, run that singular test. +- When the tests relating to your feature are passing, ask the user if they would like to also run the entire test suite to make sure everything is still passing. +- Tests should cover all happy paths, failure paths, and edge cases. +- You must not remove any tests or test files from the tests directory without approval. These are not temporary or helper files; these are core to the application. + +## Running Tests + +- Run the minimal number of tests, using an appropriate filter, before finalizing. +- To run all tests: `php artisan test --compact`. +- To run all tests in a file: `php artisan test --compact tests/Feature/ExampleTest.php`. +- To filter on a particular test name: `php artisan test --compact --filter=testName` (recommended after making a change to a related file). + +=== revolution/laravel-boost-phpstorm-copilot/core rules === + +## PhpStorm with GitHub Copilot Plugin + +This package provides custom CodeEnvironment integration for PhpStorm with GitHub Copilot plugin with Laravel Boost. It enables PhpStorm users to leverage Laravel Boost's MCP (Model Context Protocol) server functionality. + +### Important: Project Path Verification + +**Before using Laravel Boost MCP tools in PhpStorm with GitHub Copilot plugin, verify that the project path in the global MCP configuration file matches your current project.** + +The MCP configuration file is stored system-wide at: +- macOS, Linux: `~/.config/github-copilot/intellij/mcp.json` +- Windows: `%LOCALAPPDATA%\github-copilot\intellij\mcp.json` + +If the project path in the MCP configuration does not match your current Laravel project, **you must update it before using MCP tools**: + + +php artisan boost:install --guidelines --skills --mcp --no-interaction + + +This command updates the MCP configuration file with the absolute path to your current Laravel project, ensuring MCP tools interact with the correct project. + +### When to Run boost:install + +Run `php artisan boost:install` whenever you: +- Switch to a different Laravel project +- Clone or move your project to a new location +- Notice MCP tools are accessing the wrong project's data + +### Why This is Necessary + +Unlike project-local MCP configurations, PhpStorm with GitHub Copilot plugin stores MCP server configurations in a system-wide location. This allows multiple projects to share the same MCP server registration, but requires updating the configuration when switching between projects to ensure the correct project path is used. + + diff --git a/.github/instructions/nntmux-command-execution.instructions.md b/.github/instructions/nntmux-command-execution.instructions.md new file mode 100644 index 000000000..293538503 --- /dev/null +++ b/.github/instructions/nntmux-command-execution.instructions.md @@ -0,0 +1,32 @@ +--- +applyTo: "**" +description: Override Boost Sail — prefer WSL host commands for Artisan/tests/tooling +--- + +# Command execution (overrides Laravel Boost Sail) + +This project's instructions **overrule** Boost's built-in Sail guideline that says you MUST run all commands through Sail. + +## Default + +Run PHP, Artisan, Composer, npm, Pint, PHPStan, and tests on the **WSL host**: + +```bash +php artisan test --compact --filter=TestName +./vendor/bin/pint --dirty +./vendor/bin/phpstan analyse --memory-limit=2G +npm run build +php artisan make:test --phpunit ExampleTest --no-interaction +``` + +Do **not** prefix routine commands with `vendor/bin/sail` or `./sail`. + +## Sail / Docker only when needed + +Use Sail or `make …` for stack lifecycle (`make up` / `make down`) or when the user explicitly asks for containerized commands. + +## WSL2 + Windows Docker Desktop + +If `docker` is missing or the daemon is unreachable, check that **Windows Docker Desktop** is running and WSL integration is enabled for this distro. Do not assume Docker must be apt-installed inside WSL. Host Artisan/tests remain valid when Docker is down. + +Canonical override source: `.ai/guidelines/sail/core.blade.php` (consumed by `php artisan boost:update`). diff --git a/AGENTS.md b/AGENTS.md index 532355ddf..0a7226222 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,16 @@ > AI coding agent guidelines for NNTmux - a Laravel 13 Usenet indexer. +## Command execution precedence (overrules Boost Sail) + +**This section and `.ai/guidelines/sail/core.blade.php` overrule Laravel Boost's built-in Sail rules** (including any text below that says you MUST run all commands through Sail). + +1. **Default:** run Artisan, Composer, npm, Pint, PHPStan, and tests on the **WSL host** using the Quick Reference below. +2. **Sail / `make`:** only for Compose lifecycle (`make up` / `make down`) or when the user explicitly asks for containerized commands. +3. **Docker missing in WSL:** usually means Windows Docker Desktop is stopped or WSL integration is off — do not apt-install Docker inside WSL by default. Host tooling still works when Docker is down. + +Canonical Boost override: `.ai/guidelines/sail/core.blade.php`. Host binaries for generated guidelines: `config/boost.php` → `executable_paths`. Copilot mirror: `.github/instructions/nntmux-command-execution.instructions.md`. + ## Quick Reference ```bash @@ -99,8 +109,8 @@ PHPUnit only (no Pest). Create tests: `php artisan make:test --phpunit {name}` ### Commands - 80+ auto-registered in `app/Console/Commands/` - Create with `php artisan make:` + `--no-interaction` -- Docker/Sail convenience targets live in `Makefile`; prefer `make artisan cmd="..."`, `make test filter=TestName`, `make pint`, and `make npm-build` when working inside containers -- On WSL2, Docker may come from **Windows Docker Desktop** (not a Linux Docker package in the distro). If `docker` is missing or the daemon is unreachable, start Desktop / enable WSL integration before installing Docker inside WSL — see Sail rules below +- Prefer host `php artisan …` / `./vendor/bin/…` (see Command execution precedence). Use `Makefile` / Sail only for Compose lifecycle or when the user asks for containerized runs (`make artisan cmd="..."`, `make test filter=TestName`, etc.) +- On WSL2, Docker may come from **Windows Docker Desktop** (not a Linux Docker package in the distro). If `docker` is missing or the daemon is unreachable, start Desktop / enable WSL integration before installing Docker inside WSL - This workspace may have cached routes under `bootstrap/cache/routes-*.php`; after adding/changing routes, refresh with `php artisan route:cache` if a route appears missing ### Admin Content @@ -187,10 +197,6 @@ Before relying on a package's API, confirm its installed version: - PHP packages: run `composer show --direct` to list direct dependencies with versions, or `composer show ` for a single package. - JS packages: check `package.json` for the installed versions. -## Skills Activation - -This project has domain-specific skills available in `**/skills/**`. You MUST activate the relevant skill whenever you work in that domain—don't wait until you're stuck. - ## Conventions - You must follow all existing code conventions used in this application. When creating or editing a file, check sibling files for the correct structure, approach, and naming. @@ -208,7 +214,7 @@ This project has domain-specific skills available in `**/skills/**`. You MUST ac ## Frontend Bundling -- If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `vendor/bin/sail npm run build`, `vendor/bin/sail npm run dev`, or `vendor/bin/sail composer run dev`. Ask them. +- If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `npm run build`, `npm run dev`, or `composer run dev`. Ask them. ## Documentation Files @@ -251,15 +257,15 @@ This project has domain-specific skills available in `**/skills/**`. You MUST ac ## Artisan -- Run Artisan commands directly via the command line (e.g., `vendor/bin/sail artisan route:list`). Use `vendor/bin/sail artisan list` to discover available commands and `vendor/bin/sail artisan [command] --help` to check parameters. -- Inspect routes with `vendor/bin/sail artisan route:list`. Filter with: `--method=GET`, `--name=users`, `--path=api`, `--except-vendor`, `--only-vendor`. -- Read configuration values using dot notation: `vendor/bin/sail artisan config:show app.name`, `vendor/bin/sail artisan config:show database.default`. Or read config files directly from the `config/` directory. +- Run Artisan commands directly via the command line (e.g., `php artisan route:list`). Use `php artisan list` to discover available commands and `php artisan [command] --help` to check parameters. +- Inspect routes with `php artisan route:list`. Filter with: `--method=GET`, `--name=users`, `--path=api`, `--except-vendor`, `--only-vendor`. +- Read configuration values using dot notation: `php artisan config:show app.name`, `php artisan config:show database.default`. Or read config files directly from the `config/` directory. ## Tinker - Execute PHP in app context for debugging and testing code. Do not create models without user approval, prefer tests with factories instead. Prefer existing Artisan commands over custom tinker code. -- Always use single quotes to prevent shell expansion: `vendor/bin/sail artisan tinker --execute 'Your::code();'` - - Double quotes for PHP strings inside: `vendor/bin/sail artisan tinker --execute 'User::where("active", true)->count();'` +- Always use single quotes to prevent shell expansion: `php artisan tinker --execute 'Your::code();'` + - Double quotes for PHP strings inside: `php artisan tinker --execute 'User::where("active", true)->count();'` === php rules === @@ -280,36 +286,55 @@ This project has domain-specific skills available in `**/skills/**`. You MUST ac === sail rules === -# Laravel Sail +# Laravel Sail (project override) -- This project runs inside Laravel Sail's Docker containers. You MUST execute all commands through Sail. -- Start services using `vendor/bin/sail up -d` and stop them with `vendor/bin/sail stop`. -- Open the application in the browser by running `vendor/bin/sail open`. -- Always prefix PHP, Artisan, Composer, and Node commands with `vendor/bin/sail`. Examples: - - Run Artisan Commands: `vendor/bin/sail artisan migrate` - - Install Composer packages: `vendor/bin/sail composer install` - - Execute Node commands: `vendor/bin/sail npm run dev` - - Execute PHP scripts: `vendor/bin/sail php [script]` -- View all available Sail commands by running `vendor/bin/sail` without arguments. +> **This guideline OVERRULES Boost's built-in Sail rules.** Do not require `vendor/bin/sail` for day-to-day PHP, Artisan, Composer, Node, Pint, PHPStan, or tests. + +## Default: run on the WSL host + +Prefer host commands (as in the Quick Reference at the top of `AGENTS.md`): + +- Artisan: `php artisan [command]` (e.g. `php artisan test --compact --filter=TestName`) +- Composer: `composer install` +- Node/npm: `npm run build` +- Vendor bins: `vendor/bin/pint --dirty`, `vendor/bin/phpstan analyse --memory-limit=2G` + +Do **not** prefix every command with Sail. Ignore any conflicting Boost text that says you MUST execute all commands through Sail. + +## When Sail / Docker is appropriate + +Use Sail or `Makefile` targets only when: + +- Starting/stopping the stack (`make up` / `vendor/bin/sail up -d`, `make down` / `vendor/bin/sail stop`) +- The user explicitly asks for containerized commands +- A task needs services only available inside Compose (e.g. aligning container UIDs via `make fix-permissions`) + +## WSL2 + Windows Docker Desktop + +Local development is often done in WSL2 while Docker runs via **Windows Docker Desktop** (WSL integration), not a native Linux Docker install inside the distro. + +- If `docker` / `docker compose` cannot be found, or Sail fails with "Docker is not running" / cannot connect to the daemon, do **not** assume Docker must be installed inside WSL. Check that Docker Desktop is running on Windows and that WSL integration is enabled for this distro. +- Prefer diagnosing through Docker Desktop (engine status, WSL integration settings) before suggesting `apt install docker` or similar host installs. +- Host PHP/Artisan/tests remain valid even when the Docker engine is down. === tests rules === # Test Enforcement - Every change must be programmatically tested. Write a new test or update an existing test, then run the affected tests to make sure they pass. -- Run the minimum number of tests needed to ensure code quality and speed. Use `vendor/bin/sail artisan test --compact` with a specific filename or filter. +- Run the minimum number of tests needed to ensure code quality and speed. Use `php artisan test --compact` with a specific filename or filter. === laravel/core rules === # Do Things the Laravel Way -- Use `vendor/bin/sail artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using `vendor/bin/sail artisan list` and check their parameters with `vendor/bin/sail artisan [command] --help`. -- If you're creating a generic PHP class, use `vendor/bin/sail artisan make:class`. +- Use `php artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using `php artisan list` and check their parameters with `php artisan [command] --help`. +- If you're creating a generic PHP class, use `php artisan make:class`. - Pass `--no-interaction` to all Artisan commands to ensure they work without user input. You should also pass the correct `--options` to ensure correct behavior. ### Model Creation -- When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `vendor/bin/sail artisan make:model --help` to check the available options. +- When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `php artisan make:model --help` to check the available options. ## APIs & Eloquent Resources @@ -323,11 +348,11 @@ This project has domain-specific skills available in `**/skills/**`. You MUST ac - When creating models for tests, use the factories for the models. Check if the factory has custom states that can be used before manually setting up the model. - Faker: Use methods such as `$this->faker->word()` or `fake()->randomDigit()`. Follow existing conventions whether to use `$this->faker` or `fake()`. -- When creating tests, make use of `vendor/bin/sail artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests. +- When creating tests, make use of `php artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests. ## Vite Error -- If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `vendor/bin/sail npm run build` or ask the user to run `vendor/bin/sail npm run dev` or `vendor/bin/sail composer run dev`. +- If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `npm run build` or ask the user to run `npm run dev` or `composer run dev`. === livewire/core rules === @@ -341,14 +366,14 @@ This project has domain-specific skills available in `**/skills/**`. You MUST ac # Laravel Pint Code Formatter -- If you have modified any PHP files, you must run `vendor/bin/sail bin pint --dirty --format agent` before finalizing changes to ensure your code matches the project's expected style. -- Do not run `vendor/bin/sail bin pint --test --format agent`, simply run `vendor/bin/sail bin pint --format agent` to fix any formatting issues. +- If you have modified any PHP files, you must run `vendor/bin/pint --dirty --format agent` before finalizing changes to ensure your code matches the project's expected style. +- Do not run `vendor/bin/pint --test --format agent`, simply run `vendor/bin/pint --format agent` to fix any formatting issues. === phpunit/core rules === # PHPUnit -- This application uses PHPUnit for testing. All tests must be written as PHPUnit classes. Use `vendor/bin/sail artisan make:test --phpunit {name}` to create a new test. +- 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. - Every time a test has been updated, run that singular test. - When the tests relating to your feature are passing, ask the user if they would like to also run the entire test suite to make sure everything is still passing. @@ -358,9 +383,9 @@ This project has domain-specific skills available in `**/skills/**`. You MUST ac ## Running Tests - Run the minimal number of tests, using an appropriate filter, before finalizing. -- To run all tests: `vendor/bin/sail artisan test --compact`. -- To run all tests in a file: `vendor/bin/sail artisan test --compact tests/Feature/ExampleTest.php`. -- To filter on a particular test name: `vendor/bin/sail artisan test --compact --filter=testName` (recommended after making a change to a related file). +- To run all tests: `php artisan test --compact`. +- To run all tests in a file: `php artisan test --compact tests/Feature/ExampleTest.php`. +- To filter on a particular test name: `php artisan test --compact --filter=testName` (recommended after making a change to a related file). === revolution/laravel-boost-phpstorm-copilot/core rules === diff --git a/config/boost.php b/config/boost.php new file mode 100644 index 000000000..9fd07d182 --- /dev/null +++ b/config/boost.php @@ -0,0 +1,115 @@ + env('BOOST_ENABLED', true), + + /* + |-------------------------------------------------------------------------- + | Boost Project Rules + |-------------------------------------------------------------------------- + | + | Project rules let agents write decisions, traps and standing constraints + | as tracked Markdown in /.ai/rules/. Enabling "scoped_guidelines" also + | moves path-scoped guidelines to .ai/rules/boost/ - it stays opt-in. + | + */ + + 'rules' => [ + 'enabled' => env('BOOST_RULES_ENABLED', true), + 'scoped_guidelines' => env('BOOST_RULES_SCOPED_GUIDELINES', false), + ], + + /* + |-------------------------------------------------------------------------- + | Excluded Guidelines + |-------------------------------------------------------------------------- + | + | Any guidelines listed here will be excluded whenever Boost composes your + | AI guidelines during boost:install or boost:update. Entries match the + | names shown within the boost:install summary, e.g. "livewire/core". + | + */ + + 'guidelines' => [ + 'exclude' => [], + ], + + /* + |-------------------------------------------------------------------------- + | Excluded Skills + |-------------------------------------------------------------------------- + | + | Any skills listed here will not be installed or synced to your agents + | by boost:install and boost:update, e.g. "fluxui-development". Your + | own skills within the ".ai/skills" directory are never excluded. + | + */ + + 'skills' => [ + 'exclude' => [], + ], + + /* + |-------------------------------------------------------------------------- + | Boost Executables Paths + |-------------------------------------------------------------------------- + | + | These options allow you to specify custom paths for the executables that + | Boost uses. While configured, they take precedence over the automatic + | discovery mechanism (including Sail prefixes when sail is enabled). + | + | NNTmux defaults to WSL-host binaries so generated Boost guidelines and + | agent command examples are NOT forced through Sail. Override via env if + | you intentionally want Sail-prefixed guidance again. + | + */ + + 'executable_paths' => [ + 'php' => env('BOOST_PHP_EXECUTABLE_PATH', 'php'), + 'composer' => env('BOOST_COMPOSER_EXECUTABLE_PATH', 'composer'), + 'npm' => env('BOOST_NPM_EXECUTABLE_PATH', 'npm'), + 'vendor_bin' => env('BOOST_VENDOR_BIN_EXECUTABLE_PATH', 'vendor/bin/'), + 'current_directory' => env('BOOST_CURRENT_DIRECTORY_EXECUTABLE_PATH'), + ], + + /* + |-------------------------------------------------------------------------- + | Boost Browser Logs Watcher + |-------------------------------------------------------------------------- + | + | The following option may be used to enable or disable the browser logs + | watcher feature within Laravel Boost. The log watcher will read any + | errors within the browser's console to give Boost better context. + | + */ + + 'browser_logs_watcher' => env('BOOST_BROWSER_LOGS_WATCHER', true), + + /* + |-------------------------------------------------------------------------- + | Browser Log Levels + |-------------------------------------------------------------------------- + | + | This option defines which browser console log levels will be captured by + | Boost's browser logger. You may trim this list down to ['error'] when + | warnings, info, and debug messages become too noisy to be relevant. + | + */ + + 'browser_log_levels' => explode(',', env('BOOST_BROWSER_LOG_LEVELS', 'error,warning,info,debug')), + +];