@narumitw/pi-caffeinate 0.1.37 → 0.3.0

package/README.md

@@ -10,9 +10,11 @@ It is designed for long-running coding, refactoring, debugging, web research, an
 
 - Starts an OS sleep inhibitor when Pi begins processing (`agent_start`).
 - Releases the inhibitor when processing ends (`agent_end`) or the session shuts down.
-- Publishes an `awake` status only while an inhibitor is active.
+- Publishes the active keep-awake mode as status while an inhibitor is active.
 - Supports macOS, Windows, WSL, and Linux.
-- Provides `/caffeinate-status` and `/caffeinate-stop` commands.
+- Defaults to display-awake mode on every supported OS: prevent system sleep and keep the screen/display awake.
+- Provides a single `/caffeinate` command with menu-based controls and direct subcommands.
+- Persists the selected keep-awake mode in a small JSON settings file.
 - Allows a custom inhibitor command through environment configuration.
 - Allows a custom status icon through environment configuration.
 - Fails safely when no supported inhibitor is available.
@@ -37,30 +39,81 @@ pi -e ./extensions/pi-caffeinate
 
 ## 🖥️ Supported platforms
 
-- macOS: uses `caffeinate -dimsu`.
-- Windows: uses PowerShell `SetThreadExecutionState`.
-- WSL: uses Windows `powershell.exe` with `SetThreadExecutionState`.
-- Linux: uses `systemd-inhibit` with `sleep infinity`.
-- Linux fallback: uses `caffeinate -dimsu` when available.
+The default mode is `display` on every supported OS. That means pi-caffeinate prevents system sleep, suspend, or hibernate and keeps the screen/display awake.
+
+Use `/caffeinate sleep` if you want to prevent system sleep while allowing normal display idle behavior such as screen blanking or monitor power-off.
+
+| Platform | `sleep` mode | `display` mode, default |
+| --- | --- | --- |
+| macOS | `caffeinate -ims` | `caffeinate -dimsu` |
+| Windows | PowerShell `SetThreadExecutionState(0x80000001)` | PowerShell `SetThreadExecutionState(0x80000003)` |
+| WSL | Windows `powershell.exe` with `SetThreadExecutionState(0x80000001)` | Windows `powershell.exe` with `SetThreadExecutionState(0x80000003)` |
+| Linux with systemd | `systemd-inhibit --what=sleep ... sleep infinity` | `systemd-inhibit --what=idle:sleep ... sleep infinity` |
+| Linux fallback | `caffeinate -ims` when available | `caffeinate -dimsu` when available |
 
 If no supported inhibitor is available, the extension stays loaded and reports that caffeinate is unavailable.
 
 ## 🚀 Commands
 
 ```text
-/caffeinate-status
+/caffeinate
+```
+
+Opens keep-awake controls. In non-interactive sessions, it prints command usage and status.
+
+```text
+/caffeinate display
 ```
 
-Shows whether an inhibitor is active, unavailable, or disabled.
+Keeps the system and screen/display awake. If an inhibitor is currently active, it is restarted so the new mode applies immediately.
 
 ```text
-/caffeinate-stop
+/caffeinate sleep
 ```
 
-Manually releases any active inhibitor for the current session.
+Keeps the system awake while allowing normal display sleep. If an inhibitor is currently active, it is restarted so the new mode applies immediately.
+
+```text
+/caffeinate status
+```
+
+Shows whether an inhibitor is active, unavailable, disabled, or idle. The status includes the current mode and settings file path.
+
+```text
+/caffeinate mode
+```
+
+Opens an interactive selector for the keep-awake mode.
+
+```text
+/caffeinate stop
+```
+
+Releases any active inhibitor until Pi starts another agent run.
 
 ## ⚙️ Configuration
 
+### Persisted mode
+
+`/caffeinate sleep` and `/caffeinate display` save the selected mode to:
+
+```text
+${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-caffeinate-settings.json
+```
+
+Example:
+
+```json
+{
+  "mode": "display",
+  "updatedAt": 1791763200000
+}
+```
+
+Missing, invalid, or deleted settings default back to `display` mode on every supported OS.
+
+### Environment variables
+
 Disable the extension:
 
 ```bash
@@ -73,7 +126,7 @@ Use a custom inhibitor command:
 PI_CAFFEINATE_COMMAND='systemd-inhibit --what=idle:sleep --why="pi running" --mode=block sleep infinity' pi
 ```
 
