pi-cc-loop 0.4.0 → 0.5.0

package/README.md

@@ -38,7 +38,7 @@ ln -sfn "$PWD" ~/.pi/agent/extensions/pi-cc-loop
 | 次数上限 | `maxFires`，到顶自动删除 | `--max N` |
 | 持久化 | `durable: true` 写入 `.pi/scheduled_tasks.json`，重启后继续；同一项目只由一个 Pi 会话执行 | `--durable` |
 | 底部摘要 | Pi 底部状态栏一行：`loop 2 · next 3m`，无任务时不占位 | `/loop footer on\|off` |
-| 界面设置 | 本地命令，不进对话 | `/loop settings ...` |
+| 界面设置 | 和 Pi 的 `/settings` 一样的面板，本地命令，不进对话 | `/loop settings` |
 
 ## 命令
 
@@ -49,7 +49,7 @@ ln -sfn "$PWD" ~/.pi/agent/extensions/pi-cc-loop
 /loop status              列出当前任务
 /loop stop [id]           停止一个或全部
 /loop footer on|off       本地：底部摘要
-/loop settings ...        本地：界面设置
+/loop settings            本地：设置面板
 /loop help                本地：帮助
 ```
 
@@ -86,7 +86,7 @@ Ctrl+O 展开后多一行元信息（任务 id、节奏）。`compactMessages`
 
 ## 设置
 
-两个 pi-cc 扩展共用 `~/.pi/agent/pi-cc.json`，文件不存在时用默认值：
+两个 pi-cc 扩展共用 Pi 配置目录下的 `pi-cc.json`（默认 `~/.pi/agent/pi-cc.json`，跟随 `PI_CODING_AGENT_DIR`），文件不存在时用默认值：
 
 ```jsonc
 {
@@ -95,7 +95,28 @@ Ctrl+O 展开后多一行元信息（任务 id、节奏）。`compactMessages`
 }
 ```
 
-用 `/loop settings messages on|off`、`/loop settings footer on|off`（或 `/loop footer on|off`）切换，两个扩展同时生效。
+在 TUI 里输入 `/loop settings` 会打开设置面板，样子和操作都和 Pi 的 `/settings` 一样：上下键选择，Enter/空格切换，Esc 关闭；
+改动立即保存，两个扩展同时生效。Pi 的 `/settings` 不接受扩展加项，所以面板放在 `/loop settings` 下。
+
+```text
+─────────────────────────────────────────────────────────────
+pi-cc settings · ~/.pi/agent/pi-cc.json
+
+→ Message style   compact
+  Footer summary  on
+
+  How scheduled fires and Monitor events are drawn. compact: ✻ header
+  and indented body; card: the old padded card.
+
+  Enter/Space to change · Esc to cancel
+─────────────────────────────────────────────────────────────
+```
+
+也可以用文字命令：`/loop settings messages on|off`、`/loop settings footer on|off`（或 `/loop footer on|off`），适合脚本和 RPC；
+非 TUI 模式下，不带参数的 `/loop settings` 输出当前设置。命令只写改动的那一项，文件里的其他内容原样保留。
+
+环境变量 `PI_CC_FOOTER`、`PI_CC_COMPACT_MESSAGES` 优先于文件，但不会被写进文件。设着的时候，面板里这一项显示实际生效的值、不能切换，
+说明里写出是哪个变量；文字输出会在对应项后面标出来（如 `hidden (PI_CC_FOOTER=0)`）；用文字命令切换会写进文件，但提示会说明变量还在覆盖它。
 
 ## 底部摘要
 
@@ -124,7 +145,7 @@ Ctrl+O 展开后多一行元信息（任务 id、节奏）。`compactMessages`
 | `PI_LOOP_DURABLE_SYNC_MS` | `5000` | 持久化任务文件的同步间隔 |
 | `PI_CC_FOOTER` | — | `0` / `1`，覆盖设置文件里的 `footer` |
 | `PI_CC_COMPACT_MESSAGES` | — | `0` / `1`，覆盖设置文件里的 `compactMessages` |
-| `PI_CC_CONFIG_FILE` | `~/.pi/agent/pi-cc.json` | 设置文件路径 |
+| `PI_CC_CONFIG_FILE` | `~/.pi/agent/pi-cc.json` | 设置文件路径；不设时在 Pi 的配置目录里，跟随 `PI_CODING_AGENT_DIR` |
 
 ## 兼容性
 

package/config.ts

@@ -3,7 +3,8 @@
  *
  * Both pi-cc-loop and pi-cc-monitor read the same small JSON file so a single
  * toggle changes the look of both packages. The file is optional; when it is
- * missing or malformed the defaults apply.
+ * missing or malformed the defaults apply. It sits in Pi's agent directory
+ * (PI_CODING_AGENT_DIR, default ~/.pi/agent), next to Pi's own settings.
  *
  *   ~/.pi/agent/pi-cc.json
  *   {
@@ -11,14 +12,15 @@
  *     "footer": true
  *   }
  *
- * Environment overrides (useful for tests and quick experiments):
+ * Environment overrides (useful for tests and quick experiments) win over the
+ * file while they are set, and are never written to it:
  *   PI_CC_CONFIG_FILE=/path/to/pi-cc.json
  *   PI_CC_COMPACT_MESSAGES=0|1
  *   PI_CC_FOOTER=0|1
  */
 
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 
 export interface PiCcConfig {
@@ -36,6 +38,12 @@ export const DEFAULT_CONFIG: PiCcConfig = {
 	footer: true,
 };
 
+/** The environment variable that overrides each setting. */
+const ENV_OVERRIDES: Record<keyof PiCcConfig, string> = {
+	compactMessages: "PI_CC_COMPACT_MESSAGES",
+	footer: "PI_CC_FOOTER",
+};
+
 function envBool(name: string): boolean | undefined {
 	const raw = process.env[name];
 	if (raw === undefined) return undefined;
@@ -44,11 +52,16 @@ function envBool(name: string): boolean | undefined {
 	return undefined;
 }
 
-/** The settings file shared by pi-cc-loop and pi-cc-monitor. */
+/** The variable overriding a setting right now, as `PI_CC_FOOTER=0`; undefined when none is. */
+export function envOverride(key: keyof PiCcConfig): string | undefined {
+	const name = ENV_OVERRIDES[key];
+	return envBool(name) === undefined ? undefined : `${name}=${process.env[name]}`;
+}
+
+/** The settings file shared by pi-cc-loop and pi-cc-monitor, in Pi's agent directory. */
 export function configPath(): string {
 	if (process.env.PI_CC_CONFIG_FILE) return process.env.PI_CC_CONFIG_FILE;
-	const agentDir = process.env.PI_AGENT_DIR ?? path.join(os.homedir(), ".pi", "agent");
-	return path.join(agentDir, "pi-cc.json");
+	return path.join(getAgentDir(), "pi-cc.json");
 }
 
 function readConfig(): PiCcConfig {
@@ -61,10 +74,10 @@ function readConfig(): PiCcConfig {
 	}
 	return {
 		compactMessages:
-			envBool("PI_CC_COMPACT_MESSAGES") ??
+			envBool(ENV_OVERRIDES.compactMessages) ??
 			(typeof file.compactMessages === "boolean" ? file.compactMessages : DEFAULT_CONFIG.compactMessages),
 		footer:
-			envBool("PI_CC_FOOTER") ?? (typeof file.footer === "boolean" ? file.footer : DEFAULT_CONFIG.footer),
+			envBool(ENV_OVERRIDES.footer) ?? (typeof file.footer === "boolean" ? file.footer : DEFAULT_CONFIG.footer),
 	};
 }
 
@@ -81,9 +94,14 @@ export function invalidateConfig(): void {
 	cached = undefined;
 }
 
-/** Merge a patch into the settings file and update the cache. */
+/**
+ * Write the changed keys to the settings file and return the settings now in
+ * effect. Only the patch is written: every other key stays as the user left
+ * it, and an environment override is never copied into the file. It still
+ * wins over the file while it is set, so the returned value can differ from
+ * the patch (see `envOverride`).
+ */
 export function saveConfig(patch: Partial<PiCcConfig>): PiCcConfig {
-	const next = { ...loadConfig(), ...patch };
 	const file = configPath();
 	fs.mkdirSync(path.dirname(file), { recursive: true });
 	// Keep keys this version does not know about: the file is the user's.
@@ -95,8 +113,8 @@ export function saveConfig(patch: Partial<PiCcConfig>): PiCcConfig {
 		// A missing or malformed file is rewritten from scratch.
 	}
 	const temp = `${file}.tmp`;
-	fs.writeFileSync(temp, `${JSON.stringify({ ...raw, ...next }, null, 2)}\n`, "utf8");
+	fs.writeFileSync(temp, `${JSON.stringify({ ...raw, ...patch }, null, 2)}\n`, "utf8");
 	fs.renameSync(temp, file);
-	cached = next;
-	return next;
+	cached = undefined;
+	return loadConfig();
 }

package/index.ts

@@ -29,7 +29,7 @@
 
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { configPath, invalidateConfig, loadConfig, saveConfig, type PiCcConfig } from "./config.ts";
+import { configPath, envOverride, invalidateConfig, loadConfig, saveConfig, type PiCcConfig } from "./config.ts";
 import {
 	humanSchedule,
 	isUnreachable,
@@ -57,6 +57,7 @@ import {
 	loopCommandGuidelines,
 } from "./prompts.ts";
 import { formatClock, formatEta, renderScheduledMessage } from "./renderers.ts";
+import { settingsPanel } from "./settings-panel.ts";
 import {
 	DEFAULT_TIMING,
 	generateId,
@@ -574,7 +575,8 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 				case "statusline": {
 					const arg = (rest[0] ?? "").toLowerCase();
 					if (!arg) {
-						notify(ctx, `Usage: /loop footer on|off (currently ${loadConfig().footer ? "on" : "off"})`, "info");
+						const current = `${loadConfig().footer ? "on" : "off"}${overrideNote("footer")}`;
+						notify(ctx, `Usage: /loop footer on|off (currently ${current})`, "info");
 						return;
 					}
 					setSetting(ctx, "footer", arg);
@@ -584,7 +586,7 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 				case "config": {
 					const [key, value] = rest;
 					if (!key) {
-						showSettings(ctx);
+						if (!(await openSettingsPanel(ctx))) showSettings(ctx);
 						return;
 					}
 					const name = key.toLowerCase();
@@ -651,7 +653,7 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 			"/loop <prompt>              self-paced: the agent picks the next delay",
 			"/loop [interval]            the .pi/loop.md tasks, or the built-in maintenance prompt",
 			"/loop footer on|off         show or hide the one-line summary in the footer",
-			"/loop settings              show UI settings",
+			"/loop settings              settings panel (a summary outside the TUI)",
 			"/loop settings messages on|off   compact two-line markers",
 			"/loop settings footer on|off     the one-line footer summary",
 			"",
@@ -662,12 +664,46 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 		notify(ctx, help, "info");
 	}
 
+	/** ` (PI_CC_FOOTER=0)` when an environment variable decides the setting. */
+	function overrideNote(key: keyof PiCcConfig): string {
+		const override = envOverride(key);
+		return override ? ` (${override})` : "";
+	}
+
+	/**
+	 * A bare /loop settings in the TUI: a panel like Pi's /settings, which
+	 * extensions cannot add to. Resolves when the panel closes; false when there
+	 * is no TUI to show it in, so the caller prints the summary instead.
+	 */
+	async function openSettingsPanel(ctx: ExtensionCommandContext): Promise<boolean> {
+		if (ctx.mode !== "tui" || typeof ctx.ui.custom !== "function") return false;
+		await ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
+			const panel = settingsPanel({
+				theme,
+				file: configPath(),
+				onChange: (field, value) => {
+					applySetting(field, value);
+				},
+				onClose: () => done(undefined),
+			});
+			return {
+				render: (width: number) => panel.render(width),
+				invalidate: () => panel.invalidate(),
+				handleInput: (data: string) => {
+					panel.handleInput(data);
+					tui.requestRender();
+				},
+			};
+		});
+		return true;
+	}
+
 	function showSettings(ctx: ExtensionContext): void {
 		const config = loadConfig();
 		const lines = [
 			`pi-cc settings \u00b7 ${configPath()}`,
-			`  messages:  ${config.compactMessages ? "compact" : "card"}`,
-			`  footer:    ${config.footer ? "summary" : "hidden"}`,
+			`  messages:  ${config.compactMessages ? "compact" : "card"}${overrideNote("compactMessages")}`,
+			`  footer:    ${config.footer ? "summary" : "hidden"}${overrideNote("footer")}`,
 			"",
 			"Usage: /loop settings messages on|off",
 			"       /loop settings footer on|off",
@@ -683,15 +719,29 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 			showSettings(ctx);
 			return;
 		}
-		const patch: Partial<PiCcConfig> = key === "messages" ? { compactMessages: on } : { footer: on };
+		const field: keyof PiCcConfig = key === "messages" ? "compactMessages" : "footer";
+		const next = applySetting(field, on);
+		const label = key === "messages" ? "Compact message style" : "Footer summary";
+		const override = envOverride(field);
+		if (override && next[field] !== on) {
+			// The file has the choice, but the variable decides while it is set.
+			notify(ctx, `${label} saved as ${on ? "on" : "off"}, but ${override} overrides it while set`, "warning");
+		} else {
+			notify(ctx, `${label} ${on ? "enabled" : "disabled"}`, "info");
+		}
+	}
+
+	/** Save one setting, tell the other pi-cc packages, and repaint the footer. Returns the settings in effect. */
+	function applySetting(field: keyof PiCcConfig, on: boolean): PiCcConfig {
+		const patch: Partial<PiCcConfig> = field === "compactMessages" ? { compactMessages: on } : { footer: on };
 		const next = saveConfig(patch);
 		try {
 			pi.events.emit(CONFIG_CHANNEL, next);
 		} catch {
 			// another extension must not break the command
 		}
-		notify(ctx, `${key === "messages" ? "Compact message style" : "Footer summary"} ${on ? "enabled" : "disabled"}`, "info");
-		if (key === "footer") refreshStatus();
+		if (field === "footer") refreshStatus();
+		return next;
 	}
 
 	// ------------------------------------------------------------------ tools

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cc-loop",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"description": "Claude Code compatible /loop for the Pi coding agent: cron-scheduled fixed intervals, self-paced chains, and the same dispatch semantics as Claude Code.",
 	"author": "tarnish233",
 	"type": "module",

package/settings-panel.ts

@@ -0,0 +1,135 @@
+/**
+ * The /loop settings panel: the same kind of screen as Pi's /settings.
+ *
+ * Pi's /settings cannot take items from an extension (its panel is a fixed
+ * list, and the command is handled before extension commands), so the shared
+ * pi-cc settings get their own panel, built from the same parts: SettingsList
+ * between two borders, the selected setting's description below it, and
+ * Enter/Space to change a value. A change is saved at once and Esc closes.
+ *
+ * A setting that an environment variable overrides shows the value in effect
+ * and cannot be changed here; its description names the variable.
+ */
+
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import { Container, SettingsList, Spacer, Text, type SettingItem, type SettingsListTheme } from "@earendil-works/pi-tui";
+import os from "node:os";
+import path from "node:path";
+import { envOverride, loadConfig, type PiCcConfig } from "./config.ts";
+
+/** The part of Pi's theme the panel uses. */
+export interface PanelTheme {
+	fg(color: string, text: string): string;
+	bold(text: string): string;
+}
+
+interface SettingSpec {
+	field: keyof PiCcConfig;
+	label: string;
+	/** Display values for true and false. */
+	on: string;
+	off: string;
+	description: string;
+}
+
+const SETTINGS: SettingSpec[] = [
+	{
+		field: "compactMessages",
+		label: "Message style",
+		on: "compact",
+		off: "card",
+		description:
+			"How scheduled fires and Monitor events are drawn. compact: \u273b header and indented body; card: the old padded card.",
+	},
+	{
+		field: "footer",
+		label: "Footer summary",
+		on: "on",
+		off: "off",
+		description: "One line in Pi's footer while loops or monitors run: loop 2 \u00b7 next 3m, monitor 2.",
+	},
+];
+
+/**
+ * Pi's getSettingsListTheme(), built from the theme the panel is given: the
+ * global theme that function reads is not shared with extensions in every
+ * Pi runtime (see the note on Pi's DynamicBorder).
+ */
+function listTheme(theme: PanelTheme): SettingsListTheme {
+	return {
+		label: (text, selected) => (selected ? theme.fg("accent", text) : text),
+		value: (text, selected) => (selected ? theme.fg("accent", text) : theme.fg("muted", text)),
+		description: (text) => theme.fg("dim", text),
+		cursor: theme.fg("accent", "\u2192 "),
+		hint: (text) => theme.fg("dim", text),
+	};
+}
+
+/** A path with the home directory shortened to ~. */
+function displayPath(file: string): string {
+	const home = os.homedir();
+	return file === home || file.startsWith(home + path.sep) ? `~${file.slice(home.length)}` : file;
+}
+
+function item(spec: SettingSpec): SettingItem {
+	const value = loadConfig()[spec.field] ? spec.on : spec.off;
+	const override = envOverride(spec.field);
+	if (override) {
+		// No values: Enter/Space leaves it alone, and the description says why.
+		return {
+			id: spec.field,
+			label: spec.label,
+			currentValue: value,
+			description: `${spec.description}\n${override} overrides this while set; unset it to change it here.`,
+		};
+	}
+	return { id: spec.field, label: spec.label, currentValue: value, values: [spec.on, spec.off], description: spec.description };
+}
+
+export interface SettingsPanelOptions {
+	theme: PanelTheme;
+	/** Where the settings are saved, shown in the title. */
+	file: string;
+	/** Save one setting (and tell the other packages). */
+	onChange(field: keyof PiCcConfig, value: boolean): void;
+	onClose(): void;
+}
+
+export interface SettingsPanel {
+	render(width: number): string[];
+	invalidate(): void;
+	handleInput(data: string): void;
+}
+
+export function settingsPanel(options: SettingsPanelOptions): SettingsPanel {
+	const { theme } = options;
+	const list = new SettingsList(
+		SETTINGS.map(item),
+		SETTINGS.length,
+		listTheme(theme),
+		(id, value) => {
+			const spec = SETTINGS.find((candidate) => candidate.field === id);
+			if (!spec) return;
+			options.onChange(spec.field, value === spec.on);
+			// Show what is in effect now.
+			list.updateValue(id, loadConfig()[spec.field] ? spec.on : spec.off);
+		},
+		() => options.onClose(),
+	);
+
+	const border = () => new DynamicBorder((text: string) => theme.fg("border", text));
+	const container = new Container();
+	container.addChild(border());
+	container.addChild(
+		new Text(`${theme.fg("accent", theme.bold("pi-cc settings"))}${theme.fg("dim", ` \u00b7 ${displayPath(options.file)}`)}`, 0, 0),
+	);
+	container.addChild(new Spacer(1));
+	container.addChild(list);
+	container.addChild(border());
+
+	return {
+		render: (width) => container.render(width),
+		invalidate: () => container.invalidate(),
+		handleInput: (data) => list.handleInput(data),
+	};
+}