@wierdbytes/pi-facelift 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.3.1
+
+- **Fix**: `read` bodies rendered as plain uncolored text whenever
+  pi's `settings.theme` was a name Shiki doesn't ship (e.g.
+  `tokyo-night-storm`). pi-facelift forwarded the raw value to
+  Shiki's `codeToANSI`, which threw, and `hlBlock`'s `catch` block
+  silently fell back to plain `code.split("\n")` — leaving frame
+  chrome and line numbers but no syntax highlighting.
+  Three changes land together:
+  1. The resolved theme is now validated against Shiki's
+     `bundledThemes` set; unknown names fall back to
+     `DEFAULT_THEME` (`github-dark`) instead of being passed through.
+  2. Common pi/host theme aliases are mapped to their nearest Shiki
+     bundled equivalent (`tokyo-night-storm` → `tokyo-night`,
+     `catppuccin` → `catppuccin-mocha`, `material-darker` →
+     `material-theme-darker`, `gruvbox-dark` → `gruvbox-dark-medium`,
+     `solarized` → `solarized-dark`, `one-dark` → `one-dark-pro`,
+     and Tokyo Night/Material/Catppuccin variants). Lookup is
+     case-insensitive.
+  3. The `hlBlock` catch now logs once per `(theme, language)` to
+     stderr (instead of swallowing every error forever) so future
+     regressions in the highlighter pipeline surface during dev.
+  A one-shot `console.error` is also emitted the first time an
+  unknown theme name is rejected, advertising `FACELIFT_THEME` as the
+  override knob.
+
 ## 0.3.0
 
 - Frame primitives (open-right rounded box for `read` / `bash` / `ls` /

package/index.ts

@@ -43,6 +43,7 @@ import type {
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { codeToANSI } from "@shikijs/cli";
+import { bundledThemes } from "shiki";
 import {
 	formatDuration,
 	frameBodyLines,
@@ -63,12 +64,83 @@ import type { BundledLanguage, BundledTheme } from "shiki";
 
 const DEFAULT_THEME: BundledTheme = "github-dark";
 
+/**
+ * Aliases that map common pi/host theme names (or popular external
+ * themes that aren't bundled with Shiki) to their closest Shiki
+ * `BundledTheme` equivalent.
+ *
+ * Keys are lowercased; values must be valid `BundledTheme` keys.
+ * The full Shiki theme list lives at https://shiki.style/themes.
+ *
+ * Why this exists: pi's `settings.theme` is consumed by the host UI
+ * and may use names Shiki doesn't ship (e.g. `tokyo-night-storm`).
+ * Without aliasing, `codeToANSI` throws and `hlBlock` silently falls
+ * back to plain text — leaving every `read` body uncolored.
+ */
+const THEME_ALIASES: Record<string, BundledTheme> = {
+	// Tokyo Night family (storm/night/day are Tokyo Night palette variants;
+	// Shiki only ships the storm-equivalent under the bare `tokyo-night` name).
+	"tokyo-night-storm": "tokyo-night",
+	"tokyo-night-night": "tokyo-night",
+	"tokyo-night-day": "tokyo-night",
+	tokyonight: "tokyo-night",
+	"tokyonight-storm": "tokyo-night",
+	"tokyonight-night": "tokyo-night",
+	"tokyonight-day": "tokyo-night",
+	// Catppuccin (default → mocha, the most common dark variant)
+	catppuccin: "catppuccin-mocha",
+	// Dracula
+	"dracula-pro": "dracula",
+	// Material
+	material: "material-theme",
+	"material-darker": "material-theme-darker",
+	"material-lighter": "material-theme-lighter",
+	"material-ocean": "material-theme-ocean",
+	"material-palenight": "material-theme-palenight",
+	// Gruvbox (medium contrast is the canonical default)
+	"gruvbox-dark": "gruvbox-dark-medium",
+	"gruvbox-light": "gruvbox-light-medium",
+	// Solarized (default → dark)
+	solarized: "solarized-dark",
+	// One Dark
+	"one-dark": "one-dark-pro",
+	onedark: "one-dark-pro",
+};
+
+const _themeWarningShown = new Set<string>();
+
+function isBundledTheme(name: string): name is BundledTheme {
+	return Object.prototype.hasOwnProperty.call(bundledThemes, name);
+}
+
+function warnInvalidTheme(rawName: string, fallback: BundledTheme): void {
+	if (_themeWarningShown.has(rawName)) return;
+	_themeWarningShown.add(rawName);
+	console.error(
+		`pi-facelift: theme "${rawName}" is not a Shiki bundled theme; ` +
+			`falling back to "${fallback}". ` +
+			`Set FACELIFT_THEME to one of: ${Object.keys(bundledThemes).sort().join(", ")}.`,
+	);
+}
+
+/** Resolve a raw theme name to a valid `BundledTheme`, applying aliases. */
+function resolveBundledTheme(rawName: string | undefined): BundledTheme {
+	if (!rawName) return DEFAULT_THEME;
+	const trimmed = rawName.trim();
+	if (!trimmed) return DEFAULT_THEME;
+	if (isBundledTheme(trimmed)) return trimmed;
+	const aliased = THEME_ALIASES[trimmed.toLowerCase()];
+	if (aliased) return aliased;
+	warnInvalidTheme(trimmed, DEFAULT_THEME);
+	return DEFAULT_THEME;
+}
+
 function getDefaultAgentDir(): string | undefined {
 	const home = process.env.HOME ?? "";
 	return home ? join(home, ".pi/agent") : undefined;
 }
 
-function readThemeFromSettings(agentDir?: string): BundledTheme | undefined {
+function readThemeFromSettings(agentDir?: string): string | undefined {
 	const resolvedAgentDir = agentDir ?? getDefaultAgentDir();
 	if (!resolvedAgentDir) return undefined;
 
@@ -76,27 +148,34 @@ function readThemeFromSettings(agentDir?: string): BundledTheme | undefined {
 		const settings = JSON.parse(readFileSync(join(resolvedAgentDir, "settings.json"), "utf8")) as {
 			theme?: unknown;
 		};
-		return typeof settings.theme === "string" ? (settings.theme as BundledTheme) : undefined;
+		return typeof settings.theme === "string" ? settings.theme : undefined;
 	} catch {
 		return undefined;
 	}
 }
 
 function resolvePrettyTheme(agentDir?: string): BundledTheme {
-	return (
-		(process.env.FACELIFT_THEME as BundledTheme | undefined) ??
-		readThemeFromSettings(agentDir) ??
-		DEFAULT_THEME
-	);
+	const raw = process.env.FACELIFT_THEME ?? readThemeFromSettings(agentDir);
+	return resolveBundledTheme(raw);
 }
 
 let THEME: BundledTheme = resolvePrettyTheme();
 
+/** Test-only hooks for theme resolution (alias map, bundled validation, fallback warning). */
+export const __themeInternals = {
+	DEFAULT_THEME,
+	THEME_ALIASES,
+	isBundledTheme,
+	resolveBundledTheme,
+	resetWarningsForTests: () => _themeWarningShown.clear(),
+};
+
 function setPrettyTheme(agentDir?: string): void {
 	const resolvedTheme = resolvePrettyTheme(agentDir);
 	if (resolvedTheme === THEME) return;
 	THEME = resolvedTheme;
 	_cache.clear();
+	_hlErrorLogged.clear();
 	codeToANSI("", "typescript", THEME).catch(() => {});
 }
 
@@ -566,6 +645,7 @@ function dirIcon(): string {
 codeToANSI("", "typescript", THEME).catch(() => {});
 
 const _cache = new Map<string, string[]>();
+const _hlErrorLogged = new Set<string>();
 
 function _touch(k: string, v: string[]): string[] {
 	_cache.delete(k);
@@ -590,11 +670,30 @@ async function hlBlock(code: string, language: BundledLanguage | undefined): Pro
 		const ansi = normalizeShikiContrast(await codeToANSI(code, language, THEME));
 		const out = (ansi.endsWith("\n") ? ansi.slice(0, -1) : ansi).split("\n");
 		return _touch(k, out);
-	} catch {
+	} catch (err) {
+		// Log once per (theme, language) so silent regressions are visible
+		// during dev (e.g. an unsupported theme name slipping through, or a
+		// grammar load failure for a niche language) without spamming on
+		// every render. The plain-text fallback below keeps the body usable.
+		const tag = `${THEME}\0${language}`;
+		if (!_hlErrorLogged.has(tag)) {
+			_hlErrorLogged.add(tag);
+			const msg = err instanceof Error ? err.message : String(err);
+			console.error(
+				`pi-facelift: shiki highlighting failed for theme="${THEME}" language="${language}": ${msg}`,
+			);
+		}
 		return code.split("\n");
 	}
 }
 
+/** Test-only hooks for the Shiki highlighter pipeline. */
+export const __hlInternals = {
+	hlBlock,
+	resetErrorLogForTests: () => _hlErrorLogged.clear(),
+	resetCacheForTests: () => _cache.clear(),
+};
+
 // ---------------------------------------------------------------------------
 // Renderers
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wierdbytes/pi-facelift",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Cosmetic facelift for built-in pi tool output — open-right rounded frames, syntax-highlighted reads, status-aware bash summaries, find/grep.",
   "type": "module",
   "files": [

package/theme-resolution.test.ts

@@ -0,0 +1,238 @@
+/**
+ * Regression tests for Shiki theme resolution.
+ *
+ * Background: pi's `~/.pi/agent/settings.json` `theme` field is consumed
+ * by the host UI and may carry names that aren't valid Shiki bundled
+ * themes (e.g. `tokyo-night-storm`). Before this regression net,
+ * `pi-facelift` passed the raw value straight to Shiki's `codeToANSI`,
+ * which threw, and `hlBlock`'s `catch` block silently fell back to
+ * uncolored text — leaving every `read` body in plain whitish output
+ * with no obvious error.
+ *
+ * These tests pin three guarantees:
+ *   1. Bundled themes pass through untouched.
+ *   2. Common pi/host theme names are aliased to their nearest Shiki
+ *      bundled equivalent (case-insensitive).
+ *   3. Unknown / empty / whitespace-only theme names fall back to
+ *      `DEFAULT_THEME` and emit a one-shot console.error so silent
+ *      regressions are visible during dev.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { bundledThemes } from "shiki";
+
+import { __hlInternals, __themeInternals } from "./index.ts";
+
+const { DEFAULT_THEME, THEME_ALIASES, isBundledTheme, resolveBundledTheme, resetWarningsForTests } =
+	__themeInternals;
+
+const { hlBlock, resetCacheForTests, resetErrorLogForTests } = __hlInternals;
+
+beforeEach(() => {
+	resetWarningsForTests();
+});
+
+describe("theme resolution: alias map sanity", () => {
+	it("DEFAULT_THEME is a valid Shiki bundled theme", () => {
+		expect(isBundledTheme(DEFAULT_THEME)).toBe(true);
+	});
+
+	it("every alias value points at a valid Shiki bundled theme", () => {
+		for (const [from, to] of Object.entries(THEME_ALIASES)) {
+			expect(isBundledTheme(to), `alias ${from} -> ${to} must be bundled`).toBe(true);
+		}
+	});
+
+	it("alias keys are lowercase (matching the lookup convention)", () => {
+		for (const key of Object.keys(THEME_ALIASES)) {
+			expect(key).toBe(key.toLowerCase());
+		}
+	});
+
+	it("does not alias names that are already bundled (would be dead code)", () => {
+		for (const key of Object.keys(THEME_ALIASES)) {
+			expect(
+				Object.prototype.hasOwnProperty.call(bundledThemes, key),
+				`alias key "${key}" is already a bundled theme; alias entry is unreachable`,
+			).toBe(false);
+		}
+	});
+});
+
+describe("resolveBundledTheme: passthrough + fallbacks", () => {
+	let errorSpy: ReturnType<typeof vi.spyOn>;
+
+	beforeEach(() => {
+		errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+	});
+	afterEach(() => {
+		errorSpy.mockRestore();
+	});
+
+	it("returns a bundled theme name unchanged", () => {
+		expect(resolveBundledTheme("github-dark")).toBe("github-dark");
+		expect(resolveBundledTheme("dracula")).toBe("dracula");
+		expect(resolveBundledTheme("nord")).toBe("nord");
+		expect(errorSpy).not.toHaveBeenCalled();
+	});
+
+	it("falls back to DEFAULT_THEME for undefined/empty/whitespace input", () => {
+		expect(resolveBundledTheme(undefined)).toBe(DEFAULT_THEME);
+		expect(resolveBundledTheme("")).toBe(DEFAULT_THEME);
+		expect(resolveBundledTheme("   ")).toBe(DEFAULT_THEME);
+		// Empty/whitespace input is the "no theme configured" path — no warning.
+		expect(errorSpy).not.toHaveBeenCalled();
+	});
+
+	it("trims surrounding whitespace before validating", () => {
+		expect(resolveBundledTheme("  github-dark  ")).toBe("github-dark");
+		expect(errorSpy).not.toHaveBeenCalled();
+	});
+});
+
+describe("resolveBundledTheme: alias resolution", () => {
+	let errorSpy: ReturnType<typeof vi.spyOn>;
+
+	beforeEach(() => {
+		errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+	});
+	afterEach(() => {
+		errorSpy.mockRestore();
+	});
+
+	// The original bug report: pi user has `"theme": "tokyo-night-storm"`,
+	// Shiki only ships `tokyo-night`.
+	it("aliases tokyo-night-storm to tokyo-night (the original bug report)", () => {
+		expect(resolveBundledTheme("tokyo-night-storm")).toBe("tokyo-night");
+		expect(errorSpy).not.toHaveBeenCalled();
+	});
+
+	it("aliases other tokyo-night variants", () => {
+		expect(resolveBundledTheme("tokyo-night-night")).toBe("tokyo-night");
+		expect(resolveBundledTheme("tokyo-night-day")).toBe("tokyo-night");
+		expect(resolveBundledTheme("tokyonight")).toBe("tokyo-night");
+		expect(resolveBundledTheme("tokyonight-storm")).toBe("tokyo-night");
+	});
+
+	it("aliases case-insensitively", () => {
+		expect(resolveBundledTheme("Tokyo-Night-Storm")).toBe("tokyo-night");
+		expect(resolveBundledTheme("CATPPUCCIN")).toBe("catppuccin-mocha");
+		expect(resolveBundledTheme("Material")).toBe("material-theme");
+	});
+
+	it("aliases catppuccin family defaults", () => {
+		expect(resolveBundledTheme("catppuccin")).toBe("catppuccin-mocha");
+	});
+
+	it("aliases gruvbox/material/solarized/one-dark families to canonical variants", () => {
+		expect(resolveBundledTheme("gruvbox-dark")).toBe("gruvbox-dark-medium");
+		expect(resolveBundledTheme("gruvbox-light")).toBe("gruvbox-light-medium");
+		expect(resolveBundledTheme("material")).toBe("material-theme");
+		expect(resolveBundledTheme("material-darker")).toBe("material-theme-darker");
+		expect(resolveBundledTheme("solarized")).toBe("solarized-dark");
+		expect(resolveBundledTheme("one-dark")).toBe("one-dark-pro");
+	});
+});
+
+describe("resolveBundledTheme: invalid theme warning", () => {
+	let errorSpy: ReturnType<typeof vi.spyOn>;
+
+	beforeEach(() => {
+		errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+	});
+	afterEach(() => {
+		errorSpy.mockRestore();
+	});
+
+	it("falls back to DEFAULT_THEME for an unknown name and warns once", () => {
+		expect(resolveBundledTheme("not-a-real-theme-9000")).toBe(DEFAULT_THEME);
+		expect(errorSpy).toHaveBeenCalledTimes(1);
+
+		const msg = errorSpy.mock.calls[0]?.[0];
+		expect(msg).toContain("pi-facelift");
+		expect(msg).toContain("not-a-real-theme-9000");
+		expect(msg).toContain(DEFAULT_THEME);
+		// The warning should advertise FACELIFT_THEME as the fix knob.
+		expect(msg).toContain("FACELIFT_THEME");
+	});
+
+	it("warns at most once per distinct invalid theme (no per-render spam)", () => {
+		expect(resolveBundledTheme("bogus-theme")).toBe(DEFAULT_THEME);
+		expect(resolveBundledTheme("bogus-theme")).toBe(DEFAULT_THEME);
+		expect(resolveBundledTheme("bogus-theme")).toBe(DEFAULT_THEME);
+		expect(errorSpy).toHaveBeenCalledTimes(1);
+	});
+
+	it("warns separately for distinct invalid names", () => {
+		expect(resolveBundledTheme("first-bad")).toBe(DEFAULT_THEME);
+		expect(resolveBundledTheme("second-bad")).toBe(DEFAULT_THEME);
+		expect(errorSpy).toHaveBeenCalledTimes(2);
+	});
+
+	it("does NOT warn for names resolved via the alias map", () => {
+		// `tokyo-night-storm` is invalid for Shiki but covered by an alias —
+		// this is the *fixed* path, not a regression, so it must stay quiet.
+		expect(resolveBundledTheme("tokyo-night-storm")).toBe("tokyo-night");
+		expect(errorSpy).not.toHaveBeenCalled();
+	});
+});
+
+describe("hlBlock: Shiki failure logging + plain-text fallback", () => {
+	let errorSpy: ReturnType<typeof vi.spyOn>;
+
+	beforeEach(() => {
+		errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+		resetCacheForTests();
+		resetErrorLogForTests();
+	});
+	afterEach(() => {
+		errorSpy.mockRestore();
+	});
+
+	it("returns plain split lines when language is missing (no shiki call, no log)", async () => {
+		const out = await hlBlock("a\nb\nc", undefined);
+		expect(out).toEqual(["a", "b", "c"]);
+		expect(errorSpy).not.toHaveBeenCalled();
+	});
+
+	it("returns [''] for empty input", async () => {
+		expect(await hlBlock("", "typescript")).toEqual([""]);
+		expect(errorSpy).not.toHaveBeenCalled();
+	});
+
+	it("returns ANSI-colored lines for a valid theme + language (sanity)", async () => {
+		const out = await hlBlock("const x = 1;", "typescript");
+		expect(out.length).toBeGreaterThan(0);
+		// Joined output must contain at least one ANSI escape — proof shiki ran.
+		expect(out.join("\n")).toMatch(/\x1b\[/);
+		expect(errorSpy).not.toHaveBeenCalled();
+	});
+
+	it("falls back to plain split lines when shiki rejects a bogus language, and logs once", async () => {
+		// `"definitely-not-a-language"` is not a `BundledLanguage`, but the
+		// runtime check in shiki throws synchronously inside the promise.
+		// We cast through `unknown` to bypass the compile-time guard — this
+		// is the same shape a stale settings.theme value would take if it
+		// somehow reached the highlighter.
+		const bogusLang = "definitely-not-a-language" as unknown as Parameters<
+			typeof hlBlock
+		>[1];
+		const src = "const x = 1;";
+
+		const out1 = await hlBlock(src, bogusLang);
+		expect(out1).toEqual([src]);
+		expect(errorSpy).toHaveBeenCalledTimes(1);
+
+		const msg = errorSpy.mock.calls[0]?.[0];
+		expect(msg).toContain("pi-facelift");
+		expect(msg).toContain("shiki");
+		expect(msg).toContain("definitely-not-a-language");
+
+		// Second call with the same (theme, language) tag must NOT re-log.
+		// We change the source so the cache key differs and the catch path
+		// runs again — still only one log.
+		const out2 = await hlBlock("let y = 2;", bogusLang);
+		expect(out2).toEqual(["let y = 2;"]);
+		expect(errorSpy).toHaveBeenCalledTimes(1);
+	});
+});