spec.md

Based on my analysis of the codebase, here's the updated spec for adding .cat -T <topic> / .cat --topic <topic> functionality:

Code Flow Analysis

The .cat command flows through these layers:

1. xs.nu wrapper → calls xs cat CLI with flags
2. src/main.rs CommandCat → parses CLI args, builds ReadOptions
3. client/commands.rs cat() → makes HTTP GET to / with query params
4. api.rs handle_stream_cat() → parses query into ReadOptions, calls Store::read
5. store/mod.rs Store::read() → performs backlog scan + live subscription

Files Requiring Updates

Core Implementation

• src/store/mod.rs: Add topic field to ReadOptions, update from_query/to_query_string, modify Store::read() to use topic index for backlog and filter broadcasts
• src/main.rs: Add --topic/-T flag to CommandCat struct and cat() function
• client/commands.rs: Pass topic parameter through HTTP client
• xs.nu: Add topic flag to .cat wrapper command

Tests

• src/store/tests.rs: Add topic filtering tests for both historical and live frames
• src/client/mod.rs or integration tests: Test end-to-end topic filtering

Documentation

• docs/src/content/docs/reference/cli.mdx: Update xs cat command documentation
• docs/src/content/docs/getting-started/first-stream.mdx: Update .cat examples if applicable

Test Cases

1. Historical filtering: Create frames with mixed topics, verify --topic foo returns only foo frames
2. Live filtering: Follow stream with topic filter, append mixed topics, verify only matching frames received
3. Topic index optimization: Verify backlog scan uses topic index when topic specified
4. Combined flags: Test --topic with --follow, --tail, --context, --limit
5. Non-existent topic: Verify graceful handling of topics with no frames

Tactical Change Summary

Add topic filtering to .cat command using -T --topic flags:

1. Store layer: Add topic: Option<String> to ReadOptions, implement topic index scanning in Store::read() for backlog, filter broadcast frames by topic
2. CLI layer: Add topic: Option<String> to CommandCat, pass to client layer
3. Client layer: Include topic in HTTP query parameters
4. API layer: Parse topic from query into ReadOptions
5. Nushell wrapper: Add -T --topic flag to .cat command in xs.nu
6. Tests: Add comprehensive topic filtering tests for historical and live scenarios
7. Documentation: Update CLI reference and usage examples

The implementation leverages the existing topic index (idx_topic) for efficient backlog scanning when a topic is specified, falling back to full stream scan + filtering when no topic is provided.