docs-live-command-verification
Root cause: the fork inherited upstream LocalStack's README, which documents a localstack CLI daemon (localstack start -d, localstack stop). The fork's real entry point is the in-memory runtime python3 -m localstack.runtime.main (exposed via make start), and [project.scripts] only ships localstack-supervisor. A dev following the README verbatim runs a binary that was never installed → localstack: No such file or directory (exit 127).
Fix has three layers:
```markdown
Built a faithful minimal fork in `/tmp/ls-fork` (package + Makefile + venv + broken README/pyproject), then ran a full red→green cycle: **Reproduction (broken state, exact error):** ``` $ .venv/bin/localstack start -d /bin/bash: line 1: .venv/bin/localstack: No such file or directory exit=127 # .venv/bin contained ONLY: localstack-supervisor ``` **Red:** verification suite against broken state → `FAILED (failures=2)` — `test_localstack_binary_exists_and_runs` (binary missing) and `test_no_args_prints_usage` (127 ≠ 2). Suite catches the bug. **Green (after fix):** `make test` → `Ran 8 tests ... OK` (exit 0), and the documented command works verbatim: `localstack start -d` → `READY`, exit 0, with the `-d` compat warning on stderr. **Edge cases tested (8 tests + manual):** | Case | Result | |---|---| | `localstack start -d` (upstream-documented) | exit 0, READY, `-d` warning | | `make start` / `make install` from clean venv | exit 0, both console scripts created | | `python3 -m localstack.runtime.main start` (Windows/no-make path) | exit 0, READY | | `localstack` no args | exit 2 + usage (argparse contract) | | `localstack bogus` (unknown subcommand) | nonzero exit | | `localstack-supervisor` (pre-existing script) | preserved, still works | | Module entrypoint without subcommand | exit 2 + usage (documented) | | `localstack stop` | removed from README; suite asserts it's not a runnable doc command | | `.venv/bin` snapshot guard | fails if stray binaries sneak in | | README fenced-command resolution | `make`, `nohup`, `python3` (system bins) + make targets + console scripts |
{"model": "deepseek-v4-flash", "problem_class": "docs-live-command-verification", "result": "passed", "tests": 8}