Review: WebHarbor reset and smoke verification script (#47, original by @Lxr-max)

[jackjin1997]

Reviewer-owned continuation of #47 by @Lxr-max. The contributor's original commit
777fcdf remains the first feature commit; later commits contain the review fixes.

Result

This adds scripts/check_reset_smoke.py, a CLI that resolves the live site registry,
checks the control plane, exercises per-site or global reset, checks homepages, and can
compare runtime/seed DBs from an explicit Docker container or host deployment root.
Machine-readable output names the DB source used for every site.

The review originally corrected several correctness gaps in #47:

• DB parity no longer compares the repository checkout while implying it checked the
  running deployment. --docker-container reads /opt/WebSyn/<site> and --db-root
  reads an explicit host tree; without either flag parity is SKIP with source none.
• Registry drift, missing registry files, unparseable SITES, and BASE_PORT mismatch
  are structured findings rather than tracebacks.
• A parity result is only attributed to a successful reset, --strict escalates real
  warnings without failing the expected no-source case, and --reset-all failures are
  reported once with their HTTP detail.

Post-audit quality fixes

The branch is now based on current main (5d7a4e8) and closes the final quality audit:

• Docker parity is SKIP, and the container hasher is not called, after either a
  per-site or reset-all failure.
• malformed Python SITES literals and non-string entries remain valid --json
  failures with zero network checks.
• redirect loops fail homepage smoke while a redirect that reaches a page passes.
• local DB permission and file-type errors become structured DB failures and identify
  the exact unreadable path.
• local and Docker sources share one DB-pair selection rule, including the unique
  shared-filename case.
• the reviewer history was rebuilt with Conventional Commit messages and no
  Co-Authored-By trailers; the original contributor commit remains unchanged.

Verification

• python3 -m pytest scripts/test_check_reset_smoke.py -q — 26 passed, 7 subtests passed.
• python3 scripts/check_site_registry.py — 31 sites consistent across both
  registries, Dockerfile ports and task files; ports 40000–40030, bh_photo at 40030.
• Python compilation and git diff --check pass.
• The original audit's loopback/file probes now report the expected structured results.
• A fresh isolated Claude Opus 5 review recomputed all 57 packet hashes and returned
  14/14 PASS for the changed branches and direct regressions. A first pass had
  marked one scenario inconclusive because its packet omitted raw per-file md5sum
  output; the evidence was completed and re-reviewed in a new session.
• Earlier full review evidence includes 20 scenarios against a real two-site control
  plane and live Docker filesystem. The successful reset/hash path is unchanged.

Limits

The current post-audit run did not start or build a container because the host had
7.9 GiB free, below the review workflow's 10 GiB hard floor even for image reuse. The
changed Docker branches were exercised through the CLI's injected container-hasher
boundary and captured docker exec output; no unrelated Docker data was deleted.
The live environment evidence covers two representative sites, while registry parsing
and unit coverage use all current 31 sites. Podman and remote Docker daemons remain
untested. A --db-root verdict describes the root supplied by the operator.

[jackjin1997]

Update — an independent review of the frozen runs found a real defect in my own first pass, fixed in fda2266.

The SKIP-with-source-none path was only reached when the checkout had no sites/<site>/instance directory. Any checkout that happened to carry one — anyone who has run a site on the host, or extracted assets and booted locally — silently fell back to comparing the checkout and issued a parity verdict labelled local:, contradicting the documented behaviour that a flagless run reports SKIP rather than comparing this checkout's files. Two consequences, both reproduced against the live control plane:

• a stale local DB failed a healthy deployment: reset=PASS, home=PASS, the deployment's own instance and instance_seed byte-identical, yet exit 1 on "local runtime DB differs from local seed DB";
• a flagless --json run reported md5_status: PASS for every site without ever reading /opt/WebSyn — the same false confidence the first commit set out to remove, just narrowed.

A flagless run now always reports SKIP with source none. Under --db-root, a root that does not hold the site's DBs is an error (the requested check cannot run), while an undecidable DB pair stays a warning so --strict still has a genuine warning to escalate. --reset-all failures now carry the HTTP detail instead of discarding it.

Two regression tests were written first and confirmed failing before the fix; the tests that exercise the local source now pass --db-root explicitly. 20 pass. The full scenario set was re-executed against the same control plane, plus a scenario covering exactly the case that was wrong (healthy deployment, checkout carrying matching instance/ directories, no flag → SKIP [none]).

Still draft: the re-frozen runs are going back for an independent second pass before this is marked ready.

[jackjin1997]

Quality audit follow-up is complete at d660caf (rebased/merged onto current
main 5d7a4e8). The review branch was force-updated because I rebuilt the reviewer
commits to remove forbidden Co-Authored-By trailers; the contributor's original
777fcdf commit is still preserved unchanged.

Closed all five audit findings:

• no Docker hashing or parity verdict after failed per-site/reset-all reset;
• malformed/non-string Python SITES stays structured in --json mode;
• redirect loops fail while redirects that reach a page pass;
• local DB read errors become structured failures with the exact path;
• local and Docker DB inventories use the same pairing rule.

Verification: 26 tests + 7 subtests pass; all current 31 registry entries and ports
40000–40030 agree; compilation and diff checks pass. A fresh isolated Claude Opus 5
review recomputed all 57 evidence hashes and returned 14/14 PASS for the affected
matrix. The first blind packet's sole inconclusive was an evidence omission (raw
per-file md5sum output); it was retained, corrected, and re-reviewed in a new session.

Current Docker execution was intentionally not started because only 7.9 GiB was free,
below the review workflow's 10 GiB reuse floor. Docker-facing changed branches were
covered through the injected hasher/command boundary and captured per-file output;
the earlier live-container successful-path evidence remains applicable. No merge was
performed.