@knightcodeai/cli 0.17.4 → 0.18.1

package/dist/modes/interactive/theme/theme-controller.ts

@@ -0,0 +1,253 @@
+import type { RgbColor, TerminalColors, TUI } from "@knightcode/tui";
+import type { SettingsManager } from "../../../core/settings-manager.ts";
+import {
+	getTerminalTheme,
+	initTheme,
+	markTerminalColorsPending,
+	parseAutoThemeSetting,
+	resolveThemeSetting,
+	SYSTEM_THEME_NAME,
+	setTerminalColorScheme,
+	setTerminalColors,
+	setTheme,
+	setThemeInstance,
+	type TerminalTheme,
+	type Theme,
+} from "./theme.ts";
+
+type ThemeResult = { success: boolean; error?: string };
+
+/**
+ * How long the system theme stays grayscale before falling back to palette indices. Terminals answer
+ * the trailing DA1 request right after the color replies, so this only matters for terminals that
+ * answer neither. Replies arriving later still apply.
+ */
+const TERMINAL_QUERY_TIMEOUT_MS = 100;
+
+/**
+ * Query the terminal's colors and pass them to `apply` when the query completes or times out, and again
+ * if the terminal answers after the timeout. A failed query applies no colors. Settles after the first apply.
+ */
+export function requestTerminalColors(ui: TUI, apply: (colors: TerminalColors) => void): Promise<void> {
+	let query: Promise<TerminalColors>;
+	try {
+		query = ui.queryTerminalColors({ timeoutMs: TERMINAL_QUERY_TIMEOUT_MS, onLateReply: apply });
+	} catch {
+		// Treat a failed query like a terminal that does not report colors.
+		query = Promise.resolve({});
+	}
+	return query.then(apply, () => apply({}));
+}
+
+function sameRgb(a: RgbColor | undefined, b: RgbColor | undefined): boolean {
+	return a === b || (a !== undefined && b !== undefined && a.r === b.r && a.g === b.g && a.b === b.b);
+}
+
+function sameTerminalColors(a: TerminalColors, b: TerminalColors): boolean {
+	if (!sameRgb(a.foreground, b.foreground) || !sameRgb(a.background, b.background)) return false;
+	if (a.palette === b.palette) return true;
+	if (!a.palette || !b.palette || a.palette.length !== b.palette.length) return false;
+	return a.palette.every((color, index) => sameRgb(color, b.palette?.[index]));
+}
+
+/**
+ * Applies the theme setting and keeps it in sync with the terminal. The theme applies immediately, and the
+ * terminal's colors update it when they arrive; the system theme renders in grayscale until then. Callers
+ * that bake theme colors into content can wait for the colors with `waitForTerminalColors()`.
+ */
+export class InteractiveThemeController {
+	private readonly ui: TUI;
+	private readonly getSettingsManager: () => SettingsManager;
+	private readonly showError: (message: string) => void;
+	private readonly onChanged: () => void;
+	private currentThemeSetting: string | undefined;
+	// Last reported colors; a query that times out keeps them instead of erasing them.
+	private terminalColors: TerminalColors | undefined;
+	private activeThemeName: string | undefined;
+	private autoSyncEnabled = false;
+	private terminalColorSchemeUnsubscribe: (() => void) | undefined;
+	// Settles when the latest color query completed or timed out, and its colors applied.
+	private terminalColorQuery: Promise<void> = Promise.resolve();
+
+	constructor(
+		ui: TUI,
+		options: {
+			getSettingsManager: () => SettingsManager;
+			showError: (message: string) => void;
+			onChanged: () => void;
+			initialThemeSetting?: string;
+		},
+	) {
+		this.ui = ui;
+		this.getSettingsManager = options.getSettingsManager;
+		this.showError = options.showError;
+		this.onChanged = options.onChanged;
+		this.currentThemeSetting = options.initialThemeSetting;
+		this.activeThemeName = this.resolveThemeName();
+		// The system theme starts in grayscale; color follows once the terminal reports its colors.
+		markTerminalColorsPending();
+		initTheme(this.activeThemeName, true);
+		this.bindTerminalColorSchemeListener();
+	}
+
+	rebindTui(): void {
+		this.terminalColorSchemeUnsubscribe?.();
+		this.bindTerminalColorSchemeListener();
+		this.ui.setTerminalColorSchemeNotifications(this.autoSyncEnabled);
+	}
+
+	/**
+	 * Apply the theme setting now and query the terminal's colors, which update the theme when they arrive.
+	 * Theme pairs and the system theme follow terminal appearance changes.
+	 */
+	applyFromSettings(): void {
+		const themeSetting = this.getThemeSetting();
+		const themeName = this.resolveThemeName();
+		this.setAutoSync(parseAutoThemeSetting(themeSetting) !== undefined || themeName === SYSTEM_THEME_NAME);
+		this.applyThemeName(themeName, themeSetting !== undefined);
+		this.queryTerminalColors();
+	}
+
+	/**
+	 * Wait until the latest color query completed or timed out. Content that bakes theme colors into
+	 * strings, such as the startup header, should be built after this. Terminals answer the DA1 request
+	 * right after the color replies, so this only takes the full timeout when a terminal answers nothing.
+	 */
+	waitForTerminalColors(): Promise<void> {
+		return this.terminalColorQuery;
+	}
+
+	getThemeSelection(): string | undefined {
+		return this.currentThemeSetting ?? this.getSettingsManager().getThemeSetting() ?? this.activeThemeName;
+	}
+
+	setThemeName(themeName: string, showError = false): ThemeResult {
+		this.setAutoSync(themeName === SYSTEM_THEME_NAME);
+		const result = this.applyThemeName(themeName, showError);
+		if (result.success) {
+			this.currentThemeSetting = themeName;
+		}
+		return result;
+	}
+
+	setThemeSetting(themeSetting: string): void {
+		this.currentThemeSetting = themeSetting;
+		this.applyFromSettings();
+	}
+
+	setThemeInstance(themeInstance: Theme): ThemeResult {
+		this.setAutoSync(false);
+		setThemeInstance(themeInstance);
+		this.activeThemeName = "<in-memory>";
+		this.notifyChanged();
+		return { success: true };
+	}
+
+	preview(themeSettingOrName: string): void {
+		const themeName = resolveThemeSetting(themeSettingOrName, getTerminalTheme()) ?? this.activeThemeName;
+		if (!themeName) return;
+		if (setTheme(themeName, true).success) {
+			this.ui.invalidate();
+			this.ui.requestRender();
+		}
+	}
+
+	disableAutoSync(): void {
+		this.setAutoSync(false);
+	}
+
+	dispose(): void {
+		this.setAutoSync(false);
+		this.terminalColorSchemeUnsubscribe?.();
+		this.terminalColorSchemeUnsubscribe = undefined;
+	}
+
+	getTerminalTheme(): TerminalTheme {
+		return getTerminalTheme();
+	}
+
+	private getThemeSetting(): string | undefined {
+		return this.currentThemeSetting ?? this.getSettingsManager().getThemeSetting();
+	}
+
+	/** The theme for the current setting and terminal appearance. Without a setting, KnightCode uses the system theme. */
+	private resolveThemeName(): string {
+		return resolveThemeSetting(this.getThemeSetting(), getTerminalTheme()) ?? SYSTEM_THEME_NAME;
+	}
+
+	private applyThemeName(themeName: string, showError = false): ThemeResult {
+		const result = setTheme(themeName, true);
+		this.activeThemeName = result.success ? themeName : SYSTEM_THEME_NAME;
+		this.notifyChanged();
+		if (!result.success && showError) {
+			this.showError(`Failed to load theme "${themeName}": ${result.error}\nFell back to the system theme.`);
+		}
+		return result;
+	}
+
+	/** Query the terminal's colors without waiting for them; `waitForTerminalColors()` waits for this query. */
+	private queryTerminalColors(): void {
+		this.terminalColorQuery = requestTerminalColors(this.ui, (colors) => this.applyTerminalColors(colors));
+	}
+
+	/**
+	 * Record reported colors: themes use the default colors for tokens set to "", the system theme is
+	 * generated from all of them, and light/dark detection uses them. Re-renders only when they changed.
+	 */
+	private applyTerminalColors(reported: TerminalColors): void {
+		const previous = this.terminalColors;
+		const next: TerminalColors = {
+			foreground: reported.foreground ?? previous?.foreground,
+			background: reported.background ?? previous?.background,
+			palette: reported.palette ?? previous?.palette,
+		};
+		// Re-rendering rebuilds every component, so skip it when nothing changed (including timeouts).
+		if (previous && sameTerminalColors(previous, next)) return;
+		this.terminalColors = next;
+		setTerminalColors(next);
+		this.reapplyForTerminal();
+		this.ui.invalidate();
+		this.ui.requestRender();
+	}
+
+	/**
+	 * Re-apply the setting after the terminal's colors or appearance changed: regenerate the system theme,
+	 * or switch the theme of a pair. Themes set through extensions or previews are left alone.
+	 */
+	private reapplyForTerminal(): void {
+		if (this.activeThemeName === "<in-memory>") return;
+		const themeName = this.resolveThemeName();
+		if (themeName === SYSTEM_THEME_NAME || themeName !== this.activeThemeName) {
+			this.applyThemeName(themeName);
+		}
+	}
+
+	private setAutoSync(enabled: boolean): void {
+		if (this.autoSyncEnabled === enabled) return;
+		this.autoSyncEnabled = enabled;
+		this.ui.setTerminalColorSchemeNotifications(enabled);
+	}
+
+	private bindTerminalColorSchemeListener(): void {
+		this.terminalColorSchemeUnsubscribe = this.ui.onTerminalColorSchemeChange((terminalTheme) =>
+			this.applyTerminalColorSchemeChange(terminalTheme),
+		);
+	}
+
+	/**
+	 * The terminal reported a light/dark switch. Its colors changed too, so query them again: they decide
+	 * the appearance. The reported scheme only matters for terminals that do not report their background.
+	 */
+	private applyTerminalColorSchemeChange(terminalTheme: TerminalTheme): void {
+		if (!this.autoSyncEnabled) return;
+		const previous = getTerminalTheme();
+		setTerminalColorScheme(terminalTheme);
+		if (getTerminalTheme() !== previous) this.reapplyForTerminal();
+		this.queryTerminalColors();
+	}
+
+	private notifyChanged(): void {
+		this.ui.invalidate();
+		this.onChanged();
+	}
+}

