go-duck-cli 1.1.13 → 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
 ```
 

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.13",
+  "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">