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}