Wave 2: CLI skeleton, cache write, config system, spec indexer (bd-3d2, bd-1ie, bd-1sb, bd-189)

src/cli/aliases.rs

@@ -0,0 +1,23 @@
+use clap::Args as ClapArgs;
+
+use crate::errors::SwaggerCliError;
+
+/// Manage spec aliases
+#[derive(Debug, ClapArgs)]
+pub struct Args {
+    /// List all aliases
+    #[arg(long)]
+    pub list: bool,
+
+    /// Remove an alias
+    #[arg(long)]
+    pub remove: Option<String>,
+
+    /// Rename an alias (old=new)
+    #[arg(long)]
+    pub rename: Option<String>,
+}
+
+pub async fn execute(_args: &Args, _robot: bool) -> Result<(), SwaggerCliError> {
+    Err(SwaggerCliError::Usage("aliases not yet implemented".into()))
+}

src/cli/cache_cmd.rs

@@ -0,0 +1,23 @@
+use clap::Args as ClapArgs;
+
+use crate::errors::SwaggerCliError;
+
+/// Manage the spec cache
+#[derive(Debug, ClapArgs)]
+pub struct Args {
+    /// Show cache location
+    #[arg(long)]
+    pub path: bool,
+
+    /// Clear the entire cache
+    #[arg(long)]
+    pub clear: bool,
+
+    /// Show cache size
+    #[arg(long)]
+    pub size: bool,
+}
+
+pub async fn execute(_args: &Args, _robot: bool) -> Result<(), SwaggerCliError> {
+    Err(SwaggerCliError::Usage("cache not yet implemented".into()))
+}

src/cli/diff.rs

@@ -0,0 +1,18 @@
+use clap::Args as ClapArgs;
+
+use crate::errors::SwaggerCliError;
+
+/// Compare two versions of a spec
+#[derive(Debug, ClapArgs)]
+pub struct Args {
+    /// Alias of the spec to diff
+    pub alias: String,
+
+    /// Revision to compare against (default: previous)
+    #[arg(long)]
+    pub rev: Option<String>,
+}
+
+pub async fn execute(_args: &Args, _robot: bool) -> Result<(), SwaggerCliError> {
+    Err(SwaggerCliError::Usage("diff not yet implemented".into()))
+}

src/cli/doctor.rs

@@ -0,0 +1,15 @@
+use clap::Args as ClapArgs;
+
+use crate::errors::SwaggerCliError;
+
+/// Check cache health and diagnose issues
+#[derive(Debug, ClapArgs)]
+pub struct Args {
+    /// Attempt to fix issues automatically
+    #[arg(long)]
+    pub fix: bool,
+}
+
+pub async fn execute(_args: &Args, _robot: bool) -> Result<(), SwaggerCliError> {
+    Err(SwaggerCliError::Usage("doctor not yet implemented".into()))
+}

src/cli/fetch.rs

@@ -0,0 +1,26 @@
+use clap::Args as ClapArgs;
+
+use crate::errors::SwaggerCliError;
+
+/// Fetch and cache an OpenAPI spec
+#[derive(Debug, ClapArgs)]
+pub struct Args {
+    /// URL of the OpenAPI spec
+    pub url: String,
+
+    /// Alias for the cached spec
+    #[arg(long)]
+    pub alias: Option<String>,
+
+    /// Overwrite existing alias
+    #[arg(long)]
+    pub force: bool,
+
+    /// Auth profile name from config
+    #[arg(long)]
+    pub auth: Option<String>,
+}
+
+pub async fn execute(_args: &Args, _robot: bool) -> Result<(), SwaggerCliError> {
+    Err(SwaggerCliError::Usage("fetch not yet implemented".into()))
+}

src/cli/list.rs

@@ -0,0 +1,26 @@
+use clap::Args as ClapArgs;
+
+use crate::errors::SwaggerCliError;
+
+/// List endpoints from a cached spec
+#[derive(Debug, ClapArgs)]
+pub struct Args {
+    /// Alias of the cached spec
+    pub alias: String,
+
+    /// Filter by HTTP method
+    #[arg(long)]
+    pub method: Option<String>,
+
+    /// Filter by tag
+    #[arg(long)]
+    pub tag: Option<String>,
+
+    /// Filter by path pattern
+    #[arg(long)]
+    pub path: Option<String>,
+}
+
+pub async fn execute(_args: &Args, _robot: bool) -> Result<(), SwaggerCliError> {
+    Err(SwaggerCliError::Usage("list not yet implemented".into()))
+}

src/cli/mod.rs

