@mytechtoday/augment-extensions 0.2.0 → 0.5.0

package/augment-extensions/coding-standards/php/rules/web-applications.md

@@ -0,0 +1,426 @@
+# PHP Web Applications Best Practices
+
+## Overview
+
+This guide provides best practices for developing PHP web applications using MVC architecture, modern frameworks (Laravel, Symfony), templating engines, and secure form handling.
+
+## MVC Architecture
+
+### Controllers
+
+**Keep controllers thin** - Controllers should delegate business logic to services.
+
+```php
+<?php
+
+namespace App\Controllers;
+
+use App\Services\UserService;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+class UserController
+{
+    public function __construct(
+        private UserService $userService
+    ) {}
+    
+    public function index(): Response
+    {
+        // Thin controller - delegates to service
+        $users = $this->userService->getAllUsers();
+        
+        return $this->render('users/index', [
+            'users' => $users
+        ]);
+    }
+    
+    public function store(Request $request): Response
+    {
+        // Validate and delegate
+        $validated = $this->validate($request, [
+            'name' => 'required|string|max:255',
+            'email' => 'required|email|unique:users'
+        ]);
+        
+        $user = $this->userService->createUser($validated);
+        
+        return $this->redirect('/users/' . $user->id);
+    }
+}
+```
+
+### Models
+
+**Models handle data logic** - Use Eloquent ORM or Doctrine for database interactions.
+
+```php
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+class User extends Model
+{
+    protected $fillable = ['name', 'email', 'password'];
+    
+    protected $hidden = ['password', 'remember_token'];
+    
+    protected $casts = [
+        'email_verified_at' => 'datetime',
+        'is_active' => 'boolean'
+    ];
+    
+    // Relationships
+    public function posts(): HasMany
+    {
+        return $this->hasMany(Post::class);
+    }
+    
+    // Accessors
+    public function getFullNameAttribute(): string
+    {
+        return "{$this->first_name} {$this->last_name}";
+    }
+    
+    // Scopes
+    public function scopeActive($query)
+    {
+        return $query->where('is_active', true);
+    }
+}
+```
+
+### Views
+
+**Minimal logic in views** - Use template engines with auto-escaping.
+
+```php
+<!-- Blade Template (Laravel) -->
+@extends('layouts.app')
+
+@section('content')
+    <h1>{{ $title }}</h1>
+    
+    @foreach($users as $user)
+        <div class="user-card">
+            <h2>{{ $user->name }}</h2>
+            <p>{{ $user->email }}</p>
+            
+            @if($user->is_active)
+                <span class="badge badge-success">Active</span>
+            @else
+                <span class="badge badge-danger">Inactive</span>
+            @endif
+        </div>
+    @endforeach
+@endsection
+```
+
+## Routing
+
+### RESTful Routes
+
+```php
+<?php
+
+use App\Controllers\UserController;
+use Illuminate\Support\Facades\Route;
+
+// RESTful resource routes
+Route::resource('users', UserController::class);
+
+// Generates:
+// GET    /users           -> index()
+// GET    /users/create    -> create()
+// POST   /users           -> store()
+// GET    /users/{id}      -> show()
+// GET    /users/{id}/edit -> edit()
+// PUT    /users/{id}      -> update()
+// DELETE /users/{id}      -> destroy()
+
+// Route model binding
+Route::get('/users/{user}', function (User $user) {
+    return view('users.show', ['user' => $user]);
+});
+
+// Route groups with middleware
+Route::middleware(['auth', 'verified'])->group(function () {
+    Route::get('/dashboard', [DashboardController::class, 'index']);
+    Route::resource('posts', PostController::class);
+});
+```
+
+## Template Engines
+
+### Twig (Symfony)
+
+```php
+<?php
+
+// Controller
+return $this->render('user/profile.html.twig', [
+    'user' => $user,
+    'posts' => $posts
+]);
+```
+
+```twig
+{# Template: user/profile.html.twig #}
+{% extends 'base.html.twig' %}
+
+{% block title %}{{ user.name }} - Profile{% endblock %}
+
+{% block content %}
+    <h1>{{ user.name }}</h1>
+    <p>{{ user.email }}</p>
+    
+    {# Auto-escaping enabled by default #}
+    <div>{{ user.bio }}</div>
+    
+    {# Raw output (use with caution) #}
+    <div>{{ user.html_content|raw }}</div>
+    
+    {# Loops #}
+    {% for post in posts %}
+        <article>
+            <h2>{{ post.title }}</h2>
+            <p>{{ post.excerpt }}</p>
+        </article>
+    {% endfor %}
+{% endblock %}
+```
+
+### Blade (Laravel)
+
+```php
+{{-- Template inheritance --}}
+@extends('layouts.app')
+
+@section('title', 'User Profile')
+
+@section('content')
+    <h1>{{ $user->name }}</h1>
+    
+    {{-- Components --}}
+    <x-alert type="success">
+        Profile updated successfully!
+    </x-alert>
+    
+    {{-- Directives --}}
+    @auth
+        <a href="/profile/edit">Edit Profile</a>
+    @endauth
+
+    @include('partials.user-stats', ['user' => $user])
+@endsection
+```
+
+## Form Handling
+
+### CSRF Protection
+
+**Always use CSRF tokens** for forms.
+
+```php
+<!-- Blade -->
+<form method="POST" action="/users">
+    @csrf
+    <input type="text" name="name" value="{{ old('name') }}">
+    <button type="submit">Submit</button>
+</form>
+
+<!-- Twig -->
+<form method="post" action="{{ path('user_create') }}">
+    <input type="hidden" name="_token" value="{{ csrf_token('user_create') }}">
+    <input type="text" name="name">
+    <button type="submit">Submit</button>
+</form>
+```
+
+### Form Validation
+
+**Use dedicated validation classes** (Form Requests in Laravel).
+
+```php
+<?php
+
+namespace App\Http\Requests;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class StoreUserRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return $this->user()->can('create', User::class);
+    }
+
+    public function rules(): array
+    {
+        return [
+            'name' => 'required|string|max:255',
+            'email' => 'required|email|unique:users,email',
+            'password' => 'required|min:8|confirmed',
+            'age' => 'nullable|integer|min:18|max:120',
+            'role' => 'required|in:user,admin,moderator'
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [
+            'name.required' => 'Please provide your name',
+            'email.unique' => 'This email is already registered',
+            'password.min' => 'Password must be at least 8 characters'
+        ];
+    }
+}
+
+// Controller usage
+public function store(StoreUserRequest $request)
+{
+    // Validation already passed
+    $validated = $request->validated();
+
+    $user = User::create($validated);
+
+    return redirect('/users')->with('success', 'User created!');
+}
+```
+
+### Displaying Validation Errors
+
+```php
+<!-- Blade -->
+@if ($errors->any())
+    <div class="alert alert-danger">
+        <ul>
+            @foreach ($errors->all() as $error)
+                <li>{{ $error }}</li>
+            @endforeach
+        </ul>
+    </div>
+@endif
+
+<!-- Field-specific errors -->
+<input type="text" name="email" value="{{ old('email') }}"
+       class="@error('email') is-invalid @enderror">
+@error('email')
+    <span class="error">{{ $message }}</span>
+@enderror
+```
+
+## Middleware
+
+### Creating Middleware
+
+```php
+<?php
+
+namespace App\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+
+class CheckUserRole
+{
+    public function handle(Request $request, Closure $next, string $role)
+    {
+        if (!$request->user() || !$request->user()->hasRole($role)) {
+            abort(403, 'Unauthorized action.');
+        }
+
+        return $next($request);
+    }
+}
+
+// Usage in routes
+Route::middleware(['auth', 'role:admin'])->group(function () {
+    Route::get('/admin/dashboard', [AdminController::class, 'index']);
+});
+```
+
+## Session Management
+
+### Using Sessions
+
+```php
+<?php
+
+// Store data
+session(['key' => 'value']);
+$request->session()->put('user_id', $user->id);
+
+// Retrieve data
+$value = session('key');
+$userId = $request->session()->get('user_id');
+
+// Flash data (available for next request only)
+$request->session()->flash('status', 'Task was successful!');
+
+// Regenerate session ID (after login)
+$request->session()->regenerate();
+
+// Destroy session (logout)
+$request->session()->invalidate();
+```
+
+## Best Practices
+
+### ✅ DO
+
+- Use route model binding for automatic model injection
+- Implement middleware for cross-cutting concerns (auth, logging, CORS)
+- Use service classes for complex business logic
+- Leverage dependency injection for testability
+- Use database migrations for schema management
+- Implement proper error handling and logging
+- Use environment variables for configuration
+- Enable HTTPS in production
+- Implement rate limiting for public endpoints
+- Use queues for long-running tasks
+
+### ❌ DON'T
+
+- Put business logic in controllers or views
+- Use raw SQL queries without parameter binding
+- Store sensitive data in sessions without encryption
+- Disable CSRF protection
+- Use `extract()` on user input
+- Echo user input without escaping
+- Use `eval()` or similar dangerous functions
+- Hardcode credentials or API keys
+- Ignore validation errors
+- Use global variables for state management
+
+## Security Checklist
+
+- [ ] CSRF tokens on all forms
+- [ ] Input validation on all user data
+- [ ] Output escaping in all views
+- [ ] Prepared statements for database queries
+- [ ] HTTPS enforced in production
+- [ ] Secure session configuration (httponly, secure flags)
+- [ ] Password hashing with bcrypt/argon2
+- [ ] Rate limiting on authentication endpoints
+- [ ] SQL injection prevention
+- [ ] XSS prevention
+- [ ] File upload validation
+- [ ] Proper error handling (don't expose stack traces)
+
+## Performance Tips
+
+- Use eager loading to avoid N+1 queries
+- Implement caching for frequently accessed data
+- Use database indexes on frequently queried columns
+- Optimize images and assets
+- Enable OPcache in production
+- Use CDN for static assets
+- Implement database query logging in development
+- Use pagination for large datasets
+- Minimize middleware stack
+- Use lazy loading for heavy resources
+

package/augment-extensions/coding-standards/powershell/README.md

@@ -0,0 +1,154 @@
+# PowerShell Coding Standards
+
+Comprehensive PowerShell coding standards for professional, maintainable, and secure PowerShell code.
+
+## Overview
+
+This module provides AI-driven guidance for writing PowerShell code across diverse project types including automation scripts, modules, DSC configurations, cloud orchestration, administrative tools, cross-platform scripts, and legacy migrations.
+
+## Installation
+
+### With CLI (Future)
+```bash
+augx link coding-standards/powershell
+```
+
+### Without CLI (Current)
+Copy the contents of this module to your project's `.augment/` folder or reference it directly from this repository.
+
+## Key Features
+
+- **Universal Standards**: Naming conventions, error handling, security practices
+- **Category-Specific Rules**: Tailored guidance for 7 PowerShell project types
+- **Code Examples**: Working examples demonstrating best practices
+- **Configuration System**: Project-specific category selection
+- **PSScriptAnalyzer Integration**: Static analysis compliance
+- **Pester Testing**: Comprehensive testing guidelines
+
+## Directory Structure
+
+```
+augment-extensions/coding-standards/powershell/
+├── module.json                          # Module metadata
+├── README.md                            # This file
+├── rules/
+│   ├── universal-standards.md          # Cross-cutting standards
+│   ├── naming-conventions.md           # Verb-Noun, PascalCase
+│   ├── error-handling.md               # Try-Catch-Finally patterns
+│   ├── security-practices.md           # Credential handling, signing
+│   ├── performance-optimization.md     # Pipeline efficiency
+│   ├── testing-guidelines.md           # Pester integration
+│   ├── configuration-schema.md         # Configuration file schema
+│   ├── automation-scripts.md           # Category: Automation
+│   ├── modules-functions.md            # Category: Modules
+│   ├── dsc-configurations.md           # Category: DSC
+│   ├── cloud-orchestration.md          # Category: Cloud
+│   ├── administrative-tools.md         # Category: Admin
+│   ├── cross-platform-scripts.md       # Category: Cross-platform
+│   └── legacy-migrations.md            # Category: Legacy
+└── examples/
+    ├── automation-example.ps1
+    ├── module-example.psm1
+    ├── dsc-example.ps1
+    ├── cloud-example.ps1
+    ├── admin-example.ps1
+    ├── cross-platform-example.ps1
+    └── legacy-migration-example.ps1
+```
+
+## Core Guidelines
+
+### Naming Conventions
+- **Functions**: Verb-Noun format (e.g., `Get-UserData`, `Set-Configuration`)
+- **Parameters**: PascalCase (e.g., `$UserName`, `$FilePath`)
+- **Variables**: camelCase or PascalCase (consistent within project)
+- **Approved Verbs**: Use `Get-Verb` to see approved verbs
+
+### Error Handling
+```powershell
+try {
+    # Code that might fail
+    Get-Item -Path $Path -ErrorAction Stop
+}
+catch [System.IO.FileNotFoundException] {
+    Write-Error "File not found: $Path"
+}
+finally {
+    # Cleanup code
+}
+```
+
+### Security Practices
+- Use `PSCredential` objects for credentials
+- Never store plain-text passwords
+- Sign scripts for production
+- Validate and sanitize all input
+
+### Performance
+- Use pipeline efficiently
+- Avoid unnecessary loops
+- Use `-Filter` instead of `Where-Object` when possible
+- Measure performance with `Measure-Command`
+
+## Project Categories
+
+### 1. Automation Scripts
+Task automation, scheduled tasks, output formatting
+
+### 2. Modules and Functions
+CmdletBinding, parameter sets, SupportsShouldProcess
+
+### 3. DSC Configurations
+Declarative scripting, configuration data separation
+
+### 4. Cloud Orchestration
+Azure/AWS cmdlets, ARM/Bicep integration
+
+### 5. Administrative Tools
+Active Directory, Exchange, SQL management
+
+### 6. Cross-Platform Scripts
+OS-agnostic code, path handling
+
+### 7. Legacy Migrations
+Windows PowerShell → PowerShell Core
+
+## Configuration
+
+Create `.augment/powershell-config.json`:
+
+```json
+{
+  "powershell_categories": ["automation", "modules"],
+  "powershell_version": "7.4",
+  "strict_mode": true,
+  "static_analysis": {
+    "tool": "PSScriptAnalyzer",
+    "severity": "Warning"
+  },
+  "testing": {
+    "framework": "Pester",
+    "version": "5.x"
+  }
+}
+```
+
+## Character Count
+
+**Total**: ~162,000 characters
+
+## Contents
+
+- **6 Universal Rule Files**: Standards applying to all PowerShell projects
+- **1 Configuration Schema**: .augment/powershell-config.json schema documentation
+- **7 Category-Specific Rule Files**: Detailed guidance for each project type
+- **7 Code Examples**: Working examples for each category
+
+## Usage
+
+The AI agent will automatically apply these standards when working with PowerShell files (*.ps1, *.psm1, *.psd1). Configure your project categories in `.augment/powershell-config.json` to load only relevant rules.
+
+## Version
+
+**1.0.0** - Initial release
+