truth_mirror/
cli.rs

1use std::path::PathBuf;
2
3use clap::{ArgGroup, Args, Parser, Subcommand, ValueEnum};
4use serde::{Deserialize, Serialize};
5
6#[derive(Debug, Parser)]
7#[command(
8    name = "truth-mirror",
9    version,
10    about = "Truthfulness gate and reviewer harness for coding agents.",
11    propagate_version = true
12)]
13pub struct Cli {
14    #[arg(
15        long,
16        global = true,
17        env = "TRUTH_MIRROR_STATE_DIR",
18        default_value = ".truth-mirror",
19        value_name = "DIR"
20    )]
21    pub state_dir: PathBuf,
22
23    #[arg(long, global = true, env = "TRUTH_MIRROR_CONFIG", value_name = "FILE")]
24    pub config: Option<PathBuf>,
25
26    #[command(subcommand)]
27    pub command: Commands,
28}
29
30#[derive(Debug, Subcommand)]
31pub enum Commands {
32    /// Install, uninstall, or preview agent hook shims.
33    InstallHooks(InstallHooksArgs),
34    /// Review a commit or the staged diff with a separate reviewer model.
35    Review(ReviewArgs),
36    /// Run deterministic repository gates.
37    Gate(GateArgs),
38    /// Reinject unresolved findings into an agent prompt surface.
39    Reinject(ReinjectArgs),
40    /// Inspect or update the dual ledger.
41    Ledger(LedgerArgs),
42    /// Run the post-commit reviewer loop.
43    Watch(WatchArgs),
44    /// Print or install the embedded truth-mirror skill document.
45    Skills(SkillsArgs),
46    /// Internal git hook dispatcher.
47    #[command(hide = true)]
48    HookDispatch(HookDispatchArgs),
49}
50
51#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize, ValueEnum)]
52#[serde(rename_all = "kebab-case")]
53pub enum Agent {
54    Claude,
55    Codex,
56    Pi,
57}
58
59#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize, ValueEnum)]
60#[serde(rename_all = "kebab-case")]
61pub enum ReviewerHarness {
62    Claude,
63    Codex,
64    Pi,
65    Gemini,
66    Opencode,
67    Custom,
68}
69
70#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize, ValueEnum)]
71#[serde(rename_all = "kebab-case")]
72pub enum ReviewScope {
73    Commit,
74    Staged,
75    Auto,
76    WorkingTree,
77    Branch,
78}
79
80#[derive(Debug, Args)]
81pub struct InstallHooksArgs {
82    #[arg(long)]
83    pub claude: bool,
84
85    #[arg(long)]
86    pub codex: bool,
87
88    #[arg(long)]
89    pub pi: bool,
90
91    #[arg(long)]
92    pub uninstall: bool,
93
94    #[arg(long)]
95    pub dry_run: bool,
96}
97
98#[derive(Debug, Args)]
99pub struct ReviewArgs {
100    #[command(subcommand)]
101    pub command: Option<ReviewCommand>,
102
103    #[arg(value_name = "SHA", conflicts_with = "staged")]
104    pub target: Option<String>,
105
106    #[arg(long)]
107    pub staged: bool,
108
109    #[arg(long, value_enum, value_name = "SCOPE", default_value_t = ReviewScope::Commit)]
110    pub scope: ReviewScope,
111
112    #[arg(long, value_name = "REF")]
113    pub base: Option<String>,
114
115    #[arg(long, value_enum, value_name = "AGENT")]
116    pub watched_agent: Option<Agent>,
117
118    #[arg(long, value_enum, value_name = "HARNESS")]
119    pub reviewer_harness: Option<ReviewerHarness>,
120
121    #[arg(long, value_name = "MODEL")]
122    pub watched_model: Option<String>,
123
124    #[arg(long, value_name = "MODEL")]
125    pub reviewer_model: Option<String>,
126
127    #[arg(long, value_enum, value_name = "EFFORT")]
128    pub reviewer_effort: Option<crate::config::Effort>,
129
130    #[arg(long)]
131    pub allow_same_model: bool,
132
133    #[arg(long)]
134    pub strict_two_pass: bool,
135
136    #[arg(long, value_enum, value_name = "HARNESS")]
137    pub arbiter_harness: Option<ReviewerHarness>,
138
139    #[arg(long, value_name = "MODEL")]
140    pub arbiter_model: Option<String>,
141
142    #[arg(long, value_enum, value_name = "EFFORT")]
143    pub arbiter_effort: Option<crate::config::Effort>,
144
145    /// Sic the adversarial reviewer in a loop until N lies or N fuckups.
146    #[arg(long)]
147    pub strict_goal: bool,
148
149    #[arg(long, value_name = "N")]
150    pub stop_after_lies: Option<u32>,
151
152    #[arg(long, value_name = "N")]
153    pub stop_after_fuckups: Option<u32>,
154
155    #[arg(long, value_name = "N")]
156    pub max_passes: Option<u32>,
157}
158
159#[derive(Debug, Subcommand)]
160pub enum ReviewCommand {
161    /// Show tracked review run status, or all known runs when no id is provided.
162    Status {
163        #[arg(value_name = "RUN_ID")]
164        run_id: Option<String>,
165    },
166    /// Show the latest completed/failed review run, or a specific run.
167    Result {
168        #[arg(value_name = "RUN_ID")]
169        run_id: Option<String>,
170    },
171    /// Cancel a queued review run and remove it from the review queue.
172    Cancel {
173        #[arg(value_name = "RUN_ID")]
174        run_id: String,
175    },
176}
177
178#[derive(Debug, Args)]
179#[command(group(
180    ArgGroup::new("gate_mode")
181        .required(true)
182        .args(["pre_push", "commit_msg", "pre_tool_use"])
183))]
184pub struct GateArgs {
185    #[arg(long, value_name = "RANGE", conflicts_with = "commit_msg")]
186    pub pre_push: Option<String>,
187
188    #[arg(long, value_name = "FILE", conflicts_with = "pre_push")]
189    pub commit_msg: Option<PathBuf>,
190
191    #[arg(long, value_name = "FILE", requires = "commit_msg")]
192    pub claim_file: Option<PathBuf>,
193
194    #[arg(long, value_name = "FILE", requires = "commit_msg")]
195    pub diff_file: Option<PathBuf>,
196
197    #[arg(long = "fake-marker", value_name = "TOKEN", requires = "commit_msg")]
198    pub fake_markers: Vec<String>,
199
200    /// Enforcement gate: block a mutating tool call when the ledger has unresolved
201    /// rejections beyond the configured threshold.
202    #[arg(long, conflicts_with_all = ["pre_push", "commit_msg"])]
203    pub pre_tool_use: bool,
204
205    /// The tool name being gated (for `--pre-tool-use`).
206    #[arg(long, value_name = "NAME", requires = "pre_tool_use")]
207    pub tool: Option<String>,
208}
209
210#[derive(Debug, Args)]
211pub struct ReinjectArgs {
212    #[arg(long, value_enum)]
213    pub agent: Agent,
214}
215
216#[derive(Debug, Args)]
217pub struct LedgerArgs {
218    #[command(subcommand)]
219    pub command: LedgerCommand,
220}
221
222#[derive(Debug, Subcommand)]
223pub enum LedgerCommand {
224    List,
225    Show {
226        #[arg(value_name = "SHA")]
227        sha: String,
228    },
229    Resolve {
230        #[arg(value_name = "SHA")]
231        sha: String,
232    },
233    Waive {
234        #[arg(value_name = "SHA")]
235        sha: String,
236
237        #[arg(long, value_name = "REASON")]
238        reason: String,
239    },
240    Stats,
241}
242
243#[derive(Debug, Args)]
244pub struct WatchArgs {
245    #[arg(long, value_enum, value_name = "AGENT")]
246    pub watched_agent: Option<Agent>,
247
248    #[arg(long, value_enum, value_name = "HARNESS")]
249    pub reviewer_harness: Option<ReviewerHarness>,
250
251    #[arg(long, value_name = "MODEL")]
252    pub watched_model: Option<String>,
253
254    #[arg(long, value_name = "MODEL")]
255    pub reviewer_model: Option<String>,
256
257    #[arg(long, value_enum, value_name = "EFFORT")]
258    pub reviewer_effort: Option<crate::config::Effort>,
259
260    #[arg(long)]
261    pub allow_same_model: bool,
262
263    /// Drain the review queue exactly once and exit (deterministic; used in CI).
264    #[arg(long)]
265    pub once: bool,
266
267    /// Poll interval in seconds when running as a daemon (ignored with --once).
268    #[arg(long, value_name = "SECONDS", default_value_t = 5)]
269    pub poll_secs: u64,
270}
271
272#[derive(Debug, Args)]
273pub struct SkillsArgs {
274    #[command(subcommand)]
275    pub command: SkillsCommand,
276}
277
278#[derive(Debug, Subcommand)]
279pub enum SkillsCommand {
280    /// Print the embedded skill document to stdout.
281    Echo,
282    /// Write the skill document to <dir>/truth-mirror/SKILL.md.
283    Install {
284        /// Target skills directory (defaults to `.agents/skills`).
285        #[arg(long, value_name = "PATH")]
286        dir: Option<PathBuf>,
287
288        /// Overwrite an existing skill file.
289        #[arg(long)]
290        force: bool,
291    },
292}
293
294#[derive(Debug, Args)]
295pub struct HookDispatchArgs {
296    #[arg(value_enum)]
297    pub hook: HookName,
298
299    #[arg(value_name = "ARGS")]
300    pub args: Vec<String>,
301}
302
303#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
304#[value(rename_all = "kebab-case")]
305pub enum HookName {
306    CommitMsg,
307    PostCommit,
308    PrePush,
309}
310
311impl HookName {
312    pub fn as_str(self) -> &'static str {
313        match self {
314            Self::CommitMsg => "commit-msg",
315            Self::PostCommit => "post-commit",
316            Self::PrePush => "pre-push",
317        }
318    }
319}
320
321#[cfg(test)]
322mod tests {
323    use clap::CommandFactory;
324
325    use super::Cli;
326
327    #[test]
328    fn clap_contract_is_valid() {
329        Cli::command().debug_assert();
330    }
331}
truth_mirror/cli.rs

truth_mirror/
cli.rs
