@skilly-hand/skilly-hand 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -16,6 +16,21 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.4.0] - 2026-04-03
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.4.0)
+
+### Added
+
+- `feat(core)`: Extract UI rendering into modular system — `ui/theme.js`, `ui/layout.js`, `ui/brand.js` — with a clean `ui/index.js` barrel export.
+- `feat(core)`: Multi-level color detection (`detectColorLevel`) supporting no-color, basic (16), 256-color, and truecolor environments.
+- `feat(cli)`: New renderer methods `banner()`, `detectionGrid()`, and `healthBadge()` built on the new UI modules.
+
+### Changed
+
+- `refactor(core)`: `terminal.js` restructured to delegate rendering to the new `ui/` modules; backward-compatible `style` object retained for existing tests.
+- `refactor(cli)`: `bin.js` simplified by extracting inline rendering into the new renderer methods.
+- `chore`: Added `/sandbox` to `.gitignore`.
+
 ## [0.3.0] - 2026-04-03
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.3.0)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "publishConfig": {

package/packages/cli/src/bin.js

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 import path from "node:path";
+import { createRequire } from "node:module";
 import { loadAllSkills } from "../../catalog/src/index.js";
 import { installProject, runDoctor, uninstallProject } from "../../core/src/index.js";
 import { createTerminalRenderer } from "../../core/src/terminal.js";
 import { detectProject } from "../../detectors/src/index.js";
 
+const require = createRequire(import.meta.url);
+const { version } = require("../../../package.json");
+
 const renderer = createTerminalRenderer();
 
 function parseArgs(argv) {
@@ -79,57 +83,13 @@ function buildHelpText() {
   ], { bullet: "-" }));
 
   return renderer.joinBlocks([
-    renderer.status("info", "skilly-hand", "Portable AI skill orchestration for coding assistants."),
+    renderer.banner(version),
     usage,
     flags,
     examples
   ]);
 }
 
-function detectionRows(detections) {
-  return detections.map((item) => ({
-    technology: item.technology,
-    confidence: item.confidence.toFixed(2),
-    reasons: item.reasons.join("; "),
-    recommended: item.recommendedSkillIds.join(", ")
-  }));
-}
-
-function renderDetections(detections) {
-  if (detections.length === 0) {
-    return renderer.status("warn", "No technology signals were detected.", "Only core skills will be selected.");
-  }
-
-  return renderer.table(
-    [
-      { key: "technology", header: "Technology" },
-      { key: "confidence", header: "Confidence" },
-      { key: "reasons", header: "Reasons" },
-      { key: "recommended", header: "Recommended Skills" }
-    ],
-    detectionRows(detections)
-  );
-}
-
-function renderSkillTable(skills) {
-  if (skills.length === 0) {
-    return renderer.status("warn", "No skills selected.");
-  }
-
-  return renderer.table(
-    [
-      { key: "id", header: "Skill ID" },
-      { key: "title", header: "Title" },
-      { key: "tags", header: "Tags" }
-    ],
-    skills.map((skill) => ({
-      id: skill.id,
-      title: skill.title,
-      tags: skill.tags.join(", ")
-    }))
-  );
-}
-
 function printInstallResult(result, flags) {
   const mode = flags.dryRun ? "dry-run" : "apply";
   const preflight = renderer.section(
@@ -144,8 +104,30 @@ function printInstallResult(result, flags) {
     ])
   );
 
-  const detections = renderer.section("Detected Technologies", renderDetections(result.plan.detections));
-  const skills = renderer.section("Skill Plan", renderSkillTable(result.plan.skills));
+  const detections = renderer.section(
+    "Detected Technologies",
+    result.plan.detections.length > 0
+      ? renderer.detectionGrid(result.plan.detections)
+      : renderer.status("warn", "No technology signals were detected.", "Only core skills will be selected.")
+  );
+
+  const skills = renderer.section(
+    "Skill Plan",
+    result.plan.skills.length > 0
+      ? renderer.table(
+          [
+            { key: "id", header: "Skill ID" },
+            { key: "title", header: "Title" },
+            { key: "tags", header: "Tags" }
+          ],
+          result.plan.skills.map((skill) => ({
+            id: skill.id,
+            title: skill.title,
+            tags: skill.tags.join(", ")
+          }))
+        )
+      : renderer.status("warn", "No skills selected.")
+  );
 
   const status = result.applied
     ? renderer.status("success", "Installation completed.", "Managed files and symlinks are in place.")
