diff --git a/README.md b/README.md index 447bdba..8e445c0 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ validates — not a code change. DroidNetCommandLibrary.loadLibrary(boards, { libraryVersion: m.libraryVersion }); DroidNetCommandLibraryUI.renderComposer( document.getElementById('host'), - 'A007^*** Flthy Rainbow', + 'A006^*** Flthy Rainbow', { onChange: (wire) => console.log(wire) } ); })); @@ -65,8 +65,8 @@ const DroidNetCommandLibrary = require('droidnet-command-library'); require('droidnet-command-library/node-loader').loadCatalog(); // reads manifest + boards, merges, loads const solid = DroidNetCommandLibrary.getCommand('flthy.led.solid'); -DroidNetCommandLibrary.encode(solid, { designator: 'A', color: '5' }, {}); // 'A0065' -DroidNetCommandLibrary.match('A0065'); // { commandId: 'flthy.led.solid', params: {...} } +DroidNetCommandLibrary.encode(solid, { designator: 'A', color: '5' }, {}); // 'A0055' +DroidNetCommandLibrary.match('A0055'); // { commandId: 'flthy.led.solid', params: {...} } ``` See **[docs/INTEGRATION_GUIDE.md](docs/INTEGRATION_GUIDE.md)** for the full API. diff --git a/docs/BOARD_AUTHORING_GUIDE.md b/docs/BOARD_AUTHORING_GUIDE.md index f67e4a6..fb68e1d 100644 --- a/docs/BOARD_AUTHORING_GUIDE.md +++ b/docs/BOARD_AUTHORING_GUIDE.md @@ -107,6 +107,14 @@ confirm-before-firing warning in the UI. Use `movement` for anything that moves hardware, `power` for power switching, `config` for settings that change state. When unsure, pick the more cautious class. +**Firmware requirements go in the name.** Neither the composer nor the hosted +reference shows a component's `firmware` or `routing.notes`, so users never see +them. When a command needs newer firmware than the rest of its board, say so in +the command `name` — e.g. `"Go Home (WCB 6.2+)"`. When the whole board needs it, +put it in the component `name` and the matching manifest entry. Keep `firmware` +and `routing.notes` accurate anyway: they are the reviewer's record of what was +verified. + **`commentLabel` — the auto-note on insert.** When a step is added, the composer attaches this string as the step's `*** …` comment (its human label in the wire string). It supports two bits of grammar, so the note can describe the actual diff --git a/docs/INTEGRATION_GUIDE.md b/docs/INTEGRATION_GUIDE.md index 0988f5a..e2591d7 100644 --- a/docs/INTEGRATION_GUIDE.md +++ b/docs/INTEGRATION_GUIDE.md @@ -74,9 +74,9 @@ exactly what an "Update Library" button does after downloading a newer set of fi ```js const cmd = DroidNetCommandLibrary.getCommand('flthy.led.solid'); -DroidNetCommandLibrary.encode(cmd, { designator: 'A', color: '5' }, {}); // 'A0065' -DroidNetCommandLibrary.encode(cmd, { designator: 'A' }, { duration: 60 }); // 'A0065|60' (default color, duration) -DroidNetCommandLibrary.match('A0065'); // { commandId: 'flthy.led.solid', params: { designator:'A', color:'5' }, duration: undefined } +DroidNetCommandLibrary.encode(cmd, { designator: 'A', color: '5' }, {}); // 'A0055' +DroidNetCommandLibrary.encode(cmd, { designator: 'A' }, { duration: 60 }); // 'A0055|60' (default color, duration) +DroidNetCommandLibrary.match('A0055'); // { commandId: 'flthy.led.solid', params: { designator:'A', color:'5' }, duration: undefined } ``` ## The wire format @@ -91,7 +91,7 @@ DroidNetCommandLibrary.match('A0065'); // { commandId: 'flthy.led.solid', param so unknown tokens round-trip without loss. ```text -A007^*** Flthy rainbow^;t500^T52 +A006^*** Flthy rainbow^;t500^T52 └ cmd ┘└── label ──┘└delay┘└cmd┘ ``` @@ -120,7 +120,7 @@ engine being loaded first. DroidNetCommandLibrary.loadLibrary(boards, { libraryVersion: m.libraryVersion }); DroidNetCommandLibraryUI.renderComposer( document.getElementById('host'), - 'A007^*** Flthy Rainbow', // initial wire value (or '' for empty) + 'A006^*** Flthy Rainbow', // initial wire value (or '' for empty) { onChange: (wireValue) => { // fired on every edit — persist or mirror it diff --git a/docs/superpowers/plans/2026-09-15-wcb-firmware-6.2.1-sweep.md b/docs/superpowers/plans/2026-09-15-wcb-firmware-6.2.1-sweep.md new file mode 100644 index 0000000..b63b71c --- /dev/null +++ b/docs/superpowers/plans/2026-09-15-wcb-firmware-6.2.1-sweep.md @@ -0,0 +1,150 @@ +# WCB Firmware v6.2.1 Command Sweep — Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Publish droidnet-command-library **4.3.0** on top of 4.2.0: the WCB 6.2.1 command surface (Maestro comma verbs, a new DFPlayer board, HCR/MP3/WLED updates, 66 new `wcb-native` commands, range fixes) plus the FlthyHPs sequence-code fix — without breaking any value stored under a 4.2.0 id. + +**Architecture:** JSON board authoring against the schema-driven engine; no engine or schema change. Guard tests land first and pass on 4.2.0; each board commit keeps its file's existing formatting so the diff stays reviewable. + +**Tech Stack:** Node 20, ajv, jest. `npm ci`, `npm run validate`, `npm test`, `npx jest test/wcb-621.test.js`. + +**Spec:** `docs/superpowers/specs/2026-09-15-wcb-firmware-6.2.1-sweep-design.md` (decisions D1-D6, per-board tables, id map, FlthyHPs evidence). + +**Firmware source of truth:** greghulette/Wireless_Communication_Board-WCB @ `66845b9a` (`Code/WCB/`), greghulette/WcbCmd 0.8.0 @ `168f1e5` (`src/`), WCB 6.1.5 tag `v6.1.5_290119RJUN2026` for "(WCB 6.2+)" decisions, FlthyHPs v1.81 / v2.1 sketches. + +## Global Constraints + +- **Re-read every cited firmware line before encoding a template, range or enum.** If firmware and the spec disagree, follow firmware and say so in the commit message. +- **D2 freeze:** every 4.2.0 id keeps a byte-identical `template` and ordered param names. Only add ids. The one exception is A11 (three FlthyHPs templates), whitelisted in the freeze test. +- **D5 naming:** a command that needs 6.2 inside a board that also works on older firmware gets " (WCB 6.2+)" in `name`; a 6.2-only board carries it in the component and manifest `name`. +- **Hand-edit board files.** Do not regenerate a board with a JSON re-serializer: `wcb-native`, `wcb-hcr` and `wcb-wled` are compact files and a `JSON.stringify(o, null, 2)` rewrite produces thousand-line diffs. `maestro.json` is already fully expanded. +- **Categories:** every command has a `category` listed in the component `categories`. Non-standard names (`Volume`, `Variables`, `Routing`, `Advanced`) warn only. +- **Examples:** at least one per command, no `^`, and every example on a WCB board must decode to its own id (A2 test b). `wcb-verb` examples stay within 187 characters (A2 test c). +- **Order:** specific literals before catch-alls (first match wins). +- **Gate per commit:** `npm run validate` exits 0 and `npm test` is green. +- **Commits:** conventional messages; end with the `Co-Authored-By` trailer. + +--- + +### Task A0: Prepare + +- [ ] `git fetch origin && git status` — clean; `main == origin/main == 82b6a04`. +- [ ] If `origin/main` moved: rebase this plan onto it; if the new tip changed `libraryVersion`, target the next minor instead of 4.3.0. +- [ ] `git switch -c wcb-firmware-6.2.1-sweep` +- [ ] `npm ci && npm run validate && npm test` — baseline green (4.2.0: 11 suites, 324 tests). + +### Task A1: Docs — `docs(wcb-6.2.1): sweep spec + plan` + +**Files:** create the spec and this plan; modify `docs/BOARD_AUTHORING_GUIDE.md`. + +- [ ] Spec: goal, firmware refs, D1-D6, per-board tables, out-of-scope list, ordering hazards, DroidNet 2.2.0 → 4.3.0 id map, FlthyHPs decision and evidence. +- [ ] Guide: after the "`safety` matters" paragraph, add that the composer shows neither `firmware` nor `routing.notes`, so a firmware requirement goes in the command or component name, e.g. "(WCB 6.2+)". + +### Task A2: Guard tests — `test: freeze 4.2.0 ids/templates; WCB examples parse to their own command` + +Lands before any board edit and must pass on 4.2.0. + +**Files:** create `test/fixtures/catalog-4.2.0-commands.json`, `test/wcb-621.test.js`. + +- [ ] Generate the fixture once at `82b6a04` from `require('./src/load-node.js').readCatalog()`: `{ "": { "board": "", "template": "