@narumitw/pi-caffeinate 0.49.4 → 0.49.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +71 -60
  2. package/dist/index.ts +1112 -0
  3. package/dist/index.ts.map +7 -0
  4. package/package.json +11 -7
  5. package/src/dbus-inhibit.ts +2 -1
package/README.md CHANGED
@@ -1,24 +1,16 @@
1
- # ☕ pi-caffeinate — Keep Your Computer Awake While Pi Works
1
+ # ☕ pi-caffeinate — Keep Your Computer Awake While Pi Runs
2
2
 
3
3
  [![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)
4
4
 
5
- `@narumitw/pi-caffeinate` is a cross-platform [Pi coding agent](https://pi.dev) extension that prevents your computer from sleeping while the Pi agent is processing a prompt.
6
-
7
- It is designed for long-running coding, refactoring, debugging, web research, and autonomous agent workflows where a suspended laptop or desktop would interrupt progress.
5
+ Prevent system or display sleep while Pi is processing a prompt, then release the inhibitor as soon as the run ends.
8
6
 
9
7
  ## ✨ Features
10
8
 
11
- - Starts an OS sleep inhibitor when Pi begins processing (`agent_start`).
12
- - Releases the inhibitor when processing ends (`agent_end`) or the session shuts down.
13
- - Publishes the active keep-awake mode as status while an inhibitor is active, unless quiet mode is enabled.
14
- - Supports macOS, Windows, WSL, and Linux.
15
- - Defaults to display-awake mode on every supported OS: prevent system sleep and keep the screen/display awake.
16
- - Provides a single `/caffeinate` command with menu-based controls and direct subcommands.
17
- - Persists the selected keep-awake mode and optional quiet mode in a small JSON settings file.
18
- - Allows a custom inhibitor command through environment configuration.
19
- - Emits plain status text; `@narumitw/pi-statusline` can add or suppress the status icon from JSON config.
20
- - Uses the standard `org.freedesktop.ScreenSaver` D-Bus idle-inhibition service for Linux `display` mode.
21
- - Fails safely when no supported inhibitor is available.
9
+ - Starts an OS sleep inhibitor when a Pi run begins and releases it when the run or session ends.
10
+ - Supports macOS, Windows, WSL, and Linux with a display-awake default.
11
+ - Provides `/caffeinate` controls for the keep-awake mode, current status, and quiet mode.
12
+ - Persists preferences locally and accepts an optional custom inhibitor command.
13
+ - Shows activity only while the inhibitor is active and fails safely when no supported mechanism is available.
22
14
 
23
15
  ## 📦 Install
24
16
 
@@ -35,12 +27,22 @@ pi -e npm:@narumitw/pi-caffeinate
35
27
  Try this package locally from the repository root:
36
28
 
37
29
  ```bash
30
+ npm --workspace @narumitw/pi-caffeinate run build
38
31
  pi -e ./packages/pi-caffeinate
39
32
  ```
40
33
 
34
+ The package declares `dist/index.ts`, so an unbuilt local checkout must be built before Pi loads the package directory.
35
+
36
+ ## 🚀 Quick start
37
+
38
+ Load the extension and use Pi normally.
39
+ During an agent run, pi-caffeinate uses the saved keep-awake mode and defaults to keeping both the system and display awake.
40
+ Run `/caffeinate` to open the controls or `/caffeinate status` to inspect the current state.
41
+
41
42
  ## 🖥️ Supported platforms
42
43
 
43
- 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.
44
+ The default mode is `display` on every supported OS.
45
+ That means pi-caffeinate prevents system sleep, suspend, or hibernate and keeps the screen/display awake.
44
46
 
45
47
  Use `/caffeinate sleep` if you want to prevent system sleep while allowing normal display idle behavior such as screen blanking or monitor power-off.
46
48
 
@@ -52,52 +54,52 @@ Use `/caffeinate sleep` if you want to prevent system sleep while allowing norma
52
54
  | Linux with systemd | `systemd-inhibit --what=sleep ... sleep infinity` | D-Bus `org.freedesktop.ScreenSaver.Inhibit` + `systemd-inhibit --what=idle:sleep ... sleep infinity` |
53
55
  | Linux without systemd | `caffeinate -ims` when available | D-Bus `org.freedesktop.ScreenSaver.Inhibit` + `caffeinate -dimsu` when available; D-Bus only otherwise |
54
56
 
55
- On Linux, `display` mode requests idle inhibition through the standard `org.freedesktop.ScreenSaver`
56
- D-Bus service, trying both `/org/freedesktop/ScreenSaver` and `/ScreenSaver` for desktop compatibility.
57
+ 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.
57
58
  The session-bus connection stays open for the whole agent turn.
58
59
  The inhibition ends when `UnInhibit` is called or the connection closes.
59
60
  `systemd-inhibit --what=idle:sleep` runs alongside it to preserve logind idle and sleep inhibition.
60
- If no ScreenSaver service is available, pi-caffeinate keeps the systemd blocker or `caffeinate`
61
- fallback and reports a partial-activation warning.
62
- If only D-Bus is available, pi-caffeinate reports partial activation because desktop idle is
63
- inhibited but direct system suspend may remain possible.
64
- D-Bus method calls use short deadlines, and stop or shutdown aborts an in-flight acquisition before
65
- closing its session-bus connection.
61
+ If no ScreenSaver service is available, pi-caffeinate keeps the systemd blocker or `caffeinate` fallback and reports a partial-activation warning.
62
+ If only D-Bus is available, pi-caffeinate reports partial activation because desktop idle is inhibited but direct system suspend may remain possible.
63
+ D-Bus method calls use short deadlines, and stop or shutdown aborts an in-flight acquisition before closing its session-bus connection.
66
64
 
67
65
  If no supported inhibitor is available, the extension stays loaded and reports that caffeinate is unavailable.
68
66
 
69
- ## 🚀 Commands
67
+ ## 💬 Commands
70
68
 
71
69
  ```text
72
70
  /caffeinate
73
71
  ```
74
72
 
75
- Opens standard keep-awake controls in TUI or RPC mode. Print and JSON modes reject the interactive
76
- menu observably; use the direct `status`, `sleep`, `display`, `stop`, or `help` routes instead.
73
+ Opens standard keep-awake controls in TUI or RPC mode.
74
+ Print and JSON modes reject the interactive menu observably; use the direct `status`, `sleep`, `display`, `stop`, or `help` routes instead.
77
75
 
78
76
  ```text
79
77
  /caffeinate display
80
78
  ```
81
79
 
82
- Keeps the system and screen/display awake. If an inhibitor is currently active, it is restarted so the new mode applies immediately.
80
+ Keeps the system and screen/display awake.
81
+ If an inhibitor is currently active, it is restarted so the new mode applies immediately.
83
82
 
84
83
  ```text
85
84
  /caffeinate sleep
86
85
  ```
87
86
 
88
- Keeps the system awake while allowing normal display sleep. If an inhibitor is currently active, it is restarted so the new mode applies immediately.
87
+ Keeps the system awake while allowing normal display sleep.
88
+ If an inhibitor is currently active, it is restarted so the new mode applies immediately.
89
89
 
90
90
  ```text
91
91
  /caffeinate status
92
92
  ```
93
93
 
94
- Shows whether an inhibitor is active, unavailable, disabled, or idle. The status includes the current mode, quiet mode, and settings file path.
94
+ Shows whether an inhibitor is active, unavailable, disabled, or idle.
95
+ The status includes the current mode, quiet mode, and settings file path.
95
96
 
96
97
  ```text
97
98
  /caffeinate mode
98
99
  ```
99
100
 
100
- Opens the standard keep-awake mode selector in TUI or RPC mode. Escape closes the selector.
101
+ Opens the standard keep-awake mode selector in TUI or RPC mode.
102
+ Escape closes the selector.
101
103
 
102
104
  ```text
103
105
  /caffeinate stop
@@ -105,7 +107,7 @@ Opens the standard keep-awake mode selector in TUI or RPC mode. Escape closes th
105
107
 
106
108
  Releases any active inhibitor until Pi starts another agent run.
107
109
 
108
- ## ⚙️ Configuration
110
+ ## ⚙️ Settings
109
111
 
110
112
  ### Persisted settings
111
113
 
@@ -125,25 +127,22 @@ Example:
125
127
  }
126
128
  ```
127
129
 
128
- Set `"quiet": true` to hide the routine `Keeping computer awake (...)` and
129
- `Released pi-caffeinate (agent finished)` lifecycle notifications and keep the `caffeinate` status
130
- item clear while active or unavailable. Quiet mode does not hide warnings or explicit feedback from
131
- `/caffeinate` commands such as `status`, mode changes, help, and manual stop. It defaults to `false`
132
- when omitted. The file is read at startup and on `/reload`; run `/reload` after editing it in a
133
- running Pi session before using mode commands.
134
-
135
- Missing, invalid, or deleted settings default back to `display` mode with quiet mode disabled on
136
- every supported OS. 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
137
- JSON or an invalid recognized field blocks mode saves until repaired instead of being overwritten.
138
- A failed save keeps the prior runtime mode; if restarting an active inhibitor fails after publication,
139
- the extension restores the prior saved mode and inhibitor behavior or reports an explicit rollback
140
- failure.
141
-
142
- Compatibility: older versions used `pi-caffeinate-settings.json`. A legacy-only file remains
143
- readable with a warning and is never modified automatically; rename it to `pi-caffeinate.json`.
144
- The first subsequent settings save writes the canonical file. If both files exist,
145
- `pi-caffeinate.json` wins and the legacy file is ignored. The legacy filename is deprecated
146
- and will be removed in a future major release.
130
+ 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.
131
+ Quiet mode does not hide warnings or explicit feedback from `/caffeinate` commands such as `status`, mode changes, help, and manual stop.
132
+ It defaults to `false` when omitted.
133
+ The file is read at startup and on `/reload`; run `/reload` after editing it in a running Pi session before using mode commands.
134
+
135
+ Missing, invalid, or deleted settings default back to `display` mode with quiet mode disabled on every supported OS.
136
+ A missing file stays absent until the first successful mode change.
137
+ Within one Pi process, mode saves run in invocation order, reread the latest valid document, and preserve unknown fields.
138
+ Malformed JSON or an invalid recognized field blocks mode saves until repaired instead of being overwritten.
139
+ 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.
140
+
141
+ Compatibility: older versions used `pi-caffeinate-settings.json`.
142
+ A legacy-only file remains readable with a warning and is never modified automatically; rename it to `pi-caffeinate.json`.
143
+ The first subsequent settings save writes the canonical file.
144
+ If both files exist, `pi-caffeinate.json` wins and the legacy file is ignored.
145
+ The legacy filename is deprecated and will be removed in a future major release.
147
146
 
148
147
  ### Environment variables
149
148
 
@@ -159,9 +158,11 @@ Use a custom inhibitor command:
159
158
  PI_CAFFEINATE_COMMAND='systemd-inhibit --what=idle:sleep --why="pi running" --mode=block sleep infinity' pi
160
159
  ```
161
160
 
162
- 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.
161
+ The custom command is parsed with shell-like quoting and is run directly without a shell.
162
+ `PI_CAFFEINATE_COMMAND` takes precedence over the saved mode; `/caffeinate status` reports when a custom command is active.
163
163
 
164
- 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`:
164
+ Deprecated: `PI_CAFFEINATE_ICON` still works for now.
165
+ If you use `@narumitw/pi-statusline`, move the icon to `${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-statusline.json`:
165
166
 
166
167
  ```json
167
168
  {
@@ -171,18 +172,20 @@ Deprecated: `PI_CAFFEINATE_ICON` still works for now. If you use `@narumitw/pi-s
171
172
  }
172
173
  ```
173
174
 
174
- 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.
175
+ Without `@narumitw/pi-statusline`, keep using `PI_CAFFEINATE_ICON` during the compatibility window.
176
+ In `pi-statusline.json`, use an empty string to show the caffeinate status without an icon.
175
177
 
176
178
  ## 🧠 Why use pi-caffeinate?
177
179
 
178
- 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.
180
+ AI coding agents often run tool-heavy tasks that take several minutes.
181
+ `pi-caffeinate` keeps your machine awake during active Pi work, helping browser automation, local builds, test runs, code generation, and long prompts finish reliably.
179
182
 
180
- 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.
183
+ The default display-awake mode prioritizes uninterrupted long-running Pi work across platforms, including Linux desktops that require idle inhibition to prevent automatic suspend.
184
+ 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.
181
185
 
182
186
  ## 📦 Dependencies
183
187
 
184
- On Linux, `display` mode uses the `dbus-native` package (pure JavaScript, no native build step) to
185
- call `org.freedesktop.ScreenSaver` on the session bus.
188
+ On Linux, `display` mode uses the `dbus-native` package (pure JavaScript, no native build step) to call `org.freedesktop.ScreenSaver` on the session bus.
186
189
 
187
190
  ## 🗂️ Package layout
188
191
 
@@ -192,13 +195,20 @@ packages/pi-caffeinate/
192
195
  │ ├── index.ts # Pi package entrypoint
193
196
  │ ├── caffeinate.ts # Extension registration and lifecycle orchestration
194
197
  │ └── *.ts # Package-local inhibitor and settings modules
198
+ ├── dist/ # Generated source-mapped Jiti runtime
199
+ ├── scripts/
200
+ │ └── build-runtime.mjs
201
+ ├── test/
202
+ │ ├── build-runtime.test.ts
203
+ │ └── caffeinate.test.ts
195
204
  ├── README.md
196
205
  ├── LICENSE
197
206
  ├── tsconfig.json
198
207
  └── package.json
199
208
  ```
200
209
 
201
- `index.ts` is the Pi entrypoint and forwards to `caffeinate.ts`; the other source modules are internal.
210
+ `src/index.ts` remains the thin authoritative forwarder, while Pi loads the generated `dist/index.ts` runtime.
211
+ The other source modules are internal.
202
212
 
203
213
  ## 🔎 Keywords
204
214
 
@@ -206,4 +216,5 @@ Pi extension, Pi coding agent, caffeinate, prevent sleep, keep awake, sleep inhi
206
216
 
207
217
  ## 📄 License
208
218
 
209
- MIT. See [`LICENSE`](./LICENSE).
219
+ MIT.
220
+ See [`LICENSE`](./LICENSE).