@xzzpig/pi-starline 0.1.0

package/extensions/starline/pill.ts

@@ -0,0 +1,295 @@
+/**
+ * Pill footer rendering.
+ *
+ * Draws segments as coloured blocks joined by seamless powerline arrows. The
+ * arrow between two pills takes the left pill's background as its foreground
+ * and the right pill's as its background, so the colours meet with no gap. All
+ * colours come from the resolved SGR sequences, never from re-extracted RGB, so
+ * whichever encoding Pi picked for the terminal survives intact.
+ */
+
+import { stripVTControlCharacters } from "node:util";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+import type { ColorSource, ColorSpec } from "./config";
+import type { ExtensionStatusSegment } from "./extension-status";
+import {
+	EXTENSION_STATUS_PREFIX,
+	EXTENSION_STATUS_SEGMENT,
+	PILL_SEGMENT_VARIABLES,
+	type PillConfig,
+} from "./pill-config";
+import { resolveBackgroundSgr, resolveColorSpec, type ThemeLike, toForegroundSgr } from "./style";
+
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const DEFAULT_BG = "\x1b[49m";
+
+/** Text colours are the basic named codes, which every terminal renders correctly. */
+const TEXT_DARK = "\x1b[30m";
+const TEXT_LIGHT = "\x1b[97m";
+
+/** Catppuccin surface1 — the neutral for segments whose spec names no colour. */
+const NEUTRAL_BG = "\x1b[48;2;69;71;90m";
+
+const SEPARATOR_GLYPHS: Record<PillConfig["separator"], string> = {
+	powerline: "",
+	"powerline-thin": "",
+	none: "",
+};
+
+const CAP_GLYPHS = { left: "", right: "" };
+
+/** Divider used where a solid arrow would be invisible. */
+const THIN_SEPARATOR = SEPARATOR_GLYPHS["powerline-thin"];
+
+export type PillInput = {
+	/** Segment name, for diagnostics. */
+	key: string;
+	/** Segment text. Any styling it carries is stripped unless `keepStyling`. */
+	text: string;
+	/** ColorSpec the pill background is resolved from. */
+	spec: ColorSpec;
+	/**
+	 * Keep the text's own SGR instead of recolouring it. Used for extension
+	 * statuses configured with `colorMode: "original"`, whose foreground the
+	 * extension chose. Those get the neutral background so the extension's
+	 * colours stay legible instead of fighting a segment colour.
+	 */
+	keepStyling?: boolean;
+};
+
+function statusInput(
+	status: ExtensionStatusSegment,
+	statusSpec: (key: string) => ColorSpec,
+	statusIcon: (key: string) => string,
+): PillInput {
+	// colorMode "original" keeps the extension's own styling, so leave its text
+	// exactly as it arrived rather than splicing an icon into styled output.
+	if (status.colorMode === "original") {
+		return { key: status.key, text: status.text, spec: "", keepStyling: true };
+	}
+	const icon = statusIcon(status.key);
+	return {
+		key: status.key,
+		text: icon ? `${icon} ${status.text}` : status.text,
+		spec: statusSpec(status.key),
+	};
+}
+
+/**
+ * Turn the configured segment list into pill inputs.
+ *
+ * `extensionStatus` is not one segment but however many other extensions have
+ * registered, so it expands in place — minus any status already placed
+ * explicitly as `extensionStatus:<key>`, which would otherwise appear twice.
+ */
+export function collectPillInputs(
+	segments: string[],
+	statuses: ExtensionStatusSegment[],
+	renderVariable: (name: string) => string,
+	specFor: (segment: string) => ColorSpec,
+	statusSpec: (key: string) => ColorSpec,
+	statusIcon: (key: string) => string = () => "",
+): PillInput[] {
+	const placedKeys = new Set(
+		segments
+			.filter((name) => name.startsWith(EXTENSION_STATUS_PREFIX))
+			.map((name) => name.slice(EXTENSION_STATUS_PREFIX.length)),
+	);
+
+	const inputs: PillInput[] = [];
+	for (const segment of segments) {
+		if (segment === EXTENSION_STATUS_SEGMENT) {
+			for (const status of statuses) {
+				if (!placedKeys.has(status.key)) inputs.push(statusInput(status, statusSpec, statusIcon));
+			}
+			continue;
+		}
+
+		if (segment.startsWith(EXTENSION_STATUS_PREFIX)) {
+			const key = segment.slice(EXTENSION_STATUS_PREFIX.length);
+			const status = statuses.find((candidate) => candidate.key === key);
+			if (status) inputs.push(statusInput(status, statusSpec, statusIcon));
+			continue;
+		}
+
+		const variable = PILL_SEGMENT_VARIABLES[segment];
+		if (!variable) continue;
+		inputs.push({ key: segment, text: renderVariable(variable), spec: specFor(segment) });
+	}
+
+	return inputs;
+}
+
+type PreparedPill = {
+	text: string;
+	bg: string;
+	fg: string;
+	bold: boolean;
+};
+
+const XTERM_CUBE_LEVELS = [0, 95, 135, 175, 215, 255];
+
+const XTERM_BASE_RGB: ReadonlyArray<[number, number, number]> = [
+	[0, 0, 0],
+	[128, 0, 0],
+	[0, 128, 0],
+	[128, 128, 0],
+	[0, 0, 128],
+	[128, 0, 128],
+	[0, 128, 128],
+	[192, 192, 192],
+	[128, 128, 128],
+	[255, 0, 0],
+	[0, 255, 0],
+	[255, 255, 0],
+	[0, 0, 255],
+	[255, 0, 255],
+	[0, 255, 255],
+	[255, 255, 255],
+];
+
+function xterm256ToRgb(index: number): [number, number, number] | undefined {
+	if (index < 0 || index > 255) return undefined;
+	if (index < 16) return XTERM_BASE_RGB[index];
+	if (index < 232) {
+		const offset = index - 16;
+		return [
+			XTERM_CUBE_LEVELS[Math.floor(offset / 36)] ?? 0,
+			XTERM_CUBE_LEVELS[Math.floor((offset % 36) / 6)] ?? 0,
+			XTERM_CUBE_LEVELS[offset % 6] ?? 0,
+		];
+	}
+	const gray = 8 + (index - 232) * 10;
+	return [gray, gray, gray];
+}
+
+/** Recover the RGB a background SGR stands for, when it is knowable. */
+export function backgroundSgrToRgb(bg: string): [number, number, number] | undefined {
+	const truecolor = /^\x1b\[48;2;(\d{1,3});(\d{1,3});(\d{1,3})m$/.exec(bg);
+	if (truecolor) {
+		return [Number(truecolor[1]), Number(truecolor[2]), Number(truecolor[3])];
+	}
+	const palette = /^\x1b\[48;5;(\d{1,3})m$/.exec(bg);
+	if (palette) return xterm256ToRgb(Number(palette[1]));
+
+	const named = /^\x1b\[(4[0-7]|10[0-7])m$/.exec(bg);
+	if (named) {
+		const code = Number(named[1]);
+		return XTERM_BASE_RGB[code >= 100 ? code - 100 + 8 : code - 40];
+	}
+	return undefined;
+}
+
+/**
+ * Pick a legible text colour for a background. Falls back to dark text when the
+ * background's colour cannot be recovered — the case for `\x1b[49m`, where the
+ * terminal's own default background is in play and either choice is a guess.
+ */
+export function contrastTextSgr(bg: string): string {
+	const rgb = backgroundSgrToRgb(bg);
+	if (!rgb) return TEXT_DARK;
+	const [r, g, b] = rgb;
+	const luminance = 0.299 * r + 0.587 * g + 0.114 * b;
+	return luminance >= 128 ? TEXT_DARK : TEXT_LIGHT;
+}
+
+function neutralBackground(theme: ThemeLike, source: ColorSource): string {
+	return resolveBackgroundSgr(theme, source, "borderMuted") ?? NEUTRAL_BG;
+}
+
+function prepare(
+	inputs: PillInput[],
+	theme: ThemeLike,
+	source: ColorSource,
+	config: PillConfig,
+): PreparedPill[] {
+	const neutral = neutralBackground(theme, source);
+	const pills: PreparedPill[] = [];
+
+	for (const input of inputs) {
+		const text = input.keepStyling ? input.text : stripVTControlCharacters(input.text).trim();
+		if (!text || visibleWidth(text) === 0) continue;
+
+		if (input.keepStyling) {
+			pills.push({ text, bg: neutral, fg: "", bold: false });
+			continue;
+		}
+
+		const resolved = resolveColorSpec(theme, source, input.spec);
+		const bg = resolved.bg ?? resolveBackgroundSgr(theme, source, input.spec) ?? neutral;
+		// An explicit fg: in the spec wins; otherwise pick for legibility.
+		pills.push({
+			text,
+			bg,
+			fg: resolved.bg && resolved.fg ? resolved.fg : contrastTextSgr(bg),
+			bold: config.bold || resolved.bold,
+		});
+	}
+
+	return pills;
+}
+
+/**
+ * Render the pill bar. Returns "" when nothing has content, so the caller can
+ * fall back rather than emit a lone pair of caps.
+ */
+export function renderPillBar(
+	inputs: PillInput[],
+	theme: ThemeLike,
+	source: ColorSource,
+	config: PillConfig,
+	width: number,
+	options: { ascii?: boolean } = {},
+): string {
+	const pills = prepare(inputs, theme, source, config);
+	if (pills.length === 0) return "";
+
+	// Nerd Font glyphs are the whole point of the shape; without them the
+	// background transitions alone delineate the segments.
+	const ascii = options.ascii === true;
+	const separator = ascii ? "" : SEPARATOR_GLYPHS[config.separator];
+	const wantsCaps = !ascii && config.caps !== "none";
+	const leftCap = wantsCaps && config.caps === "round" ? CAP_GLYPHS.left : "";
+	const rightCap = wantsCaps ? CAP_GLYPHS.right : "";
+
+	let out = "";
+
+	const firstBg = pills[0]?.bg;
+	if (leftCap && firstBg) {
+		const capFg = toForegroundSgr(firstBg);
+		if (capFg) out += `${DEFAULT_BG}${capFg}${leftCap}${RESET}`;
+	}
+
+	pills.forEach((pill, index) => {
+		out += `${pill.bg}${pill.fg}${pill.bold ? BOLD : ""} ${pill.text} ${RESET}`;
+
+		const next = pills[index + 1];
+		if (next) {
+			if (!separator) return;
+
+			// A solid arrow works by being the left colour on the right colour, so
+			// it vanishes when the two pills share a background — several segments
+			// default to the same theme colour, which merged them into one blob.
+			// Fall back to the thin divider in the text colour, which stays visible.
+			if (pill.bg === next.bg) {
+				out += `${pill.bg}${pill.fg || contrastTextSgr(pill.bg)}${THIN_SEPARATOR}${RESET}`;
+				return;
+			}
+
+			const arrowFg = toForegroundSgr(pill.bg);
+			// Without a usable foreground the arrow would be invisible; letting the
+			// backgrounds abut is better than drawing a glyph in the wrong colour.
+			out += arrowFg ? `${next.bg}${arrowFg}${separator}${RESET}` : "";
+			return;
+		}
+
+		if (rightCap) {
+			const capFg = toForegroundSgr(pill.bg);
+			if (capFg) out += `${DEFAULT_BG}${capFg}${rightCap}${RESET}`;
+		}
+	});
+
+	return width > 0 ? truncateToWidth(out, width, "") : out;
+}

package/extensions/starline/project-refresh.ts

@@ -0,0 +1,104 @@
+export type StopProjectRefreshInterval = () => void;
+
+export type ScheduleProjectRefreshOptions = {
+	force?: boolean;
+};
+
+export type ProjectRefreshScheduler<T> = {
+	schedule: (target: T, options?: ScheduleProjectRefreshOptions) => void;
+	stop: () => void;
+};
+
+export const PROJECT_REFRESH_THROTTLE_MS = 5_000;
+
+export function startProjectRefreshInterval(
+	intervalMs: number,
+	refresh: () => void,
+): StopProjectRefreshInterval {
+	if (intervalMs <= 0) return () => {};
+
+	const timer = setInterval(refresh, intervalMs);
+	timer.unref?.();
+
+	return () => clearInterval(timer);
+}
+
+export function createProjectRefreshScheduler<T>(
+	refresh: (target: T) => Promise<void>,
+	afterRefresh: () => void,
+	throttleMs = PROJECT_REFRESH_THROTTLE_MS,
+): ProjectRefreshScheduler<T> {
+	let refreshInFlight = false;
+	let refreshPending = false;
+	let pendingTarget: T | undefined;
+	let delayedRefresh: ReturnType<typeof setTimeout> | undefined;
+	let lastRefreshStartedAt: number | undefined;
+	let generation = 0;
+
+	const clearDelayedRefresh = () => {
+		if (!delayedRefresh) return;
+		clearTimeout(delayedRefresh);
+		delayedRefresh = undefined;
+	};
+
+	const runRefresh = (target: T) => {
+		clearDelayedRefresh();
+		if (refreshInFlight) {
+			refreshPending = true;
+			pendingTarget = target;
+			return;
+		}
+
+		const currentGeneration = generation;
+		refreshInFlight = true;
+		lastRefreshStartedAt = Date.now();
+		void refresh(target)
+			.catch(() => undefined)
+			.finally(() => {
+				if (currentGeneration !== generation) return;
+				refreshInFlight = false;
+				afterRefresh();
+				if (refreshPending) {
+					refreshPending = false;
+					const nextTarget = pendingTarget ?? target;
+					pendingTarget = undefined;
+					schedule(nextTarget);
+				}
+			});
+	};
+
+	const schedule = (target: T, options: ScheduleProjectRefreshOptions = {}) => {
+		if (options.force || throttleMs <= 0 || lastRefreshStartedAt === undefined) {
+			runRefresh(target);
+			return;
+		}
+
+		const delayMs = Math.max(0, throttleMs - (Date.now() - lastRefreshStartedAt));
+		if (delayMs === 0) {
+			runRefresh(target);
+			return;
+		}
+
+		pendingTarget = target;
+		if (delayedRefresh) return;
+		delayedRefresh = setTimeout(() => {
+			delayedRefresh = undefined;
+			const nextTarget = pendingTarget ?? target;
+			pendingTarget = undefined;
+			runRefresh(nextTarget);
+		}, delayMs);
+		delayedRefresh.unref?.();
+	};
+
+	return {
+		schedule,
+		stop() {
+			generation += 1;
+			clearDelayedRefresh();
+			refreshInFlight = false;
+			refreshPending = false;
+			pendingTarget = undefined;
+			lastRefreshStartedAt = undefined;
+		},
+	};
+}

package/extensions/starline/project-state.ts

@@ -0,0 +1,66 @@
+import type { GitHost, GitReadResult } from "./git";
+import { emptyGitStatus } from "./git";
+import type { PackageVersionReadResult } from "./package-version";
+import type { RuntimeReadResult } from "./runtime";
+import type { FooterState } from "./state";
+
+/**
+ * Apply a project refresh (git + runtime) onto footer state, preserving
+ * last-good values on transient errors and clearing on cwd change / not-a-repo.
+ *
+ * Returns the cwd to store as `previousCwd` for the next refresh.
+ */
+export function applyProjectRefreshToState(
+	state: FooterState,
+	args: {
+		cwd: string;
+		previousCwd: string | undefined;
+		git: GitReadResult;
+		gitHost?: GitHost;
+		runtime: RuntimeReadResult;
+		packageVersion?: PackageVersionReadResult;
+	},
+): string {
+	const cwdChanged = args.previousCwd !== undefined && args.previousCwd !== args.cwd;
+
+	if (cwdChanged) {
+		Object.assign(state, emptyGitStatus());
+		state.runtime = undefined;
+		state.gitHost = undefined;
+		state.packageVersion = undefined;
+	}
+
+	// Undefined means "not asked for this refresh" — keep the last-good value
+	// rather than dropping the icon whenever gitHostIcon is off.
+	if (args.gitHost !== undefined) state.gitHost = args.gitHost;
+	if (args.git.kind === "not_a_repo") state.gitHost = undefined;
+
+	if (args.git.kind === "ok") {
+		Object.assign(state, args.git.status);
+	} else if (args.git.kind === "not_a_repo") {
+		Object.assign(state, emptyGitStatus());
+	}
+	// kind === "error": keep previous git fields (unless cwdChanged already cleared)
+
+	if (args.runtime.kind === "ok") {
+		state.runtime = args.runtime.runtime;
+	} else if (cwdChanged && args.runtime.kind === "error") {
+		// Already cleared above; keep undefined.
+		state.runtime = undefined;
+	}
+	// error + same cwd: keep previous runtime
+
+	if (args.packageVersion !== undefined) {
+		if (args.packageVersion.kind === "ok") {
+			// `null` means "no manifest in this cwd"; clear so the segment disappears
+			// even on the same cwd when the user removes their manifest.
+			state.packageVersion = args.packageVersion.result ?? undefined;
+		} else if (!cwdChanged) {
+			// error + same cwd: keep previous packageVersion (last-good semantics)
+		} else {
+			state.packageVersion = undefined;
+		}
+	}
+
+	return args.cwd;
+}

package/extensions/starline/prototype-patch-registry.ts

@@ -0,0 +1,136 @@
+export const STARLINE_PROTOTYPE_PATCH_REGISTRY = Symbol.for("pi-starline.prototype-patch-registry");
+
+/**
+ * The key this package used before it was renamed from pi-zentui. Read AND
+ * written, alongside the new key: package load order is not controlled by
+ * either side, so whichever of pi-starline/pi-zentui creates the registry
+ * first must expose it under both keys. Otherwise a pi-starline-first load
+ * (the common order, since it sorts first alphabetically) would leave a
+ * later-loading pi-zentui unable to find it, and each package would patch a
+ * prototype the other has already patched.
+ */
+const LEGACY_PROTOTYPE_PATCH_REGISTRY = Symbol.for("pi-zentui.prototype-patch-registry");
+
+type PrototypePatchAdapter =
+	| "user-message-render"
+	| "user-message-invalidate"
+	| "selector-border-render"
+	| "mouse-viewport-input"
+	| "mouse-wheel"
+	| "mouse-selection-event"
+	| "mouse-copy"
+	| "mouse-word-selection";
+
+type PrototypeMethodName = string;
+
+type PrototypeMethod = (this: unknown, ...args: unknown[]) => unknown;
+
+type PatchInvocation = {
+	predecessor: PrototypeMethod;
+	receiver: unknown;
+	args: unknown[];
+};
+
+type PatchBehavior = (invocation: PatchInvocation) => unknown;
+
+type Registration = {
+	token: symbol;
+	behavior?: PatchBehavior;
+};
+
+type PatchRecord = {
+	method: PrototypeMethodName;
+	predecessor: PrototypeMethod;
+	wrapper: PrototypeMethod;
+	registration?: Registration;
+};
+
+type PatchRegistry = Map<PrototypePatchAdapter, PatchRecord>;
+
+type PatchTarget = Record<PropertyKey, unknown>;
+
+function registryFor(target: PatchTarget): PatchRegistry {
+	const existing =
+		target[STARLINE_PROTOTYPE_PATCH_REGISTRY] ?? target[LEGACY_PROTOTYPE_PATCH_REGISTRY];
+	if (existing instanceof Map) return existing as PatchRegistry;
+	const registry: PatchRegistry = new Map();
+	// One Map, exposed under both keys, so whichever package looks second
+	// (in either load order) adopts this same registry instead of creating
+	// its own and double-patching.
+	Object.defineProperty(target, STARLINE_PROTOTYPE_PATCH_REGISTRY, {
+		value: registry,
+		configurable: true,
+	});
+	Object.defineProperty(target, LEGACY_PROTOTYPE_PATCH_REGISTRY, {
+		value: registry,
+		configurable: true,
+	});
+	return registry;
+}
+
+function createCleanup(
+	target: PatchTarget,
+	method: PrototypeMethodName,
+	adapter: PrototypePatchAdapter,
+	registry: PatchRegistry,
+	record: PatchRecord,
+	token: symbol,
+): () => void {
+	let cleaned = false;
+	return () => {
+		if (cleaned) return;
+		cleaned = true;
+		if (record.registration?.token !== token) return;
+		record.registration.behavior = undefined;
+		record.registration = undefined;
+
+		const current = registry.get(adapter);
+		if (current !== record) return;
+		if (target[method] === record.wrapper) target[method] = record.predecessor;
+		registry.delete(adapter);
+		if (registry.size === 0) {
+			delete target[STARLINE_PROTOTYPE_PATCH_REGISTRY];
+			delete target[LEGACY_PROTOTYPE_PATCH_REGISTRY];
+		}
+	};
+}
+
+export function installPrototypePatch(
+	targetValue: object,
+	method: PrototypeMethodName,
+	adapter: PrototypePatchAdapter,
+	behavior: PatchBehavior,
+): () => void {
+	const target = targetValue as PatchTarget;
+	const registry = registryFor(target);
+	let record = registry.get(adapter);
+
+	if (!(record && record.method === method && target[method] === record.wrapper)) {
+		const predecessor = target[method];
+		if (typeof predecessor !== "function") {
+			throw new TypeError(`Cannot patch ${method}: predecessor is not a function`);
+		}
+		const nextRecord: PatchRecord = {
+			method,
+			predecessor: predecessor as PrototypeMethod,
+			wrapper: () => undefined,
+		};
+		const wrapper: PrototypeMethod = function starlinePrototypeWrapper(
+			this: unknown,
+			...args: unknown[]
+		): unknown {
+			const activeBehavior = nextRecord.registration?.behavior;
+			return activeBehavior
+				? activeBehavior({ predecessor: nextRecord.predecessor, receiver: this, args })
+				: Reflect.apply(nextRecord.predecessor, this, args);
+		};
+		nextRecord.wrapper = wrapper;
+		record = nextRecord;
+		registry.set(adapter, record);
+		target[method] = wrapper;
+	}
+
+	const token = Symbol(adapter);
+	record.registration = { token, behavior };
+	return createCleanup(target, method, adapter, registry, record, token);
+}