@@ -162,7 +144,7 @@ function printInstallResult(result, flags) {
       "Adjust `--include` and `--exclude` tags to tune skill selection."
     ]);
 
-  renderer.write(renderer.joinBlocks([preflight, detections, skills, status, nextSteps]));
+  renderer.write(renderer.joinBlocks([renderer.banner(version), preflight, detections, skills, status, nextSteps]));
 }
 
 function printDetectResult(cwd, detections) {
@@ -174,8 +156,14 @@ function printDetectResult(cwd, detections) {
     ])
   );
 
-  const details = renderer.section("Findings", renderDetections(detections));
-  renderer.write(renderer.joinBlocks([summary, details]));
+  const findings = renderer.section(
+    "Findings",
+    detections.length > 0
+      ? renderer.detectionGrid(detections)
+      : renderer.status("warn", "No technology signals were detected.", "Only core skills will be selected.")
+  );
+
+  renderer.write(renderer.joinBlocks([summary, findings]));
 }
 
 function printListResult(skills) {
@@ -206,9 +194,7 @@ function printListResult(skills) {
 }
 
 function printDoctorResult(result) {
-  const health = result.installed
-    ? renderer.status("success", "Installation detected.")
-    : renderer.status("warn", "No installation detected.");
+  const badge = renderer.healthBadge(result.installed);
 
   const summary = renderer.section(
     "Doctor Summary",
@@ -250,7 +236,7 @@ function printDoctorResult(result) {
     )
   );
 
-  renderer.write(renderer.joinBlocks([health, summary, lock, issues, probes]));
+  renderer.write(renderer.joinBlocks([badge, summary, lock, issues, probes]));
 }
 
 function printUninstallResult(result) {

package/packages/core/src/terminal.js

@@ -1,3 +1,5 @@
+import { detectColorLevel, createTheme, createLayout } from "./ui/index.js";
+
 const ANSI_PATTERN = /\x1b\[[0-9;]*m/g;
 
 function asString(value) {
@@ -22,6 +24,7 @@ function normalizeBooleanEnv(value) {
   return true;
 }
 
+// Kept as exported API (tests import these directly)
 export function detectColorSupport({ env = process.env, stream = process.stdout } = {}) {
   const noColor = normalizeBooleanEnv(env.NO_COLOR);
   if (noColor) return false;
@@ -45,63 +48,19 @@ export function detectUnicodeSupport({ env = process.env, stream = process.stdou
   return true;
 }
 
-function createStyler(enabled) {
-  if (!enabled) {
-    const passthrough = (value) => asString(value);
-    return {
-      reset: passthrough,
-      bold: passthrough,
-      dim: passthrough,
-      cyan: passthrough,
-      green: passthrough,
-      yellow: passthrough,
-      red: passthrough,
-      magenta: passthrough
-    };
-  }
-
-  const wrap = (code) => (value) => `\u001b[${code}m${asString(value)}\u001b[0m`;
-  return {
-    reset: wrap("0"),
-    bold: wrap("1"),
-    dim: wrap("2"),
-    cyan: wrap("36"),
-    green: wrap("32"),
-    yellow: wrap("33"),
-    red: wrap("31"),
-    magenta: wrap("35")
-  };
-}
-
-function renderKeyValue(entries, style) {
-  if (!entries || entries.length === 0) return "";
-  const normalized = entries.map(([key, value]) => [asString(key), asString(value)]);
-  const width = normalized.reduce((max, [key]) => Math.max(max, key.length), 0);
-  return normalized
-    .map(([key, value]) => `${style.dim(padEndAnsi(key, width))} : ${value}`)
-    .join("\n");
-}
-
-function renderList(items, { bullet }) {
-  if (!items || items.length === 0) return "";
-  return items.map((item) => `${bullet} ${asString(item)}`).join("\n");
-}
-
-function renderTable(columns, rows) {
+function renderPlainTable(columns, rows) {
   if (!columns || columns.length === 0) return "";
-  const header = columns.map((column) => column.header);
-  const matrix = [header, ...rows.map((row) => columns.map((column) => asString(row[column.key] ?? "")))];
-  const widths = header.map((_, index) =>
-    matrix.reduce((max, line) => Math.max(max, stripAnsi(line[index]).length), 0)
+  const header = columns.map((c) => c.header);
+  const matrix = [header, ...rows.map((row) => columns.map((c) => asString(row[c.key] ?? "")))];
+  const widths = header.map((_, i) =>
+    matrix.reduce((max, line) => Math.max(max, stripAnsi(line[i]).length), 0)
   );
-
-  const headerLine = header.map((value, index) => padEndAnsi(value, widths[index])).join("  ");
-  const separatorLine = widths.map((width) => "-".repeat(Math.max(3, width))).join("  ");
+  const headerLine = header.map((v, i) => padEndAnsi(v, widths[i])).join("  ");
+  const sepLine = widths.map((w) => "-".repeat(Math.max(3, w))).join("  ");
   const body = rows.map((row) =>
-    columns.map((column, index) => padEndAnsi(asString(row[column.key] ?? ""), widths[index])).join("  ")
+    columns.map((c, i) => padEndAnsi(asString(row[c.key] ?? ""), widths[i])).join("  ")
   );
-
-  return [headerLine, separatorLine, ...body].join("\n");
+  return [headerLine, sepLine, ...body].join("\n");
 }
 
 function joinBlocks(blocks) {
@@ -116,66 +75,114 @@ export function createTerminalRenderer({
   env = process.env,
   platform = process.platform
 } = {}) {
-  const colorEnabled = detectColorSupport({ env, stream: stdout });
+  const colorLevel = detectColorLevel({ env, stream: stdout });
+  const colorEnabled = colorLevel > 0;
   const unicodeEnabled = detectUnicodeSupport({ env, stream: stdout, platform });
-  const style = createStyler(colorEnabled);
+
+  const theme = createTheme(colorLevel);
+  const layout = createLayout(theme, unicodeEnabled);
+
+  // Backward-compat style object (callers in tests may use renderer.style.*)
+  const style = {
+    reset:   (v) => asString(v),
+    bold:    theme.bold,
+    dim:     theme.dim,
+    cyan:    theme.primary,
+    green:   theme.success,
+    yellow:  theme.warn,
+    red:     theme.error,
+    magenta: theme.magenta,
+  };
+
   const symbols = unicodeEnabled
     ? { info: "i", success: "✓", warn: "!", error: "x", bullet: "•", section: "■" }
     : { info: "i", success: "+", warn: "!", error: "x", bullet: "-", section: "#" };
 
   const statusStyles = {
-    info: style.cyan,
-    success: style.green,
-    warn: style.yellow,
-    error: style.red
+    info:    theme.info,
+    success: theme.success,
+    warn:    theme.warn,
+    error:   theme.error,
   };
 
   const renderer = {
     colorEnabled,
+    colorLevel,
     unicodeEnabled,
     symbols,
     style,
+    theme,
+
     json(value) {
       return JSON.stringify(value, null, 2);
     },
+
     section(title, body = "") {
-      const heading = `${style.cyan(symbols.section)} ${style.bold(asString(title))}`;
+      const heading = layout.sectionHeader(title);
       const bodyText = asString(body).trimEnd();
       return bodyText ? `${heading}\n${bodyText}` : heading;
     },
+
     kv(entries) {
-      return renderKeyValue(entries, style);
+      return layout.kvPanel(entries);
     },
+
     list(items, options = {}) {
-      return renderList(items, { bullet: options.bullet || symbols.bullet });
+      if (!items || items.length === 0) return "";
+      const bullet = options.bullet || symbols.bullet;
+      return items.map((item) => `${bullet} ${asString(item)}`).join("\n");
     },
+
     table(columns, rows) {
-      return renderTable(columns, rows);
+      // Use bordered table when unicode is on; fall back to plain
+      if (unicodeEnabled) {
+        return layout.borderedTable(columns, rows);
+      }
+      return renderPlainTable(columns, rows);
     },
+
     status(level, message, detail = "") {
-      const applied = statusStyles[level] || ((value) => value);
+      const applied = statusStyles[level] || ((v) => v);
       const icon = symbols[level] || symbols.info;
       const main = `${applied(icon)} ${asString(message)}`;
       if (!detail) return main;
-      return `${main}\n${style.dim("  " + asString(detail))}`;
+      return `${main}\n${theme.dim("  " + asString(detail))}`;
     },
+
     summary(title, items = []) {
       return renderer.section(title, renderer.list(items));
     },
+
     nextSteps(steps = []) {
       if (!steps.length) return "";
       return renderer.section("Next Steps", renderer.list(steps));
     },
+
     error({ what = "Command failed", why = "", hint = "", exitCode = 1 } = {}) {
       const blocks = [
         renderer.status("error", what),
-        why ? renderer.kv([["Why", why]]) : "",
-        hint ? renderer.kv([["How to recover", hint]]) : "",
+        why  ? renderer.kv([["Why", why]])                : "",
+        hint ? renderer.kv([["How to recover", hint]])   : "",
         renderer.kv([["Exit code", asString(exitCode)]])
       ];
       return joinBlocks(blocks);
     },
-    joinBlocks
+
+    // ── New visual methods ─────────────────────────────────────────────────
+
+    banner(version) {
+      return layout.banner(version);
+    },
+
+    detectionGrid(detections) {
+      return layout.detectionGrid(detections);
+    },
+
+    healthBadge(installed) {
+      return layout.healthBadge(installed);
+    },
+
+    joinBlocks,
   };
 
   return {
@@ -191,6 +198,6 @@ export function createTerminalRenderer({
     },
     writeErrorJson(value) {
       stderr.write(`${renderer.json(value)}\n`);
-    }
+    },
   };
 }

package/packages/core/src/ui/brand.js

@@ -0,0 +1,31 @@
+// Brand identity: SK logo, app name, tagline.
+
+// Unicode block-letter "SK" — 5 rows, uses FULL BLOCK (U+2588) and LOWER HALF BLOCK (U+2584)
+const LOGO_UNICODE = [
+  " \u2588\u2588\u2588\u2588  \u2588\u2588  \u2588\u2588",
+  "\u2588\u2588      \u2588\u2588  \u2588\u2588",
+  " \u2588\u2588\u2588\u2588  \u2588\u2588\u2588\u2588\u2588\u2588",
+  "    \u2588\u2588  \u2588\u2588  \u2588\u2588",
+  " \u2588\u2588\u2588\u2588  \u2588\u2588  \u2588\u2588",
+];
+
+// ASCII fallback — 5 rows, same shape using pipe/underscore
+const LOGO_ASCII = [
+  " ____  _  _",
+  "/___   |//",
+  " ___/  |--\\",
+  "    |  |  \\",
+  " ___|  |   \\",
+];
+
+export function getBrand() {
+  return {
+    name: "autoskills",
+    tagline: "portable AI skill orchestration",
+    hint: "npx skilly-hand --help",
+    logo: {
+      unicode: LOGO_UNICODE,
+      ascii: LOGO_ASCII,
+    },
+  };
+}

package/packages/core/src/ui/index.js

@@ -0,0 +1,3 @@
+export { detectColorLevel, createTheme } from "./theme.js";
+export { getBrand } from "./brand.js";
+export { createLayout } from "./layout.js";

package/packages/core/src/ui/layout.js

@@ -0,0 +1,289 @@
+// Layout primitives: banner, section headers, bordered tables, detection grid, health badge.
+
+import { getBrand } from "./brand.js";
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+function stripAnsi(value) {
+  return String(value).replace(ANSI_RE, "");
+}
+
+function visLen(value) {
+  return stripAnsi(value).length;
+}
+
+function padEnd(value, width) {
+  const len = visLen(value);
+  if (len >= width) return value;
+  return value + " ".repeat(width - len);
+}
+
+function padStart(value, width) {
+  const len = visLen(value);
+  if (len >= width) return value;
+  return " ".repeat(width - len) + value;
+}
+
+function truncate(value, maxWidth) {
+  const clean = stripAnsi(value);
+  if (clean.length <= maxWidth) return value;
+  return clean.slice(0, maxWidth - 1) + "…";
+}
+
+// Box character sets
+const BOX = {
+  // double-line outer (for banner)
+  d: {
+    tl: "╔", tr: "╗", bl: "╚", br: "╝",
+    h: "═", v: "║",
+    ml: "╠", mr: "╣",
+  },
+  // single-line inner (for tables and sections)
+  s: {
+    tl: "┌", tr: "┐", bl: "└", br: "┘",
+    h: "─", v: "│",
+    ml: "├", mr: "┤",
+    mt: "┬", mb: "┴", x: "┼",
+    // double-separator row (header separator in tables)
+    dh: "═",
+    dl: "╞", dr: "╡", dc: "╪",
+  },
+};
+
+// ASCII fallback chars
+const BOX_ASCII = {
+  d: { tl: "+", tr: "+", bl: "+", br: "+", h: "=", v: "|", ml: "+", mr: "+" },
+  s: {
+    tl: "+", tr: "+", bl: "+", br: "+",
+    h: "-", v: "|",
+    ml: "+", mr: "+", mt: "+", mb: "+", x: "+",
+    dh: "=", dl: "+", dr: "+", dc: "+",
+  },
+};
+
+export function createLayout(theme, unicodeEnabled) {
+  const box = unicodeEnabled ? BOX : BOX_ASCII;
+  const brand = getBrand();
+
+  // ── Banner ────────────────────────────────────────────────────────────────
+
+  function banner(version) {
+    const logo = unicodeEnabled ? brand.logo.unicode : brand.logo.ascii;
+    const innerW = 56; // inner content width (excluding border chars)
+
+    const nameStr = brand.name;
+    const versionStr = version ? `  v${version}` : "";
+    const taglineStr = brand.tagline;
+    const hintStr = brand.hint;
+
+    // right column content
+    const rightLines = [
+      theme.bold(theme.accent(nameStr)) + theme.muted(versionStr),
+      theme.muted(taglineStr),
+      "",
+      "",
+      "",
+    ];
+
+    const logoW = Math.max(...logo.map((l) => stripAnsi(l).length));
+    const gap = 3;
+    const rightW = innerW - logoW - gap - 2; // 2 for leading spaces
+
+    const d = box.d;
+    const hLine = d.h.repeat(innerW + 2); // +2 for padding spaces inside border
+
+    const rows = logo.map((logoLine, i) => {
+      const logoColored = theme.primary(theme.bold(logoLine));
+      const rightLine = rightLines[i] || "";
+      const logoLen = logoW;
+      const logoPadded = padEnd(logoColored, logoLen + (visLen(logoColored) - stripAnsi(logoColored).length));
+      const rightPadded = padEnd(rightLine, rightW);
+      const content = "  " + logoPadded + " ".repeat(gap) + rightPadded;
+      const contentVis = visLen(content);
+      const totalW = innerW + 2;
+      const paddingNeeded = Math.max(0, totalW - contentVis);
+      return d.v + content + " ".repeat(paddingNeeded) + d.v;
+    });
+
+    // separator row between logo area and hint
+    const sepRow = d.ml + d.h.repeat(innerW + 2) + d.mr;
+
+    const hintContent = "  " + theme.muted(hintStr);
+    const hintVis = visLen(hintContent);
+    const hintPad = Math.max(0, innerW + 2 - hintVis);
+    const hintRow = d.v + hintContent + " ".repeat(hintPad) + d.v;
+
+    const lines = [
+      d.tl + hLine + d.tr,
+      ...rows,
+      sepRow,
+      hintRow,
+      d.bl + hLine + d.br,
+    ];
+
+    return lines.join("\n");
+  }
+
+  // ── Section header ────────────────────────────────────────────────────────
+
+  function sectionHeader(title) {
+    if (!unicodeEnabled) {
+      return theme.bold(title);
+    }
+    const s = box.s;
+    const decorated = theme.primary(s.tl) + theme.primary(s.h.repeat(2)) + " " + theme.bold(title) + " " + theme.primary(s.h.repeat(Math.max(2, 40 - title.length)));
+    return decorated;
+  }
+
+  // ── Bordered table ────────────────────────────────────────────────────────
+
+  function borderedTable(columns, rows, opts = {}) {
+    if (!columns || columns.length === 0) return "";
+    const maxColW = opts.maxColWidth || 36;
+
+    const headers = columns.map((c) => String(c.header));
+    const matrix = rows.map((row) =>
+      columns.map((c) => truncate(String(row[c.key] ?? ""), maxColW))
+    );
+
+    // Compute column widths
+    const widths = headers.map((h, i) => {
+      const contentMax = matrix.reduce((m, row) => Math.max(m, visLen(row[i])), 0);
+      return Math.max(visLen(h), contentMax, 3);
+    });
+
+    if (!unicodeEnabled) {
+      // Plain fallback — original table style
+      const headerLine = headers.map((h, i) => padEnd(h, widths[i])).join("  ");
+      const sepLine = widths.map((w) => "-".repeat(w)).join("  ");
+      const bodyLines = matrix.map((row) =>
+        row.map((cell, i) => padEnd(cell, widths[i])).join("  ")
+      );
+      return [headerLine, sepLine, ...bodyLines].join("\n");
+    }
+
+    const s = box.s;
+
+    function makeRow(cells, widths, leftC, midC, rightC, padChar = " ") {
+      const inner = cells.map((cell, i) => padChar + padEnd(cell, widths[i]) + padChar).join(midC);
+      return leftC + inner + rightC;
+    }
+
+    function makeDivider(widths, leftC, midC, rightC, fillC) {
+      const inner = widths.map((w) => fillC.repeat(w + 2)).join(midC);
+      return leftC + inner + rightC;
+    }
+
+    const topBorder    = makeDivider(widths, s.tl, s.mt, s.tr, s.h);
+    const headerRow    = makeRow(headers.map((h, i) => theme.bold(h)), widths, theme.primary(s.v), theme.primary(s.v), theme.primary(s.v));
+    const headerSep    = makeDivider(widths, s.dl, s.dc, s.dr, s.dh);
+    const bodyRows     = matrix.map((row) =>
+      makeRow(
+        row.map((cell, i) => {
+          // color first column (usually ID) with accent
+          return i === 0 ? theme.accent(cell) : cell;
+        }),
+        widths, theme.primary(s.v), theme.primary(s.v), theme.primary(s.v)
+      )
+    );
+    const bottomBorder = makeDivider(widths, s.bl, s.mb, s.br, s.h);
+
+    // Apply primary color to border chars
+    const colorBorder = (line) => {
+      // Replace non-letter/space chars with colored versions
+      return theme.primary(line);
+    };
+
+    return [
+      colorBorder(topBorder),
+      headerRow,
+      colorBorder(headerSep),
+      ...bodyRows,
+      colorBorder(bottomBorder),
+    ].join("\n");
+  }
+
+  // ── Detection grid ────────────────────────────────────────────────────────
+
+  function detectionGrid(detections) {
+    if (!detections || detections.length === 0) {
+      return theme.warn("! No technology signals detected.");
+    }
+
+    const COLS = 3;
+    const COL_W = 20;
+
+    function icon(confidence) {
+      if (unicodeEnabled) {
+        if (confidence >= 0.85) return theme.success("✔");
+        if (confidence >= 0.70) return theme.primary("◆");
+        return theme.warn("⚠");
+      }
+      if (confidence >= 0.85) return theme.success("[+]");
+      if (confidence >= 0.70) return theme.primary("[-]");
+      return theme.warn("[!]");
+    }
+
+    function colorTech(tech, confidence) {
+      if (confidence >= 0.85) return theme.success(tech);
+      if (confidence >= 0.70) return theme.primary(tech);
+      return theme.warn(tech);
+    }
+
+    const cells = detections.map((d) => {
+      const pct = Math.round(d.confidence * 100) + "%";
+      const ic = icon(d.confidence);
+      const name = colorTech(d.technology, d.confidence);
+      const pctStr = theme.muted(pct);
+      // visual: "✔ React        95%"
+      return ic + " " + padEnd(name, COL_W - 5) + " " + padEnd(pctStr, 4);
+    });
+
+    const rows = [];
+    for (let i = 0; i < cells.length; i += COLS) {
+      rows.push(cells.slice(i, i + COLS).join("   "));
+    }
+
+    return rows.join("\n");
+  }
+
+  // ── Health badge ──────────────────────────────────────────────────────────
+
+  function healthBadge(installed) {
+    if (unicodeEnabled) {
+      if (installed) {
+        const badge = theme.success(theme.bold("██ HEALTHY"));
+        const line = theme.primary(" ─────────────────────────────────");
+        return badge + line;
+      }
+      const badge = theme.warn(theme.bold("██ NOT INSTALLED"));
+      const line = theme.muted(" ─────────────────────────────────");
+      return badge + line;
+    }
+
+    if (installed) {
+      return theme.success(theme.bold("[OK] Installation healthy"));
+    }
+    return theme.warn(theme.bold("[!!] Not installed"));
+  }
+
+  // ── Key-value panel ───────────────────────────────────────────────────────
+
+  function kvPanel(entries) {
+    if (!entries || entries.length === 0) return "";
+    const normalized = entries.map(([k, v]) => [String(k), String(v)]);
+    const width = normalized.reduce((max, [k]) => Math.max(max, k.length), 0);
+    return normalized
+      .map(([k, v]) => `${theme.muted(padEnd(k, width))} : ${v}`)
+      .join("\n");
+  }
+
+  return {
+    banner,
+    sectionHeader,
+    borderedTable,
+    detectionGrid,
+    healthBadge,
+    kvPanel,
+  };
+}

package/packages/core/src/ui/theme.js

@@ -0,0 +1,120 @@
+// Color level detection and palette creation.
+// Level 0: no color  Level 1: basic ANSI  Level 2: 256-color  Level 3: truecolor
+
+function normalizeBooleanEnv(value) {
+  if (value === undefined || value === null) return null;
+  const normalized = String(value).trim().toLowerCase();
+  if (normalized === "" || normalized === "0" || normalized === "false" || normalized === "no") return false;
+  return true;
+}
+
+export function detectColorLevel({ env = process.env, stream = process.stdout } = {}) {
+  if (normalizeBooleanEnv(env.NO_COLOR)) return 0;
+
+  const force = env.FORCE_COLOR;
+  if (force !== undefined) {
+    const level = parseInt(force, 10);
+    if (!isNaN(level)) return Math.min(Math.max(level, 0), 3);
+    if (normalizeBooleanEnv(force) === true) return 1;
+    if (normalizeBooleanEnv(force) === false) return 0;
+  }
+
+  if (!stream?.isTTY) return 0;
+  if (env.CI) return 0;
+
+  const colorterm = (env.COLORTERM || "").toLowerCase();
+  if (colorterm === "truecolor" || colorterm === "24bit") return 3;
+
+  const term = env.TERM || "";
+  const termProgram = env.TERM_PROGRAM || "";
+  if (term.includes("256color") || termProgram === "iTerm.app" || termProgram === "vscode") return 2;
+
+  return 1;
+}
+
+// ANSI wrap helpers
+function wrapBasic(code) {
+  return (value) => `\x1b[${code}m${String(value)}\x1b[0m`;
+}
+function wrap256(code) {
+  return (value) => `\x1b[38;5;${code}m${String(value)}\x1b[0m`;
+}
+function wrapRgb(r, g, b) {
+  return (value) => `\x1b[38;2;${r};${g};${b}m${String(value)}\x1b[0m`;
+}
+function wrapBg256(code) {
+  return (value) => `\x1b[48;5;${code}m${String(value)}\x1b[0m`;
+}
+function wrapBgRgb(r, g, b) {
+  return (value) => `\x1b[48;2;${r};${g};${b}m${String(value)}\x1b[0m`;
+}
+
+const PALETTE = {
+  primary: { l3: [0, 184, 169],   l2: 38,  l1: 36  },
+  accent:  { l3: [77, 208, 225],  l2: 51,  l1: 36  },
+  muted:   { l3: [0, 150, 136],   l2: 30,  l1: 2   },
+  success: { l3: [80, 200, 120],  l2: 40,  l1: 32  },
+  warn:    { l3: [255, 185, 0],   l2: 214, l1: 33  },
+  error:   { l3: [240, 80, 80],   l2: 196, l1: 31  },
+  info:    { l3: [60, 130, 220],  l2: 33,  l1: 34  },
+  magenta: { l3: [200, 100, 200], l2: 141, l1: 35  },
+};
+
+const PALETTE_BG = {
+  primary: { l3: [0, 184, 169],   l2: 38  },
+  success: { l3: [40, 140, 80],   l2: 28  },
+  warn:    { l3: [160, 100, 0],   l2: 136 },
+  error:   { l3: [160, 40, 40],   l2: 124 },
+};
+
+const identity = (value) => String(value);
+
+export function createTheme(level) {
+  if (level === 0) {
+    const noop = identity;
+    return {
+      level,
+      primary: noop, accent: noop, muted: noop,
+      success: noop, warn: noop, error: noop, info: noop, magenta: noop,
+      bold: noop, dim: noop, reset: noop, italic: noop,
+      bgPrimary: noop, bgSuccess: noop, bgWarn: noop, bgError: noop,
+    };
+  }
+
+  function makeColor(slot) {
+    const p = PALETTE[slot];
+    if (level === 3) return wrapRgb(...p.l3);
+    if (level === 2) return wrap256(p.l2);
+    // level 1: muted is dim, rest are basic codes
+    if (slot === "muted") return wrapBasic(2);
+    return wrapBasic(p.l1);
+  }
+
+  function makeBg(slot) {
+    const p = PALETTE_BG[slot];
+    if (!p) return identity;
+    if (level === 3) return wrapBgRgb(...p.l3);
+    if (level === 2) return wrapBg256(p.l2);
+    return identity;
+  }
+
+  return {
+    level,
+    primary:   makeColor("primary"),
+    accent:    makeColor("accent"),
+    muted:     makeColor("muted"),
+    success:   makeColor("success"),
+    warn:      makeColor("warn"),
+    error:     makeColor("error"),
+    info:      makeColor("info"),
+    magenta:   makeColor("magenta"),
+    bold:      wrapBasic(1),
+    dim:       wrapBasic(2),
+    italic:    wrapBasic(3),
+    reset:     wrapBasic(0),
+    bgPrimary: makeBg("primary"),
+    bgSuccess: makeBg("success"),
+    bgWarn:    makeBg("warn"),
+    bgError:   makeBg("error"),
+  };
+}