@famgia/omnify-ai-guides 2.0.15

package/dist/knowledge/laravel/datetime.md.stub

@@ -0,0 +1,334 @@
+# DateTime Handling Guide
+
+> **Related:** [README](./README.md) | [Resource Guide](./resource-guide.md)
+
+## Golden Rule: "Store UTC, Respond UTC, Accept UTC"
+
+```
+Database (UTC) ← Carbon (UTC) → API Response (ISO 8601 UTC)
+                     ↑
+              API Request (UTC)
+```
+
+---
+
+## Configuration
+
+### 1. Set Application Timezone to UTC
+
+**`config/app.php`:**
+
+```php
+'timezone' => 'UTC',
+```
+
+> ⚠️ NEVER change this to local timezone. Always use UTC.
+
+### 2. Database Timezone
+
+**MySQL** - Ensure UTC:
+
+```sql
+SET GLOBAL time_zone = '+00:00';
+SET time_zone = '+00:00';
+```
+
+Or in `my.cnf`:
+```ini
+[mysqld]
+default-time-zone = '+00:00'
+```
+
+---
+
+## Carbon Usage Rules
+
+### Always Use Carbon (Never raw DateTime)
+
+```php
+use Illuminate\Support\Carbon;
+
+// ✅ Correct
+$now = Carbon::now();           // Current UTC time
+$date = Carbon::parse($input);  // Parse with UTC
+
+// ❌ Wrong
+$now = new \DateTime();         // Don't use raw DateTime
+$now = date('Y-m-d H:i:s');     // Don't use date()
+```
+
+### API Response Format
+
+**Always return ISO 8601 with Z suffix:**
+
+```php
+// In Model - cast dates properly
+protected $casts = [
+    'email_verified_at' => 'datetime',
+    'scheduled_at' => 'datetime',
+    'created_at' => 'datetime',
+    'updated_at' => 'datetime',
+];
+
+// In Resource - format as ISO 8601 UTC
+public function toArray($request): array
+{
+    return [
+        'id' => $this->id,
+        'title' => $this->title,
+        'scheduled_at' => $this->scheduled_at?->toISOString(),  // "2024-01-15T10:30:00.000000Z"
+        'created_at' => $this->created_at?->toISOString(),
+        'updated_at' => $this->updated_at?->toISOString(),
+    ];
+}
+```
+
+### Accepting Date Input
+
+```php
+// In FormRequest
+public function rules(): array
+{
+    return [
+        'scheduled_at' => ['required', 'date'],  // Accepts ISO 8601
+    ];
+}
+
+// In Controller - Carbon auto-parses UTC
+public function store(StoreEventRequest $request): JsonResponse
+{
+    $event = Event::create([
+        'title' => $request->title,
+        'scheduled_at' => Carbon::parse($request->scheduled_at),  // Already UTC
+    ]);
+
+    return new EventResource($event);
+}
+```
+
+---
+
+## Common Patterns
+
+### Compare Dates
+
+```php
+use Illuminate\Support\Carbon;
+
+// Current UTC time
+$now = Carbon::now();
+
+// Check if past
+if ($event->scheduled_at->isPast()) {
+    // Event has passed
+}
+
+// Check if within range
+$start = Carbon::parse($request->start_date);
+$end = Carbon::parse($request->end_date);
+
+Event::whereBetween('scheduled_at', [$start, $end])->get();
+```
+
+### Query by Date Range
+
+```php
+// Frontend sends UTC strings
+// "2024-01-01T00:00:00Z" to "2024-01-31T23:59:59Z"
+
+public function index(Request $request)
+{
+    $query = Event::query();
+
+    if ($request->filled('start_date')) {
+        $query->where('scheduled_at', '>=', Carbon::parse($request->start_date));
+    }
+
+    if ($request->filled('end_date')) {
+        $query->where('scheduled_at', '<=', Carbon::parse($request->end_date));
+    }
+
+    return EventResource::collection($query->paginate());
+}
+```
+
+### Display for Specific Timezone (if needed)
+
+```php
+// Only when generating reports for specific timezone
+$userTimezone = 'Asia/Tokyo';
+
+$localTime = $event->scheduled_at->setTimezone($userTimezone);
+// Keep original as UTC, create copy for display
+```
+
+---
+
+## Model Setup
+
+### Recommended Model Structure
+
+```php
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Support\Carbon;
+
+class Event extends Model
+{
+    protected $fillable = [
+        'title',
+        'scheduled_at',
+    ];
+
+    protected $casts = [
+        'scheduled_at' => 'datetime',
+    ];
+
+    // Accessor for formatted date (if needed internally)
+    public function getScheduledAtFormattedAttribute(): string
+    {
+        return $this->scheduled_at?->toISOString() ?? '';
+    }
+
+    // Scope for upcoming events
+    public function scopeUpcoming($query)
+    {
+        return $query->where('scheduled_at', '>', Carbon::now());
+    }
+
+    // Scope for past events
+    public function scopePast($query)
+    {
+        return $query->where('scheduled_at', '<', Carbon::now());
+    }
+}
+```
+
+### Resource Format
+
+```php
+<?php
+
+namespace App\Http\Resources;
+
+use Illuminate\Http\Resources\Json\JsonResource;
+
+class EventResource extends JsonResource
+{
+    public function toArray($request): array
+    {
+        return [
+            'id' => $this->id,
+            'title' => $this->title,
+            'scheduled_at' => $this->scheduled_at?->toISOString(),
+            'is_past' => $this->scheduled_at?->isPast() ?? false,
+            'created_at' => $this->created_at?->toISOString(),
+            'updated_at' => $this->updated_at?->toISOString(),
+        ];
+    }
+}
+```
+
+---
+
+## Migration Example
+
+```php
+Schema::create('events', function (Blueprint $table) {
+    $table->id();
+    $table->string('title');
+    $table->timestamp('scheduled_at');  // Use timestamp, not datetime
+    $table->timestamps();               // created_at, updated_at
+});
+```
+
+> **Note:** `timestamp` columns in MySQL are stored as UTC internally.
+
+---
+
+## Anti-Patterns ❌
+
+```php
+// ❌ DON'T: Set local timezone in config
+'timezone' => 'Asia/Tokyo',  // Wrong!
+
+// ❌ DON'T: Use raw PHP date functions
+$date = date('Y-m-d H:i:s');
+$date = new \DateTime();
+
+// ❌ DON'T: Return formatted local time in API
+return ['created_at' => $this->created_at->format('Y/m/d H:i')];
+
+// ❌ DON'T: Store timezone offset in database
+$event->scheduled_at = '2024-01-15 19:30:00+09:00';
+
+// ❌ DON'T: Convert to local timezone before storing
+$event->scheduled_at = Carbon::parse($input)->setTimezone('Asia/Tokyo');
+```
+
+## Correct Patterns ✅
+
+```php
+// ✅ DO: Keep UTC timezone
+'timezone' => 'UTC',
+
+// ✅ DO: Use Carbon everywhere
+$now = Carbon::now();
+$date = Carbon::parse($input);
+
+// ✅ DO: Return ISO 8601 UTC in API
+return ['created_at' => $this->created_at?->toISOString()];
+
+// ✅ DO: Store as UTC
+$event->scheduled_at = Carbon::parse($input);  // Input should be UTC from frontend
+```
+
+---
+
+## API Contract with Frontend
+
+| Direction      | Format        | Example                         |
+| -------------- | ------------- | ------------------------------- |
+| API → Frontend | ISO 8601 UTC  | `"2024-01-15T10:30:00.000000Z"` |
+| Frontend → API | ISO 8601 UTC  | `"2024-01-15T10:30:00.000Z"`    |
+| Database       | UTC Timestamp | `2024-01-15 10:30:00`           |
+
+---
+
+## Testing with Dates
+
+```php
+use Illuminate\Support\Carbon;
+
+public function test_creates_event_with_correct_date(): void
+{
+    Carbon::setTestNow('2024-01-15 10:00:00');  // Freeze time in UTC
+
+    $response = $this->postJson('/api/events', [
+        'title' => 'Test Event',
+        'scheduled_at' => '2024-01-20T15:00:00.000Z',
+    ]);
+
+    $response->assertCreated();
+    
+    $this->assertDatabaseHas('events', [
+        'title' => 'Test Event',
+        'scheduled_at' => '2024-01-20 15:00:00',  // Stored as UTC
+    ]);
+}
+```
+
+---
+
+## Checklist
+
+- [ ] `config/app.php` timezone is `UTC`
+- [ ] MySQL timezone is UTC
+- [ ] All models use `datetime` cast for date fields
+- [ ] All Resources return `->toISOString()` for dates
+- [ ] Never use raw `date()` or `DateTime` - always Carbon
+- [ ] Never convert to local timezone before storing
+- [ ] API documentation specifies UTC format

