flowey_core/

node.rs

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

//! Core types and traits used to create and work with flowey nodes.

mod github_context;
mod spec;

pub use github_context::GhOutput;
pub use github_context::GhToRust;
pub use github_context::RustToGh;

use self::steps::ado::AdoRuntimeVar;
use self::steps::ado::AdoStepServices;
use self::steps::github::GhStepBuilder;
use self::steps::rust::RustRuntimeServices;
use self::user_facing::ClaimedGhParam;
use self::user_facing::GhPermission;
use self::user_facing::GhPermissionValue;
use crate::node::github_context::GhContextVarReader;
use github_context::state::Root;
use serde::Deserialize;
use serde::Serialize;
use serde::de::DeserializeOwned;
use std::cell::RefCell;
use std::collections::BTreeMap;
use std::path::PathBuf;
use std::rc::Rc;
use user_facing::GhParam;

/// Node types which are considered "user facing", and re-exported in the
/// `flowey` crate.
pub mod user_facing {
    pub use super::ClaimVar;
    pub use super::ClaimedReadVar;
    pub use super::ClaimedWriteVar;
    pub use super::ConfigField;
    pub use super::ConfigMerge;
    pub use super::ConfigVar;
    pub use super::FlowArch;
    pub use super::FlowBackend;
    pub use super::FlowNode;
    pub use super::FlowNodeWithConfig;
    pub use super::FlowPlatform;
    pub use super::FlowPlatformKind;
    pub use super::GhUserSecretVar;
    pub use super::ImportCtx;
    pub use super::IntoConfig;
    pub use super::IntoRequest;
    pub use super::NodeCtx;
    pub use super::ReadVar;
    pub use super::SideEffect;
    pub use super::SimpleFlowNode;
    pub use super::StepCtx;
    pub use super::VarClaimed;
    pub use super::VarEqBacking;
    pub use super::VarNotClaimed;
    pub use super::WriteVar;
    pub use super::steps::ado::AdoResourcesRepositoryId;
    pub use super::steps::ado::AdoRuntimeVar;
    pub use super::steps::ado::AdoStepServices;
    pub use super::steps::github::ClaimedGhParam;
    pub use super::steps::github::GhParam;
    pub use super::steps::github::GhPermission;
    pub use super::steps::github::GhPermissionValue;
    pub use super::steps::rust::RustRuntimeServices;
    pub use crate::flowey_config;
    pub use crate::flowey_request;
    pub use crate::new_flow_node;
    pub use crate::new_flow_node_with_config;
    pub use crate::new_simple_flow_node;
    pub use crate::node::FlowPlatformLinuxDistro;
    pub use crate::pipeline::Artifact;
    pub use crate::pipeline::ArtifactType;
    pub use crate::pipeline::resolve as resolve_artifact;

    /// Helper method to streamline request validation in cases where a value is
    /// expected to be identical across all incoming requests.
    ///
    /// # Example: Request Aggregation Pattern
    ///
    /// When a node receives multiple requests, it often needs to ensure certain
    /// values are consistent across all requests. This helper simplifies that pattern:
    ///
    /// ```rust,ignore
    /// fn emit(requests: Vec<Self::Request>, ctx: &mut NodeCtx<'_>) -> anyhow::Result<()> {
    ///     let mut version = None;
    ///     let mut ensure_installed = Vec::new();
    ///
    ///     for req in requests {
    ///         match req {
    ///             Request::Version(v) => {
    ///                 // Ensure all requests agree on the version
    ///                 same_across_all_reqs("Version", &mut version, v)?;
    ///             }
    ///             Request::EnsureInstalled(v) => {
    ///                 ensure_installed.push(v);
    ///             }
    ///         }
    ///     }
    ///
    ///     let version = version.ok_or(anyhow::anyhow!("Missing required request: Version"))?;
    ///
    ///     // ... emit steps using aggregated requests
    ///     Ok(())
    /// }
    /// ```
    pub fn same_across_all_reqs<T: PartialEq>(
        req_name: &str,
        var: &mut Option<T>,
        new: T,
    ) -> anyhow::Result<()> {
        match (var.as_ref(), new) {
            (None, v) => *var = Some(v),
            (Some(old), new) => {
                if *old != new {
                    anyhow::bail!("`{}` must be consistent across requests", req_name);
                }
            }
        }

        Ok(())
    }

    /// Helper method to streamline request validation in cases where a value is
    /// expected to be identical across all incoming requests, using a custom
    /// comparison function.
    pub fn same_across_all_reqs_backing_var<V: VarEqBacking>(
        req_name: &str,
        var: &mut Option<V>,
        new: V,
    ) -> anyhow::Result<()> {
        match (var.as_ref(), new) {
            (None, v) => *var = Some(v),
            (Some(old), new) => {
                if !old.eq(&new) {
                    anyhow::bail!("`{}` must be consistent across requests", req_name);
                }
            }
        }

        Ok(())
    }

    /// Helper method to handle Linux distros that are supported only on one
    /// host architecture.
    /// match_arch!(var, arch, result)
    #[macro_export]
    macro_rules! match_arch {
        ($host_arch:expr, $match_arch:pat, $expr:expr) => {
            if matches!($host_arch, $match_arch) {
                $expr
            } else {
                anyhow::bail!("Linux distro not supported on host arch {}", $host_arch);
            }
        };
    }

    /// Claim a set of vars
    #[macro_export]
    macro_rules! claim_vars {
        ($ctx:ident, ($($var:ident),* $(,)?)) => {
            $(let $var = $var.claim($ctx);)*
        };
    }

    /// Read a set of vars
    #[macro_export]
    macro_rules! read_vars {
        ($rt:ident, ($($var:ident),* $(,)?)) => {
            $(let $var = $rt.read($var);)*
        };
    }
}

/// Check if `ReadVar` / `WriteVar` instances are backed by the same underlying
/// flowey Var.
///
/// # Why not use `Eq`? Why have a whole separate trait?
///
/// `ReadVar` and `WriteVar` are, in some sense, flowey's analog to
/// "pointers", insofar as these types primary purpose is to mediate access to
/// some contained value, as opposed to being "values" themselves.
///
/// Assuming you agree with this analogy, then we can apply the same logic to
/// `ReadVar` and `WriteVar` as Rust does to `Box<T>` wrt. what the `Eq`
/// implementation should mean.
///
/// Namely: `Eq` should check the equality of the _contained objects_, as
/// opposed to the pointers themselves.
///
/// Unfortunately, unlike `Box<T>`, it is _impossible_ to have an `Eq` impl for
/// `ReadVar` / `WriteVar` that checks contents for equality, due to the fact
/// that these types exist at flow resolution time, whereas the values they
/// contain only exist at flow runtime.
///
/// As such, we have a separate trait to perform different kinds of equality
/// checks on Vars.
pub trait VarEqBacking {
    /// Check if `self` is backed by the same variable as `other`.
    fn eq(&self, other: &Self) -> bool;
}

impl<T> VarEqBacking for WriteVar<T>
where
    T: Serialize + DeserializeOwned,
{
    fn eq(&self, other: &Self) -> bool {
        self.backing_var == other.backing_var
    }
}

impl<T> VarEqBacking for ReadVar<T>
where
    T: Serialize + DeserializeOwned + PartialEq + Eq + Clone,
{
    fn eq(&self, other: &Self) -> bool {
        self.backing_var == other.backing_var
    }
}

// TODO: this should be generic across all tuple sizes
impl<T, U> VarEqBacking for (T, U)
where
    T: VarEqBacking,
    U: VarEqBacking,
{
    fn eq(&self, other: &Self) -> bool {
        (self.0.eq(&other.0)) && (self.1.eq(&other.1))
    }
}

/// A wrapper around [`ReadVar<T>`] that implements [`PartialEq`] via
/// backing-variable identity ([`VarEqBacking`]).
///
/// Use this in config structs where a `ReadVar` field needs equality
/// comparison for config merging. Since `ReadVar` deliberately does not
/// implement `PartialEq` (its values aren't known at flow-resolution time),
/// `ConfigVar` provides identity-based comparison instead.
///
/// # Example
///
/// ```rust,ignore
/// flowey_config! {
///     pub struct Config {
///         pub verbose: Option<ConfigVar<bool>>,
///     }
/// }
/// ```
#[derive(Serialize, Deserialize)]
#[serde(bound(serialize = "T: Serialize", deserialize = "T: DeserializeOwned"))]
pub struct ConfigVar<T>(pub ReadVar<T>);

impl<T: Serialize + DeserializeOwned> Clone for ConfigVar<T> {
    fn clone(&self) -> Self {
        ConfigVar(self.0.clone())
    }
}

impl<T> std::fmt::Debug for ConfigVar<T> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_tuple("ConfigVar").finish()
    }
}

impl<T: Serialize + DeserializeOwned + PartialEq + Eq + Clone> PartialEq for ConfigVar<T> {
    fn eq(&self, other: &Self) -> bool {
        VarEqBacking::eq(&self.0, &other.0)
    }
}

impl<T: Serialize + DeserializeOwned + PartialEq + Eq + Clone> ClaimVar for ConfigVar<T> {
    type Claimed = ClaimedReadVar<T>;

    fn claim(self, ctx: &mut StepCtx<'_>) -> ClaimedReadVar<T> {
        self.0.claim(ctx)
    }
}

impl<T: Serialize + DeserializeOwned + PartialEq + Eq + Clone> From<ReadVar<T>> for ConfigVar<T> {
    fn from(v: ReadVar<T>) -> Self {
        ConfigVar(v)
    }
}

/// Type corresponding to a step which performs a side-effect,
/// without returning a specific value.
///
/// e.g: A step responsible for installing a package from `apt` might claim a
/// `WriteVar<SideEffect>`, with any step requiring the package to have been
/// installed prior being able to claim the corresponding `ReadVar<SideEffect>.`
pub type SideEffect = ();

/// Uninhabited type used to denote that a particular [`WriteVar`] / [`ReadVar`]
/// is not currently claimed by any step, and cannot be directly accessed.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub enum VarNotClaimed {}

/// Uninhabited type used to denote that a particular [`WriteVar`] / [`ReadVar`]
/// is currently claimed by a step, and can be read/written to.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub enum VarClaimed {}

/// Write a value into a flowey Var at runtime, which can then be read via a
/// corresponding [`ReadVar`].
///
/// Vars in flowey must be serde de/serializable, in order to be de/serialized
/// between multiple steps/nodes.
///
/// In order to write a value into a `WriteVar`, it must first be _claimed_ by a
/// particular step (using the [`ClaimVar::claim`] API). Once claimed, the Var
/// can be written to using APIs such as [`RustRuntimeServices::write`], or
/// [`AdoStepServices::set_var`]
///
/// Note that it is only possible to write a value into a `WriteVar` _once_.
/// Once the value has been written, the `WriteVar` type is immediately
/// consumed, making it impossible to overwrite the stored value at some later
/// point in execution.
///
/// This "write-once" property is foundational to flowey's execution model, as
/// by recoding what step wrote to a Var, and what step(s) read from the Var, it
/// is possible to infer what order steps must be run in.
#[derive(Debug, Serialize, Deserialize)]
pub struct WriteVar<T: Serialize + DeserializeOwned, C = VarNotClaimed> {
    backing_var: String,
    /// If true, then readers on this var expect to read a side effect (`()`)
    /// and not `T`.
    is_side_effect: bool,

    #[serde(skip)]
    _kind: core::marker::PhantomData<(T, C)>,
}

/// A [`WriteVar`] which has been claimed by a particular step, allowing it
/// to be written to at runtime.
pub type ClaimedWriteVar<T> = WriteVar<T, VarClaimed>;

impl<T: Serialize + DeserializeOwned> WriteVar<T, VarNotClaimed> {
    /// (Internal API) Switch the claim marker to "claimed".
    fn into_claimed(self) -> WriteVar<T, VarClaimed> {
        let Self {
            backing_var,
            is_side_effect,
            _kind,
        } = self;

        WriteVar {
            backing_var,
            is_side_effect,
            _kind: std::marker::PhantomData,
        }
    }

    /// Write a static value into the Var.
    #[track_caller]
    pub fn write_static(self, ctx: &mut NodeCtx<'_>, val: T)
    where
        T: 'static,
    {
        let val = ReadVar::from_static(val);
        val.write_into(ctx, self);
    }

    pub(crate) fn into_json(self) -> WriteVar<serde_json::Value> {
        WriteVar {
            backing_var: self.backing_var,
            is_side_effect: self.is_side_effect,
            _kind: std::marker::PhantomData,
        }
    }
}

impl WriteVar<SideEffect, VarNotClaimed> {
    /// Transforms this writer into one that can be used to write a `T`.
    ///
    /// This is useful when a reader only cares about the side effect of an
    /// operation, but the writer wants to provide output as well.
    pub fn discard_result<T: Serialize + DeserializeOwned>(self) -> WriteVar<T> {
        WriteVar {
            backing_var: self.backing_var,
            is_side_effect: true,
            _kind: std::marker::PhantomData,
        }
    }
}

/// Claim one or more flowey Vars for a particular step.
///
/// By having this be a trait, it is possible to `claim` both single instances
/// of `ReadVar` / `WriteVar`, as well as whole _collections_ of Vars.
//
// FUTURE: flowey should include a derive macro for easily claiming read/write
// vars in user-defined structs / enums.
pub trait ClaimVar {
    /// The claimed version of Self.
    type Claimed;
    /// Claim the Var for this step, allowing it to be accessed at runtime.
    fn claim(self, ctx: &mut StepCtx<'_>) -> Self::Claimed;
}

/// Read the value of one or more flowey Vars.
///
/// By having this be a trait, it is possible to `read` both single
/// instances of `ReadVar` / `WriteVar`, as well as whole _collections_ of
/// Vars.
pub trait ReadVarValue {
    /// The read value of Self.
    type Value;
    /// Read the value of the Var at runtime.
    fn read_value(self, rt: &mut RustRuntimeServices<'_>) -> Self::Value;
}

impl<T: Serialize + DeserializeOwned> ClaimVar for ReadVar<T> {
    type Claimed = ClaimedReadVar<T>;