@@ -1 +1,75 @@
-// CLI command definitions
+pub mod aliases;
+pub mod cache_cmd;
+pub mod diff;
+pub mod doctor;
+pub mod fetch;
+pub mod list;
+pub mod schemas;
+pub mod search;
+pub mod show;
+pub mod sync_cmd;
+pub mod tags;
+
+use std::path::PathBuf;
+
+use clap::{Parser, Subcommand};
+
+/// A fast, cache-first CLI for exploring OpenAPI specs
+#[derive(Debug, Parser)]
+#[command(name = "swagger-cli", version, about)]
+pub struct Cli {
+    #[command(subcommand)]
+    pub command: Commands,
+
+    /// Output machine-readable JSON
+    #[arg(long, global = true)]
+    pub robot: bool,
+
+    /// Pretty-print JSON output
+    #[arg(long, global = true)]
+    pub pretty: bool,
+
+    /// Network mode: auto, online-only, offline
+    #[arg(long, global = true, default_value = "auto")]
+    pub network: String,
+
+    /// Path to config file
+    #[arg(long, global = true, env = "SWAGGER_CLI_CONFIG")]
+    pub config: Option<PathBuf>,
+}
+
+#[derive(Debug, Subcommand)]
+pub enum Commands {
+    /// Fetch and cache an OpenAPI spec
+    Fetch(fetch::Args),
+
+    /// List endpoints from a cached spec
+    List(list::Args),
+
+    /// Show details of a specific endpoint
+    Show(show::Args),
+
+    /// Search endpoints by keyword
+    Search(search::Args),
+
+    /// List or show schemas from a cached spec
+    Schemas(schemas::Args),
+
+    /// List tags from a cached spec
+    Tags(tags::Args),
+
+    /// Manage spec aliases
+    Aliases(aliases::Args),
+
+    /// Re-fetch and update a cached spec
+    Sync(sync_cmd::Args),
+
+    /// Check cache health and diagnose issues
+    Doctor(doctor::Args),
+
+    /// Manage the spec cache
+    Cache(cache_cmd::Args),
+
+    /// Compare two versions of a spec
+    Diff(diff::Args),
+}

src/cli/schemas.rs

@@ -0,0 +1,18 @@
+use clap::Args as ClapArgs;
+
+use crate::errors::SwaggerCliError;
+
+/// List or show schemas from a cached spec
+#[derive(Debug, ClapArgs)]
+pub struct Args {
+    /// Alias of the cached spec
+    pub alias: String,
+
+    /// Specific schema name to show
+    #[arg(long)]
+    pub name: Option<String>,
+}
+
+pub async fn execute(_args: &Args, _robot: bool) -> Result<(), SwaggerCliError> {
+    Err(SwaggerCliError::Usage("schemas not yet implemented".into()))
+}

src/cli/search.rs

@@ -0,0 +1,21 @@
+use clap::Args as ClapArgs;
+
+use crate::errors::SwaggerCliError;
+
+/// Search endpoints by keyword
+#[derive(Debug, ClapArgs)]
+pub struct Args {
+    /// Alias of the cached spec
+    pub alias: String,
+
+    /// Search query
+    pub query: String,
+
+    /// Maximum number of results
+    #[arg(long, default_value = "20")]
+    pub limit: usize,
+}
+
+pub async fn execute(_args: &Args, _robot: bool) -> Result<(), SwaggerCliError> {
+    Err(SwaggerCliError::Usage("search not yet implemented".into()))
+}

src/cli/show.rs

@@ -0,0 +1,17 @@
+use clap::Args as ClapArgs;
+
+use crate::errors::SwaggerCliError;
+
+/// Show details of a specific endpoint
+#[derive(Debug, ClapArgs)]
+pub struct Args {
+    /// Alias of the cached spec
+    pub alias: String,
+
+    /// Operation ID or path to show
+    pub endpoint: String,
+}
+
+pub async fn execute(_args: &Args, _robot: bool) -> Result<(), SwaggerCliError> {
+    Err(SwaggerCliError::Usage("show not yet implemented".into()))
+}

src/cli/sync_cmd.rs

@@ -0,0 +1,18 @@
+use clap::Args as ClapArgs;
+
+use crate::errors::SwaggerCliError;
+
+/// Re-fetch and update a cached spec
+#[derive(Debug, ClapArgs)]
+pub struct Args {
+    /// Alias to sync
+    pub alias: String,
+
+    /// Auth profile name from config
+    #[arg(long)]
+    pub auth: Option<String>,
+}
+
+pub async fn execute(_args: &Args, _robot: bool) -> Result<(), SwaggerCliError> {
+    Err(SwaggerCliError::Usage("sync not yet implemented".into()))
+}

src/cli/tags.rs

@@ -0,0 +1,14 @@
+use clap::Args as ClapArgs;
+
+use crate::errors::SwaggerCliError;
+
+/// List tags from a cached spec
+#[derive(Debug, ClapArgs)]
+pub struct Args {
+    /// Alias of the cached spec
+    pub alias: String,
+}
+
+pub async fn execute(_args: &Args, _robot: bool) -> Result<(), SwaggerCliError> {
+    Err(SwaggerCliError::Usage("tags not yet implemented".into()))
+}