majordomus_cli/capability/builtin/

environment.rs

//! The `environment` module: what this checkout is, as a capability.
//!
//! One capability, one handler, and every surface a projection of it — the MCP tool and
//! resource, the HTTP route, the OpenAPI operation, the Cockpit page and the command line
//! all answer with the value [`crate::environment::resolve()`] built. The direnv banner is
//! the same value rendered for a terminal.
//!
//! The handler runs inside a process that already holds the index, so it resolves in full:
//! nothing here pays the index build, because whoever called it had already paid it. The
//! fast, cached resolution belongs to the command line, which may be starting cold on a
//! shell prompt.

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

use crate::capability::benchmark::{BenchmarkCases, CaseContext, NamedCase};
use crate::capability::handler::{CapabilityError, Context};
use crate::capability::model::{CachePolicy, Exposure, McpExposure, McpResource, Stability};
use crate::capability::module::ModuleDescriptor;
use crate::environment::preflight::{self, Preflight, Probe, RulesTally};
use crate::environment::{
    resolve, EnvironmentQuery, FieldSource, Inputs, RepositoryEnvironment, Resolution,
};
use crate::repository::Repository;
use crate::{capability, module};

use super::{get, mcp};

/// The URI under which the environment is read as an MCP resource.
pub const ENVIRONMENT_URI: &str = "majordomus://environment";

/// The URI under which the preflight is read as an MCP resource.
pub const PREFLIGHT_URI: &str = "majordomus://environment/preflight";

/// What a served preflight may cost.
///
/// ```
/// use majordomus_cli::capability::builtin::environment::PreflightInput;
/// let input: PreflightInput = serde_json::from_str("{}").unwrap();
/// assert!(!input.probe, "a served request asks no other process by default");
/// ```
#[derive(Debug, Default, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct PreflightInput {
    /// Ask the loopback address a server of this checkout published, and its peer board.
    /// Off by default: a served request answers from what this process can see, and when
    /// this process holds the checkout's lease that is itself the evidence.
    #[serde(default)]
    pub probe: bool,
}

impl BenchmarkCases for PreflightInput {
    fn benchmark_cases(_: &CaseContext<'_>) -> Vec<NamedCase<Self>> {
        vec![NamedCase::new("sealed", PreflightInput { probe: false })]
    }
}

fn preflight(ctx: &Context, input: PreflightInput) -> Result<Preflight, CapabilityError> {
    let root = std::path::Path::new(&ctx.index.repository.root);
    let repository = Repository::open(root).map_err(|e| {
        CapabilityError::Internal(format!("the repository could not be re-read: {e}"))
    })?;
    // Located here rather than carried on the context, so that the provider projections are
    // compared against their templates exactly as the command line compares them; without
    // it they would read `unknown` on this surface and `verified` on that one.
    let share = crate::share::Share::locate(None, root).ok();
    let environment = resolve(
        &Inputs {
            repository: &repository,
            share: share.as_ref(),
            index: Some(&ctx.index),
            registry: Some(&ctx.registry),
            policy: None,
        },
        &EnvironmentQuery {
            resolution: Resolution::Full,
            probe_services: false,
            use_cache: false,
            write_cache: false,
        },
    );
    let tally = RulesTally::of(&rules_report(ctx, root));
    let policy = crate::policy::LoadedPolicy::load(&repository).map_err(|e| e.to_string());
    let mut observations = preflight::observe(
        root,
        &environment,
        policy.as_ref().map_err(Clone::clone),
        Some(tally),
        // never the cache: a served request writes nothing to the checkout it serves
        Probe {
            cache: false,
            ..if input.probe {
                Probe::asked()
            } else {
                Probe::sealed()
            }
        },
    );
    // The process that holds the lease holds the board: read it here rather than asking
    // this process over its own socket, and the command line — which asks over the socket —
    // reads the same peers.
    if observations.server.this_process {
        observations.peers = Ok(preflight::PeersObservation::of(&ctx.peers.list()));
    }
    Ok(preflight::derive(&observations))
}

/// The rule corpus counted against the ledger, as `rules.report` answers it: asked through
/// the executor, so that a preflight and every other reader of the same checkout state share
/// one computation of the most expensive thing a preflight reads. A ledger that cannot be
/// read is counted as an empty one, as the preflight always counted it — `rules.report`
/// refuses that ledger, so the refusal is the one case computed here.
fn rules_report(ctx: &Context, root: &std::path::Path) -> crate::rules::RulesReport {
    ctx.execute("rules.report", serde_json::json!({}))
        .ok()
        .and_then(|v| serde_json::from_value(v).ok())
        .unwrap_or_else(|| {
            let ledger = crate::evidence::Ledger::load(root)
                .unwrap_or_else(|_| crate::evidence::Ledger::empty());
            crate::rules::report(&ctx.index, &ledger)
        })
}

