majordomus_cli/command_graph/

bridge.rs

//! The workflow bridge: the command graph projected into recipes.
//!
//! `just` is an ergonomic front door, not a place where commands are declared. Every recipe
//! this writes is one line that runs the canonical program with the caller's own arguments
//! — never a second implementation, never a second description, and never a call back into
//! `just`, which is what would make the bridge a cycle.
//!
//! ```text
//!   CommandGraph ──► render ──► bridge.just ──► imported by the root justfile
//!                       └─────► bridge.json  (what was written, and from which graph)
//! ```
//!
//! # Where it lives, and why not in the tree
//!
//! Under `.ai/local/cache/`, which no commit carries. A generated file in the tree would
//! have to be regenerated by whoever changes a command, checked by a gate, and merged by
//! hand on every branch that touches the command line — for a file that is a pure function
//! of the tree it sits in. The materialisation is cheap and fingerprinted, so the cost of
//! not tracking it is one hash comparison per entry into the repository.
//!
//! # Argument forwarding
//!
//! Interpolating a recipe's arguments into the body — `{{args}}` — splices text into a
//! shell command, so a path with a space arrives as two arguments and a quote arrives as a
//! syntax error. The runner's own answer is `set positional-arguments`, which passes a
//! recipe's arguments to the shell as `$1`, `$2`, …; the body then forwards `"$@"` and the
//! shell's own quoting carries spaces, quotes, `$(…)`, newlines and leading dashes
//! unaltered. Nothing here escapes anything, because nothing here interpolates anything.

use std::collections::BTreeSet;
use std::path::{Path, PathBuf};

use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};

use super::model::{CommandGraph, CommandNode, Origin};

/// The directory the bridge is materialised in, relative to the repository root.
pub const DIRECTORY: &str = ".ai/local/cache/command-graph";

/// The file the root justfile imports.
pub const BRIDGE: &str = "bridge.just";

/// The record of what was written, and of the graph it was written from.
pub const MANIFEST: &str = "bridge.json";

/// The schema of that record.
pub const MANIFEST_SCHEMA: &str = "majordomus/command-bridge/v1";

/// The setting the root justfile must carry for the forwarding in every recipe to be safe.
///
/// Named here so that the rule which checks it and the generator that depends on it read
/// the same constant.
pub const REQUIRED_SETTING: &str = "set positional-arguments";

/// What a materialisation wrote, and from what.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Manifest {
    /// The schema of this record.
    pub schema: String,
    /// The fingerprint of the graph the bridge was written from.
    pub fingerprint: String,
    /// Every recipe name the bridge defines, sorted. Read back on the next build so that a
    /// recipe of this bridge is not mistaken for a declared workflow.
    pub recipes: Vec<String>,
    #[serde(default)]
    /// A stamp over the files the bridge is derived from, and the executable that derived
    /// it. Entering the repository compares this and does nothing when it matches, which
    /// is what keeps `cd` at a few milliseconds: the graph is only built when one of the
    /// declarations behind it has actually changed.
    pub stamp: String,
}

/// What happened.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Outcome {
    /// Where the bridge is.
    pub path: PathBuf,
    /// Whether anything was written; false when the fingerprint already matched.
    pub written: bool,
    /// How many recipes it defines.
    pub recipes: usize,
    /// The fingerprint of the graph it was written from.
    pub fingerprint: String,
}

/// The recipe names this graph projects.
///
/// The materialiser writes them and the next build reads them back through the manifest;
/// they are computed here so that the two cannot disagree.
pub fn recipe_names(graph: &CommandGraph) -> BTreeSet<String> {
    let mut out: BTreeSet<String> = graph
        .commands
        .iter()
        .filter(|c| c.origin != Origin::Workflow)
        .filter_map(|c| c.projections.workflow.clone())
        .collect();
    for alias in super::semantics::WORKFLOW_ALIASES {
        if graph
            .commands
            .iter()
            .any(|c| c.id.as_str() == alias.command)
        {
            out.insert(alias.alias.to_string());
        }
    }
    out
}

