release_kit/commands/

upgrade.rs

//! `rk upgrade`: a landed target takes this binary's projection.
//!
//! A front over the direct writer: the receipt is required, the target's
//! evidence is gathered once, this binary's projection is computed from
//! its embedded sources, and every destination is decided by its recorded
//! kind alone. A recorded generated file whose bytes the record vouches
//! for is replaced from the candidate; one someone edited is a conflict,
//! replaced only where `--replace` names it, after its bytes are saved; a
//! recorded seeded or state file is preserved with its current digest
//! entering the receipt; a recorded marked region is replaced alone; a
//! recorded destination the projection no longer produces is released to
//! the target. A whole-file destination present on disk and absent from
//! the receipt is a conflict too. Every conflict not named refuses before
//! any write, collected in one pass. `--stage` takes every answer from a
//! stage's receipt. Preview by default; `--apply` lands under one target
//! lock with the receipt last.
//!
//! SATISFIES landing:ownership-is-elementary
//! SATISFIES landing:a-dropped-file-stays
//! SATISFIES landing:a-target-is-never-downgraded

use std::fmt::Write as _;

use serde::Serialize;

use crate::cli::upgrade::UpgradeArgs;
use crate::diagnostic::{Diagnostic, Reason};
use crate::embedded;
use crate::error::RkError;
use crate::held;
use crate::landing::apply::{self, Action, Collision, Prepared, Replaced};
use crate::landing::manifest::{self, Alignment, Manifest, Provider};
use crate::landing::{self, lock};
use crate::output::Output;
use crate::profile::{CapabilityRequests, GitWorkflow, ProfileSnapshot};
use crate::stage::CapabilityNote;

/// One destination and what the upgrade decided for it.
#[derive(Debug, Serialize)]
struct FileEntry {
    /// The destination, relative to the target.
    path: String,
    /// The kind this projection declares for it, or the recorded kind of
    /// a released destination.
    kind: &'static str,
    /// `created`, `replaced`, `matched`, `preserved`, `drift`, `released`,
    /// or `collision` in a preview.
    action: &'static str,
}

/// An answer the record leaves open, and the default this upgrade takes.
#[derive(Debug, Serialize, PartialEq, Eq)]
struct PendingAnswer {
    /// The configuration key the answer belongs to.
    key: &'static str,
    /// The answer this upgrade takes where the operator gives none.
    default: &'static str,
    /// Why the answer is open.
    reason: &'static str,
    /// The flag that gives the other answer.
    action: &'static str,
}

/// The answers this upgrade takes on the operator's behalf.
///
/// A record that predates the workflow guards carries no answer for them.
/// That is the one capability whose old records do not read as opt-out:
/// every such target carries the guards, so the upgrade keeps them, and it
/// says so once, until a flag or the configuration answers.
fn pending_answers(
    args: &UpgradeArgs,
    recorded: &Manifest,
    existing: Option<&crate::config::Config>,
) -> Vec<PendingAnswer> {
    let answered = args.workflow_guards.is_some()
        || args.workflow_only
        || existing.is_some_and(|config| config.capabilities.workflow_guards.is_some())
        || recorded.capabilities.workflow_guards.is_some();
    if answered {
        return Vec::new();
    }
    vec![PendingAnswer {
        key: "capabilities.workflow_guards",
        default: "on",
        reason: "the record predates the workflow guards, and this target carries them",
        action: "--workflow-guards off drops them; --workflow-guards on keeps them and records the answer",
    }]
}

