Keyboard shortcuts

Press ← or β†’ to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Summary

Getting Started

Core Concepts

Reference

πŸ€– AI Integration (NEW v1.0.0)

Advanced Topics

Examples

Marketplace

Architecture

Table of Contents

Install

Homebrew

brew tap ggen-dev/tap
brew install ggen

Cargo

cargo install ggen

Verify Installation

ggen --version

Post-Installation Setup

Marketplace Access

The marketplace is available immediately after installation. No additional configuration is required.

First Gpack Installation

# Search for available gpacks
ggen search rust cli

# Install your first gpack
ggen add io.ggen.rust.cli-subcommand

# Verify installation
ggen packs

Gpack Cache Location

Gpacks are cached locally in your project directory:

# View cache location
ls -la .ggen/gpacks/

# Cache structure:
# .ggen/
# β”œβ”€β”€ gpacks/
# β”‚   └── io.ggen.rust.cli-subcommand/
# β”‚       └── 0.2.1/
# β”‚           β”œβ”€β”€ templates/
# β”‚           β”œβ”€β”€ macros/
# β”‚           └── graphs/
# └── ggen.lock

Registry Configuration

By default, ggen uses the official registry. No configuration is needed for most users.

# Check registry status
ggen search --help

# Verify connectivity
ggen categories

Shell Completions (Optional)

# Generate completions for your shell
ggen completion bash > ~/.bash_completion.d/ggen
ggen completion zsh > ~/.zsh/completions/_ggen
ggen completion fish > ~/.config/fish/completions/ggen.fish

# Reload shell
source ~/.bashrc  # or ~/.zshrc

Troubleshooting Installation

Command Not Found

# Check if ggen is in PATH
which ggen

# If not found, add to PATH
export PATH="$HOME/.cargo/bin:$PATH"

# Or reinstall with explicit path
cargo install ggen --root ~/.local
export PATH="$HOME/.local/bin:$PATH"

Marketplace Access Issues

# Test marketplace connectivity
ggen search rust

# Check network connectivity
ping registry.ggen.io

# Verify DNS resolution
nslookup registry.ggen.io

Permission Issues

# Fix cache directory permissions
chmod -R 755 .ggen/

# Or use different cache location
export GGEN_CACHE_DIR="$HOME/.cache/ggen"

Next Steps

After installation:

  1. Try the quickstart: Follow the quickstart guide
  2. Explore gpacks: Browse the marketplace
  3. Learn templates: Read the templates guide
  4. Generate code: Use the CLI reference

Uninstallation

Homebrew

brew uninstall ggen
brew untap ggen-dev/tap

Cargo

cargo uninstall ggen

Cleanup

# Remove cache directories
rm -rf .ggen/
rm -rf ~/.cache/ggen/

# Remove completions
rm ~/.bash_completion.d/ggen
rm ~/.zsh/completions/_ggen
rm ~/.config/fish/completions/ggen.fish

Table of Contents

Quickstart

The fastest way to get started with ggen is using marketplace gpacks - pre-built, tested template collections.

1. Search for Templates

# Search for CLI subcommand templates
ggen search rust cli

# Output:
# ID                                    LATEST     KIND       TAGS
# io.ggen.rust.cli-subcommand           0.2.1      template   rust, cli, clap
# io.ggen.rust.api-endpoint             0.1.5      template   rust, api, axum

2. Install a Gpack

# Install the latest version
ggen add io.ggen.rust.cli-subcommand

# Or install specific version
ggen add io.ggen.rust.cli-subcommand@0.2.0

3. Generate Code

# Use the installed gpack template
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello description="Print a greeting"

4. Verify Installation

# List installed gpacks
ggen packs

# Show template details
ggen show io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl

Result:

src/cmds/hello.rs

Local Templates (Advanced)

For custom templates or when you need full control over the generation process:

1. Initialize Project Structure

mkdir -p templates/cli/subcommand

2. Create Template

Create templates/cli/subcommand/rust.tmpl:

---
to: src/cmds/{{ slug }}.rs
vars: { cmd: hello, summary: "Print a greeting", seed: cosmos }
rdf:
  - "graphs/cli.ttl"              # Local RDF file
shape:
  - "graphs/shapes/cli.shacl.ttl" # Local SHACL shapes
sparql:
  vars:
    - name: slug
      query: |
        PREFIX cli: <urn:ggen:cli#>
        SELECT ?slug WHERE { ?c a cli:Command ; cli:slug ?slug } LIMIT 1
determinism: { seed: "{{ seed }}" }
---
pub fn {{ slug }}(name:&str){ println!("hello {}", name); }

3. Generate

ggen gen cli subcommand --vars cmd=hello summary="Print a greeting"

Marketplace vs Local Templates

FeatureMarketplace GpacksLocal Templates
Setup TimeInstantRequires creation
QualityCommunity testedCustom quality
UpdatesAutomaticManual
DependenciesManagedManual
VersioningSemanticAd-hoc
Best ForCommon patternsCustom needs

Troubleshooting

First-time Setup Issues

# If ggen command not found after installation
which ggen
# Should show path to ggen binary

# If marketplace search fails
ggen search --help
# Check network connectivity and registry access

Template Not Found

# Check if gpack is installed
ggen packs

# Reinstall if missing
ggen add io.ggen.rust.cli-subcommand

# Verify template path
ggen show io.ggen.rust.cli-subcommand

Generation Errors

# Use dry run to preview
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello --dry

# Check variable requirements
ggen show io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl

Table of Contents

Templates

ggen supports two types of templates: marketplace gpacks and local templates. Marketplace gpacks are recommended for most use cases, while local templates provide full customization control.

Marketplace Gpacks

Marketplace gpacks are curated, versioned template collections published to the ggen registry.

Gpack Structure

<gpack-id>/
β”œβ”€β”€ ggen.toml          # Gpack manifest
β”œβ”€β”€ templates/          # Template files
β”‚   └── cli/
β”‚       └── subcommand/
β”‚           β”œβ”€β”€ rust.tmpl
β”‚           β”œβ”€β”€ graphs/         # Local RDF data
β”‚           β”‚   β”œβ”€β”€ cli.ttl
β”‚           β”‚   └── shapes/
β”‚           β”‚       └── cli.shacl.ttl
β”‚           └── queries/        # Local SPARQL queries
β”‚               └── commands.rq
β”œβ”€β”€ macros/            # Reusable template fragments
β”‚   └── common.tera
└── tests/             # Golden tests
    └── test_hello.rs

Gpack Manifest (ggen.toml)

[gpack]
id = "io.ggen.rust.cli-subcommand"
name = "Rust CLI subcommand"
version = "0.2.1"
description = "Generate clap subcommands"
license = "MIT"
ggen_compat = ">=0.2 <0.4"

[dependencies]
"io.ggen.macros.std" = "^0.2"

[templates]
entrypoints = ["cli/subcommand/rust.tmpl"]
includes   = ["macros/**/*.tera"]

[rdf]
base = "http://example.org/"
prefixes.ex = "http://example.org/"
files  = ["templates/**/graphs/*.ttl"]
inline = ["@prefix ex: <http://example.org/> . ex:Foo a ex:Type ."]

Using Gpack Templates

# Install gpack
ggen add io.ggen.rust.cli-subcommand

# Use template
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello

Local Templates

Local templates are stored in your project's templates/ directory.

Location

