@henryqw/pi-footer 4.2.0 → 5.0.0

package/README.md

@@ -101,9 +101,9 @@ Package-owned: `~/.pi/agent/config/pi-footer/config.json` for footer colors and
 | Name | Description | Values | Default |
 | --- | --- | --- | --- |
 | `colors` | Colors for footer-owned text by role. | Object that maps color roles to theme tokens, `#RGB`, `#RRGGBB`, `oklch(...)`, `okhsl(...)`, or an ANSI index from `0` to `255`. | Built-in colors. |
-| `command` | Command that `/open` runs. Required when the file exists. | Non-empty string. | `"code"` |
+| `command` | Command that `/open` runs. | Non-empty string. | `"code"` |
 
-The footer reads `colors` once per session start; run `/reload` after editing it. The file is never rewritten. A missing file or a missing role keeps the built-in color. At each session start, an invalid file shows a notification with the path and the reason, and the whole color config falls back to the built-in colors.
+The footer reads `colors` once per session start; run `/reload` after editing it. The file is never rewritten. A missing file or a missing role keeps the built-in color. At each session start, an unknown key, an unknown role, or an invalid color shows a warning with the path and the reason. Only the invalid role uses its built-in color. The other roles keep their configured colors. A malformed file uses the built-in colors for all roles.
 
 ### Footer color roles
 
@@ -144,7 +144,7 @@ Theme tokens are `accent`, `dim`, `muted`, `text`, `success`, `warning`, `error`
 
 ### Open command
 
-A missing file silently uses the default command, `code`. An invalid existing file makes `/open` fail visibly and stays unchanged. See Limits and recovery. `/open` reads the config on every run. Only `/set-open-in` writes the file, atomically. Reads do not create or write the config home.
+A missing file silently uses the default command, `code`. An invalid existing file shows a warning and uses `code`. The file stays unchanged. See Limits and recovery. `/open` reads the config on every run. Only `/set-open-in` writes the file, atomically. Reads do not create or write the config home.
 
 ## API
 
@@ -153,7 +153,8 @@ Consumers: use the owner API. Do not read the config file directly. Replace impo
 ```ts
 import { loadOpenInConfig } from "@henryqw/pi-footer/open-uri";
 
-const { source, value } = loadOpenInConfig();
+const loaded = loadOpenInConfig();
+if (loaded.status === "ok") console.log(loaded.value.command, loaded.issues);
 ```
 
 These exports are for package consumers. The commands in Use are the Pi interfaces.
@@ -165,15 +166,15 @@ These exports are for package consumers. The commands in Use are the Pi interfac
 | `loadOpenInConfig(agentDir?)` | function | Reads and validates the owner config. |
 | `configuredOpenUri(path)` | function | Returns a safe VS Code URI for a supported command. |
 
-`loadOpenInConfig` returns `source` as `"missing"` or `"file"`. `value.command` is validated. Pass an agent directory when needed.
+`loadOpenInConfig` returns a `@henryqw/pi-config-store` `ConfigLoad` result: `status`, `source` (`"missing"` or `"file"`), `issues`, and, when `status` is `"ok"`, `value`. `value.command` is validated. An invalid `command` gives `"code"` and an issue. The function does not show issues. Pass an agent directory when needed.
 
-`configuredOpenUri(path)` works when the executable is `code`. With `code -n` or `code --new-window`, it adds `windowId=_blank` so the link opens in a new window. It returns `undefined` for other commands or invalid config. `@henryqw/pi-config-store` owns the config home and storage.
+`configuredOpenUri(path)` works when the executable is `code`. With `code -n` or `code --new-window`, it adds `windowId=_blank` so the link opens in a new window. It returns `undefined` for other commands. An invalid config uses `code`. The function never shows a notification, because the footer calls it on each render. `@henryqw/pi-config-store` owns the config home and storage.
 
 ## Limits and recovery
 
 The open command splits on whitespace into an executable and arguments. Tokens cannot contain spaces, and quoting is unsupported. Use a wrapper script for executables in paths that contain spaces.
 
