go-duck-cli 1.0.0

package/README.md

@@ -0,0 +1,130 @@
+# GO-DUCK CLI
+
+[![npm version](https://badge.fury.io/js/go-duck-cli.svg)](https://badge.fury.io/js/go-duck-cli)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
+**GO-DUCK CLI** is a powerful and evolutionary code generator for building production-ready microservices in Go. It scaffolds a complete project with a rich set of features, allowing you to focus on your business logic instead of boilerplate code.
+
+## Overview
+
+Go-Duck is designed to accelerate backend development by generating a robust, feature-rich, and observable Go microservice from a simple definition language. It follows an "evolutionary" approach, allowing you to incrementally update your application's schema and generate the necessary code and database migrations.
+
+The generated application is built on a modern stack, including:
+
+*   **Gin Gonic** for the REST API
+*   **Kratos** for gRPC
+*   **GORM** for database interaction (PostgreSQL)
+*   **Liquibase** for database migrations
+*   **OpenTelemetry** for observability
+*   And many more...
+
+## Features
+
+*   **Full-Stack Code Generation**: Generates everything from REST and gRPC APIs to the data access layer.
+*   **Dual-Protocol APIs**: Out-of-the-box support for both REST (Gin) and gRPC (Kratos).
+*   **Stateful Incremental Updates**: Intelligently applies changes from your GDL schema to the existing codebase.
+*   **Rich Feature Set**: Includes support for:
+    *   CRUD APIs with pagination and filtering
+    *   GraphQL integration
+    *   Real-time communication with WebSockets and MQTT
+    *   Auditing and API usage metering
+    *   JWT-based security and OIDC integration
+    *   Distributed caching with Redis
+    *   Circuit breakers for resilience
+    *   Full-stack observability with OpenTelemetry
+*   **Automated Documentation**: Generates a beautiful, multi-page HTML documentation portal for your project.
+*   **Cloud-Native**: Comes with Docker support and CI/CD pipelines using GitHub Actions.
+
+## Installation
+
+```bash
+npm install -g go-duck-cli
+```
+
+## Usage
+
+The `go-duck-cli` has two main commands: `create` and `import-gdl`.
+
+### `go-duck create`
+
+This command scaffolds a new Go microservice.
+
+```bash
+go-duck create [options]
+```
+
+**Options:**
+
+*   `-c, --config <path>`: Path to the `config.yaml` file (default: `../CONFIG/config.yaml`).
+*   `-o, --output <path>`: Path where the project will be generated (default: current directory).
+*   `-g, --gdl <path>`: Path to the directory containing your GDL files (default: `../GDL`).
+
+**Example:**
+
+```bash
+go-duck create -c my-app/config.yaml -o my-app -g my-app/gdl
+```
+
+### `go-duck import-gdl <file>`
+
+This command imports a GDL file to an existing project, generating new entities, updating existing ones, and creating database migrations.
+
+```bash
+go-duck import-gdl <file> [options]
+```
+
+**Options:**
+
+*   `-o, --output <path>`: Path to the existing application root (default: current directory).
+
+**Example:**
+
+```bash
+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.
+
+**Example (`app.gdl`):**
+
+```gdl
+entity Author {
+  name String required
+  email String unique
+}
+
+entity Book {
+  title String required
+  publishedDate LocalDate
+}
+
+relationship OneToMany {
+  Author{books} to Book{author}
+}
+```
+
+## Configuration (`config.yaml`)
+
+The `config.yaml` file contains the configuration for your generated application.
+
+```yaml
+app:
+  name: my-app
+  datasource:
+    host: localhost
+    port: 5432
+    username: user
+    password: password
+    database: my_app_db
+  multitenancy:
+    enabled: true
+  security:
+    jwt:
+      secret: "your-jwt-secret"
+```
+
+## License
+
+This project is licensed under the ISC License.

package/generators/cache.js

@@ -0,0 +1,107 @@
+import fs from 'fs-extra';
+import path from 'path';
+import chalk from 'chalk';
+
+export const generateCacheCode = async (config, outputDir) => {
+    const cacheDir = path.join(outputDir, 'cache');
+    await fs.ensureDir(cacheDir);
+
+    const cacheGo = `
+package cache
+
+import (
+	"context"
+	"encoding/json"
+	"log"
+	"time"
+
+	"{{app_name}}/config"
+	"github.com/go-redis/redis/v8"
+)
+
+var (
+	RedisClient *redis.Client
+	ctx         = context.Background()
+)
+
+// InitCache initializes Redis if enabled
+func InitCache(cfg *config.Config) {
+	if !cfg.GoDuck.Cache.Redis.Enabled {
+		log.Println("Redis Caching is disabled.")
+		return
+	}
+
+	client := redis.NewClient(&redis.Options{
+		Addr:     cfg.GoDuck.Cache.Redis.Host,
+		Password: cfg.GoDuck.Cache.Redis.Password,
+		DB:       cfg.GoDuck.Cache.Redis.DB,
+	})
+
+	// Perform a quick ping to verify connection without crashing the app
+	if err := client.Ping(ctx).Err(); err != nil {
+		log.Printf("Warning: Redis is enabled but unreachable at %s: %v. Caching will be bypassed.", cfg.GoDuck.Cache.Redis.Host, err)
+		return
+	}
+
+	RedisClient = client
+	log.Printf("Connected to Redis at %s", cfg.GoDuck.Cache.Redis.Host)
+}
+
+// Get retrieves a value from cache
+func Get(key string, dest interface{}) bool {
+	if RedisClient == nil {
+		return false
+	}
+
+	val, err := RedisClient.Get(ctx, key).Result()
+	if err != nil {
+		if err != redis.Nil {
+			log.Printf("Redis Get Error: %v", err)
+		}
+		return false
+	}
+
+	err = json.Unmarshal([]byte(val), dest)
+	return err == nil
+}
+
+// Set stores a value in cache with TTL
+func Set(key string, value interface{}, ttl time.Duration) {
+	if RedisClient == nil {
+		return
+	}
+
+	data, err := json.Marshal(value)
+	if err != nil {
+		log.Printf("Redis Marshal Error: %v", err)
+		return
+	}
+
+	if err := RedisClient.Set(ctx, key, data, ttl).Err(); err != nil {
+		log.Printf("Redis Set Error: %v", err)
+	}
+}
+
+// Delete removes a key from cache
+func Delete(key string) {
+	if RedisClient == nil {
+		return
+	}
+	RedisClient.Del(ctx, key)
+}
+
+// ClearPattern deletes all keys matching a pattern (e.g. for entity invalidation)
+func ClearPattern(pattern string) {
+	if RedisClient == nil {
+		return
+	}
+	iter := RedisClient.Scan(ctx, 0, pattern, 0).Iterator()
+	for iter.Next(ctx) {
+		RedisClient.Del(ctx, iter.Val())
+	}
+}
+`;
+
+    await fs.writeFile(path.join(cacheDir, 'redis.go'), cacheGo.replace(/{{app_name}}/g, config.name));
+    console.log(chalk.gray('  Generated Resilient Redis Caching Package'));
+};

package/generators/config.js

@@ -0,0 +1,173 @@
+import fs from 'fs-extra';
+import path from 'path';
+import chalk from 'chalk';
+
+export const generateConfigLoader = async (outputDir) => {
+	const configDir = path.join(outputDir, 'config');
+	await fs.ensureDir(configDir);
+
+	const configGo = `
+package config
+
+import (
+	"fmt"
+	"os"
+	"time"
+
+	"github.com/spf13/viper"
+)
+
+type Config struct {
+	GoDuck struct {
+		Name        string \`mapstructure:"name"\`
+		Version     string \`mapstructure:"version"\`
+		Description string \`mapstructure:"description"\`
+		
+		Server struct {
+			Port         int           \`mapstructure:"port"\`
+			ReadTimeout  time.Duration \`mapstructure:"read-timeout"\`
+			WriteTimeout time.Duration \`mapstructure:"write-timeout"\`
+			GRPC struct {
+				Addr    string        \`mapstructure:"addr"\`
+				Network string        \`mapstructure:"network"\`
+				Timeout time.Duration \`mapstructure:"timeout"\`
+			} \`mapstructure:"grpc"\`
+			CORS struct {
+				AllowOrigins []string \`mapstructure:"allow-origins"\`
+				AllowMethods []string \`mapstructure:"allow-methods"\`
+				AllowHeaders []string \`mapstructure:"allow-headers"\`
+			} \`mapstructure:"cors"\`
+		} \`mapstructure:"server"\`
+
+		Security struct {
+			KeycloakHost     string \`mapstructure:"keycloak-host"\`
+			KeycloakRealm    string \`mapstructure:"keycloak-realm"\`
+			KeycloakClientID string \`mapstructure:"keycloak-client-id"\`
+			KeycloakSecret   string \`mapstructure:"keycloak-secret"\`
+			RateLimit        struct {
+				RPS   float64 \`mapstructure:"rps"\`
+				Burst int     \`mapstructure:"burst"\`
+			} \`mapstructure:"rate-limit"\`
+		} \`mapstructure:"security"\`
+
+		Logging struct {
+			Datadog struct {
+				Enabled bool   \`mapstructure:"enabled"\`
+				APIKey  string \`mapstructure:"api-key"\`
+				Site    string \`mapstructure:"site"\`
+				Service string \`mapstructure:"service"\`
+			} \`mapstructure:"datadog"\`
+		} \`mapstructure:"logging"\`
+
+		Messaging struct {
+			MQTT struct {
+				Enabled     bool   \`mapstructure:"enabled"\`
+				Broker      string \`mapstructure:"broker"\`
+				ClientID    string \`mapstructure:"client-id"\`
+				Username    string \`mapstructure:"username"\`
+				Password    string \`mapstructure:"password"\`
+				TopicPrefix string \`mapstructure:"topic-prefix"\`
+			} \`mapstructure:"mqtt"\`
+		} \`mapstructure:"messaging"\`
+
+		Cache struct {
+			Redis struct {
+				Enabled  bool          \`mapstructure:"enabled"\`
+				Host     string        \`mapstructure:"host"\`
+				Password string        \`mapstructure:"password"\`
+				DB       int           \`mapstructure:"db"\`
+				TTL      time.Duration \`mapstructure:"ttl"\`
+			} \`mapstructure:"redis"\`
+		} \`mapstructure:"cache"\`
+
+		Telemetry struct {
+			OTel struct {
+				Enabled      bool    \`mapstructure:"enabled"\`
+				Endpoint     string  \`mapstructure:"endpoint"\`
+				SamplerRatio float64 \`mapstructure:"sampler-ratio"\`
+			} \`mapstructure:"otel"\`
+		} \`mapstructure:"telemetry"\`
+
+		Resilience struct {
+			CircuitBreaker struct {
+				Enabled            bool \`mapstructure:"enabled"\`
+				FailureThreshold   uint32 \`mapstructure:"failure-threshold"\`
+				SuccessThreshold   uint32 \`mapstructure:"success-threshold"\`
+				Timeout            time.Duration \`mapstructure:"timeout"\`
+			} \`mapstructure:"circuit-breaker"\`
+		} \`mapstructure:"resilience"\`
+
+		Multitenancy struct {
+			Enabled bool \`mapstructure:"enabled"\`
+		} \`mapstructure:"multitenancy"\`
+
+		Datasource struct {
+			Host            string        \`mapstructure:"host"\`
+			Port            int           \`mapstructure:"port"\`
+			Username        string        \`mapstructure:"username"\`
+			Password        string        \`mapstructure:"password"\`
+			Database        string        \`mapstructure:"database"\`
+			MaxOpenConns    int           \`mapstructure:"max-open-conns"\`
+			MaxIdleConns    int           \`mapstructure:"max-idle-conns"\`
+			ConnMaxLifetime time.Duration \`mapstructure:"conn-max-lifetime"\`
+		} \`mapstructure:"datasource"\`
+	} \`mapstructure:"go-duck"\`
+	Environment struct {
+		ActiveProfile string \`mapstructure:"active_profile"\`
+	} \`mapstructure:"environment"\`
+}
+
+func LoadConfig() (*Config, error) {
+	v := viper.New()
+
+	profile := os.Getenv("GO_PROFILE")
+	if profile == "" {
+		profile = "dev"
+	}
+
+	v.SetConfigName(fmt.Sprintf("application-%s", profile))
+	v.SetConfigType("yml")
+	v.AddConfigPath(".")
+
+	// Default values
+	v.SetDefault("go-duck.server.port", 8080)
+	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)
+	v.SetDefault("go-duck.logging.datadog.site", "datadoghq.com")
+	v.SetDefault("go-duck.messaging.mqtt.enabled", false)
+	v.SetDefault("go-duck.messaging.mqtt.topic-prefix", "go-duck/events")
+	v.SetDefault("go-duck.cache.redis.enabled", false)
+	v.SetDefault("go-duck.cache.redis.ttl", "10m")
+	v.SetDefault("go-duck.telemetry.otel.enabled", false)
+	v.SetDefault("go-duck.telemetry.otel.endpoint", "localhost:4317")
+	v.SetDefault("go-duck.telemetry.otel.sampler-ratio", 1.0)
+	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.resilience.circuit-breaker.enabled", true)
+	v.SetDefault("go-duck.resilience.circuit-breaker.failure-threshold", 5)
+	v.SetDefault("go-duck.resilience.circuit-breaker.timeout", "60s")
+
+	if err := v.ReadInConfig(); err != nil {
+		return nil, err
+	}
+
+	var config Config
+	if err := v.Unmarshal(&config); err != nil {
+		return nil, err
+	}
+
+	return &config, nil
+}
+
+func (c *Config) GetDSN() string {
+	ds := c.GoDuck.Datasource
+	return fmt.Sprintf("host=%s user=%s password=%s dbname=%s port=%d sslmode=disable",
+		ds.Host, ds.Username, ds.Password, ds.Database, ds.Port)
+}
+`;
+
+	await fs.writeFile(path.join(configDir, 'config.go'), configGo);
+	console.log(chalk.gray('  Generated Go Config Loader with OTel support'));
+};

package/generators/devops.js

@@ -0,0 +1,212 @@
+import fs from 'fs-extra';
+import path from 'path';
+import chalk from 'chalk';
+
+export const generateDeploymentArtifacts = async (config, outputDir) => {
+    const k8sDir = path.join(outputDir, 'k8s');
+    const githubDir = path.join(outputDir, '.github/workflows');
+    await fs.ensureDir(k8sDir);
+    await fs.ensureDir(githubDir);
+
+    const appName = config.name || 'go-duck-app';
+    const appPort = 8080;
+
+    // --- 1. Dockerfile (Multi-stage, lean production image) ---
+    const dockerfile = `
+# ---- Build Stage ----
+FROM golang:1.22-alpine AS builder
+WORKDIR /app
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /app/server .
+
+# ---- Final Stage ----
+FROM gcr.io/distroless/static-debian12
+WORKDIR /app
+COPY --from=builder /app/server .
+COPY --from=builder /app/application.yml .
+COPY --from=builder /app/application-dev.yml .
+COPY --from=builder /app/application-prod.yml .
+EXPOSE ${appPort}
+ENV GO_PROFILE=prod
+ENTRYPOINT ["/app/server"]
+`;
+
+    // --- 2. Docker Compose (Full local dev environment) ---
+    const dockerCompose = `
+version: '3.9'
+
+services:
+  app:
+    build: .
+    container_name: ${appName}
+    ports:
+      - "${appPort}:${appPort}"
+    environment:
+      - GO_PROFILE=dev
+    depends_on:
+      - postgres
+      - redis
+      - mosquitto
+      - otel-collector
+    networks:
+      - go-duck-net
+
+  postgres:
+    image: postgres:15-alpine
+    container_name: ${appName}-postgres
+    environment:
+      POSTGRES_USER: go_duck_user
+      POSTGRES_PASSWORD: go_duck_pass
+      POSTGRES_DB: ${appName}
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    networks:
+      - go-duck-net
+
+  redis:
+    image: redis:7-alpine
+    container_name: ${appName}-redis
+    ports:
+      - "6379:6379"
+    command: redis-server --save 60 1 --loglevel warning
+    networks:
+      - go-duck-net
+
+  mosquitto:
+    image: eclipse-mosquitto:2
+    container_name: ${appName}-mqtt
+    ports:
+      - "1883:1883"
+      - "9001:9001"
+    volumes:
+      - ./k8s/mosquitto.conf:/mosquitto/config/mosquitto.conf
+    networks:
+      - go-duck-net
+
+  otel-collector:
+    image: otel/opentelemetry-collector-contrib:latest
+    container_name: ${appName}-otel
+    command: ["--config=/etc/otel-collector-config.yaml"]
+    volumes:
+      - ./k8s/otel-collector.yml:/etc/otel-collector-config.yaml
+    ports:
+      - "4317:4317"
+      - "4318:4318"
+    depends_on:
+      - jaeger
+    networks:
+      - go-duck-net
+
+  jaeger:
+    image: jaegertracing/all-in-one:latest
+    container_name: ${appName}-jaeger
+    ports:
+      - "16686:16686"
+      - "14317:4317"
+    networks:
+      - go-duck-net
+
+  keycloak:
+    image: quay.io/keycloak/keycloak:23.0
+    container_name: ${appName}-keycloak
+    command: start-dev
+    environment:
+      KEYCLOAK_ADMIN: admin
+      KEYCLOAK_ADMIN_PASSWORD: admin
+    ports:
+      - "8180:8080"
+    networks:
+      - go-duck-net
+
+volumes:
+  postgres_data:
+
+networks:
+  go-duck-net:
+    driver: bridge
+`;
+
+    // --- 3. MQTT Broker Config ---
+    const mosquittoConf = `
+listener 1883
+listener 9001
+protocol websockets
+allow_anonymous true
+`;
+
+    // --- 4. GitHub Actions CI/CD ---
+    const ciWorkflow = `
+name: CI - Build & Test
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.22'
+
+      - name: Cache Go modules
+        uses: actions/cache@v3
+        with:
+          path: ~/go/pkg/mod
+          key: \${{ runner.os }}-go-\${{ hashFiles('**/go.sum') }}
+
+      - name: Download dependencies
+        run: go mod download
+
+      - name: Build
+        run: go build -v ./...
+
+      - name: Run Tests
+        run: go test -v ./...
+`;
+
+    const cdWorkflow = `
+name: CD - Build & Push Docker Image
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: \${{ secrets.DOCKER_USERNAME }}
+          password: \${{ secrets.DOCKER_PASSWORD }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: \${{ secrets.DOCKER_USERNAME }}/${appName}:latest,\${{ secrets.DOCKER_USERNAME }}/${appName}:\${{ github.sha }}
+`;
+
+    await fs.writeFile(path.join(outputDir, 'Dockerfile'), dockerfile);
+    await fs.writeFile(path.join(outputDir, 'docker-compose.yml'), dockerCompose);
+    await fs.writeFile(path.join(k8sDir, 'mosquitto.conf'), mosquittoConf);
+    await fs.writeFile(path.join(githubDir, 'ci.yml'), ciWorkflow);
+    await fs.writeFile(path.join(githubDir, 'cd.yml'), cdWorkflow);
+
+    console.log(chalk.gray('  Generated Dockerfile, Docker Compose & GitHub Actions CI/CD'));
+};

package/generators/docs.js

@@ -0,0 +1,74 @@
+import fs from 'fs-extra';
+import path from 'path';
+import Handlebars from 'handlebars';
+import chalk from 'chalk';
+import { fileURLToPath } from 'url';
+
+export const generateDocumentation = async (config, entities, outputDir, enums = []) => {
+    console.log(chalk.cyan('Generating Multi-Page Developer Guide Web App...'));
+
+    const docsDir = path.join(outputDir, 'docs', 'web');
+    await fs.ensureDir(docsDir);
+
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
+    const templatesDir = path.resolve(__dirname, '../templates/docs');
+
+    if (!await fs.pathExists(templatesDir)) {
+        console.log(chalk.yellow(`⚠️  Documentation templates not found at ${templatesDir}. Skipping docs generation.`));
+        return;
+    }
+
+    const layoutSource = await fs.readFile(path.join(templatesDir, 'layout.hbs'), 'utf8');
+    const layout = Handlebars.compile(layoutSource);
+
+    // Register Helpers
+    Handlebars.registerHelper('eq', (a, b) => a === b);
+    Handlebars.registerHelper('toLowerCase', (str) => typeof str === 'string' ? str.toLowerCase() : '');
+    Handlebars.registerHelper('capitalize', (str) => typeof str === 'string' ? str.charAt(0).toUpperCase() + str.slice(1) : '');
+    Handlebars.registerHelper('defaultStr', (value, safeVal) => (value !== null && value !== undefined && value !== '') ? value : safeVal);
+
+    const pages = [
+        { file: 'index', title: 'Home' },
+        { file: 'gdl', title: 'GDL Reference' },
+        { file: 'cli', title: 'CLI & Code Injection' },
+        { file: 'rest', title: 'REST & Search API' },
+        { file: 'grpc', title: 'Kratos gRPC API' },
+        { file: 'graphql', title: 'GraphQL Framework' },
+        { file: 'realtime', title: 'WebSockets & MQTT' },
+        { file: 'audit', title: 'Audit & Metering' },
+        { file: 'security', title: 'Security & Auth' },
+        { file: 'observability', title: 'Observability' },
+        { file: 'integrations', title: 'Client Integrations' }
+    ];
+
+    const context = {
+        appName: config.name || 'GO-DUCK App',
+        entities: entities,
+        enums: enums
+    };
+
+    for (const page of pages) {
+        const pageSource = await fs.readFile(path.join(templatesDir, 'pages', `${page.file}.hbs`), 'utf8');
+        const pageTemplate = Handlebars.compile(pageSource);
+        const pageHtml = pageTemplate(context);
+        
+        const fullHtml = layout({
+            ...context,
+            body: pageHtml,
+            activePage: page.file,
+            title: page.title
+        });
+        
+        await fs.writeFile(path.join(docsDir, `${page.file}.html`), fullHtml);
+    }
+
+    const files = await fs.readdir(templatesDir);
+    for (const file of files) {
+        if (file.endsWith('.png') || file.endsWith('.mp4')) {
+            await fs.copy(path.join(templatesDir, file), path.join(docsDir, file));
+        }
+    }
+
+    console.log(chalk.green('✅ Multi-Page Developer Guide HTML Web App generated at: docs/web/index.html'));
+};