/// The machine form of an upgrade report.
#[derive(Debug, Serialize)]
struct Report {
    /// The shape version of this document.
    schema: &'static str,
    /// `preview` or `apply`.
    mode: &'static str,
    /// The target directory.
    target: String,
    /// The version the receipt came from.
    from_version: String,
    /// This binary's version.
    to_version: &'static str,
    /// What the project is, as the rewritten receipt carries it.
    profile: ProfileSnapshot,
    /// How topic branches reach the trunk.
    git: GitWorkflow,
    /// Which optional products the rewritten receipt carries.
    capabilities: CapabilityRequests,
    /// Every capability, in catalog order, with its status.
    selection: Vec<CapabilityNote>,
    /// Why the selected release automation cannot land in this release,
    /// absent where it can or none is selected. A preview reports it and
    /// exits 0; the apply refuses on it.
    #[serde(skip_serializing_if = "Option::is_none")]
    release_unavailable: Option<String>,
    /// Why the provider's licence condition refuses this target, absent
    /// where no condition applies or the licence satisfies it. A preview
    /// reports it and exits 0; the apply refuses on it.
    #[serde(skip_serializing_if = "Option::is_none")]
    licence_refusal: Option<String>,
    /// The Nix destinations this target could not take, each with why;
    /// absent where nothing was withheld.
    #[serde(skip_serializing_if = "Option::is_none")]
    withheld: Option<Vec<landing::Withheld>>,
    /// The destinations the landing refuses as they stand; absent where
    /// there is none. A preview lists them and exits 0.
    #[serde(skip_serializing_if = "Option::is_none")]
    collisions: Option<Vec<Collision>>,
    /// The conflicts `--replace` named, each with where its bytes were
    /// saved; empty where none was named.
    replaced: Vec<Replaced>,
    /// The answers the record leaves open and this upgrade takes by
    /// default; absent where the record answers everything.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pending: Vec<PendingAnswer>,
    config: crate::config::Plan,
    /// Every destination, with its action.
    files: Vec<FileEntry>,
    /// What plausibly follows.
    next: Vec<String>,
}

