@famgia/omnify-laravel 0.0.113 → 0.0.114

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@famgia/omnify-laravel",
-  "version": "0.0.113",
+  "version": "0.0.114",
   "description": "Laravel migration and TypeScript type generator for omnify-schema",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,9 +25,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@famgia/omnify-types": "0.0.102",
-    "@famgia/omnify-core": "0.0.104",
-    "@famgia/omnify-atlas": "0.0.98"
+    "@famgia/omnify-types": "0.0.103",
+    "@famgia/omnify-core": "0.0.105",
+    "@famgia/omnify-atlas": "0.0.99"
   },
   "scripts": {
     "build": "tsup",

package/stubs/ai-guides/cursor/laravel.mdc.stub

@@ -7,6 +7,7 @@ alwaysApply: false
 # Laravel Rules
 
 > **Documentation:** `.claude/guides/laravel/`
+> **Team Migration Guide:** `.claude/guides/laravel/migrations-team.md`
 > **Specific Rules:** See also `laravel-controller.mdc`, `laravel-resource.mdc`, `laravel-request.mdc`, `laravel-testing.mdc`, `migrations-workflow.mdc`, `omnify-migrations.mdc`
 
 ## ⛔ CRITICAL: DO NOT EDIT

package/stubs/ai-guides/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/ 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 -- 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/ 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 -- 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/ database/migrations/ .omnify.lock` |
+| CI Check | `npx omnify generate --check` |
+| Deploy | `php artisan migrate` |
+| Restore | `git checkout -- database/migrations/omnify/` |
+| Reset | `npx omnify reset --migrations` |