meshcore-bot-firmware/.forge/steps/step-2-plan.md

Step 2 Execution Plan: Add representative build and size-report tooling

Goal

Create local and CI tooling that applies the MeshCore patch queue, builds the four representative companion environments, captures per-environment logs/artifacts, and emits a deterministic size JSON summary.

Current Code Observations

• vendor/MeshCore/build.sh provides build-firmware <target> and copies artifacts to its own out/ directory after each build.
• vendor/MeshCore/build.sh removes vendor/MeshCore/out at startup, so wrapper tooling must copy artifacts after each environment build before starting the next one.
• vendor/MeshCore/build.sh requires FIRMWARE_VERSION in the environment and uses the current MeshCore git SHA in artifact filenames.
• Upstream CI installs Python 3.11 and PlatformIO with pip install --upgrade platformio, then runs build.sh build-companion-firmwares.
• Representative envs exist in variants/heltec_v3/platformio.ini and variants/rak4631/platformio.ini; RAK4631 companion envs set board_upload.maximum_size = 712704.
• The wrapper currently has no .gitignore, no .github/workflows/, and no build output tooling.

Files to Change

• scripts/build-representative.sh — new wrapper build script for patch application, four-env builds, logs, copied artifacts, and size summary generation.
• scripts/parse-size-report.py — new parser for PlatformIO RAM/flash output plus artifact byte sizes, with optional baseline/compare support.
• .github/workflows/firmware-build.yml — new GitHub Actions workflow using the same representative build script as local development.
• .gitignore — ignore generated out/ and local PlatformIO/cache artifacts if needed.
• README.md — add the local representative build command and output locations.

Ordered Implementation Checklist

1. Add output ignores for wrapper-level generated build artifacts.
2. Implement scripts/parse-size-report.py with ANSI stripping, PlatformIO RAM/flash line parsing, artifact byte discovery, deterministic JSON output, and optional --baseline / --compare <json> arguments.
3. Implement scripts/build-representative.sh with --help, --baseline, --compare <baseline-json>, PlatformIO availability checks, patch application, per-env build.sh build-firmware invocation, per-env log capture, artifact copying, and parser invocation.
4. Ensure build-representative.sh uses REPRESENTATIVE_ENVS from scripts/meshcore-env.sh, sets a default FIRMWARE_VERSION when absent, and preserves each env result rather than hiding failures.
5. Add .github/workflows/firmware-build.yml to check out submodules, install Python 3.11 and PlatformIO, run bash scripts/build-representative.sh --baseline, and upload out/size plus out/firmware artifacts.
6. Update README.md with the representative build command and generated output paths.
7. Run shell syntax and Python compile checks, then run script help and the parser against a small synthetic log fixture without requiring PlatformIO.
8. If PlatformIO is available locally, run the full baseline build; otherwise record that full build verification is deferred to CI or a local PlatformIO install.

Interfaces and Data Contracts

• scripts/build-representative.sh [--baseline|--compare <baseline-json>] builds all envs from REPRESENTATIVE_ENVS and writes outputs under wrapper-level out/.
• scripts/build-representative.sh --help prints usage and exits successfully without requiring PlatformIO.
• scripts/parse-size-report.py --logs <log-dir> --artifacts <artifact-dir> [--baseline|--compare <baseline-json>] [--output <json>] emits JSON containing:
  • mode
  • generated_at
  • environments[]
  • per-env env, ram_used, ram_total, flash_used, flash_total, artifact_bytes, log, metrics_found, and optional delta
• Missing RAM/flash metrics are represented as null and metrics_found: false; the parser must not invent successful measurements.
• CI must use the same local scripts instead of duplicating build logic.

Verification Plan

• Automated:
  • bash -n scripts/build-representative.sh scripts/meshcore-env.sh
  • python3 -m py_compile scripts/parse-size-report.py
  • bash scripts/build-representative.sh --help
  • Run scripts/parse-size-report.py against a synthetic log/artifact directory.
  • If PlatformIO is installed: bash scripts/build-representative.sh --baseline
• Manual:
  • Review generated JSON shape from the synthetic parser run.
  • Confirm workflow env list comes from the wrapper script, not a duplicated matrix.
• Regression:
  • bash scripts/apply-patches.sh still succeeds with an empty patch queue.
  • Step 1 patch scripts remain unchanged in behavior.

Stop Conditions

• Pause if upstream build env names differ from the planned four representative environments.
• Pause if implementing baseline comparison would require committing generated firmware artifacts.
• Pause if local PlatformIO installation or firmware build requires destructive cleanup outside wrapper-level out/ or upstream .pio build directories.