package/dist/modes/interactive/theme/theme-schema.ts

@@ -0,0 +1,145 @@
+/**
+ * Theme JSON validation, kept out of `theme.ts` on purpose.
+ *
+ * Validating user-authored theme files needs typebox, which costs ~17 MB of module graph to import.
+ * Palette lookup does not, so a presentation that only uses built-in themes should never pay for it.
+ * `main.ts` installs this validator before runtime resource loading; other consumers can opt in with
+ * `setThemeJsonValidator()`. Built-in themes do not need validation.
+ */
+
+import { type Static, type TProperties, Type } from "typebox";
+import { Compile } from "typebox/compile";
+import { THEME_TOKENS, type ThemeColorValues, type ThemeTokenDescriptors } from "./theme-tokens.ts";
+
+function colorValue(description?: string) {
+	return Type.Union(
+		[
+			Type.String({
+				description:
+					"Hex color (#RGB or #RRGGBB), OKLCH or OKHSL color, variable reference, or empty string for terminal default",
+			}),
+			Type.Integer({
+				minimum: 0,
+				maximum: 255,
+				description: "256-color palette index (0-255)",
+			}),
+		],
+		description ? { description } : {},
+	);
+}
+
+export const ColorValueSchema = colorValue();
+
+export type ThemeColorValue = Static<typeof ColorValueSchema>;
+
+function themeTokenProperties(tokens: ThemeTokenDescriptors): TProperties {
+	const properties: TProperties = {};
+	for (const [name, descriptor] of Object.entries(tokens)) {
+		const schema = colorValue(descriptor.description);
+		properties[name] = descriptor.fallback === undefined ? schema : Type.Optional(schema);
+	}
+	return properties;
+}
+
+const ThemeColorsSchema = Type.Unsafe<ThemeColorValues<ThemeColorValue>>(
+	Type.Object(themeTokenProperties(THEME_TOKENS), {
+		description:
+			"Theme color definitions (scrollbar, thinking level borders, and search highlight colors are optional and use compatible fallbacks)",
+		additionalProperties: false,
+	}),
+);
+
+export const ThemeJsonSchema = Type.Object(
+	{
+		$schema: Type.Optional(Type.String({ description: "JSON schema reference" })),
+		name: Type.String({
+			pattern: "^[^/]+$",
+			description: "Theme name. Must not contain '/' because it is reserved for automatic light/dark theme settings.",
+		}),
+		appearance: Type.Optional(
+			Type.Union([Type.Literal("dark"), Type.Literal("light")], {
+				description: "Background the theme is designed for. Detected from the theme colors when omitted.",
+			}),
+		),
+		vars: Type.Optional(
+			Type.Record(Type.String(), ColorValueSchema, {
+				description: "Reusable color variables",
+			}),
+		),
+		colors: ThemeColorsSchema,
+		export: Type.Optional(
+			Type.Object(
+				{
+					pageBg: Type.Optional(colorValue("Page background color")),
+					cardBg: Type.Optional(colorValue("Card/container background color")),
+					infoBg: Type.Optional(colorValue("Info sections background (system prompt, notices)")),
+				},
+				{
+					description: "Optional colors for HTML export (defaults derived from userMessageBg if not specified)",
+					additionalProperties: false,
+				},
+			),
+		),
+	},
+	{
+		title: "KnightCode Coding Agent Theme",
+		description: "Theme schema for KnightCode coding agent",
+		additionalProperties: false,
+	},
+);
+
+const compiledThemeSchema = Compile(ThemeJsonSchema);
+
+export type ValidatedThemeJson = Static<typeof ThemeJsonSchema>;
+
+/** Validate one theme document, throwing a message that names the offending tokens. */
+export function validateThemeJson(label: string, json: unknown): ValidatedThemeJson {
+	if (
+		typeof json === "object" &&
+		json !== null &&
+		"name" in json &&
+		typeof json.name === "string" &&
+		json.name.includes("/")
+	) {
+		throw new Error(
+			`Invalid theme name "${json.name}": theme names cannot contain "/" because it is reserved for automatic light/dark theme settings.`,
+		);
+	}
+
+	if (!compiledThemeSchema.Check(json)) {
+		const errors = Array.from(compiledThemeSchema.Errors(json));
+		const missingColors = new Set<string>();
+		const otherErrors: string[] = [];
+
+		for (const error of errors) {
+			if (error.keyword === "required" && error.instancePath === "/colors") {
+				const requiredProperties = (error.params as { requiredProperties?: string[] }).requiredProperties;
+				for (const requiredProperty of requiredProperties ?? []) {
+					missingColors.add(requiredProperty);
+				}
+				continue;
+			}
+
+			const path = error.instancePath || "/";
+			otherErrors.push(`  - ${path}: ${error.message}`);
+		}
+
+		let errorMessage = `Invalid theme "${label}":\n`;
+		if (missingColors.size > 0) {
+			errorMessage += "\nMissing required color tokens:\n";
+			errorMessage += Array.from(missingColors)
+				.sort()
+				.map((color) => `  - ${color}`)
+				.join("\n");
+			errorMessage += '\n\nPlease add these colors to your theme\'s "colors" object.';
+			errorMessage += "\nSee the built-in themes (dark.json, light.json) for reference values.";
+		}
+		if (otherErrors.length > 0) {
+			errorMessage += `\n\nOther errors:\n${otherErrors.join("\n")}`;
+		}
+
+		throw new Error(errorMessage);
+	}
+
+	return json as ValidatedThemeJson;
+}

