generator-pninja 1.2.1 → 1.5.0

package/README.md

@@ -5,7 +5,7 @@
 # generator-pninja
 
 Generate a full **Laravel + React + Vite** application from a single **JDL model**.
-Backend + Frontend + Docker + Database — ready in seconds ⚡
+Backend + Frontend + Docker + Database – ready in seconds ⚡
 
 [![License][license-badge]][license-url]
 [![npm version][npm-version-badge]][npm-version-url]
@@ -15,7 +15,7 @@ Backend + Frontend + Docker + Database — ready in seconds ⚡
 
 ## License
 
-This project is licensed under the Apache License 2.0 — see the [LICENSE.txt](LICENSE.txt) file for details.
+This project is licensed under the Apache License 2.0 – see the [LICENSE.txt](LICENSE.txt) file for details.
 
 ## What is PNinja?
 
@@ -27,7 +27,7 @@ This project is licensed under the Apache License 2.0 — see the [LICENSE.txt](
 - **Search engine:** Database, Algolia, Elasticsearch, Meilisearch, Typesense, Solr
 - **Docker Compose**
 
-All based on a **single JDL file** describing your domain!
+All based on **JDL files** describing your domain!
 
 ## Installation
 
@@ -39,6 +39,18 @@ npm install -g yo generator-pninja
 
 ## Usage
 
+### 1. Create the Application
+
+Generate the base application structure (server + client without entities):
+
+```bash
+yo pninja
+```
+
+**Answer a few prompts** ... and you're ready ⚡
+
+### 2. Generate Entities from JDL
+
 **Create your entity definition file using JDL:**
 
 ```bash
@@ -48,13 +60,34 @@ touch entities.jdl # or any other name of your choice
 and edit it using this guide:
 https://www.jhipster.tech/jdl/intro/
 
-**Run the generator:**
+**Run the entities generator:**
 
 ```bash
-yo pninja
+yo pninja:entities entities.jdl
 ```
 
-**Answer a few prompts** ... and you're ready ⚡
+You can run this command multiple times with different JDL files:
+
+```bash
+yo pninja:entities core-entities.jdl
+yo pninja:entities additional-entities.jdl
+```
+
+### 3. Interactive Entity Creation (Alternative)
+
+For incremental development or to modify entities individually, use the **entity sub-generator**:
+
+```bash
+yo pninja:entity [EntityName]
+```
+
+This interactive command allows you to:
+
+- Create new entities step by step
+- Add or remove fields and relationships
+- Update existing entities (regenerate, add, or remove)
+
+All entity configurations are stored in `.pninja/<EntityName>.json` files.
 
 ## What you get
 
@@ -63,6 +96,7 @@ my-app/
 ├── client/         # React + Vite app
 ├── docker/         # Docker compose
 ├── server/         # Laravel project
+├── .pninja/        # Entity configurations
 ├── package.json    # With commands
 └── README.md
 ```
@@ -80,15 +114,19 @@ Fully wired together: auth, routing, forms, CRUD, migrations.
 ### Data Management
 
 - **Soft Delete Support** - Logical deletion with `deleted_at` timestamps (use `@softDelete` annotation in JDL)
-  ```jdl
+
+```jdl
   @softDelete
   entity MyEntity {
     name String required
     description String
   }
-  ```
+```
+
 - **CSV Database Seeding** - Populate your database from CSV files
 - **Audit Logging** - Complete change tracking for all entity modifications
+- **Interactive Entity Generator** - Create and modify entities through CLI prompts
+- **Incremental Migrations** - Automatic database migrations for entity changes
 
 ### Search & Indexing
 
@@ -112,13 +150,15 @@ Fully wired together: auth, routing, forms, CRUD, migrations.
 - **Responsive Design** - Mobile-first approach
 - **Tailwind CSS** - Utility-first styling
 - **Material Symbols Icons** - Associate icons to entities using `@icon` annotation in JDL
-  ```jdl
+
+```jdl
   @icon("star")
   entity MyEntity {
     name String required
     description String
   }
-  ```
+```
+
 - **Component Library** - Pre-built accessible components
 
 ### DevOps Ready

package/generators/app/index.js

@@ -12,13 +12,37 @@ const __dirname = path.dirname(__filename);
 export default class extends Generator {
   constructor(args, opts) {
     super(args, opts);
-    this.option('fromMain', {
-      type: Boolean,
-      default: false
+    this.option('name', {
+      type: String,
+      description: 'Your project name'
     });
+    this.option('dmbs', {
+      type: String,
+      description: 'Your DBMS'
+    });
+    this.option('authentication', {
+      type: String,
+      description: 'The type of authentication to use',
+    });
+    this.option('clientType', {
+      type: String,
+      description: 'The type of client to use',
+    });
+    this.option('nativeLanguage', {
+      type: String,
+      description: 'The native language of the application',
+    });
+    this.option('languages', {
+      type: String,
+      description: 'Additional languages to install (comma separated)',
+    });
+    this.option('searchEngine', {
+      type: String,
+      description: 'The search engine to use (database, algolia, elastic, meilisearch, typesense, solr, null)',
+    })
   }
   async initializing() {
-    hello(this.log);
+    hello(this.log, true);
     this.log(`\n${colors.whiteBright('Application files will be generated in folder:')} ${colors.yellow(process.env.PWD)}\n`);
 
     // sub generator Auth
@@ -31,22 +55,23 @@ export default class extends Generator {
     }, {
       fromMain: true,
       env: this.env,
+      authentication: this.options.authentication,
       resolved: authGeneratorPath,
       namespace: 'pninja:auth'
     });
 
-    // sub generator Entities
-    const entitiesGeneratorPath = path.resolve(__dirname, '../entities/index.js');
-    const { default: EntitiesGenerator } = await import(entitiesGeneratorPath);
+    // sub generator Server
+    const serverGeneratorPath = path.resolve(__dirname, '../server/index.js');
+    const { default: ServerGenerator } = await import(serverGeneratorPath);
 
     await this.composeWith({
-      Generator: EntitiesGenerator,
-      path: path.dirname(entitiesGeneratorPath)
+      Generator: ServerGenerator,
+      path: path.dirname(serverGeneratorPath)
     }, {
       fromMain: true,
       env: this.env,
-      resolved: entitiesGeneratorPath,
-      namespace: 'pninja:entities'
+      resolved: serverGeneratorPath,
+      namespace: 'pninja:server'
     });
 
     // sub generator Client
@@ -58,6 +83,9 @@ export default class extends Generator {
     }, {
       fromMain: true,
       env: this.env,
+      clientType: this.options.clientType,
+      nativeLanguage: this.options.nativeLanguage,
+      languages: this.options.languages,
       resolved: clientGeneratorPath,
       namespace: 'pninja:client'
     });
@@ -73,6 +101,7 @@ export default class extends Generator {
       fromMain: true,
       env: this.env,
       resolved: searchGeneratorPath,
+      searchEngine: this.options.searchEngine,
       namespace: 'pninja:search'
     });
 
@@ -105,18 +134,25 @@ export default class extends Generator {
     });
   }
   async prompting() {
+    if (this.options.name && this.options.dbms) {
+      this.answers = {
+        name: this.options.name,
+        dbms: this.options.dbms
+      };
+      return;
+    }
     this.answers = await this.prompt([
       {
         type: "input",
         name: "name",
         message: "Your project name",
-        default: this.config.get('name') || this.appname // Default to current folder name
+        default: this.options.name || this.config.get('name') || this.appname // Default to current folder name
       }, {
         store: true,
         type: "list",
         name: "dbms",
         message: "Your DBMS",
-        default: this.config.get('dbms') || 'sqlite',
+        default: this.options.dbms || this.config.get('dbms') || 'sqlite',
         choices: [
           {
             name: `SQLite ${colors.dim('(Lightweight, serverless, file-based)')}`,

package/generators/app/templates/package.json.ejs

@@ -1,30 +1,31 @@
 {
-    "name": "<%= packageName %>",
-    "description": "<%= projectDescription %>",
-    "version": "<%= projectVersion %>",
-    "author": "<%= authorName %>",
-    "license": "ISC",
-    "dependencies": {
-    },
-    "scripts": {
-        "dev": "concurrently \"npm run server\" \"npm run client\"",
-        "client": "cd client && npm i --loglevel=error && npm run dev",
-        "dump-server": "cd server && php artisan dump-server",
-        "migrate": "cd server && php artisan migrate",
-        "migrate:fresh": "cd server && php artisan migrate:fresh",
-        "migrate:fresh:seed": "cd server && php artisan migrate:fresh --seed",
-        "migrate:seed": "cd server && php artisan migrate --seed",
-        "db:seed": "cd server && php artisan db:seed",
+  "name": "<%= packageName %>",
+  "description": "<%= projectDescription %>",
+  "version": "<%= projectVersion %>",
+  "author": "<%= authorName %>",
+  "license": "ISC",
+  "dependencies": {},
+  "scripts": {
+    "dev": "concurrently \"npm run server\" \"npm run queue:listen\" \"npm run client\"",
+    "client": "cd client && npm i --loglevel=error && npm run dev",
+    "dump-server": "cd server && php artisan dump-server",
+    "migrate": "cd server && php artisan migrate",
+    "migrate:fresh": "cd server && php artisan migrate:fresh",
+    "migrate:fresh:seed": "cd server && php artisan migrate:fresh --seed",
+    "migrate:seed": "cd server && php artisan migrate --seed",
+    "db:seed": "cd server && php artisan db:seed",
 <%  if (searchEngine === 'elastic') { -%>
-        "elastic:migrate": "cd server && php artisan elastic:migrate",
-        "elastic:migrate:reset": "cd server && php artisan elastic:migrate:reset",
-        "elastic:migrate:refresh": "cd server && php artisan elastic:migrate:refresh",
+    "elastic:migrate": "cd server && php artisan elastic:migrate",
+    "elastic:migrate:reset": "cd server && php artisan elastic:migrate:reset",
+    "elastic:migrate:refresh": "cd server && php artisan elastic:migrate:refresh",
 <%  } -%>
 <%  if (searchEngine === 'meilisearch') { -%>
-        "scout:sync-index-settings": "cd server && php artisan scout:sync-index-settings",
+    "scout:sync-index-settings": "cd server && php artisan scout:sync-index-settings",
 <%  } -%>
-        "seed": "cd server && php artisan db:seed",
-        "server": "cd server && php artisan serve"
+    "seed": "cd server && php artisan db:seed",
+    "server": "cd server && php artisan serve",
+    "queue:listen": "cd server && php artisan queue:listen",
+    "queue:work": "cd server && php artisan queue:work"
   },
   "devDependencies": {
     "concurrently": "^9.2.1"

package/generators/auth/index.js

@@ -14,9 +14,17 @@ export default class AuthGenerator extends Generator {
       type: Boolean,
       default: false
     });
+    this.option('authentication', {
+      type: String,
+      description: 'The type of authentication to use',
+    });
   }
 
   async prompting() {
+    if (this.options.authentication) {
+      this.answers = { authentication: this.options.authentication };
+      return;
+    }
     let prompts = [];
     if (this.options["fromMain"]) {
       prompts = [...prompts, ...[{
@@ -24,6 +32,7 @@ export default class AuthGenerator extends Generator {
         type: "list",
         name: "authentication",
         message: `Which ${colors.yellow('*type*')} of authentication would you like to use?`,
+        default: this.options.authentication || this.config.get('authentication') || 'keycloak',
         choices: [
           { name: 'Keycloak', value: 'keycloak' },
           { name: 'Sanctum', value: 'sanctum', disabled: "Not implemented yet" },
@@ -46,9 +55,10 @@ export default class AuthGenerator extends Generator {
       return;
     }
     if (this.answers.authentication === 'keycloak') {
-      await this.spawn('composer', ['require', 'robsontenorio/laravel-keycloak-guard'], { cwd: 'server' });
-      await this.spawn('php', ['artisan', 'vendor:publish', '--provider="KeycloakGuard\\KeycloakGuardServiceProvider"'], { cwd: 'server' });
-
+      this.fs.copy(
+        this.templatePath('packages/pninja/laravel-keycloak-guard/**'),
+        this.destinationPath('server/packages/pninja/laravel-keycloak-guard')
+      );
       const envContent = this.fs.read(this.destinationPath(`server/.env`));
       this.fs.write(this.destinationPath('server/.env'), envContent + `
 FRONTEND_URL=http://localhost:5173
@@ -57,16 +67,13 @@ KEYCLOAK_BASE_URL=https://sso.yourkeycloakbaseurl.net/auth
 KEYCLOAK_REALM=yourrealm
 KEYCLOAK_CLIENT_ID=yourclientid
 KEYCLOAK_CLIENT_SECRET=yourclientsecret
-KEYCLOAK_REALM_PUBLIC_KEY="yourrealmpublickey"
+# KEYCLOAK_REALM_PUBLIC_KEY="yourrealmpublickey"
 KEYCLOAK_LOAD_USER_FROM_DATABASE=false
 KEYCLOAK_USER_PROVIDER_CREDENTIAL=username
 KEYCLOAK_TOKEN_PRINCIPAL_ATTRIBUTE=preferred_username
 KEYCLOAK_IGNORE_RESOURCES_VALIDATION=true
 KEYCLOAK_USE_SERVICE_ACCOUNT=true`, { encoding: 'utf8', flag: 'w' });
 
-      if (this.fs.exists(`${this.destinationPath('server')}/config/auth.php`)) {
-        fs.unlinkSync(`${this.destinationPath('server')}/config/auth.php`);
-      }
       this.fs.copyTpl(this.templatePath("keycloak.auth.php.ejs"), `${this.destinationPath('server')}/config/auth.php`);
       let bootstrapAppFileContents = fs.readFileSync(`${this.destinationPath('server')}/bootstrap/app.php`, { encoding: 'utf8', flag: 'r' });
       const regexprBootstrapAppUse = /(?=use Illuminate\\Foundation\\Application;)/gmis;
@@ -86,4 +93,17 @@ KEYCLOAK_USE_SERVICE_ACCOUNT=true`, { encoding: 'utf8', flag: 'w' });
       fs.writeFileSync(`${this.destinationPath('server')}/bootstrap/app.php`, bootstrapAppFileContents, { encoding: 'utf8', flag: 'w' });
     }
   }
+  async install() {
+    if (this.config.get('authentication') === 'keycloak') {
+      const composerPath = this.destinationPath('server/composer.json');
+      const composerContent = JSON.parse(fs.readFileSync(composerPath, { encoding: 'utf8' }));
+      composerContent.repositories = composerContent.repositories || [];
+      composerContent.repositories.push({
+        type: "path",
+        url: "./packages/pninja/laravel-keycloak-guard"
+      });
+      fs.writeFileSync(composerPath, JSON.stringify(composerContent, null, 2), { encoding: 'utf8' });
+      await this.spawn('composer', ['require', 'pninja/laravel-keycloak-guard:@dev'], { cwd: 'server' });
+    }
+  }
 }

package/generators/auth/templates/packages/pninja/laravel-keycloak-guard/composer.json

@@ -0,0 +1,39 @@
+{
+  "name": "pninja/laravel-keycloak-guard",
+  "description": "Keycloak JWT Guard for Laravel — without firebase/php-jwt",
+  "type": "library",
+  "license": "MIT",
+  "require": {
+    "php": "^8.2",
+    "ext-openssl": "*",
+    "lcobucci/jwt": "^5.4",
+    "lcobucci/clock": "^3.3",
+    "illuminate/auth": "^11.0",
+    "illuminate/support": "^11.0",
+    "illuminate/http": "^11.0"
+  },
+  "require-dev": {
+    "orchestra/testbench": "^9.0",
+    "pestphp/pest": "^3.0",
+    "phpunit/phpunit": "^11.0"
+  },
+  "autoload": {
+    "psr-4": {
+      "Pninja\\KeycloakGuard\\": "src/"
+    }
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "Pninja\\KeycloakGuard\\Tests\\": "tests/"
+    }
+  },
+  "extra": {
+    "laravel": {
+      "providers": [
+        "Pninja\\KeycloakGuard\\KeycloakGuardServiceProvider"
+      ]
+    }
+  },
+  "minimum-stability": "stable",
+  "prefer-stable": true
+}

package/generators/auth/templates/packages/pninja/laravel-keycloak-guard/config/keycloak.php

@@ -0,0 +1,134 @@
+<?php
+
+return [
+
+    /*
+    |--------------------------------------------------------------------------
+    | Keycloak Server URL
+    |--------------------------------------------------------------------------
+    | Base URL of your Keycloak instance, e.g. https://keycloak.example.com
+    | Required when using JWKS discovery (realm_public_key left empty).
+    */
+    'base_url' => env('KEYCLOAK_BASE_URL', ''),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Keycloak Realm
+    |--------------------------------------------------------------------------
+    */
+    'realm' => env('KEYCLOAK_REALM', 'master'),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Realm Public Key (static)
+    |--------------------------------------------------------------------------
+    | The RS256 public key copied from:
+    |   Realm Settings → Keys → RS256 row → Public Key button
+    |
+    | If left empty, the guard will fetch keys dynamically from the JWKS
+    | endpoint: {base_url}/realms/{realm}/protocol/openid-connect/certs
+    |
+    | Example (without BEGIN/END headers):
+    |   KEYCLOAK_REALM_PUBLIC_KEY=MIIBIjANBgkqhk...
+    */
+    'realm_public_key' => env('KEYCLOAK_REALM_PUBLIC_KEY', ''),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Token Encryption Algorithm
+    |--------------------------------------------------------------------------
+    | Supported: RS256, RS384, RS512, ES256, ES384, ES512, HS256, HS384, HS512
+    */
+    'token_encryption_algorithm' => env('KEYCLOAK_TOKEN_ENCRYPTION_ALGORITHM', 'RS256'),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Load User From Database
+    |--------------------------------------------------------------------------
+    | When true the guard calls Auth::user() retrieving the user from DB.
+    | When false it builds a user object directly from the JWT claims.
+    */
+    'load_user_from_database' => env('KEYCLOAK_LOAD_USER_FROM_DATABASE', true),
+
+    /*
+    |--------------------------------------------------------------------------
+    | User Provider Custom Method
+    |--------------------------------------------------------------------------
+    | When set, this method is called on the UserProvider instead of
+    | retrieveByCredentials(). It receives the full decoded token.
+    */
+    'user_provider_custom_retrieve_method' => env('KEYCLOAK_USER_PROVIDER_CUSTOM_METHOD', null),
+
+    /*
+    |--------------------------------------------------------------------------
+    | User Provider Credential (DB field)
+    |--------------------------------------------------------------------------
+    | The column in your users table used to look up the user.
+    */
+    'user_provider_credential' => env('KEYCLOAK_USER_PROVIDER_CREDENTIAL', 'username'),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Token Principal Attribute (JWT claim)
+    |--------------------------------------------------------------------------
+    | The claim in the JWT token that maps to user_provider_credential.
+    */
+    'token_principal_attribute' => env('KEYCLOAK_TOKEN_PRINCIPAL_ATTRIBUTE', 'preferred_username'),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Append Decoded Token
+    |--------------------------------------------------------------------------
+    | When true the decoded token claims are appended to the user object
+    | as the `token` attribute.
+    */
+    'append_decoded_token' => env('KEYCLOAK_APPEND_DECODED_TOKEN', false),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Allowed Resources
+    |--------------------------------------------------------------------------
+    | Comma-separated list of Keycloak client IDs whose resource_access
+    | must be present in the token. Leave empty to skip resource validation.
+    |
+    | Example: KEYCLOAK_ALLOWED_RESOURCES=my-api,another-api
+    */
+    'allowed_resources' => env('KEYCLOAK_ALLOWED_RESOURCES', ''),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Ignore Resources Validation
+    |--------------------------------------------------------------------------
+    | Set to true to completely skip resource_access validation.
+    */
+    'ignore_resources_validation' => env('KEYCLOAK_IGNORE_RESOURCES_VALIDATION', false),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Leeway (seconds)
+    |--------------------------------------------------------------------------
+    | Clock skew tolerance between your server and Keycloak.
+    | Useful when you get "token not yet valid" / "token expired" errors.
+    */
+    'leeway' => env('KEYCLOAK_LEEWAY', 0),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Input Key
+    |--------------------------------------------------------------------------
+    | When set, the guard also looks for a token in this request parameter
+    | in addition to the Authorization: Bearer header.
+    | Example: KEYCLOAK_INPUT_KEY=api_token
+    */
+    'input_key' => env('KEYCLOAK_INPUT_KEY', ''),
+
+    /*
+    |--------------------------------------------------------------------------
+    | JWKS Cache TTL (seconds)
+    |--------------------------------------------------------------------------
+    | How long to cache the remote JWKS response.
+    | Set to 0 to disable caching (not recommended in production).
+    */
+    'jwks_cache_ttl' => env('KEYCLOAK_JWKS_CACHE_TTL', 300),
+
+];

package/generators/auth/templates/packages/pninja/laravel-keycloak-guard/src/Exceptions/InvalidTokenException.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pninja\KeycloakGuard\Exceptions;
+
+use Exception;
+
+class InvalidTokenException extends Exception
+{
+    public static function missingToken(): self
+    {
+        return new self('No token provided in request.');
+    }
+
+    public static function invalidSignature(): self
+    {
+        return new self('Token signature verification failed.');
+    }
+
+    public static function expired(): self
+    {
+        return new self('Token has expired.');
+    }
+
+    public static function notYetValid(): self
+    {
+        return new self('Token is not yet valid.');
+    }
+
+    public static function invalidResource(): self
+    {
+        return new self('Token does not contain any of the allowed resources.');
+    }
+
+    public static function jwksFetchFailed(string $url, string $reason): self
+    {
+        return new self("Failed to fetch JWKS from {$url}: {$reason}");
+    }
+
+    public static function publicKeyNotResolved(): self
+    {
+        return new self('Could not resolve a public key for the token.');
+    }
+
+    public static function unsupportedAlgorithm(string $alg): self
+    {
+        return new self("Unsupported token algorithm: {$alg}");
+    }
+}