swagger-cli/.beads/issues.jsonl

{"id":"bd-132","title":"Add semantic search with embeddings","description":"## What\nAdd semantic/fuzzy search as alternative to text search. Compute embeddings for endpoint descriptions and schema names during index building. Use cosine similarity for ranking.\n\n## Acceptance Criteria\n- [ ] --semantic flag enables embedding-based search\n- [ ] Results ranked by cosine similarity\n- [ ] Fallback to text search when embeddings unavailable\n\n## Files\n- CREATE: src/core/embeddings.rs\n- MODIFY: src/core/search.rs (add semantic search mode)","status":"open","priority":4,"issue_type":"task","created_at":"2026-02-12T16:31:57.268115Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:42:45.253877Z","compaction_level":0,"original_size":0,"labels":["future","phase3"],"dependencies":[{"issue_id":"bd-132","depends_on_id":"bd-2e4","type":"blocks","created_at":"2026-02-12T16:42:45.253860Z","created_by":"tayloreernisse"},{"issue_id":"bd-132","depends_on_id":"bd-3aq","type":"parent-child","created_at":"2026-02-12T16:31:57.269278Z","created_by":"tayloreernisse"}]}
{"id":"bd-161","title":"Epic: Sync and Updates","status":"open","priority":1,"issue_type":"task","created_at":"2026-02-12T16:22:23.251895Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:22:23.253943Z","compaction_level":0,"original_size":0,"labels":["epic"]}
{"id":"bd-16o","title":"Wire fetch command with local file, stdin, and remote URL support","description":"## Background\nThe fetch command is the primary entry point for getting specs into swagger-cli. It orchestrates: HTTP download (or local file/stdin read), format detection, YAML normalization, index building, pointer validation, and crash-consistent cache write. It supports auth headers, bearer tokens, auth profiles, --force overwrite, and robot output.\n\n## Approach\nImplement src/cli/fetch.rs with FetchArgs struct and async execute() function:\n\n**FetchArgs (clap derive):**\n- url: String (positional, required — can be URL, file path, or \"-\" for stdin)\n- alias: String (--alias, required)\n- header: Vec<String> (--header, repeatable)\n- auth_header: Vec<String> (--auth-header, alias for --header)\n- bearer: Option<String> (--bearer)\n- auth_profile: Option<String> (--auth-profile)\n- force: bool (--force)\n- timeout_ms: u64 (--timeout-ms, default 10000)\n- max_bytes: u64 (--max-bytes, default 26214400)\n- retries: u32 (--retries, default 2)\n- input_format: Option<String> (--input-format, values: auto/json/yaml)\n- resolve_external_refs: bool (--resolve-external-refs)\n- ref_allow_host: Vec<String> (--ref-allow-host, repeatable)\n- ref_max_depth: u32 (--ref-max-depth, default 3)\n- ref_max_bytes: u64 (--ref-max-bytes, default 10MB)\n- allow_private_host: Vec<String> (--allow-private-host, repeatable)\n- allow_insecure_http: bool (--allow-insecure-http)\n\n**Execute flow:**\n1. Validate alias format (validate_alias)\n2. Check if alias exists — error unless --force\n3. Resolve auth (merge --auth-profile with explicit headers, --bearer)\n4. Determine source: URL (http/https), local file (file:// or path), or stdin (-)\n5. For URL: use AsyncHttpClient.fetch_spec() with SSRF/HTTPS policy\n6. For local file: canonicalize path, read bytes directly (no network policy)\n7. For stdin: read all bytes from stdin\n8. Detect format, normalize to JSON\n9. Parse as serde_json::Value\n10. Build index (build_index)\n11. Write cache (write_cache with all artifacts)\n12. Output robot JSON or human success message\n\n## Acceptance Criteria\n- [ ] `swagger-cli fetch ./petstore.json --alias pet` succeeds (local file)\n- [ ] `swagger-cli fetch https://... --alias pet --robot` outputs JSON with ok:true, data.alias, data.endpoint_count\n- [ ] `swagger-cli fetch - --alias stdin-api` reads from stdin\n- [ ] Alias validation rejects \"../bad\" before any network call\n- [ ] Existing alias without --force returns ALIAS_EXISTS (exit 6)\n- [ ] --force overwrites existing alias\n- [ ] --bearer TOKEN adds Authorization: Bearer TOKEN header\n- [ ] --auth-profile loads from config.toml\n- [ ] Robot output includes: alias, url, version, title, endpoint_count, schema_count, cached_at, source_format, cache_dir, files, content_hash\n- [ ] Auth header values never appear in output or error messages\n\n## Files\n- MODIFY: src/cli/fetch.rs (FetchArgs, execute, auth resolution, source routing)\n- MODIFY: src/output/robot.rs (add output_fetch function)\n- MODIFY: src/output/human.rs (add output_fetch function)\n\n## TDD Anchor\nRED: Write integration test `test_fetch_local_file` — use assert_cmd to run `swagger-cli fetch tests/fixtures/petstore.json --alias test-pet --robot` with SWAGGER_CLI_HOME set to tempdir. Assert exit 0, stdout JSON has ok:true.\nGREEN: Implement full fetch pipeline.\nVERIFY: `cargo test test_fetch_local_file`\n\nAdditional tests:\n- test_fetch_alias_exists_error\n- test_fetch_force_overwrites\n- test_fetch_stdin\n- test_fetch_bearer_auth\n- test_fetch_yaml_file (if YAML fixture exists)\n\n## Edge Cases\n- stdin (\"-\") is not a URL — don't try to HTTP-fetch it\n- Local file paths must be canonicalized (resolve symlinks, relative paths) before reading\n- file:// URLs must be converted to local paths (strip scheme)\n- If auth-profile references an EnvVar source, resolve the env var at fetch time\n- Robot output: redact --bearer and --auth-header values even in success output\n\n## Dependency Context\nUses AsyncHttpClient from bd-3b6 (async HTTP client with SSRF protection). Uses build_index, detect_format, normalize_to_json from bd-189 (spec format detection and index building). Uses CacheManager.write_cache and validate_alias from bd-1ie (cache write path). Uses Config for auth profiles from bd-1sb (configuration system).","status":"open","priority":2,"issue_type":"task","created_at":"2026-02-12T16:26:35.220966Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:55:46.975549Z","compaction_level":0,"original_size":0,"labels":["fetch","phase1"],"dependencies":[{"issue_id":"bd-16o","depends_on_id":"bd-189","type":"blocks","created_at":"2026-02-12T16:34:06.059316Z","created_by":"tayloreernisse"},{"issue_id":"bd-16o","depends_on_id":"bd-1ie","type":"blocks","created_at":"2026-02-12T16:34:06.154074Z","created_by":"tayloreernisse"},{"issue_id":"bd-16o","depends_on_id":"bd-1sb","type":"blocks","created_at":"2026-02-12T16:34:06.248426Z","created_by":"tayloreernisse"},{"issue_id":"bd-16o","depends_on_id":"bd-3b6","type":"blocks","created_at":"2026-02-12T16:34:06.005417Z","created_by":"tayloreernisse"},{"issue_id":"bd-16o","depends_on_id":"bd-3d2","type":"blocks","created_at":"2026-02-12T16:26:35.222663Z","created_by":"tayloreernisse"},{"issue_id":"bd-16o","depends_on_id":"bd-3ny","type":"parent-child","created_at":"2026-02-12T16:26:35.222248Z","created_by":"tayloreernisse"}]}
{"id":"bd-189","title":"Implement spec format detection, YAML normalization, and index building","description":"## Background\nAfter downloading raw spec bytes, swagger-cli must detect the input format (JSON vs YAML), normalize YAML to JSON, parse the spec as serde_json::Value, and build a SpecIndex from it. The index building is the heart of the query performance -- it pre-extracts endpoints, schemas, and tags into a compact, sorted structure with JSON pointers back to raw.json. All pointers must be validated.\n\n## Approach\nCreate src/core/indexer.rs with:\n\n**Format detection:** `detect_format(bytes, filename_hint, content_type_hint) -> Format` where Format is Json or Yaml. Priority: explicit --input-format flag > Content-Type header > file extension > content sniffing (try JSON parse first, fall back to YAML).\n\n**YAML normalization:** `normalize_to_json(bytes, format) -> Result<Vec<u8>>` -- if YAML, parse with serde_yaml then serialize to serde_json. If JSON, pass through (validate it parses).\n\n**Index building:** `build_index(raw_json: &serde_json::Value, content_hash: &str, generation: u64) -> Result<SpecIndex>`:\n1. Extract info.title, info.version, openapi version\n2. Iterate paths.* -> methods -> build IndexedEndpoint with: path, method (uppercased), summary, description, operation_id, tags, deprecated, parameters (name/location/required/desc), request_body_required, request_body_content_types, security_schemes (effective: operation-level overrides root-level), security_required, operation_ptr (JSON pointer format: /paths/~1pet~1{petId}/get)\n3. Iterate components.schemas.* -> build IndexedSchema with name, schema_ptr\n4. Compute tags from endpoints + root-level tags -> IndexedTag with endpoint_count\n5. Sort deterministically: endpoints by (path ASC, method_rank ASC), schemas by (name ASC), tags by (name ASC)\n6. Validate ALL operation_ptr and schema_ptr resolve in the raw Value\n7. Set index_version to current version constant (1)\n\n**Canonical method ranking:** GET=0, POST=1, PUT=2, PATCH=3, DELETE=4, OPTIONS=5, HEAD=6, TRACE=7, unknown=99.\n\n**JSON pointer encoding:** Path segments use RFC 6901: `~` -> `~0`, `/` -> `~1`. So `/pet/{petId}` becomes `/paths/~1pet~1{petId}`.\n\n## Acceptance Criteria\n- [ ] JSON input detected and passed through correctly\n- [ ] YAML input detected and normalized to equivalent JSON\n- [ ] build_index extracts correct endpoint count from petstore spec (19 endpoints)\n- [ ] Endpoints sorted by path ASC, method_rank ASC (deterministic)\n- [ ] Schemas sorted by name ASC\n- [ ] Tags have correct endpoint_count\n- [ ] All operation_ptr values resolve in raw Value (validated during build_index)\n- [ ] Invalid pointer causes fetch failure (not silent corruption)\n- [ ] JSON pointer encoding handles /pet/{petId} correctly (escapes /)\n- [ ] Security inheritance: operation without security inherits root; operation with empty [] means no auth\n\n## Files\n- CREATE: src/core/indexer.rs (detect_format, normalize_to_json, build_index, method_rank, json_pointer_encode, validate_pointers)\n- MODIFY: src/core/mod.rs (pub mod indexer;)\n\n## TDD Anchor\nRED: Write `test_build_index_petstore` -- load tests/fixtures/petstore.json as Value, call build_index, assert endpoint_count == 19 and endpoints are sorted.\nGREEN: Implement full index building.\nVERIFY: `cargo test test_build_index_petstore`\n\nAdditional tests:\n- test_detect_format_json, test_detect_format_yaml\n- test_yaml_normalization_roundtrip\n- test_json_pointer_encoding\n- test_method_rank_ordering\n- test_security_inheritance\n- test_invalid_pointer_rejected\n\n## Edge Cases\n- Some specs have paths with special chars in operation IDs -- don't assume alphanumeric\n- serde_yaml may produce different JSON than direct JSON parse (number types, null handling) -- normalize consistently\n- Large specs (8MB+ GitHub) should still build index in <1s\n- OpenAPI 3.1 may use `webhooks` key -- ignore for MVP (only extract from `paths`)\n- Tags defined at root level but not used by any operation should still appear with endpoint_count=0\n\n## Dependency Context\nUses SpecIndex, IndexedEndpoint, IndexedSchema, IndexedTag, IndexedParam types from bd-ilo (error types + core models bead).","status":"closed","priority":2,"issue_type":"task","created_at":"2026-02-12T16:26:35.194671Z","created_by":"tayloreernisse","updated_at":"2026-02-12T17:41:12.926777Z","closed_at":"2026-02-12T17:41:12.926730Z","close_reason":"Format detection, YAML normalization, index building with pointer validation","compaction_level":0,"original_size":0,"labels":["fetch","phase1"],"dependencies":[{"issue_id":"bd-189","depends_on_id":"bd-3ny","type":"parent-child","created_at":"2026-02-12T16:26:35.195659Z","created_by":"tayloreernisse"},{"issue_id":"bd-189","depends_on_id":"bd-ilo","type":"blocks","created_at":"2026-02-12T16:26:35.196142Z","created_by":"tayloreernisse"}]}
{"id":"bd-1bp","title":"Implement fetch-time external ref bundling","description":"## Background\nOptional fetch-time external ref bundling. When --resolve-external-refs is passed during fetch, external $ref targets are fetched and inlined into raw.json. Requires explicit --ref-allow-host allowlist. Bounded by --ref-max-depth and --ref-max-bytes.\n\n## Approach\nAfter fetching the main spec and parsing as Value:\n1. Walk the Value tree looking for $ref values that don't start with \"#/\"\n2. For each external ref: parse URL, check host against --ref-allow-host allowlist (reject if not listed)\n3. Fetch external ref content (uses AsyncHttpClient, respects SSRF policy)\n4. Track total bytes fetched (abort at --ref-max-bytes)\n5. Track resolution depth (abort at --ref-max-depth for ref chains)\n6. Replace the $ref object with the fetched content\n7. Store bundled result as raw.json; original (with $ref pointers) as raw.source\n\n## Acceptance Criteria\n- [ ] --resolve-external-refs without --ref-allow-host returns USAGE_ERROR\n- [ ] External refs to allowed hosts are fetched and inlined\n- [ ] External refs to disallowed hosts are rejected with PolicyBlocked\n- [ ] --ref-max-depth limits chain resolution\n- [ ] --ref-max-bytes limits total fetched content\n- [ ] Bundled raw.json has all external refs resolved; raw.source preserves originals\n\n## Edge Cases\n- **Circular external refs:** A.yaml $refs B.yaml which $refs A.yaml. Must detect and break cycles (return error or annotate).\n- **Relative refs:** `$ref: \"./schemas/Pet.yaml\"` must resolve relative to the base spec URL, not CWD.\n- **Mixed internal + external refs:** Only resolve external refs (not starting with #/). Internal refs stay as-is.\n- **External ref returns non-JSON/YAML:** Return InvalidSpec error for that ref, don't fail the entire fetch.\n- **--ref-max-bytes exceeded:** Abort cleanly and report how many refs were resolved before the limit.\n\n## Files\n- CREATE: src/core/external_refs.rs (resolve_external_refs, walk_refs, fetch_ref)\n- MODIFY: src/cli/fetch.rs (integrate external ref resolution after main fetch)\n- MODIFY: src/core/mod.rs (pub mod external_refs;)\n\n## TDD Anchor\nRED: Write `test_external_ref_resolution` — create a spec with external $ref, mock the external URL, run fetch --resolve-external-refs --ref-allow-host localhost, verify ref is inlined.\nGREEN: Implement ref walking and fetching.\nVERIFY: `cargo test test_external_ref_resolution`\n\n## Dependency Context\nUses AsyncHttpClient from bd-3b6. Extends fetch pipeline from bd-16o.","status":"open","priority":3,"issue_type":"task","created_at":"2026-02-12T16:29:50.213098Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:58:12.383898Z","compaction_level":0,"original_size":0,"labels":["global","phase2"],"dependencies":[{"issue_id":"bd-1bp","depends_on_id":"bd-16o","type":"blocks","created_at":"2026-02-12T16:29:50.214577Z","created_by":"tayloreernisse"},{"issue_id":"bd-1bp","depends_on_id":"bd-3ll","type":"parent-child","created_at":"2026-02-12T16:29:50.214143Z","created_by":"tayloreernisse"}]}
{"id":"bd-1ck","title":"Implement diff command with structural comparison and CI gates","description":"## Background\nThe diff command compares two spec states structurally. It reports added, removed, and modified endpoints and schemas by comparing normalized indexes. Supports alias-vs-alias, alias-vs-URL, and --fail-on breaking for CI gates.\n\n## Approach\nImplement src/cli/diff.rs with DiffArgs and async execute():\n\n**DiffArgs:** left (String, positional), right (String, positional), fail_on (Option<String> — \"breaking\"), details (bool).\n\n**Source resolution:** LEFT and RIGHT can be alias names or URLs. If URL, fetch into a temp location, build index, use for comparison (don't persist to cache).\n\n**Diff computation (reuse from sync):**\n- Compare endpoint sets by (path, method): added = in right not left, removed = in left not right, modified = in both but different (compare summary, tags, deprecated, parameters, security)\n- Compare schema sets by name: added, removed, modified (compare schema_ptr target content hashes? or just name-based for Phase 2)\n- Summary: total_changes, has_breaking (Phase 2: just structural; Phase 3: semantic classification)\n\n**--fail-on breaking:** If breaking changes detected, exit non-zero (exit code 17). Phase 2 heuristic: removed endpoint = breaking, removed required parameter = breaking. Added endpoint/schema = non-breaking.\n\n## Acceptance Criteria\n- [ ] `diff alias1 alias2 --robot` reports structural changes\n- [ ] Added/removed/modified endpoints correctly identified\n- [ ] --fail-on breaking exits non-zero when breaking changes exist\n- [ ] URL as right-side source works (temp fetch, not persisted)\n- [ ] Robot output: left, right, changes.endpoints, changes.schemas, summary\n\n## Edge Cases\n- **Same spec on both sides:** Return ok:true with changed:false, empty change lists. Not an error.\n- **URL-as-source fails to fetch:** Return Network error, not a diff-specific error.\n- **Breaking change heuristic false positives:** Endpoint renamed (removed old + added new) looks like a breaking removal. Phase 2 is heuristic-only — document this limitation.\n- **Very large diff (thousands of changes):** Apply same 200-item cap as sync --details with truncated flag.\n- **Schema comparison:** Phase 2 is name-based only (added/removed by name). Modified schema detection is Phase 3 (requires deep structural comparison).\n\n## Files\n- MODIFY: src/cli/diff.rs (DiffArgs, execute, compute_diff, classify_breaking)\n- MODIFY: src/output/robot.rs (add output_diff)\n- MODIFY: src/output/human.rs (add output_diff)\n\n## TDD Anchor\nRED: Write `test_diff_detects_added_endpoint` — fetch petstore twice (one modified), run diff, assert added endpoint appears.\nGREEN: Implement index comparison.\nVERIFY: `cargo test test_diff_detects_added`\n\n## Dependency Context\nReuses index diff logic from sync command (bd-3f4). Uses AsyncHttpClient for URL-as-source (bd-3b6). Uses indexer for building temp index from URL (bd-189).","status":"open","priority":3,"issue_type":"task","created_at":"2026-02-12T16:30:58.972480Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:58:11.727380Z","compaction_level":0,"original_size":0,"labels":["diff","phase2"],"dependencies":[{"issue_id":"bd-1ck","depends_on_id":"bd-189","type":"blocks","created_at":"2026-02-12T16:30:58.976840Z","created_by":"tayloreernisse"},{"issue_id":"bd-1ck","depends_on_id":"bd-21m","type":"parent-child","created_at":"2026-02-12T16:30:58.975608Z","created_by":"tayloreernisse"},{"issue_id":"bd-1ck","depends_on_id":"bd-3f4","type":"blocks","created_at":"2026-02-12T16:30:58.976270Z","created_by":"tayloreernisse"}]}
{"id":"bd-1cv","title":"Implement global network policy (offline/auto/online-only)","description":"## Background\nThe --network global flag controls whether swagger-cli makes network calls. \"auto\" (default) allows network when needed. \"offline\" blocks all network calls (fetch/sync fail with OFFLINE_MODE). \"online-only\" flags when network would be needed but is not available. This is critical for CI reproducibility and agent sandboxing.\n\n## Approach\n\n### NetworkPolicy Enum (src/core/network.rs)\nCreate `NetworkPolicy` enum with three variants:\n- **Auto** (default): Allow network calls when needed, no restrictions. Standard behavior.\n- **Offline**: Block ALL outbound network calls preemptively. Any command that would make a network request (fetch, sync) returns `SwaggerCliError::OfflineMode` immediately without attempting the call. Commands that are index-only (list, search, show, tags) work normally.\n- **OnlineOnly**: Allow network calls but surface a clear, distinct error if a network call would be needed AND DNS resolution fails or the host is unreachable. The error is different from OfflineMode — it indicates \"you requested online-only mode but network is unavailable\" rather than \"network calls are blocked by policy.\"\n\n### Implementation\n1. Parse --network flag in CLI (already in Cli struct from skeleton bead)\n2. Create `NetworkPolicy` enum and `check_network_policy()` function in `src/core/network.rs`\n3. Check policy before any HTTP call in AsyncHttpClient — if Offline, return `SwaggerCliError::OfflineMode` without making the request\n4. For OnlineOnly: attempt the request, but if it fails due to network issues, return a specific `SwaggerCliError::NetworkUnavailable` (different exit code or error code than OfflineMode)\n5. `SWAGGER_CLI_NETWORK` env var as alternative to --network flag (flag takes precedence)\n\n### Scope boundaries\n- **Local file sources (file:// paths, stdin):** Network policy does NOT apply. These are local I/O operations. `fetch ./local-spec.yaml --network offline` should succeed because no network call is made.\n- **Stdin sources:** Same as local files — no network needed, policy irrelevant.\n- **sync --dry-run in offline mode:** ALLOWED. Dry-run compares cached state without actually fetching, so no network call is needed. Returns cached state comparison only.\n\n## Acceptance Criteria\n- [ ] NetworkPolicy enum with Auto, Offline, OnlineOnly variants in src/core/network.rs\n- [ ] --network offline causes fetch (remote URL) to fail with OFFLINE_MODE error (exit 15)\n- [ ] --network offline allows fetch from local file path (no network needed)\n- [ ] --network offline allows fetch from stdin (no network needed)\n- [ ] --network offline allows list/search/show/tags (index-only, no network needed)\n- [ ] --network offline allows sync --dry-run (cached comparison only, no network)\n- [ ] --network online-only surfaces clear error when network is unavailable (distinct from OFFLINE_MODE)\n- [ ] --network auto allows all commands (default behavior, no restrictions)\n- [ ] SWAGGER_CLI_NETWORK=offline env var works same as --network offline flag\n- [ ] Flag takes precedence over env var when both are set\n- [ ] Robot error for offline mode has code OFFLINE_MODE with suggestion to remove --network flag or unset env var\n- [ ] Robot error for online-only network failure has code NETWORK_UNAVAILABLE with distinct suggestion\n\n## Edge Cases\n- **sync --dry-run in offline mode:** Allowed — returns cached state comparison only, no actual fetch happens. This is a read-only operation on cached data.\n- **Local file + offline mode:** Allowed — `fetch ./spec.yaml --network offline` succeeds because it is local I/O, not a network call.\n- **OnlineOnly vs Offline distinction:** Offline blocks proactively (never attempts the call). OnlineOnly attempts the call and fails with a specific error if the network is down. This matters for agents that want to know \"was this blocked by policy or by actual network unavailability?\"\n- **Mixed sources:** If a future version supports specs that reference remote $ref URLs but the base spec is local, the network policy should apply to the remote $ref resolution (not the local file read).\n\n## Files\n- CREATE: src/core/network.rs (NetworkPolicy enum, check_network_policy function)\n- MODIFY: src/core/http.rs (check policy before fetch)\n- MODIFY: src/cli/fetch.rs (check policy at start, skip for local/stdin sources)\n- MODIFY: src/cli/sync.rs (check policy at start, allow --dry-run in offline)\n\n## TDD Anchor\nRED: Write `test_offline_blocks_fetch` — set SWAGGER_CLI_NETWORK=offline, run fetch with remote URL, assert exit 15 and OFFLINE_MODE error.\nRED: Write `test_offline_allows_local_file` — set offline, fetch local file, assert success.\nRED: Write `test_offline_allows_list` — set offline, run list on cached alias, assert success.\nRED: Write `test_online_only_network_unavailable` — set online-only, mock DNS failure, assert NETWORK_UNAVAILABLE error.\nGREEN: Implement policy check.\nVERIFY: `cargo test test_offline_blocks_fetch`\n\n## Dependency Context\nModifies AsyncHttpClient in bd-3b6 (async HTTP client) to check network policy before requests. Uses SwaggerCliError variants (OfflineMode) from bd-ilo (error types and core data models).","status":"open","priority":3,"issue_type":"task","created_at":"2026-02-12T16:29:50.156478Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:56:01.445917Z","compaction_level":0,"original_size":0,"labels":["global","phase2"],"dependencies":[{"issue_id":"bd-1cv","depends_on_id":"bd-16o","type":"blocks","created_at":"2026-02-12T16:29:50.158591Z","created_by":"tayloreernisse"},{"issue_id":"bd-1cv","depends_on_id":"bd-3b6","type":"blocks","created_at":"2026-02-12T16:29:50.158232Z","created_by":"tayloreernisse"},{"issue_id":"bd-1cv","depends_on_id":"bd-3ll","type":"parent-child","created_at":"2026-02-12T16:29:50.157784Z","created_by":"tayloreernisse"}]}
{"id":"bd-1d4","title":"Implement cache lifecycle command with stats, prune, and LRU eviction","description":"## Background\nThe cache command manages cache growth with stats, pruning, and LRU eviction. Separate from doctor (which validates health). Uses coalesced last_accessed timestamps for LRU ordering.\n\n## Approach\nImplement src/cli/cache.rs with CacheArgs and execute():\n\n**CacheArgs:** stats (bool, default action), prune_stale (bool), prune_threshold (u32, default 90 days), max_total_mb (Option<u64>), dry_run (bool).\n\n**Operations:**\n- Stats: list_aliases with size computation, show per-alias and total bytes\n- Prune: find aliases older than threshold, delete (or dry-run report)\n- LRU eviction: sort by last_accessed ASC, delete oldest until total < max_total_mb (or dry-run)\n\n## Acceptance Criteria\n- [ ] cache --stats shows per-alias sizes and total\n- [ ] cache --prune-stale deletes aliases >90 days old\n- [ ] cache --prune-threshold 30 overrides default\n- [ ] cache --max-total-mb 500 evicts oldest-accessed aliases\n- [ ] --dry-run shows what would be pruned without deleting\n- [ ] Robot output: aliases[], total_bytes, pruned[], evicted[]\n\n## Edge Cases\n- **No aliases cached:** cache --stats returns ok:true with total_bytes:0, empty aliases array.\n- **Concurrent prune + fetch:** If a fetch writes a new alias while prune is deleting, the new alias should not be affected. Prune operates on snapshot of alias list taken at start.\n- **last_accessed coalescing:** LRU ordering uses coalesced last_accessed (10-min granularity). Hot-read aliases within the same 10-min window have identical last_accessed — tie-break by fetched_at.\n- **--max-total-mb smaller than single largest alias:** Evict everything except the largest, then warn that target cannot be reached.\n- **Alias being synced during prune:** Skip locked aliases with warning.\n\n## Files\n- MODIFY: src/cli/cache.rs (CacheArgs, execute, prune, evict)\n- MODIFY: src/output/robot.rs (add output_cache)\n- MODIFY: src/output/human.rs (add output_cache)\n\n## TDD Anchor\nRED: Write `test_cache_prune_stale` — create alias with old fetched_at, run cache --prune-stale --robot, assert alias appears in pruned[].\nGREEN: Implement stale detection and pruning.\nVERIFY: `cargo test test_cache_prune_stale`\n\n## Dependency Context\nUses CacheManager (list_aliases, delete_alias) from bd-3ea. Uses is_stale from CacheMetadata.","status":"open","priority":3,"issue_type":"task","created_at":"2026-02-12T16:29:50.122830Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:58:11.481108Z","compaction_level":0,"original_size":0,"labels":["health","phase2"],"dependencies":[{"issue_id":"bd-1d4","depends_on_id":"bd-1y0","type":"parent-child","created_at":"2026-02-12T16:29:50.123937Z","created_by":"tayloreernisse"},{"issue_id":"bd-1d4","depends_on_id":"bd-3d2","type":"blocks","created_at":"2026-02-12T16:29:50.124722Z","created_by":"tayloreernisse"},{"issue_id":"bd-1d4","depends_on_id":"bd-3ea","type":"blocks","created_at":"2026-02-12T16:29:50.124351Z","created_by":"tayloreernisse"}]}
{"id":"bd-1dj","title":"Implement show command with ref expansion and pointer navigation","description":"## Background\nThe show command displays full details for a specific endpoint. Unlike list/search, show MUST load raw.json to extract the complete operation subtree (parameters with schemas, request body, response schemas, etc.). It uses the operation_ptr from the index to locate the exact JSON node in raw.json, avoiding full-spec parsing. Optional --expand-refs resolves internal $ref pointers with cycle detection.\n\n## Approach\nImplement src/cli/show.rs with ShowArgs and execute():\n\n**ShowArgs:** alias (Option<String>), path (String, positional), method (Option<String>), format (String, default \"pretty\"), expand_refs (bool), max_depth (u32, default 3).\n\n**Execute flow:**\n1. Resolve alias, load_index\n2. Find matching endpoint(s) by path in index\n3. If multiple methods and --method not specified → USAGE_ERROR listing available methods\n4. Get operation_ptr from matched IndexedEndpoint\n5. CacheManager::load_raw(alias, &meta) — loads raw.json as Value, validates raw_hash\n6. Navigate to operation subtree using JSON pointer (operation_ptr)\n7. If --expand-refs: recursively resolve internal $ref pointers (starting with #/) with cycle detection (max_depth). External refs get annotated as {\"$external_ref\": \"...\"}. Circular refs get {\"$circular_ref\": \"...\"}. Add warnings to meta.warnings[].\n8. Output robot JSON or human formatted details\n\n**JSON Pointer navigation:** Parse `/paths/~1pet~1{petId}/get` → navigate Value tree. `~1` → `/`, `~0` → `~`.\n\n**Ref expansion:** Walk the Value tree. When encountering `{\"$ref\": \"#/components/schemas/Pet\"}`, resolve by navigating the pointer in raw Value. Track visited refs for cycle detection. Stop at max_depth.\n\n## Acceptance Criteria\n- [ ] `swagger-cli show petstore \"/pet/{petId}\" --robot` returns full operation details\n- [ ] Multiple methods without --method returns USAGE_ERROR with available methods\n- [ ] --method POST selects specific method\n- [ ] operation_ptr correctly navigates to the right subtree in raw.json\n- [ ] --expand-refs resolves internal refs up to max_depth\n- [ ] Circular refs produce $circular_ref annotation (not infinite loop)\n- [ ] External refs produce $external_ref annotation + warning\n- [ ] raw_hash mismatch returns CacheIntegrity error\n- [ ] Robot output includes: path, method, summary, description, tags, operation_id, parameters, request_body, responses, security\n\n## Files\n- MODIFY: src/cli/show.rs (ShowArgs, execute, pointer navigation, ref expansion)\n- CREATE: src/core/refs.rs (expand_refs, resolve_pointer, cycle detection)\n- MODIFY: src/core/mod.rs (pub mod refs;)\n- MODIFY: src/output/robot.rs (add output_show)\n- MODIFY: src/output/human.rs (add output_show)\n\n## TDD Anchor\nRED: Write `test_show_endpoint_details` — fetch petstore fixture, run show \"/pet/{petId}\" --method GET --robot, parse JSON, assert data.path == \"/pet/{petId}\" and data.method == \"GET\".\nGREEN: Implement pointer navigation and output.\nVERIFY: `cargo test test_show_endpoint_details`\n\nAdditional tests:\n- test_show_multiple_methods_error\n- test_expand_refs_basic\n- test_expand_refs_circular_detection\n- test_expand_refs_external_annotation\n\n## Edge Cases\n- JSON pointer decoding: `~1` → `/`, `~0` → `~` (order matters: decode ~1 first, then ~0)\n- Path matching should be exact (not regex) — \"/pet/{petId}\" must match literally\n- Some operations may have no request body, no parameters, or no security — handle None gracefully\n- ref expansion must handle refs-to-refs (transitive resolution)\n\n## Dependency Context\nUses CacheManager.load_index and load_raw from bd-3ea (cache read). Uses index types from bd-ilo. Requires a fetched spec in cache.","status":"open","priority":2,"issue_type":"task","created_at":"2026-02-12T16:27:27.091022Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:27:27.093228Z","compaction_level":0,"original_size":0,"labels":["phase1","query"],"dependencies":[{"issue_id":"bd-1dj","depends_on_id":"bd-3d2","type":"blocks","created_at":"2026-02-12T16:27:27.093222Z","created_by":"tayloreernisse"},{"issue_id":"bd-1dj","depends_on_id":"bd-3ea","type":"blocks","created_at":"2026-02-12T16:27:27.092774Z","created_by":"tayloreernisse"},{"issue_id":"bd-1dj","depends_on_id":"bd-epk","type":"parent-child","created_at":"2026-02-12T16:27:27.092375Z","created_by":"tayloreernisse"}]}
{"id":"bd-1ie","title":"Implement cache write path with crash-consistent protocol and alias validation","description":"## Background\nThe cache write path is the most safety-critical code in swagger-cli. It implements a crash-consistent multi-file commit protocol: raw.source -> raw.json -> index.json are written as .tmp files with fsync, renamed atomically, then meta.json is written LAST as the commit marker. Per-alias file locking prevents concurrent write corruption. Alias names are validated against a strict regex to prevent path traversal.\n\n## Approach\n**Alias validation:** Implement `validate_alias()` that checks against `^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`, rejects path separators (/ \\), `..`, reserved device names (CON, PRN, NUL, AUX, COM1-9, LPT1-9 case-insensitive), and leading dots. Return SwaggerCliError::Usage on failure.\n\n**Cache directory management:** Implement `CacheManager` struct with `new()` (uses Config::cache_dir()), `new_with_path()` (for tests), `alias_dir()`, `ensure_dirs()`. Cache layout: `{cache_dir}/aliases/{alias}/`.\n\n**File locking:** Use `fs2::FileExt::try_lock_exclusive()` on `{alias_dir}/.lock` with a bounded timeout (default 1000ms, poll every 50ms). Return SwaggerCliError::CacheLocked on timeout.\n\n**Hash computation:** Implement `compute_hash(bytes: &[u8]) -> String` returning `\"sha256:{hex}\"` using sha2 crate.\n\n**Crash-consistent write:** Implement `CacheManager::write_cache()` that:\n1. Acquires exclusive lock on .lock (bounded timeout)\n2. Computes content_hash, raw_hash, next generation, index_hash\n3. Writes raw.source.tmp, raw.json.tmp, index.json.tmp (each with sync_all before rename)\n4. Renames each .tmp to final name (sync_all after each rename)\n5. Writes meta.json.tmp LAST (commit marker)\n6. Renames meta.json.tmp -> meta.json (sync_all)\n7. Best-effort fsync on alias directory fd (Unix only)\n8. Releases lock\n\n**Parameters for write_cache:** Takes alias, raw_source_bytes, raw_json_bytes, index (SpecIndex), url, spec_version, spec_title, source_format, etag, last_modified, previous_generation (Option<u64>).\n\n## Acceptance Criteria\n- [ ] validate_alias(\"petstore\") -> Ok\n- [ ] validate_alias(\"../etc/passwd\") -> Err(Usage)\n- [ ] validate_alias(\"CON\") -> Err(Usage) (case-insensitive)\n- [ ] validate_alias(\".hidden\") -> Err(Usage)\n- [ ] validate_alias(\"a\".repeat(65)) -> Err(Usage)\n- [ ] write_cache creates all 4 files + .lock in correct directory\n- [ ] meta.json is the last file written (verified by checking file mtimes or write order)\n- [ ] compute_hash produces deterministic sha256:hex output\n- [ ] Lock timeout returns CacheLocked error (not hang)\n- [ ] Hash values are deterministic (same input -> same sha256 output)\n- [ ] Files survive process kill between steps (no partial meta.json)\n\n## Files\n- CREATE: src/core/cache.rs (CacheManager, validate_alias, compute_hash, write_cache, lock helpers)\n- MODIFY: src/core/mod.rs (pub mod cache;)\n\n## TDD Anchor\nRED: Write `test_validate_alias_rejects_traversal` -- assert validate_alias(\"../etc\") returns Err with Usage variant.\nGREEN: Implement regex validation + blocklist checks.\nVERIFY: `cargo test test_validate_alias`\n\nAdditional tests:\n- test_validate_alias_accepts_valid (petstore, my-api, v1.0, API_2)\n- test_validate_alias_rejects_reserved (CON, con, NUL, COM1)\n- test_write_cache_creates_all_files\n- test_compute_hash_deterministic\n\n## Edge Cases\n- On macOS, fsync on directory fd may not be supported -- handle gracefully (best-effort)\n- Lock file must be created if it doesn't exist (open with create flag)\n- If alias directory doesn't exist, create it before acquiring lock\n- sync_all() is critical -- without it, data may be in OS page cache but not on disk after rename\n- Generation starts at 1 for new aliases, increments from previous for updates\n\n## Dependency Context\nUses SpecIndex and CacheMetadata types from bd-ilo (error types and core data models). Uses SwaggerCliError variants (CacheLocked, Cache, Usage) from bd-ilo.","status":"closed","priority":2,"issue_type":"task","created_at":"2026-02-12T16:25:15.503359Z","created_by":"tayloreernisse","updated_at":"2026-02-12T17:41:12.870780Z","closed_at":"2026-02-12T17:41:12.870733Z","close_reason":"CacheManager with validate_alias, compute_hash, crash-consistent write_cache","compaction_level":0,"original_size":0,"labels":["infrastructure","phase1"],"dependencies":[{"issue_id":"bd-1ie","depends_on_id":"bd-hcb","type":"parent-child","created_at":"2026-02-12T16:25:15.504778Z","created_by":"tayloreernisse"},{"issue_id":"bd-1ie","depends_on_id":"bd-ilo","type":"blocks","created_at":"2026-02-12T16:25:15.505170Z","created_by":"tayloreernisse"}]}
{"id":"bd-1ky","title":"Implement sync --all with async concurrency and resumable execution","description":"## Background\nsync --all synchronizes all aliases concurrently. It uses bounded async concurrency (--jobs, default 4) with per-host throttling (--per-host, default 2) to avoid abusive request patterns. Supports resumable execution via checkpoint files and a failure budget (--max-failures) to limit blast radius.\n\n## Approach\nBuild on the single-alias sync from the previous bead:\n\n**Async concurrency:** Use tokio::sync::Semaphore for global concurrency (--jobs). Use a per-host semaphore map (HashMap<String, Semaphore>) for --per-host throttling. Process aliases via futures::stream::StreamExt::buffer_unordered.\n\n**Resumable sync (--resume):** Write a checkpoint file ({cache_dir}/sync-checkpoint.json) after each alias completes. Contains: aliases_completed, aliases_failed, started_at. On --resume, skip already-completed aliases.\n\n**Failure budget (--max-failures):** Track failure count. When exceeded, abort remaining aliases and report partial results.\n\n**Retry-After:** Honor response header (seconds or HTTP-date format). Use exponential backoff + jitter when header absent.\n\n**Per-alias output:** Collect results from all aliases. Report per-alias success/failure in robot output. Don't abort on single-alias failure (unless failure budget exceeded).\n\n## Acceptance Criteria\n- [ ] sync --all processes all aliases concurrently\n- [ ] --jobs limits concurrent syncs (verified: never more than N in-flight)\n- [ ] --per-host limits requests to same host\n- [ ] --resume skips already-completed aliases\n- [ ] --max-failures aborts after N failures\n- [ ] Per-alias success/failure reported in robot output\n- [ ] Retry-After header honored\n\n## Edge Cases\n- **Empty aliases (no specs cached):** sync --all with no aliases should succeed with empty results, not error.\n- **All aliases fail:** If every alias fails sync, the overall command should still exit 0 with per-alias failure details (unless --max-failures triggered, then exit non-zero).\n- **Checkpoint file corruption:** If sync-checkpoint.json is malformed, delete it and start fresh (don't error).\n- **Per-host semaphore with many aliases to same host:** 10 aliases all pointing to api.example.com with --per-host 2 means only 2 concurrent to that host, even if --jobs allows more.\n- **Retry-After as HTTP-date:** Parse both formats: seconds (e.g., \"120\") and HTTP-date (e.g., \"Thu, 01 Jan 2026 00:00:00 GMT\").\n\n## Files\n- MODIFY: src/cli/sync.rs (add sync_all, concurrency control, checkpoint, failure budget)\n\n## TDD Anchor\nRED: Write `test_sync_all_concurrent` — set up 4 aliases, run sync --all --jobs 2 --robot, verify all 4 synced and output includes per-alias results.\nGREEN: Implement concurrent sync with semaphore.\nVERIFY: `cargo test test_sync_all_concurrent`\n\n## Dependency Context\nExtends single-alias sync from bd-3f4 (sync command). Uses tokio Semaphore for concurrency control. Uses CacheManager.list_aliases from bd-3ea (cache read path).","status":"open","priority":3,"issue_type":"task","created_at":"2026-02-12T16:28:47.465114Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:58:09.820419Z","compaction_level":0,"original_size":0,"labels":["phase2","sync"],"dependencies":[{"issue_id":"bd-1ky","depends_on_id":"bd-161","type":"parent-child","created_at":"2026-02-12T16:28:47.466140Z","created_by":"tayloreernisse"},{"issue_id":"bd-1ky","depends_on_id":"bd-3f4","type":"blocks","created_at":"2026-02-12T16:34:06.315322Z","created_by":"tayloreernisse"}]}
{"id":"bd-1lj","title":"Create CI/CD pipeline and cargo-deny configuration","description":"## Background\nThe CI/CD pipeline runs tests, linting, security audits, and multi-platform builds on GitLab CI. It also configures cargo-deny for license/advisory policy enforcement.\n\n## Approach\n\n### .gitlab-ci.yml Structure\n\n**Stages:** test, build, release\n\n**Test stage jobs:**\n- `test:unit` — `cargo test --lib` (unit tests only, no integration tests)\n- `test:integration` — `cargo test --test '*'` (integration tests in tests/ directory)\n- `lint` — `cargo fmt --check` + `cargo clippy -- -D warnings` (warnings are errors)\n- `security:deps` — `cargo-deny check` (license + advisory) + `cargo-audit` (RUSTSEC advisory DB)\n\n**Build stage:**\n- Build template (YAML anchor or extends) shared across 4 target jobs:\n  - `build:aarch64-apple-darwin` — Apple Silicon macOS\n  - `build:x86_64-apple-darwin` — Intel macOS\n  - `build:x86_64-unknown-linux-gnu` — x86 Linux\n  - `build:aarch64-unknown-linux-gnu` — ARM Linux\n- Each job: `cargo build --release --locked --target $TARGET`, upload binary as artifact\n\n**Release stage:**\n- `release` job (runs on tagged commits only):\n  - Collect all 4 binaries from build artifacts\n  - Generate `SHA256SUMS` file: `sha256sum swagger-cli-* > SHA256SUMS`\n  - Sign with minisign: `minisign -S -m SHA256SUMS` (produces SHA256SUMS.minisig)\n  - Upload all files to GitLab Package Registry via `curl` to Package Registry API\n- `docker` job (runs on tagged commits):\n  - `docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG .`\n  - `docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG`\n  - Also tag as `:latest`\n\n### deny.toml Structure\n\n**[licenses]:**\n- `unlicensed = \"deny\"` — all deps must have a license\n- `allow = [\"MIT\", \"Apache-2.0\", \"BSD-2-Clause\", \"BSD-3-Clause\", \"ISC\", \"Zlib\", \"Unicode-3.0\", \"Unicode-DFS-2016\", \"OpenSSL\"]` — common OSS license allow-list\n- `copyleft = \"deny\"` — no copyleft licenses without explicit exception\n\n**[advisories]:**\n- `vulnerability = \"deny\"` — fail on known vulnerabilities\n- `unmaintained = \"warn\"` — warn but don't fail on unmaintained crates\n- `unsound = \"warn\"` — warn on unsound crates\n- `yanked = \"deny\"` — fail on yanked versions\n- `notice = \"warn\"` — warn on advisories with notices\n\n**[bans]:**\n- `multiple-versions = \"warn\"` — warn if same crate appears in multiple versions\n- `wildcards = \"deny\"` — no wildcard version specs\n- Specific ban list empty initially (add problematic crates as discovered)\n\n## Acceptance Criteria\n- [ ] .gitlab-ci.yml has test, build, release stages in correct order\n- [ ] test:unit runs `cargo test --lib`\n- [ ] test:integration runs `cargo test --test '*'`\n- [ ] lint job runs both fmt --check and clippy -D warnings\n- [ ] security:deps runs both cargo-deny check and cargo-audit\n- [ ] All 4 platform targets defined as separate build jobs\n- [ ] Build jobs use shared template/anchor to avoid duplication\n- [ ] Release job generates SHA256SUMS from all binaries\n- [ ] Release job signs SHA256SUMS with minisign\n- [ ] Release job uploads to GitLab Package Registry\n- [ ] Docker job builds and pushes to CI_REGISTRY\n- [ ] deny.toml license allow-list covers common OSS licenses\n- [ ] deny.toml advisory policy denies known vulnerabilities\n- [ ] `cargo deny check` passes locally after creation\n\n## Files\n- CREATE: .gitlab-ci.yml\n- CREATE: deny.toml\n\n## TDD Anchor\nValidate: `cargo deny check` passes locally (after deny.toml is created).\nVERIFY: `cargo deny check 2>&1 | head -5`\n\n## Edge Cases\n- **Cross-compilation toolchains:** macOS targets require macOS runners or cross-compilation tools. Verify CI has the right runners or use `cross` tool.\n- **cargo-deny not installed:** The security:deps job must install cargo-deny and cargo-audit before running. Use `cargo install` with version pinning.\n- **Minisign key management:** The release job needs the minisign private key as a CI secret variable. Document the required CI variables.\n- **Tag-only release trigger:** Release jobs must have `rules: - if: $CI_COMMIT_TAG` to avoid running on every push.\n- **Large binary artifacts:** Rust release binaries can be 10MB+. Verify CI artifact storage limits.","status":"open","priority":3,"issue_type":"task","created_at":"2026-02-12T16:31:32.392078Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:56:20.412480Z","compaction_level":0,"original_size":0,"labels":["ci","phase2"],"dependencies":[{"issue_id":"bd-1lj","depends_on_id":"bd-1lo","type":"parent-child","created_at":"2026-02-12T16:31:32.394604Z","created_by":"tayloreernisse"},{"issue_id":"bd-1lj","depends_on_id":"bd-a7e","type":"blocks","created_at":"2026-02-12T16:31:32.395053Z","created_by":"tayloreernisse"}]}
{"id":"bd-1lo","title":"Epic: Distribution and CI","status":"open","priority":1,"issue_type":"task","created_at":"2026-02-12T16:22:28.089610Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:22:28.090122Z","compaction_level":0,"original_size":0,"labels":["epic"]}
{"id":"bd-1rk","title":"Implement cross-alias discovery (--all-aliases)","description":"## Background\n--all-aliases on list and search queries across every cached alias, returning results with an additional \"alias\" field per result. Useful for agents managing multiple APIs.\n\n## Approach\n1. In list execute: if --all-aliases, iterate all aliases via list_aliases(), load each index, filter/sort per-alias, merge results with \"alias\" field added to each endpoint item\n2. In search execute: same pattern — search each alias's index, merge results, re-sort by score\n3. Robot output: each endpoint/result includes \"alias\" string field identifying which spec it came from\n\n**Sorting rules:**\n- For `list --all-aliases`: merged endpoints sorted by (alias ASC, path ASC, method_rank ASC) where method_rank follows standard HTTP method ordering (GET=0, POST=1, PUT=2, PATCH=3, DELETE=4, etc.)\n- For `search --all-aliases`: merged results sorted by (score DESC, then normal tie-breaking within same score) — the alias field is just additional metadata, it does not affect ranking\n\n**Robot output envelope:**\n- `data.endpoints[]` or `data.results[]` — each item includes `\"alias\": \"petstore\"` field\n- `data.aliases_searched: string[]` — lists which aliases were queried (e.g., `[\"petstore\", \"github-api\", \"stripe\"]`)\n- This allows agents to detect if an alias was missing/skipped vs simply had no matching results\n\n**Error handling for individual alias failures:**\n- If one alias fails to load (corrupted index, missing files), do NOT abort the entire operation\n- Skip the failed alias and continue with remaining aliases\n- Add warning to `meta.warnings[]` array: `{\"alias\": \"broken-api\", \"code\": \"INDEX_LOAD_FAILED\", \"message\": \"...\"}`\n- Robot output still returns ok:true with partial results (this is a degraded success, not an error)\n- If ALL aliases fail, then return an error\n\n## Acceptance Criteria\n- [ ] `list --all-aliases --robot` returns endpoints from all aliases with alias field on each item\n- [ ] `search \"pet\" --all-aliases --robot` searches across all aliases with alias field on each result\n- [ ] List results sorted by alias ASC, then path ASC, then method_rank ASC\n- [ ] Search results sorted by score DESC (alias does not affect ranking)\n- [ ] Robot output includes data.aliases_searched listing all queried aliases\n- [ ] If one alias fails to load, operation continues with remaining aliases and meta.warnings populated\n- [ ] If all aliases fail, returns error (not partial success)\n- [ ] Human output groups or labels results by alias for readability\n\n## Edge Cases\n- **Single alias cached:** --all-aliases works but is equivalent to normal query (aliases_searched has one entry)\n- **No aliases cached:** Return error — no specs available\n- **One alias fails to load:** Skip with warning in meta.warnings, return results from healthy aliases\n- **All aliases fail:** Return error with details about each failure\n- **Duplicate endpoint paths across aliases:** Both appear in results, distinguished by alias field\n\n## Files\n- MODIFY: src/cli/list.rs (add --all-aliases logic)\n- MODIFY: src/cli/search.rs (add --all-aliases logic)\n\n## TDD Anchor\nRED: Write `test_list_all_aliases` — fetch 2 different specs, run list --all-aliases --robot, assert results contain endpoints from both with alias field.\nRED: Write `test_search_all_aliases` — fetch 2 specs, run search --all-aliases --robot, assert results from both with correct score-based sorting.\nRED: Write `test_all_aliases_partial_failure` — corrupt one alias index, run list --all-aliases, assert partial results returned with warning.\nGREEN: Implement cross-alias iteration.\nVERIFY: `cargo test test_list_all_aliases`\n\n## Dependency Context\nRequires list command (bd-3km) and search command (bd-acf) to be implemented first.","status":"open","priority":3,"issue_type":"task","created_at":"2026-02-12T16:29:50.184624Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:45:28.367812Z","compaction_level":0,"original_size":0,"labels":["global","phase2"],"dependencies":[{"issue_id":"bd-1rk","depends_on_id":"bd-3km","type":"blocks","created_at":"2026-02-12T16:29:50.187908Z","created_by":"tayloreernisse"},{"issue_id":"bd-1rk","depends_on_id":"bd-3ll","type":"parent-child","created_at":"2026-02-12T16:29:50.187260Z","created_by":"tayloreernisse"},{"issue_id":"bd-1rk","depends_on_id":"bd-acf","type":"blocks","created_at":"2026-02-12T16:29:50.188740Z","created_by":"tayloreernisse"}]}
{"id":"bd-1sb","title":"Implement configuration system with path resolution and auth profiles","description":"## Background\nswagger-cli uses TOML config files for user preferences and auth profiles, stored in XDG config dir. The config system handles path resolution with a specific precedence: --config > SWAGGER_CLI_CONFIG > SWAGGER_CLI_HOME > XDG defaults. Auth profiles allow loading credentials from config.toml instead of passing raw tokens on the command line.\n\n## Approach\nImplement Config, AuthConfig, CredentialSource, AuthType, DisplayConfig structs in src/core/config.rs per the PRD. Config::load() reads from config_path(), Config::save() writes with toml::to_string_pretty(). Both config_path() and cache_dir() implement the D7 override precedence using env vars SWAGGER_CLI_HOME, SWAGGER_CLI_CONFIG, SWAGGER_CLI_CACHE, and directories::ProjectDirs. CredentialSource is a tagged enum (Literal, EnvVar, Keyring) with serde tag=\"source\". AuthType is an enum (Bearer, ApiKey { header }). Default stale_threshold_days is 30.\n\n## Acceptance Criteria\n- [ ] Config::load() returns default Config when no file exists\n- [ ] Config::save() writes valid TOML that round-trips through load()\n- [ ] config_path() respects: --config flag > SWAGGER_CLI_CONFIG env > SWAGGER_CLI_HOME/config/config.toml > XDG\n- [ ] cache_dir() respects: SWAGGER_CLI_CACHE > SWAGGER_CLI_HOME/cache > XDG cache dir\n- [ ] AuthConfig with CredentialSource::EnvVar serializes/deserializes correctly\n- [ ] Default config has stale_threshold_days=30, empty auth_profiles, no default_alias\n- [ ] All tests hermetic (use SWAGGER_CLI_HOME with tempdir)\n\n## Files\n- CREATE: src/core/config.rs (Config, AuthConfig, CredentialSource, AuthType, DisplayConfig, Default impl, load/save, path resolution)\n- MODIFY: src/core/mod.rs (pub mod config;)\n\n## TDD Anchor\nRED: Write `test_config_path_precedence` — set SWAGGER_CLI_HOME to a tempdir, verify config_path() returns tempdir/config/config.toml. Then set SWAGGER_CLI_CONFIG to a specific path, verify it takes precedence.\nGREEN: Implement config_path() with env var checks.\nVERIFY: `cargo test test_config_path_precedence`\n\n## Edge Cases\n- CredentialSource::Keyring is Phase 2 — include the enum variant but document it as unimplemented\n- Config file might not exist (return default, don't error)\n- SWAGGER_CLI_HOME dir might not exist yet (create parent dirs on save)\n- toml crate is named `toml`, not `serde_toml`","status":"closed","priority":2,"issue_type":"task","created_at":"2026-02-12T16:25:15.475935Z","created_by":"tayloreernisse","updated_at":"2026-02-12T17:41:12.898251Z","closed_at":"2026-02-12T17:41:12.898204Z","close_reason":"Config with TOML load/save, path precedence, auth profiles","compaction_level":0,"original_size":0,"labels":["infrastructure","phase1"],"dependencies":[{"issue_id":"bd-1sb","depends_on_id":"bd-hcb","type":"parent-child","created_at":"2026-02-12T16:25:15.477635Z","created_by":"tayloreernisse"},{"issue_id":"bd-1sb","depends_on_id":"bd-ilo","type":"blocks","created_at":"2026-02-12T16:25:15.478018Z","created_by":"tayloreernisse"}]}
{"id":"bd-1x5","title":"Implement reliability stress tests and performance benchmarks","description":"## Background\nReliability tests validate the crash-consistency, concurrency safety, and determinism claims. These are the hardest tests but most important for production confidence. Includes fault injection (simulated crash at each write step), multi-process lock contention (32 concurrent processes), and property-based tests (proptest for deterministic ordering).\n\n## Approach\n**Crash consistency (tests/reliability/crash_consistency_test.rs):**\n- test_crash_before_meta_rename: write raw+index but not meta → read protocol detects → doctor --fix repairs\n- test_crash_after_raw_before_index: write raw but not index → doctor --fix rebuilds\n\n**Lock contention (tests/reliability/lock_contention_test.rs):**\n- test_concurrent_fetch_32_processes: spawn 32 threads, all fetch same alias with --force → verify all exit 0 or 9 (CACHE_LOCKED), no panics, final state passes doctor\n\n**Property-based (tests/reliability/property_test.rs with proptest):**\n- index_ordering_deterministic: random endpoints → build_index → build_index from shuffled → same JSON\n- hash_deterministic: same bytes → same hash\n\nAdd proptest = '1.0' to [dev-dependencies] in Cargo.toml alongside existing test deps.\n\n**Benchmarks (benches/perf.rs with Criterion):**\n- bench_load_index, bench_list_endpoints, bench_search_query on 500+ endpoint spec\n\n## Acceptance Criteria\n- [ ] Crash consistency tests verify doctor can repair all simulated crash states\n- [ ] 32-process contention test passes without deadlocks or corruption\n- [ ] Property-based tests verify deterministic ordering\n- [ ] Benchmarks establish baseline performance numbers\n- [ ] All reliability tests pass on CI\n\n## Files\n- CREATE: tests/reliability/crash_consistency_test.rs\n- CREATE: tests/reliability/lock_contention_test.rs\n- CREATE: tests/reliability/property_test.rs\n- CREATE: benches/perf.rs\n- MODIFY: Cargo.toml (add [[bench]] for criterion, add proptest dev-dep)\n\n## TDD Anchor\nRun: `cargo test --test crash_consistency && cargo test --test lock_contention && cargo test --test property`\nVERIFY: `cargo bench -- --test`\n\n## Dependency Context\nUses CacheManager write/read protocol from cache beads. Uses build_index from indexer bead. Uses compute_hash. Tests the claims made in the cache architecture.\n\n## Edge Cases\n- **Crash test cleanup:** Crash simulation tests must clean up temp files even on test failure. Use Drop guards or panic hooks.\n- **32-process test may exceed file descriptor limits:** On CI, ulimit may be low. Test should check and skip with a clear message if fd limit < 256.\n- **Property test shrinking:** proptest shrinking can be slow for complex inputs. Set max shrink iterations to avoid CI timeouts.\n- **Benchmark stability:** Criterion requires multiple iterations. First run creates baseline. Tests should not fail on benchmark regression — only warn.\n- **Lock contention test timing:** 32 threads racing for a lock is timing-dependent. Use a barrier to ensure all threads start simultaneously.","status":"open","priority":3,"issue_type":"task","created_at":"2026-02-12T16:30:59.112199Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:56:19.044503Z","compaction_level":0,"original_size":0,"labels":["phase2","testing"],"dependencies":[{"issue_id":"bd-1x5","depends_on_id":"bd-189","type":"blocks","created_at":"2026-02-12T16:30:59.114670Z","created_by":"tayloreernisse"},{"issue_id":"bd-1x5","depends_on_id":"bd-1ie","type":"blocks","created_at":"2026-02-12T16:30:59.113671Z","created_by":"tayloreernisse"},{"issue_id":"bd-1x5","depends_on_id":"bd-3ea","type":"blocks","created_at":"2026-02-12T16:30:59.114152Z","created_by":"tayloreernisse"},{"issue_id":"bd-1x5","depends_on_id":"bd-p7g","type":"parent-child","created_at":"2026-02-12T16:30:59.113195Z","created_by":"tayloreernisse"}]}
{"id":"bd-1y0","title":"Epic: Health and Cache Lifecycle","status":"open","priority":1,"issue_type":"task","created_at":"2026-02-12T16:22:24.038779Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:22:24.039351Z","compaction_level":0,"original_size":0,"labels":["epic"]}
{"id":"bd-21m","title":"Epic: Diff Command","status":"open","priority":1,"issue_type":"task","created_at":"2026-02-12T16:22:26.500265Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:22:26.501933Z","compaction_level":0,"original_size":0,"labels":["epic"]}
{"id":"bd-2e4","title":"Flesh out Phase 3 scope and requirements","description":"## Background\nPhase 3 beads (SBOM, keyring, curl gen, breaking-change classification, semantic search, YAML output) are currently stubs without enough detail for implementation. Before any Phase 3 work begins, the requirements and scope for each feature must be fleshed out with proper acceptance criteria, approach, and file lists.\n\n## What Needs to Happen\n1. Review each Phase 3 bead against the PRD's Phase 3 section\n2. Research any dependencies or design decisions not yet documented\n3. Write full bead descriptions (Background, Approach, Acceptance Criteria, Files, TDD Anchor, Edge Cases) for each Phase 3 bead\n4. Validate scope boundaries — what's in vs out for each feature\n\n## Acceptance Criteria\n- [ ] All Phase 3 beads have full descriptions (score 4+/5 on agent-readiness)\n- [ ] Each bead has concrete file lists and TDD anchors\n- [ ] Scope boundaries are documented (what's explicitly out of scope)\n- [ ] No unresolved ambiguities — all genuinely ambiguous decisions are resolved\n\n## Phase 3 Beads to Flesh Out\n- bd-37c: SBOM generation and cosign attestation\n- bd-3pz: OS keychain credential backend\n- bd-60k: Generate curl commands from endpoints\n- bd-j23: Breaking-change classification for diff\n- bd-132: Semantic search with embeddings\n- bd-b8h: YAML output format","status":"open","priority":3,"issue_type":"task","created_at":"2026-02-12T16:42:40.196904Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:42:40.200279Z","compaction_level":0,"original_size":0,"labels":["phase3","planning"],"dependencies":[{"issue_id":"bd-2e4","depends_on_id":"bd-3aq","type":"parent-child","created_at":"2026-02-12T16:42:40.200266Z","created_by":"tayloreernisse"}]}
{"id":"bd-2gp","title":"Implement golden robot output tests and index-only invariant tests","description":"## Background\nGolden tests are the #1 defense against robot JSON shape regressions. They verify structural invariants (ok, data, meta.schema_version, meta.tool_version, meta.command, meta.duration_ms) and snapshot-compare against golden files. Index-only invariant tests verify that list/search work without raw.json (core performance promise).\n\n## Approach\n**Golden tests (tests/integration/golden_test.rs):**\n1. For each command (list, show, search, schemas, tags, aliases), run with --robot\n2. Parse output as JSON, verify structural invariants (ok is bool, data is object, meta has required fields)\n3. Compare against golden snapshot files in tests/integration/golden/\n4. Fail CI if shape changes unless schema_version is incremented\n\n**Index-only invariant tests:**\n- test_list_does_not_read_raw_json: fetch spec, delete raw.json, run list — must succeed\n- test_search_does_not_read_raw_json: same pattern with search\n- test_tags_does_not_read_raw_json: same\n- test_schemas_list_does_not_read_raw_json: same (list mode only; show mode needs raw)\n\n**JSON Schema validation (optional enhancement):**\n- Create docs/robot-schema/v1/success.schema.json and error.schema.json\n- Validate robot output against these schemas in golden tests\n\n## Acceptance Criteria\n- [ ] Golden test verifies all 6 command outputs have correct structure\n- [ ] Index-only tests pass (list/search/tags/schemas-list work without raw.json)\n- [ ] Golden files exist in tests/integration/golden/\n- [ ] JSON Schema files exist in docs/robot-schema/v1/\n\n## Edge Cases\n- **duration_ms non-determinism:** Golden files must NOT include duration_ms in snapshot comparison (it changes every run). Strip or mask it before comparing.\n- **tool_version changes:** Updating Cargo.toml version breaks golden files. Golden comparison should either mask tool_version or tests should update golden files via an env var flag.\n- **Platform-specific key ordering:** serde_json with BTreeMap ensures deterministic ordering. Verify golden files use sorted keys.\n- **Index-only tests must verify raw.json is actually deleted:** Don't just skip loading it — physically remove the file and prove the command works without it.\n\n## Files\n- CREATE: tests/integration/golden_test.rs\n- CREATE: tests/integration/golden/*.json (golden snapshot files)\n- CREATE: docs/robot-schema/v1/success.schema.json\n- CREATE: docs/robot-schema/v1/error.schema.json\n\n## TDD Anchor\nRun all golden and invariant tests.\nVERIFY: `cargo test golden && cargo test does_not_read_raw`\n\n## Dependency Context\nRequires all query commands to be implemented. Uses test helpers from bd-lx6 (Create test fixtures and integration test helpers).","status":"open","priority":2,"issue_type":"task","created_at":"2026-02-12T16:30:59.080993Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:58:14.664977Z","compaction_level":0,"original_size":0,"labels":["phase2","testing"],"dependencies":[{"issue_id":"bd-2gp","depends_on_id":"bd-3bl","type":"blocks","created_at":"2026-02-12T16:30:59.083124Z","created_by":"tayloreernisse"},{"issue_id":"bd-2gp","depends_on_id":"bd-acf","type":"blocks","created_at":"2026-02-12T16:30:59.082691Z","created_by":"tayloreernisse"},{"issue_id":"bd-2gp","depends_on_id":"bd-lx6","type":"blocks","created_at":"2026-02-12T16:34:06.420878Z","created_by":"tayloreernisse"},{"issue_id":"bd-2gp","depends_on_id":"bd-p7g","type":"parent-child","created_at":"2026-02-12T16:30:59.082181Z","created_by":"tayloreernisse"},{"issue_id":"bd-2gp","depends_on_id":"bd-x15","type":"blocks","created_at":"2026-02-12T16:30:59.083539Z","created_by":"tayloreernisse"}]}
{"id":"bd-2mr","title":"Add supply chain hardening and robot JSON Schema artifacts","description":"## Background\nSupply chain hardening: release artifacts include SHA256SUMS + minisign signatures. Robot output JSON Schemas published as build artifacts for agent validation.\n\n## Approach\n\n### Supply Chain Artifacts\n1. Update release job in .gitlab-ci.yml to generate SHA256SUMS and sign with minisign\n2. Upload SHA256SUMS + SHA256SUMS.minisig alongside binaries to GitLab Package Registry\n3. Update install.sh to verify signature when minisign is available\n\n### JSON Schema Files\n\nCreate `docs/robot-schema/v1/success.schema.json`:\n```json\n{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"type\": \"object\",\n  \"required\": [\"ok\", \"data\", \"meta\"],\n  \"properties\": {\n    \"ok\": { \"type\": \"boolean\", \"const\": true },\n    \"data\": { \"type\": \"object\" },\n    \"meta\": {\n      \"type\": \"object\",\n      \"required\": [\"schema_version\", \"tool_version\", \"command\", \"duration_ms\"],\n      \"properties\": {\n        \"schema_version\": { \"type\": \"string\", \"pattern\": \"^\\\\d+\\\\.\\\\d+$\" },\n        \"tool_version\": { \"type\": \"string\" },\n        \"command\": { \"type\": \"string\" },\n        \"command_version\": { \"type\": \"string\", \"description\": \"Per-command payload version for independent evolution\" },\n        \"duration_ms\": { \"type\": \"integer\", \"minimum\": 0 }\n      }\n    }\n  },\n  \"additionalProperties\": false\n}\n```\n\nCreate `docs/robot-schema/v1/error.schema.json`:\n```json\n{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"type\": \"object\",\n  \"required\": [\"ok\", \"error\", \"meta\"],\n  \"properties\": {\n    \"ok\": { \"type\": \"boolean\", \"const\": false },\n    \"error\": {\n      \"type\": \"object\",\n      \"required\": [\"code\", \"message\"],\n      \"properties\": {\n        \"code\": { \"type\": \"string\" },\n        \"message\": { \"type\": \"string\" },\n        \"suggestion\": { \"type\": \"string\" }\n      }\n    },\n    \"meta\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"schema_version\": { \"type\": \"string\" },\n        \"tool_version\": { \"type\": \"string\" },\n        \"command\": { \"type\": \"string\" },\n        \"duration_ms\": { \"type\": \"integer\", \"minimum\": 0 }\n      }\n    }\n  },\n  \"additionalProperties\": false\n}\n```\n\n### Compatibility Policy\n- **No version bump:** Adding new optional fields to data or meta (additive changes)\n- **MUST bump schema_version:** Removing fields, renaming fields, changing field types, changing required status\n- **meta.command_version:** Each command can independently evolve its data payload structure. When a command's data shape changes in a breaking way, bump command_version without bumping the global schema_version. This allows agents to pin to specific command output shapes.\n\n## Acceptance Criteria\n- [ ] Release pipeline generates SHA256SUMS from all binary artifacts\n- [ ] minisign signature generated for SHA256SUMS (when key available in CI)\n- [ ] SHA256SUMS and SHA256SUMS.minisig uploaded alongside binaries\n- [ ] install.sh attempts signature verification when minisign is on PATH\n- [ ] docs/robot-schema/v1/success.schema.json matches the structure above\n- [ ] docs/robot-schema/v1/error.schema.json matches the structure above\n- [ ] success.schema.json meta requires: schema_version, tool_version, command, duration_ms\n- [ ] success.schema.json meta includes optional command_version field\n- [ ] error.schema.json error requires: code, message (suggestion is optional)\n- [ ] Both schemas have additionalProperties: false at top level\n- [ ] Schema files are valid JSON Schema (validate with a JSON Schema validator)\n\n## Files\n- MODIFY: .gitlab-ci.yml (add checksum + signing to release)\n- MODIFY: install.sh (add signature verification)\n- CREATE: docs/robot-schema/v1/success.schema.json\n- CREATE: docs/robot-schema/v1/error.schema.json\n\n## Dependency Context\nExtends CI pipeline from bd-1lj and install script from bd-gvr.\n\n## Edge Cases\n- **Schema evolution testing:** When robot output changes, both the code AND the JSON Schema must be updated together. Tests should validate all command outputs against the schemas.\n- **Minisign not available in CI:** If minisign is not installed, the release should still succeed but skip signing with a clear warning (don't fail the release).\n- **JSON Schema draft version:** Use 2020-12 draft. Older validators may not support it — document the minimum validator version.\n- **additionalProperties:false on nested objects:** The top-level schemas have it, but nested objects (data, meta) may need it too if strict validation is desired. Decision: only enforce at top level for now.","status":"open","priority":4,"issue_type":"task","created_at":"2026-02-12T16:31:32.482765Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:56:21.036013Z","compaction_level":0,"original_size":0,"labels":["ci","phase2"],"dependencies":[{"issue_id":"bd-2mr","depends_on_id":"bd-1lj","type":"blocks","created_at":"2026-02-12T16:34:06.478112Z","created_by":"tayloreernisse"},{"issue_id":"bd-2mr","depends_on_id":"bd-1lo","type":"parent-child","created_at":"2026-02-12T16:31:32.485330Z","created_by":"tayloreernisse"},{"issue_id":"bd-2mr","depends_on_id":"bd-gvr","type":"blocks","created_at":"2026-02-12T16:34:06.528568Z","created_by":"tayloreernisse"}]}
{"id":"bd-2pl","title":"Epic: Alias Management","status":"open","priority":1,"issue_type":"task","created_at":"2026-02-12T16:22:22.527514Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:22:22.528316Z","compaction_level":0,"original_size":0,"labels":["epic"]}
{"id":"bd-2s6","title":"Implement doctor command with integrity validation and --fix repair","description":"## Background\nThe doctor command validates installation health and cache integrity. It checks config/cache directories exist, validates each alias's cache files (meta, index, raw), detects integrity issues (generation/hash mismatches, stale index versions, missing files), warns on insecure config permissions, and validates all index pointers against raw.json. Optional --fix repairs recoverable issues.\n\n## Approach\nImplement src/cli/doctor.rs with DoctorArgs and execute():\n\n**Checks performed:**\n1. Config directory exists and is readable/writable\n2. Cache directory exists and is readable/writable\n3. For each alias: check meta.json exists, validate generation/index_hash/index_version against index.json, validate raw_hash against raw.json, validate all operation_ptr/schema_ptr resolve in raw.json\n4. Detect stale caches (>30 days, configurable via config)\n5. Check config.toml permissions -- warn if group/world readable when auth tokens present\n6. Report disk usage (per-alias and total)\n\n**--fix repair modes (per alias, after acquiring lock):**\n1. If raw exists but index missing/invalid or index_version mismatched -> rebuild index from raw\n2. If raw + index valid but meta missing -> reconstruct meta from raw + index\n3. If raw unreadable/unparseable -> delete alias (last resort)\n\n**Health status:** HEALTHY (no issues), WARNING (stale caches, permission issues), DEGRADED (some aliases have integrity issues but are fixable), UNHEALTHY (unfixable corruption).\n\n## Acceptance Criteria\n- [ ] doctor reports HEALTHY for a valid cache\n- [ ] doctor detects missing meta.json as integrity issue\n- [ ] doctor detects generation mismatch between meta and index\n- [ ] doctor detects invalid operation_ptr (pointer doesn't resolve)\n- [ ] doctor warns on stale caches (>30 days)\n- [ ] doctor warns on insecure config permissions\n- [ ] --fix rebuilds index from raw when index is invalid\n- [ ] --fix reconstructs meta when meta is missing but raw+index exist\n- [ ] --fix deletes alias only when raw is unreadable\n- [ ] Robot output: health status, per-alias status, warnings[], disk_usage\n\n## Edge Cases\n- **Concurrent doctor + fetch:** Doctor reads while fetch writes. Doctor should acquire read lock or tolerate mid-write state gracefully (report as integrity issue, not crash).\n- **Very large cache (hundreds of aliases):** Doctor must not OOM — process aliases one at a time, not load all into memory.\n- **Permission denied on cache directory:** Report as WARNING, not crash. Doctor should be resilient to partial access.\n- **Empty alias directory (no files):** Skip with warning, don't crash. This can happen from interrupted deletes.\n- **--fix on locked alias:** If another process holds the lock, skip that alias with warning (don't block).\n\n## Files\n- MODIFY: src/cli/doctor.rs (DoctorArgs, execute, check_alias, fix_alias, permission_check)\n- MODIFY: src/output/robot.rs (add output_doctor)\n- MODIFY: src/output/human.rs (add output_doctor)\n\n## TDD Anchor\nRED: Write `test_doctor_detects_missing_meta` -- create cache with raw+index but no meta, run doctor --robot, assert alias status is \"integrity_error\".\nGREEN: Implement per-alias integrity checking.\nVERIFY: `cargo test test_doctor_detects_missing_meta`\n\n## Dependency Context\nUses CacheManager (load_index, load_raw, list_aliases) from bd-3ea (cache read path). Uses SpecIndex and CacheMetadata types from bd-ilo (error types and core data models). Uses build_index from bd-189 (indexer) for --fix index rebuild.","status":"open","priority":2,"issue_type":"task","created_at":"2026-02-12T16:29:50.084259Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:58:11.000975Z","compaction_level":0,"original_size":0,"labels":["health","phase2"],"dependencies":[{"issue_id":"bd-2s6","depends_on_id":"bd-189","type":"blocks","created_at":"2026-02-12T16:29:50.088686Z","created_by":"tayloreernisse"},{"issue_id":"bd-2s6","depends_on_id":"bd-1y0","type":"parent-child","created_at":"2026-02-12T16:29:50.087511Z","created_by":"tayloreernisse"},{"issue_id":"bd-2s6","depends_on_id":"bd-3d2","type":"blocks","created_at":"2026-02-12T16:29:50.089158Z","created_by":"tayloreernisse"},{"issue_id":"bd-2s6","depends_on_id":"bd-3ea","type":"blocks","created_at":"2026-02-12T16:29:50.088266Z","created_by":"tayloreernisse"}]}
{"id":"bd-30a","title":"Implement aliases command with list, rename, delete, set-default","description":"## Background\nThe aliases command manages multiple API specs. List all aliases with stats, show details, rename, delete, set default. All operations except delete are metadata-only (fast). Delete removes the entire alias directory after acquiring lock.\n\n## Approach\nImplement src/cli/aliases.rs with AliasesArgs and execute():\n\n**AliasesArgs:** list (bool, default), show (Option<String>), rename (Option<Vec<String>> — [old, new], requires 2 values), delete (Option<String>), set_default (Option<String>).\n\n**Operations:**\n- **List:** CacheManager.list_aliases() -> display name, url, version, is_default, cached_at, size, endpoint/schema counts\n- **Show:** load meta for specific alias, display full details\n- **Rename:** validate new alias name format (same rules as alias creation — alphanumeric, hyphens, underscores), check new name does not already exist, rename directory atomically using `std::fs::rename()` syscall (atomic on same filesystem), if renamed alias was the default alias in config, update config.default_alias to the new name and save\n- **Delete:** acquire lock on alias directory, remove entire alias directory (`std::fs::remove_dir_all`), if deleted alias was the default alias, clear default_alias in config (set to None), save config. No confirmation prompt — CLI is non-interactive for agent compatibility. PRD says \"explicit delete required\" meaning the user must explicitly pass --delete, but no interactive Y/N prompt.\n- **Set-default:** verify alias exists in cache before setting, update config.default_alias, save config. If alias does not exist, return error with suggestion listing available aliases.\n\n## Error Handling Details\n\n**Rename errors:**\n- New name fails format validation -> error with INVALID_ALIAS_NAME code and suggestion showing valid format\n- New name already exists -> error with ALIAS_EXISTS code\n- Rename to same name -> no-op, return success (idempotent, do not error)\n- Old alias does not exist -> error with ALIAS_NOT_FOUND code\n- Filesystem rename fails -> error with IO_ERROR code\n\n**Delete errors:**\n- Alias does not exist -> error with ALIAS_NOT_FOUND code\n- Lock contention (e.g., sync running) -> error with LOCK_CONTENTION code and suggestion to retry\n- Deleting the only alias -> allowed (leaves empty aliases state, no special handling)\n\n**Set-default errors:**\n- Alias does not exist -> error with ALIAS_NOT_FOUND code and suggestion listing available aliases\n\n## Acceptance Criteria\n- [ ] `aliases --robot` lists all aliases with correct metadata (name, url, version, is_default, cached_at, size, endpoint_count, schema_count)\n- [ ] `aliases --show petstore` shows full details for one alias\n- [ ] `aliases --rename old new` renames directory atomically and updates config if renamed alias was default\n- [ ] `aliases --rename old old` (same name) is a no-op, returns success\n- [ ] `aliases --delete old-api` removes alias directory and clears default if it was default\n- [ ] Delete does NOT prompt for confirmation (non-interactive CLI)\n- [ ] `aliases --set-default petstore` updates config, errors if alias does not exist\n- [ ] Rename validates new alias format (alphanumeric, hyphens, underscores)\n- [ ] Rename checks new name does not already exist\n- [ ] Delete of default alias clears default_alias in config\n- [ ] Robot output for each operation is well-structured with ok/data/meta envelope\n- [ ] Error responses include appropriate error codes and suggestions\n\n## Edge Cases\n- **Rename to same name:** No-op, return success (idempotent behavior).\n- **Delete the only alias:** Allowed. Leaves cache in empty state. Subsequent commands that need an alias will error with ALIAS_NOT_FOUND suggesting the user fetch a spec.\n- **Delete while sync is running:** Lock contention. Return LOCK_CONTENTION error with suggestion to wait or retry. Do not force-delete.\n- **Set-default to non-existent alias:** Error with ALIAS_NOT_FOUND and suggestion listing available aliases from cache.\n- **Rename when target name has invalid characters:** Error with INVALID_ALIAS_NAME showing the format rules.\n\n## Files\n- MODIFY: src/cli/aliases.rs (AliasesArgs, execute, rename/delete/set-default logic)\n- MODIFY: src/output/robot.rs (add output_aliases)\n- MODIFY: src/output/human.rs (add output_aliases)\n\n## TDD Anchor\nRED: Write `test_aliases_list` — fetch two specs, run aliases --robot, assert data.aliases has length 2.\nRED: Write `test_aliases_rename` — rename an alias, verify directory moved and config updated.\nRED: Write `test_aliases_rename_same_name` — rename to same name, verify no-op success.\nRED: Write `test_aliases_delete` — delete alias, verify directory removed and config cleared.\nRED: Write `test_aliases_delete_lock_contention` — hold lock on alias, attempt delete, assert LOCK_CONTENTION error.\nGREEN: Implement list_aliases and output.\nVERIFY: `cargo test test_aliases_list`\n\n## Dependency Context\nUses CacheManager (list_aliases, delete_alias) from bd-3ea. Uses Config (default_alias, save) from bd-1sb.","status":"open","priority":2,"issue_type":"task","created_at":"2026-02-12T16:28:47.390765Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:46:14.418127Z","compaction_level":0,"original_size":0,"labels":["management","phase2"],"dependencies":[{"issue_id":"bd-30a","depends_on_id":"bd-1sb","type":"blocks","created_at":"2026-02-12T16:28:47.395669Z","created_by":"tayloreernisse"},{"issue_id":"bd-30a","depends_on_id":"bd-2pl","type":"parent-child","created_at":"2026-02-12T16:28:47.394226Z","created_by":"tayloreernisse"},{"issue_id":"bd-30a","depends_on_id":"bd-3d2","type":"blocks","created_at":"2026-02-12T16:28:47.396077Z","created_by":"tayloreernisse"},{"issue_id":"bd-30a","depends_on_id":"bd-3ea","type":"blocks","created_at":"2026-02-12T16:28:47.394978Z","created_by":"tayloreernisse"}]}
{"id":"bd-37c","title":"Add SBOM generation and cosign attestation","description":"## What\nGenerate SBOM (CycloneDX or SPDX) during CI build. Sign release artifacts with cosign for provenance attestation.\n\n## Acceptance Criteria\n- [ ] SBOM generated in CI pipeline\n- [ ] cosign attestation attached to release artifacts\n- [ ] Verifiable with cosign verify\n\n## Files\n- MODIFY: .gitlab-ci.yml (add SBOM + cosign steps)","status":"open","priority":4,"issue_type":"task","created_at":"2026-02-12T16:31:57.365996Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:42:45.149708Z","compaction_level":0,"original_size":0,"labels":["future","phase3"],"dependencies":[{"issue_id":"bd-37c","depends_on_id":"bd-2e4","type":"blocks","created_at":"2026-02-12T16:42:45.149692Z","created_by":"tayloreernisse"},{"issue_id":"bd-37c","depends_on_id":"bd-3aq","type":"parent-child","created_at":"2026-02-12T16:31:57.367010Z","created_by":"tayloreernisse"}]}
{"id":"bd-3aq","title":"Epic: Phase 3 Future","status":"open","priority":1,"issue_type":"task","created_at":"2026-02-12T16:22:29.339564Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:22:29.340289Z","compaction_level":0,"original_size":0,"labels":["epic"]}
{"id":"bd-3b6","title":"Build async HTTP client with SSRF protection and streaming download","description":"## Background\nswagger-cli fetches OpenAPI specs over HTTPS with strict security controls. The HTTP client must enforce SSRF protection (blocking private/loopback/link-local/multicast IPs), require HTTPS by default, support streaming downloads with max-bytes enforcement, and handle retries with backoff. This is async (tokio + reqwest).\n\n## Approach\nCreate src/core/http.rs with:\n\n**AsyncHttpClient struct:** Wraps reqwest::Client configured with rustls-tls, connect timeout (5s), overall timeout (configurable, default 10s), redirect policy (max 5). Provides `fetch_spec()` async method.\n\n**SSRF Protection:** Before connecting, resolve the hostname and check the IP against blocked CIDR ranges: 127.0.0.0/8, ::1, 169.254.0.0/16, fe80::/10, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, multicast (224.0.0.0/4, ff00::/8). Also check resolved IP AFTER redirects (DNS rebinding defense). Return PolicyBlocked error for violations. Accept --allow-private-host exceptions.\n\n**HTTPS Enforcement:** Reject http:// URLs unless --allow-insecure-http is set. Return PolicyBlocked.\n\n**Streaming Download:** Use response.chunk() in a loop, counting bytes. Abort when exceeding max_bytes (default 25MB). This prevents OOM on huge specs.\n\n**Retries:** Retry on 5xx and network errors up to N times (default 2) with exponential backoff + jitter. Honor Retry-After header. Do NOT retry 4xx (except 429 rate limit).\n\n**Auth Headers:** Accept Vec of (name, value) header pairs. Redact auth values in any error messages.\n\n## Acceptance Criteria\n- [ ] fetch_spec(\"https://...\") returns body bytes on success\n- [ ] Loopback IP (127.0.0.1) is blocked with PolicyBlocked error\n- [ ] Private IP (10.0.0.1) is blocked with PolicyBlocked error\n- [ ] Link-local (169.254.169.254) is blocked with PolicyBlocked error\n- [ ] http:// URL without --allow-insecure-http returns PolicyBlocked\n- [ ] Download exceeding max_bytes aborts with InvalidSpec error\n- [ ] 401/403 returns Auth error (not retried)\n- [ ] 500 is retried up to retry count\n- [ ] Auth header values are not included in error messages\n\n## Files\n- CREATE: src/core/http.rs (AsyncHttpClient, SSRF checks, streaming download, retries)\n- MODIFY: src/core/mod.rs (pub mod http;)\n\n## TDD Anchor\nRED: Write `test_ssrf_blocks_loopback` — call the IP validation function with 127.0.0.1, assert it returns Err(PolicyBlocked).\nGREEN: Implement CIDR range checking.\nVERIFY: `cargo test test_ssrf_blocks`\n\nAdditional tests (use mockito for HTTP):\n- test_fetch_success_https\n- test_fetch_rejects_http\n- test_fetch_max_bytes_abort\n- test_fetch_retries_on_500\n- test_fetch_no_retry_on_401\n- test_auth_header_redacted_in_errors\n\n## Edge Cases\n- DNS resolution must happen BEFORE connecting — use `tokio::net::lookup_host()` or reqwest's resolve API\n- DNS rebinding: a hostname might resolve to public IP initially, then private IP on redirect. Check IP at EACH hop.\n- IPv6 mapped IPv4 addresses (::ffff:127.0.0.1) must also be caught\n- Retry-After header may be seconds or HTTP-date — parse both formats\n- connect_timeout (5s) is separate from overall timeout (10s)\n\n## Dependency Context\nUses SwaggerCliError variants (Network, Auth, PolicyBlocked, InvalidSpec) from bd-ilo (error types and core data models).","status":"open","priority":2,"issue_type":"task","created_at":"2026-02-12T16:26:35.163338Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:55:53.972326Z","compaction_level":0,"original_size":0,"labels":["fetch","phase1","security"],"dependencies":[{"issue_id":"bd-3b6","depends_on_id":"bd-3d2","type":"blocks","created_at":"2026-02-12T16:26:35.167736Z","created_by":"tayloreernisse"},{"issue_id":"bd-3b6","depends_on_id":"bd-3ny","type":"parent-child","created_at":"2026-02-12T16:26:35.167093Z","created_by":"tayloreernisse"}]}
{"id":"bd-3bl","title":"Implement tags command","description":"## Background\nThe tags command is simple — it lists OpenAPI tags with their endpoint counts and descriptions. Pure index-backed, fast.\n\n## Approach\nImplement src/cli/tags.rs with TagsArgs (alias only) and execute(). Load index, output tags from index.tags (already sorted and counted during index building). Robot: data.tags[] with name, description, endpoint_count. Human: formatted list with \"X total\" in header.\n\n## Acceptance Criteria\n- [ ] `tags petstore --robot` returns JSON with data.tags array\n- [ ] Each tag has name (string), description (string|null), endpoint_count (integer)\n- [ ] Tags sorted by name ASC (pre-sorted in index)\n- [ ] Human output shows tag name, count, and description\n- [ ] Human output shows \"X total\" count in header line\n- [ ] Tags with no description show null in robot output, empty/omitted in human output\n- [ ] Empty tags list (spec with no tags defined) returns ok:true with data.tags as empty array\n- [ ] Robot meta includes standard fields (schema_version, tool_version, command, duration_ms)\n\n## Edge Cases\n- **Spec with no tags:** Return ok:true, data.tags: [], meta.total: 0. Human output: \"0 total\" header, no rows.\n- **Tags with empty descriptions:** Tag defined in spec with `description: \"\"` — treat as null/empty in output (same as missing description).\n- **Orphaned tags:** Tags defined at root level in the OpenAPI spec but not referenced by any operation. These should still appear in output with endpoint_count: 0 (they exist in the spec, the command reports what the spec declares).\n\n## Files\n- MODIFY: src/cli/tags.rs (TagsArgs, execute)\n- MODIFY: src/output/robot.rs (add output_tags)\n- MODIFY: src/output/human.rs (add output_tags)\n\n## TDD Anchor\nRED: Write `test_tags_list` — fetch petstore, run tags --robot, assert data.tags has expected tag count.\nRED: Write `test_tags_empty` — use a spec with no tags, assert data.tags is empty array.\nRED: Write `test_tags_no_description` — use a spec with a tag that has no description, assert description is null in robot output.\nGREEN: Implement tags command.\nVERIFY: `cargo test test_tags_list`\n\n## Dependency Context\nUses SpecIndex and IndexedTag types from bd-ilo (error types and core data models). Uses CacheManager.load_index from bd-3ea (cache read path).","status":"open","priority":3,"issue_type":"task","created_at":"2026-02-12T16:28:05.366529Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:55:58.303891Z","compaction_level":0,"original_size":0,"labels":["phase2","query"],"dependencies":[{"issue_id":"bd-3bl","depends_on_id":"bd-3d2","type":"blocks","created_at":"2026-02-12T16:28:05.368603Z","created_by":"tayloreernisse"},{"issue_id":"bd-3bl","depends_on_id":"bd-3ea","type":"blocks","created_at":"2026-02-12T16:28:05.368039Z","created_by":"tayloreernisse"},{"issue_id":"bd-3bl","depends_on_id":"bd-jek","type":"parent-child","created_at":"2026-02-12T16:28:05.367634Z","created_by":"tayloreernisse"}]}
{"id":"bd-3d2","title":"Build CLI skeleton with clap and output formatting framework","description":"## Background\nswagger-cli needs a CLI parser (clap) that routes to subcommands and an output framework that handles both human-readable and robot JSON formatting. The CLI skeleton defines the top-level Cli struct with global flags (--robot, --pretty, --network, --config) and the Commands enum with all 11 subcommands. The output framework provides consistent formatting for all commands.\n\n## Approach\n**CLI (src/cli/mod.rs):**\n- Define `Cli` struct with `#[derive(Parser)]`: command (Commands subcommand), robot (bool, global), pretty (bool, global), network (String, global, default \"auto\"), config (Option<PathBuf>, global, env SWAGGER_CLI_CONFIG)\n- Define `Commands` enum with all 11 variants: Fetch, List, Show, Search, Schemas, Tags, Aliases, Sync, Doctor, Cache, Diff\n- Create stub modules for each command (src/cli/fetch.rs, list.rs, etc.) with empty `FetchArgs` structs and `pub async fn execute()` signatures returning `Result<(), SwaggerCliError>`\n- Note: ALL execute functions use `async fn` signatures (we use tokio runtime throughout). Fetch, sync, and diff perform actual async I/O; query commands (list, show, search, etc.) are async in signature but may not await internally.\n\n**Main (src/main.rs):**\n- Pre-scan argv for `--robot` before clap parsing (handles parse errors in robot JSON)\n- `#[tokio::main] async fn main()` that tries Cli::try_parse_from, routes to command execute, handles errors\n- `output_robot_error()` and `output_human_error()` functions per PRD\n\n**Output (src/output/):**\n- `mod.rs`: Common traits/helpers, `RobotEnvelope` struct with ok, data, meta fields\n- `robot.rs`: Generic `robot_success()` and `robot_error()` functions that build the envelope with schema_version=1, tool_version from CARGO_PKG_VERSION, command name, duration_ms\n- `human.rs`: Stub formatters, TTY detection for color/unicode\n- `table.rs`: Table formatting helpers using `tabled` crate\n\n## Acceptance Criteria\n- [ ] `cargo build` succeeds with the full CLI skeleton\n- [ ] `swagger-cli --help` shows all 11 subcommands\n- [ ] `swagger-cli --version` prints version from Cargo.toml\n- [ ] `swagger-cli nonexistent --robot` outputs JSON error to stderr with code USAGE_ERROR and exits 2\n- [ ] `swagger-cli fetch --robot` (missing required args) outputs JSON error to stderr\n- [ ] RobotEnvelope serializes with ok, data, meta.schema_version, meta.tool_version, meta.command, meta.duration_ms\n- [ ] All command stubs return `Ok(())` (do nothing yet)\n\n## Files\n- CREATE: src/cli/mod.rs (Cli, Commands, pub mods)\n- CREATE: src/cli/fetch.rs, list.rs, show.rs, search.rs, schemas.rs, tags.rs, aliases.rs, sync.rs, doctor.rs, cache.rs, diff.rs (stub args + execute)\n- CREATE: src/output/mod.rs, src/output/robot.rs, src/output/human.rs, src/output/table.rs\n- MODIFY: src/main.rs (full entry point with error handling)\n- MODIFY: src/lib.rs (pub mod cli; pub mod output;)\n\n## TDD Anchor\nRED: Write test `test_robot_error_on_bad_command` using `assert_cmd` -- run `swagger-cli nonexistent --robot`, parse stderr as JSON, assert the JSON contains code=\"USAGE_ERROR\" and the process exits with code 2.\nGREEN: Implement main.rs pre-scan and robot error output.\nVERIFY: `cargo test test_robot_error_on_bad_command`\n\n## Edge Cases\n- Pre-scan argv for --robot MUST happen before clap parsing, otherwise clap's error output is plaintext even when agent expects JSON\n- Global --robot flag must be accessible from all subcommands (use `#[arg(long, global = true)]`)\n- duration_ms in robot envelope: use `std::time::Instant::now()` at start, elapsed at output\n- BTreeMap (not HashMap) for any constructed JSON objects to ensure deterministic key ordering\n\n## Dependency Context\nUses SwaggerCliError (exit_code, code, suggestion) from bd-ilo (error types and core data models).","status":"closed","priority":2,"issue_type":"task","created_at":"2026-02-12T16:24:12.604507Z","created_by":"tayloreernisse","updated_at":"2026-02-12T17:41:12.843580Z","closed_at":"2026-02-12T17:41:12.843535Z","close_reason":"CLI skeleton with 11 subcommands, robot/human output, main.rs routing","compaction_level":0,"original_size":0,"labels":["foundation","phase1"],"dependencies":[{"issue_id":"bd-3d2","depends_on_id":"bd-3e0","type":"parent-child","created_at":"2026-02-12T16:24:12.606348Z","created_by":"tayloreernisse"},{"issue_id":"bd-3d2","depends_on_id":"bd-ilo","type":"blocks","created_at":"2026-02-12T16:24:12.607227Z","created_by":"tayloreernisse"}]}
{"id":"bd-3e0","title":"Epic: Project Foundation","status":"open","priority":1,"issue_type":"task","created_at":"2026-02-12T16:22:16.954888Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:22:16.956168Z","compaction_level":0,"original_size":0,"labels":["epic"]}
{"id":"bd-3ea","title":"Implement cache read path with integrity validation","description":"## Background\nThe cache read path is used by every query command (list, search, tags, schemas, aliases, doctor). It loads index.json and meta.json, validates their integrity (generation match, hash match, index_version match), and provides the data to commands. The `show` command additionally loads raw.json. Coalesced last_accessed updates reduce write amplification for hot-read bursts.\n\n## Approach\nImplement on CacheManager:\n- `load_index(alias) -> Result<(SpecIndex, CacheMetadata)>`: Read meta.json first (commit marker). If missing -> AliasNotFound or CacheIntegrity. Read index.json. Validate: meta.index_version == index.index_version, meta.generation == index.generation, meta.index_hash == sha256(index.json bytes). Mismatch -> CacheIntegrity error. Update last_accessed if stale >10min (best-effort, no lock required).\n- `load_raw(alias, meta: &CacheMetadata) -> Result<serde_json::Value>`: Read raw.json, parse as Value. Validate meta.raw_hash == sha256(raw.json bytes). Return Value.\n- `list_aliases() -> Result<Vec<CacheMetadata>>`: Iterate alias directories, read meta.json from each. Skip broken/partial aliases (log warning).\n- `delete_alias(alias) -> Result<()>`: Remove alias directory after acquiring lock.\n- `default_alias() -> Option<String>`: Load config, return default_alias.\n- `alias_exists(alias) -> bool`: Check if meta.json exists in alias dir.\n\nCoalesced last_accessed: When load_index reads meta, check if meta.last_accessed is >10min old. If so, update only the last_accessed field in meta.json (best-effort write, no lock, ignore errors).\n\n## Acceptance Criteria\n- [ ] load_index succeeds for a valid cache (all 4 files present, hashes match)\n- [ ] load_index returns CacheIntegrity when generation mismatches\n- [ ] load_index returns CacheIntegrity when index_hash mismatches\n- [ ] load_index returns AliasNotFound when alias directory doesn't exist\n- [ ] load_raw validates raw_hash and returns parsed Value\n- [ ] list_aliases returns metadata for all valid aliases, skips broken ones\n- [ ] delete_alias removes the entire alias directory\n- [ ] last_accessed is updated at most once per 10 minutes\n\n## Files\n- MODIFY: src/core/cache.rs (add load_index, load_raw, list_aliases, delete_alias, default_alias, alias_exists, coalesced last_accessed)\n\n## TDD Anchor\nRED: Write `test_load_index_integrity_check` -- create a valid cache, then tamper with index.json (change a byte). Assert load_index returns CacheIntegrity error.\nGREEN: Implement hash validation in load_index().\nVERIFY: `cargo test test_load_index_integrity_check`\n\nAdditional tests:\n- test_load_index_success\n- test_load_index_missing_meta\n- test_load_raw_validates_hash\n- test_list_aliases_skips_broken\n- test_coalesced_last_accessed (verify not written within 10min window)\n\n## Edge Cases\n- list_aliases must not panic if an alias directory has no meta.json -- skip with warning\n- Coalesced write is best-effort: if it fails (permissions, concurrent write), silently ignore\n- load_raw is only called by show and schemas --show -- never by list/search/tags\n- Empty cache directory (no aliases) should return empty Vec, not error\n\n## Dependency Context\nUses CacheManager and write_cache() from bd-1ie (cache write path). Uses CacheMetadata, SpecIndex, and SwaggerCliError from bd-ilo (error types and core data models).","status":"open","priority":2,"issue_type":"task","created_at":"2026-02-12T16:25:15.526245Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:55:44.766573Z","compaction_level":0,"original_size":0,"labels":["infrastructure","phase1"],"dependencies":[{"issue_id":"bd-3ea","depends_on_id":"bd-1ie","type":"blocks","created_at":"2026-02-12T16:34:05.956814Z","created_by":"tayloreernisse"},{"issue_id":"bd-3ea","depends_on_id":"bd-hcb","type":"parent-child","created_at":"2026-02-12T16:25:15.528127Z","created_by":"tayloreernisse"},{"issue_id":"bd-3ea","depends_on_id":"bd-ilo","type":"blocks","created_at":"2026-02-12T16:25:15.528786Z","created_by":"tayloreernisse"}]}
{"id":"bd-3f4","title":"Implement sync command with change detection and index-based diffs","description":"## Background\nThe sync command checks if a remote spec has changed and re-fetches if needed. Change detection uses ETag/Last-Modified headers and content hash comparison. Index-based diffs compute added/removed/modified endpoints and schemas by comparing old vs new indexes. This is async (network calls).\n\n## Approach\nImplement src/cli/sync.rs with SyncArgs and async execute():\n\n**Single alias sync flow:**\n1. Load existing meta (get ETag, Last-Modified, content_hash)\n2. Fetch remote spec with conditional headers (If-None-Match, If-Modified-Since)\n3. If 304 Not Modified → report \"no changes\"\n4. If 200: compute new content_hash, compare with stored\n5. If hash matches → report \"no changes\" (content identical despite no 304)\n6. If changed: normalize, build new index, compare old vs new index\n7. Compute diff: added/removed/modified endpoints and schemas (compare by path+method / name)\n8. If not --dry-run: write new cache\n9. Output change summary\n\n**SyncArgs:** alias (Option<String>), all (bool), dry_run (bool), force (bool — re-fetch regardless), details (bool — include change lists), jobs (usize, default 4), per_host (usize, default 2), resume (bool), max_failures (Option<usize>).\n\n**--details output:** Capped at 200 items per category. Include truncated:bool flag.\n\n## Acceptance Criteria\n- [ ] Sync detects \"no changes\" via 304 response\n- [ ] Sync detects changes via content hash mismatch\n- [ ] --dry-run checks without writing\n- [ ] --force re-fetches regardless\n- [ ] --details includes added/removed/modified endpoint/schema lists (capped at 200)\n- [ ] Robot output: changed (bool), local_version, remote_version, changes.endpoints/schemas counts\n- [ ] --force with --dry-run: fetches and computes diff but doesn't write\n\n## Edge Cases\n- **304 Not Modified but content actually changed:** Server returns 304 incorrectly. Content hash comparison catches this (hash mismatch despite 304 = treat as changed).\n- **Huge index diff:** If thousands of endpoints changed, --details output must respect the 200-item cap with truncated:true flag.\n- **Server returns different Content-Type:** e.g., returns HTML error page instead of JSON. Format detection catches this — invalid spec error.\n- **ETag/Last-Modified missing on first fetch:** meta.etag and meta.last_modified will be None. Sync without conditional headers — always downloads full content.\n- **--force with --dry-run:** Fetch the content but don't write. Report what would change. This combo must be supported.\n\n## Files\n- MODIFY: src/cli/sync.rs (SyncArgs, execute, single_alias_sync, compute_index_diff)\n- MODIFY: src/output/robot.rs (add output_sync)\n- MODIFY: src/output/human.rs (add output_sync)\n\n## TDD Anchor\nRED: Write `test_sync_no_changes` — fetch petstore fixture locally, run sync --robot (mock server returns same content), assert changed==false.\nGREEN: Implement hash-based change detection.\nVERIFY: `cargo test test_sync_no_changes`\n\n## Dependency Context\nUses AsyncHttpClient from bd-3b6 for fetching. Uses indexer from bd-189 for rebuilding. Uses CacheManager from bd-3ea/bd-1ie for read/write. Requires a fetched spec in cache.","status":"open","priority":2,"issue_type":"task","created_at":"2026-02-12T16:28:47.430949Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:58:08.755348Z","compaction_level":0,"original_size":0,"labels":["phase2","sync"],"dependencies":[{"issue_id":"bd-3f4","depends_on_id":"bd-161","type":"parent-child","created_at":"2026-02-12T16:28:47.432443Z","created_by":"tayloreernisse"},{"issue_id":"bd-3f4","depends_on_id":"bd-16o","type":"blocks","created_at":"2026-02-12T16:28:47.432950Z","created_by":"tayloreernisse"},{"issue_id":"bd-3f4","depends_on_id":"bd-189","type":"blocks","created_at":"2026-02-12T16:28:47.433412Z","created_by":"tayloreernisse"}]}
{"id":"bd-3km","title":"Implement list command with index-backed filtering and sorting","description":"## Background\nThe list command is the most-used query command. It loads only index.json (never raw.json) and filters/sorts endpoints by method, tag, and path regex. This is the command that must hit <50ms for cached queries, even on large specs like Stripe (312 endpoints) and GitHub (800+ endpoints).\n\n## Approach\nImplement src/cli/list.rs with ListArgs and execute():\n\n**ListArgs:** alias (Option<String>), method (Option<String>, value_parser GET/POST/PUT/DELETE/PATCH), tag (Option<String>), path (Option<String> — regex), sort (String, default \"path\", values: path/method/tag), limit (usize, default 50), all (bool — show all, no limit), all_aliases (bool — cross-alias search, Phase 2 bead).\n\n**Execute flow:**\n1. Resolve alias (use default if not specified)\n2. CacheManager::load_index(alias) — loads index.json + meta.json only\n3. Build regex from --path (fail fast with USAGE_ERROR on invalid regex)\n4. Filter endpoints: method match (case-insensitive), tag contains, path regex match\n5. Sort using canonical method ranking: GET=0, POST=1, PUT=2, PATCH=3, DELETE=4, OPTIONS=5, HEAD=6, TRACE=7\n6. Apply limit (unless --all)\n7. Output robot JSON or human table\n\n**Robot output format:** Per PRD — ok:true, data.endpoints[], data.total, data.filtered, data.applied_filters, meta with alias/spec_version/cached_at/duration_ms.\n\n**Human output:** Tabular format with METHOD PATH SUMMARY, header with API title and total count, footer with \"Showing X of Y endpoints (filtered)\".\n\n## Acceptance Criteria\n- [ ] `swagger-cli list petstore --robot` returns all endpoints as JSON\n- [ ] --method POST filters to POST-only endpoints\n- [ ] --tag pet filters to pet-tagged endpoints\n- [ ] --path \"store.*\" filters by regex\n- [ ] Invalid regex returns USAGE_ERROR (exit 2)\n- [ ] Combined filters work (--method POST --tag pet)\n- [ ] Default limit is 50; --all shows all\n- [ ] Endpoints sorted by path ASC, method_rank ASC by default\n- [ ] --sort method sorts by method rank first\n- [ ] No alias + no default → CONFIG_ERROR with suggestion\n- [ ] Command completes in <50ms for 500+ endpoint index\n\n## Files\n- MODIFY: src/cli/list.rs (ListArgs, execute, filter_endpoints, sort_endpoints, method_rank)\n- MODIFY: src/output/robot.rs (add output_list)\n- MODIFY: src/output/human.rs (add output_list)\n\n## TDD Anchor\nRED: Write `test_list_filter_by_method` — set up test cache with petstore, run list --method POST --robot, parse JSON, assert all endpoints have method==POST.\nGREEN: Implement filter_endpoints with method check.\nVERIFY: `cargo test test_list_filter_by_method`\n\n## Edge Cases\n- Empty result set (no matches) should return ok:true with empty endpoints array, not error\n- Path regex with special chars (e.g., `/pet/{petId}` — the braces are regex special) — users must escape\n- Method comparison must be case-insensitive (user passes \"post\", spec has \"POST\")\n\n## Dependency Context\nUses CacheManager.load_index from bd-3ea (cache read). Uses SpecIndex/IndexedEndpoint types from bd-ilo. Uses CLI skeleton from bd-3d2. Requires a fetched spec in cache to work (tested via test helper that calls fetch with local fixture).","status":"open","priority":2,"issue_type":"task","created_at":"2026-02-12T16:27:27.054531Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:27:27.058996Z","compaction_level":0,"original_size":0,"labels":["phase1","query"],"dependencies":[{"issue_id":"bd-3km","depends_on_id":"bd-3d2","type":"blocks","created_at":"2026-02-12T16:27:27.058985Z","created_by":"tayloreernisse"},{"issue_id":"bd-3km","depends_on_id":"bd-3ea","type":"blocks","created_at":"2026-02-12T16:27:27.058492Z","created_by":"tayloreernisse"},{"issue_id":"bd-3km","depends_on_id":"bd-epk","type":"parent-child","created_at":"2026-02-12T16:27:27.057878Z","created_by":"tayloreernisse"}]}
{"id":"bd-3ll","title":"Epic: Global Features","status":"open","priority":1,"issue_type":"task","created_at":"2026-02-12T16:22:25.182608Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:22:25.183512Z","compaction_level":0,"original_size":0,"labels":["epic"]}
{"id":"bd-3ny","title":"Epic: Fetch Pipeline","status":"open","priority":1,"issue_type":"task","created_at":"2026-02-12T16:22:18.835110Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:22:18.835697Z","compaction_level":0,"original_size":0,"labels":["epic"]}
{"id":"bd-3pz","title":"Add OS keychain credential backend","description":"## What\nImplement CredentialSource::Keyring variant — resolve auth tokens from macOS Keychain or Linux Secret Service at runtime.\n\n## Acceptance Criteria\n- [ ] macOS Keychain lookup works\n- [ ] Linux Secret Service lookup works\n- [ ] Graceful fallback when keychain unavailable\n\n## Files\n- CREATE: src/core/keyring.rs\n- MODIFY: src/core/config.rs (implement Keyring resolution)","status":"open","priority":4,"issue_type":"task","created_at":"2026-02-12T16:31:57.341889Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:42:45.178091Z","compaction_level":0,"original_size":0,"labels":["future","phase3"],"dependencies":[{"issue_id":"bd-3pz","depends_on_id":"bd-2e4","type":"blocks","created_at":"2026-02-12T16:42:45.178074Z","created_by":"tayloreernisse"},{"issue_id":"bd-3pz","depends_on_id":"bd-3aq","type":"parent-child","created_at":"2026-02-12T16:31:57.342970Z","created_by":"tayloreernisse"}]}
{"id":"bd-60k","title":"Generate curl commands from endpoints","description":"## What\nNew command: swagger-cli curl <alias> <path> [--method METHOD] that generates a ready-to-run curl command with correct URL, headers, auth, and example request body.\n\n## Acceptance Criteria\n- [ ] Generates valid curl command for endpoint\n- [ ] Includes auth headers from profile\n- [ ] Includes example request body from schema\n\n## Files\n- CREATE: src/cli/curl.rs","status":"open","priority":4,"issue_type":"task","created_at":"2026-02-12T16:31:57.318701Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:42:45.203709Z","compaction_level":0,"original_size":0,"labels":["future","phase3"],"dependencies":[{"issue_id":"bd-60k","depends_on_id":"bd-2e4","type":"blocks","created_at":"2026-02-12T16:42:45.203691Z","created_by":"tayloreernisse"},{"issue_id":"bd-60k","depends_on_id":"bd-3aq","type":"parent-child","created_at":"2026-02-12T16:31:57.319605Z","created_by":"tayloreernisse"}]}
{"id":"bd-a7e","title":"Bootstrap Rust project and directory structure","description":"## Background\nswagger-cli is a greenfield Rust CLI tool for querying OpenAPI specifications. Nothing exists yet — no Cargo.toml, no src/, no VCS. This bead creates the complete project skeleton that all other beads build on.\n\nNote: The PRD code examples show sync patterns (blocking reqwest), but we've made a conscious decision to implement async from the start (tokio + non-blocking reqwest), following feedback-2 recommendations. The PRD code examples are stale in this regard.\n\n## Approach\n1. Run `cargo init --name swagger-cli` to create the Rust project\n2. Run `jj init --git` to initialize jj version control (colocated with git)\n3. Populate Cargo.toml with all dependencies (async tokio instead of blocking reqwest):\n   - `reqwest = { version = \"0.13\", default-features = false, features = [\"json\", \"rustls-tls\"] }`\n   - `tokio = { version = \"1\", features = [\"full\"] }`\n   - `serde`, `serde_json`, `serde_yaml`, `clap`, `anyhow`, `thiserror`, `toml`, `directories`, `colored`, `tabled`, `chrono`, `regex`, `sha2`, `fs2`\n   - dev-deps: `assert_cmd`, `predicates`, `tempfile`, `mockito`, `criterion`, `tokio` (macros+rt)\n4. Create full directory structure: src/{main.rs, lib.rs, errors.rs, utils.rs}, src/cli/, src/core/, src/output/, tests/integration/, tests/fixtures/, benches/, docs/robot-schema/v1/\n5. Add .gitignore, run `cargo check`\n\n## Acceptance Criteria\n- [ ] `cargo check` succeeds with zero errors\n- [ ] Cargo.toml has all dependencies with correct features (async reqwest, tokio)\n- [ ] src/main.rs has `#[tokio::main] async fn main()` that exits 0\n- [ ] All directories from project structure exist\n- [ ] src/lib.rs declares pub mods for cli, core, output, errors, utils\n- [ ] jj initialized (`.jj/` exists)\n- [ ] .gitignore present\n\n## Files\n- CREATE: Cargo.toml, src/main.rs, src/lib.rs, src/errors.rs, src/utils.rs, src/cli/mod.rs, src/core/mod.rs, src/output/mod.rs, .gitignore\n\n## TDD Anchor\nRED: `cargo check` fails (no modules). GREEN: Create placeholders. VERIFY: `cargo check && echo OK`\n\n## Edge Cases\n- Use `edition = \"2021\"` (safer for dep compat)\n- Do NOT add `[[bench]]` entries yet\n- main.rs should NOT do any real work yet","status":"closed","priority":2,"issue_type":"task","created_at":"2026-02-12T16:23:21.100423Z","created_by":"tayloreernisse","updated_at":"2026-02-12T17:33:03.858953Z","closed_at":"2026-02-12T17:33:03.858784Z","close_reason":"Completed: project bootstrapped with edition 2024, all deps, async tokio, directory structure, jj init","compaction_level":0,"original_size":0,"labels":["foundation","phase1"],"dependencies":[{"issue_id":"bd-a7e","depends_on_id":"bd-3e0","type":"parent-child","created_at":"2026-02-12T16:23:21.102893Z","created_by":"tayloreernisse"}]}
{"id":"bd-acf","title":"Implement search engine with tokenized scoring and search command","description":"## Background\nThe search engine is a core piece of swagger-cli. It provides tokenized multi-term text search across endpoint paths, summaries, descriptions, and schema names. All search is index-backed (never loads raw.json). Scores are quantized to integer basis points for cross-platform determinism. Results include ranked ordering with stable tie-breaking.\n\n## Approach\nImplement src/core/search.rs with SearchEngine struct and src/cli/search.rs with SearchArgs:\n\n**SearchEngine:** Takes a SpecIndex reference. search() method tokenizes query (whitespace-split unless --exact), scores each endpoint and schema against terms with field weights: path=10, summary=5, description=2, schema_name=8. Coverage boost: matching more terms increases score (score *= 1.0 + coverage_ratio). Quantize: (raw_float * 100.0).round() as u32.\n\n**Tie-breaking (deterministic):** Primary: score DESC. Secondary: type ordinal (endpoint=0 before schema=1). Tertiary: path/name ASC, method_rank ASC. Assign 1-based rank after sorting.\n\n**Unicode-safe snippets:** safe_snippet() uses char_indices() to find char-boundary-safe positions. Context window of 50 chars before/after match. Prefix/suffix with \"...\" when truncated.\n\n**SearchArgs:** alias (Option<String>), query (String, positional), case_sensitive (bool), exact (bool), in_fields (Option<String> -- comma-separated: all/paths/descriptions/schemas, invalid -> USAGE_ERROR), limit (usize, default 20), all_aliases (bool -- Phase 2 cross-alias).\n\n**SearchOptions:** search_paths, search_descriptions, search_schemas (parsed from --in), case_sensitive, exact, limit.\n\n## Acceptance Criteria\n- [ ] search(\"pet status\") finds endpoints with \"pet\" and \"status\" in path/summary\n- [ ] Scores quantized to integer (u32), deterministic across platforms\n- [ ] --exact treats query as single phrase\n- [ ] --case-sensitive respects case\n- [ ] --in paths only searches path field\n- [ ] --in invalid_field returns USAGE_ERROR\n- [ ] Results sorted by score DESC with stable tie-breaking\n- [ ] Unicode-safe snippets don't panic on multi-byte chars\n- [ ] Robot output: results[] with type, path/name, method, summary, rank, score, matches[]\n- [ ] Search never loads raw.json (index-only)\n\n## Files\n- CREATE: src/core/search.rs (SearchEngine, SearchResult, SearchResultType, Match, SearchOptions, tokenize, safe_snippet)\n- MODIFY: src/cli/search.rs (SearchArgs, execute)\n- MODIFY: src/output/robot.rs (add output_search)\n- MODIFY: src/output/human.rs (add output_search)\n\n## TDD Anchor\nRED: Write `test_search_basic` -- create a SpecIndex with petstore endpoints, search for \"pet status\", assert results include /pet/findByStatus.\nGREEN: Implement SearchEngine::search().\nVERIFY: `cargo test test_search_basic`\n\nRED: Write `test_search_scores_deterministic` -- search for \"pet\" on petstore index, record scores, search again, assert identical scores and ordering.\nGREEN: Implement quantized scoring with stable sort.\nVERIFY: `cargo test test_search_scores_deterministic`\n\n## Edge Cases\n- Empty query should return empty results, not error\n- Single-char queries should work (common for agents: \"/\" to find all paths)\n- Coverage boost division by zero: if terms.len() == 0, skip boost (shouldn't happen with non-empty query)\n- safe_snippet on very short text: don't add \"...\" if text fits entirely within context\n\n## Dependency Context\nUses SpecIndex, IndexedEndpoint, and IndexedSchema types from bd-ilo (error types and core data models). Uses CacheManager.load_index from bd-3ea (cache read path). Uses CLI skeleton from bd-3d2.","status":"open","priority":2,"issue_type":"task","created_at":"2026-02-12T16:28:05.308043Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:55:56.194230Z","compaction_level":0,"original_size":0,"labels":["phase2","query"],"dependencies":[{"issue_id":"bd-acf","depends_on_id":"bd-3d2","type":"blocks","created_at":"2026-02-12T16:28:05.310709Z","created_by":"tayloreernisse"},{"issue_id":"bd-acf","depends_on_id":"bd-3ea","type":"blocks","created_at":"2026-02-12T16:28:05.310222Z","created_by":"tayloreernisse"},{"issue_id":"bd-acf","depends_on_id":"bd-jek","type":"parent-child","created_at":"2026-02-12T16:28:05.309771Z","created_by":"tayloreernisse"}]}
{"id":"bd-b8h","title":"Add YAML output format (--format yaml)","description":"## What\nAdd --format yaml option to list/show/search/schemas commands. Use serde_yaml for serialization with deterministic key ordering. Create YAML golden fixtures.\n\n## Acceptance Criteria\n- [ ] --format yaml outputs valid YAML for all query commands\n- [ ] YAML output is deterministic (sorted keys)\n- [ ] Golden YAML fixtures exist\n\n## Files\n- MODIFY: src/output/mod.rs (add yaml output mode)\n- CREATE: src/output/yaml.rs","status":"open","priority":4,"issue_type":"task","created_at":"2026-02-12T16:31:57.239297Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:42:45.279099Z","compaction_level":0,"original_size":0,"labels":["future","phase3"],"dependencies":[{"issue_id":"bd-b8h","depends_on_id":"bd-2e4","type":"blocks","created_at":"2026-02-12T16:42:45.279082Z","created_by":"tayloreernisse"},{"issue_id":"bd-b8h","depends_on_id":"bd-3aq","type":"parent-child","created_at":"2026-02-12T16:31:57.241719Z","created_by":"tayloreernisse"}]}
{"id":"bd-epk","title":"Epic: Query Commands Phase 1","status":"open","priority":1,"issue_type":"task","created_at":"2026-02-12T16:22:20.420042Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:22:20.420513Z","compaction_level":0,"original_size":0,"labels":["epic"]}
{"id":"bd-gvr","title":"Create Dockerfile and installation script","description":"## Background\nDockerfile for minimal Alpine-based image and install.sh for curl-based binary installation with checksum/signature verification.\n\n## Approach\n\n**Dockerfile (multi-stage build):**\n- Builder stage: `FROM rust:1.93-alpine` as builder, `apk add musl-dev`, `COPY . .`, `cargo build --release --locked --target x86_64-unknown-linux-musl`\n- Runtime stage: `FROM alpine:latest`, `apk add --no-cache ca-certificates`, `COPY --from=builder /app/target/x86_64-unknown-linux-musl/release/swagger-cli /usr/local/bin/swagger-cli`\n- Pre-create XDG dirs: `mkdir -p /root/.config/swagger-cli /root/.cache/swagger-cli/aliases`\n- `ENTRYPOINT [\"swagger-cli\"]` (no CMD — user passes subcommands directly)\n\n**install.sh:**\n- Header: `#!/usr/bin/env bash`, `set -euo pipefail`\n- Secure temp directory: `mktemp -d` with cleanup trap (`trap \"rm -rf $TMPDIR\" EXIT`)\n- OS detection: `uname -s` → Darwin or Linux (reject others with clear error)\n- Arch detection: `uname -m` → arm64/aarch64 maps to aarch64, x86_64 stays x86_64 (reject others)\n- Download URL: GitLab Package Registry URL pattern, constructed from OS+arch variables\n- Download: `curl -fsSL` binary + SHA256SUMS file\n- Checksum verification (portable): Linux uses `sha256sum --check`, macOS uses `shasum -a 256 --check` — detect which is available\n- Optional minisign verification: if `minisign` is on PATH, download `.minisig` file and verify signature; if not on PATH, print info message and skip (not an error)\n- Install: `chmod +x`, move to `/usr/local/bin/` (or `~/.local/bin/` if no write access to /usr/local/bin)\n- PATH check: verify install dir is on PATH, print warning if not with suggested export command\n\n## Acceptance Criteria\n- [ ] Dockerfile builds successfully with `docker build .`\n- [ ] Container runs `swagger-cli --version` and exits 0\n- [ ] Docker image is minimal (Alpine-based runtime, no build tools in final image)\n- [ ] install.sh starts with `set -euo pipefail` and creates secure temp dir with cleanup trap\n- [ ] install.sh detects OS (Darwin/Linux) and architecture (arm64/x86_64) correctly\n- [ ] install.sh rejects unsupported OS/arch with clear error message\n- [ ] Checksum verification works on Linux (sha256sum) and macOS (shasum -a 256)\n- [ ] Checksum failure aborts install with non-zero exit\n- [ ] Optional minisign verification runs when minisign is available, skips gracefully when not\n- [ ] Binary installed to /usr/local/bin or ~/.local/bin with executable permissions\n- [ ] PATH warning printed if install directory not on PATH\n\n## Files\n- CREATE: Dockerfile\n- CREATE: install.sh\n\n## TDD Anchor\nVERIFY: `docker build -t swagger-cli-test . && docker run swagger-cli-test --version`\nVERIFY: `bash -n install.sh` (syntax check)\n\n## Edge Cases\n- **musl vs glibc:** Alpine uses musl. The Dockerfile must use the musl target, not the gnu target. Mixing causes runtime failures.\n- **Rootless Docker:** ENTRYPOINT should work regardless of UID. Don't assume /root/ — use $HOME or a configurable path.\n- **install.sh on minimal systems:** Some minimal Docker images don't have `curl`. The script should check for curl and error with a clear message.\n- **Interrupted install:** The trap ensures temp dir cleanup on any exit (EXIT, not just specific signals). Verify install.sh doesn't leave artifacts on Ctrl+C.\n- **Apple Silicon detection:** `uname -m` returns \"arm64\" on macOS but \"aarch64\" on Linux. Both must map to the aarch64 binary.","status":"open","priority":3,"issue_type":"task","created_at":"2026-02-12T16:31:32.440225Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:56:19.763349Z","compaction_level":0,"original_size":0,"labels":["ci","phase2"],"dependencies":[{"issue_id":"bd-gvr","depends_on_id":"bd-1lo","type":"parent-child","created_at":"2026-02-12T16:31:32.444746Z","created_by":"tayloreernisse"},{"issue_id":"bd-gvr","depends_on_id":"bd-a7e","type":"blocks","created_at":"2026-02-12T16:31:32.445590Z","created_by":"tayloreernisse"}]}
{"id":"bd-hcb","title":"Epic: Config and Cache Infrastructure","status":"open","priority":1,"issue_type":"task","created_at":"2026-02-12T16:22:17.707241Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:22:17.707865Z","compaction_level":0,"original_size":0,"labels":["epic"]}
{"id":"bd-ilo","title":"Implement error types and core data models","description":"## Background\nEvery command in swagger-cli returns typed errors that map to specific exit codes and robot JSON error codes. This bead defines the complete error type system and the core data models (SpecIndex, CacheMetadata, IndexedEndpoint, etc.) that all commands operate on. These types are the backbone of the entire application.\n\n## Approach\nImplement `SwaggerCliError` enum in `src/errors.rs` with variants: Usage, CacheLocked, Network, InvalidSpec, AliasNotFound, AliasExists, Cache, CacheIntegrity, Config, Auth, Io, Json, OfflineMode, PolicyBlocked. Each variant maps to an exit code (2-16), a string error code (USAGE_ERROR, CACHE_LOCKED, etc.), and an optional suggestion string. Use `thiserror::Error` for Display derivation.\n\nImplement core data models in `src/core/spec.rs`: SpecIndex (with index_version, generation, content_hash, openapi, info, endpoints, schemas, tags), IndexInfo, IndexedEndpoint (with path, method, summary, description, operation_id, tags, deprecated, parameters, request_body_required, request_body_content_types, security_schemes, security_required, operation_ptr), IndexedParam (name, location, required, description), IndexedSchema (name, schema_ptr), IndexedTag (name, description, endpoint_count). All derive Serialize, Deserialize, Debug, Clone.\n\nImplement CacheMetadata in `src/core/cache.rs` types section (or a separate types file): alias, url, fetched_at, last_accessed, content_hash, raw_hash, etag, last_modified, spec_version, spec_title, endpoint_count, schema_count, raw_size_bytes, source_format, index_version, generation, index_hash. Include `is_stale()` method.\n\n## Acceptance Criteria\n- [ ] SwaggerCliError has all 14 variants with correct exit_code(), code(), and suggestion() methods\n- [ ] SpecIndex and all index types compile and derive Serialize + Deserialize\n- [ ] CacheMetadata compiles with all fields and is_stale() works correctly\n- [ ] `cargo test --lib` passes for error mapping tests\n- [ ] No use of `any` type -- all fields have concrete types with explicit Rust type annotations\n\n## Files\n- CREATE: src/errors.rs (SwaggerCliError enum, exit_code/code/suggestion impls)\n- CREATE: src/core/spec.rs (SpecIndex, IndexInfo, IndexedEndpoint, IndexedParam, IndexedSchema, IndexedTag)\n- CREATE: src/core/cache.rs (CacheMetadata struct and related types — CacheManager is added later by bd-1ie)\n- CREATE: src/core/mod.rs (pub mod spec; pub mod cache; pub mod config; pub mod search;)\n- MODIFY: src/lib.rs (add pub mod errors; ensure pub mod core;)\n\n## TDD Anchor\nRED: Write `test_error_exit_codes` that asserts each SwaggerCliError variant returns the correct exit code (Usage->2, Network->4, InvalidSpec->5, AliasExists->6, Auth->7, AliasNotFound->8, CacheLocked->9, Cache->10, Config->11, Io->12, Json->13, CacheIntegrity->14, OfflineMode->15, PolicyBlocked->16).\nGREEN: Implement all variants and methods.\nVERIFY: `cargo test test_error_exit_codes`\n\n## Edge Cases\n- AliasNotFound suggestion references `swagger-cli aliases --list` (not just the alias name)\n- suggestion() returns Option<String> -- some variants (Io, Json) have no suggestion\n- Network variant wraps reqwest::Error via #[from] -- but since we use async reqwest, ensure the Error type is the async one","status":"closed","priority":2,"issue_type":"task","created_at":"2026-02-12T16:23:46.561151Z","created_by":"tayloreernisse","updated_at":"2026-02-12T17:37:07.284171Z","closed_at":"2026-02-12T17:37:07.284059Z","close_reason":"Completed: SwaggerCliError with 14 variants, SpecIndex, CacheMetadata, all tests pass","compaction_level":0,"original_size":0,"labels":["foundation","phase1"],"dependencies":[{"issue_id":"bd-ilo","depends_on_id":"bd-3e0","type":"parent-child","created_at":"2026-02-12T16:23:46.566627Z","created_by":"tayloreernisse"},{"issue_id":"bd-ilo","depends_on_id":"bd-a7e","type":"blocks","created_at":"2026-02-12T16:23:46.566979Z","created_by":"tayloreernisse"}]}
{"id":"bd-j23","title":"Add breaking-change classification for diff command","description":"## What\nExtend diff command with heuristic-based breaking-change classification. Removed endpoint = breaking. Removed required parameter = breaking. Added optional field = non-breaking. Changed type = breaking.\n\n## Acceptance Criteria\n- [ ] Each change classified as breaking/non-breaking/unknown\n- [ ] --fail-on breaking uses classification (not just structural)\n- [ ] classification field in robot output\n\n## Files\n- MODIFY: src/cli/diff.rs (add classification logic)","status":"open","priority":4,"issue_type":"task","created_at":"2026-02-12T16:31:57.292836Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:42:45.229543Z","compaction_level":0,"original_size":0,"labels":["future","phase3"],"dependencies":[{"issue_id":"bd-j23","depends_on_id":"bd-1ck","type":"blocks","created_at":"2026-02-12T16:31:57.294318Z","created_by":"tayloreernisse"},{"issue_id":"bd-j23","depends_on_id":"bd-2e4","type":"blocks","created_at":"2026-02-12T16:42:45.229527Z","created_by":"tayloreernisse"},{"issue_id":"bd-j23","depends_on_id":"bd-3aq","type":"parent-child","created_at":"2026-02-12T16:31:57.293815Z","created_by":"tayloreernisse"}]}
{"id":"bd-jek","title":"Epic: Query Commands Phase 2","status":"open","priority":1,"issue_type":"task","created_at":"2026-02-12T16:22:21.465792Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:22:21.466699Z","compaction_level":0,"original_size":0,"labels":["epic"]}
{"id":"bd-lx6","title":"Create test fixtures and integration test helpers","description":"## Background\nAll integration tests need test fixtures (OpenAPI spec files) and helper functions to set up hermetic test environments. This bead creates the fixtures and test infrastructure that all other test beads depend on.\n\n## Approach\n1. Create tests/fixtures/petstore.json — download the standard Petstore v3 spec (JSON format, ~50KB, 19 endpoints)\n2. Create tests/fixtures/petstore.yaml — same spec in YAML format (for format normalization tests)\n3. Create tests/fixtures/minimal.json — minimal valid OpenAPI 3.0 spec (3 endpoints, for fast tests)\n4. Create tests/helpers/mod.rs — shared test utilities:\n   - setup_test_env() → creates tempdir, sets SWAGGER_CLI_HOME, returns TestEnv struct with paths\n   - fetch_fixture(env, fixture_name, alias) → runs swagger-cli fetch with local fixture file\n   - run_cmd(args) → creates assert_cmd Command with SWAGGER_CLI_HOME set\n   - parse_robot_json(output) → parses stdout as serde_json::Value\n\n## Acceptance Criteria\n- [ ] petstore.json is a valid OpenAPI 3.0 spec with 19+ endpoints\n- [ ] petstore.yaml is equivalent YAML version\n- [ ] minimal.json is valid OpenAPI 3.0 with 3 endpoints\n- [ ] setup_test_env() creates isolated tempdir with SWAGGER_CLI_HOME\n- [ ] fetch_fixture() successfully caches a fixture spec\n- [ ] All test helpers compile and can be used from integration tests\n\n## Files\n- CREATE: tests/fixtures/petstore.json (Petstore v3 spec)\n- CREATE: tests/fixtures/petstore.yaml (same in YAML)\n- CREATE: tests/fixtures/minimal.json (minimal 3-endpoint spec)\n- CREATE: tests/helpers/mod.rs (TestEnv, setup_test_env, fetch_fixture, run_cmd, parse_robot_json)\n\n## TDD Anchor\nRED: Write `test_fixture_is_valid_json` — parse petstore.json, assert it has \"openapi\" and \"paths\" keys.\nGREEN: Create the fixture file.\nVERIFY: `cargo test test_fixture_is_valid`\n\n## Edge Cases\n- Fixtures must use absolute paths (canonicalize) for file:// URLs\n- petstore.json should be a real Petstore spec, not a minimal stub\n- SWAGGER_CLI_HOME must be set BEFORE any command runs (use env() on assert_cmd)\n- Test helpers should clean up tempdirs (use TempDir which auto-cleans on drop)","status":"open","priority":2,"issue_type":"task","created_at":"2026-02-12T16:30:59.014337Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:34:06.397049Z","compaction_level":0,"original_size":0,"labels":["phase1","testing"],"dependencies":[{"issue_id":"bd-lx6","depends_on_id":"bd-16o","type":"blocks","created_at":"2026-02-12T16:30:59.016051Z","created_by":"tayloreernisse"},{"issue_id":"bd-lx6","depends_on_id":"bd-p7g","type":"parent-child","created_at":"2026-02-12T16:30:59.015600Z","created_by":"tayloreernisse"}]}
{"id":"bd-p7g","title":"Epic: Testing","status":"open","priority":1,"issue_type":"task","created_at":"2026-02-12T16:22:27.310201Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:22:27.311058Z","compaction_level":0,"original_size":0,"labels":["epic"]}
{"id":"bd-rex","title":"Write integration tests for fetch and query commands","description":"## Background\nIntegration tests validate the full command pipeline end-to-end: fetch → list → show → search → schemas → tags. These tests use assert_cmd to run the binary, mockito for HTTP mocking, and the test fixtures/helpers from the previous bead.\n\n## Approach\nCreate tests/integration/ test files:\n\n**fetch_test.rs:** test_fetch_success (local file), test_fetch_invalid_json, test_fetch_network_error, test_fetch_alias_exists, test_fetch_force_overwrites, test_fetch_yaml_file, test_fetch_stdin\n\n**list_test.rs:** test_list_all_endpoints, test_list_filter_by_method, test_list_filter_by_tag, test_list_path_regex, test_list_invalid_regex_error, test_list_combined_filters, test_list_default_limit, test_list_all_flag\n\n**show_test.rs:** test_show_endpoint_details, test_show_multiple_methods_error, test_show_expand_refs\n\n**search_test.rs:** test_search_basic, test_search_exact, test_search_case_sensitive, test_search_in_paths_only, test_search_invalid_field_error\n\n**schemas_test.rs:** test_schemas_list, test_schemas_show, test_schemas_name_filter\n\n**aliases_test.rs:** test_aliases_list, test_aliases_rename, test_aliases_delete, test_aliases_set_default\n\n## Acceptance Criteria\n- [ ] All fetch tests pass (success, errors, force, YAML, stdin)\n- [ ] All list tests pass (filters, sorting, limits)\n- [ ] All show tests pass (details, ref expansion, method disambiguation)\n- [ ] All search tests pass (basic, exact, case-sensitive, field scoping)\n- [ ] Schema and alias tests pass\n- [ ] All tests are hermetic (SWAGGER_CLI_HOME in tempdir)\n- [ ] No real network calls (local fixtures or mockito)\n\n## Edge Cases\n- **Test isolation:** Each test MUST use its own tempdir for SWAGGER_CLI_HOME. Tests running in parallel must not share cache state.\n- **CI binary not built:** Tests use assert_cmd which builds the binary. Ensure Cargo.toml has the right [[bin]] target.\n- **Mockito port conflicts:** Each test needing a mock server should use mockito::Server::new() which picks a random port, not a hardcoded port.\n- **Fixture file paths:** Use canonicalized absolute paths for local file fetch tests. Relative paths may break depending on test runner CWD.\n\n## Files\n- CREATE: tests/integration/fetch_test.rs\n- CREATE: tests/integration/list_test.rs\n- CREATE: tests/integration/show_test.rs\n- CREATE: tests/integration/search_test.rs\n- CREATE: tests/integration/schemas_test.rs\n- CREATE: tests/integration/aliases_test.rs\n\n## TDD Anchor\nWrite all tests listed above. Many will already exist as unit tests in individual command beads — this bead consolidates them as proper integration tests using assert_cmd binary invocation.\nVERIFY: `cargo test --test '*'`\n\n## Dependency Context\nUses test fixtures and helpers from bd-lx6 (Create test fixtures and integration test helpers). Tests the commands implemented in all query/management beads.","status":"open","priority":2,"issue_type":"task","created_at":"2026-02-12T16:30:59.050732Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:58:13.670195Z","compaction_level":0,"original_size":0,"labels":["phase2","testing"],"dependencies":[{"issue_id":"bd-rex","depends_on_id":"bd-30a","type":"blocks","created_at":"2026-02-12T16:30:59.053106Z","created_by":"tayloreernisse"},{"issue_id":"bd-rex","depends_on_id":"bd-acf","type":"blocks","created_at":"2026-02-12T16:30:59.052620Z","created_by":"tayloreernisse"},{"issue_id":"bd-rex","depends_on_id":"bd-lx6","type":"blocks","created_at":"2026-02-12T16:34:06.369443Z","created_by":"tayloreernisse"},{"issue_id":"bd-rex","depends_on_id":"bd-p7g","type":"parent-child","created_at":"2026-02-12T16:30:59.051904Z","created_by":"tayloreernisse"}]}
{"id":"bd-x15","title":"Implement schemas command with list and show modes","description":"## Background\nThe schemas command lets users browse and inspect OpenAPI component schemas. Listing is index-backed (fast). Showing a specific schema loads raw.json via schema_ptr (same pattern as show command). Supports --name regex filter and --expand-refs with cycle detection.\n\n## Approach\nImplement src/cli/schemas.rs with SchemasArgs and execute():\n\n**SchemasArgs:** alias (Option<String>), name (Option<String> — regex filter, invalid → USAGE_ERROR), list (bool, default action), show (Option<String> — schema name), expand_refs (bool), max_depth (u32, default 3).\n\n**List mode (default):** Load index, filter schemas by --name regex, output names. Robot: data.schemas[] with name. Human: bulleted list with title.\n\n**Show mode (--show Name):** Find schema in index by exact name match. Load raw via schema_ptr. If --expand-refs, use the same ref expansion from show command (src/core/refs.rs). Output full schema JSON.\n\n## Acceptance Criteria\n- [ ] `schemas petstore` lists all schema names (sorted by name)\n- [ ] `schemas petstore --name \".*Pet.*\"` filters by regex\n- [ ] Invalid --name regex returns USAGE_ERROR\n- [ ] `schemas petstore --show Pet --robot` returns full Pet schema JSON\n- [ ] --expand-refs works on schema details\n- [ ] Schema not found returns clear error\n- [ ] List mode never loads raw.json\n- [ ] Show mode validates raw_hash\n\n## Edge Cases\n- **Empty schemas (spec with no components/schemas):** Return ok:true with data.schemas as empty array.\n- **Schema name with special characters:** Some schema names contain dots or hyphens (e.g., \"Pet.Response\"). Regex --name filter must handle these.\n- **--show with non-existent schema name:** Return clear error with suggestion listing available schema names.\n- **schema_ptr doesn't resolve in raw.json:** Return CacheIntegrity error (corrupted index). Should not happen if index was built correctly, but defend against it.\n\n## Files\n- MODIFY: src/cli/schemas.rs (SchemasArgs, execute)\n- MODIFY: src/output/robot.rs (add output_schemas_list, output_schemas_show)\n- MODIFY: src/output/human.rs (add output_schemas_list, output_schemas_show)\n\n## TDD Anchor\nRED: Write `test_schemas_list` — fetch petstore, run schemas --robot, assert data.schemas is array with correct count.\nGREEN: Implement list mode.\nVERIFY: `cargo test test_schemas_list`\n\n## Dependency Context\nUses ref expansion from bd-1dj (show command, src/core/refs.rs). Uses CacheManager from bd-3ea.","status":"open","priority":2,"issue_type":"task","created_at":"2026-02-12T16:28:05.337939Z","created_by":"tayloreernisse","updated_at":"2026-02-12T16:58:13.215435Z","compaction_level":0,"original_size":0,"labels":["phase2","query"],"dependencies":[{"issue_id":"bd-x15","depends_on_id":"bd-1dj","type":"blocks","created_at":"2026-02-12T16:28:05.340569Z","created_by":"tayloreernisse"},{"issue_id":"bd-x15","depends_on_id":"bd-3ea","type":"blocks","created_at":"2026-02-12T16:28:05.339868Z","created_by":"tayloreernisse"},{"issue_id":"bd-x15","depends_on_id":"bd-jek","type":"parent-child","created_at":"2026-02-12T16:28:05.339431Z","created_by":"tayloreernisse"}]}