forge: step 2 — add representative build tooling

.forge/reviews/claude-step-2.json

@@ -0,0 +1,56 @@
+{
+  "verdict": "APPROVED",
+  "blocking_issues": 0,
+  "reviewed_files": [
+    "/Users/cjvana/Documents/GitHub/meshcore-bot-fw/.forge/PLAN.md",
+    "/Users/cjvana/Documents/GitHub/meshcore-bot-fw/.forge/steps/step-2-plan.md",
+    "/Users/cjvana/Documents/GitHub/meshcore-bot-fw/.forge/reviews/claude-step-2.json",
+    "/Users/cjvana/Documents/GitHub/meshcore-bot-fw/.github/workflows/firmware-build.yml",
+    "/Users/cjvana/Documents/GitHub/meshcore-bot-fw/.gitignore",
+    "/Users/cjvana/Documents/GitHub/meshcore-bot-fw/README.md",
+    "/Users/cjvana/Documents/GitHub/meshcore-bot-fw/scripts/build-representative.sh",
+    "/Users/cjvana/Documents/GitHub/meshcore-bot-fw/scripts/parse-size-report.py",
+    "/Users/cjvana/Documents/GitHub/meshcore-bot-fw/scripts/meshcore-env.sh",
+    "/Users/cjvana/Documents/GitHub/meshcore-bot-fw/scripts/apply-patches.sh",
+    "/Users/cjvana/Documents/GitHub/meshcore-bot-fw/vendor/MeshCore/build.sh",
+    "/Users/cjvana/Documents/GitHub/meshcore-bot-fw/vendor/MeshCore/.github/workflows/build-companion-firmwares.yml",
+    "/Users/cjvana/Documents/GitHub/meshcore-bot-fw/vendor/MeshCore/.github/actions/setup-build-environment/action.yml",
+    "/Users/cjvana/Documents/GitHub/meshcore-bot-fw/vendor/MeshCore/variants/heltec_v3/platformio.ini",
+    "/Users/cjvana/Documents/GitHub/meshcore-bot-fw/vendor/MeshCore/variants/rak4631/platformio.ini"
+  ],
+  "diff_basis": "provided_list",
+  "plan_section": "Step 2: Add representative build and size-report tooling",
+  "dimensions": {
+    "plan_alignment": {
+      "score": "PASS",
+      "notes": "The implementation matches the Step 2 goal: it builds the four planned representative environments, applies patches, captures logs/artifacts, emits size summaries, adds CI, ignores generated outputs, and documents local usage."
+    },
+    "correctness_safety": {
+      "score": "PASS",
+      "notes": "PlatformIO availability is checked with a clear local .venv fallback, compare/baseline argument conflicts are rejected in the wrapper, failed envs are preserved and reported after parsing, and missing metrics are represented explicitly rather than fabricated."
+    },
+    "code_quality": {
+      "score": "PASS",
+      "notes": "The shell and Python scripts are readable, appropriately separated by responsibility, quote paths safely, and reuse Step 1 environment definitions instead of duplicating the representative env list in CI."
+    },
+    "completeness": {
+      "score": "PASS",
+      "notes": "Acceptance criteria are satisfied based on the changed files and provided verification, including full representative builds, parser synthetic coverage, CI YAML parsing, and compare/baseline checks."
+    },
+    "patterns": {
+      "score": "PASS",
+      "notes": "The changes follow the wrapper-repository pattern, use the upstream build script rather than replacing it, and store all generated build outputs under ignored wrapper-level out/ paths."
+    },
+    "integration": {
+      "score": "PASS",
+      "notes": "The wrapper accounts for upstream build.sh clearing vendor/MeshCore/out per invocation by copying artifacts after each environment build, and the GitHub workflow uses the same local script as developers."
+    }
+  },
+  "flags": [
+    {
+      "file": "/Users/cjvana/Documents/GitHub/meshcore-bot-fw/scripts/parse-size-report.py",
+      "line": 126,
+      "note": "The generated_at timestamp means summary JSON is not byte-for-byte identical across identical inputs. This is non-blocking because ordering and schema are deterministic and generated_at is part of the step execution contract."
+    }
+  ]
+}

.forge/steps/step-2-plan.md

@@ -0,0 +1,59 @@
+# 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.