@pi-unipi/unipi 2.0.4 → 2.0.5

package/README.md

@@ -27,7 +27,7 @@ pi install npm:@pi-unipi/unipi
 
 **[Notify](./packages/notify/README.md)** — Push notifications to native OS, Gotify, Telegram, or ntfy. Per-event platform routing plus native focus suppression so alerts can stay quiet while Pi is already focused.
 
-**[Footer](./packages/footer/README.md)** — Persistent status bar showing live stats from every package. Responsive layout, presets, per-segment toggling.
+**[Footer](./packages/footer/README.md)** — Persistent status bar showing live stats from every package. Responsive layout, presets, per-segment toggling, and terminal-aware color fallback.
 
 **[BTW](./packages/btw/README.md)** — Side conversations that run in parallel. Ask questions without interrupting the main agent.
 
@@ -45,7 +45,7 @@ pi install npm:@pi-unipi/unipi
 
 **[Input Shortcuts](./packages/input-shortcuts/README.md)** — Keyboard shortcuts via vim-style chord overlay. Stash/restore, undo/redo, clipboard, thinking toggle.
 
-**[Command Enchantment](./packages/autocomplete/README.md)** — Enhanced `/unipi:*` autocomplete with package grouping, descriptions, colors, and registry audits that catch stale command docs before release.
+**[Command Enchantment](./packages/autocomplete/README.md)** — Enhanced `/unipi:*` autocomplete with full command names, package tags, descriptions, colors, and registry audits that catch stale command docs before release.
 
 ## Architecture
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/unipi",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "All-in-one extension suite for Pi coding agent",
   "type": "module",
   "license": "MIT",

package/packages/autocomplete/README.md

@@ -9,6 +9,7 @@ Command Enchantment has no user commands. It improves the editor autocomplete ex
 ## What It Does
 
 - Groups `/unipi:*` commands by package so workflow, memory, web, footer, and other commands are visually distinct.
+- Shows full command values like `unipi:brainstorm` while replacing Pi source tags with concise package tags like `[workflow]`.
 - Sorts matches in predictable tiers: exact Unipi matches first, then other Unipi matches, then system commands.
 - Preserves dynamic argument completions from command providers, including workflow document and worktree suggestions.
 - Ships an audit test that checks registered Unipi commands are represented in the autocomplete registry and have descriptions.

package/packages/autocomplete/src/provider.ts

@@ -43,6 +43,18 @@ function fuzzyMatch(text: string, query: string): boolean {
 
 // ─── Namespace detection ─────────────────────────────────────────────
 
+/**
+ * Pi prefixes extension command descriptions with source tags such as
+ * `[u:npm:@pi-unipi/unipi]`. The enchanted provider replaces that with
+ * package tags (`[workflow]`, `[memory]`, …), so strip the source tag from
+ * base descriptions before reusing them.
+ */
+function stripPiSourceTag(description: string): string {
+  return description
+    .replace(/^\[(?:[upt])(?::[^\]]+)?\]\s*/, "")
+    .trimStart();
+}
+
 /**
  * If the query looks like a package namespace (e.g. "workflow", "memory",
  * "utility"), return that package name so its commands sort to the top.
@@ -174,7 +186,7 @@ function getEnhancedUnipiItems(
 
     return {
       value: cmd,
-      label: cmd.replace("unipi:", ""),
+      label: cmd,
       description: desc ? `${tag} ${desc}` : tag,
     };
   });
@@ -261,7 +273,10 @@ export function createEnchantedProvider(
         for (const item of baseSuggestions.items) {
           if (item.value.startsWith("unipi:")) {
             if (item.description) {
-              descriptionOverrides.set(item.value, item.description);
+              const cleanDescription = stripPiSourceTag(item.description);
+              if (cleanDescription) {
+                descriptionOverrides.set(item.value, cleanDescription);
+              }
             }
           } else {
             nonUnipiItems.push(item);

package/packages/footer/README.md

@@ -69,6 +69,7 @@ Settings in `~/.pi/agent/settings.json` under `unipi.footer`:
       "preset": "default",
       "separator": "powerline-thin",
       "iconStyle": "nerd",
+      "colorMode": "auto",
       "groups": {
         "compactor": {
           "show": true,
@@ -105,6 +106,17 @@ Settings in `~/.pi/agent/settings.json` under `unipi.footer`:
 
 When `iconStyle` is not set, footer auto-detects Nerd Font support and defaults to `nerd` if available, `emoji` otherwise.
 
+### Color Mode
+
+| Mode | Description |
+|------|-------------|
+| `auto` | Detect terminal support from environment (default) |
+| `truecolor` | Force 24-bit ANSI color |
+| `256` | Force xterm-256 color fallback |
+| `none` | Disable footer color escapes |
+
+`auto` uses truecolor where supported and downgrades to xterm-256 colors for terminals such as Apple Terminal that do not reliably render 24-bit color escapes.
+
 ### Responsive Layout
 
 ```

package/packages/footer/src/config.ts

@@ -8,7 +8,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
-import type { FooterSettings, FooterGroupSettings, SeparatorStyle, IconStyle } from "./types.js";
+import type { FooterSettings, FooterGroupSettings, SeparatorStyle, IconStyle, ColorMode } from "./types.js";
 import { UNIPI_SETTINGS_KEY } from "@pi-unipi/core";
 
 /** Default footer settings */
