go-duck-cli 1.1.12 → 1.1.14

package/README.md

@@ -74,6 +74,14 @@ GO-DUCK has officially reached the **375% Achievement Status**, evolving from a
 *   **SaaS Quota Engine**: Redis-backed API bandwidth tracking with dynamic, hierarchical limits (User vs. Role mapping).
 *   **Resilience Layer**: Sony/Gobreaker Integration + Zero-Trust Distributed Redis Rate Limiter.
 
+### 🗺️ System Topology & Identity Registry
+
+To prevent ID enumeration attacks and completely hide internal database names and structure, GO-DUCK implements a zero-trust **Triple-Identity Registry** (Role ↔ DB ↔ Opaque UUID):
+
+<p align="center">
+  <img src="https://goduck.theheavenscode.com/triple_identity_registry.png" alt="Triple-Identity Registry Topology" width="800"/>
+</p>
+
 ## 💾 Global Installation
 
 To get started with GO-DUCK CLI, install it globally via npm:
@@ -99,9 +107,42 @@ Follow these steps to create and run a new microservice with GO-DUCK:
 # 1. Create a new microservice
 go-duck create -o ./my-app -c config.yaml
 
-# 2. Enter the application directory and run
+# 2. Enter the application directory
 cd my-app
+```
+
+### 🏗️ Compiling Protobuf & gRPC Contracts
+
+Before running the microservice, compile the protobuf contract files using the scaffolded scripts:
+
+#### Prerequisites
+1. Ensure the `protoc` compiler is installed and added to your system's `PATH`.
+2. Install the necessary Go compiler plugins:
+   ```cmd
+   go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
+   go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
+   ```
+
+#### Compilation
+Execute the script corresponding to your operating system in the root of the generated microservice directory:
+
+*   **Windows CMD / PowerShell**:
+    ```cmd
+    .\generate.bat
+    ```
+*   **Linux / macOS / Git Bash / WSL**:
+    ```bash
+    chmod +x generate.sh
+    ./generate.sh
+    ```
+
+Once compiled, launch the dependencies and start the application:
+
+```bash
+# 3. Spin up dependent services
 docker-compose up -d
+
+# 4. Run the Go application
 go run main.go
 ```
 
@@ -149,44 +190,118 @@ go-duck import-gdl new-entities.gdl -o my-existing-app
 
 ## GoDuck Definition Language (GDL)
 
-GDL is a simple language for defining your application's entities, fields, and relationships.
+GDL is a clean DSL for defining your application's entities, enums, fields, nested document structures, relationships, and public/auth boundaries.
 
 **Example (`app.gdl`):**
 
 ```gdl
-entity Author {
-  name String required
-  email String unique
+// ==============================================================================
+// 🦆 GO-DUCK ELITE DEALERSHIP BLUEPRINT
+// ==============================================================================
+
+/**
+ * Car: Relational Entity stored in PostgreSQL.
+ * @Searchable: Enable Spring-style fuzzy search on make/model.
+ * @Federated: Synchronize history across all dealership siloes.
+ * @Audited: Track every modification with Zero-Trust Keycloak IDs.
+ */
+@Searchable @Federated @Audited
+entity Car {
+    string(100) make     required
+    string(100) model    required
+    int(32)     year     required
+    bigdecimal  price
+    string(50)  vin      unique
+    jsonb       metadata
 }
 
-entity Book {
-  title String required
-  publishedDate LocalDate
+/**
+ * Patient: MongoDB Document Entity.
+ * @Document: Stored in MongoDB instead of PostgreSQL.
+ */
+@Document
+entity Patient {
+    string name required
+    clinicalData {
+        vitals {
+            int bpm
+            float temp
+        }
+        history [String]
+    }
 }
 
+/**
+ * ArticleStatus: Native Enum Support.
+ * GO-DUCK generates Go Enums, GraphQL Enums, and Proto definitions.
+ */
+enum ArticleStatus {
+    DRAFT, PUBLISHED, ARCHIVED
+}
+
+// 🦆 RELATIONSHIPS: Build the Graph
 relationship OneToMany {
-  Author{books} to Book{author}
+    Customer{car} to Car{owner}
 }
+
+// 🦆 SECURITY: Define Public/Auth Access
+open Car(read)
 ```
 
 ## Configuration (`config.yaml`)
 
-The `config.yaml` file contains the configuration for your generated application.
+The `config.yaml` file configures the scaffolding engine and generated Go bootstrap files. It must start with the top-level `go-duck` block.
 
 ```yaml
-app:
-  name: my-app
+go-duck:
+  name: "my-app"
+  version: "1.0.0"
+  description: "GO-DUCK Scaffolded Microservice"
+  
+  # --- Network & Server Layer ---
+  server:
+    port: 8080
+    grpc:
+      addr: ":9000"
+      network: "tcp"
+      timeout: "1s"
+    cors:
+      allow-origins: ["*"]
+      allow-methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]
+      allow-headers: ["Origin", "Content-Type", "Accept", "Authorization", "X-Tenant-ID"]
+      
+  # --- Persistence Layer (Hybrid Store) ---
   datasource:
-    host: localhost
+    # PostgreSQL (Relational Registry & Entity Store)
+    host: "localhost"
     port: 5432
-    username: user
-    password: password
-    database: my_app_db
+    username: "postgres"
+    password: "password"
+    database: "my_app_db"
+    ssl-mode: "disable"
+    # MongoDB (Document Entity Store)
+    mongodb:
+      enabled: true
+      uri: "mongodb://localhost:27017"
+      database: "my_app_mongo"
+      
+  # --- Security & Identity (Keycloak/OIDC) ---
+  security:
+    keycloak-host: "http://localhost:8080"
+    keycloak-realm: "my-realm"
+    keycloak-app-client-id: "my-app"
+    keycloak-service-client-id: "my-service"
+    keycloak-service-secret: "service-secret-123"
+    super-admin-role: "admin"
+    confidential-mode: true
+    rate-limit:
+      rps: 100
+      burst: 200
+
+  # --- Federated Multi-Tenancy ---
   multitenancy:
     enabled: true
-  security:
-    jwt:
-      secret: "your-jwt-secret"
+    hide-silo-names: false
 ```
 
 ## License

package/generators/kratos.js

@@ -213,9 +213,29 @@ find api -name "*.proto" -exec protoc --proto_path=. \\
         {} +
 
 echo "✅ Protos compiled successfully!"
+`;
+    const generateBat = `@echo off
+echo 🦆 Syncing Protobuf Dependencies...
+if not exist "third_party\\google\\api" mkdir "third_party\\google\\api"
+curl -sSL https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/annotations.proto > third_party\\google\\api\\annotations.proto
+curl -sSL https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/http.proto > third_party\\google\\api\\http.proto
+
+echo 🏗️ Compiling API Layer...
+where protoc >nul 2>nul
+if %errorlevel% neq 0 (
+    echo ❌ Error: 'protoc' not found. Please install protobuf and add it to your PATH.
+    exit /b 1
+)
+
+for /f "tokens=*" %%f in ('dir /b /s api\\*.proto') do (
+    protoc --proto_path=. --proto_path=./api --proto_path=./third_party --go_out=paths=source_relative:. --go-grpc_out=paths=source_relative:. "%%f"
+)
+
+echo ✅ Protos compiled successfully!
 `;
     await fs.writeFile(path.join(projectRootDir, 'generate.sh'), generateSh);
     await fs.chmod(path.join(projectRootDir, 'generate.sh'), 0o755);
+    await fs.writeFile(path.join(projectRootDir, 'generate.bat'), generateBat);
 
     console.log(chalk.green('✅ Kratos gRPC code generated successfully!'));
 };

