xiaobaifupan/app/tools/README.md

Candidate tools

Run these commands from webapp/app/. The tools are separated by responsibility so a maintenance command cannot be mistaken for a historical migration rewrite.

Normal maintenance

• python tools/verify_baseline.py: candidate unit tests, registry checks, every frontend JavaScript syntax check, Git whitespace check, and read-only SQLite integrity check.
• python tools/verify_baseline.py --e2e: the same checks plus Playwright. The verifier owns the local static-server lifecycle so the command exits cleanly on Windows.
• python tools/build_api_registry.py [--check]: generate or verify config/api.config.json from backend/application.py.
• python tools/build_architecture_inventory.py [--check]: generate or verify config/architecture-inventory.json from the candidate source tree.

Inside the canonical webapp/app/ checkout, verify_baseline.py runs the full preservation suite against the retained original baseline and enforces git diff --check. In a standalone app/ export where that baseline and Git checkout do not exist, the same command runs all candidate-owned tests, skips only test_preservation_* comparison modules, and reports the Git check as skipped. Product, registry, JavaScript, database, and optional Playwright checks remain active in both modes.

Acceptance and differential checks

• run_preservation_runtime.py: start an isolated original or candidate runtime with an explicitly selected data directory and port.
• compare_preservation_apis.py: compare authenticated responses from two isolated runtimes.
• compare_preservation_databases.py: compare schema and selected table contents from two SQLite copies.

These tools require explicit paths and do not select the production database automatically.

Migration-only tools

• build_preservation_manifest.py: builds an exact-copy manifest for a specified source and target. --output is mandatory so committed historical evidence is not overwritten.
• move_class_methods.py: mechanically moves named class methods between explicit files.
• split_frontend_runtime.py: reproduces the one-time Slice 10 split. It refuses to write unless --apply is supplied and is not a normal maintenance command.

The migration-only tools are retained for audit and reproducibility. They are not part of application startup, normal testing, or future feature development.