@famgia/omnify 1.0.127 → 1.0.132

package/ai-guides/schema-guide.md

@@ -4,6 +4,76 @@
 
 All schemas are stored in `schemas/` directory with `.yaml` extension.
 
+## Registering Schemas from Laravel Packages
+
+Laravel packages can register their own schemas to be included in code generation.
+
+### In Package's ServiceProvider
+
+```php
+<?php
+
+namespace YourPackage\Providers;
+
+use App\Support\Omnify;
+use Illuminate\Support\ServiceProvider;
+
+class YourPackageServiceProvider extends ServiceProvider
+{
+    public function boot(): void
+    {
+        // Register package schemas for Omnify CLI
+        if (class_exists(Omnify::class)) {
+            Omnify::registerSchemaPath(
+                path: __DIR__ . '/../../schemas',    // Path to schema files
+                namespace: 'your-package'             // Optional namespace
+            );
+        }
+    }
+}
+```
+
+### Export Registered Paths
+
+Before running `npx omnify generate`, export the registered paths:
+
+```bash
+# Via Artisan command (if available)
+php artisan omnify:sync
+
+# Or via Tinker
+php artisan tinker --execute="App\Support\Omnify::exportPaths()"
+```
+
+This creates `storage/omnify/schema-paths.json` which the CLI reads to find package schemas.
+
+### Using Package Schemas in Your App
+
+Once registered, package schemas can be:
+
+1. **Referenced in relations**: `type: PackageModel` works automatically
+2. **Extended via Partial**: Create partial schemas to add custom properties
+3. **Overridden**: Create same-named schema in main `schemas/` to override
+
+### Connecting to Unloaded Package Schemas
+
+If a package's schema is not loaded but you need to reference it:
+
+```yaml
+# Create a Partial schema stub
+# schemas/stubs/User.yaml
+name: User
+kind: partial
+target: User
+
+# Minimal properties for relation connectivity
+properties:
+  id:
+    type: BigInt
+```
+
+Now other schemas can reference `User` in relationships.
+
 ## Multi-language Support (i18n)
 
 Omnify supports multi-language labels and placeholders for internationalized applications.
@@ -109,6 +179,90 @@ properties:
   # Property definitions here
 ```
 
+## Partial Schema (Extension Schema)
+
+Partial schemas allow you to extend existing schemas or connect to external package schemas.
+
+### Use Cases
+
+1. **Extend package schema**: Add properties to a schema from external package
+2. **Connect to external schema**: Create relation target for schemas not in your project
+3. **Override properties**: Customize package schema with project-specific fields
+
+### Basic Partial Schema
+
+```yaml
+# schemas/extensions/User.yaml
+name: User
+kind: partial
+target: User             # Target schema to extend (can be same as name)
+
+displayName:
+  ja: ユーザー拡張
+  en: User Extension
+
+properties:
+  # Add new properties to the target schema
+  profile_image_url:
+    type: String
+    nullable: true
+    displayName:
+      ja: プロフィール画像
+      en: Profile Image
+
+  department:
+    type: Department
+    relation: belongsTo
+    nullable: true
+```
+
+### Self-Referencing Partial (Connect to External Package)
+
+When connecting to a schema from an external package that isn't loaded in your project:
+
+```yaml
+# schemas/package/User.yaml
+# Create a stub for external package's User schema
+name: User
+kind: partial
+target: User             # Same as name = standalone schema
+
+displayName:
+  ja: ユーザー
+  en: User
+
+# Minimal properties for relationship connections
+properties:
+  email:
+    type: Email
+    displayName:
+      ja: メール
+      en: Email
+```
+
+This creates a valid `User` schema that can be referenced by other schemas:
+
+```yaml
+# schemas/blog/Post.yaml
+name: Post
+kind: object
+
+properties:
+  author:
+    type: User           # ✅ Now works! User exists as partial schema
+    relation: belongsTo
+```
+
+### Partial Schema Rules
+
+| Rule | Description |
+|------|-------------|
+| `kind: partial` | Required to mark as partial schema |
+| `target` | Schema to extend (required) |
+| Same name = standalone | If `name === target`, treated as independent schema |
+| Properties merge | Partial properties merged with target (target takes priority) |
+| No duplicates | Cannot have multiple partials with same name |
+
 ### Schema Options Reference
 
 | Option                         | Type    | Default    | Description                                        |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@famgia/omnify",
-  "version": "1.0.127",
+  "version": "1.0.132",
   "description": "Schema-driven database migration system with TypeScript types and Laravel migrations",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,15 +25,24 @@
     "ai-guides",
     "README.md"
   ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "postinstall": "node scripts/postinstall.js"
+  },
   "dependencies": {
-    "@famgia/omnify-cli": "0.0.123",
-    "@famgia/omnify-core": "0.0.117",
-    "@famgia/omnify-types": "0.0.115",
-    "@famgia/omnify-laravel": "0.0.126",
-    "@famgia/omnify-atlas": "0.0.111",
-    "@famgia/omnify-mcp": "0.0.103",
-    "@famgia/omnify-typescript": "0.0.105",
-    "@famgia/omnify-japan": "0.0.110"
+    "@famgia/omnify-cli": "workspace:*",
+    "@famgia/omnify-core": "workspace:*",
+    "@famgia/omnify-types": "workspace:*",
+    "@famgia/omnify-laravel": "workspace:*",
+    "@famgia/omnify-typescript": "workspace:*",
+    "@famgia/omnify-atlas": "workspace:*",
+    "@famgia/omnify-mcp": "workspace:*",
+    "@famgia/omnify-japan": "workspace:*"
   },
   "keywords": [
     "omnify",
@@ -48,14 +57,5 @@
     "claude"
   ],
   "author": "Famgia",
-  "license": "MIT",
-  "scripts": {
-    "build": "tsup",
-    "clean": "rm -rf dist",
-    "test": "vitest run --passWithNoTests",
-    "test:watch": "vitest",
-    "lint": "eslint src",
-    "typecheck": "tsc --noEmit",
-    "postinstall": "node scripts/postinstall.js"
-  }
-}
+  "license": "MIT"
+}

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

@@ -4,6 +4,76 @@
 
 All schemas are stored in `schemas/` directory with `.yaml` extension.
 
+## Registering Schemas from Laravel Packages
+
+Laravel packages can register their own schemas to be included in code generation.
+
+### In Package's ServiceProvider
+
+```php
+<?php
+
+namespace YourPackage\Providers;
+
+use App\Support\Omnify;
+use Illuminate\Support\ServiceProvider;
+
+class YourPackageServiceProvider extends ServiceProvider
+{
+    public function boot(): void
+    {
+        // Register package schemas for Omnify CLI
+        if (class_exists(Omnify::class)) {
+            Omnify::registerSchemaPath(
+                path: __DIR__ . '/../../schemas',    // Path to schema files
+                namespace: 'your-package'             // Optional namespace
+            );
+        }
+    }
+}
+```
+
+### Export Registered Paths
+
+Before running `npx omnify generate`, export the registered paths:
+
+```bash
+# Via Artisan command (if available)
+php artisan omnify:sync
+
+# Or via Tinker
+php artisan tinker --execute="App\Support\Omnify::exportPaths()"
+```
+
+This creates `storage/omnify/schema-paths.json` which the CLI reads to find package schemas.
+
+### Using Package Schemas in Your App
+
+Once registered, package schemas can be:
+
+1. **Referenced in relations**: `type: PackageModel` works automatically
+2. **Extended via Partial**: Create partial schemas to add custom properties
+3. **Overridden**: Create same-named schema in main `schemas/` to override
+
+### Connecting to Unloaded Package Schemas
+
+If a package's schema is not loaded but you need to reference it:
+
+```yaml
+# Create a Partial schema stub
+# schemas/stubs/User.yaml
+name: User
+kind: partial
+target: User
+
+# Minimal properties for relation connectivity
+properties:
+  id:
+    type: BigInt
+```
+
+Now other schemas can reference `User` in relationships.
+
 ## Multi-language Support (i18n)
 
 Omnify supports multi-language labels and placeholders for internationalized applications.
@@ -109,6 +179,90 @@ properties:
   # Property definitions here
 ```
 
