rinco-pi-hud 1.0.0

package/extensions/hud/config/persist.ts

@@ -0,0 +1,277 @@
+/**
+ * `save*Patch` functions: validate a partial settings patch, merge it into
+ * the on-disk config record via `mutateConfig`, and return the freshly
+ * merged `PolishedTuiConfig`. Each function only accepts fields/values that
+ * pass the corresponding type guard, so callers (e.g. the `/zentui` settings
+ * UI) cannot write malformed values into the config file.
+ */
+import { normalizeIconMode } from "../ui/icons.js";
+import { mutateConfig } from "./file-io.js";
+import {
+	isExtensionStatusColorMode,
+	isExtensionStatusPlacement,
+	isRecord,
+	normalizeGitBranchMaxLength,
+	parseContextStyle,
+	parseSeparatorStyle,
+	sanitizeConfigText,
+} from "./normalize.js";
+import {
+	configPath,
+	type ColorSource,
+	type ColorSourcesConfig,
+	type ContextStyle,
+	type ContextThresholds,
+	type ExtensionStatusColorMode,
+	type ExtensionStatusPlacement,
+	type FooterSegmentsConfig,
+	type GitBranchConfig,
+	type IconMode,
+	type PathDisplayConfig,
+	type PolishedTuiConfig,
+	type SeparatorStyle,
+	type UiFeaturesConfig,
+} from "./schema.js";
+
+function isColorSourceKey(value: string): value is keyof ColorSourcesConfig {
+	return value === "starship";
+}
+
+function isUiFeatureKey(value: string): value is keyof UiFeaturesConfig {
+	return value === "statusLine";
+}
+
+function isFooterSegmentKey(value: string): value is keyof FooterSegmentsConfig {
+	return (
+		value === "cwd" ||
+		value === "gitBranch" ||
+		value === "gitStatus" ||
+		value === "gitCounts" ||
+		value === "runtime" ||
+		value === "context" ||
+		value === "tokens" ||
+		value === "cost" ||
+		value === "sessionDuration" ||
+		value === "username" ||
+		value === "time" ||
+		value === "os" ||
+		value === "packageVersion" ||
+		value === "gitCommit" ||
+		value === "gitMetrics" ||
+		value === "sessionName" ||
+		value === "model" ||
+		value === "thinking" ||
+		value === "turnCount" ||
+		value === "cacheDetails" ||
+		value === "codexUsage" ||
+		value === "configCounts" ||
+		value === "skills" ||
+		value === "mcp" ||
+		value === "toolActivity" ||
+		value === "agentActivity"
+	);
+}
+
+function validColorSourceEntries(record: Record<string, unknown>): Partial<ColorSourcesConfig> {
+	return Object.fromEntries(
+		Object.entries(record).filter((entry): entry is [keyof ColorSourcesConfig, ColorSource] => {
+			const [key, value] = entry;
+			return isColorSourceKey(key) && (value === "theme" || value === "terminal");
+		}),
+	) as Partial<ColorSourcesConfig>;
+}
+
+function validUiFeatureEntries(record: Record<string, unknown>): Partial<UiFeaturesConfig> {
+	return Object.fromEntries(
+		Object.entries(record).filter((entry): entry is [keyof UiFeaturesConfig, boolean] => {
+			const [key, value] = entry;
+			return isUiFeatureKey(key) && typeof value === "boolean";
+		}),
+	) as Partial<UiFeaturesConfig>;
+}
+
+function validFooterSegmentEntries(record: Record<string, unknown>): Partial<FooterSegmentsConfig> {
+	return Object.fromEntries(
+		Object.entries(record).filter((entry): entry is [keyof FooterSegmentsConfig, boolean] => {
+			const [key, value] = entry;
+			return isFooterSegmentKey(key) && typeof value === "boolean";
+		}),
+	) as Partial<FooterSegmentsConfig>;
+}
+
+export function saveColorSourcesPatch(
+	patch: Partial<ColorSourcesConfig>,
+	path = configPath,
+): PolishedTuiConfig {
+	return mutateConfig(path, (record) => {
+		const existing = isRecord(record.colorSources)
+			? { ...(record.colorSources as Record<string, unknown>) }
+			: {};
+		record.colorSources = {
+			...existing,
+			...validColorSourceEntries(patch),
+		};
+	});
+}
+
+export function saveUiFeaturesPatch(
+	patch: Partial<UiFeaturesConfig>,
+	path = configPath,
+): PolishedTuiConfig {
+	return mutateConfig(path, (record) => {
+		const existing = isRecord(record.features)
+			? { ...(record.features as Record<string, unknown>) }
+			: {};
+		record.features = {
+			...existing,
+			...validUiFeatureEntries(patch),
+		};
+	});
+}
+
+export function saveFooterSegmentsPatch(
+	patch: Partial<FooterSegmentsConfig>,
+	path = configPath,
+): PolishedTuiConfig {
+	return mutateConfig(path, (record) => {
+		const existing = isRecord(record.footerSegments)
+			? { ...(record.footerSegments as Record<string, unknown>) }
+			: {};
+		record.footerSegments = {
+			...existing,
+			...validFooterSegmentEntries(patch),
+		};
+	});
+}
+
+export function saveFooterFormatPatch(value: string, path = configPath): PolishedTuiConfig {
+	return mutateConfig(path, (record) => {
+		record.footerFormat = typeof value === "string" ? sanitizeConfigText(value, 4096) : "";
+	});
+}
+
+export function saveIconsModePatch(mode: IconMode, path = configPath): PolishedTuiConfig {
+	return mutateConfig(path, (record) => {
+		const existing = isRecord(record.icons) ? { ...(record.icons as Record<string, unknown>) } : {};
+		record.icons = {
+			...existing,
+			mode: normalizeIconMode(mode),
+		};
+	});
+}
+
+export function saveContextStylePatch(style: ContextStyle, path = configPath): PolishedTuiConfig {
+	return mutateConfig(path, (record) => {
+		record.contextStyle = parseContextStyle(style);
+	});
+}
+
+export function saveSeparatorPatch(
+	separator: SeparatorStyle,
+	path = configPath,
+): PolishedTuiConfig {
+	return mutateConfig(path, (record) => {
+		record.separator = parseSeparatorStyle(separator);
+	});
+}
+
+export function saveContextThresholdsPatch(
+	thresholds: Partial<ContextThresholds>,
+	path = configPath,
+): PolishedTuiConfig {
+	return mutateConfig(path, (record) => {
+		const existing = isRecord(record.contextThresholds)
+			? { ...(record.contextThresholds as Record<string, unknown>) }
+			: {};
+		record.contextThresholds = {
+			...existing,
+			...thresholds,
+		};
+	});
+}
+
+export function savePathDisplayPatch(
+	patch: Partial<PathDisplayConfig>,
+	path = configPath,
+): PolishedTuiConfig {
+	return mutateConfig(path, (record) => {
+		const existing = isRecord(record.pathDisplay)
+			? { ...(record.pathDisplay as Record<string, unknown>) }
+			: {};
+		if (patch.mode !== undefined) existing.mode = patch.mode;
+		if (patch.depth !== undefined) existing.depth = patch.depth;
+		record.pathDisplay = existing;
+	});
+}
+
+export function saveGitBranchPatch(
+	patch: Partial<GitBranchConfig>,
+	path = configPath,
+): PolishedTuiConfig {
+	return mutateConfig(path, (record) => {
+		const existing = isRecord(record.gitBranch)
+			? { ...(record.gitBranch as Record<string, unknown>) }
+			: {};
+		if (patch.maxLength !== undefined)
+			existing.maxLength = normalizeGitBranchMaxLength(patch.maxLength);
+		record.gitBranch = existing;
+	});
+}
+
+export function saveExtensionStatusPlacement(
+	key: string,
+	placement: ExtensionStatusPlacement,
+	path = configPath,
+): PolishedTuiConfig {
+	return mutateConfig(path, (record) => {
+		const existingExtensionStatuses = isRecord(record.extensionStatuses)
+			? { ...(record.extensionStatuses as Record<string, unknown>) }
+			: {};
+		const existingPlacements = isRecord(existingExtensionStatuses.placements)
+			? { ...(existingExtensionStatuses.placements as Record<string, unknown>) }
+			: {};
+
+		if (!isExtensionStatusPlacement(placement)) return;
+
+		Object.defineProperty(existingPlacements, key, {
+			value: placement,
+			enumerable: true,
+			configurable: true,
+			writable: true,
+		});
+
+		record.extensionStatuses = {
+			...existingExtensionStatuses,
+			placements: existingPlacements,
+		};
+	});
+}
+
+export function saveExtensionStatusColorMode(
+	key: string,
+	colorMode: ExtensionStatusColorMode,
+	path = configPath,
+): PolishedTuiConfig {
+	return mutateConfig(path, (record) => {
+		const existingExtensionStatuses = isRecord(record.extensionStatuses)
+			? { ...(record.extensionStatuses as Record<string, unknown>) }
+			: {};
+		const existingColorModes = isRecord(existingExtensionStatuses.colorModes)
+			? { ...(existingExtensionStatuses.colorModes as Record<string, unknown>) }
+			: {};
+
+		if (!isExtensionStatusColorMode(colorMode)) return;
+
+		Object.defineProperty(existingColorModes, key, {
+			value: colorMode,
+			enumerable: true,
+			configurable: true,
+			writable: true,
+		});
+
+		record.extensionStatuses = {
+			...existingExtensionStatuses,
+			colorModes: existingColorModes,
+		};
+	});
+}