    fn claim(self, ctx: &mut StepCtx<'_>) -> ClaimedReadVar<T> {
        if let ReadVarBacking::RuntimeVar {
            var,
            is_side_effect: _,
        } = &self.backing_var
        {
            ctx.backend.borrow_mut().on_claimed_runtime_var(var, true);
        }
        self.into_claimed()
    }
}

impl<T: Serialize + DeserializeOwned> ClaimVar for WriteVar<T> {
    type Claimed = ClaimedWriteVar<T>;

    fn claim(self, ctx: &mut StepCtx<'_>) -> ClaimedWriteVar<T> {
        ctx.backend
            .borrow_mut()
            .on_claimed_runtime_var(&self.backing_var, false);
        self.into_claimed()
    }
}

impl<T: Serialize + DeserializeOwned> ReadVarValue for ClaimedReadVar<T> {
    type Value = T;

    fn read_value(self, rt: &mut RustRuntimeServices<'_>) -> Self::Value {
        match self.backing_var {
            ReadVarBacking::RuntimeVar {
                var,
                is_side_effect,
            } => {
                // Always get the data to validate that the variable is actually there.
                let data = rt.get_var(&var, is_side_effect);
                if is_side_effect {
                    // This was converted into a `ReadVar<SideEffect>` from
                    // another type, so parse the value that a
                    // `WriteVar<SideEffect>` would have written.
                    serde_json::from_slice(b"null").expect("should be deserializing into ()")
                } else {
                    // This is a normal variable.
                    serde_json::from_slice(&data).expect("improve this error path")
                }
            }
            ReadVarBacking::Inline(val) => val,
        }
    }
}

impl<T: ClaimVar> ClaimVar for Vec<T> {
    type Claimed = Vec<T::Claimed>;

    fn claim(self, ctx: &mut StepCtx<'_>) -> Vec<T::Claimed> {
        self.into_iter().map(|v| v.claim(ctx)).collect()
    }
}

impl<T: ReadVarValue> ReadVarValue for Vec<T> {
    type Value = Vec<T::Value>;

    fn read_value(self, rt: &mut RustRuntimeServices<'_>) -> Self::Value {
        self.into_iter().map(|v| v.read_value(rt)).collect()
    }
}

impl<T: ClaimVar> ClaimVar for Option<T> {
    type Claimed = Option<T::Claimed>;

    fn claim(self, ctx: &mut StepCtx<'_>) -> Option<T::Claimed> {
        self.map(|x| x.claim(ctx))
    }
}

impl<T: ReadVarValue> ReadVarValue for Option<T> {
    type Value = Option<T::Value>;

    fn read_value(self, rt: &mut RustRuntimeServices<'_>) -> Self::Value {
        self.map(|x| x.read_value(rt))
    }
}

impl<U: Ord, T: ClaimVar> ClaimVar for BTreeMap<U, T> {
    type Claimed = BTreeMap<U, T::Claimed>;

    fn claim(self, ctx: &mut StepCtx<'_>) -> BTreeMap<U, T::Claimed> {
        self.into_iter().map(|(k, v)| (k, v.claim(ctx))).collect()
    }
}

impl<U: Ord, T: ReadVarValue> ReadVarValue for BTreeMap<U, T> {
    type Value = BTreeMap<U, T::Value>;

    fn read_value(self, rt: &mut RustRuntimeServices<'_>) -> Self::Value {
        self.into_iter()
            .map(|(k, v)| (k, v.read_value(rt)))
            .collect()
    }
}

macro_rules! impl_tuple_claim {
    ($($T:tt)*) => {
        impl<$($T,)*> $crate::node::ClaimVar for ($($T,)*)
        where
            $($T: $crate::node::ClaimVar,)*
        {
            type Claimed = ($($T::Claimed,)*);

            #[expect(non_snake_case)]
            fn claim(self, ctx: &mut $crate::node::StepCtx<'_>) -> Self::Claimed {
                let ($($T,)*) = self;
                ($($T.claim(ctx),)*)
            }
        }

        impl<$($T,)*> $crate::node::ReadVarValue for ($($T,)*)
        where
            $($T: $crate::node::ReadVarValue,)*
        {
            type Value = ($($T::Value,)*);

            #[expect(non_snake_case)]
            fn read_value(self, rt: &mut $crate::node::RustRuntimeServices<'_>) -> Self::Value {
                let ($($T,)*) = self;
                ($($T.read_value(rt),)*)
            }
        }
    };
}

impl_tuple_claim!(A B C D E F G H I J);
impl_tuple_claim!(A B C D E F G H I);
impl_tuple_claim!(A B C D E F G H);
impl_tuple_claim!(A B C D E F G);
impl_tuple_claim!(A B C D E F);
impl_tuple_claim!(A B C D E);
impl_tuple_claim!(A B C D);
impl_tuple_claim!(A B C);
impl_tuple_claim!(A B);
impl_tuple_claim!(A);

impl ClaimVar for () {
    type Claimed = ();

    fn claim(self, _ctx: &mut StepCtx<'_>) -> Self::Claimed {}
}

impl ReadVarValue for () {
    type Value = ();

    fn read_value(self, _rt: &mut RustRuntimeServices<'_>) -> Self::Value {}
}

/// Read a custom, user-defined secret by passing in the secret name.
///
/// Intended usage is to get a secret using the [`crate::pipeline::Pipeline::gh_use_secret`] API
/// and to use the returned value through the [`NodeCtx::get_gh_context_var`] API.
#[derive(Serialize, Deserialize, Clone)]
pub struct GhUserSecretVar(pub(crate) String);

/// Read a value from a flowey Var at runtime, returning the value written by
/// the Var's corresponding [`WriteVar`].
///
/// Vars in flowey must be serde de/serializable, in order to be de/serialized
/// between multiple steps/nodes.
///
/// In order to read the value contained within a `ReadVar`, it must first be
/// _claimed_ by a particular step (using the [`ClaimVar::claim`] API). Once
/// claimed, the Var can be read using APIs such as
/// [`RustRuntimeServices::read`], or [`AdoStepServices::get_var`]
///
/// Note that all `ReadVar`s in flowey are _immutable_. In other words:
/// reading the value of a `ReadVar` multiple times from multiple nodes will
/// _always_ return the same value.
///
/// This is a natural consequence `ReadVar` obtaining its value from the result
/// of a write into [`WriteVar`], whose API enforces that there can only ever be
/// a single Write to a `WriteVar`.
#[derive(Debug, Serialize, Deserialize)]
pub struct ReadVar<T, C = VarNotClaimed> {
    backing_var: ReadVarBacking<T>,
    #[serde(skip)]
    _kind: std::marker::PhantomData<C>,
}

/// A [`ReadVar`] which has been claimed by a particular step, allowing it to
/// be read at runtime.
pub type ClaimedReadVar<T> = ReadVar<T, VarClaimed>;

// cloning is fine, since you can totally have multiple dependents
impl<T: Serialize + DeserializeOwned, C> Clone for ReadVar<T, C> {
    fn clone(&self) -> Self {
        ReadVar {
            backing_var: self.backing_var.clone(),
            _kind: std::marker::PhantomData,
        }
    }
}

#[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
enum ReadVarBacking<T> {
    RuntimeVar {
        var: String,
        /// If true, then don't try to parse this variable--it was converted
        /// into a side effect (of type `()`) from another type, so the
        /// serialization will not match.
        ///
        /// If false, it may still be a "side effect" variable, but type `T`
        /// matches its serialization.
        is_side_effect: bool,
    },
    Inline(T),
}

// avoid requiring types to include an explicit clone bound
impl<T: Serialize + DeserializeOwned> Clone for ReadVarBacking<T> {
    fn clone(&self) -> Self {
        match self {
            Self::RuntimeVar {
                var,
                is_side_effect,
            } => Self::RuntimeVar {
                var: var.clone(),
                is_side_effect: *is_side_effect,
            },
            Self::Inline(v) => {
                Self::Inline(serde_json::from_value(serde_json::to_value(v).unwrap()).unwrap())
            }
        }
    }
}

impl<T: Serialize + DeserializeOwned> ReadVar<T> {
    /// (Internal API) Switch the claim marker to "claimed".
    fn into_claimed(self) -> ReadVar<T, VarClaimed> {
        let Self { backing_var, _kind } = self;

        ReadVar {
            backing_var,
            _kind: std::marker::PhantomData,
        }
    }

    /// Discard any type information associated with the Var, and treat the Var
    /// as through it was only a side effect.
    ///
    /// e.g: if a Node returns a `ReadVar<PathBuf>`, but you know that the mere
    /// act of having _run_ the node has ensured the file is placed in a "magic
    /// location" for some other node, then it may be useful to treat the
    /// `ReadVar<PathBuf>` as a simple `ReadVar<SideEffect>`, which can be
    /// passed along as part of a larger bundle of `Vec<ReadVar<SideEffect>>`.
    #[must_use]
    pub fn into_side_effect(self) -> ReadVar<SideEffect> {
        ReadVar {
            backing_var: match self.backing_var {
                ReadVarBacking::RuntimeVar {
                    var,
                    is_side_effect: _,
                } => ReadVarBacking::RuntimeVar {
                    var,
                    is_side_effect: true,
                },
                ReadVarBacking::Inline(_) => ReadVarBacking::Inline(()),
            },
            _kind: std::marker::PhantomData,
        }
    }

