Meta: burn down all open fbuild issues one by one (#962 → #959 → #722, then #527, then #574)

[zackees]

Meta / tracking issue: burn down all open fbuild issues, one at a time

This is a sequencing/tracking issue for the 5 currently-open issues on FastLED/fbuild. Each is worked and merged one by one in the order below. The order is chosen by dependency first, then user-facing impact, then scope (smallest self-contained work before the large architectural refactor). Check each box as its PR merges; this meta auto-closes when all are CLOSED.

Snapshot taken 2026-07-08. Open issues: #962, #959, #722, #527, #574.

---

Phase 1 — USB VID/PID resolution cluster

These three share one subsystem (fbuild-core::usb resolver + the online-data VID/PID pipeline) and should land together, smallest/most-acute first so each builds on the last.

• fbuild port scan misses all PJRC/Teensy (VID 16C0) serial ports + no vendor/product resolution for them #962 (DONE — PR fix(serial): list Windows Status=Unknown ports so Teensy (16C0) is visible (#962) #1011 merged) — fbuild port scan misses all PJRC/Teensy (VID 16C0) ports + no vendor/product resolution

  • Why first: concrete user-facing bug (a physically-attached Teensy is invisible to port scan), smallest scope, unblocks the "port-scan before declaring a board absent" agent workflow.
  • Work: (1) stop filtering serial ports on PnP Status == OK so Unknown/phantom/composite MI_00 interfaces enumerate; (2) add PJRC PIDs to the resolver (16C0:0483 USB Serial, 16C0:0478 HalfKay, 16C0:0489 Serial+MIDI+Audio, 04D0..04D9); (3) bonus: surface the MI_xx composite-interface index.
  • Note: the resolver piece here is a hardcoded overlay that follow up all known vids needs built in embedding #959/feat(online-data): ingest per-board VID:PID tables from upstream vendor manifests #722 will later supersede with embedded/ingested data — do the minimal PJRC table now, don't block on the pipeline.

• follow up all known vids needs built in embedding #959 (DONE — PR feat(config): embed MCU→VID heuristic so null-vid boards resolve offline (#959) #1012 merged) — all known VIDs need built-in embedding (not online fallback)

  • Why second: foundational infra. Per PR fix(tests): drop null-vid/pid rows + reflow #740 board-name assertions #925 the resolver currently leans on an online fallback; known VIDs must be ingested at build time and embedded so resolution works offline/air-gapped and in CI without a network round-trip. Establishes the embedding mechanism that feat(online-data): ingest per-board VID:PID tables from upstream vendor manifests #722's richer per-board data will ride on.
  • Depends on: nothing hard, but should land before feat(online-data): ingest per-board VID:PID tables from upstream vendor manifests #722 so feat(online-data): ingest per-board VID:PID tables from upstream vendor manifests #722 has a build-time embedding target to populate.

• feat(online-data): ingest per-board VID:PID tables from upstream vendor manifests #722 (DONE — PR feat(usb): embed refreshed per-board VID:PID archive, drop hardcoded table (#722) #1013 merged; all sub-issues vid-ingest: Espressif Systems (0x303A — ESP32 native USB) #723–vid-ingest: final end-to-end verification (after #723–#739 close) #740 closed) — ingest per-board VID:PID tables from upstream vendor manifests (online-data)

  • Why third: the large data-pipeline piece. Adds tier-1 PID registries (Espressif 0x303A, Raspberry Pi 0x2E8A) + tier-2/3 Arduino-core boards.txt parsers → new online-data/data/usb-board-pids.json + SQLite vidpid population + runtime overlay, so pretty(0x303A, 0x4002) returns "Unexpected Maker TinyS2" instead of a placeholder.
  • Note: feat(online-data): ingest per-board VID:PID tables from upstream vendor manifests #722 is itself a meta with sub-issues vid-ingest: Espressif Systems (0x303A — ESP32 native USB) #723–vid-ingest: final end-to-end verification (after #723–#739 close) #740 (per-vendor ingest + final E2E verification vid-ingest: final end-to-end verification (after #723–#739 close) #740). Those are worked under feat(online-data): ingest per-board VID:PID tables from upstream vendor manifests #722; this meta tracks feat(online-data): ingest per-board VID:PID tables from upstream vendor manifests #722 as the rollup. Verify vid-ingest: Espressif Systems (0x303A — ESP32 native USB) #723–vid-ingest: final end-to-end verification (after #723–#739 close) #740's current state before starting — some may already be closed.

---

Phase 2 — CI cache

• Proposal: first-class fbuild cache save / restore for toolchains + platforms + framework + zccache sidecar #527 (DONE — PR feat(cli): first-class fbuild cache save/restore/list/verify (#527) #1014 merged) — first-class fbuild cache save / restore for toolchains + platforms + framework + zccache sidecar
  • Why fourth: independent of the USB cluster and self-contained, with high CI payoff (replaces the fragile six-path actions/cache@v4 workaround; parallel walk/extract fixes the Windows-Defender untar throttle). Modeled on soldr's cache_lib::save/load.
  • v1 scope: save/restore/list/verify subcommands, hand-written prost manifest (no protoc), --include/--exclude/--zstd-level(=9)/--threads(=num_cpus)/--zccache-sidecar, round-trip tests per slice on Linux + Windows. Delta archives, mtime replay, sketch caching, and extra slices are explicitly deferred to v2.

---

Phase 3 — Architecture (largest refactor, do last)

• fbuild: design unified namespaced routing for platform/framework/library artifacts driven by platformio.ini [env:*] #574 (DONE — PR feat(build): EnvNamespace + unified build_flags overlay propagation (#574) #1022 merged) — unified namespaced routing for platform/framework/library artifacts driven by platformio.ini [env:*]
  • Why last: largest architectural change; touches every per-platform orchestrator. Doing it after the smaller wins means the codebase is stable and the change gets full design attention.
  • Work: define typed EnvNamespace { platform, board, framework, env_id }; thread it through every package fetcher, compile invocation, cache path, and output dir; propagate [env:*] build_flags to framework/lib/sketch compiles (currently dropped on nxplpc); env-scoped lib cache keys; namespace-keyed deployer dispatch; docs/namespacing.md. Success = one sample sketch builds on uno, teensy40, lpc845brk, esp32s3, esp32c6, teensy41 from one project root with one build_flags mechanism.

---

Working rules for each item

1. Confirm the issue is still open and re-read its body (bodies drift).
2. Plan non-trivial work in the issue thread first (per repo CLAUDE.md).
3. One PR per issue, conventional-commit title, TDD (red → green → refactor).
4. soldr cargo for Rust, uv run for Python — never bare cargo/python.
5. Merge, tick the box here, move to the next. Do not parallelize across phases.

Dependency summary

#962 ──▶ #959 ──▶ #722 (rollup of #723–#740)   [USB cluster, sequential]
#527                                            [independent, after cluster]
#574                                            [independent, last]

🤖 Filed via Claude Code — meta tracking issue for the open-issue burn-down.

[zackees]

Progress — #962 (Phase 1, item 1): PR #1011 opened.

Root cause was deeper than a status filter: upstream serialport enumerates the Windows Ports class with DIGCF_PRESENT, which excludes the Teensy's composite MI_00 serial interfaces entirely (their function driver never starts → PnP Status = Unknown → CR_NO_SUCH_DEVINST phantoms), before the problem-code filter even runs. Fix adds a blessed fbuild_serial::ports::available_ports() (Windows fork enumerating with flags=0, recovering VID/PID from the composite child hwid when the phantom parent is unreachable, including non-present ports only when USB). Verified on real hardware — Teensy 16C0 ports now appear + resolve, with the MI_xx index surfaced.

Discovered follow-up (to be handled under #959, not a regression): the remaining hardcoded FRIENDLY_PRODUCTS entries in port_scan.rs (Espressif 303A, NXP 1FC9:0143) still aren't in the embedded FastLED/boards VID:PID archive. Migrating them into the boards other branch and deleting the in-code table is the natural "build-time embedding" work for #959.

[zackees]

All five sub-issues merged and closed: #962 (PR #1011), #959 (#1012), #722 (#1013), #527 (#1014), and #574 (#1022). Closing as completed.