Skip to main content

spec_driven_docs/cli/
stage.rs

1//! `stage` subcommand: parse-shape.
2//!
3//! Holds the clap derive structs only. No I/O, no business logic.
4
5use camino::Utf8PathBuf;
6
7use crate::domain::profile::ProfileId;
8
9/// Render this binary's candidate into a stage an agent reads.
10#[derive(Debug, clap::Args)]
11pub struct StageArgs {
12    /// What to do. Rendering a stage is the default.
13    #[command(subcommand)]
14    pub command: Option<StageCommand>,
15
16    /// The repository to render a candidate for; absolute, or the working directory.
17    #[arg(long, default_value = ".")]
18    pub target: Utf8PathBuf,
19
20    /// The profile to project: the recorded one where an instance exists,
21    /// which a different value refuses; codebase where nothing is recorded.
22    #[arg(long, value_enum)]
23    pub profile: Option<ProfileId>,
24
25    /// Where to write the stage; absolute.
26    #[arg(long)]
27    pub output: Option<Utf8PathBuf>,
28
29    /// The documentation scratch the candidate would record, or `none`.
30    #[arg(long)]
31    pub docs_scratch: Option<String>,
32
33    /// A path to record under `reserved:` in the declaration. Repeatable.
34    #[arg(long)]
35    pub reserve: Vec<String>,
36
37    /// The writing-style selection the candidate would record, unless the
38    /// declaration already holds it; a missing key holds `builtin`.
39    #[arg(long)]
40    pub writing_style: Option<String>,
41
42    /// Record that every host installs sdd itself, at this release or newer,
43    /// where no manager file pins it.
44    #[arg(long, value_enum)]
45    pub acquisition: Option<AcquisitionChoice>,
46
47    /// Print one JSON object instead of text.
48    #[arg(long)]
49    pub json: bool,
50}
51
52/// How the project obtains `sdd`, where no manager file records it.
53#[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum)]
54pub enum AcquisitionChoice {
55    /// Each host installs `sdd` itself.
56    Host,
57}
58
59/// The verbs `sdd stage` offers beyond rendering one.
60#[derive(Debug, clap::Subcommand)]
61pub enum StageCommand {
62    /// Remove one stage this tool wrote.
63    Clean(StageCleanArgs),
64    /// Compare one stage against its target, one row per destination.
65    Compare(StageCompareArgs),
66}
67
68/// Compare one stage against the target it was rendered for.
69#[derive(Debug, clap::Args)]
70pub struct StageCompareArgs {
71    /// The stage directory to read; absolute.
72    pub root: Utf8PathBuf,
73
74    /// The repository the stage was rendered for; absolute, or the working
75    /// directory.
76    #[arg(long, default_value = ".")]
77    pub target: Utf8PathBuf,
78
79    /// Print one JSON object instead of text.
80    #[arg(long)]
81    pub json: bool,
82}
83
84/// Remove one stage this tool wrote.
85#[derive(Debug, clap::Args)]
86pub struct StageCleanArgs {
87    /// The stage directory to remove; absolute.
88    pub path: Utf8PathBuf,
89
90    /// Print one JSON object instead of text.
91    #[arg(long)]
92    pub json: bool,
93}