theirongolddev/gitlore
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(cli): Improve help text, error handling, and add fuzzy command suggestions

Browse Source 
CLI help improvements (cli/mod.rs):
- Add descriptive help text to all global flags (-c, --robot, -J, etc.)
- Add descriptions to all subcommands (Issues, Mrs, Sync, etc.)
- Add --no-quiet flag for explicit quiet override
- Shell completions now shows installation instructions for each shell
- Optional subcommand: running bare 'lore' shows help in terminal mode,
  robot-docs in robot mode

Structured clap error handling (main.rs):
- Early robot mode detection before parsing (env + args)
- JSON error output for parse failures in robot mode
- Semantic error codes: UNKNOWN_COMMAND, UNKNOWN_FLAG, MISSING_REQUIRED,
  INVALID_VALUE, ARGUMENT_CONFLICT, etc.
- Fuzzy command suggestion using Jaro-Winkler similarity (>0.7 threshold)
- Help/version requests handled normally (exit 0, not error)

Robot-docs enhancements (main.rs):
- Document deprecated command aliases (list issues -> issues, etc.)
- Document clap error codes for programmatic error handling
- Include completions command in manifest
- Update flag documentation to show short forms (-n, -s, -p, etc.)

Dependencies:
- Add strsim 0.11 for Jaro-Winkler fuzzy matching

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Taylor Eernisse
2026-02-05 11:22:38 -05:00
parent ab43bbd2db
commit c730b0ec54
5 changed files with 519 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
src/cli/mod.rs
View File