templates/<scope>/<action>/*.tmpl

Structure

  • Frontmatter (YAML) header
  • Body (rendered)

Common Keys

  • to: output path
  • vars: defaults
  • rdf: includes/inline graphs
  • shape: SHACL shape files
  • sparql.vars: single-value bindings
  • sparql.matrix: fan-out rows
  • determinism: seed, sort key

Using Local Templates

# Generate from local template
ggen gen cli subcommand --vars cmd=hello summary="Print greeting"

Template Discovery Order

ggen searches for templates in this order:

  1. Installed gpacks (from .ggen/gpacks/)
  2. Local templates (from templates/)

If both exist, gpack templates take precedence.

Template Reference Syntax

Gpack Templates

<gpack-id>:<template-path>

Examples:

  • io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl
  • io.ggen.python.api:api/endpoint/fastapi.tmpl

Local Templates

<scope> <action>

Examples:

  • cli subcommand
  • api endpoint

Gpack Dependencies

Gpacks can depend on other gpacks for shared functionality:

[dependencies]
"io.ggen.macros.std" = "^0.2"
"io.ggen.common.rdf" = "~0.1.0"

Dependencies are automatically resolved when installing gpacks.

Versioning and Compatibility

Gpack Versioning

  • Follows semantic versioning (semver)
  • Specified in ggen.toml manifest
  • Locked in ggen.lock file

Compatibility

  • ggen_compat field specifies required ggen version
  • Dependency resolution follows semver rules
  • Updates respect compatibility constraints

Template Development

For Gpack Authors

# Initialize new gpack
ggen pack init

# Add templates
mkdir -p templates/cli/subcommand
# Create template files...

# Test gpack
ggen pack test

# Lint for publishing
ggen pack lint

# Publish to registry
ggen pack publish

For Local Template Authors

# Create template structure
mkdir -p templates/cli/subcommand

# Create template file
cat > templates/cli/subcommand/rust.tmpl << 'EOF'
---
to: src/cmds/{{ name }}.rs
vars:
  name: hello
---
pub fn {{ name }}() {
    println!("Hello from {{ name }}!");
}
EOF

# Test template
ggen gen cli subcommand --vars name=world

Table of Contents

ggen AI Guide - AI-Powered Code Generation

Version: v1.0.0 | Status: βœ… Production Ready

ggen-ai v1.0.0 introduces intelligent code generation using advanced LLMs with multi-provider support (OpenAI, Anthropic, Ollama).

Overview

The AI module (ggen-ai) provides natural language interfaces for generating:

  • Templates from descriptions
  • SPARQL queries from intent
  • RDF graphs from domain descriptions
  • Complete project structures from requirements
  • Template extraction from existing source files

Quick Start

# Generate a template from natural language
ggen ai generate "A Rust REST API controller" --language rust --output api.tmpl

# Generate SPARQL queries from intent
ggen ai sparql "Find all users with admin role" --graph data.ttl

# Generate RDF ontologies from descriptions
ggen ai graph "Person management system" --output person.ttl

# Generate complete project structures
ggen ai project "E-commerce API" --name shop --language rust --output project/

# Extract templates from existing code
ggen ai from-source src/main.rs --language rust --output template.tmpl

AI Commands

Template Generation

Generate templates from natural language descriptions:

ggen ai generate <description> [OPTIONS]

Options:
  --language <LANG>       Target programming language
  --framework <FRAMEWORK> Target framework
  --output <FILE>         Output template file
  --model <MODEL>         AI model to use (default: qwen3-coder:30b)
  --temperature <FLOAT>   Sampling temperature (0.0-2.0)
  --max-tokens <INT>      Maximum tokens to generate

Examples:

# Basic template generation
ggen ai generate "A simple CLI tool" --language rust --output cli.tmpl

# Framework-specific generation
ggen ai generate "REST API controller" --language rust --framework axum --output api.tmpl

# Python web application
ggen ai generate "FastAPI application" --language python --framework fastapi --output app.tmpl

SPARQL Query Generation

Generate SPARQL queries from natural language intent:

ggen ai sparql <intent> [OPTIONS]

Options:
  --graph <FILE>          RDF graph file for context
  --output <FILE>         Output SPARQL file
  --prefixes <PREFIX=URI> RDF prefixes to use

Examples:

# Generate queries with graph context
ggen ai sparql "Find all people" --graph data.ttl --output query.sparql

# Complex queries with prefixes
ggen ai sparql "Get user profiles with emails" --graph ontology.ttl \
  --prefixes "foaf=http://xmlns.com/foaf/0.1/" --output profiles.sparql

RDF Graph Generation

Generate RDF ontologies from domain descriptions:

ggen ai graph <description> [OPTIONS]

Options:
  --output <FILE>    Output RDF file
  --format <FORMAT>  Output format (ttl, jsonld, n3)

Examples:

# Generate domain ontologies
ggen ai graph "Person management system with roles" --output person.ttl

# E-commerce ontologies
ggen ai graph "Product catalog with categories and reviews" --output catalog.ttl

# Export as JSON-LD
ggen ai graph "Organization structure" --output org.jsonld --format jsonld

Project Scaffolding

Generate complete project structures:

ggen ai project <description> --name <NAME> --language <LANG> [OPTIONS]

Options:
  --framework <FRAMEWORK> Target framework
  --output <DIR>          Output directory
  --tests                 Include test files
  --docs                  Include documentation
  --ci                    Include CI/CD configuration

Examples:

# Rust web API project
ggen ai project "User management API" --name user-api --language rust \
  --framework axum --tests --docs --output user-api/

# Python CLI application
ggen ai project "Data processing tool" --name data-tool --language python \
  --output data-tool/

# Full-stack web application
ggen ai project "E-commerce platform" --name shop --language typescript \
  --framework nextjs --tests --docs --ci --output shop/

Source File Analysis

Extract templates from existing source code:

ggen ai from-source <file> [OPTIONS]

Options:
  --language <LANG>       Source language
  --output <FILE>         Output template file
  --extract-variables     Extract variables from code
  --include-rdf          Include RDF metadata

Examples:

# Extract Rust template
ggen ai from-source src/main.rs --language rust --output main.tmpl

# Extract with variable analysis
ggen ai from-source lib/utils.js --language javascript \
  --extract-variables --output utils.tmpl

AI Models and Providers

Supported Providers

ProviderModelsAccess
OpenAIGPT-4o, GPT-3.5-turboAPI key required
AnthropicClaude 3.5 Sonnet, Claude 3 HaikuAPI key required
OllamaQwen3-coder:30b, Llama 2, Code LlamaLocal installation
GeminiGemini Pro, Gemini UltraAPI key required
GroqMixtral 8x7B, Llama 2 70BAPI key required
CohereCommand R+, AyaAPI key required

Configuration

Environment Variables

# OpenAI
export OPENAI_API_KEY="your-key-here"

# Anthropic
export ANTHROPIC_API_KEY="your-key-here"

# Gemini
export GEMINI_API_KEY="your-key-here"

# Groq
export GROQ_API_KEY="your-key-here"

# Cohere
export COHERE_API_KEY="your-key-here"

Ollama Setup

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull models
ollama pull qwen3-coder:30b
ollama pull llama2:7b
ollama pull codellama:7b

Model Selection

# Use specific model
ggen ai generate "API controller" --model gpt-4o --output api.tmpl

# Use local Ollama model
ggen ai generate "CLI tool" --model qwen3-coder:30b --output cli.tmpl

# List available models
ggen ai models

Configuration

Global Configuration

# Set default model
ggen config set ai.model qwen3-coder:30b

# Set default temperature
ggen config set ai.temperature 0.7

# Set default max tokens
ggen config set ai.max_tokens 4096

Provider-Specific Configuration

# ~/.ggen/config.toml
[ai]
default_provider = "ollama"
default_model = "qwen3-coder:30b"

[ai.ollama]
endpoint = "http://localhost:11434"

[ai.openai]
api_key_env = "OPENAI_API_KEY"
model = "gpt-4o"

[ai.anthropic]
api_key_env = "ANTHROPIC_API_KEY"
model = "claude-3-sonnet-20240229"

Advanced Usage

Streaming Responses

Real-time streaming responses for interactive AI experiences:

# Basic streaming usage (Rust API)
use ggen_ai::{GenAiClient, LlmConfig};
use futures::StreamExt;

let client = GenAiClient::new(LlmConfig::default())?;
let mut stream = client.complete_stream("Write a function").await?;

while let Some(chunk) = stream.next().await {
    print!("{}", chunk.content);
}

Key Features:

  • Real-time output - Process tokens as they arrive
  • Memory efficient - No need to buffer entire response
  • Provider agnostic - Works with all supported providers
  • Tool call support - Handles function calling in streams

Supported Providers:

  • βœ… OpenAI (including tool calls and reasoning)
  • βœ… Anthropic Claude
  • βœ… Ollama (local models)
  • βœ… All other genai-supported providers

Custom Prompts

# Use custom prompt templates
ggen ai generate --prompt-template custom.tmpl "API description"

# Include additional context
ggen ai generate "Database model" --context "PostgreSQL, relationships"

Batch Generation

# Generate multiple templates
cat descriptions.txt | xargs -I {} ggen ai generate {} --output {}.tmpl

# Generate project components
find specs/ -name "*.md" | xargs -I {} basename {} .md | \
  xargs -I {} ggen ai generate --file specs/{}.md --output templates/{}.tmpl

Integration with Templates

# templates/complex-api.tmpl
---
to: "src/{{module_name}}.rs"
vars:
  module_name: "{{name}}"
  description: "{{description}}"
rdf:
  - "graphs/api.ttl"
sparql:
  routes: "SELECT ?route WHERE { ?api api:route ?route }"
---

use axum::{Router, routing::{{method}}};

pub fn {{module_name}}_router() -> Router {
    Router::new()
    {{#each (sparql query="routes")}}
        .route("{{this.route}}", {{this.method}}.handler)
    {{/each}}
}

Best Practices

Prompt Engineering

  1. Be specific: Include language, framework, and requirements
  2. Provide context: Reference existing code or patterns
  3. Use examples: Show expected output format
  4. Iterate: Refine prompts based on results

Quality Assurance

  1. Validate outputs: Use ggen ai validate to check templates
  2. Test generation: Verify generated code compiles/runs
  3. Review metadata: Check RDF graphs for semantic correctness
  4. Version control: Track template evolution

Performance

  1. Use appropriate models: Smaller models for simple tasks
  2. Batch operations: Generate multiple items together
  3. Cache results: Reuse successful generations
  4. Monitor costs: Track API usage for paid providers

Troubleshooting

Common Issues

Empty or invalid output:

  • Check model availability and API keys
  • Verify prompt clarity and specificity
  • Try different temperature settings

Compilation errors:

  • Validate generated code manually
  • Use ggen ai validate for template checking
  • Check framework compatibility

API rate limits:

  • Implement retry logic
  • Use local models when possible
  • Monitor usage quotas

Debug Mode

# Enable debug logging
export RUST_LOG=ggen_ai=debug
ggen ai generate "test" --debug

# Save prompts for analysis
ggen ai generate "test" --save-prompts

Examples

Complete Workflow

# 1. Generate ontology
ggen ai graph "User management with roles and permissions" --output user.ttl

# 2. Generate API from ontology
ggen ai generate "REST API for user management" --graph user.ttl \
  --language rust --framework axum --output api.tmpl

# 3. Generate tests
ggen ai generate "Unit tests for user API" --language rust \
  --framework tokio-test --output tests.tmpl

# 4. Generate documentation
ggen ai generate "API documentation" --language markdown \
  --output README.md.tmpl

# 5. Generate project structure
ggen ai project "User management system" --name user-system \
  --language rust --framework axum --tests --docs --output user-system/

This demonstrates the complete AI-powered development workflow from ontology to deployed application.

Table of Contents

Frontmatter schema (v1)

to: path/with/{{ vars }}
vars: { seed: cosmos }
rdf:
  - "graphs/core.ttl"
  - "graphs/x.jsonld"
shape:
  - "graphs/shapes/domain.ttl"
sparql:
  vars:
    - name: slug
      query: "SELECT ?slug WHERE { ?s <urn:ex#slug> ?slug } LIMIT 1"
  matrix:
    query: "SELECT ?id WHERE { ?s <urn:ex#id> ?id } ORDER BY ?id"
    bind: { id: "?id" }
determinism:
  sort: id
  seed: "{{ seed }}"

Validation JSON Schema: schema/frontmatter.schema.json.

Table of Contents

RDF / SHACL / SPARQL

  • RDF sources: Turtle, N-Triples, JSON-LD.
  • SHACL: core subset (NodeShape, PropertyShape, minCount, maxCount, datatype, class, pattern).
  • SPARQL: SELECT only. Require ORDER BY in matrix queries.

Merged data graph and shapes graph are hashed for determinism.

Table of Contents

Projections

Targets are just templates. ggen supports both marketplace gpacks and local templates for generating code projections.

Marketplace Gpack Examples

CLI Subcommands

# Install multi-language CLI gpacks
ggen add io.ggen.rust.cli-subcommand
ggen add io.ggen.python.cli-subcommand
ggen add io.ggen.bash.cli-subcommand

# Generate across languages
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=status
ggen gen io.ggen.python.cli-subcommand:cli/subcommand/python.tmpl name=status
ggen gen io.ggen.bash.cli-subcommand:cli/subcommand/bash.tmpl name=status

API Endpoints

# Install API gpacks
ggen add io.ggen.rust.api-endpoint
ggen add io.ggen.python.api-endpoint
ggen add io.ggen.typescript.api-endpoint

# Generate REST endpoints
ggen gen io.ggen.rust.api-endpoint:api/endpoint/rust.tmpl name=users
ggen gen io.ggen.python.api-endpoint:api/endpoint/python.tmpl name=users
ggen gen io.ggen.typescript.api-endpoint:api/endpoint/typescript.tmpl name=users

SQL DDL from Ontology

# Install SQL generation gpacks
ggen add io.ggen.sql.schema
ggen add io.ggen.sql.migrations

# Generate database schema
ggen gen io.ggen.sql.schema:schema/postgres.tmpl name=users
ggen gen io.ggen.sql.migrations:migration/postgres.tmpl name=add_users_table

Edge Function Stubs

# Install edge function gpacks
ggen add io.ggen.vercel.edge-function
ggen add io.ggen.cloudflare.worker

# Generate edge functions
ggen gen io.ggen.vercel.edge-function:edge/function.ts.tmpl name=api
ggen gen io.ggen.cloudflare.worker:worker/index.js.tmpl name=api

Documentation from Graph Annotations

# Install documentation gpacks
ggen add io.ggen.docs.api-reference
ggen add io.ggen.docs.user-guide

# Generate documentation
ggen gen io.ggen.docs.api-reference:docs/api.md.tmpl name=users
ggen gen io.ggen.docs.user-guide:docs/guide.md.tmpl name=getting-started

Local Template Examples

Custom Projections

# Create custom template
mkdir -p templates/custom/projection
cat > templates/custom/projection/rust.tmpl << 'EOF'
---
to: src/{{ name }}.rs
vars:
  name: example
---
pub struct {{ name | pascal }} {
    // Custom projection logic
}
EOF

# Generate custom projection
ggen gen custom projection --vars name=user

Discovering Projection Gpacks

By Category

# Browse categories
ggen categories

# Search by projection type
ggen search cli subcommand
ggen search api endpoint
ggen search sql schema
ggen search docs reference

By Language

# Search by language
ggen search rust
ggen search python
ggen search typescript
ggen search go

By Framework

# Search by framework
ggen search clap
ggen search fastapi
ggen search express
ggen search gin

Cross-Language Projections

Marketplace gpacks enable consistent projections across multiple languages:

Same RDF Ontology

All language-specific gpacks use the same semantic model:

  • Consistent variable binding
  • Identical SPARQL queries
  • Unified frontmatter structure

Deterministic Output

Version locking ensures reproducible results:

  • Same gpack versions β†’ identical outputs
  • Cross-language consistency
  • Deterministic generation

Projection Patterns

Standard Pattern

  1. Describe object in RDF - Define semantic model
  2. Bind vars via SPARQL - Extract variables from graph
  3. Render per target - Generate language-specific code

Marketplace Pattern

  1. Search for gpacks - Find language-specific templates
  2. Install dependencies - Get gpacks and dependencies
  3. Generate consistently - Use same RDF across languages

Local Pattern

  1. Create templates - Build custom projection logic
  2. Define RDF model - Specify semantic structure
  3. Generate outputs - Render to target formats

Best Practices

Gpack Selection

  • Choose gpacks with active maintenance
  • Verify compatibility with your ggen version
  • Check dependency requirements
  • Review example outputs

Version Management

  • Pin versions for production use
  • Test updates before applying
  • Use semantic versioning
  • Maintain lockfile consistency

Custom Projections

  • Start with marketplace gpacks
  • Extend with local templates
  • Share via gpack publishing
  • Document projection patterns

Table of Contents

Determinism

ggen ensures deterministic, reproducible code generation through manifest hashing and version locking.

Manifest Key Calculation

For local templates:

K = SHA256(seed || graph_hash || shapes_hash || frontmatter_hash || rows_hash)

For marketplace gpacks:

K = SHA256(seed || gpack_version || gpack_deps_hash || graph_hash || shapes_hash || frontmatter_hash || rows_hash)

Hash Components

Local Templates

  • Graph hash: sorted N-Quads from RDF sources
  • Shapes hash: sorted N-Quads from SHACL validation
  • Frontmatter hash: rendered header + body bytes
  • Rows hash: ordered serialization of matrix rows

Marketplace Gpacks

  • Gpack version: exact version from ggen.toml
  • Gpack deps hash: hash of all dependency versions
  • Graph hash: sorted N-Quads from gpack RDF sources
  • Shapes hash: sorted N-Quads from gpack SHACL validation
  • Frontmatter hash: rendered header + body bytes
  • Rows hash: ordered serialization of matrix rows

Version Locking

Gpack Version Management

# Install specific version
ggen add io.ggen.rust.cli-subcommand@0.2.1

# Check installed versions
ggen packs

# View lockfile
cat ggen.lock

Lockfile Structure

[lockfile]
version = "1.0"

[gpacks]
"io.ggen.rust.cli-subcommand" = "0.2.1"
"io.ggen.macros.std" = "0.2.0"

[dependencies]
"io.ggen.rust.cli-subcommand" = {
    version = "0.2.1",
    source = "registry",
    checksum = "sha256:abc123..."
}

Deterministic Behavior

Same Inputs β†’ Identical Outputs

# First generation
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello

# Second generation (same inputs)
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello

# Outputs are byte-identical
diff src/cmds/hello.rs src/cmds/hello.rs
# No differences

Cross-Language Consistency

# Generate across languages with same inputs
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello
ggen gen io.ggen.python.cli-subcommand:cli/subcommand/python.tmpl name=hello
ggen gen io.ggen.bash.cli-subcommand:cli/subcommand/bash.tmpl name=hello

# All outputs share the same semantic model
# Variable binding is consistent across languages

Gpack Dependencies and Determinism

Dependency Resolution

# Install gpack with dependencies
ggen add io.ggen.rust.cli-subcommand

# Dependencies are automatically resolved
ggen packs

# Output:
# ID                                    VERSION    KIND       TAGS
# io.ggen.rust.cli-subcommand           0.2.1      template   rust, cli, clap
# io.ggen.macros.std                    0.2.0      macro      rust, macros

Dependency Hashing

Dependencies affect determinism through their versions:

# Check dependency versions
ggen show io.ggen.rust.cli-subcommand --deps

# Update dependencies
ggen update

# Verify determinism after update
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello --dry

Ensuring Determinism

Gpack Development

# Pin versions in development
ggen add io.ggen.rust.cli-subcommand@0.2.1

# Test determinism
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=test1
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=test1
# Should produce identical output

Production Deployment

# Lock versions for production
ggen add io.ggen.rust.cli-subcommand@0.2.1
ggen add io.ggen.python.cli-subcommand@0.1.8

# Commit lockfile
git add ggen.lock
git commit -m "Lock gpack versions for production"

# Deploy with locked versions
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=api

Troubleshooting Determinism

Non-Deterministic Output

# Check for version changes
ggen packs

# Verify lockfile
cat ggen.lock

# Check for dependency updates
ggen update --dry

Manifest Key Changes

# Enable tracing to see hash components
GGEN_TRACE=1 ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello

# Output shows:
# Manifest key: sha256:abc123...
# Gpack version: 0.2.1
# Graph hash: sha256:def456...
# Frontmatter hash: sha256:ghi789...

Cross-Environment Consistency

# Ensure same gpack versions across environments
ggen add io.ggen.rust.cli-subcommand@0.2.1

# Verify environment consistency
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello --dry

Best Practices

Version Pinning

  • Pin specific versions for production
  • Use semantic versioning
  • Test updates before applying
  • Maintain lockfile consistency

Dependency Management

  • Minimize dependency depth
  • Use stable dependency versions
  • Test dependency updates
  • Document version requirements

Deterministic Testing

  • Test with multiple variable sets
  • Verify cross-language consistency
  • Use golden tests for validation
  • Monitor manifest key changes

Same inputs + same gpack versions + same dependencies β‡’ byte-identical outputs across all environments.

Table of Contents

CLI

Marketplace Commands

Search and Discovery

# Search for gpacks by keywords
ggen search <query>

# Examples:
ggen search rust cli
ggen search python api
ggen search typescript react

# Browse popular categories
ggen categories

# Get detailed gpack information
ggen show <gpack-id>

Installation and Management

# Install gpack (latest version)
ggen add <gpack-id>

# Install specific version
ggen add <gpack-id>@<version>

# Examples:
ggen add io.ggen.rust.cli-subcommand
ggen add io.ggen.rust.cli-subcommand@0.2.0

# List installed gpacks
ggen packs

# Update all gpacks to latest compatible versions
ggen update

# Update specific gpack
ggen update <gpack-id>

# Remove gpack
ggen remove <gpack-id>

Gpack Publishing (for authors)

# Initialize new gpack
ggen pack init

# Lint gpack for publishing
ggen pack lint

# Run tests
ggen pack test

# Publish to registry
ggen pack publish

AI Commands

ggen-ai v1.0.0 provides intelligent code generation using advanced LLMs with multi-provider support (OpenAI, Anthropic, Ollama, Gemini, Groq, Cohere).

AI Template Generation

# Generate templates from natural language descriptions
ggen ai generate <description> [--language LANG] [--framework FRAMEWORK] [--output FILE]

# Examples:
ggen ai generate "A Rust REST API controller for user management" --language rust --framework axum --output user_controller.tmpl
ggen ai generate "Python CLI tool for data processing" --language python --output data_tool.py.tmpl
ggen ai generate "React component for user profiles" --language typescript --framework react --output profile.tsx.tmpl

AI SPARQL Generation

# Generate SPARQL queries from natural language intent
ggen ai sparql <intent> [--graph FILE] [--output FILE] [--prefixes PREFIX=URI]

# Examples:
ggen ai sparql "Find all users with admin role" --graph data.ttl --output admin_query.sparql
ggen ai sparql "Get all properties of a resource" --graph ontology.ttl --output properties.sparql

AI RDF Graph Generation

# Generate RDF ontologies from domain descriptions
ggen ai graph <description> [--output FILE] [--format FORMAT]

# Examples:
ggen ai graph "Person management system with roles and permissions" --output person.ttl
ggen ai graph "E-commerce product catalog" --output catalog.ttl --format jsonld

AI Project Scaffolding

# Generate complete project structures
ggen ai project <description> --name NAME --language LANG [--framework FRAMEWORK] [--output DIR] [--tests] [--docs] [--ci]

# Examples:
ggen ai project "E-commerce API with authentication" --name shop-api --language rust --framework axum --tests --docs --output generated-shop-api/
ggen ai project "Python web application" --name webapp --language python --framework fastapi --output webapp/

AI Source File Analysis

# Generate templates from existing source files
ggen ai from-source <file> [--language LANG] [--output FILE] [--extract-variables] [--include-rdf]

# Examples:
ggen ai from-source src/main.rs --language rust --output main_template.tmpl
ggen ai from-source lib/utils.js --language javascript --extract-variables --output utils.tmpl

AI Model Management

# List available AI models and providers
ggen ai models

# Output shows supported models across all providers

AI Template Validation

# Validate templates with AI assistance
ggen ai validate <template> [--vars KEY=VALUE]

# Examples:
ggen ai validate templates/api.tmpl
ggen ai validate templates/cli.tmpl --vars name=hello

AI Demo

# Run the AI template demo
ggen ai demo

# Examples:
ggen ai demo --model qwen3-coder:30b

AI Frontmatter Generation

# Generate frontmatter for templates using AI
ggen ai frontmatter <template-file> [--description DESC] [--model MODEL]

# Examples:
ggen ai frontmatter api_controller.tmpl --description "REST API controller for user management"
ggen ai frontmatter data_processor.py.tmpl --model gpt-4o

Generation Commands

Template Generation

# Generate from gpack template
ggen gen <gpack-id>:<template-path> [--vars k=v ...] [--dry]

# Generate from local template
ggen gen <scope> <action> [--vars k=v ...] [--dry]

# Examples:
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello
ggen gen cli subcommand --vars cmd=hello summary="Print greeting"

Template Discovery

# List available templates (local + gpacks)
ggen list

# Show template details
ggen show <template-ref> [--vars k=v ...]

# Examples:
ggen show io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl
ggen show cli subcommand

Validation Commands

# Validate template frontmatter
ggen validate <template-ref> [--vars k=v ...]

# Lint template with schema validation
ggen lint <template-ref>

# Examples:
ggen validate io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl
ggen lint cli subcommand

Utility Commands

# Export RDF graph
ggen graph export <template-ref> --fmt ttl|jsonld

# Generate hazard report
ggen hazard

# Generate shell completion scripts
ggen completion bash|zsh|fish

Variable Precedence

Variables are resolved in this order (later values override earlier):

  1. CLI arguments (--var key=value)
  2. Environment variables (from .env files)
  3. System environment ($HOME, $USER, etc.)
  4. Gpack variables (from gpack ggen.toml)
  5. Template frontmatter (vars: section)
  6. SPARQL variables (from queries)

Gpack Template Reference Syntax

When using gpack templates, use the format:

<gpack-id>:<template-path>

Examples:

  • io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl
  • io.ggen.python.api:api/endpoint/fastapi.tmpl
  • io.ggen.typescript.react:components/button.tsx.tmpl

Dry-Run Mode

Preview template rendering without writing files:

ggen gen --template templates/api/endpoint/rust.tmpl --var name=User --dry

Dry-run behavior:

  • RDF graphs are loaded (read-only)
  • SPARQL queries execute normally
  • Templates render completely
  • Output shows what would be written
  • No files are created or modified
  • No shell commands execute (when implemented)
  • No injections occur (when implemented)

Table of Contents

Troubleshooting

General Issues

  • Missing output: check to: and matrix query.
  • Unbound var: pass --vars or add sparql.vars.
  • SHACL failure: fix data to satisfy shape.
  • Nondeterminism: ensure matrix query has ORDER BY and seed is fixed.
  • No writes: same K; use --dry-run to inspect.

Marketplace Issues

Gpack Not Found

# Error: gpack 'io.ggen.rust.cli-subcommand' not found
ggen add io.ggen.rust.cli-subcommand

# Check if gpack exists
ggen search rust cli

# Verify correct gpack ID
ggen show io.ggen.rust.cli-subcommand

Version Conflicts

# Error: version conflict for io.ggen.rust.cli-subcommand
# Check installed versions
ggen packs

# Remove conflicting version
ggen remove io.ggen.rust.cli-subcommand

# Install specific version
ggen add io.ggen.rust.cli-subcommand@0.2.1

Dependency Resolution Failures

# Error: dependency resolution failed
# Check gpack dependencies
ggen show io.ggen.rust.cli-subcommand

# Install missing dependencies
ggen add io.ggen.macros.std

# Update all gpacks
ggen update

Template Not Found in Gpack

# Error: template 'cli/subcommand/rust.tmpl' not found in gpack
# List available templates
ggen show io.ggen.rust.cli-subcommand

# Use correct template path
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello

Cache Corruption

# Error: corrupted gpack cache
# Clear cache
rm -rf .ggen/gpacks/

# Reinstall gpacks
ggen add io.ggen.rust.cli-subcommand

Network/Registry Connectivity

# Error: failed to connect to registry
# Check network connectivity
ping registry.ggen.io

# Verify registry URL
ggen search --help

# Try with verbose output
ggen search rust cli --verbose

Gpack Validation and Linting Errors

Invalid Gpack Manifest

# Error: invalid ggen.toml manifest
# Check manifest syntax
ggen pack lint

# Validate against schema
ggen validate io.ggen.rust.cli-subcommand

Template Schema Validation

# Error: template schema validation failed
# Lint template
ggen lint io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl

# Check frontmatter
ggen show io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl

RDF Graph Validation

# Error: RDF graph validation failed
# Validate RDF graphs
ggen validate io.ggen.rust.cli-subcommand --rdf-only

# Check SPARQL queries
ggen show io.ggen.rust.cli-subcommand --sparql

Local Template Issues

Template Discovery

# Error: template 'cli subcommand' not found
# Check template location
ls -la templates/cli/subcommand/

# Verify template structure
ggen list

Variable Resolution

# Error: unbound variable 'name'
# Check variable precedence
ggen gen cli subcommand --vars name=hello

# Verify template frontmatter
cat templates/cli/subcommand/rust.tmpl

Performance Issues

Slow Generation

# Enable tracing
GGEN_TRACE=1 ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello

# Check for large RDF graphs
ggen show io.ggen.rust.cli-subcommand --rdf-size

# Use dry run for testing
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello --dry

Memory Issues

# Error: out of memory
# Check RDF graph size
ggen graph export io.ggen.rust.cli-subcommand --fmt ttl | wc -l

# Use smaller graphs
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello --vars graph_size=small

Debugging Tips

Enable Verbose Output

# Show detailed execution
GGEN_TRACE=1 ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello

# Show variable resolution
ggen show io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl --vars name=hello --verbose

Check System State

# Verify installation
ggen --version

# Check gpack cache
ls -la .ggen/gpacks/

# View lockfile
cat ggen.lock

Test with Minimal Example

# Create minimal test template
echo '---\nto: test.txt\nvars:\n  name: world\n---\nHello {{ name }}!' > test.tmpl

# Test generation
ggen gen test.tmpl --vars name=world

# Verify output
cat test.txt

AI Integration Overview

Current Integration Status

AI Integration Clarification

Ollama Integration Guide

Multi-Provider Analysis

Runtime Model Configuration

Build Optimization

Cargo Best Practices

Table of Contents

ggen calculus (v1)

State Ξ£ = ⟨T,G,S,C,B,A,M,ΟƒβŸ©.

Pipeline:

project = write ∘ render* ∘ matrix? ∘ bind? ∘ shape ∘ load

Laws:

  • Determinism
  • Idempotent write
  • Precedence: CLI > SPARQL > defaults
  • Matrix ORDER BY required

Table of Contents

Ggen DX Features

This document covers all developer experience features in ggen, including both marketplace and local template workflows. These features focus on ergonomics, authoring workflows, error handling, and development productivity.

CLI Ergonomics

One Verb Philosophy

# Single command for everything
ggen gen <template> key=val ...

# No complex subcommand trees
# Just: ggen gen [template-ref] [options] [variables]

Auto-Discovery

# Automatically finds project configuration
cd my-project/
ggen gen cli subcommand name=hello  # Finds ggen.toml automatically

# Discovers templates directory
# Loads project-specific RDF graphs
# Merges environment variables

Variable Precedence

Variables are resolved in this order (later values override earlier):

  1. Environment variables (from .env files)
  2. System environment ($HOME, $USER, etc.)
  3. Project presets (from ggen.toml [preset] section)
  4. Template frontmatter (vars: section in template)
  5. CLI arguments (--var key=value)
# .env file
author=John Doe

# ggen.toml
[preset]
vars = { license = "MIT" }

# template frontmatter
vars:
  author: "Jane Smith"  # Overridden by CLI
  feature: "basic"

# CLI call
ggen gen cli subcommand --var author="CLI Author" --var feature="advanced"
# Result: author="CLI Author", license="MIT", feature="advanced"

Rich Dry Run

# Side-by-side diff view
ggen gen cli subcommand name=hello --dry

# Shows unified diff with context
# Displays target paths and variable summary
# No files written until you remove --dry

Execution Tracing

# See everything that happens during generation
GGEN_TRACE=1 ggen gen cli subcommand name=hello

# Outputs:
# === GGEN TRACE ===
# Template path: templates/cli/subcommand/rust.tmpl
# Resolved frontmatter:
# {to: "src/cmds/{{name}}.rs", vars: {name: "hello"}, ...}
# SPARQL prolog:
# @prefix cli: <urn:ggen:cli#> . @base <http://example.org/> .
# Target output path: src/cmds/hello.rs

Marketplace DX Features

Gpack Development Workflow

# Initialize new gpack
ggen pack init

# Add templates and dependencies
mkdir -p templates/cli/subcommand
# Create template files...

# Test gpack locally
ggen pack test

# Lint for publishing
ggen pack lint

# Publish to registry
ggen pack publish

Gpack Testing Best Practices

# Run golden tests
ggen pack test

# Test with different variables
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=test1
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=test2

# Verify deterministic output
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=test1
# Should produce identical output

Gpack Versioning Strategies

# Semantic versioning for gpacks
# Major.Minor.Patch
# 1.0.0 -> 1.0.1 (patch: bug fixes)
# 1.0.0 -> 1.1.0 (minor: new features)
# 1.0.0 -> 2.0.0 (major: breaking changes)

# Update gpack version
# Edit ggen.toml:
# version = "0.2.1"

# Test before publishing
ggen pack test
ggen pack lint

Authoring Loop

Live Development Mode

# Watch mode for rapid iteration
ggen dev --watch templates/

# Automatically re-renders when:
# - Template files change
# - Frontmatter is modified
# - RDF graphs are updated
# - SPARQL queries change

# Outputs to temp directory with live diff
# Perfect for template development

Gpack Development Mode

# Watch mode for gpack development
ggen pack dev --watch

# Automatically re-renders when:
# - Gpack templates change
# - Dependencies update
# - RDF graphs are modified
# - Tests need re-running

# Outputs to temp directory with live diff
# Perfect for gpack development

Template Scaffolding

# Generate new template with sensible defaults
ggen new template cli/subcommand/typescript

# Creates:
# templates/cli/subcommand/typescript.tmpl
# With standard frontmatter structure
# Includes example RDF and SPARQL
# Ready for customization

Template Documentation

# Get help for any template
ggen help cli/subcommand/rust.tmpl

# Shows:
# Template: cli/subcommand/rust.tmpl
# Description: Generate Rust CLI subcommand
# Required Variables:
#   name (string): Subcommand name
#   description (string): Help text
# Optional Variables:
#   author (string): Code author
# Examples:
#   ggen gen cli/subcommand/rust.tmpl name=status description="Show status"
# Dependencies:
#   RDF: graphs/cli.ttl
#   Queries: SELECT ?name ?description WHERE { ?cmd rdfs:label ?name }

Manifest Preview

# See what would be generated without running templates
ggen plan cli subcommand

# Shows:
# Would generate:
#   src/cmds/hello.rs (from templates/cli/subcommand/rust.tmpl)
#   src/cmds/goodbye.rs (from templates/cli/subcommand/rust.tmpl)
#   commands/hello.py (from templates/cli/subcommand/python.tmpl)
#
# Variables applied:
#   name=hello, description="Say hello"
#   name=goodbye, description="Say goodbye"

Error Handling

Tera Template Errors

# File:line:col with 5-line snippet and highlighted token
Error in templates/api/endpoint/rust.tmpl:12:8
   |
10 | pub struct {{name|pascal}}Handler {
11 |     // TODO: Add fields
12 |     pub {{field_name}
   |           ^^^^^^^^
   |
Expected closing `}}` for variable `field_name`

Suggestion: Add `}}` after field_name

Frontmatter Validation Errors

# Path.to.field with expected type and example
Error in templates/cli/subcommand/rust.tmpl frontmatter:
  .rdf[0] : Expected string, found array

  Expected format:
  rdf:
    - "graphs/cli.ttl"

  Got:
  rdf:
    - ["graphs/cli.ttl"]

Suggestion: Use string instead of array for single file

SPARQL Query Errors

# Shows prepended prolog and failing variable binding
SPARQL Error in templates/api/endpoint/rust.tmpl:
Query:
  @prefix api: <urn:ggen:api#> .
  @base <http://example.org/> .
  SELECT ?name ?type WHERE {
    ?endpoint a api:Endpoint .
    ?endpoint api:name ?name .
    ?endpoint api:type ?type
  }

Variable binding failed for ?type:
  No value found for variable 'type' in graph

Suggestion: Check RDF data or query pattern
Available variables: ?name, ?endpoint

Injection Errors

# Shows first non-matching context lines and regex used
Injection Error in src/main.rs:
Pattern 'fn main\(\) {' not found in file

Context (first 10 lines):
  1 | use std::env;
  2 |
  3 | fn main() {
  4 |     println!("Hello, world!");
  5 | }

Regex used: fn main\(\) \{

Suggestion: Check if pattern exists in target file
Try: --dry to preview injection before applying

Hygen Parity

Complete Frontmatter Support

All Hygen frontmatter keys supported 1:1:

---
to: "src/{{type}}s/{{name}}.rs"           # Output path
from: "templates/base.rs"                  # Source template
force: true                               # Overwrite existing
unless_exists: true                       # Skip if exists
inject: true                              # Enable injection mode
before: "// Existing content"             # Inject before pattern
after: "fn main() {"                      # Inject after pattern
prepend: true                             # Prepend to file
append: true                              # Append to file
at_line: 10                               # Inject at line number
eof_last: true                            # Inject before EOF
skip_if: "// GENERATED"                   # Skip if pattern found
sh_before: "echo 'Generating...'"         # Pre-generation shell
sh_after: "cargo fmt"                     # Post-generation shell
---

Regex-Based Injection

# Compiled once for performance
# Deterministic first-match behavior
# All injection modes use regex patterns

# Inject before existing function
before: "fn existing_function\(\) {"

# Inject after struct definition
after: "struct ExistingStruct \{[^}]*\}"

# Skip if already injected
skip_if: "// GENERATED CODE"

Idempotency Guarantees

# Checked before any write operation
# Echo reason in dry-run mode

# If skip_if pattern found:
#   β†’ Skip injection entirely
#   β†’ Log: "Skipped injection: pattern found"

# If unless_exists and file exists:
#   β†’ Skip generation entirely
#   β†’ Log: "Skipped generation: file exists"

Determinism & Previews

Default Diff View

# Diff shown by default in --dry mode
ggen gen cli subcommand name=hello --dry

# Unified diff format:
# --- templates/cli/subcommand/rust.tmpl
# +++ would generate: src/cmds/hello.rs
# @@ -1,4 +1,4 @@
# -use utils::error::Result;
# +use utils::error::Result;
# +
# +#[derive(clap::Args, Debug)]
# +pub struct HelloArgs {
# +    /// Name to greet
# +    #[arg(short, long, default_value = "World")]
# +    pub name: String,
# +}

Content Hashing

# Printed after successful write
ggen gen cli subcommand name=hello

# Output:
# Generated: src/cmds/hello.rs
# Content hash: sha256:a1b2c3d4e5f6...

# Same inputs β†’ identical bytes
# Enables caching and change detection

Stable Ordering

# --idempotency-key seeds stable ordering
ggen gen cli subcommand --idempotency-key "my-project"

# Multi-file generation produces consistent output order
# Same key β†’ same file ordering across runs

Graph (RDF) Integration

Single Shared Graph

#![allow(unused)]
fn main() {
// One Graph instance per pipeline run
// Preloads project + template RDF once
// Cached query results for performance

let mut pipeline = Pipeline::new()?;
pipeline.load_rdf("graphs/project.ttl")?;
pipeline.load_rdf("graphs/cli.ttl")?;
}

SPARQL Functions

// In templates:
{{ sparql(query="SELECT ?name WHERE { ?cmd rdfs:label ?name }") }}

// Named queries with parameters:
{{ sparql_named(name="command_by_name", var="name=hello") }}

// Results available as JSON in templates
{% for cmd in sparql_results %}
pub struct {{cmd.name}}Args;
{% endfor %}

Automatic Prolog Building

# Frontmatter automatically builds prolog:
prefixes:
  cli: "urn:ggen:cli#"
  ex: "http://example.org/"

base: "http://example.org/"

# Generates:
# @prefix cli: <urn:ggen:cli#> .
# @prefix ex: <http://example.org/> .
# @base <http://example.org/> .

Template Helpers

Text Transformation Filters

// All Inflector + Heck filters available:
{{ name | camel }}           // userName
{{ name | pascal }}          // UserName
{{ name | snake }}           // user_name
{{ name | kebab }}           // user-name
{{ name | shouty_snake }}    // USER_NAME
{{ name | plural }}          // users
{{ name | singular }}        // user

Built-in Functions

// Local name from IRI
{{ local(iri="<http://example.org/User>") }}  // "User"

// Slug generation
{{ slug(text="Hello World!") }}              // "hello-world"

// Indentation control
{{ indent(text="line1\nline2", n=2) }}       // "  line1\n  line2"

// Newline insertion
{{ newline(n=3) }}                           // "\n\n\n"

Safety & Guardrails

Safe Write Root

# Safe write root = current directory
ggen gen cli subcommand name=hello

# Generates: ./src/cmds/hello.rs
# Cannot write outside project root

# Override with --unsafe-write (requires explicit opt-in)
ggen gen cli subcommand name=hello --unsafe-write /tmp/output

Shell Hook Controls

# Off by default for security
sh_before: "echo 'Generating...'"    # Not executed
sh_after: "cargo fmt"                # Not executed

# Enable with --allow-sh flag
ggen gen template --allow-sh

# Always preview in --dry mode
ggen gen template --dry --allow-sh  # Shows what shell commands would run

Network Restrictions

# No network during render by default
# Prevents malicious template behavior

# Enable network for gpack fetching only
ggen add io.ggen.rust.cli-subcommand --net

# Network only for registry operations
# Templates cannot make HTTP requests

Configuration & Discovery

Project Configuration

# ggen.toml - single source of project config
[project]
name = "My CLI Tool"
version = "0.1.0"

[prefixes]
ex = "http://example.org/"

[rdf]
files = ["templates/**/graphs/*.ttl"]
inline = ["@prefix ex: <http://example.org/> . ex:Project a ex:Tool ."]

[preset]
vars = { author = "Team", license = "MIT" }

Health Check

# Validate entire project setup
ggen doctor

# Checks:
# βœ“ ggen.toml syntax
# βœ“ Template frontmatter validity
# βœ“ RDF graph well-formedness
# βœ“ SPARQL query syntax
# βœ“ File path resolution
# βœ“ Gpack compatibility

Path Resolution

# All paths resolved relative to ggen.toml location
# Printed in --trace mode for debugging

# Project structure:
# my-project/
#   ggen.toml
#   graphs/cli.ttl
#   templates/cli/subcommand/rust.tmpl

# Paths automatically resolved:
# graphs/cli.ttl β†’ /path/to/my-project/graphs/cli.ttl
# templates/cli/subcommand/rust.tmpl β†’ /path/to/my-project/templates/cli/subcommand/rust.tmpl

Testing Infrastructure

Golden Test System

# Run golden tests for specific template
ggen test cli/subcommand/rust.tmpl

# Test structure:
# tests/golden/cli/subcommand/rust.tmpl/
#   input.toml     # Variables for test
#   output.rs      # Expected output

# Update goldens after changes
ggen test cli/subcommand/rust.tmpl --update-goldens

Test Organization

# tests/golden/cli/subcommand/rust.tmpl/input.toml
name = "hello"
description = "Print a greeting"
author = "Team"

# Generates and compares against:
# tests/golden/cli/subcommand/rust.tmpl/output.rs

Pipeline Integration

Builder Pattern

#![allow(unused)]
fn main() {
// Fluent API for pipeline configuration
let pipeline = Pipeline::builder()
    .with_rdf("graphs/project.ttl")
    .with_prefixes([("ex", "http://example.org/")])
    .with_templates_dir("custom-templates")
    .with_cache_strategy(CacheStrategy::Memory)
    .build()?;
}

Single Render Call

#![allow(unused)]
fn main() {
// One method handles everything
let plan = pipeline.render_file(
    "templates/cli/subcommand/rust.tmpl",
    &variables,
    DryRun::No
)?;

// Apply or preview
plan.apply()?;           // Write files
plan.print_diff()?;      // Show diff
}

Sensible Defaults

Pre-filled Context

// Available in all templates:
{{ cwd }}              // Current working directory
{{ env.HOME }}         // User home directory
{{ git.branch }}       // Current git branch
{{ git.user }}         // Git user name
{{ now }}              // RFC3339 timestamp

Flexible Output Control

# to: can be null to skip file generation
to: null               # No file written

# from: overrides template body
from: "base-template.rs"  # Use different source

# Works with all injection modes
inject: true
before: "fn main() {"

Error Recovery

Graceful Degradation

# Missing optional RDF β†’ continues with empty graph
# Invalid SPARQL query β†’ shows helpful error
# Template syntax error β†’ precise location + suggestion
# Path traversal attempt β†’ clear security message

Recovery Suggestions

# Every error includes actionable next steps
Error: Template 'missing.tmpl' not found
Suggestion: Available templates:
  - cli/subcommand/rust.tmpl
  - api/endpoint/typescript.tmpl
  - Run 'ggen list' to see all options

Performance Optimizations

Streaming & Caching

# Large RDF graphs processed incrementally
# Repeated queries cached automatically
# Template compilation cached per-run
# File I/O batched for efficiency

Memory Efficiency

# Bounded caches prevent memory leaks
# Stream processing for large files
# Minimal allocations in hot paths
# LTO enabled in release builds

Development Workflow

Rapid Iteration Cycle

# 1. Edit template
# 2. Test with --dry
# 3. Check --trace output
# 4. Iterate quickly

ggen gen template --dry --trace
# β†’ See exactly what happens
# β†’ Fix issues immediately
# β†’ No waiting for file writes

Template Debugging

# Debug template logic step by step
GGEN_TRACE=1 ggen gen template

# See:
# - Frontmatter resolution
# - Variable precedence
# - SPARQL query execution
# - Template rendering
# - File path calculation

Integration Benefits

IDE Support

# Rich error messages work in IDEs
# Template syntax highlighting
# Variable name completion
# Live preview of generated code
# Source maps for debugging

Tool Integration

# JSON output for CI/CD
ggen gen template --dry --json > plan.json

# Machine-readable error format
# Structured logging for dashboards
# Metrics collection hooks

Best Practices

Template Organization

templates/
  cli/
    subcommand/
      rust.tmpl
      python.tmpl
      bash.tmpl
  api/
    endpoint/
      rust.tmpl
      typescript.tmpl
  component/
    mod.rs.tmpl

Variable Naming

# Use descriptive variable names
vars:
  component_name: "UserService"
  api_version: "v1"
  author_email: "team@example.com"

# Avoid generic names like 'name', 'type'
# Use domain-specific names

Error Prevention

# Validate early with schemas
# Use RDF shapes for data validation
# Test templates with golden tests
# Use --dry before --allow-sh

This comprehensive DX system provides fast feedback, predictable outputs, clear error messages, and zero ceremonyβ€”exactly the developer experience lift that covers 80% of use cases while maintaining the power and flexibility needed for complex scenarios.

Table of Contents

Gpack Development Guide

This guide covers creating, testing, and publishing gpacks to the ggen marketplace.

Overview

Gpacks are versioned template collections that can be shared across the ggen community. They include:

  • Templates: .tmpl files with YAML frontmatter
  • Macros: Reusable template fragments (.tera files)
  • RDF Graphs: Semantic models and SPARQL queries
  • Tests: Golden tests for validation
  • Dependencies: Other gpacks this gpack depends on

Getting Started

Initialize New Gpack

# Create new gpack
ggen pack init

# This creates:
# β”œβ”€β”€ ggen.toml          # Gpack manifest
# β”œβ”€β”€ templates/          # Template directory
# β”œβ”€β”€ macros/            # Macro directory
# β”œβ”€β”€ graphs/            # RDF graphs
# β”œβ”€β”€ tests/             # Test directory
# └── README.md          # Documentation

Gpack Structure

my-gpack/
β”œβ”€β”€ ggen.toml              # Gpack manifest
β”œβ”€β”€ templates/             # Template files
β”‚   └── cli/
β”‚       └── subcommand/
β”‚           β”œβ”€β”€ rust.tmpl
β”‚           β”œβ”€β”€ graphs/         # Local RDF data
β”‚           β”‚   β”œβ”€β”€ cli.ttl
β”‚           β”‚   └── shapes/
β”‚           β”‚       └── cli.shacl.ttl
β”‚           └── queries/        # Local SPARQL queries
β”‚               └── commands.rq
β”œβ”€β”€ macros/                # Reusable fragments
β”‚   └── common.tera
β”œβ”€β”€ tests/                 # Golden tests
β”‚   └── test_hello.rs
β”œβ”€β”€ README.md              # Documentation
└── .gitignore             # Git ignore file

Gpack Manifest (ggen.toml)

Basic Manifest

[gpack]
id = "io.ggen.rust.cli-subcommand"
name = "Rust CLI subcommand"
version = "0.1.0"
description = "Generate clap subcommands"
license = "MIT"
authors = ["Your Name <your.email@example.com>"]
repository = "https://github.com/your-org/your-gpack"
homepage = "https://github.com/your-org/your-gpack"
keywords = ["rust", "cli", "clap"]
ggen_compat = ">=0.2 <0.4"

[dependencies]
"io.ggen.macros.std" = "^0.2"

[templates]
entrypoints = ["cli/subcommand/rust.tmpl"]
includes   = ["macros/**/*.tera"]