package/package.json

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

package/templates/docs/pages/grpc.hbs

@@ -45,6 +45,51 @@ service {{capitalize (defaultStr (lookup entities "0.name") "Entity")}}Service {
         </div>
     </section>
 
+    <!-- Compiling Protobuf Contracts -->
+    <section class="mb-20">
+        <h2 class="text-3xl font-black text-slate-900 mb-6 tracking-tight italic underline decoration-blue-200 underline-offset-8">Compiling Protobuf & gRPC Contracts</h2>
+        <p class="text-lg text-slate-600 mb-8 leading-relaxed">
+            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="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
+            </h3>
+            <p class="text-slate-600 mb-4">The generator scaffolds both <code>generate.sh</code> and <code>generate.bat</code> files in the project root. At compilation time, they perform the following tasks:</p>
+            <ul class="list-disc pl-6 space-y-2 text-slate-600 mb-6">
+                <li>Create the <code>third_party/google/api</code> dependencies directory.</li>
+                <li>Synchronize necessary Google API annotation contracts (<code>annotations.proto</code> and <code>http.proto</code>) using native command line transfers.</li>
+                <li>Recursively find and compile all <code>.proto</code> files inside <code>api/</code> into Go source files using the <code>protoc</code> compiler.</li>
+            </ul>
+
+            <h3 class="text-xl font-bold text-slate-800 mb-4 flex items-center">
+                🚀 How to Compile
+            </h3>
+            <p class="text-slate-600 mb-4">To compile the contract schemas into Go source structures, execute the following commands in the root of your generated application:</p>
+            
+            <div class="grid grid-cols-1 md:grid-cols-2 gap-6">
+                <div class="p-6 bg-slate-50 rounded-2xl border border-slate-200">
+                    <span class="text-xs font-black text-blue-600 uppercase tracking-widest block mb-2">Windows (CMD / PowerShell)</span>
+                    <pre class="bg-slate-900 text-slate-100 p-4 rounded-xl text-xs font-mono">.\generate.bat</pre>
+                </div>
+                <div class="p-6 bg-slate-50 rounded-2xl border border-slate-200">
+                    <span class="text-xs font-black text-emerald-600 uppercase tracking-widest block mb-2">Unix / Linux / macOS</span>
+                    <pre class="bg-slate-900 text-slate-100 p-4 rounded-xl text-xs font-mono">chmod +x generate.sh<br>./generate.sh</pre>
+                </div>
+            </div>
+
+            <div class="mt-8 p-6 bg-blue-50 rounded-2xl border border-blue-100">
+                <h4 class="font-bold text-blue-900 mb-2">📌 Compilation Prerequisites</h4>
+                <p class="text-blue-800 text-sm leading-relaxed mb-4">
+                    Ensure you have the <code>protoc</code> binary installed and added to your system's <code>PATH</code>.
+                </p>
+                <p class="text-blue-800 text-sm leading-relaxed mb-2">Also ensure the necessary Go compiler plugins are installed on your environment:</p>
+                <pre class="bg-slate-900 text-slate-100 p-4 rounded-xl text-xs font-mono">go install google.golang.org/protobuf/cmd/protoc-gen-go@latest<br>go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest</pre>
+            </div>
+        </div>
+    </section>
+
     <!-- Silo-Aware Repository Wrapper -->
     <section class="mb-20">
         <div class="bg-gradient-to-r from-blue-950 to-blue-900 border border-blue-800/50 rounded-[2.5rem] p-16 text-white text-center shadow-2xl relative overflow-hidden group">