@dheerajsom/pinhub 0.1.2 → 0.2.0

package/{README.md → CLI.md}

@@ -1,4 +1,4 @@
-# pinhub — pinout diagrams in your terminal
+# PinHub CLI (`ph`)
 
 `@dheerajsom/pinhub` installs a tiny cross-platform command, **`ph`**, that draws hardware
 board pinout diagrams straight in your terminal — pin numbers, GPIO names,
@@ -10,7 +10,7 @@ $ ph rpi5
 
 Raspberry Pi 5 — Raspberry Pi
 Source: Raspberry Pi GPIO documentation (official) — see ph raspberry-pi-5 --source
-⚠ GPIO uses 3.3 V logic. Do not apply 5 V to any GPIO pin.
+✖ GPIO uses 3.3 V logic. Do not apply 5 V to any GPIO pin.
 
 40-pin GPIO header (J8)
   ┌────────────────────┬────┬────┬───────────────────┐
@@ -55,6 +55,11 @@ ph --version          # version
 Board names are forgiving: `ph rpi5`, `ph pi5`, `ph raspberry-pi-5`, and
 `ph raspberry pi 5` all resolve to the same board, case-insensitively.
 
+Compatibility note for 0.2: `arduino-uno-rev3` is the canonical UNO identifier
+used by list and JSON output; the former `arduino-uno-r3` spelling remains a
+supported alias. `esp32` continues to select the DOIT 30-pin
+`esp32-devkit-v1`; the distinct 38-pin Espressif board is `esp32-devkitc`.
+
 ### Output flags
 
 | Flag | Effect |
@@ -62,9 +67,20 @@ Board names are forgiving: `ph rpi5`, `ph pi5`, `ph raspberry-pi-5`, and
 | `--compact` | Tighter, borderless layout for small terminals |
 | `--ascii` | ASCII-only borders and symbols (no Unicode) |
 | `--no-color` | Disable ANSI colors |
-| `--json` | Emit the board's full data as JSON (stdout is pure JSON) |
-| `--source` | Print the board's documentation source links |
-| `--width <n>` | Override the detected terminal width |
+| `--no-motion` | Disable the brief interactive signal pulse |
+| `--details` | Show additional alternate pin functions |
+| `--json` | Emit machine-readable JSON (one board or a list/search array) |
+| `--source` | Print one board's documentation source links |
+| `--width <n>` | Use a whole-number terminal width from 20 to 1000 |
+
+Presentation flags are global and work in any position, including `ph list
+--no-color`, `ph search pico --width 60`, and `ph info rpi5 --ascii`. JSON
+always keeps stdout pure; `list` and `search` return arrays. Because `--source`
+and `--details` are one-board views, using them with `list` or `search` fails
+with a short correction instead of silently ignoring the flag. JSON is a
+separate machine-readable view, so it cannot be combined with `--ascii`,
+`--compact`, `--details`, `--source`, or `--width`; `--no-color` and
+`--no-motion` remain safe global opt-outs.
 
 Examples:
 
@@ -72,15 +88,17 @@ Examples:
 ph rpi5
 ph esp32
 ph pico --compact
+ph pico --details
 ph rpi5 --ascii --no-color
 ph uno --json | jq '.headers[].name'