[rdf]
base = "http://example.org/"
prefixes.ex = "http://example.org/"
files  = ["templates/**/graphs/*.ttl"]
inline = ["@prefix ex: <http://example.org/> . ex:Foo a ex:Type ."]

Manifest Fields

Required Fields

  • id: Unique identifier (reverse domain notation)
  • name: Human-readable name
  • version: Semantic version
  • description: Brief description
  • license: License identifier
  • ggen_compat: Required ggen version range

Optional Fields

  • authors: List of authors
  • repository: Source repository URL
  • homepage: Project homepage
  • keywords: Search keywords
  • readme: Path to README file
  • changelog: Path to changelog file

Template Development

Template Structure

---
to: "src/cmds/{{ name | snake_case }}.rs"
vars:
  name: "example"
  description: "Example command"
rdf:
  inline:
    - mediaType: text/turtle
      text: |
        @prefix cli: <urn:ggen:cli#> .
        [] a cli:Command ;
           cli:name "{{ name }}" ;
           cli:description "{{ description }}" .
sparql:
  vars:
    - name: slug
      query: |
        PREFIX cli: <urn:ggen:cli#>
        SELECT ?slug WHERE { ?c a cli:Command ; cli:name ?slug } LIMIT 1
determinism:
  seed: "{{ name }}"
