@famgia/omnify-laravel 0.0.87 → 0.0.89

package/stubs/ai-guides/claude-omnify/config-guide.md.stub

@@ -0,0 +1,253 @@
+# Omnify Configuration Guide
+
+## Quick Start
+
+```bash
+# Create new Laravel project (recommended)
+npx @famgia/omnify create-laravel-project my-app
+cd my-app
+
+# Or initialize in existing project
+npx @famgia/omnify init
+```
+
+## Configuration File
+
+Create `omnify.config.ts` in project root:
+
+```typescript
+import { defineConfig } from '@famgia/omnify';
+import laravel from '@famgia/omnify-laravel/plugin';
+import typescript from '@famgia/omnify-typescript/plugin';
+
+export default defineConfig({
+  schemasDir: './schemas',
+  lockFilePath: './.omnify.lock',
+
+  database: {
+    driver: 'mysql',
+    devUrl: 'mysql://root:password@localhost:3306/dev_db',
+  },
+
+  plugins: [
+    laravel({
+      migrationsPath: 'database/migrations/omnify',
+      modelsPath: 'app/Models',
+      baseModelsPath: 'app/Models/OmnifyBase',
+      providersPath: 'app/Providers',
+      localesPath: 'app/Models/OmnifyBase/Locales',
+    }),
+    typescript({
+      path: './resources/ts/types/models',
+      generateRules: true,
+    }),
+  ],
+
+  locale: {
+    locales: ['ja', 'en'],
+    defaultLocale: 'ja',
+  },
+});
+```
+
+## Configuration Options
+
+### Root Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `schemasDir` | `string` | Yes | Directory containing schema files |
+| `lockFilePath` | `string` | Yes | Path to lock file for change tracking |
+| `database` | `object` | Yes | Database configuration |
+| `plugins` | `Plugin[]` | No | Array of generator plugins |
+| `locale` | `object` | No | Multi-language support configuration |
+
+### database (required)
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `driver` | `string` | Database driver: `mysql`, `pgsql`, `sqlite`, `sqlsrv`, `mariadb` |
+| `devUrl` | `string` | Development database URL for Atlas diff (required for `generate`) |
+| `enableFieldComments` | `boolean` | Enable field comments in migrations (MySQL) |
+
+### Database URL Format
+
+```
+mysql://user:password@host:port/database
+postgres://user:password@host:port/database
+sqlite://path/to/file.db
+```
+
+## Plugin Configuration
+
+### Laravel Plugin
+
+```typescript
+import laravel from '@famgia/omnify-laravel/plugin';
+
+laravel({
+  migrationsPath: 'database/migrations/omnify',  // Migration files
+  modelsPath: 'app/Models',                       // Model classes
+  baseModelsPath: 'app/Models/OmnifyBase',        // Base model classes (auto-generated)
+  providersPath: 'app/Providers',                 // Service provider (OmnifyServiceProvider)
+  localesPath: 'app/Models/OmnifyBase/Locales',   // Locale files
+})
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `migrationsPath` | `string` | `database/migrations/omnify` | Laravel migrations output |
+| `modelsPath` | `string` | `app/Models` | Model classes output |
+| `baseModelsPath` | `string` | `app/Models/OmnifyBase` | Base model classes output |
+| `providersPath` | `string` | `app/Providers` | Service provider output |
+| `localesPath` | `string` | `app/Models/OmnifyBase/Locales` | Locale files output |
+
+### TypeScript Plugin
+
+```typescript
+import typescript from '@famgia/omnify-typescript/plugin';
+
+typescript({
+  path: './resources/ts/types/models',  // Output directory
+  generateRules: true,                   // Generate Ant Design validation rules
+})
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `path` | `string` | `./src/types/model` | Output directory for TypeScript types |
+| `generateRules` | `boolean` | `true` | Generate Ant Design validation rules |
+
+### Japan Plugin (Optional)
+
+```typescript
+import japan from '@famgia/omnify-japan/plugin';
+
+japan({
+  // Japan-specific types: JapaneseName, JapaneseAddress, etc.
+})
+```
+
+## Locale Configuration
+
+```typescript
+locale: {
+  locales: ['ja', 'en', 'vi'],    // Supported locale codes
+  defaultLocale: 'ja',            // Default locale for simple strings
+  fallbackLocale: 'en',           // Fallback when requested locale not found
+}
+```
+
+## Commands
+
+```bash
+# Create new Laravel project
+npx @famgia/omnify create-laravel-project my-app
+
+# Initialize in existing project
+npx @famgia/omnify init
+
+# Validate all schemas
+npx @famgia/omnify validate
+
+# Show pending changes
+npx @famgia/omnify diff
+
+# Generate code
+npx @famgia/omnify generate
+
+# Generate with options
+npx @famgia/omnify generate --force           # Force regenerate
+npx @famgia/omnify generate --migrations-only  # Only migrations
+npx @famgia/omnify generate --types-only       # Only TypeScript
+
+# Reset all generated files
+npx @famgia/omnify reset
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `OMNIFY_DEV_URL` | Override database.devUrl from config |
+| `DEBUG` | Set to `omnify:*` for debug output |
+
+## Common Mistakes
+
+**Wrong** - `locales` at root level:
+```typescript
+{
+  locales: ['en', 'ja'],  // ERROR: locales not in OmnifyConfig
+}
+```
+
+**Correct** - `locales` inside `locale` object:
+```typescript
+{
+  locale: {
+    locales: ['en', 'ja'],
+    defaultLocale: 'en',
+  },
+}
+```
+
+**Wrong** - Using old `output` format:
+```typescript
+{
+  output: {
+    laravel: { ... },      // ERROR: Use plugins instead
+    typescript: { ... },
+  },
+}
+```
+
+**Correct** - Using plugins:
+```typescript
+{
+  plugins: [
+    laravel({ ... }),
+    typescript({ ... }),
+  ],
+}
+```
+
+## Full Example
+
+```typescript
+import { defineConfig } from '@famgia/omnify';
+import laravel from '@famgia/omnify-laravel/plugin';
+import typescript from '@famgia/omnify-typescript/plugin';
+import japan from '@famgia/omnify-japan/plugin';
+
+export default defineConfig({
+  schemasDir: './schemas',
+  lockFilePath: './.omnify.lock',
+
+  database: {
+    driver: 'mysql',
+    devUrl: process.env.OMNIFY_DEV_URL || 'mysql://root:password@localhost:3306/dev_db',
+    enableFieldComments: true,
+  },
+
+  plugins: [
+    laravel({
+      migrationsPath: 'database/migrations/omnify',
+      modelsPath: 'app/Models',
+      baseModelsPath: 'app/Models/OmnifyBase',
+      providersPath: 'app/Providers',
+      localesPath: 'app/Models/OmnifyBase/Locales',
+    }),
+    typescript({
+      path: './resources/ts/types/models',
+      generateRules: true,
+    }),
+    japan(),  // Japan-specific types
+  ],
+
+  locale: {
+    locales: ['ja', 'en'],
+    defaultLocale: 'ja',
+    fallbackLocale: 'ja',
+  },
+});
+```

package/stubs/ai-guides/claude-omnify/japan-guide.md.stub

@@ -0,0 +1,186 @@
+# Japan Plugin Types Guide
+
+This project uses `@famgia/omnify-japan` plugin which provides Japan-specific types.
+
+## Available Types
+
+### Simple Types
+
+#### JapanesePhone
+Japanese phone number format (e.g., `090-1234-5678`, `03-1234-5678`)
+- SQL: `VARCHAR(15)`
+- Accepts with or without hyphens
+
+```yaml
+phone:
+  type: JapanesePhone
+```
+
+#### JapanesePostalCode
+Japanese postal code format (e.g., `123-4567`)
+- SQL: `VARCHAR(8)`
+- Accepts with or without hyphen
+
+```yaml
+postal_code:
+  type: JapanesePostalCode
+  nullable: true
+```
+
+### Compound Types
+
+Compound types expand into multiple database columns automatically.
+
+#### JapaneseName
+Japanese name with kanji and kana variants.
+
+**Expands to 4 columns:**
+- `{property}_lastname` - VARCHAR(50) - Family name (姓)
+- `{property}_firstname` - VARCHAR(50) - Given name (名)
+- `{property}_kana_lastname` - VARCHAR(100) - Family name in katakana
+- `{property}_kana_firstname` - VARCHAR(100) - Given name in katakana
+
+**Accessors generated:**
+- `{property}_full_name` - "姓 名" (space-separated)
+- `{property}_full_name_kana` - "セイ メイ" (space-separated)
+
+```yaml
+name:
+  type: JapaneseName
+  displayName:
+    ja: 氏名
+    en: Full Name
+  # Per-field overrides
+  fields:
+    KanaLastname:
+      nullable: true
+      hidden: true
+    KanaFirstname:
+      nullable: true
+      hidden: true
+```
+
+#### JapaneseAddress
+Japanese address with postal code and prefecture ID.
+
+**Expands to 5 columns:**
+- `{property}_postal_code` - VARCHAR(8) - Postal code (郵便番号)
+- `{property}_prefecture_id` - TINYINT UNSIGNED - Prefecture ID 1-47 (都道府県)
+- `{property}_address1` - VARCHAR(255) - City/Ward (市区町村)
+- `{property}_address2` - VARCHAR(255) - Street address (丁目番地号)
+- `{property}_address3` - VARCHAR(255) NULLABLE - Building name (ビル・マンション名)
+
+**Accessors generated:**
+- `{property}_full_address` - Concatenation of address1 + address2 + address3
+
+```yaml
+address:
+  type: JapaneseAddress
+  displayName:
+    ja: 住所
+    en: Address
+  fields:
+    Address3:
+      nullable: true
+```
+
+**Prefecture IDs (JIS X 0401):**
+| ID | Prefecture | ID | Prefecture | ID | Prefecture |
+|----|-----------|----|-----------|----|-----------|
+| 1 | 北海道 | 17 | 石川県 | 33 | 岡山県 |
+| 2 | 青森県 | 18 | 福井県 | 34 | 広島県 |
+| 3 | 岩手県 | 19 | 山梨県 | 35 | 山口県 |
+| 4 | 宮城県 | 20 | 長野県 | 36 | 徳島県 |
+| 5 | 秋田県 | 21 | 岐阜県 | 37 | 香川県 |
+| 6 | 山形県 | 22 | 静岡県 | 38 | 愛媛県 |
+| 7 | 福島県 | 23 | 愛知県 | 39 | 高知県 |
+| 8 | 茨城県 | 24 | 三重県 | 40 | 福岡県 |
+| 9 | 栃木県 | 25 | 滋賀県 | 41 | 佐賀県 |
+| 10 | 群馬県 | 26 | 京都府 | 42 | 長崎県 |
+| 11 | 埼玉県 | 27 | 大阪府 | 43 | 熊本県 |
+| 12 | 千葉県 | 28 | 兵庫県 | 44 | 大分県 |
+| 13 | 東京都 | 29 | 奈良県 | 45 | 宮崎県 |
+| 14 | 神奈川県 | 30 | 和歌山県 | 46 | 鹿児島県 |
+| 15 | 新潟県 | 31 | 鳥取県 | 47 | 沖縄県 |
+| 16 | 富山県 | 32 | 島根県 | | |
+
+#### JapaneseBankAccount
+Japanese bank account information.
+
+**Expands to 5 columns:**
+- `{property}_bank_code` - VARCHAR(4) - Bank code (銀行コード)
+- `{property}_branch_code` - VARCHAR(3) - Branch code (支店コード)
+- `{property}_account_type` - ENUM - Account type: 1=普通, 2=当座, 4=貯蓄
+- `{property}_account_number` - VARCHAR(7) - Account number (口座番号)
+- `{property}_account_holder` - VARCHAR(100) - Account holder name (口座名義)
+
+```yaml
+bank_account:
+  type: JapaneseBankAccount
+```
+
+## Per-field Overrides
+
+All compound types support per-field overrides:
+
+```yaml
+name:
+  type: JapaneseName
+  fields:
+    Lastname:
+      length: 100        # Override default VARCHAR length
+    Firstname:
+      length: 100
+    KanaLastname:
+      length: 200
+      nullable: true
+      hidden: true
+    KanaFirstname:
+      length: 200
+      nullable: true
+      hidden: true
+```
+
+**Available overrides:**
+- `length` - VARCHAR length (override default)
+- `nullable` - Whether the field can be NULL
+- `hidden` - Exclude from JSON/array output
+- `fillable` - Control mass assignment
+
+## Factory Examples
+
+```php
+$faker = fake('ja_JP');
+
+return [
+    // JapaneseName
+    'name_lastname' => $faker->lastName(),
+    'name_firstname' => $faker->firstName(),
+    'name_kana_lastname' => $faker->lastKanaName(),
+    'name_kana_firstname' => $faker->firstKanaName(),
+
+    // JapanesePhone
+    'phone' => $faker->phoneNumber(),
+
+    // JapanesePostalCode
+    'postal_code' => $faker->postcode(),
+
+    // JapaneseAddress
+    'address_postal_code' => $faker->postcode(),
+    'address_prefecture_id' => $faker->numberBetween(1, 47),
+    'address_address1' => $faker->city(),
+    'address_address2' => $faker->streetAddress(),
+    'address_address3' => $faker->optional(0.5)->secondaryAddress(),
+];
+```
+
+## Model Accessors
+
+```php
+// JapaneseName accessors
+$customer->name_full_name;      // "田中 太郎"
+$customer->name_full_name_kana; // "タナカ タロウ"
+
+// JapaneseAddress accessor
+$customer->address_full_address; // "千代田区丸の内1-1-1ビル5F"
+```

package/stubs/ai-guides/claude-omnify/laravel-guide.md.stub

@@ -0,0 +1,61 @@
+# Laravel Generator Guide
+
+## Generated Files
+
+### Migrations
+Located in `database/migrations/omnify/`
+- Auto-generated from schema changes
+- Handles column additions, modifications, removals
+- Preserves manual migrations outside omnify folder
+
+### Models
+Two-tier model structure:
+- `app/Models/OmnifyBase/*BaseModel.php` - Auto-generated, DO NOT EDIT
+- `app/Models/*.php` - User models, extend base models, safe to customize
+
+### Factories
+Located in `database/factories/`
+- Generated once, safe to customize
+- Uses appropriate Faker methods for each type
+
+## Model Features
+
+### Fillable
+All schema properties are mass-assignable by default.
+Use `fillable: false` to exclude.
+
+### Hidden
+Use `hidden: true` to exclude from JSON/array output.
+
+```yaml
+password:
+  type: Password
+  hidden: true
+```
+
+### Casts
+Auto-generated based on property types:
+- `Boolean` → `'boolean'`
+- `Json` → `'array'`
+- `Timestamp` → `'datetime'`
+
+### Relationships
+Generated from Association properties:
+- `ManyToOne` → `belongsTo()`
+- `OneToMany` → `hasMany()`
+- `ManyToMany` → `belongsToMany()`
+- `MorphTo` → `morphTo()`
+- `MorphMany` → `morphMany()`
+
+## Commands
+
+```bash
+# Generate migrations and models
+npx omnify generate
+
+# Force regeneration
+npx omnify generate --force
+
+# Validate schemas
+npx omnify validate
+```

package/stubs/ai-guides/claude-omnify/schema-guide.md.stub

@@ -0,0 +1,115 @@
+# Omnify Schema Guide
+
+## Schema File Format
+
+Schemas are YAML files defining data models. Each file represents one entity.
+
+```yaml
+name: User
+displayName:
+  ja: ユーザー
+  en: User
+kind: object
+
+properties:
+  email:
+    type: Email
+    unique: true
+  name:
+    type: String
+  bio:
+    type: Text
+    nullable: true
+
+options:
+  timestamps: true
+  softDelete: true
+```
+
+## Property Types
+
+### String Types
+- `String` - VARCHAR(255)
+- `Text` - TEXT
+- `LongText` - LONGTEXT
+- `Email` - VARCHAR(255) for email addresses
+- `Password` - VARCHAR(255), hidden in serialization
+
+### Numeric Types
+- `Int` - INTEGER
+- `BigInt` - BIGINT
+- `TinyInt` - TINYINT
+- `Float` - DOUBLE
+- `Decimal` - DECIMAL(precision, scale)
+
+### Date/Time Types
+- `Date` - DATE
+- `Time` - TIME
+- `DateTime` - DATETIME
+- `Timestamp` - TIMESTAMP
+
+### Other Types
+- `Boolean` - BOOLEAN
+- `Json` - JSON
+- `Enum` - ENUM with values
+- `EnumRef` - Reference to enum schema
+
+## Property Options
+
+```yaml
+propertyName:
+  type: String
+  nullable: true       # Can be NULL
+  unique: true         # Unique constraint
+  default: "value"     # Default value
+  length: 100          # VARCHAR length
+  hidden: true         # Hide from JSON output
+  fillable: false      # Exclude from mass assignment
+```
+
+## Associations
+
+```yaml
+# Many-to-One (belongsTo)
+author:
+  type: Association
+  relation: ManyToOne
+  target: User
+  onDelete: CASCADE
+
+# One-to-Many (hasMany)
+posts:
+  type: Association
+  relation: OneToMany
+  target: Post
+
+# Many-to-Many (belongsToMany)
+tags:
+  type: Association
+  relation: ManyToMany
+  target: Tag
+  joinTable: post_tags
+
+# Polymorphic
+commentable:
+  type: Association
+  relation: MorphTo
+```
+
+## Indexes
+
+```yaml
+indexes:
+  - columns: [status, published_at]
+  - columns: [email]
+    unique: true
+```
+
+## Schema Options
+
+```yaml
+options:
+  timestamps: true   # Add created_at, updated_at
+  softDelete: true   # Add deleted_at
+  idType: BigInt     # Primary key type (Int, BigInt, Uuid)
+```