/// Upgrade the landed target to this binary's projection.
///
/// # Errors
///
/// Returns a refusal for a missing receipt, an unknown receipt schema, a
/// receipt from a newer binary, and, on apply, any collected collision;
/// and [`RkError::Io`] on filesystem failure.
#[allow(
    clippy::too_many_lines,
    reason = "one pass holds the target, resolves the answers once from the flags or the stage, and lands"
)]
pub fn run(args: &UpgradeArgs) -> Result<(), RkError> {
    let out = Output::new(args.json);
    // An apply takes the target before it reads anything of it, the
    // receipt and the configuration included. A preview holds nothing.
    let lock = args
        .apply
        .then(|| lock::acquire(&args.target))
        .transpose()?;
    // One directory descriptor, held from here through the receipt write:
    // every read and every write goes through it, so a root exchanged
    // under the pathname later receives nothing.
    // The proof's pause: the lock is held and the directory is not yet.
    held::pause(apply::PAUSE_VAR, "locked", "proceed-locked");
    let held = lock.as_ref().map_or_else(
        || apply::Held::open(&args.target),
        |lock| apply::Held::open_locked(&args.target, lock),
    )?;
    // The proof's pause: the target is held, and nothing has been read.
    held::pause(apply::PAUSE_VAR, "held", "proceed-held");
    let recorded = load_upgradable(&held)?;
    let existing = crate::config::load(held.base().as_std_path())?;
    let staged = args
        .stage
        .as_deref()
        .map(|root| {
            if answered(args) {
                return Err(crate::stage::read::answered_twice());
            }
            let canonical = std::fs::canonicalize(args.target.as_std_path())?;
            crate::stage::read::load(root, &canonical).map(|receipt| (root, receipt))
        })
        .transpose()?;
    let params = match &staged {
        Some((root, receipt)) => {
            let params = landing::Params::resolve(
                held.base(),
                &crate::stage::read::inputs(&receipt.parameters),
                existing.as_ref(),
                Some(&recorded),
                landing::Purpose::Upgrade,
            )?;
            crate::stage::read::confirm(&params, receipt, root)?;
            params
        }
        None => resolve_params(args, &held, &recorded, existing.as_ref())?,
    };

    let mut prepared = apply::prepare(&held, Some(&recorded), &params, existing.as_ref())?;
    apply::name_replacements(&mut prepared, &args.replace)?;
    crate::commands::init::report_moved_secrets(out, &held, &prepared)?;
    let landed = if let Some(lock) = lock {
        let landed = apply::land(
            &held,
            Some(&recorded),
            &prepared,
            apply::Origin::Upgrade,
            &lock,
        )?;
        drop(lock);
        Some(landed)
    } else {
        None
    };
    let replaced = landed.as_ref().map_or_else(
        || apply::previewed_replacements(&prepared),
        |landed| landed.replaced.clone(),
    );
    for entry in &replaced {
        if let Some(saved) = &entry.saved_to {
            out.result_line(format!("saved {} to {saved}", entry.path));
        }
    }

    let pending = pending_answers(args, &recorded, existing.as_ref());
    for answer in &pending {
        out.result_line(format!(
            "pending {}: {}; this upgrade answers {}; {}",
            answer.key, answer.reason, answer.default, answer.action
        ));
    }
    let sentinels = report_decisions(out, &held, &prepared, landed.is_some())?;
    if landed.is_some() {
        out.result_line(format!("rewrote {}", manifest::MANIFEST_PATH));
        for sentinel in &sentinels {
            out.result_line(format!("fill this sentinel: {sentinel}"));
        }
    }

    let next = next_lines(args, &params, prepared.collisions.is_empty());
    out.next(&next);
    out.emit(&Report {
        schema: SCHEMA,
        config: prepared.config.clone(),
        mode: if args.apply { "apply" } else { "preview" },
        target: args.target.to_string(),
        from_version: recorded.rk_version,
        to_version: env!("CARGO_PKG_VERSION"),
        profile: params.profile().clone(),
        git: params.git().clone(),
        capabilities: params.capabilities().clone(),
        selection: prepared
            .projection
            .capabilities
            .iter()
            .map(|selection| CapabilityNote::of(selection, &prepared.projection))
            .collect(),
        release_unavailable: prepared.projection.release_unavailable().map(str::to_owned),
        licence_refusal: prepared.projection.licence_refusal.clone(),
        withheld: withheld_of(&prepared),
        collisions: (!prepared.collisions.is_empty()).then(|| prepared.collisions.clone()),
        replaced,
        pending,
        files: prepared
            .decisions
            .iter()
            .map(|decision| FileEntry {
                path: decision.destination.clone(),
                kind: decision.kind.as_str(),
                action: decision.action.as_str(),
            })
            .chain(prepared.collisions.iter().map(|collision| FileEntry {
                path: collision.path.clone(),
                kind: landing::kind_of(&collision.path).map_or("unknown", landing::Kind::as_str),
                action: "collision",
            }))
            .collect(),
        next,
    })
}

/// The report's shape version.
const SCHEMA: &str = "rk.upgrade/11";

/// Whether any answer flag was given, which `--stage` refuses beside it.
const fn answered(args: &UpgradeArgs) -> bool {
    !args.profile.is_empty()
        || args.nix_packaging.is_some()
        || args.reporting_policy.is_some()
        || args.scorecard.is_some()
        || args.workflow_guards.is_some()
        || args.workflow_only
        || args.code_scanning.is_some()
}

/// The withheld list a report carries.
fn withheld_of(prepared: &Prepared) -> Option<Vec<landing::Withheld>> {
    let withheld: Vec<landing::Withheld> = prepared
        .projection
        .omissions
        .iter()
        .map(|omission| landing::Withheld {
            path: omission.destination.clone(),
            reason: omission.reason.clone(),
        })
        .collect();
    (!withheld.is_empty()).then_some(withheld)
}