/// The files the bridge is derived from.
///
/// The declarations, not their contents' meaning: the workflow runner's files, the shell
/// tool's command registry, and the executable itself, whose clap tree is the third
/// declaration and changes when it is rebuilt. A change anywhere here can change the
/// bridge; a change nowhere here cannot.
pub fn inputs(root: &Path) -> Vec<PathBuf> {
    let mut out = vec![root.join("justfile"), root.join("share/commands.yaml")];
    if let Ok(entries) = std::fs::read_dir(root.join(".just")) {
        let mut modules: Vec<PathBuf> = entries
            .flatten()
            .map(|e| e.path())
            .filter(|p| p.extension().is_some_and(|e| e == "just"))
            .collect();
        modules.sort();
        out.extend(modules);
    }
    if let Ok(exe) = std::env::current_exe() {
        out.push(exe);
    }
    out
}

/// A stamp over those files: size and modification time, in a fixed order.
///
/// Not a hash of the contents. Reading every byte of a build artefact on every entry into
/// the repository would cost more than the work it avoids, and the question being asked is
/// only "has anything changed since I last looked", for which the filesystem's own answer
/// is enough. A file that is absent stamps as absent, so adding one is a change.
pub fn stamp(root: &Path) -> String {
    use std::time::UNIX_EPOCH;
    let mut hasher = Sha256::new();
    hasher.update(MANIFEST_SCHEMA.as_bytes());
    for path in inputs(root) {
        hasher.update(path.to_string_lossy().as_bytes());
        match std::fs::metadata(&path) {
            Ok(meta) => {
                hasher.update(meta.len().to_le_bytes());
                let secs = meta
                    .modified()
                    .ok()
                    .and_then(|t| t.duration_since(UNIX_EPOCH).ok())
                    .map(|d| d.as_nanos())
                    .unwrap_or_default();
                hasher.update(secs.to_le_bytes());
            }
            Err(_) => hasher.update(b"absent"),
        }
    }
    format!("{:x}", hasher.finalize())[..16].to_string()
}

/// Is the materialised bridge derived from the declarations as they stand?
///
/// Cheap: a few `stat` calls and one hash. This is what entering the repository asks.
pub fn is_current(root: &Path) -> bool {
    manifest(root).is_some_and(|m| !m.stamp.is_empty() && m.stamp == stamp(root))
        && root.join(DIRECTORY).join(BRIDGE).exists()
}

/// Read back what the last materialisation wrote, if anything.
pub fn manifest(root: &Path) -> Option<Manifest> {
    let text = std::fs::read_to_string(root.join(DIRECTORY).join(MANIFEST)).ok()?;
    let manifest: Manifest = serde_json::from_str(&text).ok()?;
    (manifest.schema == MANIFEST_SCHEMA).then_some(manifest)
}

/// The recipe names the last materialisation wrote; empty when there was none.
pub fn bridged(root: &Path) -> BTreeSet<String> {
    manifest(root)
        .map(|m| m.recipes.into_iter().collect())
        .unwrap_or_default()
}

