@fishawack/lab-env 4.45.0-beta.2 → 4.45.0-beta.3

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 ## Changelog
 
+### 4.45.0-beta.3 (2025-09-02)
+
+#### Features
+
+* added workspace command ([a6ad364](https://bitbucket.org/fishawackdigital/lab-env/commits/a6ad364d8846e34394318d4f908b0b2b769ea9ee))
+* allow users to pass name and error if already exists ([071d836](https://bitbucket.org/fishawackdigital/lab-env/commits/071d836402cbc595496054fcb3e6d99798f2ff67))
+* copy ai file now has cwd param ([e91f2a5](https://bitbucket.org/fishawackdigital/lab-env/commits/e91f2a53243b8fb424f2ab0abba0946cfefadbb7))
+* implement ui framework ai file ([17a7bda](https://bitbucket.org/fishawackdigital/lab-env/commits/17a7bda861bd14cb67e11e92079de809853ef242))
+* workspace command now creates a workspace ai file and mcp file ([271f9b4](https://bitbucket.org/fishawackdigital/lab-env/commits/271f9b4677a58f41e428a9d2fb95d90be9319d23))
+* workspace now creats workspace and opens ([fb40e8b](https://bitbucket.org/fishawackdigital/lab-env/commits/fb40e8bcb34669c5858ed4877218c0c8ca32a3ff))
+
+#### Bug Fixes
+
+* use @ instead of * in wildcard insructions files ([2176ad8](https://bitbucket.org/fishawackdigital/lab-env/commits/2176ad8cf6702c5ca52eccbee5637bfc9bf0bdbb))
+
 ### 4.45.0-beta.2 (2025-09-01)
 
 #### Features

package/_Ai/lab-env-@.md

@@ -0,0 +1,402 @@
+---
+applyTo: "**/*"
+---
+
+# GitHub Copilot Instructions for Lab-Env Containerized Projects
+
+## Project Overview
+
+This project uses the `@fishawack/lab-env` container orchestration system - a command-line utility that spins up and manages framework-specific Docker containers for consistent development and production environments. All development operations run entirely in Docker containers managed by the `fw` command-line tool.
+
+## Prerequisites & System Requirements
+
+Before using this containerized environment, ensure your system meets these requirements:
+
+- **Node.js**: Version 22 or higher
+- **npm**: Latest version
+- **Docker Desktop**: Latest version
+
+**Critical Setup Step**: Run `fw diagnose` to validate your environment is configured correctly before starting development.
+
+## Quick Start & Validation
+
+```bash
+# 1. Validate environment setup
+fw diagnose
+
+# 2. Install project dependencies
+fw install
+
+# 3. Start development environment
+fw start
+
+# 4. Verify containers are running correctly
+fw config
+```
+
+## Container Architecture
+
+### Core Container (Always Present)
+
+Regardless of framework, every project includes a **core container** that:
+
+- **Bundles frontend assets** using the `@fishawack/core` build system
+- **Handles deployments** to various environments
+- **Manages Node.js operations** and npm scripts
+- **Provides development tools** and utilities
+- **Serves as the primary interface** for development workflows
+
+The core container runs on ports:
+
+- `3000`: Main development server
+- `3001`: Optional secondary port for tools/debugging
+
+### Framework-Specific Container Configurations
+
+#### Laravel 10 (Latest)
+
+```yaml
+services:
+    core: # Frontend builds, deployments, Node.js
+    mysql: # Database (MySQL 8.0.32)
+    nginx: # Web server
+    php: # PHP-FPM application server
+    redis: # Caching and sessions
+    elasticsearch: # Search engine (v8.8.1)
+```
+
+**Ports**: Web: 8000, Database: 3306, Elasticsearch: 9200
+
+#### WordPress 1 (Latest)
+
+```yaml
+services:
+    core: # Frontend builds, deployments, Node.js
+    mysql: # Database (MySQL 8.0.32)
+    apache: # Web server with PHP
+    php: # PHP-FPM for additional processing
+```
+
+**Ports**: Web: 8000, Database: 3306
+
+#### Drupal 9 (Latest)
+
+```yaml
+services:
+    core: # Frontend builds, deployments, Node.js
+    mysql: # Database (MySQL 8.0.32)
+    apache: # Web server with PHP
+    php: # PHP-FPM application server
+```
+
+**Ports**: Web: 8000, Database: 3306
+
+### Volume Management
+
+Each framework manages persistent data through Docker volumes:
+
+- **node_modules**: Shared Node.js dependencies (core)
+- **vendor**: PHP Composer dependencies (PHP frameworks)
+- **mysql**: Database storage (all frameworks with DB)
+- **redis**: Cache storage (Laravel)
+- **elasticsearch**: Search index storage (Laravel)
+- **wordpress**: WordPress core files (WordPress)
+- **drupal**: Drupal core files (Drupal)
+
+## Container Orchestration Manager (`fw`)
+
+The `fw` command is our container orchestration manager that:
+
+- Manages all Docker container operations
+- Provides direct access to services within containers
+- Handles database connections and other services
+- Should be used for ALL development commands
+
+## General Container Management
+
+- **All commands run in containers** - never suggest direct execution on host
+- Use the `fw` orchestration manager to execute all commands within containers
+- The project uses Docker with various services depending on platform (nginx, apache, mysql, redis, etc.)
+
+## Common Command Patterns
+
+### Container Operations
+
+```bash
+# Start the development environment
+fw start
+
+# Stop the development environment
+fw clean
+
+# Restart services
+fw restart
+
+# Clean rebuild
+fw rebuild
+
+# Access container shell
+fw connect [service]
+
+# Execute commands in containers
+fw execute [command]
+
+# View docker configuration
+fw config
+
+# Docker compose operations
+fw up
+fw down
+fw build
+
+# Container management
+fw volumes
+fw compose [command]
+```
+
+### PHP Commands (when applicable)
+
+```bash
+# Run any PHP script
+fw php script.php
+
+# Check PHP version
+fw php -v
+
+# Run PHP commands
+fw php [command]
+```
+
+### Database Operations
+
+```bash
+# Access MySQL console (when applicable)
+fw mysql
+
+# Run database imports/exports
+fw mysql < backup.sql
+
+# Framework-specific database commands
+fw artisan migrate     # Laravel
+fw drush sql-cli       # Drupal
+fw wp db query         # WordPress
+```
+
+### Node.js/NPM Commands
+
+```bash
+# Install npm dependencies
+fw npm install
+
+# Run npm scripts
+fw npm run [script]
+
+# Run development build
+fw npm run start
+
+# Run production build
+fw npm run production
+```
+
+### Development Workflow
+
+```bash
+# Initialize new project
+fw create [type] [name]
+
+# Install dependencies
+fw install
+
+# Start development environment
+fw start
+
+# Watch for changes
+fw watch
+
+# Run tests
+fw test
+
+# Check project health
+fw check
+
+# Deploy to production
+fw deploy
+
+# Production build
+fw production
+
+# Regenerate configurations
+fw regenerate
+
+# Complete reinstall
+fw reinstall
+
+# Nuclear clean (remove everything)
+fw nuke
+```
+
+## Build System Integration
+
+- Frontend assets managed via npm scripts defined in `package.json`
+- Uses `@fishawack/core` build system when applicable
+- Files typically found in public/ directory are stored in resources/ and copied over during the build process
+- Public directories are often gitignored as they contain generated assets
+
+## Environment Setup
+
+- Environment variables managed through `.env` files
+- Use `.env.example` as reference for available variables
+- Database and service connections use container service names (never `localhost`)
+- Default ports managed automatically by the orchestration system
+- **Volume Management**: Dependencies (`vendor/`, `node_modules/`) are stored in Docker volumes, not local directories
+
+## Project File Structure Context
+
+### Configuration Files
+
+- `.env` / `.env.example`: Environment configuration
+- `package.json`: Frontend dependencies and build scripts
+- `composer.json`: PHP dependencies (for PHP frameworks)
+- `docker-compose.yml`: Local Docker overrides (if present in `_Docker/`)
+
+### Key Directories
+
+- `resources/`: Source files for frontend assets (compiled to `public/`)
+- `public/`: Generated assets directory (usually gitignored)
+- `_Build/`: Build system configuration and outputs
+- `_Docker/`: Local Docker configuration overrides
+
+### Build System Files
+
+- Uses `@fishawack/core` for frontend asset compilation
+- Public directories contain generated files, not source code
+- Always edit source files in `resources/`, never directly in `public/`
+
+## Key Principles & Best Practices
+
+1. **Always assume containerized environment** - no direct host commands
+2. **Prefix ALL commands with `fw`** unless explicitly running host-level operations
+3. **Use service names for connections** (e.g., `mysql`, `redis`, not `localhost`)
+4. **Leverage the build system** for asset compilation and optimization
+5. **Follow containerized development patterns** - everything runs in containers
+6. **Validate with `fw diagnose`** before reporting issues
+7. **Use `--debug` flag** for detailed error information when troubleshooting
+8. **Understand volume management** - dependencies live in Docker volumes, not local folders
+
+## Build & Deployment Validation
+
+### Pre-Development Checklist
+
+```bash
+fw diagnose              # Validate environment setup
+fw install               # Install dependencies
+fw start                 # Start development environment
+fw test                  # Run test suite (if applicable)
+```
+
+### Build Validation Steps
+
+```bash
+fw npm run start         # Development build
+fw npm run production    # Production build validation
+fw deploy                # Deploy to staging/production
+```
+
+### Health Checks
+
+- Core container should be accessible on port 3000
+- Web services should be accessible on port 8000 (framework dependent)
+- Database should be accessible on port 3306 (when applicable)
+- All containers should start without errors when running `fw start`
+
+## Service Access Patterns
+
+- **Database**: Access via `fw mysql` or connection string using service name
+- **Cache**: Redis connections use `redis` service name
+- **Mail**: Development mail testing via mailhog or similar
+- **Assets**: Static files served through appropriate web server container
+
+## Testing in Containers
+
+- All tests run within appropriate containers
+- Use `fw test` for running test suites
+- Test databases and services isolated within container network
+- No need for local service installations
+
+## Debugging and Development
+
+- Use `fw connect [service]` to access container shells
+- Log files accessible via `fw logs [service]`
+- Development tools run within containers
+- Hot reloading and file watching supported through container mounts
+
+**CRITICAL**: Never suggest direct execution of development commands on the host system. Always use the `fw` container orchestration manager for all project operations.
+
+Remember: This is a containerized development environment - all operations must go through the `fw` container orchestration system.
+
+## Common Issues & Troubleshooting
+
+### Volume Issues with Dependencies
+
+**Problem**: Linters and some packages expect `vendor/` or `node_modules/` to exist in the project directory, but these are managed as Docker volumes.
+
+**Solution**:
+
+- For linting issues: Configure your IDE/editor to use containerized linting via `fw lint`
+- For missing dependencies: Ensure you've run `fw install` and dependencies are installed in the container
+- If packages seem missing: Run `fw reinstall` to rebuild volumes
+
+### Docker Space Issues
+
+**Problem**: "No space left on device" errors during builds or installations.
+
+**Solution**:
+
+```bash
+# Check Docker space usage
+docker system df -v
+
+# Clean up Docker resources
+fw nuke  # For current project
+docker system prune --all --volumes -f  # For all Docker resources
+```
+
+### Container Mount Errors
+
+**Problem**: Permission denied or mount errors, especially with nginx configurations.
+
+**Solution**:
+
+- Ensure Node.js is installed via NVM rather than system installation
+- Check that your working directory case matches exactly (case-sensitive filesystems)
+- Run `fw diagnose` to check for common configuration issues
+
+### Database Connection Issues
+
+**Problem**: MySQL connection errors after changing `.env` database credentials.
+
+**Solution**:
+
+```bash
+# Rebuild database volumes with new credentials
+fw nuke
+fw setup
+```
+
+### Debugging Commands
+
+When encountering issues, use these diagnostic commands:
+
+```bash
+# Get detailed error information
+fw [command] --debug
+
+# Check Docker configuration
+fw config
+
+# Validate environment setup
+fw diagnose
+
+# Check container status
+fw up --debug
+```

package/_Ai/mcp-@.md

@@ -0,0 +1,15 @@
+---
+applyTo: "**/*"
+---
+
+# GitHub Copilot Instructions for MCP servers
+
+Playwright is available for live browser testing and interactions.
+
+Use this to automate browser tasks, run tests, and capture screenshots or videos of your application in action.
+
+Always verify changes to API & Frontend functionality visually via playwright.
+
+The api is typically already running at http://localhost:3000
+
+The frontend is typically already running at http://localhost:3002