/// Every human line one upgrade prints about its own decisions, and the
/// sentinels a landed run found while it read them back.
///
/// `landed` says whether the run wrote: only then is a created or replaced
/// destination read back for its unfilled sentinels, because a preview has
/// nothing on disk to read.
///
/// # Errors
///
/// A read failure at a destination the run just wrote.
fn report_decisions(
    out: Output,
    held: &apply::Held,
    prepared: &Prepared,
    landed: bool,
) -> Result<Vec<String>, RkError> {
    out.result_line(format!(
        "profile: {}",
        crate::commands::profile::describe(
            prepared.params.profile(),
            prepared.params.git(),
            prepared.params.capabilities(),
            prepared.params.repo()
        )
    ));
    crate::commands::init::describe_selection(out, prepared);
    for key in &prepared.config.changes {
        out.result_line(format!("configuration changes {key}"));
    }
    out.result_line(format!(
        "{} {}",
        prepared.config.action,
        crate::config::CONFIG_PATH
    ));
    let mut sentinels: Vec<String> = Vec::new();
    for decision in &prepared.decisions {
        if landed && matches!(decision.action, Action::Created | Action::Replaced) {
            let bytes =
                landing::read_recorded(held.base(), &decision.destination)?.unwrap_or_default();
            collect_sentinels(&decision.destination, &bytes, &mut sentinels);
        }
        out.result_line(crate::commands::init::describe(decision));
    }
    for collision in &prepared.collisions {
        out.result_line(format!(
            "collision {}: {}",
            collision.path, collision.reason
        ));
    }
    for entry in &prepared.projection.omissions {
        out.result_line(format!("withheld {}: {}", entry.destination, entry.reason));
        if let Some(action) = &entry.action {
            out.result_line(format!("  action: {action}"));
        }
    }
    if let Some(reason) = prepared.projection.licence_refusal.as_deref() {
        out.result_line(format!("licence refusal: {reason}"));
    }
    if let Some(reason) = prepared.projection.release_unavailable() {
        out.result_line(format!("release automation unavailable: {reason}"));
    }
    Ok(sentinels)
}

/// One capability flag's answer: `on`, `off`, or unanswered.
///
/// Every opt-in capability reads its flag the same way, so the refusal
/// names the flag and the two values from one place.
fn toggle(flag: &str, value: Option<&str>) -> Result<Option<bool>, RkError> {
    match value {
        None => Ok(None),
        Some("on") => Ok(Some(true)),
        Some("off") => Ok(Some(false)),
        Some(other) => Err(RkError::Usage(format!(
            "unknown --{flag} value '{other}'; the values are: on, off"
        ))),
    }
}

fn resolve_params(
    args: &UpgradeArgs,
    held: &apply::Held,
    recorded: &Manifest,
    existing: Option<&crate::config::Config>,
) -> Result<landing::Params, RkError> {
    let nix = toggle("nix-packaging", args.nix_packaging.as_deref())?;
    let reporting_policy = toggle("reporting-policy", args.reporting_policy.as_deref())?;
    let scorecard = toggle("scorecard", args.scorecard.as_deref())?;
    let workflow_guards = toggle("workflow-guards", args.workflow_guards.as_deref())?;
    let code_scanning = args
        .code_scanning
        .as_deref()
        .map(Provider::parse)
        .transpose()?;
    let inputs = landing::Inputs {
        nix,
        reporting_policy,
        scorecard,
        code_scanning,
        workflow_guards,
        ..args.profile.inputs()?
    };
    let inputs = if args.workflow_only {
        crate::cli::profile_flags::workflow_only(inputs)?
    } else {
        inputs
    };
    landing::Params::resolve(
        held.base(),
        &inputs,
        existing,
        Some(recorded),
        landing::Purpose::Upgrade,
    )
}

