docsrs_cli/cli/destructive.rs
1//! The register of verbs that destroy, and the one rule they all obey.
2//!
3//! # Why a register instead of two guards
4//!
5//! `cache clear` learned Explicit Target Designation on 2026-08-10 and the same
6//! plan said `config init --force` would learn it too. Only the first was built.
7//! The gap was not the missing guard — it was that nothing could tell the guard
8//! was missing, because the rule lived inside one `match` arm and could not be
9//! asked a question. A second destructive verb shipped without a waiver and every
10//! gate agreed with the tree.
11//!
12//! So the rule moved here. The runtime reads this list to decide whether to
13//! refuse, and `tests/policy/etd.rs` reads the same list to demand a waiver flag,
14//! a `target_source` in the schema, and a line in both configuration references.
15//! A third verb that destroys is either in this list or the class gate fails; it
16//! cannot be quietly correct the way `config init --force` was.
17//!
18//! # What counts as designation
19//!
20//! Naming the directory in argv designates it. Passing the waiver accepts an
21//! ambient one on purpose. Passing neither means the caller never saw the path
22//! about to be destroyed, which is the confused-deputy shape: the caller names
23//! the verb, the environment names the victim, and nothing compares the two.
24
25use crate::config::PathSource;
26use crate::error::{DestructiveEffect, ErrorDetail};
27
28/// One verb that destroys, with everything needed to refuse it safely.
29#[derive(Debug, Clone, Copy, PartialEq, Eq)]
30pub struct DestructiveVerb {
31 /// Invocation in wire spelling, as the refusal message names it.
32 pub wire: &'static str,
33 /// Flag that designates the target in argv.
34 pub target_flag: &'static str,
35 /// Flag that accepts an ambient target on purpose.
36 pub waiver_flag: &'static str,
37 /// What would happen to the target.
38 pub effect: DestructiveEffect,
39 /// Schema stem under `docs/schemas/`, which must carry `target_source`.
40 pub schema_stem: &'static str,
41}
42
43impl DestructiveVerb {
44 /// Whether this invocation must be refused for want of a designated target.
45 ///
46 /// Only [`PathSource::CliFlag`] counts as designation. `Xdg` is the ambient
47 /// layer the caller never named, and `Unresolved` is worse: there is no
48 /// target at all, so acting would be acting somewhere unknown.
49 pub fn must_refuse(self, waived: bool, source: PathSource) -> bool {
50 !waived && source != PathSource::CliFlag
51 }
52
53 /// The refusal, naming the victim and both ways out of it.
54 ///
55 /// The message names the target because a refusal that hides which path was
56 /// about to be destroyed teaches the caller nothing about what to pass.
57 pub fn refuse(self, target: String) -> ErrorDetail {
58 ErrorDetail::AmbientTargetRefused {
59 verb: self.wire.to_string(),
60 target,
61 target_flag: self.target_flag.to_string(),
62 waiver_flag: self.waiver_flag.to_string(),
63 effect: self.effect,
64 }
65 }
66}
67
68/// `cache clear` empties every cached body under the resolved cache root.
69pub const CACHE_CLEAR: DestructiveVerb = DestructiveVerb {
70 wire: "cache clear",
71 target_flag: "--cache-dir",
72 waiver_flag: "--yes",
73 effect: DestructiveEffect::Delete,
74 schema_stem: "cache-clear",
75};
76
77/// `config init --force` replaces an existing `config.toml` in place.
78///
79/// The waiver is required whenever the target is ambient, even where no file
80/// exists yet. The caller cannot know in advance whether a directory they never
81/// named holds a file, and that uncertainty is precisely the risk: a rule whose
82/// answer depends on the state of the disk gives the same argv two behaviours.
83pub const CONFIG_INIT_FORCE: DestructiveVerb = DestructiveVerb {
84 wire: "config init --force",
85 target_flag: "--config-dir",
86 waiver_flag: "--yes",
87 effect: DestructiveEffect::Overwrite,
88 schema_stem: "config-init",
89};
90
91/// Every verb in this binary that destroys something it did not create.
92///
93/// This is the list the class gate reads. Adding a destructive verb without
94/// adding it here fails `no_verb_that_destroys_escapes_the_register`.
95pub const fn destructive_verbs() -> &'static [DestructiveVerb] {
96 &[CACHE_CLEAR, CONFIG_INIT_FORCE]
97}