    /// Maps a `ReadVar<T>` to a new `ReadVar<U>`, by applying a function to the
    /// Var at runtime.
    #[track_caller]
    #[must_use]
    pub fn map<F, U>(&self, ctx: &mut NodeCtx<'_>, f: F) -> ReadVar<U>
    where
        T: 'static,
        U: Serialize + DeserializeOwned + 'static,
        F: FnOnce(T) -> U + 'static,
    {
        let (read_from, write_into) = ctx.new_var();
        self.write_into_with(ctx, write_into, f);
        read_from
    }

    /// Maps a `ReadVar<T>` into an existing `WriteVar<U>` by applying a
    /// function to the Var at runtime.
    #[track_caller]
    pub fn write_into_with<F, U>(&self, ctx: &mut NodeCtx<'_>, write_into: WriteVar<U>, f: F)
    where
        T: 'static,
        U: Serialize + DeserializeOwned + 'static,
        F: FnOnce(T) -> U + 'static,
    {
        let this = self.clone();
        ctx.emit_minor_rust_step("🌼 write_into Var", move |ctx| {
            let this = this.claim(ctx);
            let write_into = write_into.claim(ctx);
            move |rt| {
                let this = rt.read(this);
                rt.write(write_into, &f(this));
            }
        });
    }

    /// Maps a `ReadVar<T>` into an existing `WriteVar<U>`
    #[track_caller]
    pub fn write_into(&self, ctx: &mut NodeCtx<'_>, write_into: WriteVar<T>)
    where
        T: 'static,
    {
        self.write_into_with(ctx, write_into, |x| x);
    }

    /// Zips self (`ReadVar<T>`) with another `ReadVar<U>`, returning a new
    /// `ReadVar<(T, U)>`
    #[track_caller]
    #[must_use]
    pub fn zip<U>(&self, ctx: &mut NodeCtx<'_>, other: ReadVar<U>) -> ReadVar<(T, U)>
    where
        T: 'static,
        U: Serialize + DeserializeOwned + 'static,
    {
        let (read_from, write_into) = ctx.new_var();
        let this = self.clone();
        ctx.emit_minor_rust_step("🌼 Zip Vars", move |ctx| {
            let this = this.claim(ctx);
            let other = other.claim(ctx);
            let write_into = write_into.claim(ctx);
            move |rt| {
                let this = rt.read(this);
                let other = rt.read(other);
                rt.write(write_into, &(this, other));
            }
        });
        read_from
    }

    /// Create a new `ReadVar` from a static value.
    ///
    /// **WARNING:** Static values **CANNOT BE SECRETS**, as they are encoded as
    /// plain-text in the output flow.
    #[track_caller]
    #[must_use]
    pub fn from_static(val: T) -> ReadVar<T>
    where
        T: 'static,
    {
        ReadVar {
            backing_var: ReadVarBacking::Inline(val),
            _kind: std::marker::PhantomData,
        }
    }

    /// If this [`ReadVar`] contains a static value, return it.
    ///
    /// Nodes can opt-in to using this method as a way to generate optimized
    /// steps in cases where the value of a variable is known ahead of time.
    ///
    /// e.g: a node doing a git checkout could leverage this method to decide
    /// whether its ADO backend should emit a conditional step for checking out
    /// a repo, or if it can statically include / exclude the checkout request.
    pub fn get_static(&self) -> Option<T> {
        match self.clone().backing_var {
            ReadVarBacking::Inline(v) => Some(v),
            _ => None,
        }
    }

    /// Transpose a `Vec<ReadVar<T>>` into a `ReadVar<Vec<T>>`
    #[track_caller]
    #[must_use]
    pub fn transpose_vec(ctx: &mut NodeCtx<'_>, vec: Vec<ReadVar<T>>) -> ReadVar<Vec<T>>
    where
        T: 'static,
    {
        let (read_from, write_into) = ctx.new_var();
        ctx.emit_minor_rust_step("🌼 Transpose Vec<ReadVar<T>>", move |ctx| {
            let vec = vec.claim(ctx);
            let write_into = write_into.claim(ctx);
            move |rt| {
                let mut v = Vec::new();
                for var in vec {
                    v.push(rt.read(var));
                }
                rt.write(write_into, &v);
            }
        });
        read_from
    }

    /// Returns a new instance of this variable with an artificial dependency on
    /// `other`.
    ///
    /// This is useful for making explicit a non-explicit dependency between the
    /// two variables. For example, if `self` contains a path to a file, and
    /// `other` is only written once that file has been created, then this
    /// method can be used to return a new `ReadVar` which depends on `other`
    /// but is otherwise identical to `self`. This ensures that when the new
    /// variable is read, the file has been created.
    ///
    /// In general, it is better to ensure that the dependency is explicit, so
    /// that if you have a variable with a path, then you know that the file
    /// exists when you read it. This method is useful in cases where this is
    /// not naturally the case, e.g., when you are providing a path as part of a
    /// request, as opposed to the path being returned to you.
    #[must_use]
    pub fn depending_on<U>(&self, ctx: &mut NodeCtx<'_>, other: &ReadVar<U>) -> Self
    where
        T: 'static,
        U: Serialize + DeserializeOwned + 'static,
    {
        // This could probably be handled without an additional Rust step with some
        // additional work in the backend, but this is simple enough for now.
        ctx.emit_minor_rust_stepv("🌼 Add dependency", |ctx| {
            let this = self.clone().claim(ctx);
            other.clone().claim(ctx);
            move |rt| rt.read(this)
        })
    }

    /// Consume this `ReadVar` outside the context of a step, signalling that it
    /// won't be used.
    pub fn claim_unused(self, ctx: &mut NodeCtx<'_>) {
        match self.backing_var {
            ReadVarBacking::RuntimeVar {
                var,
                is_side_effect: _,
            } => ctx.backend.borrow_mut().on_unused_read_var(&var),
            ReadVarBacking::Inline(_) => {}
        }
    }

    pub(crate) fn into_json(self) -> ReadVar<serde_json::Value> {
        match self.backing_var {
            ReadVarBacking::RuntimeVar {
                var,
                is_side_effect,
            } => ReadVar {
                backing_var: ReadVarBacking::RuntimeVar {
                    var,
                    is_side_effect,
                },
                _kind: std::marker::PhantomData,
            },
            ReadVarBacking::Inline(v) => ReadVar {
                backing_var: ReadVarBacking::Inline(serde_json::to_value(v).unwrap()),
                _kind: std::marker::PhantomData,
            },
        }
    }
}

/// DANGER: obtain a handle to a [`ReadVar`] "out of thin air".
///
/// This should NEVER be used from within a flowey node. This is a sharp tool,
/// and should only be used by code implementing flow / pipeline resolution
/// logic.
#[must_use]
pub fn thin_air_read_runtime_var<T>(backing_var: String) -> ReadVar<T>
where
    T: Serialize + DeserializeOwned,
{
    ReadVar {
        backing_var: ReadVarBacking::RuntimeVar {
            var: backing_var,
            is_side_effect: false,
        },
        _kind: std::marker::PhantomData,
    }
}

/// DANGER: obtain a handle to a [`WriteVar`] "out of thin air".
///
/// This should NEVER be used from within a flowey node. This is a sharp tool,
/// and should only be used by code implementing flow / pipeline resolution
/// logic.
#[must_use]
pub fn thin_air_write_runtime_var<T>(backing_var: String) -> WriteVar<T>
where
    T: Serialize + DeserializeOwned,
{
    WriteVar {
        backing_var,
        is_side_effect: false,
        _kind: std::marker::PhantomData,
    }
}

/// DANGER: obtain a [`ReadVar`] backing variable and side effect status.
///
/// This should NEVER be used from within a flowey node. This relies on
/// flowey variable implementation details, and should only be used by code
/// implementing flow / pipeline resolution logic.
pub fn read_var_internals<T: Serialize + DeserializeOwned, C>(
    var: &ReadVar<T, C>,
) -> (Option<String>, bool) {
    match var.backing_var {
        ReadVarBacking::RuntimeVar {
            var: ref s,
            is_side_effect,
        } => (Some(s.clone()), is_side_effect),
        ReadVarBacking::Inline(_) => (None, false),
    }
}

pub trait ImportCtxBackend {
    fn on_possible_dep(&mut self, node_handle: NodeHandle);
}

/// Context passed to [`FlowNode::imports`].
pub struct ImportCtx<'a> {
    backend: &'a mut dyn ImportCtxBackend,
}

impl ImportCtx<'_> {
    /// Declare that a Node can be referenced in [`FlowNode::emit`]
    pub fn import<N: FlowNodeBase + 'static>(&mut self) {
        self.backend.on_possible_dep(NodeHandle::from_type::<N>())
    }
}

pub fn new_import_ctx(backend: &mut dyn ImportCtxBackend) -> ImportCtx<'_> {
    ImportCtx { backend }
}

pub trait NodeCtxBackend {
    /// Handle to the current node this `ctx` corresponds to
    fn current_node(&self) -> NodeHandle;

    /// Return a string which uniquely identifies this particular Var
    /// registration.
    ///
    /// Typically consists of `{current node handle}{ordinal}`
    fn on_new_var(&mut self) -> String;

    /// Invoked when a node claims a particular runtime variable
    fn on_claimed_runtime_var(&mut self, var: &str, is_read: bool);

    /// Invoked when a node marks a particular runtime variable as unused
    fn on_unused_read_var(&mut self, var: &str);

    /// Invoked when a node sets a request on a node.
    ///
    /// - `node_typeid` will always correspond to a node that was previously
    ///   passed to `on_register`.
    /// - `req` may be an error, in the case where the NodeCtx failed to
    ///   serialize the provided request.
    // FIXME: this should be using type-erased serde
    fn on_request(&mut self, node_handle: NodeHandle, req: anyhow::Result<Box<[u8]>>);

    /// Invoked when a node sets config on another node.
    ///
    /// Config is merged by the resolver and delivered before action requests.
    fn on_config(&mut self, node_handle: NodeHandle, config: anyhow::Result<Box<[u8]>>);

    fn on_emit_rust_step(
        &mut self,
        label: &str,
        can_merge: bool,
        code: Box<dyn for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> anyhow::Result<()>>,
    );

    fn on_emit_ado_step(
        &mut self,
        label: &str,
        yaml_snippet: Box<dyn for<'a> FnOnce(&'a mut AdoStepServices<'_>) -> String>,
        inline_script: Option<
            Box<dyn for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> anyhow::Result<()>>,
        >,
        condvar: Option<String>,
    );

    fn on_emit_gh_step(
        &mut self,
        label: &str,
        uses: &str,
        with: BTreeMap<String, ClaimedGhParam>,
        condvar: Option<String>,
        outputs: BTreeMap<String, Vec<GhOutput>>,
        permissions: BTreeMap<GhPermission, GhPermissionValue>,
        gh_to_rust: Vec<GhToRust>,
        rust_to_gh: Vec<RustToGh>,
    );

    fn on_emit_side_effect_step(&mut self);

    fn backend(&mut self) -> FlowBackend;
    fn platform(&mut self) -> FlowPlatform;
    fn arch(&mut self) -> FlowArch;

    /// Return a node-specific persistent store path. The backend does not need
    /// to ensure that the path exists - flowey will automatically emit a step
    /// to construct the directory at runtime.
    fn persistent_dir_path_var(&mut self) -> Option<String>;
}

pub fn new_node_ctx(backend: &mut dyn NodeCtxBackend) -> NodeCtx<'_> {
    NodeCtx {
        backend: Rc::new(RefCell::new(backend)),
    }
}

/// What backend the flow is being running on.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum FlowBackend {
    /// Running locally.
    Local,
    /// Running on ADO.
    Ado,
    /// Running on GitHub Actions
    Github,
}

/// The kind platform the flow is being running on, Windows or Unix.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum FlowPlatformKind {
    Windows,
    Unix,
}

/// The kind platform the flow is being running on, Windows or Unix.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
pub enum FlowPlatformLinuxDistro {
    /// Fedora (including WSL2)
    Fedora,
    /// Ubuntu (including WSL2)
    Ubuntu,
    /// Azure Linux (tdnf-based)
    AzureLinux,
    /// Arch Linux (including WSL2)
    Arch,
    /// openSUSE (including WSL2)
    OpenSuse,
    /// Nix environment (detected via IN_NIX_SHELL env var or having a `/nix/store` in PATH)
    Nix,
    /// An unknown distribution
    Unknown,
}

/// What platform the flow is being running on.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[non_exhaustive]
pub enum FlowPlatform {
    /// Windows
    Windows,
    /// Linux (including WSL2)
    Linux(FlowPlatformLinuxDistro),
    /// macOS
    MacOs,
}

impl FlowPlatform {
    pub fn kind(&self) -> FlowPlatformKind {
        match self {
            Self::Windows => FlowPlatformKind::Windows,
            Self::Linux(_) | Self::MacOs => FlowPlatformKind::Unix,
        }
    }

    fn as_str(&self) -> &'static str {
        match self {
            Self::Windows => "windows",
            Self::Linux(_) => "linux",
            Self::MacOs => "macos",
        }
    }

    /// The suffix to use for executables on this platform.
    pub fn exe_suffix(&self) -> &'static str {
        if self == &Self::Windows { ".exe" } else { "" }
    }

    /// The full name for a binary on this platform (i.e. `name + self.exe_suffix()`).
    pub fn binary(&self, name: &str) -> String {
        format!("{}{}", name, self.exe_suffix())
    }
}

impl std::fmt::Display for FlowPlatform {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.pad(self.as_str())
    }
}

/// What architecture the flow is being running on.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[non_exhaustive]
pub enum FlowArch {
    X86_64,
    Aarch64,
}

impl FlowArch {
    fn as_str(&self) -> &'static str {
        match self {
            Self::X86_64 => "x86_64",
            Self::Aarch64 => "aarch64",
        }
    }
}

impl std::fmt::Display for FlowArch {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.pad(self.as_str())
    }
}

/// Context object for an individual step.
pub struct StepCtx<'a> {
    backend: Rc<RefCell<&'a mut dyn NodeCtxBackend>>,
}

impl StepCtx<'_> {
    /// What backend the flow is being running on (e.g: locally, ADO, GitHub,
    /// etc...)
    pub fn backend(&self) -> FlowBackend {
        self.backend.borrow_mut().backend()
    }

    /// What platform the flow is being running on (e.g: windows, linux, wsl2,
    /// etc...).
    pub fn platform(&self) -> FlowPlatform {
        self.backend.borrow_mut().platform()
    }
}

const NO_ADO_INLINE_SCRIPT: Option<
    for<'a> fn(&'a mut RustRuntimeServices<'_>) -> anyhow::Result<()>,
> = None;

/// Context object for a `FlowNode`.
pub struct NodeCtx<'a> {
    backend: Rc<RefCell<&'a mut dyn NodeCtxBackend>>,
}

impl<'ctx> NodeCtx<'ctx> {
    /// Emit a Rust-based step.
    ///
    /// As a convenience feature, this function returns a special _optional_
    /// [`ReadVar<SideEffect>`], which will not result in a "unused variable"
    /// error if no subsequent step ends up claiming it.
    pub fn emit_rust_step<F, G>(&mut self, label: impl AsRef<str>, code: F) -> ReadVar<SideEffect>
    where
        F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G,
        G: for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> anyhow::Result<()> + 'static,
    {
        self.emit_rust_step_inner(label.as_ref(), false, code)
    }

