Add guardrails and smoke harness for MUIO v5.5 pull (#389)

[sanvishukla]

Linked issue

• Closes [Task] Add guardrails and a smoke harness for the MUIO v5.5 pull #389
• Related [Task] Absorb selected MUIO v5.5 changes on origin/main #388

Existing related work reviewed

• Issues/PRs reviewed: [Task] Absorb selected MUIO v5.5 changes on origin/main #388, [Task] Implement Foundational CI/CD Infrastructure #375, **Proposal:** This issue defines the contribution-intake framework we intend to adopt to reduce PR firehose and improve quality/signal. #255

Overlap assessment

• Classification:Feature / Stability / Guardrails
• Overlapping items: None (Added new tests/ and scripts/ files; no core code modification).
• Why this is not duplicate/superseded: This PR specifically satisfies the requirement for the MUIO v5.5 port as defined in the project roadmap.

Why this PR should proceed

This PR establishes the mandatory repeatable check layer required before any upstream v5.5 changes can be safely absorbed. It prevents "blind merges" by providing an automated way to verify environment health, solver availability, and basic API stability.

Summary

• What changed:

  • Added scripts/verify_base.sh: A composite verification command (syntax, environment, solvers, git-state).
  • Added tests/smoke_test.py: A unittest-based harness for app-load and route discovery.
  • Added scripts/smoke.sh and scripts/smoke.bat for quick test execution.

• Why: To provide a "Green/Red" landing gate for the upcoming MUIO v5.5 sync.

Validation

• Tests added/updated (or not applicable)
• Validation steps documented
• Evidence attached (logs/screenshots/output as relevant)

1. Created tests/smoke_test.py, a standalone health-check suite using the Python standard unittest library.
2. Implemented 5 core tests that verify the application can boot, dependencies are correctly mapped, and critical backend routes are responsive.
3. Verified the harness is non-destructive and safe for "read-only" environments (no root-write assumptions).

Tests:

=== Step 1: Environment & Solvers ===
  [PASS] Python venv and solvers (GLPK/CBC) are ready.

=== Step 2: Python Syntax Check ===
  [PASS] app.py is syntactically valid.

=== Step 3: API & Route Smoke Tests ===
  [PASS] Smoke tests passed (API boot and core routes).

=== Step 4: Git Merge Integrity ===
  [PASS] No unresolved git merge/rebase state found.

=== Step 5: Conflict Marker Scan ===
  [PASS] No conflict markers found in key backend/frontend folders.

Verification Complete: MUIOGO is healthy and ready for upstream pull.

To test: run ./scripts/verify_base.sh in terminal

Documentation

• Docs updated in this PR (or not applicable)
• Any setup/workflow changes reflected in repo docs

Scope check

• No unrelated refactors
• Implemented from a feature branch
• Change is deliverable without upstream OSeMOSYS/MUIO dependency
• Base repo/branch is EAPD-DRB/MUIOGO:main (not upstream)

[brightyorcerf]

Minimalism is a great goal for a smoke harness, but moving the gate logic to Bash/Batch wrappers creates a parallel maintenance burden. As we continue to institutionalize Pathlib and OS-agnosticism, a Python-native gate is significantly more sustainable.

Two specific architectural concerns with this implementation in my opinion:

• Diagnostic Blindness: Wrapping core imports in try/except self.fail() swallows the Python traceback. This makes debugging 'import failures' significantly harder for contributors, as it masks the underlying cause (syntax errors, dependency drift, etc.).

• Bytecode Leakage: To truly satisfy the 'No Writable Root' constraint, we must explicitly suppress pycache generation (via sys.dont_write_bytecode). Without this, the gate will still trigger OSError in strictly read-only environments.

I’d suggest we stick to a Python-centric approach (like the intent of #402) but shore up the path logic and environment isolation to meet the stability standards we're targeting for v5.5.