package/dist/modes/interactive/theme/theme-tokens.ts

@@ -0,0 +1,145 @@
+export interface ThemeTokenDescriptor {
+	slot: "foreground" | "background";
+	description: string;
+	fallback?: string;
+}
+
+export type ThemeTokenDescriptors = Readonly<Record<string, ThemeTokenDescriptor>>;
+
+function defineThemeTokens<const T extends ThemeTokenDescriptors>(tokens: T): T {
+	for (const [name, descriptor] of Object.entries(tokens)) {
+		if (descriptor.fallback === undefined) continue;
+		const fallback = tokens[descriptor.fallback];
+		if (fallback === undefined) {
+			throw new Error(`Theme token ${name} has unknown fallback ${descriptor.fallback}`);
+		}
+		if (fallback.slot !== descriptor.slot) {
+			throw new Error(`Theme token ${name} has fallback ${descriptor.fallback} in a different color slot`);
+		}
+	}
+	return tokens;
+}
+
+/** Theme token metadata in the same order used by theme files and the published JSON Schema. */
+export const THEME_TOKENS = defineThemeTokens({
+	accent: { slot: "foreground", description: "Primary accent color (logo, selected items, cursor)" },
+	border: { slot: "foreground", description: "Normal borders" },
+	borderAccent: { slot: "foreground", description: "Highlighted borders" },
+	borderMuted: { slot: "foreground", description: "Subtle borders" },
+	success: { slot: "foreground", description: "Success states" },
+	error: { slot: "foreground", description: "Error states" },
+	warning: { slot: "foreground", description: "Warning states" },
+	muted: { slot: "foreground", description: "Secondary/dimmed text" },
+	dim: { slot: "foreground", description: "Very dimmed text (more subtle than muted)" },
+	text: { slot: "foreground", description: "Default text color (usually empty string)" },
+	thinkingText: { slot: "foreground", description: "Thinking block text color" },
+	scrollbarTrack: {
+		slot: "foreground",
+		description: "Fullscreen scrollbar track foreground (falls back to muted when omitted)",
+		fallback: "muted",
+	},
+	scrollbarThumb: {
+		slot: "foreground",
+		description: "Fullscreen scrollbar thumb foreground (falls back to text when omitted)",
+		fallback: "text",
+	},
+	selectedBg: { slot: "background", description: "Selected item background" },
+	searchMatchBg: {
+		slot: "background",
+		description: "Transcript search match background and current-match text (falls back to selectedBg when omitted)",
+		fallback: "selectedBg",
+	},
+	searchMatchText: {
+		slot: "foreground",
+		description: "Transcript search match text and current-match background (falls back to text when omitted)",
+		fallback: "text",
+	},
+	userMessageBg: { slot: "background", description: "User message background" },
+	userMessageText: { slot: "foreground", description: "User message text color" },
+	customMessageBg: { slot: "background", description: "Custom message background (hook-injected messages)" },
+	customMessageText: { slot: "foreground", description: "Custom message text color" },
+	customMessageLabel: { slot: "foreground", description: "Custom message type label color" },
+	toolPendingBg: { slot: "background", description: "Tool execution box (pending state)" },
+	toolSuccessBg: { slot: "background", description: "Tool execution box (success state)" },
+	toolErrorBg: { slot: "background", description: "Tool execution box (error state)" },
+	toolTitle: { slot: "foreground", description: "Tool execution box title color" },
+	toolOutput: { slot: "foreground", description: "Tool execution box output text color" },
+	mdHeading: { slot: "foreground", description: "Markdown heading text" },
+	mdLink: { slot: "foreground", description: "Markdown link text" },
+	mdLinkUrl: { slot: "foreground", description: "Markdown link URL" },
+	mdCode: { slot: "foreground", description: "Markdown inline code" },
+	mdCodeBlock: { slot: "foreground", description: "Markdown code block content" },
+	mdCodeBlockBorder: { slot: "foreground", description: "Markdown code block fences" },
+	mdQuote: { slot: "foreground", description: "Markdown blockquote text" },
+	mdQuoteBorder: { slot: "foreground", description: "Markdown blockquote border" },
+	mdHr: { slot: "foreground", description: "Markdown horizontal rule" },
+	mdListBullet: { slot: "foreground", description: "Markdown list bullets/numbers" },
+	toolDiffAdded: { slot: "foreground", description: "Added lines in tool diffs" },
+	toolDiffRemoved: { slot: "foreground", description: "Removed lines in tool diffs" },
+	toolDiffContext: { slot: "foreground", description: "Context lines in tool diffs" },
+	syntaxComment: { slot: "foreground", description: "Syntax highlighting: comments" },
+	syntaxKeyword: { slot: "foreground", description: "Syntax highlighting: keywords" },
+	syntaxFunction: { slot: "foreground", description: "Syntax highlighting: function names" },
+	syntaxVariable: { slot: "foreground", description: "Syntax highlighting: variable names" },
+	syntaxString: { slot: "foreground", description: "Syntax highlighting: string literals" },
+	syntaxNumber: { slot: "foreground", description: "Syntax highlighting: number literals" },
+	syntaxType: { slot: "foreground", description: "Syntax highlighting: type names" },
+	syntaxOperator: { slot: "foreground", description: "Syntax highlighting: operators" },
+	syntaxPunctuation: { slot: "foreground", description: "Syntax highlighting: punctuation" },
+	thinkingOff: {
+		slot: "foreground",
+		description: "Thinking level border: off (falls back to border when omitted)",
+		fallback: "border",
+	},
+	thinkingMinimal: {
+		slot: "foreground",
+		description: "Thinking level border: minimal (falls back to thinkingOff when omitted)",
+		fallback: "thinkingOff",
+	},
+	thinkingLow: {
+		slot: "foreground",
+		description: "Thinking level border: low (falls back to thinkingMinimal when omitted)",
+		fallback: "thinkingMinimal",
+	},
+	thinkingMedium: {
+		slot: "foreground",
+		description: "Thinking level border: medium (falls back to thinkingLow when omitted)",
+		fallback: "thinkingLow",
+	},
+	thinkingHigh: {
+		slot: "foreground",
+		description: "Thinking level border: high (falls back to thinkingMedium when omitted)",
+		fallback: "thinkingMedium",
+	},
+	thinkingXhigh: {
+		slot: "foreground",
+		description: "Thinking level border: xhigh (falls back to thinkingHigh when omitted)",
+		fallback: "thinkingHigh",
+	},
+	thinkingMax: {
+		slot: "foreground",
+		description: "Thinking level border: max (falls back to thinkingXhigh when omitted)",
+		fallback: "thinkingXhigh",
+	},
+	bashMode: { slot: "foreground", description: "Editor border color in bash mode" },
+});
+
+export type ThemeToken = keyof typeof THEME_TOKENS;
+export type ThemeColor = {
+	[K in ThemeToken]: (typeof THEME_TOKENS)[K]["slot"] extends "foreground" ? K : never;
+}[ThemeToken];
+export type ThemeBg = Exclude<ThemeToken, ThemeColor>;
+
+type OptionalToken = {
+	[K in ThemeToken]: (typeof THEME_TOKENS)[K] extends { fallback: string } ? K : never;
+}[ThemeToken];
+
+type RequiredToken = Exclude<ThemeToken, OptionalToken>;
+
+export type ThemeColorValues<Value> = {
+	[K in RequiredToken]: Value;
+} & {
+	[K in OptionalToken]?: Value;
+};
+
+export type ResolvedThemeColorValues<Value> = Record<ThemeToken, Value>;