/// Render the bridge.
///
/// Deterministic: the same graph renders the same bytes.
pub fn render(graph: &CommandGraph) -> String {
    let mut out = String::new();
    out.push_str(&format!(
        "# GENERATED FILE — DO NOT EDIT.\n\
         #\n\
         # The command graph, projected into recipes. Every line below is derived from a\n\
         # declaration somewhere else: the clap tree of the Rust executable, the shipped\n\
         # command registry of the shell tool, and the semantics beside each. Editing this\n\
         # file changes nothing durable — the next entry into the repository overwrites it.\n\
         #\n\
         # graph:  {}\n\
         # source: majordomus commands bridge\n\
         # schema: {}\n\n",
        graph.fingerprint,
        super::model::SCHEMA
    ));

    out.push_str(
        "# Both programs are reached through the launchers, never through a path into a build\n\
         # directory: the launcher is what decides where the executable of this checkout is.\n",
    );
    out.push_str("majordomus_executable := justfile_directory() / \"bin/majordomus-cli\"\n");
    out.push_str("majordomus_tool := justfile_directory() / \"bin/majordomus\"\n\n");

    for node in graph
        .commands
        .iter()
        .filter(|c| c.origin != Origin::Workflow)
    {
        let Some(name) = &node.projections.workflow else {
            continue;
        };
        out.push_str(&recipe(node, name));
    }

    // The names the runner answered to before the bridge was derived. Each one runs the
    // canonical program directly — never another recipe, which would be a bridge over a
    // bridge — and says in its own description what it is an older spelling of.
    let mut aliases: Vec<String> = Vec::new();
    for alias in super::semantics::WORKFLOW_ALIASES {
        let Some(node) = graph
            .commands
            .iter()
            .find(|c| c.id.as_str() == alias.command)
        else {
            continue;
        };
        aliases.push(alias_recipe(node, alias));
    }
    if !aliases.is_empty() {
        out.push_str("# The older spellings, kept so that nothing a person typed disappears.\n");
        for a in aliases {
            out.push_str(&a);
        }
    }
    out
}

/// One compatibility alias.
fn alias_recipe(node: &CommandNode, alias: &super::semantics::WorkflowAlias) -> String {
    let program = match node.origin {
        Origin::Tool => "{{majordomus_tool}}",
        _ => "{{majordomus_executable}}",
    };
    let mut argv = node.execution.argv.clone();
    argv.extend(alias.arguments.iter().map(|a| (*a).to_string()));
    format!(
        "# {} — {}\n[group('compatibility')]\n{} *args:\n    @\"{program}\" {} \"$@\"\n\n",
        one_line(&node.summary),
        one_line(alias.reason),
        alias.alias,
        argv.join(" ")
    )
}

/// One recipe.
fn recipe(node: &CommandNode, name: &str) -> String {
    let program = match node.origin {
        Origin::Tool => "{{majordomus_tool}}",
        _ => "{{majordomus_executable}}",
    };
    let mut out = String::new();
    // The doc comment `just --list` shows. One line, from the one summary; a second line
    // would silently become the description, which is a defect this repository has met.
    out.push_str(&format!("# {}\n", one_line(&node.summary)));
    if let Some(group) = &node.group {
        out.push_str(&format!("[group('{}')]\n", escape_group(group)));
    }
    // A destructive command asks before it runs, from the runner's own mechanism, because
    // the effect said so — not because someone remembered to add the attribute.
    if node.effect == super::model::Effect::Destructive {
        out.push_str(&format!(
            "[confirm(\"{} — run it? [y/N]\")]\n",
            escape_double(&node.invocation)
        ));
    }
    out.push_str(&format!("{name} *args:\n"));
    out.push_str(&format!(
        "    @\"{program}\" {} \"$@\"\n\n",
        node.execution.argv.join(" ")
    ));
    out
}

/// One line, with anything that would break out of a comment removed.
///
/// A summary comes from a declaration in this repository, but the graph is a general
/// mechanism and a workflow's description comes from a file a person edits. Control
/// characters, newlines and escape sequences never reach a generated shell file.
fn one_line(text: &str) -> String {
    let first = text.lines().next().unwrap_or_default();
    first
        .chars()
        .filter(|c| !c.is_control())
        .collect::<String>()
        .trim()
        .to_string()
}

/// A group name, safe inside single quotes.
fn escape_group(text: &str) -> String {
    one_line(text).replace('\'', "")
}

/// Text safe inside a double-quoted runner string.
fn escape_double(text: &str) -> String {
    one_line(text).replace('\\', "").replace('"', "'")
}