    /// Emit a Rust-based step that cannot fail.
    ///
    /// This is equivalent to [`NodeCtx::emit_rust_step`], but it is for steps that cannot
    /// fail and that do not need to be emitted as a separate step in a YAML
    /// pipeline. This simplifies the pipeline logs.
    pub fn emit_minor_rust_step<F, G>(
        &mut self,
        label: impl AsRef<str>,
        code: F,
    ) -> ReadVar<SideEffect>
    where
        F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G,
        G: for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) + 'static,
    {
        self.emit_rust_step_inner(label.as_ref(), true, |ctx| {
            let f = code(ctx);
            |rt| {
                f(rt);
                Ok(())
            }
        })
    }

    /// Emit a Rust-based step, creating a new `ReadVar<T>` from the step's
    /// return value.
    ///
    /// This is a convenience function that streamlines the following common
    /// flowey pattern:
    ///
    /// ```ignore
    /// // creating a new Var explicitly
    /// let (read_foo, write_foo) = ctx.new_var();
    /// ctx.emit_rust_step("foo", |ctx| {
    ///     let write_foo = write_foo.claim(ctx);
    ///     |rt| {
    ///         rt.write(write_foo, &get_foo());
    ///         Ok(())
    ///     }
    /// });
    ///
    /// // creating a new Var automatically
    /// let read_foo = ctx.emit_rust_stepv("foo", |ctx| |rt| Ok(get_foo()));
    /// ```
    #[must_use]
    #[track_caller]
    pub fn emit_rust_stepv<T, F, G>(&mut self, label: impl AsRef<str>, code: F) -> ReadVar<T>
    where
        T: Serialize + DeserializeOwned + 'static,
        F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G,
        G: for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> anyhow::Result<T> + 'static,
    {
        self.emit_rust_stepv_inner(label.as_ref(), false, code)
    }

    /// Emit a Rust-based step, creating a new `ReadVar<T>` from the step's
    /// return value.
    ///
    /// This is equivalent to `emit_rust_stepv`, but it is for steps that cannot
    /// fail and that do not need to be emitted as a separate step in a YAML
    /// pipeline. This simplifies the pipeline logs.
    ///
    /// This is a convenience function that streamlines the following common
    /// flowey pattern:
    ///
    /// ```ignore
    /// // creating a new Var explicitly
    /// let (read_foo, write_foo) = ctx.new_var();
    /// ctx.emit_minor_rust_step("foo", |ctx| {
    ///     let write_foo = write_foo.claim(ctx);
    ///     |rt| {
    ///         rt.write(write_foo, &get_foo());
    ///     }
    /// });
    ///
    /// // creating a new Var automatically
    /// let read_foo = ctx.emit_minor_rust_stepv("foo", |ctx| |rt| get_foo());
    /// ```
    #[must_use]
    #[track_caller]
    pub fn emit_minor_rust_stepv<T, F, G>(&mut self, label: impl AsRef<str>, code: F) -> ReadVar<T>
    where
        T: Serialize + DeserializeOwned + 'static,
        F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G,
        G: for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> T + 'static,
    {
        self.emit_rust_stepv_inner(label.as_ref(), true, |ctx| {
            let f = code(ctx);
            |rt| Ok(f(rt))
        })
    }

    fn emit_rust_step_inner<F, G>(
        &mut self,
        label: &str,
        can_merge: bool,
        code: F,
    ) -> ReadVar<SideEffect>
    where
        F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G,
        G: for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> anyhow::Result<()> + 'static,
    {
        let (read, write) = self.new_prefixed_var("auto_se");

        let ctx = &mut StepCtx {
            backend: self.backend.clone(),
        };
        write.claim(ctx);

        let code = code(ctx);
        self.backend
            .borrow_mut()
            .on_emit_rust_step(label.as_ref(), can_merge, Box::new(code));
        read
    }

    #[must_use]
    #[track_caller]
    fn emit_rust_stepv_inner<T, F, G>(
        &mut self,
        label: impl AsRef<str>,
        can_merge: bool,
        code: F,
    ) -> ReadVar<T>
    where
        T: Serialize + DeserializeOwned + 'static,
        F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G,
        G: for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> anyhow::Result<T> + 'static,
    {
        let (read, write) = self.new_var();

        let ctx = &mut StepCtx {
            backend: self.backend.clone(),
        };
        let write = write.claim(ctx);

        let code = code(ctx);
        self.backend.borrow_mut().on_emit_rust_step(
            label.as_ref(),
            can_merge,
            Box::new(|rt| {
                let val = code(rt)?;
                rt.write(write, &val);
                Ok(())
            }),
        );
        read
    }

    /// Load an ADO global runtime variable into a flowey [`ReadVar`].
    #[track_caller]
    #[must_use]
    pub fn get_ado_variable(&mut self, ado_var: AdoRuntimeVar) -> ReadVar<String> {
        let (var, write_var) = self.new_var();
        self.emit_ado_step(format!("🌼 read {}", ado_var.as_raw_var_name()), |ctx| {
            let write_var = write_var.claim(ctx);
            |rt| {
                rt.set_var(write_var, ado_var);
                "".into()
            }
        });
        var
    }

    /// Emit an ADO step.
    pub fn emit_ado_step<F, G>(&mut self, display_name: impl AsRef<str>, yaml_snippet: F)
    where
        F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G,
        G: for<'a> FnOnce(&'a mut AdoStepServices<'_>) -> String + 'static,
    {
        self.emit_ado_step_inner(display_name, None, |ctx| {
            (yaml_snippet(ctx), NO_ADO_INLINE_SCRIPT)
        })
    }

    /// Emit an ADO step, conditionally executed based on the value of `cond` at
    /// runtime.
    pub fn emit_ado_step_with_condition<F, G>(
        &mut self,
        display_name: impl AsRef<str>,
        cond: ReadVar<bool>,
        yaml_snippet: F,
    ) where
        F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G,
        G: for<'a> FnOnce(&'a mut AdoStepServices<'_>) -> String + 'static,
    {
        self.emit_ado_step_inner(display_name, Some(cond), |ctx| {
            (yaml_snippet(ctx), NO_ADO_INLINE_SCRIPT)
        })
    }

    /// Emit an ADO step, conditionally executed based on the value of`cond` at
    /// runtime.
    pub fn emit_ado_step_with_condition_optional<F, G>(
        &mut self,
        display_name: impl AsRef<str>,
        cond: Option<ReadVar<bool>>,
        yaml_snippet: F,
    ) where
        F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G,
        G: for<'a> FnOnce(&'a mut AdoStepServices<'_>) -> String + 'static,
    {
        self.emit_ado_step_inner(display_name, cond, |ctx| {
            (yaml_snippet(ctx), NO_ADO_INLINE_SCRIPT)
        })
    }

    /// Emit an ADO step which invokes a rust callback using an inline script.
    ///
    /// By using the `{{FLOWEY_INLINE_SCRIPT}}` template in the returned yaml
    /// snippet, flowey will interpolate a command ~roughly akin to `flowey
    /// exec-snippet <rust-snippet-id>` into the generated yaml.
    ///
    /// e.g: if we wanted to _manually_ wrap the bash ADO snippet for whatever
    /// reason:
    ///
    /// ```text
    /// - bash: |
    ///     echo "hello there!"
    ///     {{FLOWEY_INLINE_SCRIPT}}
    ///     echo echo "bye!"
    /// ```
    ///
    /// # Limitations
    ///
    /// At the moment, due to flowey API limitations, it is only possible to
    /// embed a single inline script into a YAML step.
    ///
    /// In the future, rather than having separate methods for "emit step with X
    /// inline scripts", flowey should support declaring "first-class" callbacks
    /// via a (hypothetical) `ctx.new_callback_var(|ctx| |rt, input: Input| ->
    /// Output { ... })` API, at which point.
    ///
    /// If such an API were to exist, one could simply use the "vanilla" emit
    /// yaml step functions with these first-class callbacks.
    pub fn emit_ado_step_with_inline_script<F, G, H>(
        &mut self,
        display_name: impl AsRef<str>,
        yaml_snippet: F,
    ) where
        F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> (G, H),
        G: for<'a> FnOnce(&'a mut AdoStepServices<'_>) -> String + 'static,
        H: for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> anyhow::Result<()> + 'static,
    {
        self.emit_ado_step_inner(display_name, None, |ctx| {
            let (f, g) = yaml_snippet(ctx);
            (f, Some(g))
        })
    }

    fn emit_ado_step_inner<F, G, H>(
        &mut self,
        display_name: impl AsRef<str>,
        cond: Option<ReadVar<bool>>,
        yaml_snippet: F,
    ) where
        F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> (G, Option<H>),
        G: for<'a> FnOnce(&'a mut AdoStepServices<'_>) -> String + 'static,
        H: for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> anyhow::Result<()> + 'static,
    {
        let condvar = match cond.map(|c| c.backing_var) {
            // it seems silly to allow this... but it's not hard so why not?
            Some(ReadVarBacking::Inline(cond)) => {
                if !cond {
                    return;
                } else {
                    None
                }
            }
            Some(ReadVarBacking::RuntimeVar {
                var,
                is_side_effect,
            }) => {
                assert!(!is_side_effect);
                self.backend.borrow_mut().on_claimed_runtime_var(&var, true);
                Some(var)
            }
            None => None,
        };

        let (yaml_snippet, inline_script) = yaml_snippet(&mut StepCtx {
            backend: self.backend.clone(),
        });
        self.backend.borrow_mut().on_emit_ado_step(
            display_name.as_ref(),
            Box::new(yaml_snippet),
            if let Some(inline_script) = inline_script {
                Some(Box::new(inline_script))
            } else {
                None
            },
            condvar,
        );
    }

    /// Load a GitHub context variable into a flowey [`ReadVar`].
    #[track_caller]
    #[must_use]
    pub fn get_gh_context_var(&mut self) -> GhContextVarReader<'ctx, Root> {
        GhContextVarReader {
            ctx: NodeCtx {
                backend: self.backend.clone(),
            },
            _state: std::marker::PhantomData,
        }
    }

    /// Emit a GitHub Actions action step.
    pub fn emit_gh_step(
        &mut self,
        display_name: impl AsRef<str>,
        uses: impl AsRef<str>,
    ) -> GhStepBuilder {
        GhStepBuilder::new(display_name, uses)
    }

    fn emit_gh_step_inner(
        &mut self,
        display_name: impl AsRef<str>,
        cond: Option<ReadVar<bool>>,
        uses: impl AsRef<str>,
        with: Option<BTreeMap<String, GhParam>>,
        outputs: BTreeMap<String, Vec<WriteVar<String>>>,
        run_after: Vec<ReadVar<SideEffect>>,
        permissions: BTreeMap<GhPermission, GhPermissionValue>,
    ) {
        let condvar = match cond.map(|c| c.backing_var) {
            // it seems silly to allow this... but it's not hard so why not?
            Some(ReadVarBacking::Inline(cond)) => {
                if !cond {
                    return;
                } else {
                    None
                }
            }
            Some(ReadVarBacking::RuntimeVar {
                var,
                is_side_effect,
            }) => {
                assert!(!is_side_effect);
                self.backend.borrow_mut().on_claimed_runtime_var(&var, true);
                Some(var)
            }
            None => None,
        };

        let with = with
            .unwrap_or_default()
            .into_iter()
            .map(|(k, v)| {
                (
                    k.clone(),
                    v.claim(&mut StepCtx {
                        backend: self.backend.clone(),
                    }),
                )
            })
            .collect();

        for var in run_after {
            var.claim(&mut StepCtx {
                backend: self.backend.clone(),
            });
        }

        let outputvars = outputs
            .into_iter()
            .map(|(name, vars)| {
                (
                    name,
                    vars.into_iter()
                        .map(|var| {
                            let var = var.claim(&mut StepCtx {
                                backend: self.backend.clone(),
                            });
                            GhOutput {
                                backing_var: var.backing_var,
                                is_secret: false,
                                is_object: false,
                            }
                        })
                        .collect(),
                )
            })
            .collect();

        self.backend.borrow_mut().on_emit_gh_step(
            display_name.as_ref(),
            uses.as_ref(),
            with,
            condvar,
            outputvars,
            permissions,
            Vec::new(),
            Vec::new(),
        );
    }

    /// Emit a "side-effect" step, which simply claims a set of side-effects in
    /// order to resolve another set of side effects.
    ///
    /// The same functionality could be achieved (less efficiently) by emitting
    /// a Rust step (or ADO step, or github step, etc...) that claims both sets
    /// of side-effects, and then does nothing. By using this method - flowey is
    /// able to avoid emitting that additional noop step at runtime.
    pub fn emit_side_effect_step(
        &mut self,
        use_side_effects: impl IntoIterator<Item = ReadVar<SideEffect>>,
        resolve_side_effects: impl IntoIterator<Item = WriteVar<SideEffect>>,
    ) {
        let mut backend = self.backend.borrow_mut();
        for var in use_side_effects.into_iter() {
            if let ReadVarBacking::RuntimeVar {
                var,
                is_side_effect: _,
            } = &var.backing_var
            {
                backend.on_claimed_runtime_var(var, true);
            }
        }

        for var in resolve_side_effects.into_iter() {
            backend.on_claimed_runtime_var(&var.backing_var, false);
        }

        backend.on_emit_side_effect_step();
    }

    /// What backend the flow is being running on (e.g: locally, ADO, GitHub,
    /// etc...)
    pub fn backend(&self) -> FlowBackend {
        self.backend.borrow_mut().backend()
    }

    /// What platform the flow is being running on (e.g: windows, linux, wsl2,
    /// etc...).
    pub fn platform(&self) -> FlowPlatform {
        self.backend.borrow_mut().platform()
    }

    /// What architecture the flow is being running on (x86_64 or Aarch64)
    pub fn arch(&self) -> FlowArch {
        self.backend.borrow_mut().arch()
    }

    /// Set a request on a particular node.
    pub fn req<R>(&mut self, req: R)
    where
        R: IntoRequest + 'static,
    {
        let mut backend = self.backend.borrow_mut();
        backend.on_request(
            NodeHandle::from_type::<R::Node>(),
            serde_json::to_vec(&req.into_request())
                .map(Into::into)
                .map_err(Into::into),
        );
    }

    /// Set config on a particular node.
    ///
    /// Config is merged by the resolver (all callers must agree on values)
    /// and delivered to the target node before any action requests.
    pub fn config<C>(&mut self, config: C)
    where
        C: IntoConfig + 'static,
    {
        let mut backend = self.backend.borrow_mut();
        backend.on_config(
            NodeHandle::from_type::<C::Node>(),
            serde_json::to_vec(&config)
                .map(Into::into)
                .map_err(Into::into),
        );
    }

    /// Set a request on a particular node, simultaneously creating a new flowey
    /// Var in the process.
    #[track_caller]
    #[must_use]
    pub fn reqv<T, R>(&mut self, f: impl FnOnce(WriteVar<T>) -> R) -> ReadVar<T>
    where
        T: Serialize + DeserializeOwned,
        R: IntoRequest + 'static,
    {
        let (read, write) = self.new_var();
        self.req::<R>(f(write));
        read
    }

    /// Set multiple requests on a particular node.
    pub fn requests<N>(&mut self, reqs: impl IntoIterator<Item = N::Request>)
    where
        N: FlowNodeBase + 'static,
    {
        let mut backend = self.backend.borrow_mut();
        for req in reqs.into_iter() {
            backend.on_request(
                NodeHandle::from_type::<N>(),
                serde_json::to_vec(&req).map(Into::into).map_err(Into::into),
            );
        }
    }

    /// Allocate a new flowey Var, returning two handles: one for reading the
    /// value, and another for writing the value.
    #[track_caller]
    #[must_use]
    pub fn new_var<T>(&self) -> (ReadVar<T>, WriteVar<T>)
    where
        T: Serialize + DeserializeOwned,
    {
        self.new_prefixed_var("")
    }

    #[track_caller]
    #[must_use]
    fn new_prefixed_var<T>(&self, prefix: &'static str) -> (ReadVar<T>, WriteVar<T>)
    where
        T: Serialize + DeserializeOwned,
    {
        // normalize call path to ensure determinism between windows and linux
        //
        // Only the source file is kept, not line/column: `{modpath}:{ordinal}`
        // already uniquely identifies the var, so including line/column would
        // needlessly churn every generated pipeline whenever unrelated edits
        // shift line numbers.
        let caller = std::panic::Location::caller().file().replace('\\', "/");

        // until we have a proper way to "split" debug info related to vars, we
        // kinda just lump it in with the var name itself.
        //
        // HACK: to work around cases where - depending on what the
        // current-working-dir is when incoking flowey - the returned
        // caller.file() path may leak the full path of the file (as opposed to
        // the relative path), resulting in inconsistencies between build
        // environments.
        //
        // For expediency, and to preserve some semblance of useful error
        // messages, we decided to play some sketchy games with the resulting
        // string to only preserve the _consistent_ bit of the path for a human
        // to use as reference.
        //
        // This is not ideal in the slightest, but it works OK for now
        let caller = caller
            .split_once("flowey/")
            .expect("due to a known limitation with flowey, all flowey code must have an ancestor dir called 'flowey/' somewhere in its full path")
            .1;

        let colon = if prefix.is_empty() { "" } else { ":" };
        let ordinal = self.backend.borrow_mut().on_new_var();
        let backing_var = format!("{prefix}{colon}{ordinal}:{caller}");

        (
            ReadVar {
                backing_var: ReadVarBacking::RuntimeVar {
                    var: backing_var.clone(),
                    is_side_effect: false,
                },
                _kind: std::marker::PhantomData,
            },
            WriteVar {
                backing_var,
                is_side_effect: false,
                _kind: std::marker::PhantomData,
            },
        )
    }

    /// Allocate special [`SideEffect`] var which can be used to schedule a
    /// "post-job" step associated with some existing step.
    ///
    /// This "post-job" step will then only run after all other regular steps
    /// have run (i.e: steps required to complete any top-level objectives
    /// passed in via [`crate::pipeline::PipelineJob::dep_on`]). This makes it
    /// useful for implementing various "cleanup" or "finalize" tasks.
    ///
    /// e.g: the Cache node uses this to upload the contents of a cache
    /// directory at the end of a Job.
    #[track_caller]
    #[must_use]
    pub fn new_post_job_side_effect(&self) -> (ReadVar<SideEffect>, WriteVar<SideEffect>) {
        self.new_prefixed_var("post_job")
    }

    /// Return a flowey Var pointing to a **node-specific** directory which
    /// will be persisted between runs, if such a directory is available.
    ///
    /// WARNING: this method is _very likely_ to return None when running on CI
    /// machines, as most CI agents are wiped between jobs!
    ///
    /// As such, it is NOT recommended that node authors reach for this method
    /// directly, and instead use abstractions such as the
    /// `flowey_lib_common::cache` Node, which implements node-level persistence
    /// in a way that works _regardless_ if a persistent_dir is available (e.g:
    /// by falling back to uploading / downloading artifacts to a "cache store"
    /// on platforms like ADO or Github Actions).
    #[track_caller]
    #[must_use]
    pub fn persistent_dir(&mut self) -> Option<ReadVar<PathBuf>> {
        let path: ReadVar<PathBuf> = ReadVar {
            backing_var: ReadVarBacking::RuntimeVar {
                var: self.backend.borrow_mut().persistent_dir_path_var()?,
                is_side_effect: false,
            },
            _kind: std::marker::PhantomData,
        };

        let folder_name = self
            .backend
            .borrow_mut()
            .current_node()
            .modpath()
            .replace("::", "__");

        Some(
            self.emit_rust_stepv("🌼 Create persistent store dir", |ctx| {
                let path = path.claim(ctx);
                |rt| {
                    let dir = rt.read(path).join(folder_name);
                    fs_err::create_dir_all(&dir)?;
                    Ok(dir)
                }
            }),
        )
    }

    /// Check to see if a persistent dir is available, without yet creating it.
    pub fn supports_persistent_dir(&mut self) -> bool {
        self.backend
            .borrow_mut()
            .persistent_dir_path_var()
            .is_some()
    }
}

