go-duck-cli 1.0.9 → 1.1.12

package/templates/docs/pages/grpc.hbs

@@ -1,100 +1,63 @@
-<div class="mb-10 border-b border-slate-200 pb-8">
-    <div class="inline-flex items-center px-3 py-1 rounded-full bg-rose-100 text-rose-700 text-xs font-semibold tracking-wide uppercase mb-4">
-        Protocol Buffer APIs
-    </div>
-    <h1 class="text-4xl font-extrabold text-slate-900 tracking-tight mb-4">Secured Kratos gRPC APIs</h1>
-    <p class="text-lg text-slate-600">Access the generated microservices over ultra-fast gRPC using Kratos framework, fully authenticated by Keycloak.</p>
-</div>
-
-<section class="mb-10">
-    <h2 class="text-2xl font-bold text-slate-800 mb-6 flex items-center">
-        <span class="w-8 h-8 rounded-lg bg-slate-100 text-slate-600 flex items-center justify-center mr-3 text-sm">
-            <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 10V3L4 14h7v7l9-11h-7z"></path></svg>
-        </span>
-        Overview
-    </h2>
-    <p class="mb-4 text-slate-600 leading-relaxed">The GO-DUCK CLI generated app binds the Gin REST webserver on port 8080 and simultaneously spins up an optimized <strong>Go-Kratos</strong> gRPC listener on <code class="bg-slate-100 px-1.5 py-0.5 rounded text-slate-800 font-mono text-sm">port 9000</code>. Both the REST and gRPC handlers share the exact same clean <code>Repository</code> architecture underneath, guaranteeing 100% data and logic consistency.</p>
-    
-    <div class="bg-emerald-50/80 border border-emerald-200 p-5 mt-6 rounded-xl flex items-start shadow-sm">
-        <svg class="w-6 h-6 text-emerald-500 mt-0.5 mr-3 flex-shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"></path></svg>
-        <div>
-            <h4 class="font-semibold text-emerald-900 mb-1">Automatic Compilation</h4>
-            <p class="text-emerald-800 text-sm leading-relaxed"><code class="bg-emerald-100 text-emerald-900 px-1 py-0.5 rounded">api/v1/*.proto</code> definitions are generated automatically whenever you add an entity or change fields.</p>
+<div class="prose prose-slate max-w-none">
+    <div class="flex items-center space-x-3 mb-8 text-blue-700">
+        <div class="p-4 bg-gradient-to-br from-blue-600 to-blue-800 rounded-2xl shadow-lg shadow-blue-200">
+            <svg class="w-8 h-8 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 10V3L4 14h7v7l9-11h-7z" />
+            </svg>
         </div>
+        <h1 class="text-5xl font-black text-slate-900 m-0 tracking-tighter leading-none">Scaffolding gRPC <br><span class="text-blue-600 italic leading-snug">The Kratos Connection.</span></h1>
     </div>
-</section>
 
-<section class="mb-12">
-    <h2 class="text-2xl font-bold text-slate-800 mb-6 flex items-center">
-        <span class="w-8 h-8 rounded-lg bg-indigo-100 text-indigo-600 flex items-center justify-center mr-3 text-sm">
-            <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m5.618-4.016A11.955 11.955 0 0112 2.944a11.955 11.955 0 01-8.618 3.04A12.02 12.02 0 003 9c0 5.591 3.824 10.29 9 11.622 5.176-1.332 9-6.03 9-11.622 0-1.042-.133-2.052-.382-3.016z"></path></svg>
-        </span>
-        Client Connection Example (Go)
-    </h2>
-    <p class="mb-6 text-slate-600 leading-relaxed">This snippet demonstrates how a developer orchestrating another microservice connects securely using Google's <code class="bg-slate-100 px-1.5 py-0.5 rounded text-slate-800 font-mono text-sm">clientcredentials</code> to fulfill the Kratos Auth Header standards.</p>
-    
-    <div class="bg-blue-50/80 border border-blue-200 p-5 mt-6 mb-6 rounded-xl flex items-start shadow-sm">
-        <svg class="w-6 h-6 text-blue-500 mt-0.5 mr-3 flex-shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"></path></svg>
-        <div>
-            <h4 class="font-semibold text-blue-900 mb-1">Crucial Architecture Note (Server-to-Server)</h4>
-            <p class="text-blue-800 text-sm leading-relaxed mb-2">If an event triggers a gRPC call asynchronously in the background (meaning there is NO active human user pushing a token from a frontend), the calling microservice must authenticate itself using a <strong>Keycloak Service Account</strong>.</p>
-            <p class="text-blue-800 text-sm leading-relaxed">The calling server sends its own <code class="bg-blue-100 px-1 py-0.5 rounded">Client ID</code> and <code class="bg-blue-100 px-1 py-0.5 rounded">Client Secret</code> directly to Keycloak's Token Endpoint using the <strong>Client Credentials Grant</strong> flow. Keycloak responds with a valid JWT representing the "Server", which is then injected into the gRPC dialer below.</p>
+    <p class="text-2xl text-slate-500 font-medium mb-12 leading-relaxed">
+        Experience blazing-fast, binary-efficient communication between your services. GO-DUCK automatically generates production-ready gRPC schemas and Kratos service implementations for every GDL entity.
+    </p>
+
+    <!-- Key Performance Block -->
+    <div class="grid grid-cols-1 md:grid-cols-2 gap-8 mb-20 px-4">
+        <div class="p-8 bg-blue-50 rounded-[2rem] border border-blue-100 shadow-sm border-l-[1rem] border-l-blue-600">
+            <h5 class="font-black text-blue-900 mb-2 uppercase text-xs tracking-widest italic tracking-wide">Protobuf First</h5>
+            <p class="text-sm text-blue-800 leading-relaxed font-medium italic">Auto-generated <code>.proto</code> files with deep field validation and secure gRPC-Gateway metadata definitions.</p>
+        </div>
+        <div class="p-8 bg-blue-50 rounded-[2rem] border border-blue-100 shadow-sm border-l-[1rem] border-l-indigo-600">
+            <h5 class="font-black text-blue-900 mb-2 uppercase text-xs tracking-widest italic tracking-wide">Kratos secured</h5>
+            <p class="text-sm text-blue-800 leading-relaxed font-medium italic">OIDC/JWT authentication interceptors baked directly into the Kratos middleware for every generated gRPC service.</p>
         </div>
     </div>
-    
-    <div class="bg-[#1e1e1e] rounded-xl overflow-hidden shadow-xl mb-4">
-        <div class="bg-[#2d2d2d] px-4 py-2 border-b border-[#404040] flex items-center justify-between">
-            <div class="flex items-center">
-                <div class="flex space-x-1.5 mr-4">
-                    <div class="w-3 h-3 rounded-full bg-rose-500"></div>
-                    <div class="w-3 h-3 rounded-full bg-amber-500"></div>
-                    <div class="w-3 h-3 rounded-full bg-emerald-500"></div>
+
+    <!-- The Proto Lifecycle -->
+    <section class="mb-20">
+        <h2 class="text-3xl font-black text-slate-900 mb-10 tracking-tight italic text-center underline decoration-blue-200 underline-offset-8">The Protobuf Lifecycle</h2>
+        <div class="space-y-6">
+            <div class="bg-slate-900 rounded-[2.5rem] p-10 text-white shadow-2xl relative overflow-hidden flex flex-col md:flex-row gap-12 group transition-all duration-300">
+                <div class="flex-grow p-6 bg-slate-800/50 rounded-3xl border border-slate-700/50 backdrop-blur-sm self-center">
+                    <pre class="text-xs text-blue-300 leading-relaxed whitespace-pre font-mono italic">
+<span class="text-slate-500">// Generated Service Schema for {{capitalize (defaultStr (lookup entities "0.name") "Entity")}}</span>
+service {{capitalize (defaultStr (lookup entities "0.name") "Entity")}}Service {
+  rpc Get (Get{{capitalize (defaultStr (lookup entities "0.name") "Entity")}}Request) returns ({{capitalize (defaultStr (lookup entities "0.name") "Entity")}}Reply) {
+    option (google.api.http) = {
+      get: "/v1/{{toLowerCase (defaultStr (lookup entities "0.name") "entity")}}/{id}"
+    };
+  }
+}
+                    </pre>
                 </div>
-                <span class="text-xs text-slate-300 font-mono">grpc_client.go</span>
             </div>
-            <span class="text-[10px] text-slate-400 font-bold uppercase tracking-widest">Go</span>
         </div>
-        <div class="p-5 overflow-x-auto text-sm">
-<pre><code class="language-go">import (
-    "context"
-    "log"
-    "google.golang.org/grpc"
-    "golang.org/x/oauth2/clientcredentials"
-    pb "{{appName}}/api/v1"
-)
-
-func main() {
-    // 1. Configure the Client Credentials Flow
-    // These values should match your go-duck.security block in application-dev.yml
-    config := clientcredentials.Config{
-        ClientID:     "internal",       // Matches keycloak-client-id
-        ClientSecret: "internal",       // Matches keycloak-secret
-        TokenURL:     "http://localhost:9080/realms/master/protocol/openid-connect/token",
-    }
+    </section>
 
-    // 2. Fetch the token dynamically from Keycloak
-    tokenSource := config.TokenSource(context.Background())
-
-    // 3. Dial the local port 9000 (GoDuck Server)
-    // grpc.WithPerRPCCredentials injects the automatically updating token into every request!
-    conn, err := grpc.Dial("localhost:9000", grpc.WithInsecure(), grpc.WithPerRPCCredentials(tokenSource))
-    if err != nil {
-        log.Fatalf("did not connect: %v", err)
-    }
-    defer conn.Close()
-
-    // 4. Initialize the Kratos-generated gRPC Client
-    client := pb.New{{capitalize (defaultStr (lookup entities "0.name") "Entity")}}ServiceClient(conn)
-
-    // 5. Execute Native Network Call over gRPC
-    res, err := client.Get{{capitalize (defaultStr (lookup entities "0.name") "Entity")}}(context.Background(), &pb.Get{{capitalize (defaultStr (lookup entities "0.name") "Entity")}}Request{Id: 1})
-    if err != nil {
-        log.Fatalf("RPC failed: %v", err)
-    }
-    
-    log.Printf("Successfully Received Data Pipeline Object OVER gRPC: %v", res)
-}
-</code></pre>
+    <!-- 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">
+            <h2 class="text-4xl font-black mb-6 tracking-tight italic underline decoration-blue-500 underline-offset-8">Federated gRPC Resolution</h2>
+            <p class="text-blue-100 text-lg mb-10 max-w-2xl mx-auto leading-relaxed italic font-medium">
+                Our gRPC implementation is natively silo-aware. It uses the same <strong>Repository Layer</strong> as the REST controllers—ensuring that every RPC call is routed to the correct database silo based on the caller's JWT role.
+            </p>
+            <div class="flex flex-col md:flex-row gap-6 justify-center">
+                <div class="px-8 py-4 bg-white/10 rounded-2xl border border-white/10 flex flex-col items-center hover:bg-white/20 transition-all duration-300 cursor-default shadow-md group-hover:scale-110">
+                    <span class="text-blue-400 font-black text-2xl uppercase italic font-mono">100% Binary</span>
+                    <span class="text-[0.6rem] text-white/50 tracking-[0.2em] font-bold uppercase mt-2">Maximum Throughput</span>
+                </div>
+            </div>
         </div>
-    </div>
-</section>
+    </section>
+</div>

package/templates/docs/pages/hybrid-store.hbs

@@ -0,0 +1,127 @@
+<div class="prose prose-slate max-w-none">
+    <!-- Hybrid-Store Hero -->
+    <div class="flex items-center space-x-3 mb-10 text-emerald-700">
+        <div class="p-4 bg-gradient-to-br from-emerald-600 to-emerald-800 rounded-3xl shadow-xl shadow-emerald-100">
+            <svg class="w-10 h-10 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 11H5m14 0a2 2 0 012 2v6a2 2 0 01-2 2H5a2 2 0 01-2-2v-6a2 2 0 012-2m14 0V9a2 2 0 00-2-2M5 11V9a2 2 0 012-2m0 0V5a2 2 0 012-2h6a2 2 0 012 2v2M7 7h10" />
+            </svg>
+        </div>
+        <div>
+            <h1 class="text-4xl font-black text-slate-900 m-0 tracking-tight leading-none">Hybrid-Store Architecture</h1>
+            <p class="text-emerald-600 font-bold tracking-widest uppercase text-[10px] mt-2 ml-1">SQL + NoSQL Heterogeneous Persistence</p>
+        </div>
+    </div>
+
+    <p class="text-xl text-slate-600 mb-12 italic border-l-4 border-emerald-500 pl-6 leading-relaxed">
+        GO-DUCK represents the pinnacle of modern persistence strategy, enabling the seamless coexistence of <strong>PostgreSQL</strong> (for relational logic) and <strong>MongoDB</strong> (for high-velocity document storage) within a single microservice.
+    </p>
+
+    <!-- CORE CONCEPTS -->
+    <div class="grid grid-cols-1 md:grid-cols-3 gap-6 mb-16">
+        <div class="p-6 bg-white rounded-3xl border border-slate-100 shadow-sm">
+            <h4 class="text-emerald-700 font-black mb-2 uppercase text-xs tracking-widest">PostgreSQL Core</h4>
+            <p class="text-sm text-slate-500 italic leading-relaxed">Default store for system registries, billing, and relational entities requiring strict ACID compliance.</p>
+        </div>
+        <div class="p-6 bg-white rounded-3xl border border-slate-100 shadow-sm">
+            <h4 class="text-emerald-700 font-black mb-2 uppercase text-xs tracking-widest">MongoDB Engine</h4>
+            <p class="text-sm text-slate-500 italic leading-relaxed">Triggered via <code>@isDocument</code>. Handles nested JSON structures and high-throughput document access.</p>
+        </div>
+        <div class="p-6 bg-white rounded-3xl border border-slate-100 shadow-sm">
+            <h4 class="text-emerald-700 font-black mb-2 uppercase text-xs tracking-widest">Unified Repository</h4>
+            <p class="text-sm text-slate-500 italic leading-relaxed">A single internal interface abstracts both engines, ensuring logic parity across REST and gRPC.</p>
+        </div>
+    </div>
+
+    <!-- TECHNICAL DEEP DIVE -->
+    <h2 class="text-2xl font-black text-slate-900 mb-6 tracking-tight">1. Cross-Database Soft Relationships</h2>
+    <p class="mb-8 leading-relaxed text-slate-600">
+        One of the most complex challenges in hybrid architectures is maintaining relationships across different database engines. GO-DUCK solves this with <strong>Dynamic ID Mapping</strong>:
+    </p>
+
+    <div class="bg-slate-900 rounded-[2.5rem] p-10 text-white mb-16 shadow-2xl relative overflow-hidden group">
+        <div class="absolute inset-0 bg-gradient-to-br from-emerald-900/30 to-transparent"></div>
+        <div class="relative z-10">
+            <div class="bg-slate-800/80 rounded-2xl p-6 border border-white/10 mb-8">
+                <pre><code class="font-mono text-sm leading-relaxed text-emerald-300"><span class="text-slate-500">// Relationship across SQL and MongoDB</span>
+entity User {  <span class="text-slate-500">// PostgreSQL (relational)</span>
+    string email required
+    [Profile] profiles
+}
+
+<span class="text-emerald-500">@isDocument</span>
+entity Profile { <span class="text-slate-500">// MongoDB (document)</span>
+    string bio
+    string avatar
+    User owner
+}</code></pre>
+            </div>
+            <p class="text-slate-400 text-sm italic leading-relaxed m-0 border-l border-emerald-500/30 pl-6">
+                GO-DUCK automatically detects that <code>Profile</code> is NoSQL and <code>User</code> is SQL. It generates a <code>uint64</code> owner ID in MongoDB and a <code>string</code> profile pointer in SQL, handling all casting and <code>gorm:"-"</code> shielding automatically.
+            </p>
+        </div>
+    </div>
+
+    <h2 class="text-2xl font-black text-slate-900 mb-6 tracking-tight">2. Federated Parallel Harvester 2.0</h2>
+    <p class="mb-8 leading-relaxed text-slate-600">
+        When executing multi-tenant "Harvest" operations (e.g., getting all Users across 50 authorized silos), GO-DUCK uses <strong>Heterogeneous Parallel Execution</strong>.
+    </p>
+
+    <div class="p-8 bg-blue-50 rounded-[2rem] border border-blue-100 mb-16">
+        <div class="flex items-start gap-6">
+            <div class="w-16 h-16 bg-white rounded-2xl flex items-center justify-center text-3xl shadow-sm">🚀</div>
+            <div>
+                <h4 class="text-lg font-black text-blue-900 m-0 uppercase tracking-tighter">Concurrency Paradigm</h4>
+                <p class="text-sm text-blue-700 italic mt-2 leading-relaxed">
+                    The Harvester spawns goroutines that simultaneously query PostgreSQL and MongoDB silos. Results are aggregated into a single, unified response stream, regardless of the underlying storage engine for each entity.
+                </p>
+            </div>
+        </div>
+    </div>
+
+    <h2 class="text-2xl font-black text-slate-900 mb-6 tracking-tight">3. BSON & Recursive GDL Support</h2>
+    <p class="mb-8 leading-relaxed text-slate-600">
+        Entities marked with <code>@isDocument</code> support deep nested brace structures in GDL, which map directly to recursive BSON tags in Go:
+    </p>
+
+    <div class="bg-slate-100 rounded-3xl p-8 mb-16 border border-slate-200">
+        <table class="w-full text-left">
+            <thead>
+                <tr class="border-b border-slate-300">
+                    <th class="pb-4 font-black text-slate-900 uppercase text-xs tracking-widest">Storage Engine</th>
+                    <th class="pb-4 font-black text-slate-900 uppercase text-xs tracking-widest">ID Type</th>
+                    <th class="pb-4 font-black text-slate-900 uppercase text-xs tracking-widest">Key Mapping</th>
+                </tr>
+            </thead>
+            <tbody class="text-slate-600 text-sm italic">
+                <tr class="border-b border-slate-200">
+                    <td class="py-4 font-bold text-slate-900">PostgreSQL</td>
+                    <td class="py-4"><code>uint64</code></td>
+                    <td class="py-4">GORM Primary Key / Auto-Increment</td>
+                </tr>
+                <tr>
+                    <td class="py-4 font-bold text-emerald-600">MongoDB</td>
+                    <td class="py-4"><code>string</code></td>
+                    <td class="py-4">BSON <code>primitive.ObjectID</code> (hex-mapped)</td>
+                </tr>
+            </tbody>
+        </table>
+    </div>
+
+    <!-- NEXT STEPS -->
+    <div class="flex flex-col md:flex-row gap-4 mb-20">
+        <a href="federation.html" class="flex-1 p-6 bg-slate-900 rounded-2xl text-white hover:bg-slate-800 transition-colors group">
+            <div class="text-xs font-bold text-slate-500 uppercase tracking-widest mb-2">Previous Category</div>
+            <div class="text-xl font-bold flex items-center">
+                <svg class="w-5 h-5 mr-2 group-hover:-translate-x-1 transition-transform" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M11 17l-5-5m0 0l5-5m-5 5h12" /></svg>
+                🌐 Federated Architecture
+            </div>
+        </a>
+        <a href="serverless.html" class="flex-1 p-6 bg-emerald-700 rounded-2xl text-white hover:bg-emerald-800 transition-colors group text-right">
+            <div class="text-xs font-bold text-emerald-200 uppercase tracking-widest mb-2">Next Category</div>
+            <div class="text-xl font-bold flex items-center justify-end">
+                🚀 Serverless Docs
+                <svg class="w-5 h-5 ml-2 group-hover:translate-x-1 transition-transform" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 7l5 5m0 0l-5 5m5-5H6" /></svg>
+            </div>
+        </a>
+    </div>
+</div>