---
// Generated by gpack: {{ gpack.id }}
// Template: {{ template.path }}

use clap::Parser;

#[derive(Parser)]
pub struct {{ name | pascal }}Args {
    /// {{ description }}
    #[arg(short, long)]
    pub verbose: bool,
}

pub fn {{ name | snake_case }}(args: {{ name | pascal }}Args) -> Result<(), Box<dyn std::error::Error>> {
    println!("{{ name | pascal }} command executed");
    if args.verbose {
        println!("Verbose mode enabled");
    }
    Ok(())
}

Template Best Practices

  1. Use semantic variable names: name, description, version
  2. Include RDF models: Define semantic structure
  3. Add SPARQL queries: Extract variables from graphs
  4. Include determinism: Use seeds for reproducibility
  5. Add comments: Document generated code
  6. Use filters: Apply transformations (| snake_case, | pascal)

Macro Development

Creating Macros

{#- Common CLI argument structure #}
{% macro cli_args(name, description) %}
#[derive(Parser)]
pub struct {{ name | pascal }}Args {
    /// {{ description }}
    #[arg(short, long)]
    pub verbose: bool,
}
{% endmacro %}

{#- Common error handling #}
{% macro error_handling() %}
-> Result<(), Box<dyn std::error::Error>> {
    // Error handling logic
    Ok(())
}
{% endmacro %}

Using Macros

---
to: "src/cmds/{{ name }}.rs"
---
{% import "macros/common.tera" as common %}

{{ common::cli_args(name, description) }}

pub fn {{ name }}(args: {{ name | pascal }}Args) {{ common::error_handling() }}

RDF Graph Development

Graph Structure

@prefix cli: <urn:ggen:cli#> .
@prefix ex: <http://example.org/> .
@base <http://example.org/> .

ex:Command a cli:Command ;
    cli:name "example" ;
    cli:description "Example command" ;
    cli:subcommands (
        ex:StatusCommand
        ex:ConfigCommand
    ) .

ex:StatusCommand a cli:Command ;
    cli:name "status" ;
    cli:description "Show status" .

ex:ConfigCommand a cli:Command ;
    cli:name "config" ;
    cli:description "Manage configuration" .

SPARQL Queries

PREFIX cli: <urn:ggen:cli#>
PREFIX ex: <http://example.org/>

# Extract command names
SELECT ?name WHERE {
    ?cmd a cli:Command ;
         cli:name ?name .
}

# Extract subcommands
SELECT ?parent ?child WHERE {
    ?parent a cli:Command ;
            cli:subcommands ?child .
    ?child a cli:Command .
}

Testing

Golden Tests

#![allow(unused)]
fn main() {
// tests/test_hello.rs
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_hello_command() {
        // Test generated code compiles
        let args = HelloArgs { verbose: false };
        let result = hello(args);
        assert!(result.is_ok());
    }
}
}

Test Configuration

# ggen.toml
[tests]
golden = ["tests/*.rs"]
variables = [
    { name = "test1", description = "Test command 1" },
    { name = "test2", description = "Test command 2" }
]

Running Tests

# Run all tests
ggen pack test

# Run specific test
ggen pack test --test test_hello

# Run with verbose output
ggen pack test --verbose

Linting and Validation

Lint Gpack

# Lint gpack for publishing
ggen pack lint

# Lint specific template
ggen pack lint --template templates/cli/subcommand/rust.tmpl

# Lint with fixes
ggen pack lint --fix

Validation Checks

The linter checks for:

  • Manifest validity: Correct ggen.toml structure
  • Template syntax: Valid YAML frontmatter
  • RDF validity: Well-formed RDF graphs
  • SPARQL syntax: Valid SPARQL queries
  • Dependencies: Resolvable dependencies
  • Versioning: Semantic versioning compliance

Publishing

Prepare for Publishing

# Update version
# Edit ggen.toml:
# version = "0.2.0"

# Run tests
ggen pack test

# Lint gpack
ggen pack lint

# Generate changelog
ggen pack changelog

Publish to Registry

# Publish gpack
ggen pack publish

# Publish with specific version
ggen pack publish --version 0.2.0

# Publish with dry run
ggen pack publish --dry-run

Publishing Process

  1. Validation: Gpack is validated against schema
  2. Testing: Golden tests are run
  3. Linting: Code quality checks
  4. Registry Upload: Gpack is uploaded to registry
  5. Index Update: Registry index is updated
  6. Notification: Community is notified

Versioning

Semantic Versioning

Follow semantic versioning (semver):

  • Major (1.0.0 β†’ 2.0.0): Breaking changes
  • Minor (1.0.0 β†’ 1.1.0): New features
  • Patch (1.0.0 β†’ 1.0.1): Bug fixes

Version Guidelines

  • 0.x.x: Development versions
  • 1.x.x: Stable versions
  • Pre-release: Use -alpha, -beta, -rc suffixes

Changelog

# Changelog

## [0.2.0] - 2024-01-15

### Added
- New CLI subcommand template
- Support for verbose flag
- Error handling macros

### Changed
- Updated RDF model structure
- Improved SPARQL queries

### Fixed
- Template variable resolution
- Macro import issues

## [0.1.0] - 2024-01-01

### Added
- Initial release
- Basic CLI subcommand template

Dependencies

Adding Dependencies

# ggen.toml
[dependencies]
"io.ggen.macros.std" = "^0.2"
"io.ggen.common.rdf" = "~0.1.0"
"io.ggen.rust.cli" = ">=0.1.0 <0.3.0"

Dependency Types

  • Caret (^): Compatible versions (^0.2.0 = >=0.2.0 <0.3.0)
  • Tilde (~): Patch-level changes (~0.1.0 = >=0.1.0 <0.2.0)
  • Exact: Specific version (=0.2.1)
  • Range: Version range (>=0.1.0 <0.3.0)

Dependency Resolution

# Check dependencies
ggen pack deps

# Update dependencies
ggen pack update

# Resolve conflicts
ggen pack resolve

Best Practices

Gpack Design

  1. Single Responsibility: One gpack, one purpose
  2. Consistent API: Use standard variable names
  3. Documentation: Include README and examples
  4. Testing: Comprehensive golden tests
  5. Versioning: Follow semver strictly

Template Quality

  1. Readability: Clear, well-commented code
  2. Maintainability: Modular, reusable templates
  3. Performance: Efficient SPARQL queries
  4. Security: Validate all inputs
  5. Accessibility: Follow language best practices

Community Guidelines

  1. Naming: Use descriptive, consistent names
  2. Licensing: Choose appropriate licenses
  3. Contributing: Welcome community contributions
  4. Support: Provide issue tracking
  5. Updates: Regular maintenance and updates

Troubleshooting

Common Issues

Template Not Found

# Check template path
ggen pack lint --template templates/cli/subcommand/rust.tmpl

# Verify entrypoints in manifest
cat ggen.toml | grep entrypoints

Dependency Conflicts

# Check dependency tree
ggen pack deps --tree

# Resolve conflicts
ggen pack resolve --force

RDF Validation Errors

# Validate RDF graphs
ggen pack lint --rdf-only

# Check SPARQL syntax
ggen pack lint --sparql-only

Test Failures

# Run tests with verbose output
ggen pack test --verbose

# Check test configuration
cat ggen.toml | grep -A 10 "\[tests\]"

Getting Help

  • Documentation: Check this guide and other docs
  • Community: Join ggen community forums
  • Issues: Report bugs and request features
  • Discussions: Ask questions and share ideas

Advanced Topics

Custom Filters

#![allow(unused)]
fn main() {
// Add custom Tera filters
use tera::{Filter, Value, Result};

pub fn custom_filter(value: &Value, _: &HashMap<String, Value>) -> Result<Value> {
    // Custom filter logic
    Ok(value.clone())
}
}

Plugin System

# ggen.toml
[plugins]
"io.ggen.plugin.custom" = "^0.1.0"

CI/CD Integration

# .github/workflows/publish.yml
name: Publish Gpack

on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install ggen
        run: cargo install ggen
      - name: Test gpack
        run: ggen pack test
      - name: Lint gpack
        run: ggen pack lint
      - name: Publish gpack
        run: ggen pack publish
        env:
          GGEN_REGISTRY_TOKEN: ${{ secrets.GGEN_REGISTRY_TOKEN }}

This guide provides comprehensive coverage of gpack development, from initial creation to publishing and maintenance. Follow these practices to create high-quality, maintainable gpacks for the ggen community.

Table of Contents

Multi-language CLI subcommand

Generate the same CLI subcommand across multiple languages using curated gpacks.

1. Install Language-Specific Gpacks

# Install gpacks for different languages
ggen add io.ggen.rust.cli-subcommand
ggen add io.ggen.python.cli-subcommand
ggen add io.ggen.bash.cli-subcommand
ggen add io.ggen.go.cli-subcommand

2. Generate Across Languages

# Generate Rust CLI subcommand
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello description="Print a greeting"

# Generate Python CLI subcommand
ggen gen io.ggen.python.cli-subcommand:cli/subcommand/python.tmpl name=hello description="Print a greeting"

# Generate Bash CLI subcommand
ggen gen io.ggen.bash.cli-subcommand:cli/subcommand/bash.tmpl name=hello description="Print a greeting"

# Generate Go CLI subcommand
ggen gen io.ggen.go.cli-subcommand:cli/subcommand/go.tmpl name=hello description="Print a greeting"

3. Verify Deterministic Output

# Check that all outputs are consistent
ls -la src/cmds/hello.rs commands/hello.py commands/hello.sh cmd/hello.go

# Verify determinism by regenerating
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello description="Print a greeting"
# Should produce identical output

Produces:

src/cmds/hello.rs
commands/hello.py
commands/hello.sh
cmd/hello.go

Using Local Templates (Advanced)

For custom multi-language generation using local templates:

ggen gen cli subcommand --vars cmd=hello summary="Print a greeting"

Produces, if templates exist:

src/cmds/hello.rs
commands/hello.py
commands/hello.sh

Determinism Verification

Gpack Version Locking

Gpacks ensure determinism through version locking:

# Check installed versions
ggen packs

# Output:
# ID                                    VERSION    KIND       TAGS
# io.ggen.rust.cli-subcommand           0.2.1      template   rust, cli, clap
# io.ggen.python.cli-subcommand         0.1.8      template   python, cli, click
# io.ggen.bash.cli-subcommand            0.1.2      template   bash, cli, getopts

Lockfile Management

# View lockfile
cat ggen.lock

# Update to latest compatible versions
ggen update

# Verify determinism
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello description="Print a greeting" --dry

Cross-Language Consistency

All generated subcommands share the same semantic model:

  • Same RDF ontology across all languages
  • Consistent variable binding via SPARQL queries
  • Identical frontmatter structure
  • Deterministic output through version locking

Best Practices

Gpack Selection

# Search for multi-language gpacks
ggen search cli subcommand

# Look for gpacks with multiple language support
ggen show io.ggen.rust.cli-subcommand

Version Management

# Pin specific versions for production
ggen add io.ggen.rust.cli-subcommand@0.2.1
ggen add io.ggen.python.cli-subcommand@0.1.8

# Update carefully
ggen update --dry  # Preview updates
ggen update        # Apply updates

Testing Multi-Language Output

# Test all languages
for lang in rust python bash go; do
  ggen gen io.ggen.${lang}.cli-subcommand:cli/subcommand/${lang}.tmpl name=test description="Test command"
done

# Verify consistency
diff <(grep -o 'name.*test' src/cmds/test.rs) <(grep -o 'name.*test' commands/test.py)

Same RDF + seed + gpack versions β‡’ byte-identical outputs across all languages.

Table of Contents

Example: CLI subcommand

1. Search and Install

# Search for CLI subcommand gpacks
ggen search rust cli

# Install the gpack
ggen add io.ggen.rust.cli-subcommand

2. Generate Code

# Generate using the gpack template
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=status description="Show application status"

3. Verify Output

# Check generated file
cat src/cmds/status.rs

Output:

#![allow(unused)]
fn main() {
// Generated by gpack: io.ggen.rust.cli-subcommand
// Template: cli/subcommand/rust.tmpl

use clap::Parser;

#[derive(Parser)]
pub struct StatusArgs {
    /// Show application status
    #[arg(short, long)]
    pub verbose: bool,
}

pub fn status(args: StatusArgs) -> Result<(), Box<dyn std::error::Error>> {
    println!("Application status: Running");
    if args.verbose {
        println!("Detailed status information...");
    }
    Ok(())
}
}

Using Local Template (Advanced)

Create templates/cli/subcommand/rust.tmpl (see quickstart for full template).

Generate:

ggen gen cli subcommand --vars cmd=status summary="Show status"

Outputs:

src/cmds/status.rs

Comparison

ApproachSetup TimeQualityUpdatesBest For
MarketplaceInstantCommunity testedAutomaticMost users
LocalManualCustomManualSpecial needs

Next Steps

Table of Contents

Example: SQL from ontology

---
to: db/{{ table }}.sql
rdf:
  - "graphs/domain.ttl"
sparql:
  matrix:
    query: |
      PREFIX nk: <https://neako.app/onto#>
      SELECT ?table ?col ?dtype WHERE {
        ?c a nk:Class ; nk:sqlName ?table .
        ?c nk:property [ nk:sqlName ?col ; nk:sqlType ?dtype ] .
      } ORDER BY ?table ?col
    bind: { table: "?table", col: "?col", dtype: "?dtype" }
determinism: { seed: schema-1, sort: table }
---
CREATE TABLE {{ table }} (
  {{ col }} {{ dtype }}
);

Run:

ggen gen db schema

Table of Contents

πŸͺ Marketplace

The ggen marketplace provides a curated ecosystem of reusable code generation packs (gpacks) served via GitHub Pages with automated validation and deployment. Discover, install, and use high-quality templates from the community.

πŸ“š About

The ggen marketplace provides a curated ecosystem of reusable code generation packs (gpacks) served via GitHub Pages with automated validation and deployment. Discover, install, and use high-quality templates from the community.

Key Statistics

MetricValue
Available Gpacks1
Open Source100%
LicenseMIT

πŸ” Registry API

Access the marketplace registry programmatically:

# Registry URL: https://seanchatmangpt.github.io/ggen/registry/
# API Endpoint: https://seanchatmangpt.github.io/ggen/registry/index.json

πŸš€ Quick Start

Get started with the ggen marketplace:

# Search for gpacks
ggen search rust cli

# Install an gpack
ggen add io.ggen.rust.cli-subcommand

# Use installed gpack
ggen gen io.ggen.rust.cli-subcommand:rust.tmpl cmd=test

πŸ“¦ Available Gpacks

Currently available gpacks in the marketplace:

io.ggen.rust.cli-subcommand
β”œβ”€β”€ Generate clap subcommands for Rust CLI applications
β”œβ”€β”€ Version: 0.1.0
β”œβ”€β”€ License: MIT
└── Tags: rust, cli, clap, subcommand

πŸ”§ Configuration

Configure the marketplace registry URL:

# Use GitHub Pages marketplace (default)
export GGEN_REGISTRY_URL="https://seanchatmangpt.github.io/ggen/registry/"

# Use local registry for development/testing
export GGEN_REGISTRY_URL="file:///path/to/local/registry/"

# Use custom registry
export GGEN_REGISTRY_URL="https://your-registry.com/"

πŸ“– Documentation

Learn more about using and contributing to the marketplace:


Built with ❀️ by the ggen community | GitHub

{ "updated": "2024-12-19T00:00:00Z", "packs": { "io.ggen.rust.cli-subcommand": { "id": "io.ggen.rust.cli-subcommand", "name": "Rust CLI Subcommand", "description": "Generate clap subcommands for Rust CLI applications with proper error handling and testing", "tags": ["rust", "cli", "clap", "subcommand"], "keywords": ["rust", "cli", "clap", "command-line", "terminal"], "category": "rust", "author": "ggen-team", "latest_version": "0.1.0", "versions": { "0.1.0": { "version": "0.1.0", "git_url": "https://github.com/seanchatmangpt/ggen.git", "git_rev": "11ea0739a579165c33fde5fb4d5a347bed6f5c58", "sha256": "00000000000058db00000000000067ac0000000000008440000000000000401e" } }, "license": "MIT", "homepage": "https://github.com/seanchatmangpt/ggen", "repository": "https://github.com/seanchatmangpt/ggen", "documentation": "https://github.com/seanchatmangpt/ggen/tree/main/templates/cli/subcommand" } } }

Table of Contents

Ggen Marketplace C4 Diagrams

This directory contains comprehensive C4 architecture diagrams for the Ggen Marketplace system, documenting the full end-to-end lifecycles and system interactions.

Diagram Overview

1. System Context (C4_marketplace_context.puml)

Purpose: High-level view of the marketplace system and its external interactions Key Elements:

  • Developer and Publisher personas
  • Ggen CLI system
  • Marketplace registry
  • GitHub hosting platform

2. Container Diagram (C4_marketplace_container.puml)

Purpose: Shows the major containers and their responsibilities Key Elements:

  • CLI and Core Engine containers
  • Local Cache and Lockfile
  • Registry Index and CI/CD Pipeline
  • Gpack Repositories

3. Consumer Lifecycle (C4_marketplace_consumer_lifecycle.puml)

Purpose: Detailed workflow for developers using gpacks Key Elements:

  • Search, Add, List, Generate, Update, Remove commands
  • Registry Client, Cache Manager, Lockfile Manager
  • Template Resolver and Generation Pipeline
  • External systems (Registry, Repos, Cache, Lockfile)

4. Publisher Lifecycle (C4_marketplace_publisher_lifecycle.puml)

Purpose: Detailed workflow for publishers creating gpacks Key Elements:

  • Pack Init, Lint, Test, Publish commands
  • Validation System (Schema, Semver, Compatibility, Path, License, Size, Security)
  • Registry System (Repository, Index Generator, Pages)
  • Gpack Repository structure

5. Data Flow (C4_marketplace_data_flow.puml)

Purpose: Shows how data flows through the system Key Elements:

  • Search, Add, Generate, Publish, Update data flows
  • Local System (CLI, Cache, Lockfile, Config)
  • Registry System (Index, Pages)
  • Gpack Repositories (Manifest, Templates, RDF, Queries)

6. Sequence Diagram (C4_marketplace_sequence.puml)

Purpose: Detailed sequence of interactions for key workflows Key Elements:

  • Search Workflow
  • Add Workflow
  • Generate Workflow
  • Update Workflow
  • Remove Workflow

7. Deployment Diagram (C4_marketplace_deployment.puml)

Purpose: Shows how the system is deployed across different environments Key Elements:

  • Developer Machine (Local installation)
  • GitHub Platform (Registry repo, Gpack repos, Pages)
  • Network (HTTPS, Git protocol)
  • Security considerations

8. Security Model (C4_marketplace_security.puml)

Purpose: Documents the security architecture and threat model Key Elements:

  • Trust boundaries and relationships
  • Security controls (SHA256, License, Path, Sandbox, Network, Static Analysis)
  • Security threats and mitigations
  • Trust levels (Trusted, Semi-trusted, Untrusted)

9. Error Handling (C4_marketplace_error_handling.puml)

Purpose: Documents error scenarios and recovery strategies Key Elements:

  • Network errors, Pack not found, Version resolution errors
  • Download errors, Integrity verification errors
  • Lockfile errors, Template resolution errors
  • Cache corruption, Compatibility errors
  • Recovery strategies and user guidance

10. Performance & Scalability (C4_marketplace_performance.puml)

Purpose: Documents performance characteristics and scalability considerations Key Elements:

  • Performance optimizations (Local caching, Index caching, Parallel downloads)
  • Incremental updates, Compression, CDN distribution
  • Performance metrics and monitoring
  • Scalability limits and considerations

Usage

These diagrams can be rendered using PlantUML:

# Install PlantUML
npm install -g plantuml

# Render all diagrams
plantuml docs/diagrams/C4_marketplace_*.puml

# Render specific diagram
plantuml docs/diagrams/C4_marketplace_context.puml

Key Lifecycle Flows

Consumer Lifecycle

  1. Search β†’ Find gpacks in registry
  2. Add β†’ Download and cache gpacks
  3. List β†’ Show installed gpacks
  4. Generate β†’ Use gpack templates
  5. Update β†’ Update to latest versions
  6. Remove β†’ Clean up gpacks

Publisher Lifecycle

  1. Init β†’ Create new gpack structure
  2. Lint β†’ Validate gpack manifest
  3. Test β†’ Test template rendering
  4. Publish β†’ Submit to registry via PR
  5. Validation β†’ Automated CI/CD checks
  6. Deployment β†’ Registry index update

Error Recovery

  • Network errors β†’ Retry with exponential backoff
  • Integrity errors β†’ Re-download and verify
  • Cache corruption β†’ Clear and re-download
  • Compatibility errors β†’ Suggest version updates
  • Template errors β†’ Provide helpful diagnostics

Security Considerations

  • Trust boundaries clearly defined
  • Sandboxed execution for templates
  • SHA256 verification for integrity
  • License validation for compliance
  • Path sanitization for security
  • Network controls for access restriction

Performance Characteristics

  • Local caching for fast access
  • CDN distribution for global performance
  • Parallel downloads for efficiency
  • Incremental updates for minimal transfers
  • Compression for bandwidth optimization

These diagrams provide comprehensive documentation of the marketplace system architecture, covering all aspects from high-level context to detailed implementation, security, and performance considerations.