// FUTURE: explore using type-erased serde here, instead of relying on
// `serde_json` in `flowey_core`.
pub trait RuntimeVarDb {
    fn get_var(&mut self, var_name: &str) -> (Vec<u8>, bool) {
        self.try_get_var(var_name)
            .unwrap_or_else(|| panic!("db is missing var {}", var_name))
    }

    fn try_get_var(&mut self, var_name: &str) -> Option<(Vec<u8>, bool)>;
    fn set_var(&mut self, var_name: &str, is_secret: bool, value: Vec<u8>);
}

impl RuntimeVarDb for Box<dyn RuntimeVarDb> {
    fn try_get_var(&mut self, var_name: &str) -> Option<(Vec<u8>, bool)> {
        (**self).try_get_var(var_name)
    }

    fn set_var(&mut self, var_name: &str, is_secret: bool, value: Vec<u8>) {
        (**self).set_var(var_name, is_secret, value)
    }
}

pub mod steps {
    pub mod ado {
        use crate::node::ClaimedReadVar;
        use crate::node::ClaimedWriteVar;
        use crate::node::ReadVarBacking;
        use serde::Deserialize;
        use serde::Serialize;
        use std::borrow::Cow;

        /// An ADO repository declared as a resource in the top-level pipeline.
        ///
        /// Created via [`crate::pipeline::Pipeline::ado_add_resources_repository`].
        ///
        /// Consumed via [`AdoStepServices::resolve_repository_id`].
        #[derive(Debug, Clone, Serialize, Deserialize)]
        pub struct AdoResourcesRepositoryId {
            pub(crate) repo_id: String,
        }

        impl AdoResourcesRepositoryId {
            /// Create a `AdoResourcesRepositoryId` corresponding to `self`
            /// (i.e: the repo which stores the current pipeline).
            ///
            /// This is safe to do from any context, as the `self` resource will
            /// _always_ be available.
            pub fn new_self() -> Self {
                Self {
                    repo_id: "self".into(),
                }
            }

            /// (dangerous) get the raw ID associated with this resource.
            ///
            /// It is highly recommended to avoid losing type-safety, and
            /// sticking to [`AdoStepServices::resolve_repository_id`].in order
            /// to resolve this type to a String.
            pub fn dangerous_get_raw_id(&self) -> &str {
                &self.repo_id
            }

            /// (dangerous) create a new ID out of thin air.
            ///
            /// It is highly recommended to avoid losing type-safety, and
            /// sticking to [`AdoStepServices::resolve_repository_id`].in order
            /// to resolve this type to a String.
            pub fn dangerous_new(repo_id: &str) -> Self {
                Self {
                    repo_id: repo_id.into(),
                }
            }
        }

        /// Handle to an ADO variable.
        ///
        /// Includes a (non-exhaustive) list of associated constants
        /// corresponding to global ADO vars which are _always_ available.
        #[derive(Clone, Debug, Serialize, Deserialize)]
        pub struct AdoRuntimeVar {
            is_secret: bool,
            ado_var: Cow<'static, str>,
        }

        impl AdoRuntimeVar {
            /// `build.SourceBranch`
            ///
            /// NOTE: Includes the full branch ref (ex: `refs/heads/main`) so
            /// unlike `build.SourceBranchName`, a branch like `user/foo/bar`
            /// won't be stripped to just `bar`
            pub const BUILD_SOURCE_BRANCH: AdoRuntimeVar = AdoRuntimeVar::new("build.SourceBranch");

            /// `build.BuildNumber`
            pub const BUILD_BUILD_NUMBER: AdoRuntimeVar = AdoRuntimeVar::new("build.BuildNumber");

            /// `Build.BuildId`
            pub const BUILD_BUILD_ID: AdoRuntimeVar = AdoRuntimeVar::new("Build.BuildId");

            /// `System.CollectionUri`
            pub const SYSTEM_COLLECTION_URI: AdoRuntimeVar =
                AdoRuntimeVar::new("System.CollectionUri");

            /// `System.TeamProjectId`
            pub const SYSTEM_TEAM_PROJECT_ID: AdoRuntimeVar =
                AdoRuntimeVar::new("System.TeamProjectId");

            /// `System.AccessToken`
            pub const SYSTEM_ACCESS_TOKEN: AdoRuntimeVar =
                AdoRuntimeVar::new_secret("System.AccessToken");

            /// `System.System.JobAttempt`
            pub const SYSTEM_JOB_ATTEMPT: AdoRuntimeVar =
                AdoRuntimeVar::new_secret("System.JobAttempt");

            /// `Pipeline.Workspace`
            pub const PIPELINE_WORKSPACE: AdoRuntimeVar = AdoRuntimeVar::new("Pipeline.Workspace");
        }

        impl AdoRuntimeVar {
            const fn new(s: &'static str) -> Self {
                Self {
                    is_secret: false,
                    ado_var: Cow::Borrowed(s),
                }
            }

            const fn new_secret(s: &'static str) -> Self {
                Self {
                    is_secret: true,
                    ado_var: Cow::Borrowed(s),
                }
            }

            /// Check if the ADO var is tagged as being a secret
            pub fn is_secret(&self) -> bool {
                self.is_secret
            }

            /// Get the raw underlying ADO variable name
            pub fn as_raw_var_name(&self) -> String {
                self.ado_var.as_ref().into()
            }

            /// Get a handle to an ADO runtime variable corresponding to a
            /// global ADO variable with the given name.
            ///
            /// This method should be used rarely and with great care!
            ///
            /// ADO variables are global, and sidestep the type-safe data flow
            /// between flowey nodes entirely!
            pub fn dangerous_from_global(ado_var_name: impl AsRef<str>, is_secret: bool) -> Self {
                Self {
                    is_secret,
                    ado_var: ado_var_name.as_ref().to_owned().into(),
                }
            }
        }

        pub fn new_ado_step_services(
            fresh_ado_var: &mut dyn FnMut() -> String,
        ) -> AdoStepServices<'_> {
            AdoStepServices {
                fresh_ado_var,
                ado_to_rust: Vec::new(),
                rust_to_ado: Vec::new(),
            }
        }

        pub struct CompletedAdoStepServices {
            pub ado_to_rust: Vec<(String, String, bool)>,
            pub rust_to_ado: Vec<(String, String)>,
        }

        impl CompletedAdoStepServices {
            pub fn from_ado_step_services(access: AdoStepServices<'_>) -> Self {
                let AdoStepServices {
                    fresh_ado_var: _,
                    ado_to_rust,
                    rust_to_ado,
                } = access;

                Self {
                    ado_to_rust,
                    rust_to_ado,
                }
            }
        }