-The custom command is parsed with shell-like quoting and is run directly without a shell.
+The custom command is parsed with shell-like quoting and is run directly without a shell. `PI_CAFFEINATE_COMMAND` takes precedence over the saved mode; `/caffeinate status` reports when a custom command is active.
 
 Customise the status bar icon (default: `💊`):
 
@@ -85,6 +138,8 @@ PI_CAFFEINATE_ICON='☕️' pi
 
 AI coding agents often run tool-heavy tasks that take several minutes. `pi-caffeinate` keeps your machine awake during active Pi work, helping browser automation, local builds, test runs, code generation, and long prompts finish reliably.
 
+The default display-awake mode prioritizes uninterrupted long-running Pi work across platforms, including Linux desktops that require idle inhibition to prevent automatic suspend. Use sleep-only mode when you prefer normal screen power saving and your system does not need idle inhibition to keep Pi running.
+
 ## 🗂️ Package layout
 
 ```txt

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-caffeinate",
-	"version": "0.1.37",
+	"version": "0.3.0",
 	"description": "Pi extension that keeps the computer awake while the agent is running.",
 	"type": "module",
 	"license": "MIT",

package/src/caffeinate.ts

@@ -1,17 +1,53 @@
 import { type ChildProcess, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 import pathModule from "node:path";
 import process from "node:process";
-import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionContext,
+} from "@mariozechner/pi-coding-agent";
 
 const STATUS_KEY = "caffeinate";
 const DISABLED_VALUES = new Set(["1", "true", "yes", "on"]);
+const DEFAULT_MODE = "display" satisfies CaffeinateMode;
+const SETTINGS_FILE = join(
+	process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent"),
+	"pi-caffeinate-settings.json",
+);
+const COMMAND_COMPLETIONS = [
+	{ value: "display", label: "Keep system and display awake" },
+	{ value: "sleep", label: "Keep system awake; allow display sleep" },
+	{ value: "status", label: "Show current status" },
+	{ value: "mode", label: "Choose keep-awake mode" },
+	{ value: "stop", label: "Release inhibitor for now" },
+	{ value: "help", label: "Show command help" },
+];
+const MENU_OPTIONS = {
+	display: "Keep system and display awake",
+	sleep: "Keep system awake; allow display sleep",
+	status: "Show current status",
+	stop: "Release inhibitor for now",
+	help: "Show command help",
+} as const;
+const MODE_OPTIONS = {
+	display: "Keep system and display awake",
+	sleep: "Keep system awake; allow display sleep",
+} as const;
+
+type CaffeinateMode = "sleep" | "display";
+type CommandAction = "menu" | "help" | "status" | "mode" | "sleep" | "display" | "stop";
+type CommandContext = ExtensionCommandContext;
 
 interface InhibitorCommand {
 	command: string;
 	args: string[];
 	description: string;
 	releaseOnStdinClose?: boolean;
+	custom?: boolean;
 }
 
 interface CaffeinateState {
@@ -22,20 +58,32 @@ interface CaffeinateState {
 	activeTurns: number;
 	available: boolean;
 	disabled: boolean;
+	mode: CaffeinateMode;
+	settingsLoaded: boolean;
+	settingsError?: string;
+}
+
+interface CaffeinateSettings {
+	mode: CaffeinateMode;
+	updatedAt: number;
 }
 
 const state: CaffeinateState = {
 	activeTurns: 0,
 	available: true,
 	disabled: isDisabled(),
+	mode: DEFAULT_MODE,
+	settingsLoaded: false,
 };
 
 export default function caffeinate(pi: ExtensionAPI) {
-	pi.on("session_start", (_event, ctx) => {
+	pi.on("session_start", async (_event, ctx) => {
+		await loadSettingsIntoState(ctx);
 		updateStatus(ctx);
 	});
 
-	pi.on("agent_start", (_event, ctx) => {
+	pi.on("agent_start", async (_event, ctx) => {
+		await ensureSettingsLoaded(ctx);
 		state.activeTurns += 1;
 		startInhibitor(ctx);
 	});
@@ -52,22 +100,167 @@ export default function caffeinate(pi: ExtensionAPI) {
 		ctx.ui.setStatus(STATUS_KEY, undefined);
 	});
 
-	pi.registerCommand("caffeinate-status", {
-		description: "Show whether pi-caffeinate is currently keeping the computer awake",
-		handler: async (_args, ctx) => {
-			ctx.ui.notify(describeState(), state.process ? "info" : state.available ? "info" : "warning");
-			updateStatus(ctx);
+	pi.registerCommand("caffeinate", {
+		description: "Open pi-caffeinate keep-awake controls",
+		getArgumentCompletions: (prefix) => commandCompletions(prefix),
+		handler: async (args, ctx) => {
+			await ensureSettingsLoaded(ctx);
+			await handleCaffeinateCommand(args, ctx);
 		},
 	});
 
-	pi.registerCommand("caffeinate-stop", {
-		description: "Release the active pi-caffeinate sleep inhibitor",
-		handler: async (_args, ctx) => {
-			state.activeTurns = 0;
-			stopInhibitor(ctx, "manual stop");
-			updateStatus(ctx);
-		},
-	});
+}
+
+async function handleCaffeinateCommand(args: string, ctx: CommandContext) {
+	const command = parseCommand(args);
+	switch (command) {
+		case "menu":
+			await showMenu(ctx);
+			return;
+		case "help":
+			ctx.ui.notify(buildCommandGuide(), "info");
+			return;
+		case "status":
+			showStatus(ctx);
+			return;
+		case "mode":
+			await showModeSelector(ctx);
+			return;
+		case "sleep":
+			await setMode(ctx, "sleep");
+			return;
+		case "display":
+			await setMode(ctx, "display");
+			return;
+		case "stop":
+			stopCaffeinate(ctx, "manual stop");
+			return;
+	}
+
+	ctx.ui.notify(`Unknown /caffeinate command: ${args.trim()}\n\n${buildCommandGuide()}`, "warning");
+}
+
+async function showMenu(ctx: CommandContext) {
+	if (!ctx.hasUI) {
+		ctx.ui.notify(`${buildCommandGuide()}\n\n${describeState()}`, statusLevel());
+		updateStatus(ctx);
+		return;
+	}
+
+	const choice = await ctx.ui.select("pi-caffeinate controls", Object.values(MENU_OPTIONS));
+	switch (choice) {
+		case MENU_OPTIONS.status:
+			showStatus(ctx);
+			return;
+		case MENU_OPTIONS.sleep:
+			await setMode(ctx, "sleep");
+			return;
+		case MENU_OPTIONS.display:
+			await setMode(ctx, "display");
+			return;
+		case MENU_OPTIONS.stop:
+			stopCaffeinate(ctx, "manual stop");
+			return;
+		case MENU_OPTIONS.help:
+			ctx.ui.notify(buildCommandGuide(), "info");
+			return;
+	}
+}
+
+async function showModeSelector(ctx: CommandContext) {
+	if (!ctx.hasUI) {
+		ctx.ui.notify(
+			`Mode selection needs an interactive UI. Run /caffeinate sleep or /caffeinate display.\n\n${describeState()}`,
+			statusLevel(),
+		);
+		updateStatus(ctx);
+		return;
+	}
+
+	const choice = await ctx.ui.select(
+		`pi-caffeinate mode (current: ${formatMode(state.mode)})`,
+		Object.values(MODE_OPTIONS),
+	);
+	if (choice === MODE_OPTIONS.sleep) {
+		await setMode(ctx, "sleep");
+		return;
+	}
+	if (choice === MODE_OPTIONS.display) {
+		await setMode(ctx, "display");
+	}
+}
+
+async function setMode(ctx: ExtensionContext, mode: CaffeinateMode) {
+	const previousMode = state.mode;
+	state.mode = mode;
+	state.settingsError = undefined;
+
+	let saved = true;
+	try {
+		await saveSettings({ mode, updatedAt: Date.now() });
+	} catch (error) {
+		saved = false;
+		state.settingsError = `settings save failed: ${formatError(error)}`;
+		ctx.ui.notify(`pi-caffeinate settings save failed: ${formatError(error)}`, "warning");
+	}
+
+	if (state.process && previousMode !== mode && !state.command?.custom) {
+		stopInhibitor(ctx, "mode changed", { notify: false });
+		startInhibitor(ctx);
+	}
+
+	ctx.ui.notify(
+		saved
+			? `pi-caffeinate mode set to ${formatMode(mode)} and saved.`
+			: `pi-caffeinate mode set to ${formatMode(mode)} for this session, but settings were not saved.`,
+		saved ? "info" : "warning",
+	);
+	updateStatus(ctx);
+}
+
+function showStatus(ctx: ExtensionContext) {
+	ctx.ui.notify(describeState(), statusLevel());
+	updateStatus(ctx);
+}
+
+function stopCaffeinate(ctx: ExtensionContext, reason: string) {
+	state.activeTurns = 0;
+	stopInhibitor(ctx, reason);
+	updateStatus(ctx);
+}
+
+function parseCommand(args: string): CommandAction | "unknown" {
+	const command = args.trim().toLowerCase();
+	if (!command) return "menu";
+	if (command === "help") return "help";
+	if (command === "status") return "status";
+	if (command === "mode" || command === "config" || command === "settings") return "mode";
+	if (command === "sleep" || command === "system") return "sleep";
+	if (command === "display" || command === "screen") return "display";
+	if (command === "stop" || command === "off") return "stop";
+	return "unknown";
+}
+
+function commandCompletions(prefix: string) {
+	const normalized = prefix.trim().toLowerCase();
+	if (normalized.includes(" ")) return null;
+
+	const matches = COMMAND_COMPLETIONS.filter((completion) =>
+		completion.value.startsWith(normalized),
+	);
+	return matches.length > 0 ? matches : null;
+}
+
+function buildCommandGuide() {
+	return [
+		"pi-caffeinate commands:",
+		"/caffeinate — open keep-awake controls",
+		"/caffeinate display — keep the system and display awake",
+		"/caffeinate sleep — keep the system awake while allowing display sleep",
+		"/caffeinate status — show current mode, settings, and inhibitor state",
+		"/caffeinate mode — choose a keep-awake mode",
+		"/caffeinate stop — release the active inhibitor until the next agent run",
+	].join("\n");
 }
 
 function startInhibitor(ctx: ExtensionContext) {
@@ -81,7 +274,7 @@ function startInhibitor(ctx: ExtensionContext) {
 		return;
 	}
 
-	const command = getInhibitorCommand();
+	const command = getInhibitorCommand(state.mode);
 	if (!command) {
 		state.available = false;
 		state.lastError = `No supported sleep inhibitor found for ${process.platform}.`;
@@ -168,49 +361,62 @@ function stopInhibitor(ctx: ExtensionContext, reason: string, options: { notify?
 	}
 }
 
-function getInhibitorCommand(): InhibitorCommand | undefined {
+function getInhibitorCommand(mode: CaffeinateMode): InhibitorCommand | undefined {
 	const customCommand = process.env.PI_CAFFEINATE_COMMAND?.trim();
 	if (customCommand) {
 		const [command, ...args] = splitCommand(customCommand);
-		if (command) return { command, args, description: command };
+		if (command) return { command, args, description: `custom command (${command})`, custom: true };
 	}
 
 	if (process.platform === "darwin") {
-		return parentBoundUnixCommand("caffeinate", ["-dimsu"], "caffeinate");
+		return parentBoundUnixCommand("caffeinate", macCaffeinateArgs(mode), caffeinateDescription(mode));
 	}
 
 	if (process.platform === "linux") {
 		if (isWsl() && commandExists("powershell.exe")) {
-			return windowsPowerInhibitorCommand("powershell.exe");
+			return windowsPowerInhibitorCommand("powershell.exe", mode);
 		}
 
 		if (commandExists("systemd-inhibit")) {
+			const what = mode === "sleep" ? "sleep" : "idle:sleep";
 			return parentBoundUnixCommand(
 				"systemd-inhibit",
 				[
-					"--what=idle:sleep",
+					`--what=${what}`,
 					"--who=pi-caffeinate",
 					"--why=Pi agent is running",
 					"--mode=block",
 					"sleep",
 					"infinity",
 				],
-				"systemd-inhibit",
+				`systemd-inhibit (${formatMode(mode)})`,
 			);
 		}
 
 		if (commandExists("caffeinate")) {
-			return parentBoundUnixCommand("caffeinate", ["-dimsu"], "caffeinate");
+			return parentBoundUnixCommand(
+				"caffeinate",
+				macCaffeinateArgs(mode),
+				caffeinateDescription(mode),
+			);
 		}
 	}
 
 	if (process.platform === "win32") {
-		return windowsPowerInhibitorCommand("powershell.exe");
+		return windowsPowerInhibitorCommand("powershell.exe", mode);
 	}
 
 	return undefined;
 }
 
+function macCaffeinateArgs(mode: CaffeinateMode) {
+	return mode === "sleep" ? ["-ims"] : ["-dimsu"];
+}
+
+function caffeinateDescription(mode: CaffeinateMode) {
+	return `caffeinate (${formatMode(mode)})`;
+}
+
 function parentBoundUnixCommand(
 	command: string,
 	args: string[],
@@ -292,17 +498,18 @@ function splitCommand(input: string) {
 	return parts;
 }
 
-function windowsPowerInhibitorCommand(command: string): InhibitorCommand {
+function windowsPowerInhibitorCommand(command: string, mode: CaffeinateMode): InhibitorCommand {
 	return {
 		command,
-		args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", windowsInhibitorScript()],
-		description: "PowerShell SetThreadExecutionState",
+		args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", windowsInhibitorScript(mode)],
+		description: `PowerShell SetThreadExecutionState (${formatMode(mode)})`,
 		releaseOnStdinClose: true,
 	};
 }
 
-function windowsInhibitorScript() {
-	return `$ErrorActionPreference = 'Stop'; Add-Type -Namespace Native -Name Power -MemberDefinition '[DllImport("kernel32.dll")] public static extern uint SetThreadExecutionState(uint esFlags);'; $flags = [uint32]'0x80000003'; $release = [uint32]'0x80000000'; $stdin = [Console]::OpenStandardInput(); $buffer = New-Object byte[] 1; $readTask = $stdin.ReadAsync($buffer, 0, 1); try { while ($true) { [Native.Power]::SetThreadExecutionState($flags) | Out-Null; if ($readTask.Wait(30000)) { break } } } finally { [Native.Power]::SetThreadExecutionState($release) | Out-Null }`;
+function windowsInhibitorScript(mode: CaffeinateMode) {
+	const flags = mode === "sleep" ? "0x80000001" : "0x80000003";
+	return `$ErrorActionPreference = 'Stop'; Add-Type -Namespace Native -Name Power -MemberDefinition '[DllImport("kernel32.dll")] public static extern uint SetThreadExecutionState(uint esFlags);'; $flags = [uint32]'${flags}'; $release = [uint32]'0x80000000'; $stdin = [Console]::OpenStandardInput(); $buffer = New-Object byte[] 1; $readTask = $stdin.ReadAsync($buffer, 0, 1); try { while ($true) { [Native.Power]::SetThreadExecutionState($flags) | Out-Null; if ($readTask.Wait(30000)) { break } } } finally { [Native.Power]::SetThreadExecutionState($release) | Out-Null }`;
 }
 
 function isWsl() {
@@ -320,7 +527,7 @@ function updateStatus(ctx: ExtensionContext) {
 	}
 
 	if (state.process) {
-		ctx.ui.setStatus(STATUS_KEY, `${getIcon()} awake`);
+		ctx.ui.setStatus(STATUS_KEY, `${getIcon()} ${statusModeLabel()}`);
 		return;
 	}
 
@@ -333,14 +540,133 @@ function updateStatus(ctx: ExtensionContext) {
 }
 
 function describeState() {
-	if (state.disabled) return "pi-caffeinate is disabled by PI_CAFFEINATE_DISABLED.";
+	const customCommand = hasCustomCommand();
+	const lines = [
+		`Mode: ${formatMode(state.mode)}${customCommand ? " (overridden by custom command)" : ""}`,
+		`Settings: ${SETTINGS_FILE}`,
+	];
+
+	if (customCommand) lines.push("Custom command: PI_CAFFEINATE_COMMAND overrides the saved mode.");
+	if (state.settingsError) lines.push(`Settings warning: ${state.settingsError}`);
+	if (state.disabled) {
+		lines.unshift("pi-caffeinate is disabled by PI_CAFFEINATE_DISABLED.");
+		return lines.join("\n");
+	}
+
 	if (state.process) {
 		const seconds = state.startedAt ? Math.round((Date.now() - state.startedAt) / 1000) : 0;
-		return `pi-caffeinate is active using ${state.command?.description ?? "an inhibitor"} for ${seconds}s.`;
+		lines.unshift(
+			`pi-caffeinate is active using ${state.command?.description ?? "an inhibitor"} for ${seconds}s.`,
+		);
+		return lines.join("\n");
+	}
+
+	if (!state.available) {
+		lines.unshift(`pi-caffeinate is unavailable: ${state.lastError ?? "unknown reason"}`);
+		return lines.join("\n");
+	}
+
+	lines.unshift("pi-caffeinate is idle and will keep the computer awake during the next agent run.");
+	return lines.join("\n");
+}
+
+function statusLevel() {
+	return state.available && !state.settingsError ? "info" : "warning";
+}
+
+function statusModeLabel() {
+	if (state.command?.custom) return "custom";
+	return state.mode === "sleep" ? "sleep" : "display";
+}
+
+function formatMode(mode: CaffeinateMode) {
+	return mode === "sleep" ? "sleep-only" : "display-awake";
+}
+
+async function ensureSettingsLoaded(ctx: ExtensionContext) {
+	if (state.disabled || state.settingsLoaded) return;
+	await loadSettingsIntoState(ctx);
+}
+
+async function loadSettingsIntoState(ctx: ExtensionContext) {
+	if (state.disabled) {
+		state.settingsLoaded = true;
+		state.settingsError = undefined;
+		return;
+	}
+
+	const settings = await loadSettings();
+	state.settingsLoaded = true;
+	state.settingsError = undefined;
+
+	if (settings.kind === "loaded") {
+		state.mode = settings.settings.mode;
+		return;
 	}
-	if (!state.available)
-		return `pi-caffeinate is unavailable: ${state.lastError ?? "unknown reason"}`;
-	return "pi-caffeinate is idle and will keep the computer awake during the next agent run.";
+
+	state.mode = DEFAULT_MODE;
+	if (settings.kind === "invalid") {
+		state.settingsError = settings.reason;
+		ctx.ui.notify(
+			`pi-caffeinate settings ignored: ${settings.reason}; using ${formatMode(DEFAULT_MODE)} mode.`,
+			"warning",
+		);
+	}
+}
+
+async function loadSettings(): Promise<
+	| { kind: "missing" }
+	| { kind: "invalid"; reason: string }
+	| { kind: "loaded"; settings: CaffeinateSettings }
+> {
+	let text: string;
+	try {
+		text = await readFile(SETTINGS_FILE, "utf8");
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return { kind: "missing" };
+		return { kind: "invalid", reason: formatError(error) };
+	}
+
+	try {
+		const parsed = JSON.parse(text) as unknown;
+		const settings = normalizeCaffeinateSettings(parsed);
+		if (settings) return { kind: "loaded", settings };
+		return { kind: "invalid", reason: 'expected { "mode": "sleep" | "display" }' };
+	} catch (error) {
+		return { kind: "invalid", reason: formatError(error) };
+	}
+}
+
+function normalizeCaffeinateSettings(value: unknown): CaffeinateSettings | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const settings = value as { mode?: unknown; updatedAt?: unknown };
+	if (!isCaffeinateMode(settings.mode)) return undefined;
+	if (settings.updatedAt !== undefined && typeof settings.updatedAt !== "number") return undefined;
+	return { mode: settings.mode, updatedAt: settings.updatedAt ?? 0 };
+}
+
+function isCaffeinateMode(value: unknown): value is CaffeinateMode {
+	return value === "sleep" || value === "display";
+}
+
+async function saveSettings(settings: CaffeinateSettings) {
+	await mkdir(dirname(SETTINGS_FILE), { recursive: true });
+	const tempFile = `${SETTINGS_FILE}.${process.pid}.${Date.now()}.tmp`;
+	try {
+		await writeFile(tempFile, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+		await rename(tempFile, SETTINGS_FILE);
+	} catch (error) {
+		await rm(tempFile, { force: true }).catch(() => undefined);
+		throw error;
+	}
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error && "code" in error;
+}
+
+function formatError(error: unknown) {
+	return error instanceof Error ? error.message : String(error);
 }
 
 function formatExit(code: number | null, signal: NodeJS.Signals | null) {
@@ -353,6 +679,10 @@ function isDisabled() {
 	return value ? DISABLED_VALUES.has(value) : false;
 }
 
+function hasCustomCommand() {
+	return Boolean(process.env.PI_CAFFEINATE_COMMAND?.trim());
+}
+
 function getIcon() {
 	return process.env.PI_CAFFEINATE_ICON?.trim() ?? "💊";
 }