/// The `Next:` lines for each outcome. A behavior-defining flag the
/// preview was run with rides into the follow-up command, so following
/// it applies the decision that was previewed, never a different one.
fn next_lines(args: &UpgradeArgs, params: &landing::Params, clean: bool) -> Vec<String> {
    // A flag the preview was run with rides into the follow-up, as the
    // resolved answer it produced; a flag it was not run with stays out,
    // so the configuration and the record keep answering it.
    let profile = &args.profile;
    let mut identity_flags = String::new();
    for technology in params.technologies() {
        if !profile.technology.is_empty() {
            let _ = write!(identity_flags, " --technology {technology}");
        }
    }
    for (given, flag, value) in [
        (
            profile.forge.is_some(),
            "forge",
            params.forge().map(str::to_owned),
        ),
        (
            profile.repo.is_some(),
            "repo",
            Some(params.repo().to_owned()),
        ),
        (
            profile.release_mode.is_some(),
            "release-mode",
            Some(params.release_mode().as_str().to_owned()),
        ),
        (
            profile.release_driver.is_some(),
            "release-driver",
            params.driver().map(str::to_owned),
        ),
        (
            profile.release_style.is_some(),
            "release-style",
            params.style().map(|style| style.as_str().to_owned()),
        ),
        (
            profile.trunk.is_some(),
            "trunk",
            Some(params.trunk().to_owned()),
        ),
        (
            profile.checkout_mode.is_some(),
            "checkout-mode",
            Some(params.checkout_mode().as_str().to_owned()),
        ),
    ] {
        if given && let Some(value) = value {
            let _ = write!(identity_flags, " --{flag} {value}");
        }
    }
    // The preset rides as itself: its four answers are what the preview
    // resolved, and the follow-up must resolve them the same way.
    let workflow_flag = if args.workflow_only {
        format!(" {}", crate::cli::profile_flags::WORKFLOW_ONLY)
    } else {
        String::new()
    };
    let style_flag = String::new();
    let capabilities = params.capability_toggles();
    if args.apply {
        vec![
            "commit the upgraded files, the receipt included".to_owned(),
            format!("rk status --target {} reports the result", args.target),
        ]
    } else if clean {
        vec![
            format!(
                "rk upgrade{identity_flags}{workflow_flag}{style_flag}{capabilities} --target {} --apply writes",
                args.target
            ),
            format!(
                "rk stage --target {} stages the complete candidate for a byte comparison",
                args.target
            ),
        ]
    } else {
        vec![
            format!(
                "resolve each collision above through the rk-setup skill; rk upgrade{identity_flags}{workflow_flag}{style_flag}{capabilities} --target {} --apply refuses until then",
                args.target
            ),
            format!(
                "rk stage --target {} stages the complete candidate for a byte comparison",
                args.target
            ),
        ]
    }
}

/// The receipt an upgrade may act on: present, at a known schema, and not
/// from a newer binary than this one.
fn load_upgradable(held: &apply::Held) -> Result<Manifest, RkError> {
    let target = held.display();
    let Some(recorded) = manifest::load(held.base())? else {
        return Err(RkError::refusal(
            Diagnostic::new(
                Reason::StateDrift,
                format!(
                    "no {} at {target}: an upgrade needs the receipt of the landing it moves, and nothing was written",
                    manifest::MANIFEST_PATH
                ),
            )
            .expected("a recorded landing")
            .action(format!(
                "rk stage --target {target} stages this binary's candidate for a byte comparison; the rk-setup skill carries the best-effort migration, ending in rk adopt for a target brought to the candidate or rk init for a fresh one"
            ))
            .target_state("unchanged"),
        ));
    };
    if manifest::alignment(&recorded.rk_version, env!("CARGO_PKG_VERSION"))
        == Alignment::TargetNewer
    {
        return Err(RkError::refusal(
            Diagnostic::new(
                Reason::StateDrift,
                format!(
                    "this landing came from rk {}, newer than this binary's {}; downgrading a target is not an upgrade",
                    recorded.rk_version,
                    env!("CARGO_PKG_VERSION")
                ),
            )
            .expected("a binary at or above the recorded rk_version")
            .action(format!("install release-kit {} or newer", recorded.rk_version))
            .target_state("unchanged"),
        ));
    }
    Ok(recorded)
}