        pub struct AdoStepServices<'a> {
            fresh_ado_var: &'a mut dyn FnMut() -> String,
            ado_to_rust: Vec<(String, String, bool)>,
            rust_to_ado: Vec<(String, String)>,
        }

        impl AdoStepServices<'_> {
            /// Return the raw string identifier for the given
            /// [`AdoResourcesRepositoryId`].
            pub fn resolve_repository_id(&self, repo_id: AdoResourcesRepositoryId) -> String {
                repo_id.repo_id
            }

            /// Set the specified flowey Var using the value of the given ADO var.
            // TODO: is there a good way to allow auto-casting the ADO var back
            // to a WriteVar<T>, instead of just a String? It's complicated by
            // the fact that the ADO var to flowey bridge is handled by the ADO
            // backend, which itself needs to know type info...
            pub fn set_var(&mut self, var: ClaimedWriteVar<String>, from_ado_var: AdoRuntimeVar) {
                self.ado_to_rust.push((
                    from_ado_var.ado_var.into(),
                    var.backing_var,
                    from_ado_var.is_secret,
                ))
            }

            /// Get the value of a flowey Var as a ADO runtime variable.
            pub fn get_var(&mut self, var: ClaimedReadVar<String>) -> AdoRuntimeVar {
                let backing_var = if let ReadVarBacking::RuntimeVar {
                    var,
                    is_side_effect,
                } = &var.backing_var
                {
                    assert!(!is_side_effect);
                    var
                } else {
                    todo!("support inline ado read vars")
                };

                let new_ado_var_name = (self.fresh_ado_var)();

                self.rust_to_ado
                    .push((backing_var.clone(), new_ado_var_name.clone()));
                AdoRuntimeVar::dangerous_from_global(new_ado_var_name, false)
            }
        }
    }

    pub mod github {
        use crate::node::ClaimVar;
        use crate::node::NodeCtx;
        use crate::node::ReadVar;
        use crate::node::ReadVarBacking;
        use crate::node::SideEffect;
        use crate::node::StepCtx;
        use crate::node::VarClaimed;
        use crate::node::VarNotClaimed;
        use crate::node::WriteVar;
        use std::collections::BTreeMap;

        pub struct GhStepBuilder {
            display_name: String,
            cond: Option<ReadVar<bool>>,
            uses: String,
            with: Option<BTreeMap<String, GhParam>>,
            outputs: BTreeMap<String, Vec<WriteVar<String>>>,
            run_after: Vec<ReadVar<SideEffect>>,
            permissions: BTreeMap<GhPermission, GhPermissionValue>,
        }

        impl GhStepBuilder {
            /// Creates a new GitHub step builder, with the given display name and
            /// action to use. For example, the following code generates the following yaml:
            ///
            /// ```ignore
            /// GhStepBuilder::new("Check out repository code", "actions/checkout@v6").finish()
            /// ```
            ///
            /// ```ignore
            /// - name: Check out repository code
            ///   uses: actions/checkout@v6
            /// ```
            ///
            /// For more information on the yaml syntax for the `name` and `uses` parameters,
            /// see <https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsname>
            pub fn new(display_name: impl AsRef<str>, uses: impl AsRef<str>) -> Self {
                Self {
                    display_name: display_name.as_ref().into(),
                    cond: None,
                    uses: uses.as_ref().into(),
                    with: None,
                    outputs: BTreeMap::new(),
                    run_after: Vec::new(),
                    permissions: BTreeMap::new(),
                }
            }

            /// Adds a condition [`ReadVar<bool>`] to the step,
            /// such that the step only executes if the condition is true.
            /// This is equivalent to using an `if` conditional in the yaml.
            ///
            /// For more information on the yaml syntax for `if` conditionals, see
            /// <https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsname>
            pub fn condition(mut self, cond: ReadVar<bool>) -> Self {
                self.cond = Some(cond);
                self
            }

            /// Adds a parameter to the step, specified as a key-value pair corresponding
            /// to the param name and value. For example the following code generates the following yaml:
            ///
            /// ```rust,ignore
            /// let (client_id, write_client_id) = ctx.new_var();
            /// let (tenant_id, write_tenant_id) = ctx.new_var();
            /// let (subscription_id, write_subscription_id) = ctx.new_var();
            /// // ... insert rust step writing to each of those secrets ...
            /// GhStepBuilder::new("Azure Login", "Azure/login@v2")
            ///               .with("client-id", client_id)
            ///               .with("tenant-id", tenant_id)
            ///               .with("subscription-id", subscription_id)
            /// ```
            ///
            /// ```text
            /// - name: Azure Login
            ///   uses: Azure/login@v2
            ///   with:
            ///     client-id: ${{ env.floweyvar1 }} // Assuming the backend wrote client_id to floweyvar1
            ///     tenant-id: ${{ env.floweyvar2 }} // Assuming the backend wrote tenant-id to floweyvar2
            ///     subscription-id: ${{ env.floweyvar3 }} // Assuming the backend wrote subscription-id to floweyvar3
            /// ```
            ///
            /// For more information on the yaml syntax for the `with` parameters,
            /// see <https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepswith>
            pub fn with(mut self, k: impl AsRef<str>, v: impl Into<GhParam>) -> Self {
                self.with.get_or_insert_with(BTreeMap::new);
                if let Some(with) = &mut self.with {
                    with.insert(k.as_ref().to_string(), v.into());
                }
                self
            }

            /// Specifies an output to read from the step, specified as a key-value pair
            /// corresponding to the output name and the flowey var to write the output to.
            ///
            /// This is equivalent to writing into `v` the output of a step in the yaml using:
            /// `${{ steps.<backend-assigned-step-id>.outputs.<k> }}`
            ///
            /// For more information on step outputs, see
            /// <https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#outputs-for-composite-actions>
            pub fn output(mut self, k: impl AsRef<str>, v: WriteVar<String>) -> Self {
                self.outputs
                    .entry(k.as_ref().to_string())
                    .or_default()
                    .push(v);
                self
            }

            /// Specifies a side-effect that must be resolved before this step can run.
            pub fn run_after(mut self, side_effect: ReadVar<SideEffect>) -> Self {
                self.run_after.push(side_effect);
                self
            }

            /// Declare that this step requires a certain GITHUB_TOKEN permission in order to run.
            ///
            /// For more info about Github Actions permissions, see [`gh_grant_permissions`](crate::pipeline::PipelineJob::gh_grant_permissions) and
            /// <https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/assigning-permissions-to-jobs>
            pub fn requires_permission(
                mut self,
                perm: GhPermission,
                value: GhPermissionValue,
            ) -> Self {
                self.permissions.insert(perm, value);
                self
            }

            /// Finish building the step, emitting it to the backend and returning a side-effect.
            #[track_caller]
            pub fn finish(self, ctx: &mut NodeCtx<'_>) -> ReadVar<SideEffect> {
                let (side_effect, claim_side_effect) = ctx.new_prefixed_var("auto_se");
                ctx.backend
                    .borrow_mut()
                    .on_claimed_runtime_var(&claim_side_effect.backing_var, false);

                ctx.emit_gh_step_inner(
                    self.display_name,
                    self.cond,
                    self.uses,
                    self.with,
                    self.outputs,
                    self.run_after,
                    self.permissions,
                );

                side_effect
            }
        }

        #[derive(Clone, Debug)]
        pub enum GhParam<C = VarNotClaimed> {
            Static(String),
            FloweyVar(ReadVar<String, C>),
        }

        impl From<String> for GhParam {
            fn from(param: String) -> GhParam {
                GhParam::Static(param)
            }
        }

        impl From<&str> for GhParam {
            fn from(param: &str) -> GhParam {
                GhParam::Static(param.to_string())
            }
        }

        impl From<ReadVar<String>> for GhParam {
            fn from(param: ReadVar<String>) -> GhParam {
                GhParam::FloweyVar(param)
            }
        }

        pub type ClaimedGhParam = GhParam<VarClaimed>;

        impl ClaimVar for GhParam {
            type Claimed = ClaimedGhParam;

            fn claim(self, ctx: &mut StepCtx<'_>) -> ClaimedGhParam {
                match self {
                    GhParam::Static(s) => ClaimedGhParam::Static(s),
                    GhParam::FloweyVar(var) => match &var.backing_var {
                        ReadVarBacking::RuntimeVar { is_side_effect, .. } => {
                            assert!(!is_side_effect);
                            ClaimedGhParam::FloweyVar(var.claim(ctx))
                        }
                        ReadVarBacking::Inline(var) => ClaimedGhParam::Static(var.clone()),
                    },
                }
            }
        }

        /// The assigned permission value for a scope.
        ///
        /// For more details on how these values affect a particular scope, refer to:
        /// <https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs>
        #[derive(Debug, Clone, PartialEq, Eq, PartialOrd)]
        pub enum GhPermissionValue {
            None = 0,
            Read = 1,
            Write = 2,
        }

        /// Refers to the scope of a permission granted to the GITHUB_TOKEN
        /// for a job.
        ///
        /// For more details on each scope, refer to:
        /// <https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs>
        #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
        pub enum GhPermission {
            Actions,
            ArtifactMetadata,
            Attestations,
            Checks,
            Contents,
            Deployments,
            Discussions,
            IdToken,
            Issues,
            Packages,
            Pages,
            PullRequests,
            RepositoryProjects,
            SecurityEvents,
            Statuses,
        }
    }

    pub mod rust {
        use crate::node::ClaimedWriteVar;
        use crate::node::FlowArch;
        use crate::node::FlowBackend;
        use crate::node::FlowPlatform;
        use crate::node::ReadVarValue;
        use crate::node::RuntimeVarDb;
        use crate::shell::FloweyShell;
        use serde::Serialize;
        use serde::de::DeserializeOwned;

        pub fn new_rust_runtime_services(
            runtime_var_db: &mut dyn RuntimeVarDb,
            backend: FlowBackend,
            platform: FlowPlatform,
            arch: FlowArch,
        ) -> anyhow::Result<RustRuntimeServices<'_>> {
            Ok(RustRuntimeServices {
                runtime_var_db,
                backend,
                platform,
                arch,
                has_read_secret: false,
                sh: FloweyShell::new()?,
            })
        }

        pub struct RustRuntimeServices<'a> {
            runtime_var_db: &'a mut dyn RuntimeVarDb,
            backend: FlowBackend,
            platform: FlowPlatform,
            arch: FlowArch,
            has_read_secret: bool,
            /// A pre-initialized [`FloweyShell`] for running commands.
            ///
            /// This wraps [`xshell::Shell`] and supports transparent command
            /// wrapping. Implements [`Deref<Target = xshell::Shell>`](std::ops::Deref)
            /// so methods like `change_dir()`, `set_var()`, etc. work directly.
            pub sh: FloweyShell,
        }

        impl RustRuntimeServices<'_> {
            /// What backend the flow is being running on (e.g: locally, ADO,
            /// GitHub, etc...)
            pub fn backend(&self) -> FlowBackend {
                self.backend
            }

            /// What platform the flow is being running on (e.g: windows, linux,
            /// etc...).
            pub fn platform(&self) -> FlowPlatform {
                self.platform
            }

            /// What arch the flow is being running on (X86_64 or Aarch64)
            pub fn arch(&self) -> FlowArch {
                self.arch
            }

            /// Write a value.
            ///
            /// If this step has already read a secret value, then this will be
            /// written as a secret value, as a conservative estimate to avoid
            /// leaking secrets. Use [`write_secret`](Self::write_secret) or
            /// [`write_not_secret`](Self::write_not_secret) to override this
            /// behavior.
            pub fn write<T>(&mut self, var: ClaimedWriteVar<T>, val: &T)
            where
                T: Serialize + DeserializeOwned,
            {
                self.write_maybe_secret(var, val, self.has_read_secret)
            }

            /// Write a secret value, such as a key or token.
            ///
            /// Flowey will avoid logging this value, and if the value is
            /// converted to a CI environment variable, the CI system will be
            /// told not to print the value either.
            pub fn write_secret<T>(&mut self, var: ClaimedWriteVar<T>, val: &T)
            where
                T: Serialize + DeserializeOwned,
            {
                self.write_maybe_secret(var, val, true)
            }

            /// Write a value that is not secret, even if this step has already
            /// read secret values.
            ///
            /// Usually [`write`](Self::write) is preferred--use this only when
            /// your step reads secret values and you explicitly want to write a
            /// non-secret value.
            pub fn write_not_secret<T>(&mut self, var: ClaimedWriteVar<T>, val: &T)
            where
                T: Serialize + DeserializeOwned,
            {
                self.write_maybe_secret(var, val, false)
            }

            fn write_maybe_secret<T>(&mut self, var: ClaimedWriteVar<T>, val: &T, is_secret: bool)
            where
                T: Serialize + DeserializeOwned,
            {
                let val = if var.is_side_effect {
                    b"null".to_vec()
                } else {
                    serde_json::to_vec(val).expect("improve this error path")
                };
                self.runtime_var_db
                    .set_var(&var.backing_var, is_secret, val);
            }

            pub fn write_all<T>(
                &mut self,
                vars: impl IntoIterator<Item = ClaimedWriteVar<T>>,
                val: &T,
            ) where
                T: Serialize + DeserializeOwned,
            {
                for var in vars {
                    self.write(var, val)
                }
            }

            pub fn read<T: ReadVarValue>(&mut self, var: T) -> T::Value {
                var.read_value(self)
            }

            pub(crate) fn get_var(&mut self, var: &str, is_side_effect: bool) -> Vec<u8> {
                let (v, is_secret) = self.runtime_var_db.get_var(var);
                self.has_read_secret |= is_secret && !is_side_effect;
                v
            }

            /// DANGEROUS: Set the value of _Global_ Environment Variable (GitHub Actions only).
            ///
            /// It is up to the caller to ensure that the variable does not get
            /// unintentionally overwritten or used.
            ///
            /// This method should be used rarely and with great care!
            pub fn dangerous_gh_set_global_env_var(
                &mut self,
                var: String,
                gh_env_var: String,
            ) -> anyhow::Result<()> {
                if !matches!(self.backend, FlowBackend::Github) {
                    return Err(anyhow::anyhow!(
                        "dangerous_set_gh_env_var can only be used on GitHub Actions"
                    ));
                }

                let gh_env_file_path = std::env::var("GITHUB_ENV")?;
                let mut gh_env_file = fs_err::OpenOptions::new()
                    .append(true)
                    .open(gh_env_file_path)?;
                let gh_env_var_assignment = format!(
                    r#"{}<<EOF
{}
EOF
"#,
                    gh_env_var, var
                );
                std::io::Write::write_all(&mut gh_env_file, gh_env_var_assignment.as_bytes())?;

                Ok(())
            }
        }
    }
}

/// The base underlying implementation of all FlowNode variants.
///
/// Do not implement this directly! Use the `new_flow_node!` family of macros
/// instead!
pub trait FlowNodeBase {
    type Request: Serialize + DeserializeOwned;

    fn imports(&mut self, ctx: &mut ImportCtx<'_>);
    fn emit(
        &mut self,
        config_bytes: Vec<Box<[u8]>>,
        requests: Vec<Self::Request>,
        ctx: &mut NodeCtx<'_>,
    ) -> anyhow::Result<()>;

    /// A noop method that all human-written impls of `FlowNodeBase` are
    /// required to implement.
    ///
    /// By implementing this method, you're stating that you "know what you're
    /// doing" by having this manual impl.
    fn i_know_what_im_doing_with_this_manual_impl(&mut self);
}

pub mod erased {
    use crate::node::FlowNodeBase;
    use crate::node::NodeCtx;
    use crate::node::user_facing::*;

    pub struct ErasedNode<N: FlowNodeBase>(pub N);

    impl<N: FlowNodeBase> ErasedNode<N> {
        pub fn from_node(node: N) -> Self {
            Self(node)
        }
    }

    impl<N> FlowNodeBase for ErasedNode<N>
    where
        N: FlowNodeBase,
    {
        // FIXME: this should be using type-erased serde
        type Request = Box<[u8]>;

        fn imports(&mut self, ctx: &mut ImportCtx<'_>) {
            self.0.imports(ctx)
        }

        fn emit(
            &mut self,
            config_bytes: Vec<Box<[u8]>>,
            requests: Vec<Box<[u8]>>,
            ctx: &mut NodeCtx<'_>,
        ) -> anyhow::Result<()> {
            let mut converted_requests = Vec::new();
            for req in requests {
                converted_requests.push(serde_json::from_slice(&req)?)
            }

            self.0.emit(config_bytes, converted_requests, ctx)
        }

        fn i_know_what_im_doing_with_this_manual_impl(&mut self) {}
    }
}

/// Cheap handle to a registered [`FlowNode`]
#[derive(Clone, Copy, PartialEq, Eq, Hash)]
pub struct NodeHandle(std::any::TypeId);

impl Ord for NodeHandle {
    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
        self.modpath().cmp(other.modpath())
    }
}

impl PartialOrd for NodeHandle {
    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
        Some(self.cmp(other))
    }
}

impl std::fmt::Debug for NodeHandle {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        std::fmt::Debug::fmt(&self.try_modpath(), f)
    }
}

impl NodeHandle {
    pub const fn from_type<N: FlowNodeBase + 'static>() -> NodeHandle {
        NodeHandle(std::any::TypeId::of::<N>())
    }

    pub fn from_modpath(modpath: &str) -> NodeHandle {
        node_luts::erased_node_by_modpath().get(modpath).unwrap().0
    }

    pub fn try_from_modpath(modpath: &str) -> Option<NodeHandle> {
        node_luts::erased_node_by_modpath()
            .get(modpath)
            .map(|(s, _)| *s)
    }

    pub fn new_erased_node(&self) -> Box<dyn FlowNodeBase<Request = Box<[u8]>>> {
        let ctor = node_luts::erased_node_by_typeid().get(self).unwrap();
        ctor()
    }

    pub fn modpath(&self) -> &'static str {
        node_luts::modpath_by_node_typeid().get(self).unwrap()
    }

    pub fn try_modpath(&self) -> Option<&'static str> {
        node_luts::modpath_by_node_typeid().get(self).cloned()
    }

    /// Return a dummy NodeHandle, which will panic if `new_erased_node` is ever
    /// called on it.
    pub const fn dummy() -> NodeHandle {
        NodeHandle(std::any::TypeId::of::<()>())
    }
}

pub fn list_all_registered_nodes() -> impl Iterator<Item = NodeHandle> {
    node_luts::modpath_by_node_typeid().keys().cloned()
}

// Encapsulate these look up tables in their own module to limit the scope of
// the HashMap import.
//
// In general, using HashMap in flowey is a recipe for disaster, given that
// iterating through the hash-map will result in non-deterministic orderings,
// which can cause annoying ordering churn.
//
// That said, in this case, it's OK since the code using these LUTs won't ever
// iterate through the map.
//
// Why is the HashMap even necessary vs. a BTreeMap?
//
// Well... NodeHandle's `Ord` impl does a `modpath` comparison instead of a
// TypeId comparison, since TypeId will vary between compilations.
mod node_luts {
    use super::FlowNodeBase;
    use super::NodeHandle;
    use std::collections::HashMap;
    use std::sync::OnceLock;