package/extensions/hud/config/schema.ts

@@ -0,0 +1,303 @@
+/**
+ * Zentui config schema: types, format-string vocabulary, and defaults.
+ *
+ * Pure data/types module — no file I/O, no normalization logic. Parsing
+ * untrusted JSON into this shape lives in `normalize.ts`; reading/writing the
+ * config file lives in `file-io.ts`.
+ */
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import { NERD_DEFAULT_ICONS, type ResolvedIcons } from "../ui/icons.js";
+
+export type ColorSpec = string;
+export type ColorSource = "theme" | "terminal";
+export type { IconMode } from "../ui/icons.js";
+
+export type ContextStyle = "text" | "gauge" | "text+gauge";
+export type SeparatorStyle = "pipe" | "dot" | "chevron" | "none";
+
+export type ContextThresholds = {
+	warning: number;
+	error: number;
+};
+
+export type PathDisplayMode = "basename" | "full";
+
+export type PathDisplayConfig = {
+	mode: PathDisplayMode;
+	/** Trailing directories to show in full mode. 0 = unlimited; clamped to 0..5. */
+	depth: number;
+};
+
+export type GitBranchMaxLength = "full" | number;
+
+export type GitBranchConfig = {
+	maxLength: GitBranchMaxLength;
+};
+
+export type ColorSourcesConfig = {
+	starship: ColorSource;
+};
+
+export type UiFeaturesConfig = {
+	statusLine: boolean;
+};
+
+export type FooterSegmentsConfig = {
+	cwd: boolean;
+	gitBranch: boolean;
+	gitStatus: boolean;
+	gitCounts: boolean;
+	gitCommit: boolean;
+	gitMetrics: boolean;
+	runtime: boolean;
+	context: boolean;
+	tokens: boolean;
+	cost: boolean;
+	sessionDuration: boolean;
+	username: boolean;
+	time: boolean;
+	os: boolean;
+	packageVersion: boolean;
+	sessionName: boolean;
+	model: boolean;
+	thinking: boolean;
+	turnCount: boolean;
+	cacheDetails: boolean;
+	codexUsage: boolean;
+	configCounts: boolean;
+	skills: boolean;
+	mcp: boolean;
+	toolActivity: boolean;
+	agentActivity: boolean;
+};
+
+export type ExtensionStatusPlacement = "off" | "left" | "middle" | "right";
+export type ExtensionStatusColorMode = "zentui" | "original";
+
+/**
+ * Starship `git_commit`-style options.
+ * See https://starship.rs/config/#git-commit
+ */
+export type GitCommitConfig = {
+	hashLength: number;
+	onlyDetached: boolean;
+	showTag: boolean;
+};
+
+/**
+ * Starship `git_metrics`-style options.
+ * See https://starship.rs/config/#git-metrics
+ */
+export type GitMetricsConfig = {
+	onlyNonzero: boolean;
+	ignoreSubmodules: boolean;
+};
+
+export const DEFAULT_EXTENSION_STATUS_COLOR_MODE: ExtensionStatusColorMode = "zentui";
+
+export type ExtensionStatusesConfig = {
+	defaultPlacement: ExtensionStatusPlacement;
+	placements: Record<string, ExtensionStatusPlacement>;
+	colorModes: Record<string, ExtensionStatusColorMode>;
+};
+
+export const DEFAULT_PROJECT_REFRESH_INTERVAL_MS = 30_000;
+export const MIN_PROJECT_REFRESH_INTERVAL_MS = 5_000;
+
+export type PolishedTuiConfig = {
+	projectRefreshIntervalMs: number;
+	footerFormat: string;
+	separator: SeparatorStyle;
+	contextStyle: ContextStyle;
+	contextThresholds: ContextThresholds;
+	pathDisplay: PathDisplayConfig;
+	gitBranch: GitBranchConfig;
+	icons: ResolvedIcons;
+	colors: {
+		cwd: ColorSpec;
+		gitBranch: ColorSpec;
+		gitStatus: ColorSpec;
+		contextNormal: ColorSpec;
+		contextWarning: ColorSpec;
+		contextError: ColorSpec;
+		tokens: ColorSpec;
+		cost: ColorSpec;
+		separator: ColorSpec;
+		runtimePrefix: ColorSpec;
+		extensionStatus: ColorSpec;
+		sessionDuration: ColorSpec;
+		packageVersion: ColorSpec;
+		gitCommit: ColorSpec;
+		gitMetricsAdded: ColorSpec;
+		gitMetricsDeleted: ColorSpec;
+		username: ColorSpec;
+		time: ColorSpec;
+		os: ColorSpec;
+		muted: ColorSpec;
+	};
+	colorSources: ColorSourcesConfig;
+	features: UiFeaturesConfig;
+	footerSegments: FooterSegmentsConfig;
+	gitCommit: GitCommitConfig;
+	gitMetrics: GitMetricsConfig;
+	extensionStatuses: ExtensionStatusesConfig;
+};
+
+/**
+ * Canonical footer format variable names. In a `footerFormat` string these
+ * are written as `$name` or `${name}`.
+ */
+export const FOOTER_FORMAT_VARIABLES = [
+	"cwd",
+	"git_branch",
+	"git_status",
+	"git_state",
+	"runtime",
+	"session_duration",
+	"username",
+	"os",
+	"time",
+	"context",
+	"tokens",
+	"cost",
+	"package",
+	"package_version",
+	"git_commit",
+	"git_tag",
+	"git_metrics",
+	"git_added",
+	"git_deleted",
+	"session_name",
+	"model",
+	"provider",
+	"model_id",
+	"thinking",
+	"turn",
+	"cache_read",
+	"cache_write",
+	"cache_hit",
+	"codex_usage",
+	"instruction_files",
+	"agents_files",
+	"claude_files",
+	"skills",
+	"active_skills",
+	"extensions",
+	"mcp",
+	"tool_counts",
+	"running_tools",
+	"active_agents",
+	"sep",
+] as const;
+
+/**
+ * Alias → canonical variable name mapping for `footerFormat`.
+ * `$fill` is special (not a variable) and handled by the parser.
+ */
+export const FOOTER_FORMAT_ALIASES: Record<string, string> = {
+	directory: "cwd",
+	branch: "git_branch",
+	status: "git_status",
+	state: "git_state",
+	commit: "git_commit",
+	tag: "git_tag",
+	duration: "session_duration",
+	session: "session_name",
+	thinking_level: "thinking",
+	turn_count: "turn",
+	codex: "codex_usage",
+	tools: "tool_counts",
+	agents: "active_agents",
+	separator: "sep",
+};
+
+export const configPath = join(getAgentDir(), "rinco-pi-hud.json");
+
+export const defaultConfig: PolishedTuiConfig = {
+	projectRefreshIntervalMs: DEFAULT_PROJECT_REFRESH_INTERVAL_MS,
+	footerFormat: "",
+	separator: "chevron",
+	contextStyle: "text+gauge",
+	contextThresholds: { warning: 70, error: 90 },
+	pathDisplay: { mode: "basename", depth: 0 },
+	gitBranch: { maxLength: 30 },
+	icons: {
+		mode: "auto",
+		...NERD_DEFAULT_ICONS,
+	},
+	colors: {
+		cwd: "bold #F2A7C6",
+		gitBranch: "bold #C7B8F5",
+		gitStatus: "bold #F6BC9A",
+		contextNormal: "#AEE5C5",
+		contextWarning: "bold #F3D98B",
+		contextError: "bold #FF8FA3",
+		tokens: "#A99BAE",
+		cost: "bold #AEE5C5",
+		separator: "#716879",
+		runtimePrefix: "#9FD3F2",
+		extensionStatus: "#EFC3E6",
+		sessionDuration: "#F3D98B",
+		packageVersion: "#F6BC9A",
+		gitCommit: "#AEE5C5",
+		gitMetricsAdded: "#AEE5C5",
+		gitMetricsDeleted: "#FF8FA3",
+		username: "#F3D98B",
+		time: "#F3D98B",
+		os: "#F7EEF8",
+		muted: "#A99BAE",
+	},
+	colorSources: {
+		starship: "terminal",
+	},
+	features: {
+		statusLine: true,
+	},
+	footerSegments: {
+		cwd: true,
+		gitBranch: true,
+		gitStatus: true,
+		gitCounts: false,
+		runtime: true,
+		context: true,
+		tokens: true,
+		cost: true,
+		sessionDuration: false,
+		username: false,
+		time: false,
+		os: true,
+		packageVersion: false,
+		gitCommit: false,
+		gitMetrics: false,
+		sessionName: true,
+		model: true,
+		thinking: true,
+		turnCount: true,
+		cacheDetails: true,
+		codexUsage: true,
+		configCounts: false,
+		skills: true,
+		mcp: true,
+		toolActivity: true,
+		agentActivity: true,
+	},
+	gitCommit: {
+		hashLength: 7,
+		onlyDetached: true,
+		showTag: true,
+	},
+	gitMetrics: {
+		onlyNonzero: true,
+		ignoreSubmodules: false,
+	},
+	extensionStatuses: {
+		defaultPlacement: "right",
+		placements: {
+			"dual-subscription-quota": "left",
+			"codex-goal": "middle",
+			"xai-usage": "right",
+		},
+		colorModes: {},
+	},
+};