Doc system test

Dependency tree

A template version plus every template version it pins, transitively, each a node by version id; groups are nodes that make no files.

Meta block front matter of this doc
namespaces
  • durian.cloud/cyanprint/composition
  • durian.cloud/cyanprint/registry
  • durian.cloud/cyanprint/authoring
  • durian.cloud/cyanprint/project-lifecycle
type
feature

What it is. A dependency tree is one template version plus every template version it lists under templates: in its cyan.yaml, and theirs, all the way down. Each node is one template version, named by its version id. The edges carry preset answers.

What problem it solves. An author can build a template from smaller ones (a web app from a Node base and a Docker setup) without copying their files. One cyanprint create of the top template runs the whole tree and writes one merged result.

What newcomers get wrong.

  • A dependency is not a stacked template. Dependencies live in the registry, inside one template version. Stacked templates live only in a folder's state file.
  • The tree is fixed when the template version is pushed. A newer dependency version never reaches an old template version.
  • A node is a template version, not a template. The same template at two versions is two nodes, and both run.

The picture shows web:5's tree and web:6's tree from the shop example.

flowchart TD
  W5["atomi/web:5<br/>e5d0…"] -->|"preset module_type: esm"| NB["atomi/node-base:3<br/>b2e4…"]
  W5 -->|"no presets"| D7["atomi/docker:7<br/>7a90…"]
  NB -->|"no presets"| L2["atomi/lint:2<br/>3c1f…"]
  W6["atomi/web:6<br/>1f6a…"] -->|"preset module_type: esm"| NB
  W6 -->|"no presets"| D8["atomi/docker:8<br/>8b11…"]
The dependency trees of web:5 and web:6

The rules

  1. Nodes are version ids. The registry stores each dependency as { id, version, presetAnswers }. The CLI follows id only; version is shown, never used to fetch.
  2. Pinned at push. cyan.yaml may name a dependency without a version (atomi/docker). cyanprint push sends version 0, and the registry stores the newest version at that moment (reference pinning). web:5 pinned docker:7 forever; web:6, pushed later, pinned docker:8.
  3. Edges carry presets. A parent can answer some of a child's questions (preset answer). The root has no incoming edge, so it never has presets.
  4. A shared node runs once. If two parents pin the same version id, the node appears once in the run order, and both parents' presets are merged into it (first value wins per question).
  5. Two versions of one template are two nodes. If node-base:3 pinned docker:7 while web:6 pins docker:8, web:6's tree would run both, and both would write Dockerfile.
  6. Template groups are nodes too. A group has no images (properties is null). It stays in the run order, its conflict resolver declarations and commands still count, but it is never run and makes no files.
  7. The tree is a tree in name only. Nothing checks for cycles. A back edge to a node that is still being visited is skipped without a word (dependency flattening).

Here is the wire shape the CLI reads for each node and edge (the registry's template version response).

sulfone.iridiumcyanregistry/src/http/models/template_res.rs
  1. lines 5-13A node's identity: the version id, its version number, and properties (the images). properties is None for a group.
    cyanregistry/src/http/models/template_res.rs:5-13rust
    #[derive(Debug, Clone, Serialize, Deserialize)]
    #[serde(rename_all = "camelCase")]
    pub struct TemplateVersionPrincipalRes {
    pub id: String,
    pub version: i64,
    pub created_at: String,
    pub description: String,
    pub properties: Option<TemplatePropertyRes>,
    }
  2. lines 24-36A template version: its own processors, plugins, dependency edges (templates), conflict resolvers and commands.
    cyanregistry/src/http/models/template_res.rs:24-36rust
    #[derive(Debug, Clone, Serialize, Deserialize)]
    pub struct TemplateVersionRes {
    pub principal: TemplateVersionPrincipalRes,
    pub template: TemplatePrincipalRes,
    pub plugins: Vec<PluginVersionPrincipalRes>,
    pub processors: Vec<ProcessorVersionPrincipalRes>,
    pub templates: Vec<TemplateVersionTemplateRefRes>,
    #[serde(default)]
    pub resolvers: Vec<TemplateVersionResolverRes>,
    #[serde(default)]
    pub commands: Vec<String>,
    }
  3. lines 52-60One edge: the child's version id, its version number (unused by the walk) and the preset answers as raw JSON.
    cyanregistry/src/http/models/template_res.rs:52-60rust
    /// Template dependency reference with preset answers
    #[derive(Debug, Clone, Serialize, Deserialize)]
    #[serde(rename_all = "camelCase")]
    pub struct TemplateVersionTemplateRefRes {
    pub id: String,
    pub version: i64,
    #[serde(default)]
    pub preset_answers: std::collections::HashMap<String, serde_json::Value>,
    }
  4. sulfone.iridium/cyancoordinator/src/operations/composition/operator.rs:243-257At run time, a node with no properties is a group: logged, added to the order, and skipped.
    cyancoordinator/src/operations/composition/operator.rs:243-257rust
    // Check if template has execution artifacts (properties field)
    if template.principal.properties.is_none() {
    cprogress!(
    headless,
    "⏭️ Skipping template: {}/{} (v{}) - no execution artifacts (group template)",
    template.template.name,
    template.template.name, // TODO: Need username
    template.principal.version
    );
    // Update execution order tracking even for skipped templates
    shared_state
    .execution_order
    .push(template.principal.id.clone());
    continue;
    }

Worked example: the shop's two trees

Step through how web:5's and web:6's trees come to be, from push to run order (steps 0, 1 and 4 of the shop example).

web:5 and web:6 trees
  1. Push web:5

    cyan.yaml lists node-base:3 (preset module_type: esm) and atomi/docker with no version. The registry pins docker to its newest version, 7.

    web:5 edgesb2e4 (module_type: esm), 7a90 (none)
  2. Push docker:8

    A new docker version. web:5's stored edge still points at 7a90.

    web:5 edgesb2e4, 7a90 (unchanged)
  3. Push web:6

    Same cyan.yaml, but docker now resolves to 8.

    web:6 edgesb2e4 (module_type: esm), 8b11 (none)
  4. Run web:5

    Four nodes. Siblings go in version id order, so docker:7 runs before node-base:3.

    run orderdocker:7, lint:2, node-base:3, web:5
  5. Run web:6

    docker:8 (8b11) still sorts before node-base:3 (b2e4).

    run orderdocker:8, lint:2, node-base:3, web:6

Why it is built this way

Hard cases

  • The edge's version number is never checked against the fetched node. A registry that returned another version for that id would run it unnoticed.
  • Same template, two versions, one folder. Both run and both write the same paths; dependency layering settles it, usually by last layer wins.
  • A group's own incoming presets go nowhere. A group never runs, so presets on the edge into it are not passed on to its children.
  • Cycles are silent. A tree where lint:2 pinned web:5 would still run, with the back edge dropped.
  • Upgrading a dependency means a new parent version. To move web from docker:7 to docker:8, the author pushes a new web version; users then update.

Questions for the designer

  1. Should the run check the edge's version number against the fetched node?
  2. Should a cycle in a dependency tree be an error at push time, at run time, or both?
  3. Should presets on the edge into a template group be passed down to the group's children?
  4. Is running two versions of one template in one tree wanted, or should the newer one replace the older? (The successor sulfone.lite requires global template uniqueness and one configuring parent per dependency: simplification-spec.md, lines 50 and 196.)