@@ -6,71 +6,127 @@ use std::io::IsTerminal;
#[derive(Parser)]
#[command(name = "lore")]
#[command(version, about, long_about = None)]
#[command(version, about = "Local GitLab data management with semantic search", long_about = None)]
#[command(subcommand_required = false)]
pub struct Cli {
#[arg(short = 'c', long, global = true)]
/// Path to config file
#[arg(short = 'c', long, global = true, help = "Path to config file")]
pub config: Option<String>,
#[arg(long, global = true, env = "LORE_ROBOT")]
/// Machine-readable JSON output (auto-enabled when piped)
#[arg(
long,
global = true,
env = "LORE_ROBOT",
help = "Machine-readable JSON output (auto-enabled when piped)"
)]
pub robot: bool,
#[arg(short = 'J', long = "json", global = true)]
/// JSON output (global shorthand)
#[arg(
short = 'J',
long = "json",
global = true,
help = "JSON output (global shorthand)"
)]
pub json: bool,
#[arg(long, global = true, value_parser = ["auto", "always", "never"], default_value = "auto")]
/// Color output: auto (default), always, or never
#[arg(long, global = true, value_parser = ["auto", "always", "never"], default_value = "auto", help = "Color output: auto (default), always, or never")]
pub color: String,
#[arg(short = 'q', long, global = true)]
/// Suppress non-essential output
#[arg(
short = 'q',
long,
global = true,
overrides_with = "no_quiet",
help = "Suppress non-essential output"
)]
pub quiet: bool,
#[arg(short = 'v', long = "verbose", action = clap::ArgAction::Count, global = true)]
#[arg(
long = "no-quiet",
global = true,
hide = true,
overrides_with = "quiet"
)]
pub no_quiet: bool,
/// Increase log verbosity (-v, -vv, -vvv)
#[arg(short = 'v', long = "verbose", action = clap::ArgAction::Count, global = true, help = "Increase log verbosity (-v, -vv, -vvv)")]
pub verbose: u8,
#[arg(long = "log-format", global = true, value_parser = ["text", "json"], default_value = "text")]
/// Log format for stderr output: text (default) or json
#[arg(long = "log-format", global = true, value_parser = ["text", "json"], default_value = "text", help = "Log format for stderr output: text (default) or json")]
pub log_format: String,
#[command(subcommand)]
pub command: Commands,
pub command: Option<Commands>,
}
impl Cli {
pub fn is_robot_mode(&self) -> bool {
self.robot || self.json || !std::io::stdout().is_terminal()
}
/// Detect robot mode from environment before parsing succeeds.
/// Used for structured error output when clap parsing fails.
pub fn detect_robot_mode_from_env() -> bool {
let args: Vec<String> = std::env::args().collect();
args.iter()
.any(|a| a == "--robot" || a == "-J" || a == "--json")
|| std::env::var("LORE_ROBOT").is_ok()
|| !std::io::stdout().is_terminal()
}
}
#[derive(Subcommand)]
#[allow(clippy::large_enum_variant)]
pub enum Commands {
/// List or show issues
Issues(IssuesArgs),
/// List or show merge requests
Mrs(MrsArgs),
/// Ingest data from GitLab
Ingest(IngestArgs),
/// Count entities in local database
Count(CountArgs),
/// Show sync state
Status,
/// Verify GitLab authentication
Auth,
/// Check environment health
Doctor,
/// Show version information
Version,
/// Initialize configuration and database
Init {
/// Skip overwrite confirmation
#[arg(short = 'f', long)]
force: bool,
/// Fail if prompts would be shown
#[arg(long)]
non_interactive: bool,
/// GitLab base URL (required in robot mode)
#[arg(long)]
gitlab_url: Option<String>,
/// Environment variable name holding GitLab token (required in robot mode)
#[arg(long)]
token_env_var: Option<String>,
/// Comma-separated project paths (required in robot mode)
#[arg(long)]
projects: Option<String>,
},
@@ -84,26 +140,41 @@ pub enum Commands {
yes: bool,
},
/// Search indexed documents
Search(SearchArgs),
/// Show document and index statistics
Stats(StatsArgs),
/// Generate searchable documents from ingested data
#[command(name = "generate-docs")]
GenerateDocs(GenerateDocsArgs),
/// Generate vector embeddings for documents via Ollama
Embed(EmbedArgs),
/// Run full sync pipeline: ingest -> generate-docs -> embed
Sync(SyncArgs),
/// Run pending database migrations
Migrate,
/// Quick health check: config, database, schema version
Health,
/// Machine-readable command manifest for agent self-discovery
#[command(name = "robot-docs")]
RobotDocs,
#[command(hide = true)]
/// Generate shell completions
#[command(long_about = "Generate shell completions for lore.\n\n\
Installation:\n \
bash: lore completions bash > ~/.local/share/bash-completion/completions/lore\n \
zsh: lore completions zsh > ~/.zfunc/_lore && echo 'fpath+=~/.zfunc' >> ~/.zshrc\n \
fish: lore completions fish > ~/.config/fish/completions/lore.fish\n \
pwsh: lore completions powershell >> $PROFILE")]
Completions {
/// Shell to generate completions for
#[arg(value_parser = ["bash", "zsh", "fish", "powershell"])]
shell: String,
},
@@ -171,8 +242,10 @@ pub enum Commands {
#[derive(Parser)]
pub struct IssuesArgs {
/// Issue IID (omit to list, provide to show details)
pub iid: Option<i64>,
/// Maximum results
#[arg(
short = 'n',
long = "limit",
@@ -181,30 +254,43 @@ pub struct IssuesArgs {
)]
pub limit: usize,
/// Select output fields (comma-separated: iid,title,state,author,labels,updated)
#[arg(long, help_heading = "Output", value_delimiter = ',')]
pub fields: Option<Vec<String>>,
/// Filter by state (opened, closed, all)
#[arg(short = 's', long, help_heading = "Filters")]
pub state: Option<String>,
/// Filter by project path
#[arg(short = 'p', long, help_heading = "Filters")]
pub project: Option<String>,
/// Filter by author username
#[arg(short = 'a', long, help_heading = "Filters")]
pub author: Option<String>,
/// Filter by assignee username
#[arg(short = 'A', long, help_heading = "Filters")]
pub assignee: Option<String>,
/// Filter by label (repeatable, AND logic)
#[arg(short = 'l', long, help_heading = "Filters")]
pub label: Option<Vec<String>>,
/// Filter by milestone title
#[arg(short = 'm', long, help_heading = "Filters")]
pub milestone: Option<String>,
/// Filter by time (7d, 2w, 1m, or YYYY-MM-DD)
#[arg(long, help_heading = "Filters")]
pub since: Option<String>,
/// Filter by due date (before this date, YYYY-MM-DD)
#[arg(long = "due-before", help_heading = "Filters")]
pub due_before: Option<String>,
/// Show only issues with a due date
#[arg(
long = "has-due",
help_heading = "Filters",
@@ -215,15 +301,18 @@ pub struct IssuesArgs {
#[arg(long = "no-has-due", hide = true, overrides_with = "has_due")]
pub no_has_due: bool,
/// Sort field (updated, created, iid)
#[arg(long, value_parser = ["updated", "created", "iid"], default_value = "updated", help_heading = "Sorting")]
pub sort: String,
/// Sort ascending (default: descending)
#[arg(long, help_heading = "Sorting", overrides_with = "no_asc")]
pub asc: bool,
#[arg(long = "no-asc", hide = true, overrides_with = "asc")]
pub no_asc: bool,
/// Open first matching item in browser
#[arg(
short = 'o',
long,
@@ -238,8 +327,10 @@ pub struct IssuesArgs {
#[derive(Parser)]
pub struct MrsArgs {
/// MR IID (omit to list, provide to show details)
pub iid: Option<i64>,
/// Maximum results
#[arg(
short = 'n',
long = "limit",
@@ -248,27 +339,39 @@ pub struct MrsArgs {
)]
pub limit: usize,
/// Select output fields (comma-separated: iid,title,state,author,labels,updated)
#[arg(long, help_heading = "Output", value_delimiter = ',')]
pub fields: Option<Vec<String>>,
/// Filter by state (opened, merged, closed, locked, all)
#[arg(short = 's', long, help_heading = "Filters")]
pub state: Option<String>,
/// Filter by project path
#[arg(short = 'p', long, help_heading = "Filters")]
pub project: Option<String>,
/// Filter by author username
#[arg(short = 'a', long, help_heading = "Filters")]
pub author: Option<String>,
/// Filter by assignee username
#[arg(short = 'A', long, help_heading = "Filters")]
pub assignee: Option<String>,
/// Filter by reviewer username
#[arg(short = 'r', long, help_heading = "Filters")]
pub reviewer: Option<String>,
/// Filter by label (repeatable, AND logic)
#[arg(short = 'l', long, help_heading = "Filters")]
pub label: Option<Vec<String>>,
/// Filter by time (7d, 2w, 1m, or YYYY-MM-DD)
#[arg(long, help_heading = "Filters")]
pub since: Option<String>,
/// Show only draft MRs
#[arg(
short = 'd',
long,
@@ -277,6 +380,7 @@ pub struct MrsArgs {
)]
pub draft: bool,
/// Exclude draft MRs
#[arg(
short = 'D',
long = "no-draft",
@@ -285,21 +389,26 @@ pub struct MrsArgs {
)]
pub no_draft: bool,
/// Filter by target branch
#[arg(long, help_heading = "Filters")]
pub target: Option<String>,
/// Filter by source branch
#[arg(long, help_heading = "Filters")]
pub source: Option<String>,
/// Sort field (updated, created, iid)
#[arg(long, value_parser = ["updated", "created", "iid"], default_value = "updated", help_heading = "Sorting")]
pub sort: String,
/// Sort ascending (default: descending)
#[arg(long, help_heading = "Sorting", overrides_with = "no_asc")]
pub asc: bool,
#[arg(long = "no-asc", hide = true, overrides_with = "asc")]
pub no_asc: bool,
/// Open first matching item in browser
#[arg(
short = 'o',
long,
@@ -314,65 +423,95 @@ pub struct MrsArgs {
#[derive(Parser)]
pub struct IngestArgs {
/// Entity to ingest (issues, mrs). Omit to ingest everything
#[arg(value_parser = ["issues", "mrs"])]
pub entity: Option<String>,
/// Filter to single project
#[arg(short = 'p', long)]
pub project: Option<String>,
/// Override stale sync lock
#[arg(short = 'f', long, overrides_with = "no_force")]
pub force: bool,
#[arg(long = "no-force", hide = true, overrides_with = "force")]
pub no_force: bool,
/// Full re-sync: reset cursors and fetch all data from scratch
#[arg(long, overrides_with = "no_full")]
pub full: bool,
#[arg(long = "no-full", hide = true, overrides_with = "full")]
pub no_full: bool,
/// Preview what would be synced without making changes
#[arg(long, overrides_with = "no_dry_run")]
pub dry_run: bool,
#[arg(long = "no-dry-run", hide = true, overrides_with = "dry_run")]
pub no_dry_run: bool,
}
#[derive(Parser)]
pub struct StatsArgs {
/// Run integrity checks
#[arg(long, overrides_with = "no_check")]
pub check: bool,
#[arg(long = "no-check", hide = true, overrides_with = "check")]
pub no_check: bool,
/// Repair integrity issues (auto-enables --check)
#[arg(long)]
pub repair: bool,
/// Preview what would be repaired without making changes (requires --repair)
#[arg(long, overrides_with = "no_dry_run")]
pub dry_run: bool,
#[arg(long = "no-dry-run", hide = true, overrides_with = "dry_run")]
pub no_dry_run: bool,
}
#[derive(Parser)]
pub struct SearchArgs {
/// Search query string
pub query: String,
/// Search mode (lexical, hybrid, semantic)
#[arg(long, default_value = "hybrid", value_parser = ["lexical", "hybrid", "semantic"], help_heading = "Output")]
pub mode: String,
/// Filter by source type (issue, mr, discussion)
#[arg(long = "type", value_name = "TYPE", value_parser = ["issue", "mr", "discussion"], help_heading = "Filters")]
pub source_type: Option<String>,
/// Filter by author username
#[arg(long, help_heading = "Filters")]
pub author: Option<String>,
/// Filter by project path
#[arg(short = 'p', long, help_heading = "Filters")]
pub project: Option<String>,
/// Filter by label (repeatable, AND logic)
#[arg(long, action = clap::ArgAction::Append, help_heading = "Filters")]
pub label: Vec<String>,
/// Filter by file path (trailing / for prefix match)
#[arg(long, help_heading = "Filters")]
pub path: Option<String>,
/// Filter by created after (7d, 2w, or YYYY-MM-DD)
#[arg(long, help_heading = "Filters")]
pub after: Option<String>,
/// Filter by updated after (7d, 2w, or YYYY-MM-DD)
#[arg(long = "updated-after", help_heading = "Filters")]
pub updated_after: Option<String>,
/// Maximum results (default 20, max 100)
#[arg(
short = 'n',
long = "limit",
@@ -381,57 +520,75 @@ pub struct SearchArgs {
)]
pub limit: usize,
/// Show ranking explanation per result
#[arg(long, help_heading = "Output", overrides_with = "no_explain")]
pub explain: bool,
#[arg(long = "no-explain", hide = true, overrides_with = "explain")]
pub no_explain: bool,
/// FTS query mode: safe (default) or raw
#[arg(long = "fts-mode", default_value = "safe", value_parser = ["safe", "raw"], help_heading = "Output")]
pub fts_mode: String,
}
#[derive(Parser)]
pub struct GenerateDocsArgs {
/// Full rebuild: seed all entities into dirty queue, then drain
#[arg(long)]
pub full: bool,
/// Filter to single project
#[arg(short = 'p', long)]
pub project: Option<String>,
}
#[derive(Parser)]
pub struct SyncArgs {
/// Reset cursors, fetch everything
#[arg(long, overrides_with = "no_full")]
pub full: bool,
#[arg(long = "no-full", hide = true, overrides_with = "full")]
pub no_full: bool,
/// Override stale lock
#[arg(long, overrides_with = "no_force")]
pub force: bool,
#[arg(long = "no-force", hide = true, overrides_with = "force")]
pub no_force: bool,
/// Skip embedding step
#[arg(long)]
pub no_embed: bool,
/// Skip document regeneration
#[arg(long)]
pub no_docs: bool,
/// Skip resource event fetching (overrides config)
#[arg(long = "no-events")]
pub no_events: bool,
/// Preview what would be synced without making changes
#[arg(long, overrides_with = "no_dry_run")]
pub dry_run: bool,
#[arg(long = "no-dry-run", hide = true, overrides_with = "dry_run")]
pub no_dry_run: bool,
}
#[derive(Parser)]
pub struct EmbedArgs {
/// Re-embed all documents (clears existing embeddings first)
#[arg(long, overrides_with = "no_full")]
pub full: bool,
#[arg(long = "no-full", hide = true, overrides_with = "full")]
pub no_full: bool,
/// Retry previously failed embeddings
#[arg(long, overrides_with = "no_retry_failed")]
pub retry_failed: bool,
@@ -441,9 +598,11 @@ pub struct EmbedArgs {
#[derive(Parser)]
pub struct CountArgs {
/// Entity type to count (issues, mrs, discussions, notes, events)
#[arg(value_parser = ["issues", "mrs", "discussions", "notes", "events"])]
pub entity: String,
/// Parent type filter: issue or mr (for discussions/notes)
#[arg(short = 'f', long = "for", value_parser = ["issue", "mr"])]
pub for_entity: Option<String>,
}