prisma-laravel-migrate 0.0.13 → 0.0.15

package/README.md

@@ -14,45 +14,181 @@ npm install prisma-laravel-migrate --save-dev
 ```
 
 ---
+🛠️ Configuration layers
 
-## 🛠️ Prisma Generator Setup
+The generators read options in **three tiers (highest → lowest)**:
 
-Add both generator blocks to **`schema.prisma`**:
+1. **Environment override** – `PRISMA_LARAVEL_CFG=/path/to/laravel.config.js`
+2. **Shared project file** – **`prisma/laravel.config.js`** (auto‑loaded if present)
+3. **`generator … { … }` blocks** in `schema.prisma`
 
-```prisma
-generator migrate {
-  provider  = "prisma-laravel-migrations"
-  stubDir   = "./prisma/stubs"
+A key in tier ① shadows the same key in ② and ③; tier ② shadows tier ③.
+
+### 📁 Shared project file — `prisma/laravel.config.js`
+
+```js
+/** Global to all Prisma‑Laravel generators */
+module.exports = {
+  /* -- table decoration ------------------------------- */
+  tablePrefix: "tx_",
+  tableSuffix: "_arch",
+
+  /* -- default stub root ------------------------------ */
+  stubDir: "prisma/stubs",
 
-  output    = "database/migrations"   // fallback
-  outputDir = "database/migrations"   // takes precedence
+  /* -- global dry‑run --------------------------------- */
+  noEmit: false,
+
+  /* -- override default outputs ----------------------- */
+  output: {
+    migrations: "database/migrations",
+    models:      "app/Models",
+    enums:       "app/Enums"
+  },
 
-  noEmit    = false                   // skip writing if true
-  groups    = "./prisma/group-stubs.js"
+  /* -- per‑generator overrides ------------------------ */
+  migrate: {
+    groups: "./prisma/migrate-groups.js",
+    rules : "./prisma/custom-rules.js"
+  },
+
+  modeler: {
+    groups: [
+      { stubFile: "audit.stub", tables: ["logs","audit_trails"] }
+    ],
+    outputEnumDir: "app/Enums",
+    overwriteExisting: true
+  }
+};
+```
+
+<details>
+<summary>Type reference</summary>
+
+```ts
+export interface Rule {
+   test(
+      def: ColumnDefinition,
+      allDefs: ColumnDefinition[],
+      dmmf: DMMF.Document
+   ): boolean;
+   render(
+      def: ColumnDefinition,
+      allDefs: ColumnDefinition[],
+      dmmf: DMMF.Document
+   ): Render;
+}
+/* ------------------------------------------------------------
+ *  Re-usable stub-group description
+ * ---------------------------------------------------------- */
+export interface StubGroupConfig {
+   /** Path relative to stubDir/<type>/  (e.g. "auth.stub") */
+   stubFile: string;
+   tables: string[];      // ["users","accounts",…] or enum names
 }
 
-generator modeler {
-  provider      = "prisma-laravel-models"
-  stubDir       = "./prisma/stubs"
+/* ------------------------------------------------------------
+ *  Per-generator overrides  (migration / modeler)
+ * ---------------------------------------------------------- */
+export interface LaravelGeneratorConfig {
+
+   /** Override stubDir only for this generator */
+   stubDir?: string;
+
+   /** Where the generated PHP goes (overrides block) */
+   outputDir?: string;
+
+   overwriteExisting?: boolean;
 
-  output        = "app/Models"
-  outputDir     = "app/Models"        // overrides output
-  outputEnumDir = "app/Enums"
+   /**
+    * Stub grouping:
+    *  • string  – path to a JS module exporting StubGroupConfig[]
+    *  • array   – the group definitions themselves
+    */
+   groups?: string | StubGroupConfig[];
 
-  noEmit        = false
-  groups        = "./prisma/group-stubs.js"
+   /** Skip file emission for *this* generator only */
+   noEmit?: boolean;
 }
+
+/* ------------------------------------------------------------
+ *  Top-level shared config  (visible to all generators)
+ * ---------------------------------------------------------- */
+export interface LaravelSharedConfig {
+   /** Table name decoration */
+   tablePrefix?: string;
+   tableSuffix?: string;
+
+   /** Default stub root (migration/, model/, enum/) */
+   stubDir?: string;
+
+   /** Global “don’t write files” switch */
+   noEmit?: boolean;
+
+   /** Override default output folders */
+   output?: {
+      migrations?: string;
+      models?: string;
+      enums?: string;
+   };
+
+   /** Per-generator fine-tuning */
+   migrate?: Partial<MigratorConfigOverride>;
+   modeler?: Partial<ModelConfigOverride>;
+}
+
+
+/* --- Migrator-specific extra keys ---------------------------------------- */
+export interface MigratorConfigOverride extends LaravelGeneratorConfig {
+   /**
+    * Custom migration rules:
+    *  • string – path to JS module exporting Rule[]
+    *  • Rule[] – rules array inline
+    */
+   rules?: string | Rule[];
+
+   stubPath?: string;
+}
+
+
+export interface ModelConfigOverride extends LaravelGeneratorConfig {
+   modelStubPath?: string;
+   enumStubPath?: string;
+   /** Extra folder for enums (modeler only) */
+   outputEnumDir?: string;
+}
+```
+
+</details>
+
+---
+
+## 🛠️ Prisma Generator Setup (quick)
+
+Even with the shared file you may still keep minimal blocks in `schema.prisma`:
+
+```prisma
+generator migrate {
+  provider  = "prisma-laravel-migrations"
+  stubDir   = "./prisma/stubs"
+}
+
+generator modeler {
+  provider  = "prisma-laravel-models"
+  stubDir   = "./prisma/stubs"
 ```
 
 ### Field Reference
 
-| Key | Notes |
-| --- | --- |
-| `outputDir / output` | Destination folder (`outputDir` overrides `output`). |
-| `outputEnumDir` | (modeler) directory for generated enum classes. |
-| `stubDir` | Root stub folder (`migration/`, `model/`, `enum/`). |
-| `groups` | JS module that maps stub files to table groups. |
-| `noEmit` | If `true`, generator parses but **writes no** files (dry‑run). |
+| Key                    | Notes                                                                                                     |
+| ---------------------- | --------------------------------------------------------------------------------------------------------- |
+| `outputDir / output`   | Destination folder (`outputDir` overrides `output`).                                                      |
+| `outputEnumDir`        | (modeler) directory for generated enum classes.                                                           |
+| `stubDir`              | Root stub folder (`migration/`, `model/`, `enum/`).                                                       |
+| `tablePrefix`          | String prepended to every generated **physical** table name.                                              |
+| `tableSuffix`          | String appended to every generated **physical** table name.                                               |
+| `groups`               | JS module *or* inline array that maps stub files to table groups.                                         |
+| `noEmit`               | If `true`, generator parses and validates but **does not write** any files (dry-run / CI mode).           |
 
 ---
 
@@ -408,6 +544,12 @@ your Eloquent model.
 | `@ignore` | Relation field | Skips generating the relationship method |
 | `@with` (no args) | Relation field | Adds that single relation to `$with` |
 | `@with(rel1,rel2,…)` | Model only | Adds listed relations to `$with` |
+| **NEW** `@trait:Full\Namespace\MyTrait`      | Model only                          | Adds `use MyTrait;` inside the class                                                    |
+| **NEW** `@implements:Full\Interface as Alias`| Model only                          | Adds the interface (with alias) to the class’s `implements` list                        |
+| **NEW** `@observer:App\Observers\FooObserver`| Model only                          | Generates a `boot()` method that calls `static::observe(FooObserver::class);`           |
+| **NEW** `@factory:FooFactory`                | Model only                          | Adds `use HasFactory;` and `protected static string $factory = FooFactory::class;`      |
+| **NEW** `@touch{col1,col2}`                  | Model only                          | Generates `protected $touches = ['col1','col2'];`                                       |
+| **NEW** `@appends{attr1,attr2}`               | Model only                          | Generates `protected $appends = ['attr1','attr2'];` plus `$this->getAttrAttribute()` stubs |
 
 > **Syntax options**  
 > • Inline:  
@@ -418,7 +560,15 @@ your Eloquent model.
 >  `/// @fillable{name,balance}`  
 > • Model eager‑load:  
 >  `/// @with(posts,roles)`
-
+> • **Traits / implements**:  
+>   `/// @trait:Illuminate\Auth\Authenticatable`  
+>   `/// @implements:Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract`  
+> • **Observers / factory**:  
+>   `/// @observer:App\Observers\UserObserver`  
+>   `/// @factory:UserFactory`  
+> • **Touches / appends**:  
+>   `/// @touch{company,profile}`  
+>   `/// @appends{full_name,age}`  
 ---
 
 #### Example
@@ -467,6 +617,71 @@ protected $with = ['posts','comments'];
 `@ignore` prevents the `company()` relation method.  
 Combine multiple inline directives; they’re processed left‑to‑right.
 
+
+#### Example: Combined Directives
+
+```prisma
+/// @fillable{name,balance}
+/// @hidden{secretToken}
+/// @guarded{password,apiToken}
+/// @trait:Illuminate\Auth\Authenticatable
+/// @implements:Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract
+/// @observer:App\Observers\UserObserver
+/// @factory:UserFactory
+/// @touch{company}
+/// @appends{full_name}
+model User {
+  id        Int      @id @default(autoincrement())
+  email     String   @unique                      /// @hidden @fillable
+  password  String                                 /// @hidden @guarded
+  balance   Decimal @default(0.0) /// @cast{decimal:2}
+  profile   Json?    /// @type{ import:'@types/forms', type:'ProfileDTO' }
+  company   Company? @relation(fields:[companyId], references:[id]) /// @ignore
+  companyId Int?
+  posts     Post[]   /// @with
+}
+```
+
+**Generated output (simplified)**
+
+```php
+use Illuminate\Auth\Authenticatable;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract;
+use App\Observers\UserObserver;
+
+class User extends Model implements AuthenticatableContract
+{
+    use HasFactory, Authenticatable;
+
+    protected $fillable = ['name','balance','email'];
+    protected $hidden   = ['secretToken','password'];
+    protected $guarded  = ['password','apiToken'];
+
+    protected $casts    = ['balance' => 'decimal:2'];
+    protected $touches  = ['company'];
+    protected $appends  = ['full_name'];
+    protected static string $factory = UserFactory::class;
+
+    protected static function boot()
+    {
+        parent::boot();
+        static::observe(UserObserver::class);
+    }
+
+    public function getFullNameAttribute()
+    {
+        // TODO
+        return $this->attributes['full_name'] ?? null;
+    }
+
+    public function posts()
+    {
+        return $this->hasMany(Post::class);
+    }
+}
+```
+
 ---
 
 ## 💡 Tips
@@ -477,6 +692,110 @@ Combine multiple inline directives; they’re processed left‑to‑right.
 
 ---
 
+## 📚 Programmatic API (ES / TypeScript)
+
+Use the library directly in a script or build tool instead of the CLI.
+
+```ts
+import {
+  generateLaravelSchema,
+  generateLaravelModels,
+  sortMigrations,
+} from 'prisma-laravel-migrate';
+import { readFileSync, writeFileSync } from 'fs';
+import { getDMMF } from '@prisma/sdk';
+
+(async () => {
+  /* 1. Load schema & build DMMF */
+  const schemaPath = 'prisma/schema.prisma';
+  const datamodel  = readFileSync(schemaPath, 'utf8');
+  const dmmf       = await getDMMF({ datamodel });
+
+  /* 2. Run generators entirely in-memory */
+  const migrations = generateLaravelSchema({
+    dmmf,
+    schemaPath,                 // ← always pass this
+    generator : { config: {} } as any,
+  });
+
+  const { models, enums } = generateLaravelModels({
+    dmmf,
+    schemaPath,
+    generator : { config: {} } as any,
+  });
+
+  /* 3. Inspect or write output */
+  sortMigrations(migrations).forEach(m => {
+    writeFileSync(`./out/${m.tableName}.php`, m.statements.join('\n'), 'utf8');
+  });
+})();
+```
+
+### Custom migration rules in code
+
+```ts
+import { Rule } from 'prisma-laravel-migrate';
+
+const softDeleteRule: Rule = {
+  test:   d => d.name === 'deleted_at' && d.migrationType === 'timestamp',
+  render: () => ({
+    column : 'deleted_at',
+    snippet: ["$table->timestamp('deleted_at')->nullable();"],
+  }),
+};
+
+generateLaravelSchema({
+  dmmf,
+  schemaPath: 'prisma/schema.prisma',
+  generator : { config: { rules: [softDeleteRule] } } as any,
+});
+```
+
+### Public exports
+
+| Export                           | Purpose                                             |
+| -------------------------------- | --------------------------------------------------- |
+| `generateLaravelSchema`          | Build migration objects (and optionally write files)|
+| `generateLaravelModels`          | Build model + enum definitions                      |
+| `sortMigrations`                 | Topologically sort migrations by FK dependencies    |
+| `Rule`                           | Type helper for custom migration shortcuts          |
+| _types_ (`column-definition-types`, `laravel-config`) | Full TypeScript typings          |
+
+```ts
+import {
+  ColumnDefinition,
+  LaravelSharedConfig,
+  MigratorConfigOverride,
+} from 'prisma-laravel-migrate';
+```
+
+> **Heads-up:**  
+> `generateLaravelSchema` and `generateLaravelModels` **write files by default**  
+> (honouring the `outputDir` settings).  
+> If you only want the in-memory objects—e.g. to capture the returned
+> `migrations`, `models`, or `enums` arrays—set  
+> `noEmit: true` in either
+>
+> * the per-call `generator.config` object:
+>   ```ts
+>   generateLaravelSchema({
+>     dmmf,
+>     schemaPath,
+>     generator: { config: { noEmit: true } } as any,
+>   });
+>   ```
+> * **or** in `prisma/laravel.config.js`:
+>   ```js
+>   module.exports = {
+>     migrate: { noEmit: true },
+>     modeler: { noEmit: true },
+>   };
+>   ```
+> This prevents any files from being created or overwritten while still
+> returning the fully-populated data structures for custom processing.
+
+---
+
 ## 📜 License
 
 MIT — Happy scaffolding! 🎉

package/dist/cli/cli.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import * as dmf from '@prisma/sdk';
+import { generateLaravelSchema } from '../generator/migrator/index.js';
+import { generateLaravelModels } from '../generator/modeler/index.js';
+import { existsSync, readFileSync } from 'fs';
+import { spawn } from 'child_process';
+const cli = new Command();
+cli
+    .name('prisma-laravel-cli')
+    .description('Initialize and customize Prisma→Laravel generators & stubs')
+    .version('0.1.0');
+function generatorBlock(base, // singular
+stubDirRel, extras = []) {
+    const name = `${base}s`; // migrations / models
+    const provider = `prisma-laravel-${name}s`; // prisma-laravel-migrations
+    const extra = extras.length ? "\n  " + extras.join("\n  ") : "";
+    return `
+generator ${name} {
+  provider = "${provider}"
+  stubDir  = "${stubDirRel}"${extra}
+}
+`;
+}
+//
+// init
+//
+cli
+    .command("init")
+    .description("Inject generators into schema.prisma and scaffold stubs/")
+    .option("-s, --schema <path>", "Prisma schema file", "prisma/schema.prisma")
+    .action(async (opts) => {
+    /* 1. Paths ------------------------------------------------------ */
+    const schemaPath = path.resolve(process.cwd(), opts.schema);
+    const schemaDir = path.dirname(schemaPath); // prisma/
+    const userStubs = path.join(schemaDir, "stubs"); // prisma/stubs
+    const stubDirRel = "./" + path.relative(schemaDir, userStubs).replace(/\\/g, "/"); // "./stubs"
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+    const pkgStubs = path.resolve(__dirname, "../stubs"); // bundled stubs
+    /* 2. Load schema.prisma ---------------------------------------- */
+    let schema = await fs.readFile(schemaPath, "utf-8");
+    const hasGen = (base) => new RegExp(`generator\\s+${base}s\\s*\\{`).test(schema);
+    /* 3. Inject generator blocks if missing ------------------------ */
+    if (!hasGen("migration")) {
+        schema += generatorBlock("migration", stubDirRel, [
+            'outputDir = "database/migrations"',
+        ]);
+        console.log("➡️  Added migrations generator");
+    }
+    if (!hasGen("model")) {
+        schema += generatorBlock("model", stubDirRel, [
+            'outputDir     = "app/Models"',
+            'outputEnumDir = "app/Enums"',
+        ]);
+        console.log("➡️  Added models generator");
+    }
+    await fs.writeFile(schemaPath, schema, "utf-8");
+    console.log(`✅ Updated ${schemaPath}`);
+    /* 4. Copy default stub files ---------------------------------- */
+    const stubTypes = ["migration", "model", "enum"];
+    for (const type of stubTypes) {
+        const targetDir = path.join(userStubs, type);
+        await fs.mkdir(targetDir, { recursive: true });
+        /* index.stub */
+        const src = path.join(pkgStubs, `${type}.stub`);
+        const dst = path.join(targetDir, "index.stub");
+        try {
+            await fs.access(dst);
+        }
+        catch {
+            await fs.copyFile(src, dst);
+            console.log(`➡️  Copied ${type}.stub → stubs/${type}/index.stub`);
+        }
+        /* simple-model.stub */
+        if (type === "model") {
+            const src2 = path.join(pkgStubs, "simple-model.stub");
+            const dst2 = path.join(targetDir, "simple-model.stub");
+            try {
+                await fs.access(dst2);
+            }
+            catch {
+                await fs.copyFile(src2, dst2);
+                console.log("➡️  Copied simple-model.stub → stubs/model/simple-model.stub");
+            }
+        }
+    }
+    /* 5. Create laravel.config.js if absent ------------------------ */
+    const cfgPath = path.join(schemaDir, "prisma-laravel.config.js");
+    try {
+        await fs.access(cfgPath);
+    }
+    catch {
+        const cfgTemplate = `
+// prisma/prisma-laravel.config.js
+module.exports = {
+  tablePrefix: "",        // e.g. "tx_"
+  tableSuffix: "",        // e.g. "_arch"
+  stubDir:     "${stubDirRel}",
+  // migrate: { noEmit: false },
+  // modeler: { noEmit: false }
+};
+`;
+        await fs.writeFile(cfgPath, cfgTemplate.trimStart(), "utf-8");
+        console.log("➡️  Created laravel.config.js");
+    }
+    console.log("🎉 Initialization complete!");
+});
+//
+// customize
+//
+cli
+    .command('customize')
+    .alias('c')
+    .description('Scaffold per-table stub files from index.stub')
+    .option('-s, --schema <path>', 'Prisma schema file', 'prisma/schema.prisma')
+    .option('-t, --types <list>', 'Comma-separated: migration,model,enum', (val) => val.split(',').map(s => s.trim().toLowerCase()), [])
+    .option('-n, --names <list>', 'Comma-separated base names', (val) => val.split(',').map(s => s.trim()), [])
+    .action(async (opts) => {
+    const want = opts.types;
+    const bases = opts.names;
+    if (!want.length)
+        throw new Error('Specify at least one type with -t');
+    if (!bases.length)
+        throw new Error('Specify at least one name with -n');
+    // enums stand alone
+    if (want.includes('enum') && want.length > 1) {
+        throw new Error('`enum` cannot be combined with other types');
+    }
+    const schemaDir = path.dirname(path.resolve(process.cwd(), opts.schema));
+    const stubRoot = path.join(schemaDir, 'stubs');
+    const doBoth = want.includes('migration') && want.includes('model');
+    for (const t of want) {
+        if (t === 'enum') {
+            const dir = path.join(stubRoot, 'enum');
+            const idx = path.join(dir, 'index.stub');
+            await fs.mkdir(dir, { recursive: true });
+            for (const name of bases) {
+                const dst = path.join(dir, `${name}.stub`);
+                try {
+                    await fs.access(dst);
+                    console.log(`🟡 Skip enum/${name}.stub`);
+                }
+                catch {
+                    await fs.copyFile(idx, dst);
+                    console.log(`✅ Created enum/${name}.stub`);
+                }
+            }
+            continue;
+        }
+        for (const kind of doBoth ? ['migration', 'model'] : [t]) {
+            const dir = path.join(stubRoot, kind);
+            const idx = path.join(dir, 'index.stub');
+            await fs.mkdir(dir, { recursive: true });
+            for (const base of bases) {
+                const dst = path.join(dir, `${base}.stub`);
+                try {
+                    await fs.access(dst);
+                    console.log(`🟡 Skip ${kind}/${base}.stub`);
+                }
+                catch {
+                    await fs.copyFile(idx, dst);
+                    console.log(`✅ Created ${kind}/${base}.stub`);
+                }
+            }
+        }
+    }
+    console.log('🎉 Customize complete!');
+});
+//
+// proxy to Prisma generate
+//
+cli
+    .command('gen')
+    .description('Run Prisma generate, or skip it (--skipGenerate), then run Laravel generators')
+    .option('--config <path>', 'Path to prisma-laravel config file')
+    .option('--skipGenerate', 'Only run the Laravel generators (no Prisma generate)')
+    .action(async (opts) => {
+    const configPath = opts.config
+        ? path.resolve(process.cwd(), opts.config)
+        : path.resolve(process.cwd(), 'prisma-laravel.config.js');
+    if (!existsSync(configPath)) {
+        console.error(`❌ Config file not found: ${configPath}`);
+        process.exit(1);
+    }
+    const cfgMod = await import(configPath);
+    const cfg = cfgMod.default ?? cfgMod;
+    if (!cfg.generator?.config) {
+        console.error('❌ `generator.config` is required in your config.');
+        process.exit(1);
+    }
+    const schemaPrismaPath = cfg.schemaPath
+        ? path.resolve(process.cwd(), cfg.schemaPath)
+        : path.resolve(process.cwd(), 'prisma/schema.prisma');
+    if (!existsSync(schemaPrismaPath)) {
+        console.error(`❌ Schema not found: ${schemaPrismaPath}`);
+        process.exit(1);
+    }
+    const run = async () => {
+        const datamodel = readFileSync(schemaPrismaPath, 'utf-8');
+        const sdk = dmf.default ?? dmf;
+        const { dmmf } = await sdk.getDMMF({ datamodel });
+        await generateLaravelSchema({
+            dmmf,
+            //@ts-ignore
+            generator: { config: cfg.generator.config },
+            otherGenerators: [],
+            schemaPath: schemaPrismaPath,
+            datasources: [],
+            datamodel,
+            version: '',
+        });
+        await generateLaravelModels({
+            dmmf,
+            //@ts-ignore
+            generator: { config: cfg.generator.config },
+            otherGenerators: [],
+            schemaPath: schemaPrismaPath,
+            datasources: [],
+            datamodel,
+            version: '',
+        });
+    };
+    if (opts.skipGenerate) {
+        await run();
+    }
+    else {
+        const prisma = spawn('npx', ['prisma', 'generate'], {
+            stdio: 'inherit',
+            shell: true,
+        });
+        prisma.on('exit', (code) => {
+            if (code !== 0)
+                process.exit(code);
+            run().catch(e => {
+                console.error('❌ Gen failed:', e.message ?? e);
+                process.exit(1);
+            });
+        });
+    }
+});
+cli.parse(process.argv);
+//# sourceMappingURL=cli.js.map

package/dist/cli/{index.js → migrator.index.js}

@@ -9,4 +9,4 @@ generatorHandler({
         prettyName: 'Laravel Schema',
     }),
 });
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=migrator.index.js.map