GO-DUCK-COVE-CLI 🦆

The ultra-lightweight, embedded desktop edition of the GO-DUCK microservice scaffolder.

⚓ The Port Royal Refit

After navigating the turbulent, sprawling oceans of Kubernetes and multi-tenant enterprise clouds, Go-Duck finally dropped anchor at the infamous pirate haven of Port Royal. Realizing that not every journey requires a massive, cloud-native galleon, he traded in his fleet for a nimble, self-sufficient sloop.

GO-DUCK-COVE is that sloop. It’s a specialized fork of the GO-DUCK engine, redesigned specifically for desktop apps, edge devices, and self-contained monoliths. We threw the heavy cargo overboard—Kubernetes, Postgres, Keycloak, Kratos, and Redis—and replaced them with zero-dependency embedded alternatives.

What you get is a single, lightning-fast Go binary that serves your REST API, manages its own local SQLite database, handles local JWT authentication, and serves your React/Angular/Vue frontend—all from a single process.

🌟 Key Features

• Embedded SQLite: Zero-dependency, pure Go (github.com/glebarez/sqlite) database. No CGO required, no external database servers needed. Your entire state lives in a simple data.db file.
• Built-in Local Auth: Generates local user models, login/registration endpoints, and JWT middleware out of the box. No external Keycloak required.
• Unified Static Frontend: Drop your compiled SPA (React, Vue, HTML/JS) into the frontend/ directory, and the Go binary will automatically serve it alongside your API.
• GDL Powered: Still powered by the legendary Go-Duck Definition Language (GDL). Write a simple .gdl schema and instantly get GORM models, Gin controllers, and database migrations.
• Public Swagger UI Automation: Swagger documentation (swagger.json) and the Swagger UI are completely stabilized and decoupled from strict DuckGuard access policies. The UI dynamically resolves API paths, supporting direct local-token authentication right out of the box. (See templates/go/router.go.hbs)
• Standalone Windows 10+ EXE Packaging: Generates a build.bat that embeds the app icon/manifest via go-winres and builds with CGO_ENABLED=0. The generated app has no CGO dependencies (SQLite is the pure-Go modernc.org/sqlite driver), so the .exe needs no GCC to build and no MinGW runtime DLLs to run. It also emits app-console.exe — run it on a target machine if the GUI build closes silently, to see the startup error. (See generators/packaging.js)

🚀 Quick Start

# 1. Install the CLI globally
npm install -g go-duck-cove

# 2. Bootstrap a config + folder structure in an empty directory
mkdir my-desktop-app && cd my-desktop-app
go-duck-cove init

# 3. Generate the application (config.yaml + GDL files → real Go project)
go-duck-cove create -c config/config.yaml -g gdl -o .

# 4. Build and Run! (No Docker required)
go mod tidy
go run main.go

That's it! Your API is running on :8080, your frontend is served on http://localhost:8080, and your SQLite database data.db is ready to go.

🦆 GDL (Go-Duck Definition Language) 101

Define your models in a .gdl file inside your gdl/ folder. The generator will instantly build full CRUD REST endpoints, models, and migrations for them.

@Audited
entity Note {
    title string required
    content text
    isPinned boolean
    createdAt timestamp
}

@Delete
entity OldFeature {}

Supported Annotations in Deskport:

• @Audited: Automatically generates audit logs for every creation, modification, or deletion of the entity.
• @Delete: Safely drops the table via migrations and purges the generated code.
• @SoftDelete: Injects deleted_at, adding /trashed and /restore endpoints.
• @Draftable: Adds an is_draft column and /draft / /publish endpoints.
• @ActiveStatus / @IsActive: Injects an active toggle boolean.

🛠️ CLI Commands

| Command | Description | | :--- | :--- | | go-duck-cove init | Scaffolds the default config.yaml and a gdl/ directory. | | go-duck-cove create | Full application scaffold from config.yaml + GDL directory. | | go-duck-cove import-gdl <path> | Stateful incremental update. Diffs against .go-duck/ snapshots, emits only delta migrations without touching custom code. | | go-duck-cove validate-gdl <path> | Static analysis to verify your .gdl schema is valid before generating. |

Flags for create and import-gdl:

• -c, --config <path>: Path to your config.yaml.
• -o, --output <path>: Output directory.
• -g, --gdl <path>: Directory containing your .gdl files.
• --preserve-root: Skips overwriting main.go and go.mod.

📂 Project Structure

When you run go-duck-cove create, you get a production-ready standard Go layout:

├── config/              # Configuration loading
├── controllers/         # Generated REST handlers
├── frontend/            # Drop your static HTML/JS/CSS/SPA build here!
├── internal/            # Core engine
├── interceptors/        # Business logic hooks (pre/post save)
├── migrations/          # Goose SQL migrations
├── models/              # GORM database models
├── router/              # Gin engine setup and static file serving
├── main.go              # Entry point
├── data.db              # Your SQLite embedded database
└── config.yaml          # The application config

Adding a Frontend

Simply place your index.html, CSS, and JS files into the frontend/ directory. The Go server automatically hosts index.html at the root / path, and serves the rest as static assets. You now have a complete, self-contained desktop web-app in a single binary!