+## Partial Schema (Extension Schema)
+
+Partial schemas allow you to extend existing schemas or connect to external package schemas.
+
+### Use Cases
+
+1. **Extend package schema**: Add properties to a schema from external package
+2. **Connect to external schema**: Create relation target for schemas not in your project
+3. **Override properties**: Customize package schema with project-specific fields
+
+### Basic Partial Schema
+
+```yaml
+# schemas/extensions/User.yaml
+name: User
+kind: partial
+target: User             # Target schema to extend (can be same as name)
+
+displayName:
+  ja: ユーザー拡張
+  en: User Extension
+
+properties:
+  # Add new properties to the target schema
+  profile_image_url:
+    type: String
+    nullable: true
+    displayName:
+      ja: プロフィール画像
+      en: Profile Image
+
+  department:
+    type: Department
+    relation: belongsTo
+    nullable: true
+```
+
+### Self-Referencing Partial (Connect to External Package)
+
+When connecting to a schema from an external package that isn't loaded in your project:
+
+```yaml
+# schemas/package/User.yaml
+# Create a stub for external package's User schema
+name: User
+kind: partial
+target: User             # Same as name = standalone schema
+
+displayName:
+  ja: ユーザー
+  en: User
+
+# Minimal properties for relationship connections
+properties:
+  email:
+    type: Email
+    displayName:
+      ja: メール
+      en: Email
+```
+
+This creates a valid `User` schema that can be referenced by other schemas:
+
+```yaml
+# schemas/blog/Post.yaml
+name: Post
+kind: object
+
+properties:
+  author:
+    type: User           # ✅ Now works! User exists as partial schema
+    relation: belongsTo
+```
+
+### Partial Schema Rules
+
+| Rule | Description |
+|------|-------------|
+| `kind: partial` | Required to mark as partial schema |
+| `target` | Schema to extend (required) |
+| Same name = standalone | If `name === target`, treated as independent schema |
+| Properties merge | Partial properties merged with target (target takes priority) |
+| No duplicates | Cannot have multiple partials with same name |
+
 ### Schema Options Reference
 
 | Option                         | Type    | Default    | Description                                        |