diff --git a/.gitignore b/.gitignore index 4e5215c..58b07f4 100644 --- a/.gitignore +++ b/.gitignore @@ -68,4 +68,6 @@ Testing/ .cache/ # local evidence artifacts generated by standalone scripts -.sisyphus/ +.sisyphus/evidence/ +.sisyphus/evidence/* +.sisyphus/boulder.json \ No newline at end of file diff --git a/.sisyphus/notepads/major-refactor-cli11-cvmmap/learnings.md b/.sisyphus/notepads/major-refactor-cli11-cvmmap/learnings.md new file mode 100644 index 0000000..4eb5414 --- /dev/null +++ b/.sisyphus/notepads/major-refactor-cli11-cvmmap/learnings.md @@ -0,0 +1,8 @@ +- 2026-03-06: Updated `src/main_streamer.cpp` to remove explicit `has_help_flag`/`print_help` preflight checks and treat empty/`help` parse result as graceful exit. +- `parse_runtime_config` in `src/config/runtime_config.cpp` now returns `std::unexpected("")` for help path (via `app.exit(e) == 0`) and `std::unexpected("parse_error")` for parse failures. +- Kept `--help` behavior delegated to CLI11: `./build/cvmmap_streamer --help` prints CLI11-generated help and exits non-zero through parse path logging in current wrapper. +- Verified with `cmake --build build` and CLI smoke commands: `--help`, `--definitely-invalid`, and no-arg execution (shows runtime config then fails runtime stage as expected). + +- 2026-03-06: applied concrete edits: streamer now relies on parse_runtime_config returning "help"/"parse_error" and main handles those exits directly (help=>0, parse_error=>2). + +- 2026-03-06: completed remaining task checks: grep-verified no manual streamer help preflight in main, plus help parse/parse_error control flow validated with --help exit 0 and invalid flag exit 2; note appended. \ No newline at end of file diff --git a/.sisyphus/plans/major-refactor-cli11-cvmmap.md b/.sisyphus/plans/major-refactor-cli11-cvmmap.md new file mode 100644 index 0000000..047ee1c --- /dev/null +++ b/.sisyphus/plans/major-refactor-cli11-cvmmap.md @@ -0,0 +1,659 @@ +# Major Refactor: CLI11 Unification + Real cv-mmap Primary + Dummy Backend + +## TL;DR +> **Summary**: Remove manual/custom CLI/help paths, make CLI11 the single CLI surface, remove `cvmmap_sim`, and refactor ingestion to support `real` (default, cvmmap-client-cpp) and protocol-faithful `dummy` backends. +> **Deliverables**: +> - Unified CLI11 behavior across streamer + testers (no handcrafted help) +> - `cvmmap_sim` removed from build/scripts/docs +> - `FrameSource` input boundary with `real` and `dummy` backends +> - Required real cv-mmap integration profile using `/home/crosstyan/Code/cv-mmap` +> - Updated acceptance/fault/release gates + evidence paths +> **Effort**: XL +> **Parallel**: YES - 3 waves +> **Critical Path**: T1 → T2/T3/T4 → T5 → T6/T7 → T8 → T9/T10/T11 → T12 + +## Context +### Original Request +- Remove custom CLI flags/help and use CLI11. +- Major cleanup/refactor with `cvmmap-client-cpp` integration. +- Stop using `cvmmap_sim`; use real cv-mmap and add dummy/stub mode. +- Improve testing/integration with SRS/ZLMediaKit and real cv-mmap. + +### Interview Summary +- Legacy CLI policy: **immediate removal**. +- Integration gating: **required real cv-mmap profile**; SRS/ZLMediaKit remain optional/nightly-manual. +- Default input mode: **real**. +- Dummy backend shape: **protocol-faithful SHM+ZMQ**. +- `cvmmap_sim` binary: **remove**. +- Input target must support **CVMMAP URI** compatible with `/home/crosstyan/Code/cvmmap-python-client` conventions. +- Execution model: implementation must run from a dedicated **git worktree** (branch-isolated workspace), not the primary checkout. + +### Metis Review (gaps addressed) +- Guardrail added for preserving exit code semantics and evidence formats. +- Guardrail added for script updates in same refactor wave as `cvmmap_sim` removal. +- Guardrail added for protocol/fault knob parity in dummy backend. + +## Work Objectives +### Core Objective +Produce a decision-complete refactor plan that eliminates CLI ambiguity, replaces simulator-binary dependency with backend architecture, and hardens verification with required real cv-mmap integration. + +### Deliverables +- CLI11-only entrypoints for streamer and tester binaries. +- `FrameSource` boundary with `RealCvmmapSource` + `DummyShmZmqSource`. +- Streamer runtime option `--input-mode real|dummy` (default `real`). +- Removal of `cvmmap_sim` build target and sim-binary assumptions. +- Updated acceptance/fault/release scripts and docs. +- Required integration script/profile against `/home/crosstyan/Code/cv-mmap`. + +### Definition of Done (verifiable conditions with commands) +- Work executes from a dedicated worktree path created via `git worktree add` and branch-isolated from main workspace. +- `cmake -S . -B build && cmake --build build` succeeds. +- `test ! -x build/cvmmap_sim` returns success. +- `./build/cvmmap_streamer --help` shows CLI11-generated usage/options and no handcrafted help path. +- `./build/cvmmap_streamer --input-uri "cvmmap://default" ...` (or equivalent URI input flag) resolves and starts in real mode. +- `./scripts/acceptance_standalone.sh` returns 0 with `total=5 pass=5 fail=0 skip=0`. +- `./scripts/fault_suite.sh` returns 0 baseline. +- Required real profile script returns 0 when `/home/crosstyan/Code/cv-mmap` is available. + +### Must Have +- Dedicated worktree bootstrap and validation step before any refactor change. +- No `src/ipc/help.cpp` runtime dependency for CLI help. +- No manual argv scanning/parsing in tester binaries. +- Dummy backend reproduces SHM/ZMQ protocol semantics needed by acceptance/fault suites. +- Real mode uses `cvmmap-client-cpp` path by default. +- Streamer accepts CVMMAP plain names and URI form compatible with python client semantics (`cvmmap://[@][?namespace=]`). + +### Must NOT Have (guardrails, AI slop patterns, scope boundaries) +- No compatibility aliases for removed legacy CLI flags. +- No behavioral drift in accepted exit-code contracts used by scripts. +- No mandatory SRS/ZLMediaKit gate in PR critical path. +- No new feature scope (RTSP/WebRTC/audio/etc.). + +## Verification Strategy +> ZERO HUMAN INTERVENTION — all verification is agent-executed. +- Test decision: **tests-after** using existing shell suites + tester binaries. +- QA policy: Every task includes happy + edge/failure scenario. +- Evidence: `.sisyphus/evidence/task-{N}-{slug}.{ext}` + +## Execution Strategy +### Parallel Execution Waves +Wave 1: worktree bootstrap + CLI contract + parser unification + foundational input abstraction +Wave 2: real/dummy backend implementation + simulator removal plumbing +Wave 3: script/gate/docs/integration profile hardening + +### Dependency Matrix (full, all tasks) +- T0 blocks all implementation tasks. +- T1 blocks T2, T3, T4. +- T2/T3/T4 block T12 validation updates. +- T5 blocks T6 and T7. +- T6/T7 block T8/T9/T10. +- T8 blocks T9/T10/T11. +- T9/T10/T11 block T12. + +### Agent Dispatch Summary (wave → task count → categories) +- Wave 1 → 6 tasks → quick, unspecified-high +- Wave 2 → 5 tasks → deep, unspecified-high +- Wave 3 → 3 tasks → writing, unspecified-high + +## TODOs +> Implementation + Test = ONE task. Never separate. +> EVERY task MUST have: Agent Profile + Parallelization + QA Scenarios. + +- [ ] 0. Bootstrap dedicated git worktree and enforce branch isolation + + **What to do**: Create a dedicated git worktree for this refactor branch, validate branch isolation, and pin all subsequent build/test commands to that worktree path. + **Must NOT do**: Do not execute refactor work in primary checkout; do not reuse a dirty worktree. + + **Recommended Agent Profile**: + - Category: `quick` — Reason: procedural setup with strict safeguards. + - Skills: [`git-master`] — safe git/worktree operations and verification. + - Omitted: [`feature-research`] — no architecture decision here. + + **Parallelization**: Can Parallel: NO | Wave 1 | Blocks: [1,2,3,4,5,6,6A,7,8,9,10,11,12] | Blocked By: [] + + **References**: + - Pattern: `docs/caveats.md:49-61` — downstream path and cache-collision constraints. + - Pattern: `README.md:237-244` — sibling-path configure caveat. + - External: `https://git-scm.com/docs/git-worktree` — official worktree commands/constraints. + + **Acceptance Criteria**: + - [ ] `git worktree list --porcelain` shows exactly one new path for refactor branch. + - [ ] `git -C status --short` is clean before edits. + - [ ] Build/test commands in plan execution are run from ``. + + **QA Scenarios**: + ``` + Scenario: Happy path worktree bootstrap + Tool: Bash + Steps: Create worktree with new branch, verify list output and clean status. + Expected: New worktree present, branch checked out, clean tree. + Evidence: .sisyphus/evidence/task-0-worktree.txt + + Scenario: Failure path dirty/non-isolated workspace + Tool: Bash + Steps: Attempt run with dirty worktree or branch already checked out elsewhere. + Expected: Preflight stops execution with clear isolation error. + Evidence: .sisyphus/evidence/task-0-worktree-error.txt + ``` + + **Commit**: NO | Message: `n/a` | Files: `none (setup/preflight only)` + +- [ ] 1. CLI contract lock + help-path inventory + + **What to do**: Create an explicit CLI contract table (flags, defaults, required/optional, error codes) for `cvmmap_streamer`, `rtp_receiver_tester`, `rtmp_stub_tester`, and identify all handcrafted help/manual parser call sites to remove. + **Must NOT do**: Do not alter behavior yet; this task is contract freeze and inventory only. + + **Recommended Agent Profile**: + - Category: `unspecified-high` — Reason: cross-file contract extraction with regression risk. + - Skills: [`explore`] — discover all parser/help call sites and script expectations. + - Omitted: [`playwright`] — no browser surface. + + **Parallelization**: Can Parallel: NO | Wave 1 | Blocks: [2,3,4] | Blocked By: [] + + **References**: + - Pattern: `src/main_streamer.cpp:14-29` — manual help path entry. + - Pattern: `src/ipc/help.cpp:26-44` — handcrafted help + `has_help_flag`. + - Pattern: `src/testers/rtp_receiver_tester.cpp:189-232,291-299` — manual parse/help. + - Pattern: `src/testers/rtmp_stub_tester.cpp:267-303,1906-1912` — manual parse/help. + - Pattern: `src/config/runtime_config.cpp:262-447` — current CLI11 + normalization behavior. + + **Acceptance Criteria**: + - [ ] A machine-readable contract file/checklist exists in plan notes with every currently supported flag and expected exit behavior. + - [ ] All help/manual parse call sites are enumerated with exact paths and replacement targets. + + **QA Scenarios** (MANDATORY — task incomplete without these): + ``` + Scenario: Happy path inventory completeness + Tool: Bash + Steps: Run static searches for help/parser symbols and map all binaries to parser entrypoints. + Expected: No binary entrypoint remains unaccounted for in contract table. + Evidence: .sisyphus/evidence/task-1-cli-contract.txt + + Scenario: Edge path missing-coverage check + Tool: Bash + Steps: Search for "--help" and manual argv scanning patterns; compare to contract table. + Expected: Zero unmatched parser/help call sites. + Evidence: .sisyphus/evidence/task-1-cli-contract-error.txt + ``` + + **Commit**: YES | Message: `chore(cli): freeze cli contract and removal inventory` | Files: `docs/* (if used), internal planning evidence` + +- [ ] 2. Remove handcrafted help path and rely on CLI11-generated help + + **What to do**: Eliminate `has_help_flag` + handcrafted `print_help` call chain from runtime flow; entrypoints should delegate help/error output to CLI11 parse behavior. + **Must NOT do**: Do not reintroduce custom help text wrappers. + + **Recommended Agent Profile**: + - Category: `quick` — Reason: focused code-path cleanup with clear target. + - Skills: [`code-edit`] — precise edits across small set of files. + - Omitted: [`feature-research`] — design already fixed. + + **Parallelization**: Can Parallel: YES | Wave 1 | Blocks: [12] | Blocked By: [1] + + **References**: + - Pattern: `src/main_streamer.cpp:14-29` — remove pre-parse manual help checks. + - Pattern: `src/ipc/help.cpp` — remove usage in runtime path (delete or dead-code prune if fully unused). + - API/Type: `src/config/runtime_config.cpp:262-292` — canonical CLI11 parse error flow. + + **Acceptance Criteria**: + - [ ] `./build/cvmmap_streamer --help` exits 0 and prints CLI11 help. + - [ ] Manual help helper symbols are not referenced by production entrypoints. + + **QA Scenarios**: + ``` + Scenario: Happy path CLI11 help output + Tool: Bash + Steps: Build then run ./build/cvmmap_streamer --help + Expected: Exit code 0 and CLI11-style usage/options output. + Evidence: .sisyphus/evidence/task-2-cli11-help.txt + + Scenario: Failure path unknown option handling + Tool: Bash + Steps: Run ./build/cvmmap_streamer --definitely-invalid + Expected: Non-zero exit and parse error from CLI11 path (no handcrafted help banner). + Evidence: .sisyphus/evidence/task-2-cli11-help-error.txt + ``` + + **Commit**: YES | Message: `refactor(cli): remove handcrafted help path` | Files: `src/main_streamer.cpp, src/ipc/help.cpp, related headers` + +- [ ] 3. Migrate `rtp_receiver_tester` to CLI11-only parsing + + **What to do**: Replace manual `parseArgs` and bespoke help output with CLI11 parser, preserving current option names and exit code semantics. + **Must NOT do**: Do not change tester protocol validation behavior. + + **Recommended Agent Profile**: + - Category: `unspecified-high` — Reason: parser migration + behavior compatibility. + - Skills: [`code-edit`] — reliable targeted rewrite. + - Omitted: [`frontend-ui-ux`] — not applicable. + + **Parallelization**: Can Parallel: YES | Wave 1 | Blocks: [12] | Blocked By: [1] + + **References**: + - Pattern: `src/testers/rtp_receiver_tester.cpp:189-232` — manual parse path. + - Pattern: `src/testers/rtp_receiver_tester.cpp:291-299` — manual help pre-check. + - Pattern: `src/config/runtime_config.cpp` — preferred CLI11 style. + + **Acceptance Criteria**: + - [ ] Existing flags (`--port`, `--expect-pt`, `--sdp`, `--decode-hook`, `--packet-threshold`, `--timeout-ms`) still function. + - [ ] `--help` and invalid flag behavior are CLI11-native; scripts relying on return-code expectations still pass. + + **QA Scenarios**: + ``` + Scenario: Happy path tester invocation + Tool: Bash + Steps: Run ./build/rtp_receiver_tester --port 5004 --expect-pt 96 --packet-threshold 1 --timeout-ms 100 + Expected: CLI parsing succeeds and tester enters runtime path. + Evidence: .sisyphus/evidence/task-3-rtp-cli11.txt + + Scenario: Failure path invalid option + Tool: Bash + Steps: Run ./build/rtp_receiver_tester --not-a-real-flag + Expected: Exit code matches contract and parse fails cleanly. + Evidence: .sisyphus/evidence/task-3-rtp-cli11-error.txt + ``` + + **Commit**: YES | Message: `refactor(testers): migrate rtp_receiver_tester to cli11` | Files: `src/testers/rtp_receiver_tester.cpp` + +- [ ] 4. Migrate `rtmp_stub_tester` to CLI11-only parsing + + **What to do**: Replace manual `parse_args` and custom help with CLI11, preserving modes/threshold/timeouts and existing semantics. + **Must NOT do**: Do not alter protocol parser/state machine logic. + + **Recommended Agent Profile**: + - Category: `unspecified-high` — Reason: large file, parser section surgery. + - Skills: [`code-edit`] — scoped rewrite. + - Omitted: [`deep`] — not needed if confined to parser/help layer. + + **Parallelization**: Can Parallel: YES | Wave 1 | Blocks: [12] | Blocked By: [1] + + **References**: + - Pattern: `src/testers/rtmp_stub_tester.cpp:267-303` — custom usage + arg parsing helpers. + - Pattern: `src/testers/rtmp_stub_tester.cpp:1906-1912` — parser call in main. + - Test: `scripts/acceptance_standalone.sh:205-212` — expected invocation shape. + + **Acceptance Criteria**: + - [ ] Modes (`h264`, `h265-enhanced`, `h265-domestic`) parse exactly as before. + - [ ] Invalid arg handling/exit behavior matches contract table. + + **QA Scenarios**: + ``` + Scenario: Happy path mode parsing + Tool: Bash + Steps: Run ./build/rtmp_stub_tester --mode h264 --listen-host 127.0.0.1 --listen-port 1935 --video-threshold 1 --timeout-ms 100 + Expected: Parser accepts args and tester starts. + Evidence: .sisyphus/evidence/task-4-rtmp-cli11.txt + + Scenario: Failure path unsupported mode + Tool: Bash + Steps: Run ./build/rtmp_stub_tester --mode invalid-mode + Expected: Parse/config failure with non-zero exit per contract. + Evidence: .sisyphus/evidence/task-4-rtmp-cli11-error.txt + ``` + + **Commit**: YES | Message: `refactor(testers): migrate rtmp_stub_tester to cli11` | Files: `src/testers/rtmp_stub_tester.cpp` + +- [ ] 5. Introduce `FrameSource` boundary and input-mode contract + + **What to do**: Define common source interface for frame/event ingestion and wire streamer runtime to select backend via `--input-mode real|dummy` (default `real`). + **Must NOT do**: Do not couple backend-specific SHM/ZMQ details into pipeline/controller layers. + + **Recommended Agent Profile**: + - Category: `deep` — Reason: architectural seam with broad downstream impact. + - Skills: [`feature-research`] — ensure interface matches existing runtime contracts. + - Omitted: [`quick`] — insufficient for this scope. + + **Parallelization**: Can Parallel: NO | Wave 1 | Blocks: [6,7] | Blocked By: [1] + + **References**: + - Pattern: `src/core/ingest_runtime.cpp:155-386` — current direct SHM/ZMQ ingest flow. + - Pattern: `src/pipeline/pipeline_stub.cpp:692-1138` — duplicated ingestion/open logic. + - API/Type: `include/cvmmap_streamer/config/runtime_config.hpp` — extend with input mode enum. + + **Acceptance Criteria**: + - [ ] Streamer supports explicit `--input-mode` with default `real`. + - [ ] Runtime constructs backend through interface, not direct branch sprawl. + + **QA Scenarios**: + ``` + Scenario: Happy path default backend selection + Tool: Bash + Steps: Run streamer without --input-mode and inspect startup logs/config dump. + Expected: Backend resolves to real mode by default. + Evidence: .sisyphus/evidence/task-5-framesource.txt + + Scenario: Failure path invalid mode value + Tool: Bash + Steps: Run ./build/cvmmap_streamer --input-mode nonsense ... + Expected: Immediate config error with non-zero exit. + Evidence: .sisyphus/evidence/task-5-framesource-error.txt + ``` + + **Commit**: YES | Message: `refactor(input): add framesource interface and input-mode contract` | Files: `include/src config/core/pipeline inputs` + +- [ ] 6. Implement `RealCvmmapSource` using `cvmmap-client-cpp` + + **What to do**: Integrate `lib/cvmmap-client-cpp` as the real backend implementation behind `FrameSource`; map callbacks/events to existing ingest semantics. + **Must NOT do**: Do not bypass `FrameSource` or duplicate direct SHM+ZMQ open logic in pipeline/ingest loops. + + **Recommended Agent Profile**: + - Category: `deep` — Reason: third-party integration + callback/contract adaptation. + - Skills: [`feature-research`] — align API/metadata contract and lifecycle. + - Omitted: [`playwright`] — irrelevant. + + **Parallelization**: Can Parallel: YES | Wave 2 | Blocks: [8,12] | Blocked By: [5] + + **References**: + - API/Type: `lib/cvmmap-client-cpp/include/app/cvmmap/cvmmap_client.hpp:274-309` — client API/callbacks. + - Pattern: `lib/cvmmap-client-cpp/app_cvmmap_client.cpp` — polling lifecycle and event flow. + - Pattern: `src/core/ingest_runtime.cpp` — target behavior to preserve. + + **Acceptance Criteria**: + - [ ] Real backend successfully receives frames/events and feeds existing pipeline path. + - [ ] Existing coherent-frame semantics and reset handling remain valid under real backend. + - [ ] Real backend path accepts CVMMAP URI inputs and resolves endpoints consistently with python client behavior. + + **QA Scenarios**: + ``` + Scenario: Happy path real backend ingest + Tool: Bash + Steps: Start real cv-mmap server profile, then run streamer in default mode. + Expected: Frames processed and published without backend init failures. + Evidence: .sisyphus/evidence/task-6-real-backend.txt + + Scenario: Failure path server unavailable + Tool: Bash + Steps: Run streamer in real mode with unavailable cv-mmap endpoint/root. + Expected: Deterministic startup failure with actionable error and non-zero exit. + Evidence: .sisyphus/evidence/task-6-real-backend-error.txt + ``` + + **Commit**: YES | Message: `feat(input): add real cvmmap source via client-cpp` | Files: `src/input/*, CMakeLists.txt, core/pipeline integration` + +- [ ] 6A. Enforce CVMMAP URI compatibility contract; refactor `cvmmap-client-cpp` if needed + + **What to do**: Validate C++ client URI parsing/resolution against `/home/crosstyan/Code/cvmmap-python-client` contract; if any divergence exists, refactor `lib/cvmmap-client-cpp` to match and expose the aligned URI path to streamer config. + **Must NOT do**: Do not invent a streamer-only URI grammar that diverges from python client contract. + + **Recommended Agent Profile**: + - Category: `deep` — Reason: cross-repo contract parity and potential library-level refactor. + - Skills: [`feature-research`] — compare URI grammar, validation, derived endpoint rules. + - Omitted: [`quick`] — cross-library behavior risk. + + **Parallelization**: Can Parallel: NO | Wave 2 | Blocks: [8,11,12] | Blocked By: [6] + + **References**: + - External: `/home/crosstyan/Code/cvmmap-python-client/src/cvmmap/__init__.py` — authoritative URI resolver behavior. + - External: `/home/crosstyan/Code/cvmmap-python-client/README.md` — documented URI scheme and examples. + - Pattern: `lib/cvmmap-client-cpp/app_cvmmap_client.cpp:93-190,593-597` — current C++ URI resolution and constructor path. + - API/Type: `lib/cvmmap-client-cpp/include/app/cvmmap/cvmmap_client.hpp:285` — constructor contract surface. + + **Acceptance Criteria**: + - [ ] Plain instance and URI forms produce the same derived base/endpoint semantics as python client for shared test vectors. + - [ ] Unsupported query keys, invalid prefixes, invalid namespace/instance tokens fail with deterministic validation errors. + - [ ] Streamer runtime can consume URI input and pass it cleanly into C++ client path. + + **QA Scenarios**: + ``` + Scenario: Happy path URI parity vectors + Tool: Bash + Steps: Run parity checks for vectors like "cvmmap://default" and "cvmmap://camera0@/run/cvmmap?namespace=zed" through C++ client path. + Expected: Derived names/endpoints match python client contract exactly. + Evidence: .sisyphus/evidence/task-6a-uri-parity.txt + + Scenario: Failure path invalid URI validation + Tool: Bash + Steps: Pass invalid forms (bad query key, traversal prefix, invalid token chars). + Expected: Deterministic validation failure and non-zero exit/error propagation. + Evidence: .sisyphus/evidence/task-6a-uri-parity-error.txt + ``` + + **Commit**: YES | Message: `refactor(client): align cvmmap-client-cpp uri contract with python client` | Files: `lib/cvmmap-client-cpp/*, streamer runtime config/plumbing` + +- [ ] 7. Implement protocol-faithful `DummyShmZmqSource` backend (in-process) + + **What to do**: Add in-process dummy backend that reproduces SHM metadata + ZMQ sync/status semantics and fault knobs used by matrix/fault suites. + **Must NOT do**: Do not create a replacement standalone simulator binary. + + **Recommended Agent Profile**: + - Category: `unspecified-high` — Reason: protocol emulation with timing/fault controls. + - Skills: [`feature-research`] — preserve wire-level behavior. + - Omitted: [`quick`] — too risky for protocol fidelity. + + **Parallelization**: Can Parallel: YES | Wave 2 | Blocks: [8,12] | Blocked By: [5] + + **References**: + - Pattern: `src/main_sim.cpp` — behavior source to port into backend, not binary. + - Pattern: `src/sim/wire.cpp` and `include/cvmmap_streamer/sim/wire.hpp` — protocol writers/serialization. + - Test: `scripts/fault_suite.sh:171-239` — required scenario knobs and dynamics. + + **Acceptance Criteria**: + - [ ] Dummy backend supports equivalent frame generation, reset emission, and timing knobs required by existing suites. + - [ ] Standalone suite can run using streamer+testers without `build/cvmmap_sim`. + + **QA Scenarios**: + ``` + Scenario: Happy path dummy backend matrix row + Tool: Bash + Steps: Run one acceptance row configured for dummy backend. + Expected: Streamer/tester pass with expected packet/video threshold. + Evidence: .sisyphus/evidence/task-7-dummy-backend.txt + + Scenario: Failure path dummy reset storm edge + Tool: Bash + Steps: Configure high reset frequency and run fault reset scenario. + Expected: Fault suite captures expected behavior and exits per baseline criteria. + Evidence: .sisyphus/evidence/task-7-dummy-backend-error.txt + ``` + + **Commit**: YES | Message: `feat(input): add protocol-faithful dummy shm+zmq backend` | Files: `src/input/*, migrated sim logic files` + +- [ ] 8. Remove `cvmmap_sim` target and all sim-binary dependencies + + **What to do**: Delete CMake target and obsolete simulator entrypoint files, and replace all build/script references with backend-mode runtime execution. + **Must NOT do**: Do not leave stale references in scripts/docs/README quickstart. + + **Recommended Agent Profile**: + - Category: `quick` — Reason: deterministic deletion/plumbing updates. + - Skills: [`code-edit`] — direct target/reference cleanup. + - Omitted: [`deep`] — architecture decisions already made. + + **Parallelization**: Can Parallel: NO | Wave 2 | Blocks: [9,10,11,12] | Blocked By: [6,6A,7] + + **References**: + - Pattern: `CMakeLists.txt:101-105` — remove sim target block. + - Pattern: `scripts/acceptance_standalone.sh:273` and `scripts/fault_suite.sh:303` — binary preflight assumptions. + - Pattern: `README.md` quickstart sections mentioning `cvmmap_sim`. + + **Acceptance Criteria**: + - [ ] `build/cvmmap_sim` is no longer generated. + - [ ] No script/doc references require `cvmmap_sim` as executable. + + **QA Scenarios**: + ``` + Scenario: Happy path build artifact validation + Tool: Bash + Steps: Configure+build then assert build/cvmmap_sim absent. + Expected: Assertion passes and build completes. + Evidence: .sisyphus/evidence/task-8-remove-sim.txt + + Scenario: Failure path stale-reference scan + Tool: Bash + Steps: Search repo scripts/docs for remaining executable references to cvmmap_sim. + Expected: Zero hard dependency references remain. + Evidence: .sisyphus/evidence/task-8-remove-sim-error.txt + ``` + + **Commit**: YES | Message: `refactor(build): remove cvmmap_sim target and references` | Files: `CMakeLists.txt, src/main_sim.cpp, src/sim/*, scripts/docs refs` + +- [ ] 9. Rewrite acceptance suite to backend-mode runner (no simulator process) + + **What to do**: Update `scripts/acceptance_standalone.sh` so each row drives streamer in `--input-mode dummy` and removes sim process lifecycle/return-code handling. + **Must NOT do**: Do not change matrix semantics (5 rows/protocol+codec coverage) or summary format contract. + + **Recommended Agent Profile**: + - Category: `unspecified-high` — Reason: gate-critical script surgery with evidence contract. + - Skills: [`code-edit`] — safe structured shell changes. + - Omitted: [`feature-research`] — behavior already specified. + + **Parallelization**: Can Parallel: YES | Wave 3 | Blocks: [12] | Blocked By: [8] + + **References**: + - Pattern: `scripts/acceptance_standalone.sh:129-139,224-238` — current sim process usage. + - Pattern: `scripts/acceptance_summary_helper.py` — output schema to preserve. + - Test: `README.md` mandatory acceptance expected summary. + + **Acceptance Criteria**: + - [ ] Script returns 0 with `total=5 pass=5 fail=0 skip=0` on passing runs. + - [ ] Manifest/summary fields remain compatible with helper parser expectations. + + **QA Scenarios**: + ``` + Scenario: Happy path full acceptance run + Tool: Bash + Steps: Run ./scripts/acceptance_standalone.sh after build. + Expected: Exit 0 and expected pass/fail/skip totals. + Evidence: .sisyphus/evidence/task-9-acceptance.txt + + Scenario: Failure path induced row failure + Tool: Bash + Steps: Trigger one row with invalid endpoint/arg via controlled injection and run suite. + Expected: Row marked FAIL, summary reflects non-zero fail count, script exits non-zero. + Evidence: .sisyphus/evidence/task-9-acceptance-error.txt + ``` + + **Commit**: YES | Message: `test(acceptance): migrate standalone matrix to dummy backend mode` | Files: `scripts/acceptance_standalone.sh` + +- [ ] 10. Rewrite fault suite to backend-mode scenarios (no simulator process) + + **What to do**: Update `scripts/fault_suite.sh` to drive fault knobs through dummy backend config in streamer path and remove sim process management. + **Must NOT do**: Do not relax baseline success criteria (`3/3 pass`) or degraded-mode semantics. + + **Recommended Agent Profile**: + - Category: `unspecified-high` — Reason: fault semantics are fragile and gate-critical. + - Skills: [`code-edit`] — structured shell and threshold contract preservation. + - Omitted: [`quick`] — risk too high. + + **Parallelization**: Can Parallel: YES | Wave 3 | Blocks: [12] | Blocked By: [8] + + **References**: + - Pattern: `scripts/fault_suite.sh:208-220,258-271,301-330` — current sim-driven lifecycle. + - Pattern: `scripts/fault_summary_helper.py` — threshold expectations and summary schema. + + **Acceptance Criteria**: + - [ ] Baseline mode still returns 0 only when all three scenarios pass. + - [ ] Degraded mode behavior preserved per existing semantics. + + **QA Scenarios**: + ``` + Scenario: Happy path baseline fault suite + Tool: Bash + Steps: Run ./scripts/fault_suite.sh + Expected: Exit 0 with total=3 pass=3 fail=0. + Evidence: .sisyphus/evidence/task-10-fault-suite.txt + + Scenario: Edge path degraded thresholds + Tool: Bash + Steps: Run ./scripts/fault_suite.sh --degraded + Expected: Behavior matches existing degraded contract and evidence records threshold outcomes. + Evidence: .sisyphus/evidence/task-10-fault-suite-error.txt + ``` + + **Commit**: YES | Message: `test(fault): migrate fault suite to dummy backend scenarios` | Files: `scripts/fault_suite.sh` + +- [ ] 11. Add required real cv-mmap integration profile and gate wiring + + **What to do**: Add required integration script/profile using `/home/crosstyan/Code/cv-mmap`, with explicit preflight checks and deterministic fail messages when dependency is unavailable/misconfigured. + **Must NOT do**: Do not fold SRS/ZLMediaKit into required PR gate. + + **Recommended Agent Profile**: + - Category: `unspecified-high` — Reason: external dependency contract and deterministic gating. + - Skills: [`feature-research`] — align with real server startup/runtime assumptions. + - Omitted: [`playwright`] — not needed. + + **Parallelization**: Can Parallel: YES | Wave 3 | Blocks: [12] | Blocked By: [8] + + **References**: + - External: `/home/crosstyan/Code/cv-mmap` — required integration root. + - Pattern: `scripts/release_gate.sh:101-117` — existing gate sequencing. + - Docs: `docs/smoke/srs.md`, `docs/smoke/zlm.md` — keep optional-only placement. + + **Acceptance Criteria**: + - [ ] New integration profile script exits 0 when real cv-mmap profile is healthy. + - [ ] Fails with clear actionable message if profile cannot be started or connected. + + **QA Scenarios**: + ``` + Scenario: Happy path real integration profile + Tool: Bash + Steps: Run integration script with --cvmmap-root /home/crosstyan/Code/cv-mmap and valid runtime options. + Expected: End-to-end profile passes and emits evidence bundle. + Evidence: .sisyphus/evidence/task-11-real-profile.txt + + Scenario: Failure path missing cv-mmap root + Tool: Bash + Steps: Run integration script with non-existent --cvmmap-root. + Expected: Deterministic preflight failure with non-zero exit and explicit missing-path reason. + Evidence: .sisyphus/evidence/task-11-real-profile-error.txt + ``` + + **Commit**: YES | Message: `test(integration): add required real cv-mmap profile` | Files: `scripts/*real-profile*.sh, docs/smoke/*.md, release gate wiring` + +- [ ] 12. Final gate/docs alignment and regression sweep + + **What to do**: Update `release_gate.sh`, README, compat/caveats docs, and any evidence expectations to reflect no simulator binary, real default mode, dummy backend usage, and required real profile. + **Must NOT do**: Do not alter scope constraints (no rtsp/webrtc/audio) or evidence key names unless helper tooling is updated in same task. + + **Recommended Agent Profile**: + - Category: `writing` — Reason: high-accuracy docs+gate alignment. + - Skills: [`code-edit`] — script/doc synchronized edits. + - Omitted: [`frontend-ui-ux`] — irrelevant. + + **Parallelization**: Can Parallel: NO | Wave 3 | Blocks: [] | Blocked By: [2,3,4,6,7,8,9,10,11] + + **References**: + - Pattern: `scripts/release_gate.sh:119-141` — required evidence bundle checks. + - Pattern: `README.md` quickstart/manual test sections currently showing `cvmmap_sim`. + - Docs: `docs/compat_matrix.md`, `docs/caveats.md` — keep optional checks separation and scope text. + + **Acceptance Criteria**: + - [ ] Release gate passes with updated mandatory checks and evidence expectations. + - [ ] Documentation examples no longer require `cvmmap_sim` and accurately describe `--input-mode` behavior. + - [ ] No stale references to removed simulator binary remain. + + **QA Scenarios**: + ``` + Scenario: Happy path full release gate + Tool: Bash + Steps: Run ./scripts/release_gate.sh + Expected: PASS with updated gate summary and evidence bundle. + Evidence: .sisyphus/evidence/task-12-release-gate.txt + + Scenario: Failure path evidence gate injection + Tool: Bash + Steps: Run ./scripts/release_gate.sh --inject-failure evidence + Expected: Deterministic FAIL at evidence gate with clear failing_gates output. + Evidence: .sisyphus/evidence/task-12-release-gate-error.txt + ``` + + **Commit**: YES | Message: `docs(gate): align release gate and docs with real/dummy backend model` | Files: `scripts/release_gate.sh, README.md, docs/*.md, helper references` + +## Final Verification Wave (4 parallel agents, ALL must APPROVE) +- [ ] F1. Plan Compliance Audit — oracle +- [ ] F2. Code Quality Review — unspecified-high +- [ ] F3. Real Manual QA — unspecified-high (+ playwright if UI) +- [ ] F4. Scope Fidelity Check — deep + +## Commit Strategy +- Commit in atomic slices by wave; no cross-wave mixed commits. +- Suggested pattern: + - `refactor(cli): remove manual help paths and unify CLI11` + - `refactor(input): add real/dummy FrameSource and remove cvmmap_sim target` + - `test(integration): update acceptance/fault/release gates and real cv-mmap profile` + - `docs(runtime): align README/compat/caveats with new backend model` + +## Success Criteria +- All mandatory gates pass with no simulator binary. +- Real cv-mmap integration profile is required and passing when local dependency exists. +- Dummy backend fully replaces simulator role for standalone matrix/fault coverage. +- CLI experience is deterministic, CLI11-native, and free from handcrafted help output. +- CVMMAP URI behavior in streamer/C++ client is contract-compatible with python client semantics. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d9194e9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,25 @@ +# Repository Guidelines + +## Project Structure & Module Organization +Core code lives in `src/` and public headers in `include/cvmmap_streamer/`. The main runtime is `src/main_streamer.cpp`; shared logic is split by concern under `src/config`, `src/core`, `src/ipc`, `src/pipeline`, `src/protocol`, and `src/metrics`. Test utilities are standalone binaries in `src/testers/`. Automation and release gates live in `scripts/`, while operator notes and smoke-test profiles live in `docs/`. Third-party dependencies are vendored in `lib/` and should only be changed deliberately. + +## Build, Test, and Development Commands +Configure and build with: + +```bash +cmake -B build -S . +cmake --build build +``` + +This produces `build/cvmmap_streamer`, `build/rtp_receiver_tester`, `build/rtmp_stub_tester`, and `build/ipc_snapshot_tester`. + +Use `cmake --fresh -B build -S .` if CMake caches stale dependency paths. Run the mandatory acceptance matrix with `./scripts/acceptance_standalone.sh` and the baseline fault suite with `./scripts/fault_suite.sh`. For targeted manual checks, run the built testers directly against `build/cvmmap_streamer`. + +## Coding Style & Naming Conventions +This project targets C++23. Follow the existing style: tabs for indentation, braces on the same line, `snake_case` for functions and variables, `PascalCase` for types and enums, and lowercase directory names by subsystem. Keep headers under `include/cvmmap_streamer/...` aligned with their implementation paths where practical. No formatter or linter config is checked in, so match the surrounding file exactly before submitting changes. + +## Testing Guidelines +There is no top-level unit-test framework in this repo; verification is primarily binary- and script-driven. Add behavior checks through `src/testers/` and extend the shell suites in `scripts/` when introducing new protocol or fault scenarios. Prefer deterministic inputs such as the dummy backend (`--input-mode dummy`) and keep labels short. Review generated evidence under `.sisyphus/evidence/` when validating failures. + +## Commit & Pull Request Guidelines +Recent history uses Conventional Commit prefixes such as `feat(...)`, `fix(...)`, `refactor(...)`, `test(...)`, `build(...)`, and `chore(...)`. Continue that pattern and keep scopes specific, for example `refactor(protocol): simplify wire codec setup`. PRs should explain the runtime impact, list the commands you ran, and attach relevant logs or screenshots when output behavior changes. Link any issue or task ID when one exists.