/// What to include in the snapshot.
#[derive(Debug, Default, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct EnvironmentInput {
    /// Contact the local address a running server published, to say whether it answers.
    /// Off by default: a served request should not open a socket to another server on
    /// behalf of its caller, and the caller usually is that server.
    #[serde(default)]
    pub probe_services: bool,
}

impl BenchmarkCases for EnvironmentInput {
    fn benchmark_cases(_: &CaseContext<'_>) -> Vec<NamedCase<Self>> {
        vec![NamedCase::new(
            "default",
            EnvironmentInput {
                probe_services: false,
            },
        )]
    }
}

/// Which field's provenance to explain.
#[derive(Debug, Default, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ExplainInput {
    /// The field in dotted form (`services.url`, `capabilities.objects`); every field when
    /// absent.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub field: Option<String>,
}

impl BenchmarkCases for ExplainInput {
    fn benchmark_cases(_: &CaseContext<'_>) -> Vec<NamedCase<Self>> {
        vec![
            NamedCase::new("all", ExplainInput { field: None }),
            NamedCase::new(
                "one-field",
                ExplainInput {
                    field: Some("project.version".into()),
                },
            ),
        ]
    }
}

/// Where the values of one snapshot came from.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct EnvironmentProvenance {
    /// How the snapshot behind these entries was resolved.
    pub resolution: Resolution,
    /// One entry per field, in the order the resolver produced them.
    pub fields: Vec<FieldSource>,
}

fn snapshot(
    ctx: &Context,
    input: EnvironmentInput,
) -> Result<RepositoryEnvironment, CapabilityError> {
    let root = std::path::Path::new(&ctx.index.repository.root);
    let repository = Repository::open(root).map_err(|e| {
        CapabilityError::Internal(format!("the repository could not be re-read: {e}"))
    })?;
    // The share directory is not carried on the context; without it the provider
    // projections are still listed from the policy, and their state is `unknown` rather
    // than guessed. `env status` on the command line has it and reports the state.
    Ok(resolve(
        &Inputs {
            repository: &repository,
            share: None,
            index: Some(&ctx.index),
            registry: Some(&ctx.registry),
            policy: None,
        },
        &EnvironmentQuery {
            resolution: Resolution::Full,
            probe_services: input.probe_services,
            use_cache: false,
            // A served request writes nothing: the cache belongs to the checkout's own
            // command line, and a request that wrote it would be a request with a side
            // effect on the repository.
            write_cache: false,
        },
    ))
}

fn explain(ctx: &Context, input: ExplainInput) -> Result<EnvironmentProvenance, CapabilityError> {
    let environment = snapshot(
        ctx,
        EnvironmentInput {
            probe_services: false,
        },
    )?;
    let fields = match &input.field {
        None => environment.provenance.clone(),
        Some(field) => {
            let found: Vec<FieldSource> = environment
                .provenance
                .iter()
                .filter(|p| p.field == *field || p.field.starts_with(&format!("{field}.")))
                .cloned()
                .collect();
            if found.is_empty() {
                return Err(CapabilityError::NotFound(format!(
                    "no field named '{field}'; `environment.explain` with no field lists every one"
                )));
            }
            found
        }
    };
    Ok(EnvironmentProvenance {
        resolution: environment.resolution,
        fields,
    })
}

