Summary
Getting Started
Core Concepts
Reference
π€ AI Integration (NEW v1.0.0)
Advanced Topics
Examples
Marketplace
Architecture
Table of Contents
- Install
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:
- Try the quickstart: Follow the quickstart guide
- Explore gpacks: Browse the marketplace
- Learn templates: Read the templates guide
- 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
Quickstart
Marketplace Workflow (Recommended)
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
Feature | Marketplace Gpacks | Local Templates |
---|---|---|
Setup Time | Instant | Requires creation |
Quality | Community tested | Custom quality |
Updates | Automatic | Manual |
Dependencies | Managed | Manual |
Versioning | Semantic | Ad-hoc |
Best For | Common patterns | Custom 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
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 pathvars:
defaultsrdf:
includes/inline graphsshape:
SHACL shape filessparql.vars:
single-value bindingssparql.matrix:
fan-out rowsdeterminism:
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:
- Installed gpacks (from
.ggen/gpacks/
) - 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
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
Provider | Models | Access |
---|---|---|
OpenAI | GPT-4o, GPT-3.5-turbo | API key required |
Anthropic | Claude 3.5 Sonnet, Claude 3 Haiku | API key required |
Ollama | Qwen3-coder:30b, Llama 2, Code Llama | Local installation |
Gemini | Gemini Pro, Gemini Ultra | API key required |
Groq | Mixtral 8x7B, Llama 2 70B | API key required |
Cohere | Command R+, Aya | API 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
- Be specific: Include language, framework, and requirements
- Provide context: Reference existing code or patterns
- Use examples: Show expected output format
- Iterate: Refine prompts based on results
Quality Assurance
- Validate outputs: Use
ggen ai validate
to check templates - Test generation: Verify generated code compiles/runs
- Review metadata: Check RDF graphs for semantic correctness
- Version control: Track template evolution
Performance
- Use appropriate models: Smaller models for simple tasks
- Batch operations: Generate multiple items together
- Cache results: Reuse successful generations
- 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
inmatrix
queries.
Merged data graph and shapes graph are hashed for determinism.
Table of Contents
- Projections
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
- Describe object in RDF - Define semantic model
- Bind vars via SPARQL - Extract variables from graph
- Render per target - Generate language-specific code
Marketplace Pattern
- Search for gpacks - Find language-specific templates
- Install dependencies - Get gpacks and dependencies
- Generate consistently - Use same RDF across languages
Local Pattern
- Create templates - Build custom projection logic
- Define RDF model - Specify semantic structure
- 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
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
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):
- CLI arguments (
--var key=value
) - Environment variables (from
.env
files) - System environment (
$HOME
,$USER
, etc.) - Gpack variables (from gpack
ggen.toml
) - Template frontmatter (
vars:
section) - 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
Troubleshooting
General Issues
- Missing output: check
to:
and matrix query. - Unbound var: pass
--vars
or addsparql.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
- CLI Ergonomics
- Marketplace DX Features
- Authoring Loop
- Error Handling
- Hygen Parity
- Determinism & Previews
- Graph (RDF) Integration
- Template Helpers
- Safety & Guardrails
- Configuration & Discovery
- Testing Infrastructure
- Pipeline Integration
- Sensible Defaults
- Error Recovery
- Performance Optimizations
- Development Workflow
- Integration Benefits
- Best Practices
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):
- Environment variables (from
.env
files) - System environment (
$HOME
,$USER
, etc.) - Project presets (from
ggen.toml
[preset] section) - Template frontmatter (
vars:
section in template) - 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
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 nameversion
: Semantic versiondescription
: Brief descriptionlicense
: License identifierggen_compat
: Required ggen version range
Optional Fields
authors
: List of authorsrepository
: Source repository URLhomepage
: Project homepagekeywords
: Search keywordsreadme
: Path to README filechangelog
: 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
- Use semantic variable names:
name
,description
,version
- Include RDF models: Define semantic structure
- Add SPARQL queries: Extract variables from graphs
- Include determinism: Use seeds for reproducibility
- Add comments: Document generated code
- 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
- Validation: Gpack is validated against schema
- Testing: Golden tests are run
- Linting: Code quality checks
- Registry Upload: Gpack is uploaded to registry
- Index Update: Registry index is updated
- 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
- Single Responsibility: One gpack, one purpose
- Consistent API: Use standard variable names
- Documentation: Include README and examples
- Testing: Comprehensive golden tests
- Versioning: Follow semver strictly
Template Quality
- Readability: Clear, well-commented code
- Maintainability: Modular, reusable templates
- Performance: Efficient SPARQL queries
- Security: Validate all inputs
- Accessibility: Follow language best practices
Community Guidelines
- Naming: Use descriptive, consistent names
- Licensing: Choose appropriate licenses
- Contributing: Welcome community contributions
- Support: Provide issue tracking
- 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
Multi-language CLI subcommand
Using Marketplace Gpacks (Recommended)
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
Using Marketplace Gpack (Recommended)
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
Approach | Setup Time | Quality | Updates | Best For |
---|---|---|---|---|
Marketplace | Instant | Community tested | Automatic | Most users |
Local | Manual | Custom | Manual | Special needs |
Next Steps
- Try the multi-language example
- Explore marketplace gpacks
- Learn about template development
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
Metric | Value |
---|---|
Available Gpacks | 1 |
Open Source | 100% |
License | MIT |
π Registry API
Access the marketplace registry programmatically:
- Registry Index (JSON): registry/index.json
- Source Repository: seanchatmangpt/ggen
# 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
- Diagram Overview
- 1. System Context (
C4_marketplace_context.puml
) - 2. Container Diagram (
C4_marketplace_container.puml
) - 3. Consumer Lifecycle (
C4_marketplace_consumer_lifecycle.puml
) - 4. Publisher Lifecycle (
C4_marketplace_publisher_lifecycle.puml
) - 5. Data Flow (
C4_marketplace_data_flow.puml
) - 6. Sequence Diagram (
C4_marketplace_sequence.puml
) - 7. Deployment Diagram (
C4_marketplace_deployment.puml
) - 8. Security Model (
C4_marketplace_security.puml
) - 9. Error Handling (
C4_marketplace_error_handling.puml
) - 10. Performance & Scalability (
C4_marketplace_performance.puml
)
- 1. System Context (
- Usage
- Key Lifecycle Flows
- Security Considerations
- Performance Characteristics
- Diagram Overview
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
- Search β Find gpacks in registry
- Add β Download and cache gpacks
- List β Show installed gpacks
- Generate β Use gpack templates
- Update β Update to latest versions
- Remove β Clean up gpacks
Publisher Lifecycle
- Init β Create new gpack structure
- Lint β Validate gpack manifest
- Test β Test template rendering
- Publish β Submit to registry via PR
- Validation β Automated CI/CD checks
- 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.