ralph/cli/task/args/
template.rs

1//! CLI arguments for task template commands.
2//!
3//! Responsibilities:
4//! - Define Args structs for template commands and from-template commands.
5//! - Define TaskTemplateCommand and TaskFromCommand enums.
6//!
7//! Not handled here:
8//! - Command execution (see template and from_template handlers).
9//!
10//! Invariants/assumptions:
11//! - All types must be Clone where needed for clap.
12
13use clap::{Args, Subcommand};
14
15use crate::agent;
16
17#[derive(Args)]
18pub struct TaskTemplateArgs {
19    #[command(subcommand)]
20    pub command: TaskTemplateCommand,
21}
22
23/// Arguments for `ralph task from` command (parent of template subcommand).
24#[derive(Args)]
25pub struct TaskFromArgs {
26    #[command(subcommand)]
27    pub command: TaskFromCommand,
28}
29
30/// Subcommands for `ralph task from`
31#[derive(Subcommand)]
32pub enum TaskFromCommand {
33    /// Build a task from a template with variable substitution.
34    ///
35    /// This is a convenience command that combines template selection,
36    /// variable substitution, and task creation in one step.
37    #[command(after_long_help = "Examples:
38  ralph task from template bug --title \"Fix login timeout\"
39  ralph task from template feature --title \"Add dark mode\" --set target=src/ui/theme.rs
40  ralph task from template add-tests --title \"Test auth module\" --set target=src/auth/mod.rs
41  ralph task from template refactor-performance --title \"Optimize parser\" --set target=src/parser/
42  ralph task from template custom-template --title \"Custom task\" --set component=auth
43
44Template variables:
45  {{target}}  - Target file/path (set via --set target=... or positional TARGET)
46  {{module}}  - Derived module name (e.g., src/cli/task.rs -> cli::task)
47  {{file}}    - Filename only (e.g., task.rs)
48  {{branch}}  - Current git branch name
49
50Use 'ralph task template list' to see available templates.
51Use 'ralph task template show <name>' to view template details.")]
52    Template(TaskFromTemplateArgs),
53}
54
55/// Arguments for `ralph task from template` command.
56#[derive(Args)]
57pub struct TaskFromTemplateArgs {
58    /// Template name (e.g., bug, feature, refactor, add-tests)
59    pub template: String,
60
61    /// Task title (required)
62    #[arg(long = "title")]
63    pub title: String,
64
65    /// Set template variable (repeatable, format: VAR=value)
66    /// Supported: target=PATH, component=NAME, or any custom variable used in the template
67    #[arg(long = "set", value_name = "VAR=VALUE")]
68    pub variables: Vec<String>,
69
70    /// Additional tags to add (comma-separated)
71    #[arg(short, long)]
72    pub tags: Option<String>,
73
74    /// Runner to use
75    #[arg(long)]
76    pub runner: Option<String>,
77
78    /// Model to use
79    #[arg(long)]
80    pub model: Option<String>,
81
82    /// Reasoning effort (Codex only)
83    #[arg(short = 'e', long)]
84    pub effort: Option<String>,
85
86    /// RepoPrompt mode (tools, plan, off)
87    #[arg(long = "repo-prompt", value_enum, value_name = "MODE")]
88    pub repo_prompt: Option<agent::RepoPromptMode>,
89
90    #[command(flatten)]
91    pub runner_cli: agent::RunnerCliArgs,
92
93    /// Fail on unknown template variables
94    #[arg(long)]
95    pub strict_templates: bool,
96
97    /// Preview task without adding to queue
98    #[arg(long)]
99    pub dry_run: bool,
100}
101
102#[derive(Subcommand)]
103#[allow(clippy::large_enum_variant)]
104pub enum TaskTemplateCommand {
105    /// List available task templates
106    List,
107    /// Show template details
108    Show(TaskTemplateShowArgs),
109    /// Build a task from a template
110    Build(TaskTemplateBuildArgs),
111}
112
113#[derive(Args)]
114pub struct TaskTemplateShowArgs {
115    /// Template name (e.g., "bug", "feature")
116    pub name: String,
117}
118
119#[derive(Args)]
120pub struct TaskTemplateBuildArgs {
121    /// Template name
122    pub template: String,
123
124    /// Target file/path for template variable substitution ({{target}}, {{module}}, {{file}}).
125    /// Used to auto-fill template variables with context from the specified path.
126    #[arg(value_name = "TARGET")]
127    pub target: Option<String>,
128
129    /// Task title/request
130    pub request: Vec<String>,
131
132    /// Additional tags to merge
133    #[arg(short, long)]
134    pub tags: Option<String>,
135
136    /// Additional scope to merge
137    #[arg(short, long)]
138    pub scope: Option<String>,
139
140    /// Runner to use. CLI flag overrides config defaults (project > global > built-in).
141    #[arg(long)]
142    pub runner: Option<String>,
143
144    /// Model to use. CLI flag overrides config defaults (project > global > built-in).
145    #[arg(long)]
146    pub model: Option<String>,
147
148    /// Codex reasoning effort. CLI flag overrides config defaults (project > global > built-in).
149    /// Ignored for opencode and gemini.
150    #[arg(short = 'e', long)]
151    pub effort: Option<String>,
152
153    /// RepoPrompt mode (tools, plan, off). Alias: -rp.
154    #[arg(long = "repo-prompt", value_enum, value_name = "MODE")]
155    pub repo_prompt: Option<agent::RepoPromptMode>,
156
157    #[command(flatten)]
158    pub runner_cli: agent::RunnerCliArgs,
159
160    /// Fail on unknown template variables (default: warn only).
161    /// When enabled, template loading fails if the template contains unknown {{variables}}.
162    /// When disabled (default), unknown variables are left as-is with a warning.
163    #[arg(long)]
164    pub strict_templates: bool,
165}
ralph/cli/task/args/template.rs

ralph/cli/task/args/
template.rs