    pub(super) fn modpath_by_node_typeid() -> &'static HashMap<NodeHandle, &'static str> {
        static TYPEID_TO_MODPATH: OnceLock<HashMap<NodeHandle, &'static str>> = OnceLock::new();

        TYPEID_TO_MODPATH.get_or_init(|| {
            let mut lookup = HashMap::new();
            for crate::node::private::FlowNodeMeta {
                module_path,
                ctor: _,
                typeid,
            } in crate::node::private::FLOW_NODES
            {
                let existing = lookup.insert(
                    NodeHandle(*typeid),
                    module_path
                        .strip_suffix("::_only_one_call_to_flowey_node_per_module")
                        .unwrap(),
                );
                // if this were to fire for an array where the key is a TypeId...
                // something has gone _terribly_ wrong
                assert!(existing.is_none())
            }

            lookup
        })
    }

    pub(super) fn erased_node_by_typeid()
    -> &'static HashMap<NodeHandle, fn() -> Box<dyn FlowNodeBase<Request = Box<[u8]>>>> {
        static LOOKUP: OnceLock<
            HashMap<NodeHandle, fn() -> Box<dyn FlowNodeBase<Request = Box<[u8]>>>>,
        > = OnceLock::new();

        LOOKUP.get_or_init(|| {
            let mut lookup = HashMap::new();
            for crate::node::private::FlowNodeMeta {
                module_path: _,
                ctor,
                typeid,
            } in crate::node::private::FLOW_NODES
            {
                let existing = lookup.insert(NodeHandle(*typeid), *ctor);
                // if this were to fire for an array where the key is a TypeId...
                // something has gone _terribly_ wrong
                assert!(existing.is_none())
            }

            lookup
        })
    }

    pub(super) fn erased_node_by_modpath() -> &'static HashMap<
        &'static str,
        (
            NodeHandle,
            fn() -> Box<dyn FlowNodeBase<Request = Box<[u8]>>>,
        ),
    > {
        static MODPATH_LOOKUP: OnceLock<
            HashMap<
                &'static str,
                (
                    NodeHandle,
                    fn() -> Box<dyn FlowNodeBase<Request = Box<[u8]>>>,
                ),
            >,
        > = OnceLock::new();

        MODPATH_LOOKUP.get_or_init(|| {
            let mut lookup = HashMap::new();
            for crate::node::private::FlowNodeMeta { module_path, ctor, typeid } in crate::node::private::FLOW_NODES {
                let existing = lookup.insert(module_path.strip_suffix("::_only_one_call_to_flowey_node_per_module").unwrap(), (NodeHandle(*typeid), *ctor));
                if existing.is_some() {
                    panic!("conflicting node registrations at {module_path}! please ensure there is a single node per module!")
                }
            }
            lookup
        })
    }
}

#[doc(hidden)]
pub mod private {
    pub use linkme;

    pub struct FlowNodeMeta {
        pub module_path: &'static str,
        pub ctor: fn() -> Box<dyn super::FlowNodeBase<Request = Box<[u8]>>>,
        pub typeid: std::any::TypeId,
    }

    #[linkme::distributed_slice]
    pub static FLOW_NODES: [FlowNodeMeta] = [..];

    // UNSAFETY: linkme uses manual link sections, which are unsafe.
    #[expect(unsafe_code)]
    #[linkme::distributed_slice(FLOW_NODES)]
    static DUMMY_FLOW_NODE: FlowNodeMeta = FlowNodeMeta {
        module_path: "<dummy>::_only_one_call_to_flowey_node_per_module",
        ctor: || unreachable!(),
        typeid: std::any::TypeId::of::<()>(),
    };
}

#[doc(hidden)]
#[macro_export]
macro_rules! new_flow_node_base {
    (struct Node) => {
        /// (see module-level docs)
        #[non_exhaustive]
        pub struct Node;

        mod _only_one_call_to_flowey_node_per_module {
            const _: () = {
                use $crate::node::private::linkme;

                fn new_erased() -> Box<dyn $crate::node::FlowNodeBase<Request = Box<[u8]>>> {
                    Box::new($crate::node::erased::ErasedNode(super::Node))
                }

                #[linkme::distributed_slice($crate::node::private::FLOW_NODES)]
                #[linkme(crate = linkme)]
                static FLOW_NODE: $crate::node::private::FlowNodeMeta =
                    $crate::node::private::FlowNodeMeta {
                        module_path: module_path!(),
                        ctor: new_erased,
                        typeid: std::any::TypeId::of::<super::Node>(),
                    };
            };
        }
    };
}

/// A reusable unit of automation logic in flowey.
///
/// FlowNodes process requests, emit steps, and can depend on other nodes. They are
/// the building blocks for creating complex automation workflows.
///
/// # The Node/Request Pattern
///
/// Every node has an associated **Request** type that defines what the node can do.
/// Nodes receive a vector of requests and process them together, allowing for
/// aggregation and conflict resolution.
///
/// # Example: Basic FlowNode Implementation
///
/// ```rust,ignore
/// use flowey_core::node::*;
///
/// // Define the node
/// new_flow_node!(struct Node);
///
/// // Define requests using the flowey_request! macro
/// flowey_request! {
///     pub enum Request {
///         InstallRust(String),                    // Install specific version
///         EnsureInstalled(WriteVar<SideEffect>),  // Ensure it's installed
///         GetCargoHome(WriteVar<PathBuf>),        // Get CARGO_HOME path
///     }
/// }
///
/// impl FlowNode for Node {
///     type Request = Request;
///
///     fn imports(ctx: &mut ImportCtx<'_>) {
///         // Declare node dependencies
///         ctx.import::<other_node::Node>();
///     }
///
///     fn emit(requests: Vec<Self::Request>, ctx: &mut NodeCtx<'_>) -> anyhow::Result<()> {
///         // 1. Aggregate and validate requests
///         let mut version = None;
///         let mut ensure_installed = Vec::new();
///         let mut get_cargo_home = Vec::new();
///
///         for req in requests {
///             match req {
///                 Request::InstallRust(v) => {
///                     same_across_all_reqs("version", &mut version, v)?;
///                 }
///                 Request::EnsureInstalled(var) => ensure_installed.push(var),
///                 Request::GetCargoHome(var) => get_cargo_home.push(var),
///             }
///         }
///
///         let version = version.ok_or(anyhow::anyhow!("Version not specified"))?;
///
///         // 2. Emit steps to do the work
///         ctx.emit_rust_step("install rust", |ctx| {
///             let ensure_installed = ensure_installed.claim(ctx);
///             let get_cargo_home = get_cargo_home.claim(ctx);
///             move |rt| {
///                 // Install rust with the specified version
///                 // Write to all the output variables
///                 for var in ensure_installed {
///                     rt.write(var, &());
///                 }
///                 for var in get_cargo_home {
///                     rt.write(var, &PathBuf::from("/path/to/cargo"));
///                 }
///                 Ok(())
///             }
///         });
///
///         Ok(())
///     }
/// }
/// ```
///
/// # When to Use FlowNode vs SimpleFlowNode
///
/// **Use `FlowNode`** when you need to:
/// - Aggregate multiple requests and process them together
/// - Resolve conflicts between requests
/// - Perform complex request validation
///
/// **Use [`SimpleFlowNode`]** when:
/// - Each request can be processed independently
/// - No aggregation logic is needed
pub trait FlowNode {
    /// The request type that defines what operations this node can perform.
    ///
    /// Use the [`crate::flowey_request!`] macro to define this type.
    type Request: Serialize + DeserializeOwned;