-An existing config file must be a JSON object with exactly one non-empty string `command` property. Otherwise `/open` fails with a visible error, offers no open URI, and leaves the malformed file unchanged. If the configured command exits with an error, Pi reports its error output or exit code. Fix the command and run `/open` again.
+An existing config file must be a JSON object with one non-empty string `command` property. An unknown key, an invalid `command`, or a malformed file shows a warning at session start, or at the next `/open`. The warning also shows when only the footer is active, because the footer link uses this config. Each issue shows one time in each session, also when the footer and `/open` are both active. The footer render never shows a warning. Then `/open` and the footer link use `code`, and the file stays unchanged. Fix the file or run `/set-open-in <command>` to replace it. `/set-open-in` first shows each new problem in the file that it replaces. If the configured command exits with an error, Pi reports its error output or exit code. Fix the command and run `/open` again.
 
 When the configured executable is `code` and Pi reports hyperlink support, the accent-colored checkout name links to the current path. The link opens a new window for `code -n` or `code --new-window`. A missing config silently uses `code`. Other executables and terminals with hyperlinks disabled render plain text.
 

package/extensions/footer-config.ts

@@ -1,4 +1,4 @@
-import { extensionConfigPath, createConfigStore } from "@henryqw/pi-config-store";
+import { createConfigStore, field, type FieldParser, parsers } from "@henryqw/pi-config-store";
 import { parseColor, type Color } from "@earendil-works/pi-tui";
 import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
 