/// Write the bridge and its manifest, atomically, and only when the graph changed.
///
/// Two shells entering the repository at once may both call this. Each renders to its own
/// temporary file and renames it over the destination, which is atomic on the platforms
/// this runs on, so a reader sees one complete file or the other and never a half-written
/// one. No lock is taken: the two contents are identical whenever the two graphs are, and
/// the loser of the race has written the same bytes as the winner.
pub fn materialise(root: &Path, graph: &CommandGraph) -> std::io::Result<Outcome> {
    let dir = root.join(DIRECTORY);
    let path = dir.join(BRIDGE);
    let names = recipe_names(graph);

    if let Some(previous) = manifest(root) {
        if previous.fingerprint == graph.fingerprint && path.exists() {
            return Ok(Outcome {
                path,
                written: false,
                recipes: previous.recipes.len(),
                fingerprint: graph.fingerprint.clone(),
            });
        }
    }

    std::fs::create_dir_all(&dir)?;
    write_atomic(&path, render(graph).as_bytes())?;
    let manifest = Manifest {
        schema: MANIFEST_SCHEMA.into(),
        fingerprint: graph.fingerprint.clone(),
        recipes: names.iter().cloned().collect(),
        stamp: stamp(root),
    };
    write_atomic(
        &dir.join(MANIFEST),
        serde_json::to_string_pretty(&manifest)
            .unwrap_or_default()
            .as_bytes(),
    )?;

    Ok(Outcome {
        path,
        written: true,
        recipes: names.len(),
        fingerprint: graph.fingerprint.clone(),
    })
}

/// Render beside the destination, then rename over it.
fn write_atomic(path: &Path, bytes: &[u8]) -> std::io::Result<()> {
    let tmp = path.with_extension(format!("tmp.{}", std::process::id()));
    std::fs::write(&tmp, bytes)?;
    std::fs::rename(&tmp, path)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::command_graph::{build, Inputs};

    #[test]
    fn every_recipe_runs_the_canonical_program_and_forwards_safely() {
        let graph = build(&Inputs::default());
        let text = render(&graph);
        assert!(text.contains("GENERATED FILE"));
        assert!(text.contains(&graph.fingerprint));
        for line in text.lines().filter(|l| l.trim_start().starts_with("@\"")) {
            assert!(
                line.ends_with("\"$@\""),
                "a recipe forwards its arguments unquoted: {line}"
            );
            assert!(
                !line.contains("{{args}}"),
                "a recipe interpolates its arguments: {line}"
            );
            assert!(
                !line.contains("just "),
                "a recipe calls the runner back: {line}"
            );
        }
    }

    #[test]
    fn the_names_it_writes_are_the_names_it_reports() {
        let graph = build(&Inputs::default());
        let text = render(&graph);
        for name in recipe_names(&graph) {
            assert!(
                text.contains(&format!("\n{name} *args:")),
                "{name} is reported and not written"
            );
        }
    }

    #[test]
    fn a_destructive_command_asks_first() {
        let graph = build(&Inputs::default());
        let text = render(&graph);
        let remove = graph
            .commands
            .iter()
            .find(|c| c.id.as_str() == "executable.worktree.remove")
            .expect("worktree remove is declared");
        let name = remove.projections.workflow.clone().unwrap();
        let block = text
            .split("\n\n")
            .find(|b| b.contains(&format!("\n{name} *args:")))
            .expect("the recipe is written");
        assert!(block.contains("[confirm("), "{block}");
    }

    #[test]
    fn hostile_metadata_cannot_break_out_of_the_generated_file() {
        assert_eq!(one_line("a\nb"), "a");
        assert_eq!(one_line("a\u{1b}[31mb"), "a[31mb");
        assert_eq!(escape_double("say \"hi\""), "say 'hi'");
        assert_eq!(escape_group("it's"), "its");
    }

    #[test]
    fn materialising_twice_writes_once() {
        let dir = tempfile::tempdir().expect("a temporary directory");
        let graph = build(&Inputs::default());
        let first = materialise(dir.path(), &graph).expect("the first write");
        assert!(first.written);
        let second = materialise(dir.path(), &graph).expect("the second write");
        assert!(!second.written, "an unchanged graph rewrote the bridge");
        assert_eq!(second.recipes, first.recipes);
        assert_eq!(bridged(dir.path()).len(), first.recipes);
    }
}