feat(server): server list CLI (P1)

First slice of opt-in Axum server codegen. Adds a read-only
discovery command:

  openapi-to-rust server list --spec <path>
      [--tag <name>] [--method <verb>] [--grep <pat>] [--json]

Aligned-table output by default, JSON for scripting. [SSE] marker
on operations whose responses declare text/event-stream.

Surfaces the canonical test cases for later phases:
  - OpenAI createResponse (POST /responses, [SSE])
  - Anthropic messages_post (POST /v1/messages)

Mechanics:
  - OperationInfo gains a tags: Vec<String> field, populated from
    the spec's operation.tags. Empty when untagged.
  - New module src/server/ with OperationIndex + list filter/render.
  - Tests construct OperationSummary directly; 9 unit tests cover
    filter composition, JSON output, SSE marker, empty-result UX.
  - Existing OperationInfo struct-literal sites in tests updated.
  - Snapshot tests refreshed to include the new tags field.

Closes openapi-generator-f8q; followups: openapi-generator-in6
(Anthropic spec lacks text/event-stream content type on
messages_post — needs schema-extension overlay before SSE works
on that endpoint).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: lightsofapollo

.beads/issues.jsonl

@@ -189,7 +189,13 @@ Reuses the reachability pass that the client generator already has.
 3. `server add` / `server remove` — TOML edits.
 4. Trait + response-enum emitter.
 5. Router factory + extractors + reachability pruning.
-6. Snapshot tests against `specs/openai.yaml`, canonical case
-   `createChatCompletion`.
+6. Snapshot tests against the two canonical specs:
+   - OpenAI Responses API — `createResponse` in `specs/openai.yaml`
+     (POST `/v1/responses`, SSE via `stream: true`)
+   - Anthropic Messages API — `messages_post` in `specs/anthropic.yaml`
+     (POST `/v1/messages`, SSE via `stream: true`)
+
+   Both must work end-to-end. They drive everything: streaming, complex
+   request unions, header params (`anthropic-version`), 4XX response groups.
 
 Each phase ships standalone and is reviewable independently.

docs/planning/server-codegen.md

@@ -311,6 +311,10 @@ pub struct OperationInfo {
     pub supports_streaming: bool,
     /// Stream parameter name if applicable
     pub stream_parameter: Option<String>,
+    /// Tags declared on the operation. Empty when the spec sets none.
+    /// Used by the server codegen selector grammar (e.g. `tag:Chat`)
+    /// and by `openapi-to-rust server list` for grouping.
+    pub tags: Vec<String>,
 }
 
 /// Content type and schema for a request body
@@ -4232,6 +4236,7 @@ impl SchemaAnalyzer {
             parameters: Vec::new(),
             supports_streaming: false, // Will be determined by StreamingConfig, not spec
             stream_parameter: None,    // Will be determined by StreamingConfig, not spec
+            tags: operation.tags.clone().unwrap_or_default(),
         };
 
         // Extract request body schema with content-type awareness

src/analysis.rs

@@ -1,5 +1,9 @@
 use clap::{Parser, Subcommand};
 use openapi_to_rust::cli::{json_from_str_lossy, yaml_to_json_value};
+use openapi_to_rust::server::{
+    OperationIndex,
+    list::{ListFilter, ListOutput, render as render_list},
+};
 use openapi_to_rust::{CodeGenerator, ConfigFile, SchemaAnalyzer};
 use std::path::PathBuf;
 
@@ -31,6 +35,37 @@ enum Commands {
         #[arg(short, long, default_value = "openapi-to-rust.toml")]
         config: PathBuf,
     },
+    /// Server codegen commands (opt-in Axum scaffolding).
+    Server {
+        #[command(subcommand)]
+        action: ServerCommands,
+    },
+}
+
+#[derive(Subcommand)]
+enum ServerCommands {
+    /// List every operation in a spec. Read-only.
+    List {
+        /// Path to the OpenAPI spec (.yaml/.yml/.json). If omitted,
+        /// the spec_path from openapi-to-rust.toml is used.
+        #[arg(long)]
+        spec: Option<PathBuf>,
+        /// Path to TOML config to read spec_path from when --spec is absent.
+        #[arg(long, default_value = "openapi-to-rust.toml")]
+        config: PathBuf,
+        /// Substring match against tag names (case insensitive).
+        #[arg(long)]
+        tag: Option<String>,
+        /// Exact HTTP method filter (GET, POST, ...; case insensitive).
+        #[arg(long)]
+        method: Option<String>,
+        /// Substring match against operationId and path.
+        #[arg(long)]
+        grep: Option<String>,
+        /// Emit JSON instead of an aligned table.
+        #[arg(long)]
+        json: bool,
+    },
 }
 
 #[tokio::main]
@@ -190,5 +225,62 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
             Ok(())
         }
+        Commands::Server { action } => match action {
+            ServerCommands::List {
+                spec,
+                config,
+                tag,
+                method,
+                grep,
+                json,
+            } => run_server_list(spec, config, tag, method, grep, json),
+        },
     }
 }
+
+fn run_server_list(
+    spec: Option<PathBuf>,
+    config: PathBuf,
+    tag: Option<String>,
+    method: Option<String>,
+    grep: Option<String>,
+    json: bool,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let spec_path = match spec {
+        Some(p) => p,
+        None => {
+            let cf = ConfigFile::load(&config).map_err(|e| {
+                format!(
+                    "no --spec provided and failed to load {}: {}",
+                    config.display(),
+                    e
+                )
+            })?;
+            cf.into_generator_config().spec_path
+        }
+    };
+
+    let spec_content = std::fs::read_to_string(&spec_path)?;
+    let spec_value: serde_json::Value = if spec_path.extension()
+        == Some(std::ffi::OsStr::new("yaml"))
+        || spec_path.extension() == Some(std::ffi::OsStr::new("yml"))
+    {
+        yaml_to_json_value(&spec_content)?
+    } else {
+        json_from_str_lossy(&spec_content)?
+    };
+
+    let mut analyzer = SchemaAnalyzer::new(spec_value)?;
+    let analysis = analyzer.analyze()?;
+    let index = OperationIndex::from_analysis(&analysis);
+
+    let filter = ListFilter { tag, method, grep };
+    let output = if json {
+        ListOutput::Json
+    } else {
+        ListOutput::Table
+    };
+    let (body, _count) = render_list(&index, &filter, output);
+    print!("{body}");
+    Ok(())
+}

src/bin/openapi-to-rust.rs

@@ -10,6 +10,7 @@ pub mod http_error;
 pub mod openapi;
 pub mod patterns;
 pub mod registry_generator;
+pub mod server;
 pub mod streaming;
 pub mod type_mapping;