Function sync

Source

pub fn sync(
    manifest: Option<String>,
    output_dir: Option<String>,
    dry_run: Option<bool>,
    force: Option<bool>,
    audit: Option<bool>,
    rule: Option<String>,
    verbose: Option<bool>,
    watch: Option<bool>,
    validate_only: Option<bool>,
    format: Option<String>,
    timeout: Option<u64>,
    stage: Option<String>,
    ontology: Option<String>,
    queries: Option<String>,
    language: Option<String>,
    profile: Option<String>,
    locked: bool,
) -> Result<SyncOutput>

Expand description

Execute the complete code synchronization pipeline from a ggen.toml manifest.

This is THE ONLY command in ggen v26_5_19. It replaces all previous commands (ggen generate, ggen validate, ggen template, etc.) with a single unified pipeline.

§A2A-RS μ Pipeline (μ₁ through μ₅)

When generating A2A-RS code from .specify/specs/014-a2a-integration/:

μ₁ CONSTRUCT: Normalize RDF ontology
   Input: .specify/specs/014-a2a-integration/a2a-ontology.ttl
   Query: crates/ggen-core/queries/a2a/construct-agents.rq
   Output: Normalized A2A RDF with a2a: prefix

μ₂ SELECT: Extract bindings for each module
   Queries: crates/ggen-core/queries/a2a/extract-*.rq
     - extract-agents.rq → agent bindings
     - extract-messages.rq → message bindings
     - extract-tasks.rq → task bindings
     - extract-transports.rq → transport bindings
     - extract-skills.rq → skill bindings
   Output: SPARQL result bindings

μ₃ Tera: Generate Rust code
   Templates: crates/ggen-core/templates/a2a/*.tera
     - agent.rs.tera → crates/a2a-generated/src/agent.rs
     - message.rs.tera → crates/a2a-generated/src/message.rs
     - task.rs.tera → crates/a2a-generated/src/task.rs
     - transport.rs.tera → crates/a2a-generated/src/transport.rs
     - skill.rs.tera → crates/a2a-generated/src/skill.rs
     - lib.rs.tera → crates/a2a-generated/src/lib.rs
   Output: Generated Rust source files

μ₄ Canonicalize: Format and organize
   Action: rustfmt, organize imports, verify compilation
   Output: Formatted, ready-to-compile code

μ₅ Receipt: Generate cryptographic verification
   Output: .ggen/receipts/a2a-{timestamp}.json
   Contains: SHA256 hashes, input ontology hash, timestamp

§Pipeline Flow

ggen.toml → ontology → CONSTRUCT inference → SELECT → Template → Code

§Flags

–manifest PATH Path to ggen.toml (default: ./ggen.toml) –output-dir PATH Override output directory from manifest –dry-run Preview changes without writing files –force Overwrite existing files (DESTRUCTIVE - use with –audit) –audit Create detailed audit trail in .ggen/audit/ –rule NAME Execute only specific generation rule –verbose Show detailed execution logs –watch Continuous file monitoring and auto-regeneration –validate-only Run SHACL/SPARQL validation without generation –format FORMAT Output format: text, json, yaml (default: text) –timeout MS Maximum execution time in milliseconds (default: 30000) –stage STAGE Run specific μ stage only (μ₁, μ₂, μ₃, μ₄, μ₅) –ontology PATH Override ontology path (default: from manifest)

§Flag Combinations

Safe workflows: ggen sync –dry-run –audit Preview with audit ggen sync –force –audit Destructive overwrite with tracking ggen sync –watch –validate-only Continuous validation

A2A-specific workflows: ggen sync –audit Full A2A μ₁-μ₅ pipeline with receipt ggen sync –stage μ₃ Only run template generation ggen sync –ontology .specify/specs/014-a2a-integration/a2a-ontology.ttl

CI/CD workflows: ggen sync –format json Machine-readable output ggen sync –validate-only Pre-flight checks

Development workflows: ggen sync –watch –verbose Live feedback ggen sync –rule structs Focused iteration

§Progress Reporting (A2A Pipeline)

When running A2A sync, progress is reported for each μ stage:

[μ₁/5] CONSTRUCT: Normalizing ontology...
       Loaded 847 triples from a2a-ontology.ttl
       +124 triples from construct-agents.rq
[μ₂/5] SELECT: Extracting bindings...
       Agents: 8 bindings
       Messages: 12 bindings
       Tasks: 15 bindings
       Transports: 3 bindings
       Skills: 24 bindings
[μ₃/5] Tera: Generating code...
       agent.rs (2.4 KB)
       message.rs (3.1 KB)
       task.rs (2.8 KB)
       transport.rs (1.2 KB)
       skill.rs (4.5 KB)
       lib.rs (1.8 KB)
[μ₄/5] Canonicalizing: Formatting code...
       Running rustfmt...
       Verifying compilation...
[μ₅/5] Receipt: Generating verification...
       Receipt: .ggen/receipts/a2a-20250208-143022.json
       Ontology hash: a3f2e1b4...
       Total: 6 files, 15.8 KB, 2.34s

§Flag Precedence

–validate-only overrides –force –dry-run prevents file writes (–force has no effect) –watch triggers continuous execution –stage limits execution to specific μ stage

§Safety Notes

⚠️ ALWAYS use –audit with –force to enable rollback ⚠️ ALWAYS use –dry-run before –force to preview changes ⚠️ Review docs/features/force-flag.md before using –force

§Examples

# Basic sync (the primary workflow)
ggen sync

# Sync from specific manifest
ggen sync --manifest project/ggen.toml

# Dry-run to preview changes
ggen sync --dry-run

# Sync specific rule only
ggen sync --rule structs

# Force overwrite with audit trail (RECOMMENDED)
ggen sync --force --audit

# Watch mode for development
ggen sync --watch --verbose

# Validate without generating
ggen sync --validate-only

# JSON output for CI/CD
ggen sync --format json

# A2A generation with custom ontology
ggen sync --ontology .specify/specs/014-a2a-integration/a2a-ontology.ttl --audit

# Run specific μ stage only
ggen sync --stage μ₃

# Complex: Watch, audit, verbose
ggen sync --watch --audit --verbose --rule api_endpoints

§Documentation

Full feature documentation:

docs/features/audit-trail.md Audit trail format and usage
docs/features/force-flag.md Safe destructive workflows
docs/features/merge-mode.md Hybrid manual/generated code
docs/features/watch-mode.md Continuous regeneration
docs/features/conditional-execution.md SPARQL ASK conditions
docs/features/validation.md SHACL/SPARQL constraints
docs/features/a2a-pipeline.md A2A μ₁-μ₅ pipeline details

sync

Function sync Copy item path