heddle-cli 0.2.3

An AI-native version control system
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

// SPDX-License-Identifier: Apache-2.0
//! Base CLI flags.
//!
//! ## Short-flag conventions
//!
//! The CLI is small and the short forms have to mean the same thing
//! everywhere they appear. The table below is the source of truth — new
//! verbs should reuse these letters before claiming new ones. Verbs that
//! diverge (e.g. `-n` for `--steps` on `undo`/`redo` vs `--limit` on
//! `log`/`list`) keep the muscle memory consistent within the verb's own
//! family: "n" is always "how many," "m" is always "message."
//!
//! | Short | Long(s)                           | Used by                       |
//! |-------|-----------------------------------|-------------------------------|
//! | `-m`  | `--message`, `--intent`           | capture, merge, revert,       |
//! |       |                                   | cherry-pick, checkpoint,      |
//! |       |                                   | stash push, context set/edit, |
//! |       |                                   | discuss append                |
//! | `-n`  | `--limit` (queries),              | log, list, query (limit);     |
//! |       | `--steps` (undo/redo)             | undo, redo (steps)            |
//! | `-f`  | `--force`                         | capture, push, goto, clean,   |
//! |       |                                   | cherry-pick, rebase           |
//! | `-s`  | `--short`                         | status                        |
//! | `-U`  | `--unified`                       | diff                          |
//! | `-v`  | `--verbose` (repeatable)          | global                        |
//! | `-q`  | `--quiet`                         | global                        |
//!
//! Renames are out of scope — scripts written against the surface MUST
//! keep working. Add a new short alias only when the letter is already
//! reserved for that semantic in the table above.

use clap::{Parser, ValueEnum};

use super::Commands;

/// Heddle: An AI-native version control system.
#[derive(Parser)]
#[command(name = "heddle")]
#[command(author, version, about, long_about = None)]
// We ship our own `Help` subcommand (curated everyday/advanced
// surface + topic pages). clap's auto-generated `help` subcommand
// would shadow it; turn it off so `heddle help [topic]` reaches our
// printer instead.
#[command(disable_help_subcommand = true)]
pub struct Cli {
    #[command(subcommand)]
    pub command: Commands,

    /// Output JSON (deprecated; use `--output json`).
    ///
    /// Still functional — both forms route to JSON. Kept for compatibility
    /// with scripts and agent harnesses written against the old surface.
    /// Emits a one-shot stderr warning on first use within a process.
    #[arg(long, global = true, hide = true)]
    pub json: bool,

    /// Output format. `auto` (default) renders text on a TTY and JSON when piped;
    /// `json` and `text` override regardless of stream.
    #[arg(long, global = true, value_enum)]
    pub output: Option<OutputMode>,

    /// Disable colored output.
    #[arg(long, global = true)]
    pub no_color: bool,

    /// Repository path (default: find .heddle in ancestors).
    #[arg(long, global = true)]
    pub repo: Option<std::path::PathBuf>,

    /// Increase verbosity.
    #[arg(short, long, global = true, action = clap::ArgAction::Count)]
    pub verbose: u8,

    /// Decrease verbosity.
    #[arg(short, long, global = true)]
    pub quiet: bool,

    /// Client-supplied operation id (UUID v4) for idempotent retries.
    ///
    /// State-changing verbs that pass this id to the dedup store
    /// return the original outcome on replay. Unset by default; agents
    /// supply one explicitly. Honoured for any state-changing verb that
    /// has been wired through the dedup store. Also reads
    /// `HEDDLE_OPERATION_ID` from the environment.
    ///
    /// Hidden from default `--help` to keep the human surface uncluttered;
    /// see `heddle help operation-ids` for the full agent-facing contract.
    #[arg(long, global = true, env = "HEDDLE_OPERATION_ID", hide = true)]
    pub op_id: Option<String>,
}

#[derive(Copy, Clone, Debug, ValueEnum)]
pub enum OutputMode {
    Auto,
    Json,
    Text,
}