+ph search raspberry --json | jq '.[].id'
 ph rpi5 --source
 ```
 
 ## Boards
 
 The catalog carries the full [PinHub website](https://pinhub.vercel.app) board
-set — 125 boards across Raspberry Pi, Arduino, Espressif, STM32, Teensy,
+set — 126 boards across Raspberry Pi, Arduino, Espressif, STM32, Teensy,
 Adafruit, SparkFun, Seeed, BeagleBone, Jetson, and more. Run `ph list` to see
 everything. A few starters:
 
@@ -103,10 +121,21 @@ everything. A few starters:
   is `--no-color`.
 - When output is piped or redirected (not a TTY), color is disabled
   automatically and the layout stays stable.
-- `--ascii` avoids all Unicode for legacy terminals and screen readers that
-  struggle with box-drawing characters.
+- `--ascii` guarantees ASCII-only text for legacy terminals and screen readers
+  that struggle with box-drawing characters.
 - On narrow terminals the diagram degrades gracefully: full bordered table →
-  compact pairs → vertical list. Warnings and source lines are never truncated.
+  compact pairs → wrapped vertical list. Catalog tables, warnings, long source
+  titles, and URLs wrap to the requested terminal-cell width without truncating
+  hardware information.
+- Danger, warning, and informational messages use distinct symbols (`✖`, `⚠`,
+  `ℹ`; or `X`, `!`, `i` in ASCII mode), so severity never depends on color.
+- Interactive commands briefly show a color-cycling signal pulse before their
+  result. It is written to the TTY only and erases itself. It never runs for
+  pipes, CI, `TERM=dumb`, help, version, JSON, `--no-color`/`NO_COLOR`, or
+  `--no-motion`. `PINHUB_NO_MOTION=1` disables it persistently.
+- Pin-specific notes are printed below their header and marked on the diagram.
+  The first alternate function remains inline; `--details` expands any
+  additional functions.
 
 ## Hardware safety disclaimer
 
@@ -128,7 +157,7 @@ Most of the catalog is **generated from the PinHub website data**
    `src/boards/generated.ts`.
 2. Add short aliases people actually type in `scripts/curated-aliases.ts`.
 3. Run `npm test` — catalog invariant tests check sources, warnings, alias
-   uniqueness, and pin-grid consistency across all 125 boards.
+   uniqueness, and pin-grid consistency across all 126 boards.
 
 Five flagship boards (Pi 5, Pico, Pico W, UNO R3, ESP32 DevKit V1) have richer
 hand-written modules in `src/boards/`, one file per board, using the typed
@@ -151,15 +180,26 @@ npm run dev -- rpi5     # run from TypeScript source
 npm test                # vitest suite (alias, JSON, rendering, snapshots)
 npm run lint            # eslint
 npm run build           # compile to dist/
+npm run check:boards    # verify generated catalog data is current
 npm run package:check   # npm pack --dry-run
 ```
 
 The CLI entry point is `src/cli.ts`; `src/run.ts` contains the whole command
-surface as a testable function that writes to captured buffers. Renderers live
+surface as a deterministic, testable function that writes to captured buffers.
+The executable-only signal pulse stays at the `src/cli.ts` boundary, so library
+callers and JSON output never receive animation controls. Renderers live
 in `src/render/` behind a small abstraction (`dual-row` bordered table,
 compact pairs, and vertical list), so new header layouts can be added without
 touching board data. CI runs lint, tests, build, and a smoke test on Windows,
 macOS, and Linux via GitHub Actions.
 
-To publish: `npm publish` from `cli/` (the `prepublishOnly` hook lints, tests,
-and builds; the `files` allowlist ships only `dist/`).
+To publish a SemVer release from `cli/` (choose the appropriate version level):
+
+```bash
+npm version patch
+npm publish --access public
+```
+
+The `prepublishOnly` hook verifies generated board data, lints, tests, and
+builds. The `files` allowlist ships only the compiled CLI and its user
+documentation.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dheeraj Som
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/SETUP.md

@@ -50,7 +50,7 @@ If `ph` prints a pinout diagram, you're done.
 ## 3. Install from source (this repository)
 
 ```bash
-git clone https://github.com/<your-org>/PinHub.git
+git clone https://github.com/Dheerajsom/PinHub.git
 cd PinHub/cli
 npm install
 npm run build
@@ -70,7 +70,7 @@ npm run dev -- rpi5
 ## 4. First steps
 
 ```bash
-ph list                 # see all 125 boards in the catalog
+ph list                 # see all 126 boards in the catalog
 ph rpi5                 # Raspberry Pi 5 GPIO header
 ph pico                 # Raspberry Pi Pico
 ph uno                  # Arduino UNO R3
