go-duck-cli 1.2.11 → 1.3.0

package/README.md

@@ -13,6 +13,7 @@
 <p align="center">
   <a href="https://badge.fury.io/js/go-duck-cli"><img src="https://badge.fury.io/js/go-duck-cli.svg" alt="npm version"></a>
   <a href="https://opensource.org/licenses/ISC"><img src="https://img.shields.io/badge/License-ISC-blue.svg" alt="License: ISC"></a>
+  ![Version](https://img.shields.io/badge/version-1.2.25-blue)
 </p>
 
 ---
@@ -64,6 +65,8 @@ GO-DUCK has officially reached the **410% Achievement Status**, evolving from a
 ### ✨ Primary Features (The 410% Core)
 
 *   **Federated Multi-Tenancy**: Side-by-side **Database-per-Tenant isolation** with a **Master-Tenant Registry** (Role ↔ DB ↔ Opaque UUID).
+*   **Multi-Protocol REST**: Dynamically switchable REST rendering using standard `json` or high-performance `messagepack` based on configuration.
+*   **gRPC-Web Native Proxy**: Natively wraps Kratos gRPC to automatically serve a web proxy (e.g. on port `9090`) to allow direct frontend Protobuf interaction.
 *   **Industrial-Grade Parallel Harvester**: Asynchronous goroutine-based data aggregation across multiple silos with `?federated=true` opt-in.
 *   **Precision Harvesting**: Surgical multi-silo selection via comma-separated `X-Tenant-ID` headers.
 *   **Super Admin Security Boundaries**: Strict architectural separation between Business APIs and Infrastructure Control APIs.
@@ -104,16 +107,61 @@ Ensure your development environment meets the following requirements:
 *   **Docker:** v20+
 *   **Composability:** v2+
 
+## Quick‑Start
+
+Follow these four steps to get a generated microservice running locally and in Kubernetes:
+
+1. **Create**: `go-duck create -o ./my-app -c config.yaml`
+2. **Enter**: `cd my-app`
+3. **Build & Push**: `./push.sh my-registry/my-app:1.0.0`
+4. **Deploy**: `kubectl apply -f devops/k8s/`
+
 ## 🚀 Scaffold & Run
 
 Follow these steps to create and run a new microservice with GO-DUCK:
 
+```bash
+# 0. Design your schema visually (Optional)
+go-duck gdl-planner -p 8000
+```
+This launches a browser-based drag-and-drop canvas at `http://localhost:8000` where you can visually design your entities, relationships, nested BSON objects, and Enums, and then export it directly into a `.gdl` file!
+
 ```bash
 # 1. Create a new microservice
 go-duck create -o ./my-app -c config.yaml
 
 # 2. Enter the application directory
 cd my-app
+
+# 3. Build, tag, and push Docker image (updates app.yaml)
+./push.sh my-registry/my-app:1.0.0
+
+# 4. Deploy to Kubernetes
+kubectl apply -f devops/k8s/
+
+### 🚢 Deploy to Kubernetes & Push Images
+
+The generated project includes a **devops/k8s** directory with ready‑to‑apply Kubernetes manifests:
+
+- `mongo.yaml` – StatefulSet & Service for MongoDB.
+- `minio.yaml` – Deployment & Service for MinIO object storage.
+- `app.yaml` – Deployment for the generated Go microservice, referencing a placeholder image name (`<app‑name>:latest`). Replace the image with the tag you push.
+
+A helper script **push.sh** (located at the project root) automates the Docker build, tag, push, and then updates the `app.yaml` image field:
+
+```bash
+./push.sh my-registry/my-app:1.0.0
+```
+
+After pushing, deploy everything with:
+
+```bash
+kubectl apply -f devops/k8s/
+```
+
+> [!NOTE]
+> The K8s manifests use placeholder values (e.g., resource limits, storage class). Adjust them to match your cluster requirements before applying.
+
 ```
 
 ### 🏗️ Compiling Protobuf & gRPC Contracts
@@ -156,6 +204,37 @@ docker-compose up -d
 go run main.go
 ```
 
+## 🌐 Calling the Multi-Protocol Endpoints
+
+GO-DUCK automatically exposes your microservice across three distinct ports to serve different architectural needs without code duplication:
+
+1. **REST API (Port 8080 by default)**
+   Standard HTTP endpoints for web browsers and legacy clients.
+   - **JSON (Default):** Perfect for general use.
+   - **MessagePack (High Performance):** To switch to binary MessagePack, update your `config.yaml` before generation:
+     ```yaml
+     server:
+       rest:
+         port: 8080
+         protocol: "messagepack"
+     ```
+     Clients must send the `Accept: application/msgpack` and `Content-Type: application/msgpack` headers to consume this endpoint correctly.
+   - **Pagination & Sorting:** All `GetAll` endpoints support pagination via `?page=1&size=20`, and dynamic sorting via `?sort=field,asc` or `?sort=field,desc` (e.g. `?sort=name,desc`).
+
+2. **Native Kratos gRPC (Port 9000 by default)**
+   Pure HTTP/2 Protobuf communication. Used strictly for internal **backend-to-backend** communication (e.g., Microservice A calling Microservice B) where maximum throughput is required.
+
+3. **gRPC-Web Proxy (Port 9090 by default)**
+   Web browsers cannot speak raw HTTP/2 gRPC. This port acts as an HTTP/1.1 proxy bridge, allowing frontend frameworks (React, Angular, Vue) to interact directly with the Protobuf gRPC contracts.
+   To disable or change the proxy port, update your `config.yaml`:
+   ```yaml
+   server:
+     grpc:
+       web_enabled: true
+       web_port: 9090
+   ```
+   *Frontend Tip: Use the `grpc-web` npm package to generate a frontend client that communicates with this port!*
+
 ## Usage
 
 The `go-duck-cli` has two main commands: `create` and `import-gdl`.

package/generators/ai_docs.js

@@ -52,7 +52,7 @@ export const generateAIDocs = async (config, entities, outputDir, enums, openEnt
     for (const entity of entities) {
         const routeName = entity.name.toLowerCase() + 's';
         endpointsContent += `\n#### ${entity.name}\n`;
-        endpointsContent += `- \`GET /api/${routeName}\` (Pagination, e.g. \`?page=1&size=10&eager=true\`)\n`;
+        endpointsContent += `- \`GET /api/${routeName}\` (Pagination & dynamic sorting, e.g. \`?page=1&size=10&eager=true&sort=id,asc\`)\n`;
         endpointsContent += `- \`GET /api/${routeName}/:id\`\n`;
         endpointsContent += `- \`POST /api/${routeName}\`\n`;
         endpointsContent += `- \`PUT /api/${routeName}/:id\`\n`;
@@ -88,6 +88,7 @@ export const generateAIDocs = async (config, entities, outputDir, enums, openEnt
         if (entity.isSearchable) entitiesContent += `- \`@Searchable\`\n`;
         if (entity.isAudited) entitiesContent += `- \`@Audited\`\n`;
         if (entity.isFederated) entitiesContent += `- \`@Federated\`\n`;
+        if (entity.isDelete) entitiesContent += `- \`@Delete\`\n`;
         
         entitiesContent += `\nFields:\n`;
         for (const field of entity.fields) {
@@ -101,16 +102,20 @@ export const generateAIDocs = async (config, entities, outputDir, enums, openEnt
     // 4. PROTOCOLS.md
     let protoContent = `# Additional Network Protocols\n\n`;
     protoContent += `## GraphQL Surface\n`;
-    protoContent += `- **Endpoint**: \`POST /query\`\n`;
-    protoContent += `- **Playground**: \`GET /\`\n\n`;
+    protoContent += `- **Endpoint**: \`POST /graphql\` (Secured via JWT and Tenant headers)\n`;
+    protoContent += `- **Playground**: GraphQL Playground UI is enabled on the server.\n`;
+    protoContent += `- **Queries**: \`list[Entity]s(page: Int, size: Int)\`, \`get[Entity](id: ID!)\`\n`;
+    protoContent += `- **Mutations**: \`create[Entity](input: CreateInput)\`, \`update[Entity](id: ID!, input: UpdateInput)\`, \`delete[Entity](id: ID!)\`\n`;
+    protoContent += `- **Postman Collection Integration**: The auto-generated Postman collection includes a comprehensive **GraphQL Federation Layer** folder containing test queries and mutations for all entities.\n\n`;
     
     protoContent += `## WebSocket Engine\n`;
-    protoContent += `- **Endpoint**: \`ws[s]://host/ws\`\n`;
-    protoContent += `- **Format**: JSON Envelope Payload \`{ "type": "...", "payload": {...} }\`\n\n`;
+    protoContent += `- **Endpoint**: \`ws[s]://host/ws?token={JWT}\`\n`;
+    protoContent += `- **Format**: JSON Envelope Payload with HMAC-SHA256 digital signature: \`{ "type": "...", "payload": {...} }\`\n\n`;
 
-    protoContent += `## gRPC (Kratos) Engine\n`;
-    protoContent += `- **Port**: \`9000\` (Default)\n`;
-    protoContent += `- **Proto Definitions**: Located in \`api/.../\`\n`;
+    protoContent += `## gRPC & gRPC-Web Engine\n`;
+    protoContent += `- **Native Kratos gRPC Port**: \`9000\` (TCP)\n`;
+    protoContent += `- **gRPC-Web Proxy Port**: \`9090\` (HTTP/1.1 for web clients)\n`;
+    protoContent += `- **Proto Definitions**: Located in \`api/v1/*.proto\`\n`;
 
     await fs.writeFile(path.join(aiDocsDir, 'PROTOCOLS.md'), protoContent);
 
@@ -118,6 +123,15 @@ export const generateAIDocs = async (config, entities, outputDir, enums, openEnt
     let agentInstructions = `# LLM / AI AGENT INSTRUCTIONS 🤖\n\n`;
     agentInstructions += `Welcome to the generated codebase for **${appName}**.\n\n`;
     agentInstructions += `This application was generated by the GO-DUCK-CLI (An advanced Evolutionary Go Code Generator).\n\n`;
+    agentInstructions += `### High-Velocity Commands:\n`;
+    agentInstructions += `- **Build Project**: \`go build ./...\`\n`;
+    agentInstructions += `- **Protobuf Compilation**: \`./generate.sh\` (or \`.\\generate.bat\` on Windows)\n`;
+    agentInstructions += `- **Local Dependencies & Dev Boot**: \`docker-compose up -d && go run main.go\`\n`;
+    agentInstructions += `- **Docker Build & Push**: \`./push.sh\` (Builds and pushes the Docker image to registry)\n\n`;
+    agentInstructions += `### GDL Evolution & Schema Deletions:\n`;
+    agentInstructions += `- **Snapshot Merging (Multi-File GDL)**: The generator implements stateful snapshot merging. Running \`import-gdl\` on a single GDL file will NOT wipe out other entities; previous snapshots are retrieved from the \`.go-duck/\` state folder and merged automatically.\n`;
+    agentInstructions += `- **Altering/Dropping Fields**: To add, drop, or edit fields within an entity, update the fields inline in the GDL entity block. Running \`import-gdl\` generates targeted Goose SQL column-level migrations.\n`;
+    agentInstructions += `- **Dropping Entities**: To completely delete an entity, its database table, all generated code files, and its snapshot, append the \`@Delete\` annotation above the entity definition block and run \`import-gdl\`.\n\n`;
     agentInstructions += `### How to navigate this system:\n`;
     agentInstructions += `The full system specifications and dynamically generated blueprints have been exported for you in the \`docs/ai/\` folder. Look there before attempting any code modifications.\n\n`;
     agentInstructions += `- **[docs/ai/ARCHITECTURE.md](docs/ai/ARCHITECTURE.md)**: Describes the databases, caching layers, configuration structure, and middleware enabled in this project.\n`;

package/generators/config.js

@@ -2,7 +2,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import chalk from 'chalk';
 
-export const generateConfigLoader = async (outputDir) => {
+export const generateConfigLoader = async (outputDir, configObj) => {
 	const configDir = path.join(outputDir, 'config');
 	await fs.ensureDir(configDir);
 
@@ -25,13 +25,17 @@ type Config struct {
 		Description string \`mapstructure:"description"\`
 		
 		Server struct {
-			Port         int           \`mapstructure:"port"\`
-			ReadTimeout  time.Duration \`mapstructure:"read-timeout"\`
-			WriteTimeout time.Duration \`mapstructure:"write-timeout"\`
+			REST struct {
+				Port     int    \`mapstructure:"port"\`
+				Protocol string \`mapstructure:"protocol"\`
+				ApiPathPrefix string \`mapstructure:"api-path-prefix"\`
+			} \`mapstructure:"rest"\`
 			GRPC struct {
-				Addr    string        \`mapstructure:"addr"\`
-				Network string        \`mapstructure:"network"\`
-				Timeout time.Duration \`mapstructure:"timeout"\`
+				Addr       string        \`mapstructure:"addr"\`
+				Network    string        \`mapstructure:"network"\`
+				Timeout    time.Duration \`mapstructure:"timeout"\`
+				WebEnabled bool          \`mapstructure:"web_enabled"\`
+				WebPort    int           \`mapstructure:"web_port"\`
 			} \`mapstructure:"grpc"\`
 			CORS struct {
 				AllowOrigins []string \`mapstructure:"allow-origins"\`
@@ -237,7 +241,9 @@ func LoadConfig() (*Config, error) {
 	v.AddConfigPath(".")
 
 	// Default values
-	v.SetDefault("go-duck.server.port", 8080)
+	v.SetDefault("go-duck.server.rest.port", 8080)
+	v.SetDefault("go-duck.server.rest.protocol", "json")
+	v.SetDefault("go-duck.server.rest.api-path-prefix", "/${configObj.name || 'api'}/api")
 	v.SetDefault("go-duck.security.rate-limit.rps", 100.0)
 	v.SetDefault("go-duck.security.rate-limit.burst", 200)
 	v.SetDefault("go-duck.logging.datadog.enabled", false)
@@ -254,6 +260,8 @@ func LoadConfig() (*Config, error) {
 	v.SetDefault("go-duck.server.grpc.addr", ":9000")
 	v.SetDefault("go-duck.server.grpc.network", "tcp")
 	v.SetDefault("go-duck.server.grpc.timeout", "1s")
+	v.SetDefault("go-duck.server.grpc.web_enabled", false)
+	v.SetDefault("go-duck.server.grpc.web_port", 9090)
 	v.SetDefault("go-duck.resilience.circuit-breaker.enabled", true)
 	v.SetDefault("go-duck.resilience.circuit-breaker.failure-threshold", 5)
 	v.SetDefault("go-duck.resilience.circuit-breaker.timeout", "60s")