@fishawack/lab-env 4.44.1 → 4.45.0-beta.1

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 ## Changelog
 
+### 4.45.0-beta.1 (2025-09-01)
+
+#### Features
+
+* added a manage users permission ([e59b21a](https://bitbucket.org/fishawackdigital/lab-env/commits/e59b21a3c3d307aae3430cce676d8f20ed936525))
+* added besins client ([58bcc77](https://bitbucket.org/fishawackdigital/lab-env/commits/58bcc771fe28029e92e63be315292605974c747a))
+* added custom python setup and start commands ([6ca192f](https://bitbucket.org/fishawackdigital/lab-env/commits/6ca192f92bf1044b52aaa1e890a13be68d9cb366))
+* added devops preset ([46f43c5](https://bitbucket.org/fishawackdigital/lab-env/commits/46f43c5f7c0648112edb3ff20439626fd6a69077))
+* added devops specific commands ([21daf7a](https://bitbucket.org/fishawackdigital/lab-env/commits/21daf7a8dfb9cde0ed88b2a943c6753ef1ea003f))
+* added python instructions file ([4ba1c77](https://bitbucket.org/fishawackdigital/lab-env/commits/4ba1c7717e8e41414758d1e77bab6fc891553763))
+* copy python ai files ([def8212](https://bitbucket.org/fishawackdigital/lab-env/commits/def8212f7151a6714a76e5096c7c41c1cf55908f))
+* copy the lab-env ai file into projects ([c217274](https://bitbucket.org/fishawackdigital/lab-env/commits/c2172745ebef906536d12347c051c4e3d38f663d))
+* improved laravel ai docs ([076bd4d](https://bitbucket.org/fishawackdigital/lab-env/commits/076bd4d6d99ad58ca68b117b8d0425e3ada72cb3))
+* split lab-env into standalone ai file ([4f84fd9](https://bitbucket.org/fishawackdigital/lab-env/commits/4f84fd9999e571b67d313511f00f5bee310ac24b))
+* support python builds ([10f9929](https://bitbucket.org/fishawackdigital/lab-env/commits/10f99291306f060e720ad2e2ccf536ecda12a53c))
+* two new commands for pip and python ([658191a](https://bitbucket.org/fishawackdigital/lab-env/commits/658191a4dfeba7459d4513a875b9511fb5f1e5ee))
+* updates to lab-env config ([de73808](https://bitbucket.org/fishawackdigital/lab-env/commits/de73808cf13283ad469161c27937671de14ffcdb))
+
+#### Bug Fixes
+
+* added apply to to lab env ai file ([e82f875](https://bitbucket.org/fishawackdigital/lab-env/commits/e82f87543f0cc3add465b414b393a50b595e95c1))
+* added more context around query binding ([4cfd427](https://bitbucket.org/fishawackdigital/lab-env/commits/4cfd42737fa9b19d5b24e28e9219bbae629c5b32))
+* dont attempt to remove volumes if there aren't any ([ac9f621](https://bitbucket.org/fishawackdigital/lab-env/commits/ac9f62133f47b1e4971524fc75e8ae94ba32d4ba))
+* fixed no cache flag ([d1f3f9a](https://bitbucket.org/fishawackdigital/lab-env/commits/d1f3f9a329177f2431be802897d37bfdf3df5b1e))
+* ignore .venv from linting checks ([e49fa69](https://bitbucket.org/fishawackdigital/lab-env/commits/e49fa698397ba2287def174ad3b2a5608b7a393b))
+* support no core in python projects ([2882070](https://bitbucket.org/fishawackdigital/lab-env/commits/2882070c34546daf1d261f708a63687dcc303dfc))
+* support python in execute command ([619deea](https://bitbucket.org/fishawackdigital/lab-env/commits/619deea45eac08d41076b70c505fdaf043e5c7c1))
+* switch connect default to python for those projects ([d481960](https://bitbucket.org/fishawackdigital/lab-env/commits/d481960f1a836f5841dcf79ec5f90819eacae212))
+* use php 8.2 for new php environments ([d2a180e](https://bitbucket.org/fishawackdigital/lab-env/commits/d2a180ebcbf679d49b598f22b6587b3e28327b2a))
+
 ### 4.44.1 (2025-08-18)
 
 #### Bug Fixes

package/_Ai/laravel-12.md

@@ -2,19 +2,477 @@
 applyTo: "app/**/*,bootstrap/**/*,config/**/*,database/**/*,resources/**/*,routes/**/*,tests/**/*,composer.json,phpunit.xml"
 ---
 
-# GitHub Copilot Instructions for Laravel Containerized Project
+# GitHub Copilot Instructions for Laravel 12 Project
 
-## Project Overview
+## Laravel Model Structure & Architecture
 
-This is a Laravel application that runs entirely in Docker containers. All PHP, Composer, and database operations must be executed within the appropriate containers using our `fw` container orchestration manager.
+This is a Laravel 12 application using a comprehensive model architecture. When creating new models, follow this complete structure pattern based on existing codebase conventions.
 
-## Container Management
+### Complete Model Creation Command
 
-- **All PHP/Composer commands run in containers** - never suggest direct `php` or `composer` commands
-- Use the `fw` orchestration manager to execute all commands within containers
-- The project uses Docker with services like `nginx`, `mysql`, `redis`, and `mailhog`
+```bash
+# Create all standard files for a model (Model, Factory, Migration, Seeder, Controller, Policy)
+fw artisan make:model Post -a --api
+```
+
+### Additional Files Required Per Model
+
+After running the base command, create these additional files:
+
+```bash
+# Create Request (combines store/update requests)
+fw artisan make:request PostRequest
+
+# Create Observer
+fw artisan make:observer PostObserver -m Post
+
+# Create Resource
+fw artisan make:resource PostResource
+
+# Create Query (custom class for query building)
+fw artisan make:class Http/Queries/PostQuery
+
+# Create Test
+fw artisan make:test PostTest
+```
+
+## Model Architecture Patterns
+
+### 1. Model Structure
+
+Models should follow this pattern:
+
+```php
+<?php
+
+namespace App\Models;
+
+use App\Http\Queries\PostQuery;
+use App\Observers\PostObserver;
+use App\Traits\QueryBuilderBindable;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\SoftDeletes;
+use Illuminate\Database\Eloquent\Attributes\ObservedBy;
+
+#[ObservedBy([PostObserver::class])]
+class Post extends Model {
+    use HasFactory, QueryBuilderBindable, SoftDeletes;
+
+    public static $queryClass = PostQuery::class;
+
+    protected $fillable = [
+        // Define fillable attributes
+        "title",
+        "content",
+        "status",
+        "created_by",
+        "updated_by",
+        "deleted_by"
+    ];
+
+    protected $casts = [
+        // Cast enums and other types
+        "status" => PostStatusEnum::class
+    ];
+}
+```
+
+**Key conventions:**
+
+- Use `#[ObservedBy([ModelObserver::class])]` attribute for observer registration
+- Always include `QueryBuilderBindable` trait
+- Include `SoftDeletes` for most models
+- Set `public static $queryClass` property
+- Use enum casting where applicable
+- Include author tracking fields (`created_by`, `updated_by`, `deleted_by`)
+
+The QueryBuilderBindable trait should resolve route model binding for controller endpoints and contain the following code
+
+```php
+<?php
+
+namespace App\Traits;
+
+trait QueryBuilderBindable {
+    public function resolveRouteBinding($value, $field = null) {
+        return (new $this::$queryClass())
+            ->where($field ?? $this->getRouteKeyName(), $value)
+            ->first();
+    }
+}
+```
+
+This results in less eager loading of variables that are expected from the api endpoints as it allows the api request itself to define which models it wants to load via query params
+
+```
+/api/posts/1?include=comments
+```
+
+### 2. Request Structure
+
+Combine store/update requests into single file:
+
+```php
+<?php
+
+namespace App\Http\Requests;
+
+use App\Traits\HandlesPatchRequests;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+class PostRequest extends FormRequest {
+    use HandlesPatchRequests;
+
+    public function authorize(): bool {
+        return true; // Authorization handled by Policy
+    }
+
+    public function rules(): array {
+        $arr = [
+            "title" => "required|string|max:255",
+            "content" => "required|string",
+            "status" => [Rule::enum(PostStatusEnum::class)]
+        ];
+
+        // Handle PATCH requests (make fields optional)
+        if ($this->isMethod("patch")) {
+            $arr = $this->handlePatchRequest($arr);
+        }
+
+        return $arr;
+    }
+}
+```
+
+**Key conventions:**
+
+- Extend `FormRequest` directly (not BaseFormRequest)
+- Include `HandlesPatchRequests` trait
+- Set `authorize()` to `true` (policies handle authorization)
+- Use `handlePatchRequest()` for PATCH method validation
+- Use `Rule::enum()` for enum validation
+
+### 3. Controller Structure
+
+```php
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Http\Requests\PostRequest;
+use App\Http\Resources\PostResource;
+use App\Models\Post;
+
+class PostController extends Controller {
+    public function __construct() {
+        $this->authorizeResource(Post::class, "post");
+    }
+
+    public function index() {
+        return PostResource::collection(
+            (new Post::$queryClass())
+                ->paginate(request("per_page", 10))
+                ->appends(request()->query())
+        );
+    }
+
+    public function store(PostRequest $request) {
+        $post = Post::create($request->validated());
+
+        return (new PostResource($post))->response()->setStatusCode(201);
+    }
+
+    public function show(Post $post) {
+        return new PostResource($post);
+    }
+
+    public function update(PostRequest $request, Post $post) {
+        $post->update($request->validated());
+
+        return new PostResource($post);
+    }
+
+    public function destroy(Post $post) {
+        $post->delete();
+
+        return response()->json(null, 204);
+    }
+}
+```
+
+**Key conventions:**
+
+- Use `authorizeResource()` in constructor
+- Use model's `$queryClass` for queries
+- Use `request('per_page', 10)` for pagination
+- Append query parameters with `appends(request()->query())`
+- Return 201 status for store, 204 for destroy
+- Use resource classes for all responses
+
+### 4. Resource Structure
+
+```php
+<?php
 
-## Common Command Patterns
+namespace App\Http\Resources;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+class PostResource extends JsonResource {
+    public function toArray(Request $request): array {
+        return [
+            "id" => $this->id,
+            "title" => $this->title,
+            "content" => $this->content,
+            "status" => new EnumResource($this->status),
+            "created_at" => $this->created_at,
+            "updated_at" => $this->updated_at,
+
+            // Conditional includes
+            "author" => UserResource::collection($this->whenLoaded("author"))
+        ];
+    }
+}
+```
+
+**Key conventions:**
+
+- Use `EnumResource` for enum fields
+- Use `whenLoaded()` for relationship includes
+- Return raw data without additional wrapping
+
+### 5. Query Builder Class
+
+```php
+<?php
+
+namespace App\Http\Queries;
+
+use App\Models\Post;
+use Spatie\QueryBuilder\QueryBuilder;
+use Spatie\QueryBuilder\AllowedFilter;
+use Spatie\QueryBuilder\AllowedInclude;
+
+class PostQuery extends QueryBuilder {
+    public function __construct($query = null) {
+        parent::__construct($query ?: Post::query());
+
+        $this->defaultSort("id");
+
+        $this->allowedSorts([
+            "id",
+            "title",
+            "status",
+            "created_at",
+            "updated_at"
+        ]);
+
+        $this->allowedIncludes(["author", "comments"]);
+
+        $this->allowedFilters([
+            AllowedFilter::exact("id"),
+            AllowedFilter::exact("status"),
+            AllowedFilter::partial("title")
+        ]);
+    }
+}
+```
+
+**Key conventions:**
+
+- Extend Spatie `QueryBuilder`
+- Set `defaultSort('id')`
+- Define `allowedSorts`, `allowedIncludes`, and `allowedFilters`
+- Use `AllowedFilter::exact()` and `AllowedFilter::partial()` as appropriate
+
+### 6. Observer Structure
+
+```php
+<?php
+
+namespace App\Observers;
+
+use App\Models\Post;
+use App\Traits\ObservesAuthorChanges;
+use App\Enums\AuthorChangeEventTypeEnum;
+
+class PostObserver {
+    use ObservesAuthorChanges;
+
+    public function created(Post $post): void {
+        if (auth()->user()) {
+            $this->observeChanges(
+                $post,
+                auth()->user(),
+                AuthorChangeEventTypeEnum::CREATED
+            );
+        }
+    }
+
+    public function updated(Post $post): void {
+        if (auth()->user()) {
+            $this->observeChanges(
+                $post,
+                auth()->user(),
+                AuthorChangeEventTypeEnum::UPDATED
+            );
+        }
+    }
+
+    public function deleted(Post $post): void {
+        if (auth()->user()) {
+            $this->observeChanges(
+                $post,
+                auth()->user(),
+                AuthorChangeEventTypeEnum::DELETED
+            );
+        }
+    }
+}
+```
+
+**Key conventions:**
+
+- Use `ObservesAuthorChanges` trait
+- Check for `auth()->user()` before observing
+- Use `AuthorChangeEventTypeEnum` for event types
+
+### 7. Policy Structure
+
+```php
+<?php
+
+namespace App\Policies;
+
+use App\Models\Post;
+use App\Models\User;
+use App\Traits\PerformsSubscriptionChecks;
+
+class PostPolicy {
+    use PerformsSubscriptionChecks;
+
+    public function viewAny(User $user): bool {
+        return $user->can(PermissionEnum::VIEW_CONTENT->value);
+    }
+
+    public function view(User $user, Post $post): bool {
+        return $user->can(PermissionEnum::VIEW_CONTENT->value);
+    }
+
+    public function create(User $user): bool {
+        return $user->can(PermissionEnum::CREATE_CONTENT->value);
+    }
+
+    public function update(User $user, Post $post): bool {
+        return $user->can(PermissionEnum::EDIT_CONTENT->value);
+    }
+
+    public function delete(User $user, Post $post): bool {
+        return $user->can(PermissionEnum::DELETE_CONTENT->value);
+    }
+}
+```
+
+**Key conventions:**
+
+- Use `PerformsSubscriptionChecks` trait where applicable
+- Use permission enums for authorization checks
+- Follow standard policy method names
+
+### 8. Test Structure
+
+```php
+<?php
+
+namespace Tests\Feature;
+
+use App\Http\Resources\PostResource;
+use App\Models\Post;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\Feature\Traits\Resource;
+use Tests\TestCase;
+
+class PostTest extends TestCase {
+    use RefreshDatabase, Resource;
+
+    public $endpoint = "/api/posts";
+    public $model = Post::class;
+    public $resourceClass = PostResource::class;
+
+    public $invalidInput = [
+        "title" => null
+    ];
+
+    public $invalidRequiredInput = [
+        "title" => null
+    ];
+}
+```
+
+**Key conventions:**
+
+- Use `RefreshDatabase` and `Resource` traits
+- Set `$endpoint`, `$model`, and `$resourceClass` properties
+- Define `$invalidInput` and `$invalidRequiredInput` arrays
+
+### 9. Factory Structure
+
+```php
+<?php
+
+namespace Database\Factories;
+
+use App\Enums\PostStatusEnum;
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+class PostFactory extends Factory {
+    public function definition(): array {
+        return [
+            "title" => fake()->sentence(),
+            "content" => fake()->paragraphs(3, true),
+            "status" => $this->faker->randomElement(PostStatusEnum::cases())
+        ];
+    }
+}
+```
+
+**Key conventions:**
+
+- Use `fake()` helper for data generation
+- Use `randomElement()` with enum cases for enum fields
+- Keep factories simple and focused
+
+## Route Registration
+
+Add API resource routes in `routes/api.php`:
+
+```php
+Route::middleware(["auth:sanctum"])->group(function () {
+    Route::apiResource("posts", \App\Http\Controllers\PostController::class);
+});
+```
+
+## Migration Best Practices
+
+- Never access models in migrations
+- Use DB facade directly for data manipulation
+- Follow standard Laravel migration conventions
+- Use descriptive migration names
+
+## Critical Notes
+
+- **All Laravel/PHP operations must use `fw` prefix** (e.g., `fw artisan`, `fw composer`)
+- **Model names should be Capital case and singular** (e.g., Post, Comment, Media)
+- **Observers are registered using attributes, not service providers**
+- **All API endpoints should be protected with `auth:sanctum` middleware**
+- **Policies handle authorization, not request authorize() methods**
+- **Enums should be created when needed, not by default**
+- **Seeders are required for all models**
+
+## Laravel Command Patterns
 
 ### Composer Operations
 
@@ -107,24 +565,24 @@ fw artisan tinker
 - **Environment**: Use [`.env.example`](.env.example) as reference for environment variables
 - **Frontend**: Resources in [`resources/`](resources/) directory with build system using npm scripts
 
-## Environment Variables
+## Laravel Environment Configuration
 
-Reference the [`.env.example`](.env.example) file for available environment variables:
+Reference the [`.env.example`](.env.example) file for Laravel-specific environment variables:
 
 - Database connection uses `mysql` service
 - Redis connection uses `redis` service
 - Mail testing uses `mailhog` service
 - App URL defaults to `http://localhost:3000`
 
-## Build System
+## Laravel Build System
 
 - Frontend assets managed via npm scripts defined in [`package.json`](package.json)
-- Uses `@fishawack/core` build system
-- Run `npm run start` for development
-- Run `npm run production` for production builds
-- Files typically found in public/ directory are stored in resources/ and copied over during the build process, this allows public to be gitignored as a whole
+- Uses `@fishawack/core` build system optimized for Laravel
+- Run `fw npm run start` for development
+- Run `fw npm run production` for production builds
+- Public directory gitignored - assets copied from resources/ during build
 
-## Key Configuration Notes
+## Laravel Configuration Notes
 
 - Application uses Laravel 12
 - PHP 8+ requirement
@@ -133,30 +591,21 @@ Reference the [`.env.example`](.env.example) file for available environment vari
 - Queue: Sync driver (no queue worker needed for development)
 - Storage: Local disk with public disk for uploads
 
-## When Suggesting Code Changes
-
-1. Always assume containerized environment
-2. Prefix ALL PHP/Composer/Artisan commands with `fw`
-3. Reference existing configuration patterns from the [`config/`](config/) directory
-4. Follow Laravel conventions and use existing service providers
-5. Consider the build system when suggesting frontend changes
-
-## Testing Guidelines
+## Laravel Testing Guidelines
 
 - Unit tests go in [`tests/Unit/`](tests/Unit/)
 - Feature tests go in [`tests/Feature/`](tests/Feature/)
 - Use the existing [`phpunit.xml`](phpunit.xml) configuration
 - Run tests via `fw artisan test`
 
-## Container Orchestration Manager (`fw`)
-
-The `fw` command is our container orchestration manager that:
+## Laravel Code Suggestions
 
-- Manages all Docker container operations
-- Provides direct access to PHP, Composer, and Artisan within containers
-- Handles database connections and other services
-- Should be used for ALL Laravel/PHP related commands
+When suggesting code changes:
 
-**CRITICAL**: Never suggest direct `php`, `composer`, or `artisan` commands. Always prefix with `fw`.
+1. Always use containerized commands with `fw` prefix
+2. Reference existing configuration patterns from the [`config/`](config/) directory
+3. Follow Laravel 12 conventions and use existing service providers
+4. Consider the build system when suggesting frontend changes
+5. Use Laravel's built-in features and helpers where possible
 
-Remember: This is a containerized Laravel application - all PHP operations must go through the `fw` container orchestration manager.
+**CRITICAL**: All Laravel/PHP operations must use the `fw` container orchestration manager. Never suggest direct `php`, `composer`, or `artisan` commands.

package/_Ai/python-3.md

@@ -0,0 +1,42 @@
+---
+applyTo: "src/**/*"
+---
+
+# GitHub Copilot Instructions for Python Project
+
+## Project Overview
+
+This is a Python application that runs entirely in the host machine. All Python and pip operations must be executed within the appropriate environment using `venv`, `pip` and `python` for the python executable.
+
+## Project Management
+
+- The codebase follows a standard Python project structure.
+- Virtual environments are used to manage dependencies.
+- Always run python and pip from the virtual environment directly (`./venv/bin/python` and `./venv/bin/pip`)
+- The project runs on Python 3.13 or higher.
+- The project must always use the `python-dotenv` package to load environment variables from a `.env` file.
+- All dependencies are listed in the `requirements.txt` file.
+- The project uses FastAPI and Uvicorn for the web server. Upon running the project, it will be accessible at `http://localhost:3000` and it'll keep running as long as the process is active. For easier development, pipe the output to a log file.
+- The project must always try to stay stateless and handle requests with in-memory processing whenever possible.
+- The project must always fail gracefully and return appropriate error messages.
+
+## Common Command Patterns
+
+### Run Project
+
+```bash
+# Update dependencies
+pip install -r ./src/requirements.txt
+
+# Add new package
+pip install package/name
+
+# Run project
+python ./src/main.py
+```
+
+## Project Structure Context
+
+- **Main application**: The main entry point is `./src/main.py`
+- **Routes**: API routes are defined in `./src/routes/*.py`
+- **Connectors**: LLM Connectors are defined in `./src/connectors/*.py`