@@ -83,8 +83,13 @@ ph info esp32           # warnings, sources, aliases
 ph rpi5 --source        # official documentation links
 ```
 
-Useful flags: `--compact` (small terminals), `--ascii` (no Unicode),
-`--no-color`, `--json` (script-friendly), `--width <n>`.
+Useful flags: `--compact` (small terminals), `--ascii` (strict ASCII),
+`--no-color`, `--no-motion`, `--details` (all alternate functions), `--json`
+(script-friendly), and `--width <n>` (20 to 1000 columns).
+
+`--json` is a separate machine-readable view and cannot be combined with
+`--ascii`, `--compact`, `--details`, `--source`, or `--width`. Source and detail
+views require one board and cannot be requested together.
 
 Board names are forgiving — `ph rpi5`, `ph pi5`, and `ph raspberry pi 5` all
 work. If you guess wrong, `ph` suggests the closest matches.
@@ -110,6 +115,11 @@ Color is automatically disabled when output is piped or when the
 [`NO_COLOR`](https://no-color.org/) environment variable is set. Force it off
 per-invocation with `--no-color`.
 
+**You prefer no terminal animation**
+The short signal pulse only appears in an interactive color terminal. It is
+automatically disabled for pipes, CI, `TERM=dumb`, help, version, and JSON.
+Use `--no-motion` for one command, or set `PINHUB_NO_MOTION=1` to keep it off.
+
 **The diagram looks cramped or wraps badly**
 `ph` adapts to terminal width and falls back to a compact layout, but you can
 control it: widen the terminal, or use `--compact`, or `--width 100`.
@@ -125,5 +135,6 @@ npm uninstall -g @dheerajsom/pinhub
 `ph` shows each board's voltage levels, reserved pins, and boot-strap pins,
 and cites its documentation sources — but board revisions differ (ESP32
 boards especially). Always cross-check your exact board's silkscreen and the
-official documentation (`ph <board> --source`) before wiring. 3.3 V GPIO does
+source list (`ph <board> --source`), including any third-party label, before
+wiring. 3.3 V GPIO does
 not forgive 5 V.

package/dist/boards/arduino-uno-r3.js

@@ -9,7 +9,7 @@ function col(physical, label, category, extra = {}) {
 }
 const V5 = { voltage: "5 V" };
 export const arduinoUnoR3 = {
-    id: "arduino-uno-r3",
+    id: "arduino-uno-rev3",
     name: "Arduino UNO R3",
     manufacturer: "Arduino",
     aliases: ["uno", "uno-r3", "arduino-uno", "arduino-uno-r3", "arduino-uno-rev3"],

package/dist/boards/esp32-devkit-v1.js

@@ -23,11 +23,9 @@ export const esp32DevkitV1 = {
     aliases: [
         "esp32",
         "esp32-devkit",
-        "esp32-devkit-v1",
         "esp32-devkitv1",
         "doit-esp32-devkit-v1",
         "esp32-wroom-32",
-        "esp32-devkitc",
     ],
     description: "The ubiquitous 30-pin ESP32-WROOM-32 breadboard dev kit. Wi-Fi + Bluetooth, two breadboard-friendly headers, 3.3 V logic.",
     revisionNote: "ESP32 dev boards vary a lot: 30-pin DevKit V1, 36-pin variants, and the 38-pin Espressif ESP32-DevKitC all have different headers. Verify the silkscreen of your exact board before wiring anything.",
@@ -58,16 +56,19 @@ export const esp32DevkitV1 = {
             title: "Espressif ESP32-WROOM-32 datasheet",
             url: "https://www.espressif.com/sites/default/files/documentation/esp32-wroom-32_datasheet_en.pdf",
             official: true,
+            type: "Datasheet",
         },
         {
             title: "Espressif ESP32 series datasheet",
             url: "https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf",
             official: true,
+            type: "Datasheet",
         },
         {
-            title: "Last Minute Engineers — ESP32 DevKit pinout reference (third-party board layout)",
+            title: "Last Minute Engineers — ESP32 DevKit 30-pin layout",
             url: "https://lastminuteengineers.com/esp32-pinout-reference/",
             official: false,
+            type: "Pinout",
         },
     ],
     headers: [
@@ -132,7 +133,7 @@ export const esp32DevkitV1 = {
                 pin(28, "D15", "gpio", {
                     gpio: "GPIO15",
                     functions: ["ADC2_CH3", "HSPI CS"],
-                    notes: ["Boot strap: keep high at reset to silence boot log"],
+                    notes: ["Boot strap; pull low at reset to silence the ROM boot log"],
                     ...V33,
                 }),
                 pin(29, "GND", "ground"),