go-duck-cli 1.1.15 → 1.1.16

package/README.md

@@ -115,6 +115,11 @@ cd my-app
 
 Before running the microservice, compile the protobuf contract files using the scaffolded scripts:
 
+> [!NOTE]
+> **Do I need to run this?**
+> *   **Yes (Local Host Execution)**: You must run the compilation script whenever you first create the microservice, or whenever you modify the GDL schemas and re-run `import-gdl` to generate updated gRPC structures.
+> *   **No (Docker Deployment)**: If you compile and run the application via Docker (using `docker build` or `docker-compose`), the multi-stage `devops/Dockerfile` compiles the protobuf definitions internally, so you do not need to run the scripts locally.
+
 #### Prerequisites
 1. Ensure the `protoc` compiler is installed and added to your system's `PATH`.
 2. Install the necessary Go compiler plugins:

package/generators/devops.js

@@ -15,6 +15,20 @@ export const generateDeploymentArtifacts = async (config, projectRootDir) => {
 
     const appName = config.name || 'go-duck';
     const appPort = config.server?.port || 8080;
+    const keycloakHost = config.security?.['keycloak-host'] || 'http://localhost:8180';
+    const keycloakPort = keycloakHost.includes(':') ? keycloakHost.split(':').pop() : '8080';
+
+    const dbPort = config.datasource?.port || 5432;
+
+    const redisHost = config.cache?.redis?.host || 'localhost:6379';
+    const redisPort = redisHost.includes(':') ? redisHost.split(':').pop() : '6379';
+
+    const mqttBroker = config.messaging?.mqtt?.broker || 'tcp://localhost:1883';
+    const mqttPort = mqttBroker.includes(':') ? mqttBroker.split(':').pop() : '1883';
+
+    const esAddr = config.elasticsearch?.addresses?.[0] || 'http://localhost:9200';
+    const esAddrClean = esAddr.replace(/\/+$/, '');
+    const esPort = esAddrClean.includes(':') ? esAddrClean.split(':').pop() : '9200';
 
     // --- 1. Dockerfile (Multi-stage, lean production image) ---
     const dockerfile = `
@@ -63,7 +77,7 @@ COPY --from=builder /app/application.yml .
 COPY --from=builder /app/application-dev.yml .
 COPY --from=builder /app/application-prod.yml .
 
-EXPOSE 8080
+EXPOSE ${appPort}
 ENV GO_PROFILE=prod
 ENTRYPOINT ["/app/server"]
 `;
@@ -79,7 +93,7 @@ services:
       POSTGRES_PASSWORD: ${config.datasource?.password || 'password'}
       POSTGRES_DB: ${config.datasource?.database || 'go_duck_master'}
     ports:
-      - "5432:5432"
+      - "${dbPort}:5432"
     volumes:
       - postgres_data:/var/lib/postgresql/data
     networks:
@@ -89,7 +103,7 @@ services:
     image: redis:7.2.4-alpine
     container_name: ${appName}-redis
     ports:
-      - "6379:6379"
+      - "${redisPort}:6379"
     command: redis-server --save 60 1 --loglevel warning
     networks:
       - go-duck-net
@@ -98,7 +112,7 @@ services:
     image: eclipse-mosquitto:2.0.18
     container_name: ${appName}-mqtt
     ports:
-      - "1883:1883"
+      - "${mqttPort}:1883"
       - "9001:9001"
     volumes:
       - ./k8s/mosquitto.conf:/mosquitto/config/mosquitto.conf
@@ -136,7 +150,7 @@ services:
       - xpack.security.enabled=false
       - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
     ports:
-      - "9200:9200"
+      - "${esPort}:9200"
     networks:
       - go-duck-net
 
@@ -150,7 +164,7 @@ services:
     volumes:
       - ./keycloak/realm-config:/opt/keycloak/data/import
     ports:
-      - "8180:8080"
+      - "${keycloakPort}:8080"
     networks:
       - go-duck-net
 

package/generators/docs.js

@@ -61,11 +61,20 @@ export const generateDocumentation = async (config, entities, outputDir, enums =
         { file: 'serverless', title: 'Serverless Transformation' }
     ];
 
+    const grpcAddr = config.server?.grpc?.addr || ':9000';
+    const grpcPort = grpcAddr.includes(':') ? grpcAddr.split(':').pop() : '9000';
+
+    const mqttBroker = config.messaging?.mqtt?.broker || 'tcp://localhost:1883';
+    const mqttPort = mqttBroker.includes(':') ? mqttBroker.split(':').pop() : '1883';
+
     const context = {
         appName: config.name || 'GO-DUCK App',
         entities: entities,
         enums: enums,
-        openEntities: openEntities
+        openEntities: openEntities,
+        serverPort: config.server?.port || 8080,
+        grpcPort: grpcPort,
+        mqttPort: mqttPort
     };
 
     for (const page of pages) {

package/generators/postman.js

@@ -15,16 +15,16 @@ export const generatePostmanCollection = async (config, entities, outputDir, ope
         item: [],
         variable: [
             { key: "host", value: "localhost", type: "string" },
-            { key: "port", value: "8080", type: "string" },
+            { key: "port", value: String(config.server?.port || 8080), type: "string" },
             { key: "tenant", value: "tenant_1", type: "string" },
             { key: "token", value: "", type: "string" },
-            { key: "keycloak_url", value: "http://localhost:8180", type: "string" },
+            { key: "keycloak_url", value: config.security?.['keycloak-host'] || "http://localhost:8180", type: "string" },
             { key: "realm", value: config.security?.['keycloak-realm'] || 'master', type: "string" },
-            { key: "app_client_id", value: `${config.name}-app`, type: "string" },
-            { key: "service_client_id", value: `${config.name}-service`, type: "string" },
-            { key: "service_secret", value: "service-secret-123", type: "string" },
-            { key: "username", value: "admin", type: "string" },
-            { key: "password", value: "admin", type: "string" }
+            { key: "app_client_id", value: config.security?.['keycloak-app-client-id'] || `${config.name}-app`, type: "string" },
+            { key: "service_client_id", value: config.security?.['keycloak-service-client-id'] || `${config.name}-service`, type: "string" },
+            { key: "service_secret", value: config.security?.['keycloak-service-secret'] || "service-secret-123", type: "string" },
+            { key: "username", value: config.security?.['keycloak-admin-client-id'] || "admin", type: "string" },
+            { key: "password", value: config.security?.['keycloak-admin-secret'] || "admin", type: "string" }
         ]
     };
 

package/generators/swagger.js

@@ -14,7 +14,7 @@ export const generateSwaggerDocs = async (config, entities, outputDir, openEntit
             description: `Generated documentation for ${config.name} microservice`
         },
         servers: [
-            { url: 'http://localhost:8080', description: 'Local Development Server' }
+            { url: `http://localhost:${config.server?.port || 8080}`, description: 'Local Development Server' }
         ],
         paths: {},
         components: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "go-duck-cli",
-  "version": "1.1.15",
+  "version": "1.1.16",
   "description": "The Ultimate Evolutionary Go Microservice Scaffolder.",
   "main": "index.js",
   "type": "module",

package/templates/docs/index.html.hbs

@@ -60,7 +60,7 @@
                 <pre><code class="language-bash"># Start local infrastructure (DB, Redis, MQTT, Keycloak, Jaeger/OTel)
 docker-compose up -d
 
-# Run the Go app (starts on port 8080 by default)
+# Run the Go app (starts on port {{serverPort}} by default)
 go run main.go</code></pre>
             </section>
 
@@ -77,7 +77,7 @@ DELETE /api/{{#if entities.length}}{{toLowerCase entities.[0].name}}s{{else}}ent
 
                 <h3 class="font-semibold mb-2 mt-6">PostgREST-like Generic Search:</h3>
                 <p class="mb-2">We expose a dynamic search endpoint allowing powerful querying directly from the frontend.</p>
-                <pre><code class="language-bash">curl -X GET "http://localhost:8080/api/rpc/{{#if entities.length}}{{toLowerCase entities.[0].name}}{{else}}your_table{{/if}}?name=eq.John&age=gt.18" \
+                <pre><code class="language-bash">curl -X GET "http://localhost:{{serverPort}}/api/rpc/{{#if entities.length}}{{toLowerCase entities.[0].name}}{{else}}your_table{{/if}}?name=eq.John&age=gt.18" \
   -H "Authorization: Bearer YOUR_JWT" \
   -H "X-Tenant-ID: tenant_1"</code></pre>
                 <p class="text-sm text-gray-500 mt-2">Supported operators: <code>eq, neq, gt, gte, lt, lte, like, ilike</code></p>
@@ -88,10 +88,10 @@ DELETE /api/{{#if entities.length}}{{toLowerCase entities.[0].name}}s{{else}}ent
                 <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">Audit & Metering</h2>
                 <p class="mb-4">Entity mutations are automatically tracked via the <code>AuditMiddleware</code>. Usage limits per-tenant can be managed via the Metering API.</p>
                 <pre><code class="language-bash"># View Audit Logs
-curl -X GET http://localhost:8080/api/audit -H "Authorization: Bearer YOUR_JWT"
+curl -X GET http://localhost:{{serverPort}}/api/audit -H "Authorization: Bearer YOUR_JWT"
 
 # View Usage for Current Tenant
-curl -X GET http://localhost:8080/api/metering/usage -H "Authorization: Bearer YOUR_JWT" -H "X-Tenant-ID: my_tenant"</code></pre>
+curl -X GET http://localhost:{{serverPort}}/api/metering/usage -H "Authorization: Bearer YOUR_JWT" -H "X-Tenant-ID: my_tenant"</code></pre>
             </section>
 
             <!-- WebSockets -->
@@ -102,7 +102,7 @@ curl -X GET http://localhost:8080/api/metering/usage -H "Authorization: Bearer Y
                 <h3 class="font-semibold mb-2">Connecting via JS:</h3>
                 <pre><code class="language-javascript">const token = 'YOUR_JWT_TOKEN';
 // Pass token as query param for auth
-const ws = new WebSocket(`ws://localhost:8080/ws?token=${token}`);
+const ws = new WebSocket(`ws://localhost:{{serverPort}}/ws?token=${token}`);
 
 ws.onopen = () => {
   // Sending a signed Traced Envelope
@@ -123,14 +123,14 @@ ws.onmessage = (event) => console.log("Received:", event.data);</code></pre>
                 <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">MQTT Event Streaming</h2>
                 <p class="mb-4">Successful CRUD operations (Create, Update, Delete) are published as JSON payloads to the MQTT broker. This is perfect for webhooks, async processing, or triggering other microservices.</p>
                 <pre><code class="language-bash"># Using mosquitto_sub to listen to events
-mosquitto_sub -h localhost -p 1883 -t "go-duck/events/#" -u dev_user -P dev_password</code></pre>
+mosquitto_sub -h localhost -p {{mqttPort}} -t "go-duck/events/#" -u dev_user -P dev_password</code></pre>
                 <p class="text-sm mt-2">Example topic: <code>go-duck/events/{{#if entities.length}}{{toLowerCase entities.[0].name}}{{else}}entity{{/if}}/CREATE</code></p>
             </section>
 
             <!-- Kratos gRPC -->
             <section id="grpc-kratos" class="content-section">
                 <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">Kratos Secured gRPC APIs</h2>
-                <p class="mb-4">The application runs a Kratos gRPC server on <code>port 9000</code> by default, sharing the internal repository with Gin. It validates Keycloak JWTs via Kratos middleware.</p>
+                <p class="mb-4">The application runs a Kratos gRPC server on <code>port {{grpcPort}}</code> by default, sharing the internal repository with Gin. It validates Keycloak JWTs via Kratos middleware.</p>
                 <h3 class="font-semibold mb-2">Calling the gRPC Service (Go Client Example):</h3>
                 <pre><code class="language-go">import (
     "context"
@@ -143,7 +143,7 @@ mosquitto_sub -h localhost -p 1883 -t "go-duck/events/#" -u dev_user -P dev_pass
 // The JWT must be generated using the Keycloak secret configured in the app
 token := oauth.TokenSource{TokenSource: oauth2.StaticTokenSource(&oauth2.Token{AccessToken: "YOUR_JWT"})}
 
-conn, err := grpc.Dial("localhost:9000", grpc.WithInsecure(), grpc.WithPerRPCCredentials(token))
+conn, err := grpc.Dial("localhost:{{grpcPort}}", grpc.WithInsecure(), grpc.WithPerRPCCredentials(token))
 client := pb.New{{#if entities.length}}{{capitalize entities.[0].name}}{{else}}Entity{{/if}}ServiceClient(conn)
 
 // Execute Call
@@ -167,7 +167,7 @@ res, err := client.Get{{#if entities.length}}{{capitalize entities.[0].name}}{{e
   }
 }</code></pre>
                 <h3 class="font-semibold mb-2 mt-4">Example Request via Fetch:</h3>
-                <pre><code class="language-javascript">fetch('http://localhost:8080/graphql', {
+                <pre><code class="language-javascript">fetch('http://localhost:{{serverPort}}/graphql', {
   method: 'POST',
   headers: { 'Content-Type': 'application/json' },
   body: JSON.stringify({ query: 'query { list{{#if entities.length}}{{capitalize entities.[0].name}}s{{else}}Entities{{/if}} { id } }' })

package/templates/docs/pages/grpc.hbs

@@ -52,6 +52,14 @@ service {{capitalize (defaultStr (lookup entities "0.name") "Entity")}}Service {
             GO-DUCK scaffolds script files in the root of the generated project to manage the compilation of <code>.proto</code> contracts natively on all operating systems.
         </p>
 
+        <div class="mb-8 p-6 bg-slate-900 border border-slate-800 rounded-3xl text-white shadow-lg">
+            <h4 class="font-bold text-amber-400 mb-2 uppercase text-xs tracking-widest font-mono">⚡ Execution Requirement Guide</h4>
+            <ul class="list-disc pl-6 space-y-2 text-slate-300 text-sm leading-relaxed">
+                <li><strong>Local Host Execution (Required)</strong>: You must run the compilation script whenever you first create the microservice, or whenever you modify the GDL schemas and re-run <code>import-gdl</code> to generate updated gRPC structures.</li>
+                <li><strong>Docker Deployment (Automated)</strong>: If you compile and run the application via Docker (using <code>docker build</code> or <code>docker-compose</code>), the multi-stage <code>devops/Dockerfile</code> compiles the protobuf definitions internally, so you do not need to run the scripts locally.</li>
+            </ul>
+        </div>
+
         <div class="bg-white border border-slate-200 rounded-3xl p-8 shadow-sm mb-8">
             <h3 class="text-xl font-bold text-slate-800 mb-4 flex items-center">
                 🛠️ Scaffolded Compiler Scripts

package/templates/docs/pages/integrations.hbs

@@ -25,7 +25,7 @@ export interface {{capitalize (defaultStr (lookup entities "0.name") "Entity")}}
 
 @Injectable({ providedIn: 'root' })
 export class {{capitalize (defaultStr (lookup entities "0.name") "Entity")}}Service {
-  private apiUrl = 'http://localhost:8080/api/{{toLowerCase (defaultStr (lookup entities "0.name") "entity")}}s';
+  private apiUrl = 'http://localhost:{{serverPort}}/api/{{toLowerCase (defaultStr (lookup entities "0.name") "entity")}}s';
 
   constructor(private http: HttpClient) {}
 
@@ -40,7 +40,7 @@ export class {{capitalize (defaultStr (lookup entities "0.name") "Entity")}}Serv
   // Example: Using the powerful Generic Search RPC Engine
   search(queryField: string, operator: string, value: string): Observable<any> {
     let params = new HttpParams().set(queryField, \`\${operator}.\${value}\`);
-    return this.http.get<any>('http://localhost:8080/api/rpc/{{toLowerCase (defaultStr (lookup entities "0.name") "entity")}}', { params });
+    return this.http.get<any>('http://localhost:{{serverPort}}/api/rpc/{{toLowerCase (defaultStr (lookup entities "0.name") "entity")}}', { params });
   }
 }
 </code></pre>
@@ -55,7 +55,7 @@ import 'package:http/http.dart' as http;
 import 'package:flutter_secure_storage/flutter_secure_storage.dart';
 
 class ApiProvider {
-  static const String baseUrl = "http://localhost:8080/api/{{toLowerCase (defaultStr (lookup entities "0.name") "entity")}}s";
+  static const String baseUrl = "http://localhost:{{serverPort}}/api/{{toLowerCase (defaultStr (lookup entities "0.name") "entity")}}s";
   final storage = const FlutterSecureStorage();
 
   // Retrieve Keycloak Bearer token from secure storage

package/templates/docs/pages/mosquitto.hbs

@@ -26,7 +26,7 @@ messaging.Publish("events/users", event)</code></pre>
     <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">Local Development</h2>
     <p class="mb-4">Your <code>docker-compose.yml</code> includes a pre-configured Mosquitto image. You can use any MQTT client (like MQTT.fx or mosquitto_pub/sub) to listen to your service events.</p>
     <pre><code class="language-bash"># Subscribe to all audit events locally
-mosquitto_sub -h localhost -p 1883 -t "audit/logs/#" -v</code></pre>
+mosquitto_sub -h localhost -p {{mqttPort}} -t "audit/logs/#" -v</code></pre>
 </section>
 
 <section class="mb-10">

package/templates/docs/pages/realtime.hbs

@@ -3,7 +3,7 @@
 
 <section class="mb-10">
     <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">1. REST-over-WS Dispatcher</h2>
-    <p class="mb-4">Instead of traditional HTTP, you can pass highly efficient "Traced Envelopes" through our WebSocket endpoint at <code>ws://localhost:8080/ws</code>. The GO-DUCK generated engine unpacks the WS payload and routes it natively through Gin.</p>
+    <p class="mb-4">Instead of traditional HTTP, you can pass highly efficient "Traced Envelopes" through our WebSocket endpoint at <code>ws://localhost:{{serverPort}}/ws</code>. The GO-DUCK generated engine unpacks the WS payload and routes it natively through Gin.</p>
     
     <div class="bg-indigo-50 border-l-4 border-indigo-500 p-4 mb-6 rounded-r">
         <p class="text-indigo-900"><strong>Note:</strong> Token validation is done via query-param out of necessity due to websocket protocol limitations.</p>
@@ -13,7 +13,7 @@
     <pre><code class="language-javascript">const token = "eyJhbGciOi..."; // Valid Keycloak Access Token
 
 // Phase 1: Authentication happens precisely on the handshake (WSS Handshake via query param)
-const ws = new WebSocket(`ws://localhost:8080/ws?token=${token}`);
+const ws = new WebSocket(`ws://localhost:{{serverPort}}/ws?token=${token}`);
 
 ws.onopen = () => {
   // Phase 2: Send HMAC-SHA256 Signed Messages