@narumitw/pi-caffeinate 0.49.6 → 0.49.8

package/README.md

@@ -2,15 +2,15 @@
 
 [![npm](https://img.shields.io/npm/v/@narumitw/pi-caffeinate)](https://www.npmjs.com/package/@narumitw/pi-caffeinate) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 
-Prevent system or display sleep while Pi is processing a prompt, then release the inhibitor as soon as the run ends.
+Prevent system or display sleep while Pi is running an agent task, then release the inhibitor when the run ends.
 
 ## ✨ Features
 
 - Starts an OS sleep inhibitor when a Pi run begins and releases it when the run or session ends.
-- Supports macOS, Windows, WSL, and Linux with a display-awake default.
-- Provides `/caffeinate` controls for the keep-awake mode, current status, and quiet mode.
+- Supports macOS, Windows, WSL, and Linux, with display-awake as the default.
+- Provides `/caffeinate` controls for keep-awake mode and status.
 - Persists preferences locally and accepts an optional custom inhibitor command.
-- Shows activity only while the inhibitor is active and fails safely when no supported mechanism is available.
+- Falls back when possible, warns on partial activation, and reports when no inhibitor is available.
 
 ## 📦 Install
 
@@ -32,19 +32,18 @@ pi -e ./packages/pi-caffeinate
 ```
 
 The package declares `dist/index.ts`, so an unbuilt local checkout must be built before Pi loads the package directory.
+Pi extensions run with the Pi process's user permissions, so install only trusted packages.
 
 ## 🚀 Quick start
 
 Load the extension and use Pi normally.
-During an agent run, pi-caffeinate uses the saved keep-awake mode and defaults to keeping both the system and display awake.
-Run `/caffeinate` to open the controls or `/caffeinate status` to inspect the current state.
+During each agent run, pi-caffeinate uses the saved mode and defaults to keeping the system and display awake.
+Run `/caffeinate` for controls or `/caffeinate status` for the current state.
 
 ## 🖥️ Supported platforms
 
-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.
+The default `display` mode prevents system sleep, suspend, or hibernate and keeps the display awake.
+Use `/caffeinate sleep` to prevent system sleep while allowing normal screen blanking or monitor power-off.
 
 | Platform | `sleep` mode | `display` mode, default |
 | --- | --- | --- |
@@ -54,58 +53,31 @@ Use `/caffeinate sleep` if you want to prevent system sleep while allowing norma
 | Linux with systemd | `systemd-inhibit --what=sleep ... sleep infinity` | D-Bus `org.freedesktop.ScreenSaver.Inhibit` + `systemd-inhibit --what=idle:sleep ... sleep infinity` |
 | Linux without systemd | `caffeinate -ims` when available | D-Bus `org.freedesktop.ScreenSaver.Inhibit` + `caffeinate -dimsu` when available; D-Bus only otherwise |
 
-On Linux, `display` mode requests idle inhibition through the standard `org.freedesktop.ScreenSaver` D-Bus service, trying both `/org/freedesktop/ScreenSaver` and `/ScreenSaver` for desktop compatibility.
-The session-bus connection stays open for the whole agent turn.
-The inhibition ends when `UnInhibit` is called or the connection closes.
-`systemd-inhibit --what=idle:sleep` runs alongside it to preserve logind idle and sleep inhibition.
-If no ScreenSaver service is available, pi-caffeinate keeps the systemd blocker or `caffeinate` fallback and reports a partial-activation warning.
-If only D-Bus is available, pi-caffeinate reports partial activation because desktop idle is inhibited but direct system suspend may remain possible.
-D-Bus method calls use short deadlines, and stop or shutdown aborts an in-flight acquisition before closing its session-bus connection.
+On Linux, `display` mode requests idle inhibition from `org.freedesktop.ScreenSaver` over D-Bus.
+It tries `/org/freedesktop/ScreenSaver` and `/ScreenSaver` for desktop compatibility and keeps the session-bus connection open for the agent turn.
+Calling `UnInhibit` or closing the connection releases the request.
+`systemd-inhibit --what=idle:sleep` runs alongside D-Bus to preserve logind idle and sleep inhibition.
+If the ScreenSaver service is unavailable, pi-caffeinate keeps the systemd or `caffeinate` blocker and warns that activation is partial.
+If only D-Bus is available, it warns that direct system suspend may remain possible.
+D-Bus calls have 2-second deadlines, and stop or shutdown aborts an in-progress acquisition before closing the connection.
 
 If no supported inhibitor is available, the extension stays loaded and reports that caffeinate is unavailable.
 
 ## 💬 Commands
 
-```text
-/caffeinate
-```
-
-Opens standard keep-awake controls in TUI or RPC mode.
-Print and JSON modes reject the interactive menu observably; use the direct `status`, `sleep`, `display`, `stop`, or `help` routes instead.
-
-```text
-/caffeinate display
-```
-
-Keeps the system and screen/display awake.
-If an inhibitor is currently active, it is restarted so the new mode applies immediately.
-
-```text
-/caffeinate sleep
-```
+| Command | Purpose |
+| --- | --- |
+| `/caffeinate` | Open keep-awake controls. |
+| `/caffeinate display` (alias: `screen`) | Keep the system and display awake. |
+| `/caffeinate sleep` (alias: `system`) | Keep the system awake while allowing display sleep. |
+| `/caffeinate status` | Show inhibitor state, mode, quiet mode, and settings path. |
+| `/caffeinate mode` (aliases: `config`, `settings`) | Choose the keep-awake mode. |
+| `/caffeinate stop` (alias: `off`) | Release the inhibitor until the next agent run. |
+| `/caffeinate help` | Show command usage. |
 
-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, quiet mode, and settings file path.
-
-```text
-/caffeinate mode
-```
-
-Opens the standard keep-awake mode selector in TUI or RPC mode.
-Escape closes the selector.
-
-```text
-/caffeinate stop
-```
-
-Releases any active inhibitor until Pi starts another agent run.
+All routes support TUI and RPC and reject unknown or trailing arguments.
+Print and JSON modes reject the menu and mode selector; other direct routes run but do not display notification feedback.
+Changing to `display` or `sleep` restarts an active inhibitor immediately.
 
 ## ⚙️ Settings
 
@@ -127,21 +99,23 @@ Example:
 }
 ```
 
-Set `"quiet": true` to hide the routine `Keeping computer awake (...)` and `Released pi-caffeinate (agent finished)` lifecycle notifications and keep the `caffeinate` status item clear while active or unavailable.
-Quiet mode does not hide warnings or explicit feedback from `/caffeinate` commands such as `status`, mode changes, help, and manual stop.
+Set `"quiet": true` to hide routine start and release notifications and clear the `caffeinate` status item while active or unavailable.
+Quiet mode does not hide warnings or explicit command feedback.
 It defaults to `false` when omitted.
-The file is read at startup and on `/reload`; run `/reload` after editing it in a running Pi session before using mode commands.
+The file is read at startup and on `/reload`.
+After editing it in a running session, run `/reload` before using mode commands.
 
-Missing, invalid, or deleted settings default back to `display` mode with quiet mode disabled on every supported OS.
+Missing, invalid, or deleted settings use `display` mode with quiet mode off.
 A missing file stays absent until the first successful mode change.
 Within one Pi process, mode saves run in invocation order, reread the latest valid document, and preserve unknown fields.
-Malformed JSON or an invalid recognized field blocks mode saves until repaired instead of being overwritten.
-A failed save keeps the prior runtime mode; if restarting an active inhibitor fails after publication, the extension restores the prior saved mode and inhibitor behavior or reports an explicit rollback failure.
-
-Compatibility: older versions used `pi-caffeinate-settings.json`.
-A legacy-only file remains readable with a warning and is never modified automatically; rename it to `pi-caffeinate.json`.
-The first subsequent settings save writes the canonical file.
-If both files exist, `pi-caffeinate.json` wins and the legacy file is ignored.
+Malformed JSON or an invalid recognized field blocks saves until repaired.
+A failed save keeps the previous runtime mode.
+If applying a published mode fails while an inhibitor is active, the extension restores the previous saved mode and inhibitor or reports a rollback failure.
+
+Older versions used `pi-caffeinate-settings.json`.
+A legacy-only file remains readable with a warning and is not modified automatically; rename it to `pi-caffeinate.json`.
+The next settings save writes the canonical file.
+If both files exist, `pi-caffeinate.json` takes precedence.
 The legacy filename is deprecated and will be removed in a future major release.
 
 ### Environment variables
@@ -158,8 +132,8 @@ 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.
-`PI_CAFFEINATE_COMMAND` takes precedence over the saved mode; `/caffeinate status` reports when a custom command is active.
+The custom command uses shell-like argument parsing but runs directly without a shell.
+`PI_CAFFEINATE_COMMAND` overrides the saved mode, and `/caffeinate status` reports the override.
 
 Deprecated: `PI_CAFFEINATE_ICON` still works for now.
 If you use `@narumitw/pi-statusline`, move the icon to `${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-statusline.json`:
@@ -173,42 +147,27 @@ If you use `@narumitw/pi-statusline`, move the icon to `${PI_CODING_AGENT_DIR:-~
 ```
 
 Without `@narumitw/pi-statusline`, keep using `PI_CAFFEINATE_ICON` during the compatibility window.
-In `pi-statusline.json`, use an empty string to show the caffeinate status without an icon.
+In `pi-statusline.json`, use an empty string to show caffeinate status without an icon.
 
-## 🧠 Why use pi-caffeinate?
-
-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 `/caffeinate sleep` (shown as `system-awake` in status output) when you prefer normal screen power saving and your system does not need idle inhibition to keep Pi running.
+Status output calls `display` mode `display-awake` and `sleep` mode `system-awake`.
 
 ## 📦 Dependencies
 
-On Linux, `display` mode uses the `dbus-native` package (pure JavaScript, no native build step) to call `org.freedesktop.ScreenSaver` on the session bus.
+On Linux, `display` mode uses the pure-JavaScript `dbus-native` package to call `org.freedesktop.ScreenSaver` on the session bus.
 
 ## 🗂️ Package layout
 
-```txt
+```text
 packages/pi-caffeinate/
-├── src/
-│   ├── index.ts       # Pi package entrypoint
-│   ├── caffeinate.ts  # Extension registration and lifecycle orchestration
-│   └── *.ts           # Package-local inhibitor and settings modules
-├── dist/              # Generated source-mapped Jiti runtime
-├── scripts/
-│   └── build-runtime.mjs
-├── test/
-│   ├── build-runtime.test.ts
-│   └── caffeinate.test.ts
-├── README.md
-├── LICENSE
-├── tsconfig.json
-└── package.json
+├── src/                               # Authoritative implementation and helpers
+│   ├── index.ts                       # Thin Pi entrypoint
+│   └── caffeinate.ts                  # Sleep inhibitors and lifecycle
+├── dist/                              # Generated Jiti runtime
+├── scripts/build-runtime.mjs          # Runtime builder
+└── test/                              # Behavior and lifecycle coverage
 ```
 
-`src/index.ts` remains the thin authoritative forwarder, while Pi loads the generated `dist/index.ts` runtime.
-The other source modules are internal.
+The generated runtime is built from `src/index.ts` and does not import back into `src`.
 
 ## 🔎 Keywords
 

package/dist/index.ts

@@ -34,9 +34,7 @@ var NativeScreenSaverClient = class {
   };
   handleConnectionClose = (error) => {
     if (this.closing || this.cookie === void 0) return;
-    this.reportFailure(
-      toError(error, this.lastConnectionError?.message ?? "D-Bus session connection closed")
-    );
+    this.reportFailure(toError(error, this.lastConnectionError?.message ?? "D-Bus session connection closed"));
   };
   setFailureHandler(handler) {
     this.failureHandler = handler;
@@ -176,11 +174,7 @@ function getInhibitorCommand(mode) {
     if (command) return { command, args, description: `custom command (${command})`, custom: true };
   }
   if (process2.platform === "darwin") {
-    return parentBoundUnixCommand(
-      "caffeinate",
-      macCaffeinateArgs(mode),
-      caffeinateDescription(mode)
-    );
+    return parentBoundUnixCommand("caffeinate", macCaffeinateArgs(mode), caffeinateDescription(mode));
   }
   if (process2.platform === "linux") {
     if (isWsl() && commandExists("powershell.exe")) {
@@ -190,14 +184,7 @@ function getInhibitorCommand(mode) {
       const what = mode === "display" ? "idle:sleep" : "sleep";
       return parentBoundUnixCommand(
         "systemd-inhibit",
-        [
-          `--what=${what}`,
-          "--who=pi-caffeinate",
-          "--why=Pi agent is running",
-          "--mode=block",
-          "sleep",
-          "infinity"
-        ],
+        [`--what=${what}`, "--who=pi-caffeinate", "--why=Pi agent is running", "--mode=block", "sleep", "infinity"],
         `systemd-inhibit (${formatMode(mode)})`,
         mode === "display"
       );
@@ -223,14 +210,7 @@ function caffeinateDescription(mode) {
 function parentBoundUnixCommand(command, args, description, addDbusIdleInhibit = false) {
   return {
     command: "sh",
-    args: [
-      "-c",
-      unixParentBoundScript(),
-      "pi-caffeinate-watch",
-      String(process2.pid),
-      command,
-      ...args
-    ],
+    args: ["-c", unixParentBoundScript(), "pi-caffeinate-watch", String(process2.pid), command, ...args],
     description,
     ...addDbusIdleInhibit ? { addDbusIdleInhibit: true } : {}
   };
@@ -431,11 +411,8 @@ async function saveSettingsNow(settings, operations) {
   await mkdir(dirname(filePath), { recursive: true });
   const tempFile = `${filePath}.${process3.pid}.${randomUUID()}.tmp`;
   try {
-    await (operations.write ?? DEFAULT_FILE_OPERATIONS.write)(
-      tempFile,
-      `${JSON.stringify(nextDocument, null, 2)}
-`
-    );
+    await (operations.write ?? DEFAULT_FILE_OPERATIONS.write)(tempFile, `${JSON.stringify(nextDocument, null, 2)}
+`);
     if (!replaceCanonical && await pathEntryExists(filePath)) {
       throw new Error(`${NEW_SETTINGS_FILE} was created concurrently; reopen settings and retry.`);
     }
@@ -681,9 +658,7 @@ async function setModeNow(ctx, mode, generation) {
   if (generation !== state.sessionGeneration) return;
   const previousMode = state.mode;
   const previousQuiet = state.quiet;
-  const restartRequired = Boolean(
-    hasActiveInhibitor() && previousMode !== mode && !state.command?.custom
-  );
+  const restartRequired = Boolean(hasActiveInhibitor() && previousMode !== mode && !state.command?.custom);
   state.settingsError = void 0;
   if (restartRequired) {
     state.mode = mode;
@@ -758,9 +733,7 @@ function parseCommand(args) {
 function commandCompletions(prefix) {
   const normalized = prefix.trimStart().toLowerCase();
   if (/\s/.test(normalized)) return null;
-  const matches = COMMAND_COMPLETIONS.filter(
-    (completion) => completion.value.startsWith(normalized)
-  );
+  const matches = COMMAND_COMPLETIONS.filter((completion) => completion.value.startsWith(normalized));
   return matches.length > 0 ? matches : null;
 }
 function buildCommandGuide() {
@@ -1028,9 +1001,7 @@ function describeState() {
     const activeParts = [];
     if (state.dbus) activeParts.push(`D-Bus idle inhibit (${SCREENSAVER_BUS_NAME})`);
     if (state.process && state.command) activeParts.push(state.command.description);
-    lines.unshift(
-      `pi-caffeinate is active using ${activeParts.join(" + ") || "an inhibitor"} for ${seconds}s.`
-    );
+    lines.unshift(`pi-caffeinate is active using ${activeParts.join(" + ") || "an inhibitor"} for ${seconds}s.`);
     if (state.inhibitWarning) lines.push(`Inhibitor warning: ${state.inhibitWarning}`);
     return lines.join("\n");
   }
@@ -1038,9 +1009,7 @@ function describeState() {
     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."
-  );
+  lines.unshift("pi-caffeinate is idle and will keep the computer awake during the next agent run.");
   return lines.join("\n");
 }
 function statusLevel() {