/// The judgment sentinels a newly written file carries.
fn collect_sentinels(destination: &str, bytes: &[u8], found: &mut Vec<String>) {
    let text = String::from_utf8_lossy(bytes);
    for (idx, line) in text.lines().enumerate() {
        if line.contains(embedded::SENTINEL) {
            found.push(format!("{destination}:{}: {}", idx + 1, line.trim()));
        }
    }
}

#[cfg(test)]
mod tests {
    use super::{FileEntry, Report};
    use crate::landing::CheckoutMode;
    use crate::landing::Integration;
    use crate::profile::{
        CapabilityRequests, GitWorkflow, ProfileSnapshot, ReleaseIntent, ReleaseMode,
    };

    /// The complete `rk.upgrade/11` shape, held by snapshot.
    #[test]
    fn the_upgrade_report_schema_snapshot_holds() {
        let report = Report {
            schema: super::SCHEMA,
            config: crate::config::Plan {
                action: "added",
                changes: vec![],
                content: "schema_version = 2\n".into(),
            },
            mode: "preview",
            target: "/tmp/t".into(),
            from_version: "0.1.0".into(),
            to_version: "0.2.0",
            profile: ProfileSnapshot {
                technologies: vec!["rust".into()],
                forge: Some("github".into()),
                release: ReleaseIntent {
                    mode: ReleaseMode::Automatic,
                    driver: Some("rust".into()),
                    style: Some(crate::landing::Style::Trunk),
                    line_prefix: Some("release/".into()),
                    registry: None,
                    build: None,
                },
            },
            git: GitWorkflow {
                trunk: "master".into(),
                checkout_mode: CheckoutMode::MainWorktree,
                integration: Integration::Local,
                merge_form: crate::landing::MergeForm::Squash,
            },
            capabilities: CapabilityRequests {
                nix_packaging: false,
                reporting_policy: true,
                scorecard: false,
                code_scanning: None,
                workflow_guards: Some(false),
            },
            selection: vec![],
            release_unavailable: None,
            licence_refusal: None,
            withheld: None,
            collisions: Some(vec![crate::landing::apply::Collision {
                path: "SECURITY.md".into(),
                reason: "was edited after the landing".into(),
                replaceable: true,
            }]),
            replaced: vec![crate::landing::apply::Replaced {
                path: ".github/workflows/release-plz.yml".into(),
                saved_to: Some("/state/snapshots/widget-0123456789ab/20261009T120000Z/replaced/.github/workflows/release-plz.yml".into()),
            }],
            pending: vec![],
            files: vec![
                FileEntry {
                    path: "release-plz.toml".into(),
                    kind: "seeded",
                    action: "drift",
                },
                FileEntry {
                    path: "legacy.yml".into(),
                    kind: "rendered",
                    action: "released",
                },
            ],
            next: vec!["rk upgrade --target /tmp/t --apply writes".into()],
        };
        assert_eq!(
            serde_json::to_string(&report).expect("a report serializes"),
            r#"{"schema":"rk.upgrade/11","mode":"preview","target":"/tmp/t","from_version":"0.1.0","to_version":"0.2.0","profile":{"technologies":["rust"],"forge":"github","release":{"mode":"automatic","driver":"rust","style":"trunk","line_prefix":"release/"}},"git":{"trunk":"master","checkout_mode":"main-worktree","integration":"local","merge_form":"squash"},"capabilities":{"nix_packaging":false,"reporting_policy":true,"scorecard":false,"workflow_guards":false},"selection":[],"collisions":[{"path":"SECURITY.md","reason":"was edited after the landing","replaceable":true}],"replaced":[{"path":".github/workflows/release-plz.yml","saved_to":"/state/snapshots/widget-0123456789ab/20261009T120000Z/replaced/.github/workflows/release-plz.yml"}],"config":{"action":"added","changes":[],"content":"schema_version = 2\n"},"files":[{"path":"release-plz.toml","kind":"seeded","action":"drift"},{"path":"legacy.yml","kind":"rendered","action":"released"}],"next":["rk upgrade --target /tmp/t --apply writes"]}"#
        );
    }
}