@@ -37,65 +37,32 @@ export type FooterColorValue = { kind: "token"; token: ThemeColor } | { kind: "c
 
 export type FooterColorConfig = Partial<Record<FooterColorRole, FooterColorValue>>;
 
-function parseColorValue(role: string, raw: unknown): FooterColorValue {
+/** Parses one role's color; a throw drops only that role. */
+export const parseFooterColor: FieldParser<FooterColorValue> = (raw) => {
 	if (typeof raw === "number") {
-		if (!Number.isInteger(raw) || raw < 0 || raw > 255) {
-			throw new Error(`colors.${role}: ANSI index must be an integer from 0 to 255`);
-		}
+		if (!Number.isInteger(raw) || raw < 0 || raw > 255) throw new Error("ANSI index must be an integer from 0 to 255");
 		return { kind: "color", color: parseColor(raw) };
 	}
-	if (typeof raw !== "string" || !raw.trim()) {
-		throw new Error(`colors.${role}: expected a theme token or a color value`);
-	}
+	if (typeof raw !== "string" || !raw.trim()) throw new Error("expected a theme token or a color value");
 	if (THEME_TOKENS.has(raw as ThemeColor)) return { kind: "token", token: raw as ThemeColor };
 	try {
 		return { kind: "color", color: parseColor(raw) };
 	} catch {
-		throw new Error(`colors.${role}: invalid color "${raw}"`);
+		throw new Error(`invalid color "${raw}"`);
 	}
-}
+};
 
-/** Validates and converts the config file; throws on a present-but-invalid file so the caller decides the fallback. */
-export function parseFooterColorConfig(value: unknown): { colors: FooterColorConfig } {
-	if (!value || typeof value !== "object" || Array.isArray(value)) {
-		throw new Error("config must be a JSON object");
-	}
-	const root = value as Record<string, unknown>;
-	const unknown = Object.keys(root).filter((key) => key !== "colors");
-	if (unknown.length > 0) throw new Error(`unknown field(s): ${unknown.join(", ")}`);
-	if (!("colors" in root)) throw new Error('missing "colors" field');
-	if (!root.colors || typeof root.colors !== "object" || Array.isArray(root.colors)) {
-		throw new Error('"colors" must be an object');
-	}
-	const colors: FooterColorConfig = {};
-	for (const [role, raw] of Object.entries(root.colors as Record<string, unknown>)) {
-		if (!FOOTER_COLOR_ROLES.includes(role as FooterColorRole)) {
-			throw new Error(`unknown color role "${role}"`);
-		}
-		colors[role as FooterColorRole] = parseColorValue(role, raw);
-	}
-	return { colors };
-}
-
-function createFooterConfigStore(agentDir?: string) {
-	return createConfigStore<{ colors: FooterColorConfig }>({
+/** A missing file, role, or invalid role keeps the built-in color for that role. */
+export function createFooterConfigStore(agentDir?: string) {
+	return createConfigStore({
 		extensionId: "pi-footer",
 		agentDir,
-		defaults: () => ({ colors: {} }),
-		parse: parseFooterColorConfig,
+		fields: {
+			colors: field(parsers.record(parseFooterColor, { key: parsers.oneOf(FOOTER_COLOR_ROLES) }), {}),
+		},
 	});
 }
 
-/** Reads the color config; a missing file yields empty colors (built-in colors), an invalid file throws. */
-export function loadFooterConfig(agentDir?: string): FooterColorConfig {
-	return createFooterConfigStore(agentDir).loadSync().value.colors;
-}
-
-/** Config file path, used in error notifications. */
-export function footerConfigPath(agentDir?: string): string {
-	return extensionConfigPath("pi-footer", agentDir);
-}
-
 /** An explicit config wins; otherwise fall back to the caller's semantic token. */
 export function paintFooter(theme: Theme, value: FooterColorValue | undefined, fallback: ThemeColor, text: string): string {
 	if (value === undefined) return theme.fg(fallback, text);

package/extensions/footer.ts

@@ -2,8 +2,10 @@ import { readFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 import type { ExtensionAPI, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
 import { getCapabilities, hyperlink, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { registerConfigReporting } from "@henryqw/pi-config-store";
+import { createOpenInConfigStore } from "./open-in-config.ts";
 import { configuredOpenUri } from "./open.ts";
-import { type FooterColorConfig, footerConfigPath, loadFooterConfig, paintFooter } from "./footer-config.ts";
+import { createFooterConfigStore, paintFooter } from "./footer-config.ts";
 
 const THINKING_COLORS = {
 	minimal: 46,
@@ -179,6 +181,10 @@ function latestResponse(ctx: ExtensionContext): { model: string; thinkingLevel?:
 }
 
 export default function footerExtension(pi: ExtensionAPI): void {
+	const colorStore = createFooterConfigStore();
+	// Launch reporting shows color config issues; the session-start read below sees the same file. Renders read
+	// the open-in config for the checkout link but never notify, so its issues show here too, shared with /open.
+	registerConfigReporting(pi, [colorStore, createOpenInConfigStore()]);
 	let activeMilliseconds = 0;
 	let activeStartedAt: number | undefined;
 	let promptPaused = false;
@@ -328,12 +334,8 @@ export default function footerExtension(pi: ExtensionAPI): void {
 		};
 
 		// Colors are read once per session start; /reload applies edits
-		let footerColors: FooterColorConfig = {};
-		try {
-			footerColors = loadFooterConfig();
-		} catch (error) {
-			ctx.ui.notify(`Footer colors ignored (${footerConfigPath()}): ${(error as Error).message}`, "error");
-		}
+		const loadedColors = colorStore.loadSync();
+		const footerColors = loadedColors.status === "ok" ? loadedColors.value.colors : {};
 
 		ctx.ui.setFooter((tui, theme, data) => {
 			requestRuntimeRender = () => tui.requestRender();

package/extensions/open-in-config.ts

@@ -0,0 +1,12 @@
+import { createConfigStore, field, parsers } from "@henryqw/pi-config-store";
+
+const DEFAULT_COMMAND = "code";
+
+/** The open-in config store, shared by the footer link and `/open`. */
+export function createOpenInConfigStore(agentDir?: string) {
+	return createConfigStore({
+		extensionId: "pi-open-in",
+		agentDir,
+		fields: { command: field(parsers.string({ trim: true }), DEFAULT_COMMAND) },
+	});
+}

package/extensions/open.ts

@@ -1,48 +1,20 @@
 import { pathToFileURL } from "node:url";
 import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { createConfigStore } from "@henryqw/pi-config-store";
-
-const DEFAULT_COMMAND = "code";
+import { type ConfigLoad, registerConfigReporting } from "@henryqw/pi-config-store";
+import { createOpenInConfigStore } from "./open-in-config.ts";
 
 export type OpenInConfig = { command: string };
 
-function parseOpenInConfig(value: unknown): OpenInConfig {
-	const config = value as Record<string, unknown>;
-	if (
-		!config ||
-		typeof config !== "object" ||
-		Array.isArray(config) ||
-		Object.keys(config).length !== 1 ||
-		typeof config.command !== "string" ||
-		!config.command.trim()
-	) {
-		throw new Error('Invalid open-in config: expected exactly one non-empty string "command" property');
-	}
-	return { command: config.command.trim() };
-}
-
-function createOpenInConfigStore(agentDir?: string) {
-	return createConfigStore<OpenInConfig>({
-		extensionId: "pi-open-in",
-		agentDir,
-		defaults: () => ({ command: DEFAULT_COMMAND }),
-		parse: parseOpenInConfig,
-	});
-}
-
-export function loadOpenInConfig(agentDir?: string): { source: "file" | "missing"; value: OpenInConfig } {
+/** An invalid or unknown key is an issue; an invalid `command` falls back to `code`. */
+export function loadOpenInConfig(agentDir?: string): ConfigLoad<OpenInConfig> {
 	return createOpenInConfigStore(agentDir).loadSync();
 }
 
+/** Runs on every footer render, so it never notifies; the footer and open extensions report issues at session start. */
 export function configuredOpenUri(path: string): string | undefined {
-	let command: string;
-	try {
-		command = loadOpenInConfig().value.command;
-	} catch {
-		// Invalid config must not break footer render; just omit the URI.
-		return undefined;
-	}
-	const [executable, ...args] = command.split(/\s+/);
+	const loaded = loadOpenInConfig();
+	if (loaded.status === "disabled") return undefined;
+	const [executable, ...args] = loaded.value.command.split(/\s+/);
 	if (executable !== "code") return undefined;
 	const query = args.includes("-n") || args.includes("--new-window") ? "?windowId=_blank" : "";
 	if (path.startsWith("\\\\")) {
@@ -56,12 +28,16 @@ export function configuredOpenUri(path: string): string | undefined {
 
 export default function openInExtension(pi: ExtensionAPI): void {
 	const configStore = createOpenInConfigStore();
+	const reporter = registerConfigReporting(pi, [configStore]);
 
 	// Reload config on each call; split the command on whitespace (no quoted tokens).
 	pi.registerCommand("open", {
 		description: "Open the current path with the configured command",
 		handler: async (_args, ctx) => {
-			const [executable, ...args] = configStore.loadSync().value.command.split(/\s+/);
+			const loaded = configStore.loadSync();
+			reporter.report(ctx, configStore, loaded);
+			if (loaded.status === "disabled") return;
+			const [executable, ...args] = loaded.value.command.split(/\s+/);
 			const result = await pi.exec(executable, [...args, ctx.cwd]);
 			if (result.code !== 0) {
 				throw new Error(`Open command failed: ${result.stderr.trim() || `exit code ${result.code}`}`);
@@ -74,6 +50,8 @@ export default function openInExtension(pi: ExtensionAPI): void {
 		handler: async (args, ctx) => {
 			const command = args.trim();
 			if (!command) throw new Error("Usage: /set-open-in <command>");
+			// The new command replaces the whole file, so first show any problem in the file that it removes.
+			reporter.report(ctx, configStore, configStore.loadSync());
 			await configStore.save({ command });
 			ctx.ui.notify(`Saved open-in command: ${command}`, "info");
 		},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-footer",
-  "version": "4.2.0",
+  "version": "5.0.0",
   "description": "Show repository and usage details in the Pi footer and open the current working directory.",
   "keywords": [
     "pi-package",
@@ -50,7 +50,7 @@
     "image": "https://raw.githubusercontent.com/HenryQW/pi-harness/main/extensions/pi-footer/example.png"
   },
   "dependencies": {
-    "@henryqw/pi-config-store": "^3.0.0"
+    "@henryqw/pi-config-store": "^4.0.0"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "1.1.0",