@dheerajsom/pinhub 0.1.2 → 0.2.0

package/dist/render/meta.js

@@ -1,62 +1,143 @@
+import { asciiChars } from "./chars.js";
+import { normalizeWidth, padEndVisible, padStartVisible, toAscii, visibleWidth, wrapText, } from "./text.js";
 import { warningStyle } from "./theme.js";
-import { wrapText } from "./board.js";
-export function renderBoardTable(boardList, c) {
+function finish(text, opts) {
+    return opts.chars === asciiChars ? toAscii(text) : text;
+}
+function warningMarker(chars, severity) {
+    switch (severity) {
+        case "danger":
+            return chars.danger ?? chars.warn;
+        case "warning":
+            return chars.warn;
+        case "info":
+            return chars.info;
+    }
+}
+function renderCardList(rows, opts) {
+    const { chalk: c, chars: ch } = opts;
+    const width = normalizeWidth(opts.width);
+    const lines = [];
+    for (const row of rows) {
+        lines.push(...wrapText(`${row.id} (${row.pins} pins)`, width).map((line) => c.bold(line)));
+        if (!opts.compact) {
+            lines.push(...wrapText(`${row.name} ${ch.dash ?? "-"} ${row.manufacturer}`, width, "  ").map((line) => c.dim(line)));
+        }
+    }
+    return lines;
+}
+/** Width-responsive catalog/search table; cells wrap instead of being truncated. */
+export function renderBoardTable(boardList, opts) {
+    const { chalk: c } = opts;
+    const width = normalizeWidth(opts.width);
     const rows = boardList.map((board) => ({
         id: board.id,
         name: board.name,
         manufacturer: board.manufacturer,
-        pins: String(board.headers.reduce((sum, h) => sum + h.pins.length, 0)),
+        pins: String(board.headers.reduce((sum, header) => sum + header.pins.length, 0)),
     }));
-    const idWidth = Math.max(...rows.map((r) => r.id.length), 2);
-    const nameWidth = Math.max(...rows.map((r) => r.name.length), 5);
-    const mfrWidth = Math.max(...rows.map((r) => r.manufacturer.length), 12);
-    const lines = [
-        c.dim(`${"ID".padEnd(idWidth)}  ${"BOARD".padEnd(nameWidth)}  ${"MANUFACTURER".padEnd(mfrWidth)}  PINS`),
-        ...rows.map((r) => `${c.bold(r.id.padEnd(idWidth))}  ${r.name.padEnd(nameWidth)}  ${r.manufacturer.padEnd(mfrWidth)}  ${r.pins.padStart(4)}`),
-    ];
+    const lines = [c.bold(`${rows.length} board${rows.length === 1 ? "" : "s"}`)];
+    if (rows.length === 0)
+        return finish(lines.join("\n"), opts);
+    const pinWidth = Math.max(4, ...rows.map((row) => visibleWidth(row.pins)));
+    const availableForText = width - pinWidth - 6;
+    if (opts.compact || availableForText < 36) {
+        lines.push(...renderCardList(rows, opts));
+    }
+    else {
+        const idWidth = Math.max(14, Math.floor(availableForText * 0.4));
+        const nameWidth = Math.max(12, Math.floor(availableForText * 0.34));
+        const manufacturerWidth = availableForText - idWidth - nameWidth;
+        lines.push(c.dim(`${padEndVisible("ID", idWidth)}  ${padEndVisible("BOARD", nameWidth)}  ${padEndVisible("MANUFACTURER", manufacturerWidth)}  ${padStartVisible("PINS", pinWidth)}`));
+        for (const row of rows) {
+            const idLines = wrapText(row.id, idWidth);
+            const nameLines = wrapText(row.name, nameWidth);
+            const manufacturerLines = wrapText(row.manufacturer, manufacturerWidth);
+            const height = Math.max(idLines.length, nameLines.length, manufacturerLines.length);
+            for (let index = 0; index < height; index += 1) {
+                const id = padEndVisible(idLines[index] ?? "", idWidth);
+                const name = padEndVisible(nameLines[index] ?? "", nameWidth);
+                const manufacturer = padEndVisible(manufacturerLines[index] ?? "", manufacturerWidth);
+                const pins = index === 0 ? padStartVisible(row.pins, pinWidth) : " ".repeat(pinWidth);
+                lines.push(`${c.bold(id)}  ${name}  ${manufacturer}  ${pins}`.trimEnd());
+            }
+        }
+    }
     lines.push("");
-    lines.push(c.dim("Show a pinout with: ph <id>   e.g. ph rpi5"));
-    return lines.join("\n");
+    lines.push(...wrapText("Show a pinout with: ph <id>   e.g. ph rpi5", width).map((line) => c.dim(line)));
+    return finish(lines.join("\n"), opts);
 }
-export function renderSources(board, c) {
-    const lines = [`${c.bold(board.name)} ${c.dim("— sources")}`];
+export function renderSources(board, opts) {
+    const { chalk: c, chars: ch } = opts;
+    const width = normalizeWidth(opts.width);
+    const lines = wrapText(`${board.name} ${ch.dash ?? "-"} sources`, width).map((line) => c.bold(line));
     for (const source of board.sources) {
-        const tag = source.official ? c.green("(official)") : c.yellow("(third-party)");
-        lines.push(`  ${source.title} ${tag}`);
-        lines.push(c.dim(`    ${source.url}`));
+        const tag = source.official ? "official" : "third-party";
+        const style = source.official ? c.green : c.yellow;
+        lines.push(...wrapText(`${ch.bullet} ${source.title} (${tag})`, width, "  ", "    ").map((line) => style(line)));
+        lines.push(...wrapText(source.url, width, "    ", "    ").map((line) => c.dim(line)));
     }
-    return lines.join("\n");
+    return finish(lines.join("\n"), opts);
 }
-export function renderInfo(board, c, ch, width) {
+export function renderInfo(board, opts) {
+    const { chalk: c, chars: ch } = opts;
+    const width = normalizeWidth(opts.width);
     const lines = [];
-    lines.push(`${c.bold(board.name)} ${c.dim(`— ${board.manufacturer}`)}`);
+    lines.push(...wrapText(`${board.name} ${ch.dash ?? "-"} ${board.manufacturer}`, width).map((line) => c.bold(line)));
     if (board.description)
-        lines.push(...wrapText(board.description, width, ""));
+        lines.push(...wrapText(board.description, width));
     if (board.revisionNote) {
         lines.push("");
-        lines.push(...wrapText(`Revision note: ${board.revisionNote}`, width, "").map((l) => c.dim(l)));
+        lines.push(...wrapText(`Revision note: ${board.revisionNote}`, width).map((line) => c.dim(line)));
     }
-    lines.push("");
-    lines.push(c.bold("Headers"));
+    lines.push("", c.bold("Headers"));
     for (const header of board.headers) {
-        lines.push(`  ${ch.bullet} ${header.name} — ${header.pins.length} pins`);
+        lines.push(...wrapText(`${ch.bullet} ${header.name} ${ch.dash ?? "-"} ${header.pins.length} pins`, width, "  ", "    "));
     }
-    lines.push("");
-    lines.push(c.bold("Warnings"));
+    if (board.headers.length === 0) {
+        lines.push(...wrapText("No pinout headers available yet.", width, "  ").map((line) => c.dim(line)));
+    }
+    lines.push("", c.bold("Warnings"));
     for (const warning of board.warnings) {
-        const marker = warning.severity === "info" ? ch.info : ch.warn;
+        const marker = warningMarker(ch, warning.severity);
         const style = warningStyle(c, warning.severity);
-        lines.push(...wrapText(`${marker} ${warning.text}`, width, "  ").map((l) => style(l)));
+        lines.push(...wrapText(`${marker} ${warning.text}`, width, "  ", "    ").map((line) => style(line)));
     }
-    lines.push("");
-    lines.push(c.bold("Sources"));
+    lines.push("", c.bold("Sources"));
     for (const source of board.sources) {
-        const tag = source.official ? c.green("(official)") : c.yellow("(third-party)");
-        lines.push(`  ${ch.bullet} ${source.title} ${tag}`);
-        lines.push(c.dim(`    ${source.url}`));
+        const tag = source.official ? "official" : "third-party";
+        const style = source.official ? c.green : c.yellow;
+        lines.push(...wrapText(`${ch.bullet} ${source.title} (${tag})`, width, "  ", "    ").map((line) => style(line)));
+        lines.push(...wrapText(source.url, width, "    ", "    ").map((line) => c.dim(line)));
+    }
+    if (opts.details) {
+        lines.push("", c.bold("Pin details"));
+        let detailCount = 0;
+        for (const header of board.headers) {
+            const pins = [...header.pins]
+                .sort((left, right) => left.physical - right.physical)
+                .filter((pin) => Boolean(pin.functions?.length || pin.notes?.length));
+            if (pins.length === 0)
+                continue;
+            lines.push(...wrapText(header.name, width, "  ").map((line) => c.bold(line)));
+            for (const pin of pins) {
+                const detail = [];
+                if (pin.functions?.length)
+                    detail.push(`functions: ${pin.functions.join(", ")}`);
+                if (pin.notes?.length)
+                    detail.push(...pin.notes);
+                const prefix = `    Pin ${pin.physical}: `;
+                const continuation = " ".repeat(visibleWidth(prefix));
+                lines.push(...wrapText(detail.join("; "), width, prefix, continuation));
+                detailCount += 1;
+            }
+        }
+        if (detailCount === 0) {
+            lines.push(...wrapText("No additional pin details.", width, "  ").map((line) => c.dim(line)));
+        }
     }
     lines.push("");
-    lines.push(c.dim(`Aliases: ${board.aliases.join(", ")}`));
-    lines.push(c.dim(`Pinout: ph ${board.id}`));
-    return lines.join("\n");
+    lines.push(...wrapText(`Aliases: ${board.aliases.join(", ") || "none"}`, width).map((line) => c.dim(line)));
+    lines.push(...wrapText(`Pinout: ph ${board.id}`, width).map((line) => c.dim(line)));
+    return finish(lines.join("\n"), opts);
 }

package/dist/render/text.d.ts

@@ -0,0 +1,22 @@
+export declare const MIN_TERMINAL_WIDTH = 20;
+export declare const MAX_TERMINAL_WIDTH = 1000;
+export declare const DEFAULT_TERMINAL_WIDTH = 80;
+/** Clamp externally detected widths to a usable, integer terminal width. */
+export declare function normalizeWidth(value: number | undefined, fallback?: number): number;
+/** Width in terminal cells, ignoring ANSI styling. */
+export declare function visibleWidth(text: string): number;
+export declare function padEndVisible(text: string, width: number): string;
+export declare function padStartVisible(text: string, width: number): string;
+/**
+ * Word-wrap text to terminal cells and hard-wrap long tokens such as URLs.
+ * The first and continuation prefixes may differ, which keeps warning markers
+ * aligned without accidentally adding columns after wrapping.
+ */
+export declare function wrapText(text: string, width: number, firstIndent?: string, continuationIndent?: string): string[];
+/** Remove terminal control sequences before echoing user-provided arguments. */
+export declare function safeTerminalText(text: string): string;
+/**
+ * Structural ASCII mode also sanitizes source data punctuation. Replacements
+ * stay at one cell so a width-safe render remains width-safe after conversion.
+ */
+export declare function toAscii(text: string): string;

package/dist/render/text.js

@@ -0,0 +1,163 @@
+import { stripVTControlCharacters } from "node:util";
+import stringWidth from "string-width";
+export const MIN_TERMINAL_WIDTH = 20;
+export const MAX_TERMINAL_WIDTH = 1000;
+export const DEFAULT_TERMINAL_WIDTH = 80;
+/** Clamp externally detected widths to a usable, integer terminal width. */
+export function normalizeWidth(value, fallback = DEFAULT_TERMINAL_WIDTH) {
+    if (value === undefined || !Number.isFinite(value) || value <= 0)
+        return fallback;
+    return Math.min(MAX_TERMINAL_WIDTH, Math.max(MIN_TERMINAL_WIDTH, Math.floor(value)));
+}
+/** Width in terminal cells, ignoring ANSI styling. */
+export function visibleWidth(text) {
+    return stringWidth(text);
+}
+export function padEndVisible(text, width) {
+    return text + " ".repeat(Math.max(0, width - visibleWidth(text)));
+}
+export function padStartVisible(text, width) {
+    return " ".repeat(Math.max(0, width - visibleWidth(text))) + text;
+}
+function splitAtWidth(text, width) {
+    if (width <= 0)
+        return ["", text];
+    let head = "";
+    let used = 0;
+    let offset = 0;
+    let preferredBreak = 0;
+    for (const character of text) {
+        const characterWidth = visibleWidth(character);
+        if (head && used + characterWidth > width)
+            break;
+        // A single wide glyph is preferable to an infinite loop at a one-cell edge.
+        if (!head && characterWidth > width) {
+            head = character;
+            offset += character.length;
+            break;
+        }
+        if (used + characterWidth > width)
+            break;
+        head += character;
+        used += characterWidth;
+        offset += character.length;
+        if (/[-/_.?&=]/.test(character))
+            preferredBreak = offset;
+    }
+    // Keep identifiers and URLs readable by preferring a nearby punctuation
+    // boundary over an arbitrary mid-token split.
+    if (offset < text.length && preferredBreak > 0) {
+        const preferredHead = text.slice(0, preferredBreak);
+        if (visibleWidth(preferredHead) >= Math.max(4, Math.floor(width / 2))) {
+            return [preferredHead, text.slice(preferredBreak)];
+        }
+    }
+    return [head, text.slice(offset)];
+}
+/**
+ * Word-wrap text to terminal cells and hard-wrap long tokens such as URLs.
+ * The first and continuation prefixes may differ, which keeps warning markers
+ * aligned without accidentally adding columns after wrapping.
+ */
+export function wrapText(text, width, firstIndent = "", continuationIndent = firstIndent) {
+    const targetWidth = Number.isFinite(width) ? Math.max(1, Math.floor(width)) : DEFAULT_TERMINAL_WIDTH;
+    const paragraphs = text.replace(/\r\n?/g, "\n").split("\n");
+    const output = [];
+    let firstOutputLine = true;
+    for (const paragraph of paragraphs) {
+        const words = paragraph.trim().split(/\s+/).filter(Boolean);
+        if (words.length === 0) {
+            output.push("");
+            firstOutputLine = false;
+            continue;
+        }
+        let indent = firstOutputLine ? firstIndent : continuationIndent;
+        let line = "";
+        const flush = () => {
+            if (!line)
+                return;
+            output.push(indent + line);
+            line = "";
+            firstOutputLine = false;
+            indent = continuationIndent;
+        };
+        for (const originalWord of words) {
+            let word = originalWord;
+            const available = () => Math.max(1, targetWidth - visibleWidth(indent));
+            if (line && visibleWidth(`${line} ${word}`) <= available()) {
+                line += ` ${word}`;
+                continue;
+            }
+            if (line)
+                flush();
+            while (visibleWidth(word) > available()) {
+                const [head, tail] = splitAtWidth(word, available());
+                line = head;
+                flush();
+                word = tail;
+            }
+            line = word;
+        }
+        flush();
+    }
+    return output;
+}
+/** Remove terminal control sequences before echoing user-provided arguments. */
+export function safeTerminalText(text) {
+    return Array.from(stripVTControlCharacters(text), (character) => {
+        const code = character.codePointAt(0) ?? 0;
+        return code <= 0x1f || code === 0x7f ? " " : character;
+    }).join("");
+}
+/**
+ * Structural ASCII mode also sanitizes source data punctuation. Replacements
+ * stay at one cell so a width-safe render remains width-safe after conversion.
+ */
+export function toAscii(text) {
+    const replacements = {
+        "—": "-",
+        "–": "-",
+        "−": "-",
+        "…": ".",
+        "×": "x",
+        "µ": "u",
+        "μ": "u",
+        "°": "o",
+        "→": ">",
+        "←": "<",
+        "↔": "-",
+        "≥": ">",
+        "≤": "<",
+        "“": "\"",
+        "”": "\"",
+        "‘": "'",
+        "’": "'",
+        "Ω": "O",
+        "ω": "o",
+        "·": ".",
+        " ": " ",
+    };
+    let output = "";
+    let inUnknownRun = false;
+    for (const character of text.normalize("NFKD")) {
+        if (replacements[character] !== undefined) {
+            output += replacements[character];
+            inUnknownRun = false;
+            continue;
+        }
+        const code = character.codePointAt(0) ?? 0;
+        if (code <= 0x7f) {
+            output += character;
+            inUnknownRun = false;
+            continue;
+        }
+        // Combining marks introduced by NFKD can be omitted; unknown glyphs remain
+        // visibly represented without breaking strict ASCII output.
+        if (/\p{Mark}/u.test(character))
+            continue;
+        if (!inUnknownRun)
+            output += "?";
+        inUnknownRun = true;
+    }
+    return output;
+}

package/dist/render/theme.js

@@ -1,6 +1,9 @@
 import { Chalk } from "chalk";
 export function makeChalk(colorEnabled) {
-    return new Chalk({ level: colorEnabled ? 3 : 0 });
+    // The palette uses only the portable 16-color range. Avoid emitting truecolor
+    // sequences merely because stdout is a TTY; older consoles can still render
+    // this level cleanly.
+    return new Chalk({ level: colorEnabled ? 1 : 0 });
 }
 /**
  * Category colors. Color is never the only signal: labels and category names

package/dist/run.d.ts

@@ -3,7 +3,7 @@ export type RunOptions = {
     columns?: number;
     /** Override TTY detection (piped output disables color automatically). */
     isTTY?: boolean;
-    /** Override environment (for NO_COLOR handling in tests). */
+    /** Override environment (for NO_COLOR/CI/TERM handling in tests). */
     env?: Record<string, string | undefined>;
 };
 export type RunResult = {
@@ -11,8 +11,10 @@ export type RunResult = {
     stdout: string;
     stderr: string;
 };
+export declare function parseWidth(value: string): number;
 /**
  * Runs the CLI against captured buffers instead of process streams, so the
- * whole command surface is testable without spawning child processes.
+ * whole command surface stays deterministic and testable. Executable-only
+ * motion lives in cli.ts and never enters these buffers.
  */
 export declare function runCli(argv: string[], runOpts?: RunOptions): Promise<RunResult>;

package/dist/run.js

@@ -1,57 +1,67 @@
-import { Command, CommanderError } from "commander";
+import { Command, CommanderError, InvalidArgumentError } from "commander";
 import { boards, resolveBoard, searchBoards, suggestBoards } from "./catalog.js";
 import { VERSION } from "./version.js";
 import { asciiChars, unicodeChars } from "./render/chars.js";
 import { makeChalk } from "./render/theme.js";
 import { renderBoard } from "./render/board.js";
 import { renderBoardTable, renderInfo, renderSources } from "./render/meta.js";
+import { MAX_TERMINAL_WIDTH, MIN_TERMINAL_WIDTH, normalizeWidth, safeTerminalText, } from "./render/text.js";
+import { hasNoColor, isCiEnvironment } from "./status.js";
+export function parseWidth(value) {
+    if (!/^\d+$/.test(value)) {
+        throw new InvalidArgumentError(`Invalid --width: expected a whole number from ${MIN_TERMINAL_WIDTH} to ${MAX_TERMINAL_WIDTH}.`);
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) ||
+        parsed < MIN_TERMINAL_WIDTH ||
+        parsed > MAX_TERMINAL_WIDTH) {
+        throw new InvalidArgumentError(`Invalid --width: expected a whole number from ${MIN_TERMINAL_WIDTH} to ${MAX_TERMINAL_WIDTH}.`);
+    }
+    return parsed;
+}
 /**
  * Runs the CLI against captured buffers instead of process streams, so the
- * whole command surface is testable without spawning child processes.
+ * whole command surface stays deterministic and testable. Executable-only
+ * motion lives in cli.ts and never enters these buffers.
  */
 export async function runCli(argv, runOpts = {}) {
     let stdout = "";
     let stderr = "";
     let code = 0;
     const print = (text) => {
-        stdout += text + "\n";
+        stdout += `${text}\n`;
     };
     const printErr = (text) => {
-        stderr += text + "\n";
+        stderr += `${text}\n`;
     };
     const env = runOpts.env ?? process.env;
     const isTTY = runOpts.isTTY ?? Boolean(process.stdout.isTTY);
-    const detectedColumns = runOpts.columns ?? (isTTY ? process.stdout.columns : undefined) ?? 80;
-    const colorEnabled = (flags) => flags.color !== false && !env.NO_COLOR && isTTY;
-    const buildRender = (flags) => {
-        let width = detectedColumns;
-        if (flags.width !== undefined) {
-            const parsed = Number.parseInt(flags.width, 10);
-            if (!Number.isFinite(parsed) || parsed < 40) {
-                return { error: "Invalid --width: expected a number of at least 40." };
-            }
-            width = parsed;
-        }
-        return {
-            chalk: makeChalk(colorEnabled(flags)),
-            chars: flags.ascii ? asciiChars : unicodeChars,
-            width,
-            compact: Boolean(flags.compact),
-        };
-    };
+    const detectedColumns = normalizeWidth(runOpts.columns ?? (isTTY ? process.stdout.columns : undefined));
+    const colorEnabled = (flags) => flags.color !== false &&
+        !hasNoColor(env) &&
+        !isCiEnvironment(env) &&
+        env.TERM?.toLowerCase() !== "dumb" &&
+        isTTY;
+    const buildRender = (flags) => ({
+        chalk: makeChalk(colorEnabled(flags)),
+        chars: flags.ascii ? asciiChars : unicodeChars,
+        width: flags.width ?? detectedColumns,
+        compact: Boolean(flags.compact),
+        details: Boolean(flags.details),
+    });
     const resolveOrSuggest = (words) => {
         const query = words.join(" ");
+        const displayQuery = safeTerminalText(query);
         const board = resolveBoard(query);
         if (board)
             return board;
-        printErr(`Board "${query}" was not found.`);
+        printErr(`Board "${displayQuery}" was not found.`);
         const suggestions = suggestBoards(query);
         if (suggestions.length > 0) {
             printErr("");
             printErr("Did you mean:");
-            for (const suggestion of suggestions) {
+            for (const suggestion of suggestions)
                 printErr(`  ph ${suggestion.alias}`);
-            }
         }
         printErr("");
         printErr("Run `ph list` to see all supported boards.");
@@ -68,25 +78,45 @@ export async function runCli(argv, runOpts = {}) {
             return;
         }
         const render = buildRender(flags);
-        if ("error" in render) {
-            printErr(render.error);
+        print(flags.source ? renderSources(board, render) : renderBoard(board, render));
+    };
+    const rejectIncompatibleFlags = (flags, scope) => {
+        if (scope === "multi-board" && flags.source) {
+            printErr("`--source` needs one board. Use `ph <board> --source`.");
             code = 1;
-            return;
+            return true;
         }
-        if (flags.source) {
-            print(renderSources(board, render.chalk));
-            return;
+        if (scope === "multi-board" && flags.details) {
+            printErr("`--details` needs one board. Use `ph <board> --details`.");
+            code = 1;
+            return true;
+        }
+        if (flags.source && flags.details) {
+            printErr("`--source` and `--details` are separate one-board views; choose one.");
+            code = 1;
+            return true;
+        }
+        const jsonConflicts = [
+            flags.ascii && "`--ascii`",
+            flags.compact && "`--compact`",
+            flags.details && "`--details`",
+            flags.source && "`--source`",
+            flags.width !== undefined && "`--width`",
+        ].filter((flag) => Boolean(flag));
+        if (flags.json && jsonConflicts.length > 0) {
+            printErr(`\`--json\` cannot be combined with ${jsonConflicts.join(", ")}.`);
+            code = 1;
+            return true;
         }
-        print(renderBoard(board, render));
+        return false;
     };
-    const metaChalk = (flags = {}) => makeChalk(colorEnabled(flags));
-    const metaChars = (flags = {}) => (flags.ascii ? asciiChars : unicodeChars);
     const program = new Command();
     program
         .name("ph")
         .description("Hardware board pinout diagrams in your terminal.")
         .version(VERSION, "-v, --version", "print the version")
         .helpCommand("help [command]", "display help for a command")
+        .showHelpAfterError("(add --help for usage)")
         .exitOverride()
         .configureOutput({
         writeOut: (text) => {
@@ -98,48 +128,63 @@ export async function runCli(argv, runOpts = {}) {
     })
         .argument("[board...]", "board id or alias (e.g. rpi5, pico, uno, esp32)")
         .option("--compact", "tighter, borderless layout")
-        .option("--ascii", "ASCII-only borders and symbols")
+        .option("--ascii", "ASCII-only output")
         .option("--no-color", "disable ANSI colors (the NO_COLOR env var is also honored)")
-        .option("--json", "emit the board data as JSON")
-        .option("--source", "print official source links for the board")
-        .option("--width <number>", "override the detected terminal width")
-        .addHelpText("after", "\nExamples:\n  ph rpi5\n  ph raspberry pi 5\n  ph pico --compact\n  ph esp32 --ascii --no-color\n  ph uno --json\n  ph rpi5 --source")
+        .option("--no-motion", "disable the interactive signal pulse")
+        .option("--details", "show additional alternate pin functions")
+        .option("--json", "emit machine-readable JSON")
+        .option("--source", "print documentation source links for one board")
+        .option("--width <columns>", `override terminal width (${MIN_TERMINAL_WIDTH}-${MAX_TERMINAL_WIDTH})`, parseWidth)
+        .addHelpText("after", "\nExamples:\n  ph rpi5\n  ph raspberry pi 5\n  ph pico --compact\n  ph esp32 --ascii --no-color\n  ph uno --details\n  ph uno --json\n  ph rpi5 --source\n  ph search raspberry")
         .action((words, flags) => {
         if (words.length === 0) {
             program.outputHelp();
             return;
         }
+        if (rejectIncompatibleFlags(flags, "single-board"))
+            return;
         showBoard(words, flags);
     });
     program
         .command("list")
         .description("list all boards in the catalog")
         .action(() => {
-        print(renderBoardTable(boards, metaChalk()));
+        const flags = program.opts();
+        if (rejectIncompatibleFlags(flags, "multi-board"))
+            return;
+        if (flags.json) {
+            print(JSON.stringify(boards, null, 2));
+            return;
+        }
+        print(renderBoardTable(boards, buildRender(flags)));
     });
     program
         .command("search <query...>")
         .description("search boards by name, alias, or manufacturer")
         .action((words) => {
+        const flags = program.opts();
+        if (rejectIncompatibleFlags(flags, "multi-board"))
+            return;
         const query = words.join(" ");
         const results = searchBoards(query);
         if (results.length === 0) {
-            printErr(`No boards matched "${query}". Run \`ph list\` to see all boards.`);
+            printErr(`No boards matched "${safeTerminalText(query)}". Run \`ph list\` to see all boards.`);
             code = 1;
             return;
         }
-        print(renderBoardTable(results, metaChalk()));
+        if (flags.json) {
+            print(JSON.stringify(results, null, 2));
+            return;
+        }
+        print(renderBoardTable(results, buildRender(flags)));
     });
     program
         .command("info <board...>")
         .description("show board details, warnings, sources, and aliases")
-        .option("--ascii", "ASCII-only symbols")
-        .option("--json", "emit the board data as JSON")
-        .action((words, localFlags, command) => {
-        // Flags like --json are also declared on the root command, which
-        // consumes them before dispatch; merge both option scopes.
-        const flags = command.optsWithGlobals();
-        void localFlags;
+        .action((words) => {
+        const flags = program.opts();
+        if (rejectIncompatibleFlags(flags, "single-board"))
+            return;
         const board = resolveOrSuggest(words);
         if (!board)
             return;
@@ -147,7 +192,8 @@ export async function runCli(argv, runOpts = {}) {
             print(JSON.stringify(board, null, 2));
             return;
         }
-        print(renderInfo(board, metaChalk(flags), metaChars(flags), detectedColumns));
+        const render = buildRender(flags);
+        print(flags.source ? renderSources(board, render) : renderInfo(board, render));
     });
     try {
         await program.parseAsync(argv, { from: "user" });