@@ -19,6 +19,7 @@ export const DEFAULT_FOOTER_SETTINGS: FooterSettings = {
   iconStyle: "nerd",
   zoneSeparator: "\u2502", // │
   showFullLabels: false,
+  colorMode: "auto",
   groups: {
     core: { show: true, segments: {} },
     compactor: { show: true, segments: {} },
@@ -96,6 +97,7 @@ export function loadFooterSettings(): FooterSettings {
       iconStyle: isValidIconStyle(footer.iconStyle) ? footer.iconStyle as IconStyle : DEFAULT_FOOTER_SETTINGS.iconStyle,
       zoneSeparator: typeof footer.zoneSeparator === "string" ? footer.zoneSeparator : DEFAULT_FOOTER_SETTINGS.zoneSeparator,
       showFullLabels: typeof footer.showFullLabels === "boolean" ? footer.showFullLabels : DEFAULT_FOOTER_SETTINGS.showFullLabels,
+      colorMode: isValidColorMode(footer.colorMode) ? footer.colorMode as ColorMode : DEFAULT_FOOTER_SETTINGS.colorMode,
       groups: mergeGroupSettings(
         DEFAULT_FOOTER_SETTINGS.groups,
         footer.groups as Record<string, FooterGroupSettings> | undefined,
@@ -170,6 +172,12 @@ function isValidIconStyle(value: unknown): boolean {
   return valid.includes(value);
 }
 
+function isValidColorMode(value: unknown): boolean {
+  if (typeof value !== "string") return false;
+  const valid: string[] = ["auto", "truecolor", "256", "none"];
+  return valid.includes(value);
+}
+
 function mergeGroupSettings(
   defaults: Record<string, FooterGroupSettings>,
   overrides: Record<string, FooterGroupSettings> | undefined,

package/packages/footer/src/rendering/renderer.ts

@@ -11,7 +11,7 @@ import type { PresetDef, FooterSegmentContext, FooterSegment, ColorScheme, Rende
 import type { FooterRegistry } from "../registry/index.js";
 import { visibleWidth as piVisibleWidth, truncateToWidth } from "@mariozechner/pi-tui";
 import { getSeparator, separatorVisibleWidth } from "./separators.js";
-import { getDefaultColors } from "./theme.js";
+import { getDefaultColors, setColorMode, refreshColorMode } from "./theme.js";
 import { setIconStyle } from "./icons.js";
 import { getPreset } from "../presets.js";
 import { isSegmentEnabled, isSegmentExplicitlyEnabled, loadFooterSettings } from "../config.js";
@@ -104,6 +104,19 @@ export class FooterRenderer {
   private syncIconStyle(): void {
     const settings = loadFooterSettings();
     setIconStyle(settings.iconStyle);
+    this.syncColorMode(settings);
+  }
+
+  /** Sync the colour-emission mode from settings to the theme module. */
+  private syncColorMode(settings?: ReturnType<typeof loadFooterSettings>): void {
+    const s = settings ?? loadFooterSettings();
+    const mode = s.colorMode ?? "auto";
+    if (mode === "auto") {
+      setColorMode(null);
+      refreshColorMode();
+    } else {
+      setColorMode(mode);
+    }
   }
 
   /** Get the active preset name */

package/packages/footer/src/rendering/theme.ts

@@ -3,11 +3,174 @@
  *
  * Maps semantic color names to pi theme colors. Supports
  * hex overrides via ColorScheme.
+ *
+ * Color emission is capability-aware: hex values are emitted as 24-bit
+ * truecolor on terminals that advertise truecolor (COLORTERM or known
+ * truecolor TERM_PROGRAM), and gracefully downgraded to the nearest
+ * xterm-256 index on legacy terminals (notably Apple Terminal.app, which
+ * silently swallows 24-bit escapes and renders the text uncoloured).
  */
 
 import type { Theme, ThemeColor } from "@mariozechner/pi-coding-agent";
 import type { ColorScheme, ColorValue, SemanticColor, ThemeLike } from "../types.js";
 
+// ─── Color mode detection ──────────────────────────────────────────────────
+
+/**
+ * Detected colour-emission mode for the current terminal.
+ *  - `truecolor` → emit 24-bit `\x1b[38;2;R;G;Bm`
+ *  - `256`       → emit 8-bit  `\x1b[38;5;Nm` (nearest xterm-256 index)
+ *  - `none`      → emit no colour codes (plain text)
+ */
+export type ColorMode = "truecolor" | "256" | "none";
+
+/** Manual override (set via `setColorMode`) — wins over env-based detection. */
+let manualMode: ColorMode | null = null;
+/** Cached detection result; cleared by `refreshColorMode()`. */
+let detectedMode: ColorMode | null = null;
+
+/** Terminals known to honour 24-bit truecolor escapes. */
+const TRUECOLOR_TERM_PROGRAMS = [
+  "iTerm.app",
+  "WezTerm",
+  "Alacritty",
+  "vscode",
+  "Hyper",
+  "Warp",
+  "ghostty",
+  "Ghostty",
+  "zed",
+  "Zed",
+  "cursor",
+  "Cursor",
+];
+
+/**
+ * Detect the colour mode of the current terminal from environment.
+ * Respects `NO_COLOR`, `FORCE_COLOR`, then sniffs `COLORTERM` / `TERM_PROGRAM`
+ * / `TERM`. Apple Terminal is explicitly capped at 256-colour.
+ */
+function detectColorMode(): ColorMode {
+  const env = process.env;
+  if (env.NO_COLOR || env.NODE_DISABLE_COLORS) return "none";
+  if (env.FORCE_COLOR) {
+    const lvl = parseInt(env.FORCE_COLOR, 10);
+    if (Number.isNaN(lvl)) return "truecolor"; // any non-numeric truthy value
+    if (lvl >= 3) return "truecolor";
+    if (lvl >= 1) return "256";
+    return "none";
+  }
+  const term = env.TERM ?? "";
+  const termProgram = env.TERM_PROGRAM ?? "";
+  // Apple Terminal.app does NOT support 24-bit colour. Force 256 even if
+  // some wrapper leaked COLORTERM into the env.
+  if (termProgram === "Apple_Terminal") {
+    return "256";
+  }
+  if (env.COLORTERM === "truecolor" || env.COLORTERM === "24bit") {
+    return "truecolor";
+  }
+  if (TRUECOLOR_TERM_PROGRAMS.includes(termProgram)) {
+    return "truecolor";
+  }
+  if (term === "dumb") return "none";
+  // Anything that talks ANSI but isn't known-truecolor → 256
+  if (term.includes("256color") || term.includes("color") || term.includes("xterm") || term.includes("ansi") || term.includes("screen") || term.includes("tmux")) {
+    return "256";
+  }
+  // Default conservative: 256 colour. Better than dropping colours entirely
+  // on unknown terminals that almost certainly understand the 256 palette.
+  return "256";
+}
+
+/**
+ * Get the active colour mode (manual override > cached detection > env probe).
+ */
+export function getColorMode(): ColorMode {
+  if (manualMode) return manualMode;
+  if (!detectedMode) detectedMode = detectColorMode();
+  return detectedMode;
+}
+
+/**
+ * Force a specific colour mode (e.g. from user settings). Pass `null` to
+ * revert to auto-detection.
+ */
+export function setColorMode(mode: ColorMode | null): void {
+  manualMode = mode;
+}
+
+/** Re-run env-based detection (useful after settings or env changes). */
+export function refreshColorMode(): ColorMode {
+  detectedMode = null;
+  return getColorMode();
+}
+
+// ─── 24-bit → 256 colour downgrade ─────────────────────────────────────────
+
+/**
+ * Map an RGB triple to the nearest xterm-256 index.
+ *
+ * xterm-256 layout:
+ *   0–15   → system / bright colours (skipped; we route through the cube
+ *            for predictability)
+ *   16–231 → 6×6×6 colour cube
+ *   232–255 → 24-step grayscale
+ *
+ * We pick the better of (cube nearest) and (grayscale nearest) by squared
+ * RGB distance, which matches the heuristic used by chalk / ansi-styles.
+ */
+function rgbTo256(r: number, g: number, b: number): number {
+  // Grayscale candidate
+  const grayAvg = Math.round((r + g + b) / 3);
+  let grayIdx: number;
+  let grayR: number;
+  if (grayAvg < 8) {
+    grayIdx = 16;
+    grayR = 0;
+  } else if (grayAvg > 248) {
+    grayIdx = 231;
+    grayR = 255;
+  } else {
+    const step = Math.round(((grayAvg - 8) / 247) * 24);
+    grayIdx = 232 + step;
+    grayR = 8 + step * 10;
+  }
+  const grayDist = sqDist(r, g, b, grayR, grayR, grayR);
+
+  // Cube candidate (6 steps: 0, 95, 135, 175, 215, 255)
+  const cubeR = cubeStep(r);
+  const cubeG = cubeStep(g);
+  const cubeB = cubeStep(b);
+  const cubeIdx = 16 + 36 * cubeR.idx + 6 * cubeG.idx + cubeB.idx;
+  const cubeDist = sqDist(r, g, b, cubeR.value, cubeG.value, cubeB.value);
+
+  return cubeDist <= grayDist ? cubeIdx : grayIdx;
+}
+
+const CUBE_STEPS = [0, 95, 135, 175, 215, 255];
+function cubeStep(v: number): { idx: number; value: number } {
+  let bestIdx = 0;
+  let bestDist = Infinity;
+  for (let i = 0; i < CUBE_STEPS.length; i++) {
+    const d = Math.abs(v - CUBE_STEPS[i]);
+    if (d < bestDist) {
+      bestDist = d;
+      bestIdx = i;
+    }
+  }
+  return { idx: bestIdx, value: CUBE_STEPS[bestIdx] };
+}
+
+function sqDist(r1: number, g1: number, b1: number, r2: number, g2: number, b2: number): number {
+  const dr = r1 - r2;
+  const dg = g1 - g2;
+  const db = b1 - b2;
+  return dr * dr + dg * dg + db * db;
+}
+
+// ─── Public API ────────────────────────────────────────────────────────────
+
 /** Wrap text in dim ANSI codes for muted placeholder display */
 export function mutedPlaceholder(text: string): string {
   return `\x1b[2m${text}\x1b[0m`;
@@ -95,6 +258,26 @@ export function resolveColor(color: ColorValue, theme: ThemeLike): string {
   return theme.fg(color as ThemeColor, "").replace(/\x1b\[0m$/, "");
 }
 
+/**
+ * Wrap `text` in an ANSI escape for the given hex value, chosen to match
+ * the active colour mode (truecolor / 256 / none).
+ */
+function wrapHex(hex: string, text: string): string {
+  const mode = getColorMode();
+  if (mode === "none") return text;
+  const h = hex.startsWith("#") ? hex.slice(1) : hex;
+  const r = parseInt(h.slice(0, 2), 16);
+  const g = parseInt(h.slice(2, 4), 16);
+  const b = parseInt(h.slice(4, 6), 16);
+  if (Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b)) return text;
+  if (mode === "truecolor") {
+    return `\x1b[38;2;${r};${g};${b}m${text}\x1b[0m`;
+  }
+  // 256-color fallback
+  const idx = rgbTo256(r, g, b);
+  return `\x1b[38;5;${idx}m${text}\x1b[0m`;
+}
+
 /**
  * Apply a semantic color to text using the theme.
  * Falls back to the default theme color if no override is provided.
@@ -109,16 +292,14 @@ export function applyColor(
   if (!colorValue) {
     // Use default from the map
     const defaultColor = DEFAULT_COLOR_MAP[semantic] || "text";
+    if (typeof defaultColor === "string" && defaultColor.startsWith("#")) {
+      return wrapHex(defaultColor, text);
+    }
     return theme.fg(defaultColor as ThemeColor, text);
   }
 
   if (colorValue.startsWith("#")) {
-    // Hex color — we need to emit ANSI directly
-    const hex = colorValue.slice(1);
-    const r = Number.parseInt(hex.slice(0, 2), 16);
-    const g = Number.parseInt(hex.slice(2, 4), 16);
-    const b = Number.parseInt(hex.slice(4, 6), 16);
-    return `\x1b[38;2;${r};${g};${b}m${text}\x1b[0m`;
+    return wrapHex(colorValue, text);
   }
 
   return theme.fg(colorValue as ThemeColor, text);

package/packages/footer/src/types.ts

@@ -82,6 +82,9 @@ export type ColorScheme = Partial<Record<SemanticColor, ColorValue>>;
 /** Icon style — determines which icon set is used for segments */
 export type IconStyle = "nerd" | "emoji" | "text";
 
+/** Colour-emission mode for terminal output. */
+export type ColorMode = "auto" | "truecolor" | "256" | "none";
+
 /** Separator styles for segment dividers */
 export type SeparatorStyle =
   | "powerline"
@@ -190,6 +193,8 @@ export interface FooterSettings {
   zoneSeparator?: string;
   /** Show full labels instead of compact short labels */
   showFullLabels?: boolean;
+  /** Terminal colour mode override (default: "auto" — env-detected). */
+  colorMode?: ColorMode;
   /** Per-group settings */
   groups: Record<string, FooterGroupSettings>;
 }

package/packages/utility/README.md

@@ -128,9 +128,12 @@ import { detectCapabilities, getIcon } from "@pi-unipi/utility/display/capabilit
 
 const caps = detectCapabilities();
 console.log("Nerd Font:", caps.nerdFont);
+console.log("Truecolor:", caps.truecolor);
 console.log(getIcon("󰘳", "[OK]")); // Uses Nerd Font if available
 ```
 
+Capability detection distinguishes basic color, xterm-256-compatible terminals, and truecolor-capable terminals. Apple Terminal is treated as color-capable but not truecolor-capable so renderers can fall back safely.
+
 ## Privacy
 
 The analytics collector is privacy-respecting:

package/packages/utility/src/display/capabilities.ts

@@ -42,24 +42,38 @@ function detectColorSupport(): { color: boolean; truecolor: boolean } {
   const term = env.TERM || "";
   const termProgram = env.TERM_PROGRAM || "";
 
-  // Truecolor support
-  const truecolorTerms = [
-    "truecolor",
-    "24bit",
-    "xterm-256color",
-    "screen-256color",
-    "tmux-256color",
-    "alacritty",
-    "kitty",
-    "wezterm",
-    "iTerm",
+  // Apple Terminal.app does NOT support 24-bit truecolor (longstanding
+  // limitation as of macOS 26). Force 256-colour even if some wrapper
+  // leaked COLORTERM=truecolor into the environment.
+  const isAppleTerminal = termProgram === "Apple_Terminal";
+
+  // Truecolor TERM_PROGRAM allow-list. Note: terminfo names like
+  // "xterm-256color" / "screen-256color" / "tmux-256color" advertise
+  // 256-colour, NOT truecolor — they must not appear here.
+  const truecolorTermPrograms = [
+    "iTerm.app",
+    "WezTerm",
+    "Alacritty",
+    "vscode",
+    "Hyper",
+    "Warp",
     "ghostty",
+    "Ghostty",
+    "zed",
+    "Zed",
+    "cursor",
+    "Cursor",
   ];
 
-  const hasTruecolor =
-    env.COLORTERM === "truecolor" ||
-    env.COLORTERM === "24bit" ||
-    truecolorTerms.some((t) => term.includes(t) || termProgram.includes(t));
+  // Truecolor TERM tokens (the rare TERM that *does* advertise truecolor).
+  const truecolorTermTokens = ["truecolor", "24bit", "alacritty", "kitty", "wezterm"];
+
+  const hasTruecolor = isAppleTerminal
+    ? false
+    : env.COLORTERM === "truecolor" ||
+      env.COLORTERM === "24bit" ||
+      truecolorTermPrograms.includes(termProgram) ||
+      truecolorTermTokens.some((t) => term.includes(t));
 
   // Basic color support
   const hasColor =