Greentic Flow

Generic schema, loader, and intermediate representation for YGTC flows composed of self-describing component nodes.

Quickstart

use greentic_flow::{loader::load_ygtc_from_str, resolve::resolve_parameters, to_ir};
use std::path::Path;

let yaml = std::fs::read_to_string("fixtures/weather_bot.ygtc")?;
let flow = load_ygtc_from_str(&yaml, Path::new("schemas/ygtc.flow.schema.json"))?;
let ir = to_ir(flow)?;
let node = ir.nodes.get("forecast_weather").unwrap();
let resolved = resolve_parameters(&node.payload_expr, &ir.parameters, "nodes.forecast_weather")?;
# Ok::<_, greentic_flow::error::FlowError>(())

Design Highlights

• JSON Schema (schemas/ygtc.flow.schema.json) enforces exactly one component key per node plus optional routing metadata.
• Loader converts YAML documents to FlowDoc, validates against the schema, extracts component metadata, and performs basic graph checks.
• IR (FlowIR) keeps nodes generic and serde-friendly so runtimes can post-process component payloads while exposing NodeKind classification for adapters.
• NodeKind::Adapter recognises node component strings shaped as <namespace>.<adapter>.<operation> and keeps the trailing segments joined so nested operations are preserved.
• resolve::resolve_parameters pre-resolves only parameters.* references, leaving other runtime bindings intact.
• start is optional; if omitted and an in node exists, the loader defaults start to in.

Adapter Registry Format

Adapter-backed nodes can be linted against an on-disk catalog that maps <namespace>.<adapter> pairs to the operations they expose. The registry is JSON by default, with optional TOML support via the toml feature.

{
  "adapters": {
    "messaging.telegram": ["sendMessage", "editMessage"],
    "email.google": ["send", "draft.create"]
  }
}

With the registry loaded, the adapter_resolvable rule reports any node whose component string cannot be found in the catalog.

Development

• cargo fmt --check
• cargo clippy -D warnings
• cargo test

Fixtures under fixtures/ mirror common success and failure scenarios.

CLI

Run cargo run --bin ygtc-lint -- <paths> to validate flows. Example:

cargo run --bin ygtc-lint -- fixtures --schema schemas/ygtc.flow.schema.json

To enable adapter linting, provide --registry:

cargo run --bin ygtc-lint -- \
  --schema schemas/ygtc.flow.schema.json \
  --registry tests/data/registry_ok.json \
  tests/data/flow_ok.ygtc

The CLI recursively walks any directories provided, only inspecting files with a .ygtc extension. Schema validation always runs; adapter checks are additive when a registry is supplied.

Maintenance Notes

• Keep shared primitives flowing through greentic-types and greentic-interfaces.
• Prefer zero-copy patterns and stay within safe Rust (#![forbid(unsafe_code)] is enabled).
• Update the adapter registry fixtures under tests/data/ when new adapters or operations are introduced.

Releases & Publishing

• Crate versions are sourced directly from each crate's Cargo.toml.
• Every push to master compares the previous commit; if a crate version changed, a tag <crate-name>-v<semver> is created and pushed automatically.
• The publish workflow runs on the tagged commit and attempts to publish all changed crates to crates.io using katyo/publish-crates@v2.
• Publishing is idempotent: if the version already exists on crates.io, the workflow succeeds without error.