/// The module.
pub fn module() -> ModuleDescriptor {
    module! {
        id: "environment",
        title: "Repository environment",
        description: "What this checkout is right now: the project and its version, the repository and its layer, version control, the toolchains it declares, what the layer holds, the workflows a person can run, the provider projections and the local services — one typed snapshot, with a provenance entry for every value in it. The direnv banner, the Cockpit's overview and this route are renderings of the same value.",
        stability: Stability::BehaviorallyVerified,
        capabilities: [
            capability! {
                id: "environment.status",
                title: "The repository environment",
                description: "One snapshot of this checkout: project identity, repository identity, version control, declared toolchains, what the layer holds counted per kind, the workflows the runner describes, the provider projections against the policy that renders them, and the local services with the address a running server published. Every value carries where it came from.",
                input: EnvironmentInput,
                output: RepositoryEnvironment,
                stability: Stability::BehaviorallyVerified,
                exposure: Exposure {
                    mcp: Some(McpExposure {
                        tool: Some("majordomus_environment".into()),
                        resource: Some(McpResource { uri: ENVIRONMENT_URI.into(), name: "environment".into() }),
                    }),
                    http: get("/api/v1/environment"),
                    cli: None,
                },
                tags: ["environment", "repository", "introspection"],
                // Not cached, and deliberately so. This answer is a snapshot of *now*:
                // it runs `git status`, reads the lease, and stamps the moment it was
                // taken into `generated_at`, so two calls a second apart legitimately
                // differ. The executor holds that a cached capability answers the same
                // value from the handler, from a cold cache and from a warm one
                // (`tests/executor.rs`, `docs/claims/execution-cache-equivalence.md`), and
                // a cache that may change the answer is a cache that lies. For a value
                // whose whole product is its freshness the honest declaration is no cache
                // — and the window bought nothing this module was not already paying:
                // `environment.explain` runs the same full resolution uncached, and
                // nothing polls the route on a timer. `project.cache-is-invisible` is the
                // rule: a cache key is a content hash of what it derives from and never a
                // timestamp, and a cache a caller can observe is a defect. This value
                // cannot be made invisible while it carries when it was taken.
                cache: CachePolicy::Disabled,
                handler: snapshot,
            },
            capability! {
                id: "environment.explain",
                title: "Where an environment value came from",
                description: "The provenance of the snapshot: for each field, what decided it — a compile-time constant, a file, a command, or the cache — which resolver read it, and how far it can be trusted. Narrow it to one field, or to a prefix, by name.",
                input: ExplainInput,
                output: EnvironmentProvenance,
                stability: Stability::BehaviorallyVerified,
                exposure: Exposure {
                    mcp: mcp("majordomus_environment_explain"),
                    http: get("/api/v1/environment/explain"),
                    cli: None,
                },
                tags: ["environment", "provenance", "introspection"],
                handler: explain,
            },
            capability! {
                id: "environment.preflight",
                title: "Whether Majordomus is in force here, and what proves it",
                description: "One verdict per claim about this checkout — git; the episode, its briefing, the task and the handover; the policy, the rule corpus and the ADRs; the shared server and the MCP, API and Cockpit surfaces it serves; the peer board; recorded test runs, rule enforcement, provider projections, generated documentation and the deployment — each `verified`, `active`, `fresh`, `stale`, `degraded`, `unavailable`, `failed`, `unknown` or `not_applicable`, with the evidence it rests on. A verdict that asserts something is in force cannot be produced without evidence. The same value the command line prints and the entry banner summarises.",
                input: PreflightInput,
                output: Preflight,
                stability: Stability::BehaviorallyVerified,
                exposure: Exposure {
                    mcp: Some(McpExposure {
                        tool: Some("majordomus_preflight".into()),
                        resource: Some(McpResource { uri: PREFLIGHT_URI.into(), name: "preflight".into() }),
                    }),
                    http: get("/api/v1/environment/preflight"),
                    cli: None,
                },
                tags: ["environment", "governance", "verification", "evidence"],
                // A judgement of *now*, stamped with when it was taken: the same reason
                // `environment.status` is not cached.
                cache: CachePolicy::Disabled,
                handler: preflight,
            },
        ],
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// The preflight counts the rules `rules.report` answers, and a ledger `rules.report`
    /// refuses is counted as an empty one, as the preflight always counted it.
    #[test]
    fn the_preflight_counts_the_rules_rules_report_answers() {
        let repo = crate::synthetic::SyntheticRepository::small().expect("a repository");
        let ctx = repo.context().expect("a context");
        let root = std::path::Path::new(&ctx.index.repository.root);
        let ledger = crate::evidence::Ledger::load(root).expect("a readable ledger");
        assert_eq!(
            rules_report(&ctx, root),
            crate::rules::report(&ctx.index, &ledger)
        );
        let path = root.join(crate::evidence::LEDGER_PATH);
        std::fs::create_dir_all(path.parent().expect("a parent")).expect("a directory");
        std::fs::write(&path, "{ not a ledger").expect("an unreadable ledger");
        assert!(ctx.execute("rules.report", serde_json::json!({})).is_err());
        assert_eq!(
            rules_report(&ctx, root),
            crate::rules::report(&ctx.index, &crate::evidence::Ledger::empty())
        );
    }

    /// The declaration is the only place these names exist, and every projection — the MCP
    /// tool, the resource, the HTTP route, the OpenAPI operation, the benchmark target —
    /// is derived from it. A refactor that dropped an exposure would still compile.
    #[test]
    fn the_declaration_yields_the_projections_it_claims() {
        let m = module();
        assert_eq!(m.id.as_str(), "environment");
        let expected: &[(&str, &str, &str)] = &[
            (
                "environment.status",
                "majordomus_environment",
                "/api/v1/environment",
            ),
            (
                "environment.explain",
                "majordomus_environment_explain",
                "/api/v1/environment/explain",
            ),
            (
                "environment.preflight",
                "majordomus_preflight",
                "/api/v1/environment/preflight",
            ),
        ];
        let ids: Vec<&str> = m
            .capabilities
            .iter()
            .map(|e| e.capability.id.as_str())
            .collect();
        let want: Vec<&str> = expected.iter().map(|(id, _, _)| *id).collect();
        assert_eq!(
            ids, want,
            "the module declares a different set of capabilities"
        );
        for (executable, (id, tool, path)) in m.capabilities.iter().zip(expected) {
            let exposure = &executable.capability.exposure;
            assert_eq!(
                exposure.mcp.as_ref().and_then(|m| m.tool.as_deref()),
                Some(*tool),
                "{id} lost or renamed its MCP tool"
            );
            assert_eq!(
                exposure.http.as_ref().map(|h| h.path.as_str()),
                Some(*path),
                "{id} lost or renamed its HTTP route"
            );
        }
        let resource = m.capabilities[0]
            .capability
            .exposure
            .mcp
            .as_ref()
            .and_then(|m| m.resource.as_ref())
            .expect("the snapshot is readable as a resource");
        assert_eq!(resource.uri, ENVIRONMENT_URI);
    }

    /// A snapshot of *now* must not be served from a cache. The value stamps the moment
    /// it was taken into `generated_at`, and the executor holds that a cached capability
    /// answers the same value from the handler, from a cold cache and from a warm one; the
    /// two together made `tests/executor.rs` fail whenever a pair of calls straddled a
    /// second boundary — a test that failed on the calendar. The declaration was the
    /// defect, not the invariant.
    #[test]
    fn the_snapshot_is_not_cached_because_it_carries_the_moment_it_was_taken() {
        let m = module();
        let status = m
            .capabilities
            .iter()
            .find(|e| e.capability.id.as_str() == "environment.status")
            .expect("the module declares the snapshot");
        assert!(
            !status.capability.cache.is_enabled(),
            "environment.status answers with a wall clock in it, so it cannot be cached"
        );
    }

    /// A served request must not write to the checkout it is serving. The whole cache is
    /// the command line's, and a handler that wrote it would give an HTTP GET a side
    /// effect on the repository.
    #[test]
    fn a_served_snapshot_writes_nothing() {
        let repo = crate::synthetic::SyntheticRepository::small().expect("a repository");
        let ctx = repo.context().expect("a context");
        let cache = crate::environment::Cache::path(repo.root(), ".ai/local");
        let environment = snapshot(
            &ctx,
            EnvironmentInput {
                probe_services: false,
            },
        )
        .expect("a snapshot");
        assert_eq!(environment.resolution, Resolution::Full);
        assert!(
            !cache.exists(),
            "a served request wrote the checkout's cache"
        );
    }

    #[test]
    fn a_served_snapshot_counts_the_layer_it_is_serving() {
        let repo = crate::synthetic::SyntheticRepository::small().expect("a repository");
        let ctx = repo.context().expect("a context");
        let environment = snapshot(&ctx, EnvironmentInput::default()).expect("a snapshot");
        assert_eq!(environment.layer.objects, Some(ctx.index.objects.len()));
        assert_eq!(
            environment.layer.capabilities,
            Some(ctx.registry.summary().total)
        );
    }

    #[test]
    fn explaining_a_field_that_does_not_exist_says_so_rather_than_answering_emptily() {
        let repo = crate::synthetic::SyntheticRepository::small().expect("a repository");
        let ctx = repo.context().expect("a context");
        match explain(
            &ctx,
            ExplainInput {
                field: Some("nothing.like.this".into()),
            },
        ) {
            Err(CapabilityError::NotFound(message)) => {
                assert!(message.contains("nothing.like.this"))
            }
            other => panic!("{other:?}"),
        }
    }

    #[test]
    fn explaining_a_prefix_gives_every_field_under_it() {
        let repo = crate::synthetic::SyntheticRepository::small().expect("a repository");
        let ctx = repo.context().expect("a context");
        let all = explain(&ctx, ExplainInput { field: None }).expect("every field");
        let some = explain(
            &ctx,
            ExplainInput {
                field: Some("project".into()),
            },
        )
        .expect("the project fields");
        assert!(!some.fields.is_empty());
        assert!(some.fields.len() < all.fields.len());
        assert!(some.fields.iter().all(|f| f.field.starts_with("project.")));
    }
}