package/dist/knowledge/laravel/migrations-team.md.stub

@@ -0,0 +1,376 @@
+# Migration Team Workflow Guide
+
+> Best practices for managing database migrations in team development environments.
+
+## Overview
+
+Omnify follows **international standards** for database migration management:
+
+1. **Schema as Source of Truth** - YAML schemas define the database structure
+2. **Simple File Tracking** - Lock file tracks migrations for regeneration
+3. **CI Validation** - Automated checks ensure sync between schema and migrations
+4. **Git for Conflict Resolution** - Standard Git workflow handles merge conflicts
+
+## Migration Tracking System
+
+### Lock File Structure
+
+The `.omnify.lock` file tracks all generated migrations:
+
+```json
+{
+  "version": 2,
+  "migrations": [
+    {
+      "fileName": "2026_01_13_100000_create_users_table.php",
+      "timestamp": "2026_01_13_100000",
+      "tableName": "users",
+      "type": "create",
+      "generatedAt": "2026-01-13T10:00:00Z",
+      "schemas": ["User"],
+      "checksum": "sha256..."
+    }
+  ]
+}
+```
+
+### Key Fields
+
+| Field | Purpose |
+|-------|---------|
+| `fileName` | Full migration filename |
+| `timestamp` | Timestamp prefix for regeneration |
+| `tableName` | Table name for lookup |
+| `type` | Migration type (create/alter/drop/pivot) |
+| `checksum` | SHA-256 hash for integrity verification |
+
+## CI/CD Integration
+
+### GitHub Actions Example
+
+```yaml
+# .github/workflows/migration-check.yml
+name: Migration Check
+
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          
+      - name: Install dependencies
+        run: npm ci
+        
+      - name: Check migrations sync
+        run: npx omnify generate --check
+        
+      - name: Test migrations (optional)
+        run: |
+          php artisan migrate:fresh --force
+          php artisan migrate:status
+```
+
+### CI Check Mode
+
+```bash
+# Check if migrations are in sync (for CI)
+npx omnify generate --check
+
+# Exit codes:
+# 0 = All migrations in sync ✅
+# 1 = Schema changes detected or migration issues ❌
+```
+
+Output example:
+```
+Omnify v1.0.113 - Generating Outputs
+
+✔ Loading schemas from schemas
+✔ Validating schemas...
+✔ Checking for changes...
+
+CI Check Mode Results:
+  Schemas: 12
+  Tracked migrations: 15
+  Migrations on disk: 15
+  Schema changes: 0
+
+✅ All migrations in sync
+```
+
+## Team Development Workflow
+
+### Standard Workflow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  1. Edit YAML Schema                                        │
+│     schemas/module/Model.yaml                               │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  2. Generate Migrations                                     │
+│     npx omnify generate                                     │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  3. Commit Both                                             │
+│     git add schemas/ {{LARAVEL_ROOT}}database/migrations/ .omnify.lock      │
+│     git commit -m "feat: add phone field to User"           │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  4. CI Validates                                            │
+│     GitHub Actions runs: npx omnify generate --check        │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  5. Merge & Deploy                                          │
+│     php artisan migrate                                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Parallel Development
+
+When multiple developers work on different schemas:
+
+```
+Developer A                    Developer B
+    │                              │
+Edit User.yaml                Edit Product.yaml
+(add phone)                   (add sku)
+    │                              │
+omnify generate               omnify generate
+    │                              │
+Creates:                      Creates:
+alter_users_add_phone.php     alter_products_add_sku.php
+    │                              │
+    └──────────┬───────────────────┘
+               │
+          Git Merge
+               │
+    Both migrations exist ✅
+    (different tables, no conflict)
+```
+
+### Same Schema Conflict
+
+When multiple developers edit the SAME schema:
+
+```
+Developer A                    Developer B
+    │                              │
+Edit User.yaml                Edit User.yaml
+(add phone)                   (add address)
+    │                              │
+omnify generate               omnify generate
+    │                              │
+    └──────────┬───────────────────┘
+               │
+          Git Merge
+               │
+        ⚠️ YAML Conflict!
+               │
+    ┌──────────┴──────────┐
+    │                     │
+Resolve YAML            Keep both migrations
+(merge both fields)     (Laravel runs both)
+    │                     │
+    └──────────┬──────────┘
+               │
+           Result:
+    User.yaml has phone + address
+    Both migrations exist
+    Laravel runs in timestamp order ✅
+```
+
+## Handling Common Scenarios
+
+### Scenario 1: Accidentally Deleted Migration
+
+**Problem:** Migration file deleted but lock file still tracks it.
+
+**Detection:**
+```bash
+npx omnify generate
+
+⚠️  Migration file issues detected:
+  Missing files (1):
+    - 2026_01_13_100000_create_users_table.php
+```
+
+**Solutions:**
+```bash
+# Option 1: Restore from git
+git checkout -- {{LARAVEL_ROOT}}database/migrations/omnify/
+
+# Option 2: Reset and regenerate (destructive!)
+npx omnify reset --migrations
+npx omnify generate --force
+```
+
+### Scenario 2: Stale Migration from Old Branch
+
+**Problem:** Branch created 1 month ago, merged today with old timestamp.
+
+**Detection:**
+```bash
+npx omnify generate
+
+⚠️  Stale migrations detected (old timestamp, not in lock file):
+    - 2026_01_04_100000_add_phone_to_users_table.php
+  These may be from merged branches. Review before running migrate.
+```
+
+**Action:**
+1. Review the migration - is it independent or dependent?
+2. If independent: Keep as-is, Laravel runs in timestamp order
+3. If dependent: Consider renaming with new timestamp
+
+### Scenario 3: CI Fails with "Schema changes detected"
+
+**Problem:** Someone edited schema but forgot to run generate.
+
+**Detection:**
+```bash
+npx omnify generate --check
+
+❌ Schema changes detected - run "npx omnify generate" to update migrations
+```
+
+**Solution:**
+```bash
+# Locally
+npx omnify generate
+git add .
+git commit --amend  # or new commit
+git push --force    # or regular push
+```
+
+## Best Practices
+
+### DO ✅
+
+1. **Always commit schema + migrations together**
+   ```bash
+   git add schemas/ {{LARAVEL_ROOT}}database/migrations/omnify/ .omnify.lock
+   git commit -m "feat: add field to schema"
+   ```
+
+2. **Use CI to validate migrations**
+   ```bash
+   npx omnify generate --check
+   ```
+
+3. **Pull and migrate before starting new work**
+   ```bash
+   git pull
+   php artisan migrate
+   ```
+
+4. **Review stale migration warnings**
+   - Check dependencies before merging old branches
+
+### DON'T ❌
+
+1. **Don't manually edit migrations in `omnify/` folder**
+   - They will be overwritten!
+
+2. **Don't ignore CI failures**
+   - Always run `npx omnify generate` if CI fails
+
+3. **Don't commit migrations without schemas**
+   - Schema is source of truth
+
+4. **Don't skip stale warnings without review**
+   - Old timestamps might run before dependent migrations
+
+## Migration Validation
+
+### Check Commands
+
+```bash
+# Full check (for CI)
+npx omnify generate --check
+
+# Generate with stale warnings (default)
+npx omnify generate
+
+# Generate without stale warnings
+npx omnify generate --no-warn-stale
+
+# Force regenerate everything
+npx omnify generate --force
+```
+
+### Validation Checks
+
+| Check | Description | Exit Code |
+|-------|-------------|-----------|
+| Schema sync | Schema matches generated migrations | 1 if mismatch |
+| Missing files | Migration files exist on disk | 1 if missing |
+| Modified files | Files match stored checksum | Warning only |
+| Stale files | Old timestamp, not tracked | Warning only |
+
+## Troubleshooting
+
+### "Missing migration files"
+
+```bash
+# Check what's missing
+npx omnify generate --check
+
+# Restore from git
+git checkout -- {{LARAVEL_ROOT}}database/migrations/omnify/
+
+# Or reset completely
+npx omnify reset --migrations
+npx omnify generate --force
+```
+
+### "Checksum mismatch"
+
+Someone manually edited an auto-generated file.
+
+```bash
+# Option 1: Regenerate
+npx omnify generate --force
+
+# Option 2: Reset lock file entry
+# (manually edit .omnify.lock to remove the entry)
+```
+
+### "Stale migrations"
+
+Old branch merged with old timestamps.
+
+```bash
+# Usually safe to ignore if migrations are independent
+# But review the migration order:
+
+php artisan migrate:status
+# Check: Will the old migration run before something it depends on?
+```
+
+## Summary
+
+| Workflow Step | Command |
+|---------------|---------|
+| Edit schema | Edit `schemas/*.yaml` |
+| Generate | `npx omnify generate` |
+| Commit | `git add schemas/ {{LARAVEL_ROOT}}database/migrations/ .omnify.lock` |
+| CI Check | `npx omnify generate --check` |
+| Deploy | `php artisan migrate` |
+| Restore | `git checkout -- {{LARAVEL_ROOT}}database/migrations/omnify/` |
+| Reset | `npx omnify reset --migrations` |