    /// A list of nodes that this node is capable of taking a dependency on.
    ///
    /// Attempting to take a dep on a node that wasn't imported via this method
    /// will result in an error during flow resolution time.
    ///
    /// * * *
    ///
    /// To put it bluntly: This is boilerplate.
    ///
    /// We (the flowey devs) are thinking about ways to avoid requiring this
    /// method, but do not have a good solution at this time.
    fn imports(ctx: &mut ImportCtx<'_>);

    /// Given a set of incoming `requests`, emit various steps to run, set
    /// various dependencies, etc...
    fn emit(requests: Vec<Self::Request>, ctx: &mut NodeCtx<'_>) -> anyhow::Result<()>;
}

#[macro_export]
macro_rules! new_flow_node {
    (struct Node) => {
        $crate::new_flow_node_base!(struct Node);

        impl $crate::node::FlowNodeBase for Node
        where
            Node: FlowNode,
        {
            type Request = <Node as FlowNode>::Request;

            fn imports(&mut self, dep: &mut $crate::node::ImportCtx<'_>) {
                <Node as FlowNode>::imports(dep)
            }

            fn emit(
                &mut self,
                _config_bytes: Vec<Box<[u8]>>,
                requests: Vec<Self::Request>,
                ctx: &mut $crate::node::NodeCtx<'_>,
            ) -> anyhow::Result<()> {
                <Node as FlowNode>::emit(requests, ctx)
            }

            fn i_know_what_im_doing_with_this_manual_impl(&mut self) {}
        }
    };
}

/// A helper trait to streamline implementing [`FlowNode`] instances that only
/// ever operate on a single request at a time.
///
/// In essence, [`SimpleFlowNode`] handles the boilerplate (and rightward-drift)
/// of manually writing:
///
/// ```ignore
/// impl FlowNode for Node {
///     fn imports(dep: &mut ImportCtx<'_>) { ... }
///     fn emit(requests: Vec<Self::Request>, ctx: &mut NodeCtx<'_>) {
///         for req in requests {
///             Node::process_request(req, ctx)
///         }
///     }
/// }
/// ```
///
/// Nodes which accept a `struct Request` often fall into this pattern, whereas
/// nodes which accept a `enum Request` typically require additional logic to
/// aggregate / resolve incoming requests.
pub trait SimpleFlowNode {
    type Request: Serialize + DeserializeOwned;

    /// A list of nodes that this node is capable of taking a dependency on.
    ///
    /// Attempting to take a dep on a node that wasn't imported via this method
    /// will result in an error during flow resolution time.
    ///
    /// * * *
    ///
    /// To put it bluntly: This is boilerplate.
    ///
    /// We (the flowey devs) are thinking about ways to avoid requiring this
    /// method, but do not have a good solution at this time.
    fn imports(ctx: &mut ImportCtx<'_>);

    /// Process a single incoming `Self::Request`
    fn process_request(request: Self::Request, ctx: &mut NodeCtx<'_>) -> anyhow::Result<()>;
}

#[macro_export]
macro_rules! new_simple_flow_node {
    (struct Node) => {
        $crate::new_flow_node_base!(struct Node);

        impl $crate::node::FlowNodeBase for Node
        where
            Node: $crate::node::SimpleFlowNode,
        {
            type Request = <Node as $crate::node::SimpleFlowNode>::Request;

            fn imports(&mut self, dep: &mut $crate::node::ImportCtx<'_>) {
                <Node as $crate::node::SimpleFlowNode>::imports(dep)
            }

            fn emit(
                &mut self,
                _config_bytes: Vec<Box<[u8]>>,
                requests: Vec<Self::Request>,
                ctx: &mut $crate::node::NodeCtx<'_>,
            ) -> anyhow::Result<()> {
                for req in requests {
                    <Node as $crate::node::SimpleFlowNode>::process_request(req, ctx)?
                }

                Ok(())
            }

            fn i_know_what_im_doing_with_this_manual_impl(&mut self) {}
        }
    };
}

/// A [`FlowNode`] variant that receives a typed, pre-merged config alongside
/// its requests.
///
/// Use this when a node has "config" values (e.g., version strings, feature
/// flags) that must agree across all callers AND are needed to emit outgoing
/// requests or steps.
///
/// The framework merges config from all callers (validating equality) and
/// delivers the finalized `Config` to `emit()`. The node never sees raw
/// config requests — they are handled by the infrastructure.
///
/// # Example
///
/// ```rust,ignore
/// flowey_config! {
///     pub struct Config {
///         pub version: Option<String>,
///     }
/// }
///
/// flowey_request! {
///     pub enum Request {
///         GetAzCopy(WriteVar<PathBuf>),
///     }
/// }
///
/// new_flow_node_with_config!(struct Node);
///
/// impl FlowNodeWithConfig for Node {
///     type Request = Request;
///     type Config = Config;
///
///     fn imports(ctx: &mut ImportCtx<'_>) { /* ... */ }
///
///     fn emit(
///         config: Config,
///         requests: Vec<Self::Request>,
///         ctx: &mut NodeCtx<'_>,
///     ) -> anyhow::Result<()> {
///         let version = config.version
///             .ok_or(anyhow::anyhow!("missing config: version"))?;
///         // ...
///         Ok(())
///     }
/// }
/// ```
pub trait FlowNodeWithConfig {
    /// The request type (action requests only — no config variants).
    type Request: Serialize + DeserializeOwned;

    /// The config type generated by [`flowey_config!`](crate::flowey_config).
    ///
    /// Scalar fields are typically wrapped in `Option<T>`, and the node decides which
    /// options are treated as required vs optional. Configs may also include
    /// non-`Option` mergeable fields (for example, maps) that are combined according
    /// to the [`ConfigMerge`] implementation.
    type Config: ConfigMerge;

    /// Declare node dependencies.
    fn imports(ctx: &mut ImportCtx<'_>);

    /// Process requests with the merged config.
    fn emit(
        config: Self::Config,
        requests: Vec<Self::Request>,
        ctx: &mut NodeCtx<'_>,
    ) -> anyhow::Result<()>;
}

#[macro_export]
macro_rules! new_flow_node_with_config {
    (struct Node) => {
        $crate::new_flow_node_base!(struct Node);

        impl $crate::node::FlowNodeBase for Node
        where
            Node: $crate::node::FlowNodeWithConfig,
        {
            type Request = <Node as $crate::node::FlowNodeWithConfig>::Request;

            fn imports(&mut self, dep: &mut $crate::node::ImportCtx<'_>) {
                <Node as $crate::node::FlowNodeWithConfig>::imports(dep)
            }

            fn emit(
                &mut self,
                config_bytes: Vec<Box<[u8]>>,
                requests: Vec<Self::Request>,
                ctx: &mut $crate::node::NodeCtx<'_>,
            ) -> anyhow::Result<()> {
                use $crate::node::ConfigMerge;

                type C = <Node as $crate::node::FlowNodeWithConfig>::Config;

                let mut merged = <C as Default>::default();
                for bytes in config_bytes {
                    let partial: C = serde_json::from_slice(&bytes)?;
                    merged.merge(partial)?;
                }

                <Node as $crate::node::FlowNodeWithConfig>::emit(merged, requests, ctx)
            }

            fn i_know_what_im_doing_with_this_manual_impl(&mut self) {}
        }
    };
}

/// A "glue" trait which improves [`NodeCtx::req`] ergonomics, by tying a
/// particular `Request` type to its corresponding [`FlowNode`].
///
/// This trait should be autogenerated via [`flowey_request!`] - do not try to
/// implement it manually!
///
/// [`flowey_request!`]: crate::flowey_request
pub trait IntoRequest {
    type Node: FlowNodeBase;
    fn into_request(self) -> <Self::Node as FlowNodeBase>::Request;

    /// By implementing this method manually, you're indicating that you know what you're
    /// doing,
    #[doc(hidden)]
    #[expect(nonstandard_style)]
    fn do_not_manually_impl_this_trait__use_the_flowey_request_macro_instead(&mut self);
}

/// A "glue" trait for routing config to the correct node, analogous to
/// [`IntoRequest`].
///
/// This trait should be autogenerated via the `flowey_config!` macro - do not
/// try to implement it manually!
pub trait IntoConfig: Serialize {
    type Node: FlowNodeBase;

    /// By implementing this method manually, you're indicating that you know what you're
    /// doing,
    #[doc(hidden)]
    #[expect(nonstandard_style)]
    fn do_not_manually_impl_this_trait__use_the_flowey_config_macro_instead(&mut self);
}

/// Trait for merging config values. Implemented by the `flowey_config!`
/// macro on the generated `Config` type.
pub trait ConfigMerge: Serialize + DeserializeOwned + Default {
    /// Merge another config into this one. Fields that are already set
    /// must agree with the incoming values.
    fn merge(&mut self, other: Self) -> anyhow::Result<()>;
}

/// Trait for merging a single config field. The `flowey_config!` macro calls
/// `ConfigField::merge_field` on each field during config merging.
///
/// Implemented for:
/// - `Option<T>`: first setter wins, subsequent must agree (`PartialEq`)
/// - `BTreeMap<K, V>`: per-key merge, each key's value must agree
pub trait ConfigField {
    fn merge_field(&mut self, field_name: &str, other: Self) -> anyhow::Result<()>;
}

impl<T: PartialEq> ConfigField for Option<T> {
    fn merge_field(&mut self, field_name: &str, other: Self) -> anyhow::Result<()> {
        if let Some(new) = other {
            match self {
                None => *self = Some(new),
                Some(old) if *old == new => {}
                Some(_) => {
                    anyhow::bail!("config field `{field_name}` mismatch");
                }
            }
        }
        Ok(())
    }
}

impl<K: Ord + std::fmt::Debug, V: PartialEq> ConfigField for BTreeMap<K, V> {
    fn merge_field(&mut self, field_name: &str, other: Self) -> anyhow::Result<()> {
        for (k, v) in other {
            use std::collections::btree_map::Entry;
            match self.entry(k) {
                Entry::Vacant(e) => {
                    e.insert(v);
                }
                Entry::Occupied(e) if *e.get() == v => {}
                Entry::Occupied(e) => {
                    anyhow::bail!("config field `{field_name}` mismatch for key {:?}", e.key(),);
                }
            }
        }
        Ok(())
    }
}

#[doc(hidden)]
#[macro_export]
macro_rules! __flowey_request_inner {
    //
    // @emit_struct: emit structs for each variant of the request enum
    //
    (@emit_struct [$req:ident]
        $(#[$a:meta])*
        $variant:ident($($tt:tt)*),
        $($rest:tt)*
    ) => {
        $(#[$a])*
        #[derive($crate::reexports::Serialize, $crate::reexports::Deserialize)]
        pub struct $variant($($tt)*);

        impl IntoRequest for $variant {
            type Node = Node;
            fn into_request(self) -> $req {
                $req::$variant(self)
            }
            fn do_not_manually_impl_this_trait__use_the_flowey_request_macro_instead(&mut self) {}
        }

        $crate::__flowey_request_inner!(@emit_struct [$req] $($rest)*);
    };
    (@emit_struct [$req:ident]
        $(#[$a:meta])*
        $variant:ident { $($tt:tt)* },
        $($rest:tt)*
    ) => {
        $(#[$a])*
        #[derive($crate::reexports::Serialize, $crate::reexports::Deserialize)]
        pub struct $variant {
            $($tt)*
        }

        impl IntoRequest for $variant {
            type Node = Node;
            fn into_request(self) -> $req {
                $req::$variant(self)
            }
            fn do_not_manually_impl_this_trait__use_the_flowey_request_macro_instead(&mut self) {}
        }

        $crate::__flowey_request_inner!(@emit_struct [$req] $($rest)*);
    };
    (@emit_struct [$req:ident]
        $(#[$a:meta])*
        $variant:ident,
        $($rest:tt)*
    ) => {
        $(#[$a])*
        #[derive(Serialize, Deserialize)]
        pub struct $variant;

        impl IntoRequest for $variant {
            type Node = Node;
            fn into_request(self) -> $req {
                $req::$variant(self)
            }
            fn do_not_manually_impl_this_trait__use_the_flowey_request_macro_instead(&mut self) {}
        }

        $crate::__flowey_request_inner!(@emit_struct [$req] $($rest)*);
    };
    (@emit_struct [$req:ident]
    ) => {};

    //
    // @emit_req_enum: build up root request enum
    //
    (@emit_req_enum [$req:ident($($root_a:meta,)*), $($prev:ident[$($prev_a:meta,)*])*]
        $(#[$a:meta])*
        $variant:ident($($tt:tt)*),
        $($rest:tt)*
    ) => {
        $crate::__flowey_request_inner!(@emit_req_enum [$req($($root_a,)*), $($prev[$($prev_a,)*])* $variant[$($a,)*]] $($rest)*);
    };
    (@emit_req_enum [$req:ident($($root_a:meta,)*), $($prev:ident[$($prev_a:meta,)*])*]
        $(#[$a:meta])*
        $variant:ident { $($tt:tt)* },
        $($rest:tt)*
    ) => {
        $crate::__flowey_request_inner!(@emit_req_enum [$req($($root_a,)*), $($prev[$($prev_a,)*])* $variant[$($a,)*]] $($rest)*);
    };
    (@emit_req_enum [$req:ident($($root_a:meta,)*), $($prev:ident[$($prev_a:meta,)*])*]
        $(#[$a:meta])*
        $variant:ident,
        $($rest:tt)*
    ) => {
        $crate::__flowey_request_inner!(@emit_req_enum [$req($($root_a,)*), $($prev[$($prev_a,)*])* $variant[$($a,)*]] $($rest)*);
    };
    (@emit_req_enum [$req:ident($($root_a:meta,)*), $($prev:ident[$($prev_a:meta,)*])*]
    ) => {
        #[derive(Serialize, Deserialize)]
        pub enum $req {$(
            $(#[$prev_a])*
            $prev(self::req::$prev),
        )*}

        impl IntoRequest for $req {
            type Node = Node;
            fn into_request(self) -> $req {
                self
            }
            fn do_not_manually_impl_this_trait__use_the_flowey_request_macro_instead(&mut self) {}
        }
    };
}

/// Declare a new `Request` type for the current `Node`.
///
/// ## `struct` and `enum` Requests
///
/// When wrapping a vanilla Rust `struct` and `enum` declaration, this macro
/// simply derives [`Serialize`], [`Deserialize`], and [`IntoRequest`] for the
/// type, and does nothing else.
///
/// ## `enum_struct` Requests
///
/// This macro also supports a special kind of `enum_struct` derive, which
/// allows declaring a Request enum where each variant is split off into its own
/// separate (named) `struct`.
///
/// e.g:
///
/// ```ignore
/// flowey_request! {
///     pub enum_struct Foo {
///         Bar,
///         Baz(pub usize),
///         Qux(pub String),
///     }
/// }
/// ```
///
/// will be expanded into:
///
/// ```ignore
/// #[derive(Serialize, Deserialize)]
/// pub enum Foo {
///    Bar(req::Bar),
///    Baz(req::Baz),
///    Qux(req::Qux),
/// }
///
/// pud mod req {
///     #[derive(Serialize, Deserialize)]
///     pub struct Bar;
///
///     #[derive(Serialize, Deserialize)]
///     pub struct Baz(pub usize);
///
///     #[derive(Serialize, Deserialize)]
///     pub struct Qux(pub String);
/// }
/// ```
#[macro_export]
macro_rules! flowey_request {
    (
        $(#[$root_a:meta])*
        pub enum_struct $req:ident {
            $($tt:tt)*
        }
    ) => {
        $crate::__flowey_request_inner!(@emit_req_enum [$req($($root_a,)*),] $($tt)*);
        pub mod req {
            use super::*;
            $crate::__flowey_request_inner!(@emit_struct [$req] $($tt)*);
        }
    };

    (
        $(#[$a:meta])*
        pub enum $req:ident {
            $($tt:tt)*
        }
    ) => {
        $(#[$a])*
        #[derive($crate::reexports::Serialize, $crate::reexports::Deserialize)]
        pub enum $req {
            $($tt)*
        }

        impl $crate::node::IntoRequest for $req {
            type Node = Node;
            fn into_request(self) -> $req {
                self
            }
            fn do_not_manually_impl_this_trait__use_the_flowey_request_macro_instead(&mut self) {}
        }
    };

    (
        $(#[$a:meta])*
        pub struct $req:ident {
            $($tt:tt)*
        }
    ) => {
        $(#[$a])*
        #[derive($crate::reexports::Serialize, $crate::reexports::Deserialize)]
        pub struct $req {
            $($tt)*
        }

        impl $crate::node::IntoRequest for $req {
            type Node = Node;
            fn into_request(self) -> $req {
                self
            }
            fn do_not_manually_impl_this_trait__use_the_flowey_request_macro_instead(&mut self) {}
        }
    };

    (
        $(#[$a:meta])*
        pub struct $req:ident($($tt:tt)*);
    ) => {
        $(#[$a])*
        #[derive($crate::reexports::Serialize, $crate::reexports::Deserialize)]
        pub struct $req($($tt)*);

        impl $crate::node::IntoRequest for $req {
            type Node = Node;
            fn into_request(self) -> $req {
                self
            }
            fn do_not_manually_impl_this_trait__use_the_flowey_request_macro_instead(&mut self) {}
        }
    };
}

/// Declare a config struct for a flowey node.
///
/// Fields should be `Option<T>` or `BTreeMap<K, V>`:
///
/// - `Option<T>` — callers set only the fields they care about. The first
///   caller to set a field wins; subsequent callers must agree on the same
///   value or merging will fail. The node decides which fields are required
///   vs optional in its `emit()`.
///
/// - `BTreeMap<K, V>` — callers contribute entries independently. Each key
///   may only be set once; if two callers set the same key, the values must
///   agree. Useful for per-variant or per-target configuration maps.
///
/// Generates:
/// - The `Config` struct with `Serialize`, `Deserialize`, `Default` derives
/// - `ConfigMerge` impl with field-level equality merging
/// - `IntoConfig` impl tying it to `Node`
///
/// # Example
///
/// ```rust,ignore
/// flowey_config! {
///     pub struct Config {
///         pub version: Option<String>,
///         pub auto_install: Option<bool>,
///         pub target_flags: BTreeMap<String, String>,
///     }
/// }
/// ```
///
/// Callers send config via:
/// ```rust,ignore
/// ctx.config(node::Config {
///     version: Some("10.31.0".into()),
///     ..Default::default()
/// });
/// ```
#[macro_export]
macro_rules! flowey_config {
    (
        $(#[$meta:meta])*
        pub struct $Config:ident {
            $(
                $(#[$field_meta:meta])*
                pub $field:ident : $ty:ty
            ),* $(,)?
        }
    ) => {
        $(#[$meta])*
        #[derive(
            $crate::reexports::Serialize,
            $crate::reexports::Deserialize,
            Default,
        )]
        pub struct $Config {
            $(
                $(#[$field_meta])*
                pub $field: $ty,
            )*
        }

        impl $crate::node::ConfigMerge for $Config {
            fn merge(&mut self, other: Self) -> anyhow::Result<()> {
                $(
                    $crate::node::ConfigField::merge_field(
                        &mut self.$field,
                        stringify!($field),
                        other.$field,
                    )?;
                )*
                Ok(())
            }
        }

        impl $crate::node::IntoConfig for $Config {
            type Node = Node;

            fn do_not_manually_impl_this_trait__use_the_flowey_config_macro_instead(&mut self) {}
        }
    };
}

/// Construct a command to run via the flowey shell.
///
/// This is a wrapper around [`xshell::cmd!`] that returns a [`FloweyCmd`]
/// instead of a raw [`xshell::Cmd`]. The [`FloweyCmd`] applies any
/// [`CommandWrapperKind`] configured on the shell at execution time, making it
/// possible to transparently wrap commands (e.g. in `nix-shell --pure`)
/// without touching every callsite.
///
/// [`FloweyCmd`]: crate::shell::FloweyCmd
/// [`CommandWrapperKind`]: crate::shell::CommandWrapperKind
///
/// # Example
///
/// ```ignore
/// flowey::shell_cmd!(rt, "cargo build --release").run()?;
/// ```
#[macro_export]
macro_rules! shell_cmd {
    ($rt:expr, $cmd:literal) => {{
        let flowey_sh = &$rt.sh;
        #[expect(clippy::disallowed_macros)]
        flowey_sh.wrap($crate::reexports::xshell::cmd!(flowey_sh.xshell(), $cmd))
    }};
}