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

Step 1 Execution Plan: Bootstrap wrapper repository, upstream submodule, and patch workflow

Goal

Create a reproducible Colorado Mesh firmware wrapper that pins upstream MeshCore and can apply/export Colorado bot patches without relying on untracked submodule edits.

Current Code Observations

• Local MeshCore exists at /Users/cjvana/Documents/GitHub/MeshCore commit 6b52fb32301c273fc78d96183501eb23ad33c5bb, but research recommends pinning the wrapper submodule independently.
• MeshCore builds from its repo root with build.sh build-firmware <env> and expects FIRMWARE_VERSION in the environment before building.
• MeshCore platformio.ini includes all variant configs via variants/*/platformio.ini and currently enables ENABLE_PRIVATE_KEY_IMPORT=1 / ENABLE_PRIVATE_KEY_EXPORT=1; key hardening is a later step.
• Representative environments exist in the local checkout: Heltec_v3_companion_radio_usb, Heltec_v3_companion_radio_ble, RAK_4631_companion_radio_usb, and RAK_4631_companion_radio_ble.
• PlatformIO is not installed locally right now, so Step 1 verification must be limited to git/submodule/script behavior and shell syntax.

Files to Change

• .gitmodules — created by git submodule add.
• vendor/MeshCore — submodule pointer to upstream MeshCore.
• scripts/meshcore-env.sh — shared wrapper environment variables and helper functions.
• scripts/apply-patches.sh — verify submodule state and apply sorted patch queue.
• scripts/export-patches.sh — regenerate patch queue from a named submodule branch/range.
• patches/meshcore/.gitkeep — keep empty patch queue directory tracked.
• colorado/README.md — short notes for Colorado overlay intent.
• README.md — wrapper workflow instructions for future contributors.

Ordered Implementation Checklist

1. Add vendor/MeshCore as a git submodule from https://github.com/meshcore-dev/MeshCore.git and leave it pinned at the resolved commit.
2. Create scripts/, patches/meshcore/, and colorado/ directories.
3. Implement scripts/meshcore-env.sh with repo-root detection, MESHCORE_DIR, PATCH_DIR, representative env list, and meshcore_commit() helper.
4. Implement scripts/apply-patches.sh with strict shell settings, submodule existence check, dirty submodule check, empty-patch success path, sorted patch application, and clear status output.
5. Implement scripts/export-patches.sh with strict shell settings, dirty submodule guidance, configurable base ref defaulting to origin/main, deterministic patch regeneration, and refusal to export when there are no commits beyond the base.
6. Add minimal README/development notes describing submodule init, patch apply, patch export, and representative env names.
7. Run shell syntax checks and scripts/apply-patches.sh with the empty patch queue.
8. Stage only Step 1 files for review.

Interfaces and Data Contracts

• scripts/meshcore-env.sh can be sourced by other scripts and must not execute builds itself.
• scripts/apply-patches.sh exits 0 with an empty patch queue and exits non-zero if the submodule is missing, dirty, or patch application fails.
• scripts/export-patches.sh [base-ref] regenerates patches/meshcore/*.patch from commits after base-ref; it does not export uncommitted submodule edits.
• Representative env names are exposed as the shell array REPRESENTATIVE_ENVS.

Verification Plan

• Automated:
  • git submodule status
  • bash -n scripts/meshcore-env.sh scripts/apply-patches.sh scripts/export-patches.sh
  • bash scripts/apply-patches.sh
  • git status --short
• Manual:
  • Confirm vendor/MeshCore points to a real upstream commit.
  • Confirm an empty patch queue leaves the submodule unchanged.
• Regression:
  • No firmware source files should be modified in Step 1.
  • .forge/ artifacts are not staged as product source except required Forge documents remain available for review.

Stop Conditions

• Stop and ask if git submodule add fails due to network/auth issues.
• Stop and ask if vendor/MeshCore already exists with unexpected contents.
• Stop and ask before deleting or overwriting any existing non-Forge files.
• Stop if the submodule checkout has unexpected dirty changes immediately after adding it.