pi-farm 0.0.0-stage → 0.2.0

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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 HardyDou
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,399 @@
1
- # Temporary Holding Version
1
+ # pp · 用一个 YAML 管住一农场 pi agent
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![ci](https://github.com/HardyDou/pi-plus/actions/workflows/ci.yml/badge.svg)](https://github.com/HardyDou/pi-plus/actions/workflows/ci.yml)
4
+ [![npm](https://img.shields.io/npm/v/pi-farm.svg)](https://www.npmjs.com/package/pi-farm)
5
+
6
+ > Declarative tmux farm for [pi](https://github.com/badlogic/pi-mono) agents.
7
+ > One YAML file drives the **tmux session**, the **pi session id/name** and the
8
+ > **remote-pi mesh name** — and everything comes back after a reboot.
9
+
10
+ ```
11
+ pi-plus.yml ──► tmux new-session -d -s backend -c ~/code/backend -- pi --name backend --session-id 1a2b3c4d
12
+ │ │ │ │
13
+ │ │ │ └─ 续接/新建 pi session
14
+ │ │ └─ pi 会话显示名 + remote-pi 名称
15
+ │ └─ 工作目录
16
+ └─ tmux session 名(默认三个名字共用一个)
17
+ ```
18
+
19
+ ---
20
+
21
+ ## 特性
22
+
23
+ - **一份 YAML,三层名字**:`tmux session` / `pi --name` / `remote-pi` 默认全部等于 `name`,也可分别覆盖。
24
+ - **续接或新建 pi session**:`pi_session` 填 session id 就续接(不存在则以该 id 新建),填 `.jsonl` 路径就 `--session`。
25
+ - **真正在后台跑**:`tmux new-session -d`,关掉终端不掉线;`pp attach` 随时接管。
26
+ - **开机自启**:Linux systemd user unit / macOS launchd,`--watch` 还能定时巡检自动补活。
27
+ - **零依赖**:单文件 Node CLI,自带 YAML 子集解析器,不装 `js-yaml`、不需要 Python。
28
+ - **可脚本化**:`--json`、`--dry-run`、`--quiet`,退出码可用(`up` 有失败即 1)。
29
+ - **安全默认**:不经过 shell 拼接命令;tmux 名做白名单校验;重建前先 `check`。
30
+
31
+ ## 安装
32
+
33
+ ```bash
34
+ # 从 npm 安装(包名 pi-farm,装完命令就是 pp)
35
+ npm i -g pi-farm
36
+
37
+ # 或直接从 GitHub 安装
38
+ npm i -g github:HardyDou/pi-plus
39
+
40
+ # 或克隆后本地软链到 ~/.local/bin/pp
41
+ git clone https://github.com/HardyDou/pi-plus.git
42
+ cd pi-plus && ./install.sh
43
+ # 直接运行也可以:node bin/pp.js <command>
44
+ ```
45
+
46
+ 依赖:Node.js ≥ 18、tmux、pi(非 pi 的 agent 也可以,见 `agent` 字段)。
47
+
48
+ Shell 补全(可选):
49
+
50
+ ```bash
51
+ source completions/pp.bash # bash
52
+ fpath+=(~/path/to/pi-plus/completions); compinit # zsh
53
+ ```
54
+
55
+ ## 快速开始
56
+
57
+ ```bash
58
+ pp init # 生成 ~/.pi/plus.yml(或 --local 生成 ./pi-plus.yml)
59
+ $EDITOR ~/.pi/plus.yml
60
+ pp check # 只校验配置,不碰 tmux
61
+ pp doctor # 环境体检:node / tmux / pi / 自启
62
+ pp up # 后台拉起所有 session
63
+ pp status # 看状态:序号、tmux 名、pid、pi session、remote-pi 名
64
+ pp attach backend # 进入某个 session(没启动会先启动)
65
+ pp attach 3 # 也可以直接给序号(pp ls 第一列的 #)
66
+ pp up --dry-run -v # 只打印将要执行的 tmux 命令
67
+ ```
68
+
69
+ 按名字操作,省略即全部(`restart: no` 的会话不参与,见下文策略):
70
+
71
+ ```bash
72
+ pp up backend docs
73
+ pp restart backend
74
+ pp down backend # 只停一个
75
+ pp down # 全部停掉
76
+ ```
77
+
78
+ > 被单独 `down` 掉的会话会不会被拉回来,取决于它的 `restart` 策略——
79
+ > `unless-stopped` / `on-failure` 会记住这次手动停止,`always` 会在下个巡检周期回来。
80
+
81
+ ## 临时开一个(不写配置)
82
+
83
+ 不想动配置文件时,直接在当前目录(或 `-C` 指定的目录)开一个:
84
+
85
+ ```bash
86
+ pp new # 名字 = 目录名(tmux 安全字符,重名自动加 -2)
87
+ pp new api -C ~/code/api # 指定目录 + 名字
88
+ pp new scratch --agent bash --log -a # 别的 agent、留日志、进去(简写 n)
89
+ pp n api --save # 同时写进配置文件,重启后自动拉起
90
+ ```
91
+
92
+ - 名字默认取**目标目录名**,会被规整成 tmux 安全字符(空格/中文/`.` → `-`);目录名已被占用时自动 `-2`、`-3`
93
+ - 默认 agent 是 `pi`,自动带 `--name <会话名>`;remote-pi 名称同样取会话名,通过**环境变量**注入(`remote_pi_mode: env`),不会改写项目里的 `.pi/remote-pi/config.json`
94
+ - 常用选项:`-C/--dir`、`--agent`、`--log`、`--save`、`-a/--attach`、`--no-remote-pi`、`--force`、`--dry-run`
95
+ - `pp new` 不依赖任何配置文件;`--save` 会在**没有配置时新建** `~/.pi/plus.yml`(或 `-c` / `$PI_PLUS_CONFIG` 指向的路径)并追加这一条
96
+
97
+ ## 配置参考
98
+
99
+ ```yaml
100
+ version: 1
101
+
102
+ # 可选:所有 session 跑在独立 tmux socket 上(等价于每条命令都加 --socket pi-plus)
103
+ # tmux:
104
+ # socket: pi-plus
105
+
106
+ defaults: # 所有 session 的默认值
107
+ agent: pi # 可写成 "pi --verbose",按空格分词、不经 shell
108
+ args: [] # 追加参数:["--approve"]
109
+ env: {} # 追加环境变量
110
+
111
+ sessions:
112
+ - name: backend # 必填;tmux / pi / remote-pi 的默认名
113
+ cwd: ~/code/backend # 必填;支持 ~ 与相对路径(相对配置文件所在目录)
114
+
115
+ # ---- 以下全部可选 ----
116
+ tmux_name: backend # tmux session 名(默认 name)
117
+ pi_session_name: backend # pi --name(默认 name)
118
+ remote_pi_name: backend # remote-pi 名(默认 name;false/null 表示不设置)
119
+ remote_pi_mode: config # config | env | off(默认 config)
120
+
121
+ pi_session: 1a2b3c4d # pi session id;或 ~/.pi/.../x.jsonl 路径
122
+ # pi_session_dir: ~/.pi/agent/sessions # 可选,传给 --session-dir
123
+
124
+ agent: pi # 覆盖 defaults.agent(bash / claude / "pi --verbose" 都行)
125
+ args: ["--approve"] # 追加参数
126
+ env: # 覆盖/追加环境变量
127
+ TZ: Asia/Shanghai
128
+ restart: unless-stopped # no | always | on-failure | unless-stopped
129
+ log: ~/.pi/plus/backend.log # 可选:pipe-pane 落盘
130
+ remain_on_exit: false # 可选:进程退出后保留 pane 便于看报错
131
+ ```
132
+
133
+ 字段速查:
134
+
135
+ | 字段 | 默认 | 说明 |
136
+ | --- | --- | --- |
137
+ | `name` | 必填 | 会话逻辑名,也是另外三个名字的默认值 |
138
+ | `cwd` | 必填 | 工作目录,不存在则 `up` 直接报错 |
139
+ | `tmux_name` | `name` | tmux session 名,白名单 `[A-Za-z0-9][A-Za-z0-9_-]*` |
140
+ | `pi_session_name` | `name` | `pi --name`,会话列表里显示的名字 |
141
+ | `remote_pi_name` | `name` | remote-pi mesh 名,自动 sanitize(空格/斜杠→`-`) |
142
+ | `remote_pi_mode` | `config` | `config` 写 `<cwd>/.pi/remote-pi/config.json`;`env` 用 `REMOTE_PI_DIRECT_CONFIG`;`off` 不设置 |
143
+ | `pi_session` | 新会话 | session id(`--session-id`)或 `.jsonl` 路径(`--session`) |
144
+ | `pi_session_dir` | pi 默认 | `--session-dir` |
145
+ | `agent` | `pi` | 启动命令,支持带参数;非 `pi` 时不追加 pi 专用flag |
146
+ | `args` | `[]` | 追加到命令末尾 |
147
+ | `env` | `{}` | 注入环境变量 |
148
+ | `restart` | `always` | 拉起策略,取值见下节(对齐 docker compose) |
149
+ | `log` | 无 | `pipe-pane` 输出文件 |
150
+ | `remain_on_exit` | `false` | 保留 dead pane;`restart: no` 会自动开启 |
151
+
152
+ ### restart 策略(和 docker compose 一致)
153
+
154
+ | 值 | 裸 `up` / 开机自启 | `--watch` 巡检 / 崩溃后 | 手动 `down <name>` 之后 |
155
+ | --- | --- | --- | --- |
156
+ | `always`(默认) | 启动 | 补起 | 下次 `up` / 巡检仍会启动 |
157
+ | `no` | 跳过 | 跳过 | —(只能 `up <name>` 手动启动) |
158
+ | `unless-stopped` | 启动 | 补起 | 记住这次停止,自启/巡检都不碰;`up <name>` 解除 |
159
+ | `on-failure` | 启动 | 只在 pane 进程异常退出(dead pane)时补起 | 同 `unless-stopped` |
160
+
161
+ 判定规则:
162
+
163
+ - 不带名字的命令只处理 `restart != no` 的会话;`up <name>` / `restart <name>` 永远生效,
164
+ 并会清除"手动停止"记录。
165
+ - 会话存在但 pane 已经死了(agent 进程退出)时,`up` 对 `restart != no` 的会话会重建;
166
+ `restart: no` 会保留 dead pane(自动打开 `remain-on-exit`),`status` 显示 `dead`,
167
+ `pp logs <name>` 还能看到它最后吐出来的报错,`up <name>` 才会重建。
168
+ - 这和 compose 里 `docker compose ps` 还能看到 `Exited (1)` 的容器是一个意思。
169
+ - 手动停止记录存在 `$XDG_STATE_HOME/pi-plus/state.json`(默认 `~/.local/state/pi-plus/state.json`),
170
+ 按配置文件路径 + 会话名区分。
171
+ - 开机自启用的就是"巡检语义":`pp up --config <cfg> --reconcile --quiet`,
172
+ 所以 `unless-stopped` / `on-failure` 在你手动停掉后不会在重启时自己回来。
173
+
174
+ ```yaml
175
+ sessions:
176
+ - name: backend
177
+ cwd: ~/code/backend
178
+ restart: always # 常驻,挂了就补
179
+
180
+ - name: experiment
181
+ cwd: ~/code/exp
182
+ restart: no # 不参与自动拉起,只按需 pp up experiment
183
+ ```
184
+
185
+ ### 名字映射:一个名字,三处生效
186
+
187
+ | 想设置 | 字段 | 实际效果 |
188
+ | --- | --- | --- |
189
+ | tmux session | `tmux_name` | `tmux new-session -s <name>` |
190
+ | pi 会话名 | `pi_session_name` | `pi --name <name>`(续接旧会话也会改名) |
191
+ | remote-pi mesh 名 | `remote_pi_name` | 写 `agent_name` 到 `<cwd>/.pi/remote-pi/config.json` |
192
+
193
+ 三个都不写时全部等于 `name`,所以最简配置只有两行:
194
+
195
+ ```yaml
196
+ sessions:
197
+ - { name: backend, cwd: ~/code/backend }
198
+ ```
199
+
200
+ > remote-pi 的 `agent_name` 是**按目录**存的。同一 `cwd` 下多个 session 配不同
201
+ > `remote_pi_name`(且用默认的 `remote_pi_mode: config`)会互相覆盖,`pi-plus` 会给出
202
+ > warning;想让同目录多个 agent 各自有名字,用 `remote_pi_mode: env`(每个进程独立
203
+ > 环境变量),这样 `pp check` 不再告警。
204
+
205
+ > 小提示:`remote_pi_mode: config` 会在项目里生成 `.pi/remote-pi/config.json`,
206
+ > 建议加到全局 gitignore:`echo '.pi/remote-pi/' >> ~/.config/git/ignore`。
207
+
208
+ ## 帮助
209
+
210
+ ```bash
211
+ pp help # 总览:命令表、全局选项、restart 策略、配置示例
212
+ pp help up # 单命令:用法、说明、选项、示例、相关命令
213
+ pp up --help # 等价写法(-h 也可以)
214
+ pp help ls # 别名也能查,自动解析到 status
215
+ pp help instal # 拼错会给建议:did you mean 'pp help install'?
216
+ ```
217
+
218
+ - `pi-plus` 不带参数 = `pp help`
219
+ - `-h` / `--help` 出现在任何位置都生效,已经写了命令就给该命令的帮助
220
+ - 帮助内容由 `src/help.js` 的 `COMMANDS` 表生成,总览、单命令、补全词表共用一份数据,
221
+ 加新命令时不会出现"文档忘了更新"
222
+
223
+ 退出码:
224
+
225
+ | 码 | 含义 |
226
+ | --- | --- |
227
+ | `0` | 成功 |
228
+ | `1` | 运行时失败(会话启动失败、doctor 有检查项不通过) |
229
+ | `2` | 用法/配置错误(未知命令、未知选项、配置校验失败、找不到配置) |
230
+
231
+ ## 命令参考
232
+
233
+ 凡是接 `<name>` 的地方都可以写成 `pp ls` 的 `#` 序号(1 起,按配置顺序;
234
+ 若真有会话叫这个名字,名字优先):`pp attach 3`、`pp logs 3`、`pp down 2 5`。
235
+
236
+ ```
237
+ pp new [name] [opts] 在当前目录/指定目录临时开一个(别名 n、create)
238
+ pp up [name|#...] 后台创建/启动(--force 重建已在跑的;别名 start)
239
+ pp down [name|#...] 停止
240
+ pp restart [name|#...] 重启(遵守 restart 策略)
241
+ pp status [name|#...] 状态表,第一列是 # 序号(--json 机器可读;别名 ls/list)
242
+ pp attach <name|#> 进入;不存在则先启动
243
+ pp logs <name|#> [-n 200] 打印滚动输出
244
+ pp send <name|#> "文本" 往 pane 里打字并回车(--no-enter 不回车)
245
+ pp check 校验配置
246
+ pp doctor 环境诊断(含自启状态、WSL 提示)
247
+ pp init 写示例配置
248
+ pp install [--watch N] 安装开机自启(别名 autostart)
249
+ pp uninstall 卸载自启
250
+ pp help [命令] 帮助(不带参数为总览)
251
+ pp version 打印版本
252
+ ```
253
+
254
+ 全局选项:`-c/--config`、`--socket`、`--json`、`--dry-run`、`--force`、`-q`、`-v`、`-h`、`-V`。
255
+
256
+ `--reconcile` 是给自启/巡检用的:跳过被手动停止的 `unless-stopped` / `on-failure` 会话。
257
+ 日常手动 `up` 不需要它。
258
+
259
+ 配置文件查找顺序:
260
+
261
+ 1. `-c/--config <path>`
262
+ 2. `$PI_PLUS_CONFIG`
263
+ 3. `./pi-plus.yml`、`./pi-plus.yaml`、`./plus.yml`、`./plus.yaml`
264
+ 4. `~/.pi/plus.yml`、`~/.pi/plus.yaml`
265
+ 5. `$XDG_CONFIG_HOME/pi-plus/config.yml`(默认 `~/.config/pi-plus/config.yml`)
266
+
267
+ ## 开机自启
268
+
269
+ ```bash
270
+ pp install # 开机/登录时按 restart 策略 up 一次
271
+ pp install --watch 300 # 另外每 5 分钟巡检,挂了自动补
272
+ pp install --print # 只打印 unit/plist,不落盘
273
+ pp uninstall
274
+ ```
275
+
276
+ **Linux(systemd user unit)**:写入 `~/.config/systemd/user/pi-plus.service`,
277
+ `systemctl --user enable`。要开机即启动(不用先登录)需要一次 linger:
278
+
279
+ ```bash
280
+ sudo loginctl enable-linger $USER
281
+ ```
282
+
283
+ **macOS(launchd)**:写入 `~/Library/LaunchAgents/com.pi-plus.plist`,
284
+ `RunAtLoad` 登录即启动;`--watch` 用 `StartInterval` 定时巡检;日志在
285
+ `~/Library/Logs/pi-plus.log`。
286
+
287
+ **WSL2**:分两半,缺一不可。
288
+
289
+ 1) WSL 内部(`pp install` 能做的部分):
290
+ - `/etc/wsl.conf` 里 `[boot] systemd=true`(较新 WSL 默认开启,可用 `cat /etc/wsl.conf` 确认)
291
+ - `sudo loginctl enable-linger $USER`:不登录也能启动 user 服务
292
+ - `pp install`:写 `~/.config/systemd/user/pi-plus.service` 并 enable
293
+
294
+ 2) Windows 侧(**WSL 内部再怎么配也做不到**):Windows 重启后 WSL 发行版本身不会自己
295
+ 启动,没有任何进程能替你触发它。必须由 Windows 上的一次动作把发行版拉起来,例如
296
+ 登录时执行(PowerShell,无需管理员):
297
+
298
+ ```powershell
299
+ $p = "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Startup\pi-plus.vbs"
300
+ Set-Content -Encoding ASCII $p 'Set s = CreateObject("WScript.Shell") : s.Run "wsl.exe -d <发行版名> -u <用户名> -e /bin/true", 0, False'
301
+ ```
302
+
303
+ 把 `<发行版名>` 换成 `wsl -l -v` 里的名字(例如 `Ubuntu-24.04`)。也可以用任务计划
304
+ 程序建一个“登录时”任务,动作同样是 `wsl.exe -d <发行版名> -u <用户名> -e /bin/true`。
305
+
306
+ 原理:这条命令把发行版启动起来(systemd 成为 PID 1 并常驻),`--reconcile` 的
307
+ `pi-plus.service` 随即按各会话的 `restart` 策略拉起 agent;命令本身会立刻退出,
308
+ VBScript 用隐藏窗口跑,不闪黑框。
309
+
310
+ > 只配 WSL 内部、不配 Windows 侧:`wsl --shutdown` 或重启后不会有任何会话,直到你手动
311
+ > 打开一次终端。`pp doctor` 在 WSL 下会多打一行 `wsl` 提示这件事。
312
+
313
+ ## 续接已有 pi 会话
314
+
315
+ ```bash
316
+ # 1) 找到 session id:文件名就是 id
317
+ ls ~/.pi/agent/sessions/--<cwd编码>--/
318
+ # 编码规则:绝对路径里的 "/" 换成 "-",例如 /home/me/code → --home-me-code--
319
+ # 也可以在目录里跑 `pi --resume` 从列表里挑,再按提示查看 id
320
+
321
+ # 2) 写进配置
322
+ sessions:
323
+ - name: backend
324
+ cwd: ~/code/backend
325
+ pi_session: 1a2b3c4d # id 不存在时 pi 会以该 id 新建
326
+ ```
327
+
328
+ 同理,把之前手动 `tmux new -s xxx` 起的会话迁过来:先 `pp down`,
329
+ 或者直接 `tmux kill-session -t xxx` 后 `pp up`。
330
+
331
+ ## 排障
332
+
333
+ | 现象 | 处理 |
334
+ | --- | --- |
335
+ | `session "x" exited immediately` | `-v` 看实际命令;先用 `check` 确认 cwd/agent;临时加 `remain_on_exit: true` 看报错 |
336
+ | `tmux ... can't find pane` | 老版本 bug,升级;pane 目标需要 `=name:` 形式 |
337
+ | remote-pi 名字不对 | 看 `<cwd>/.pi/remote-pi/config.json` 的 `agent_name`;同名冲突时 broker 可能显示 `name#2` |
338
+ | 自启没生效 | `systemctl --user status pi-plus`;WSL 确认 systemd 开启;`pp doctor` |
339
+ | pi 找不到 | systemd 的 PATH 由 `install` 自动写入 node 所在目录;自定义路径用 `agent: /abs/path/pi` |
340
+
341
+ ## 开发
342
+
343
+ ```bash
344
+ npm test # node --test,纯单元测试,不需要 tmux
345
+ ./test/e2e.sh # 端到端冒烟测试(需 tmux/pi,约 3 分钟,会临时装一个 systemd unit 再删掉)
346
+ node bin/pp.js --help
347
+ ```
348
+
349
+ 代码结构:
350
+
351
+ ```
352
+ bin/pp.js CLI 入口、参数解析
353
+ src/config.js YAML → 归一化配置、argv 构建
354
+ src/yaml.js 零依赖 YAML 子集解析器
355
+ src/tmux.js tmux 封装(含 dry-run 只读查询)
356
+ src/remote-pi.js remote-pi 配置读写
357
+ src/autostart.js systemd / launchd 模板与安装
358
+ src/commands.js 各子命令实现
359
+ ```
360
+
361
+ ## English
362
+
363
+ `pi-plus` keeps a farm of [pi](https://github.com/badlogic/pi-mono) coding
364
+ agents alive in tmux. Declare sessions in one YAML file; each session gets a
365
+ tmux session, a pi session (resumed by id or freshly created), a pi display
366
+ name, and a remote-pi mesh name — all defaulting to the same `name`.
367
+
368
+ ```bash
369
+ npm i -g github:HardyDou/pi-plus
370
+ pp init && $EDITOR ~/.pi/plus.yml
371
+ pp check && pp up && pp status
372
+ pp attach backend
373
+ pp install --watch 300 # survive reboots, reconcile every 5 min
374
+ ```
375
+
376
+ Minimal config:
377
+
378
+ ```yaml
379
+ version: 1
380
+ sessions:
381
+ - name: backend
382
+ cwd: ~/code/backend
383
+ pi_session: 1a2b3c4d # optional: resume (or create) this pi session
384
+ ```
385
+
386
+ Name overrides: `tmux_name`, `pi_session_name`, `remote_pi_name`.
387
+ remote-pi mode: `config` (default, writes `<cwd>/.pi/remote-pi/config.json`),
388
+ `env` (`REMOTE_PI_DIRECT_CONFIG`), `off`.
389
+
390
+ Commands: `up`, `down`, `restart`, `status`, `attach`, `logs`, `send`, `check`,
391
+ `doctor`, `init`, `install`, `uninstall`. Options: `--config`, `--socket`,
392
+ `--json`, `--dry-run`, `--force`, `--watch`, `--lines`, `--quiet`, `--verbose`.
393
+
394
+ Zero runtime dependencies. Requires Node.js ≥ 18, tmux, and pi (any command
395
+ works via `agent:`).
396
+
397
+ ## License
398
+
399
+ MIT © 2026 HardyDou
package/bin/pp.js ADDED
@@ -0,0 +1,138 @@
1
+ #!/usr/bin/env node
2
+ import { readFileSync, realpathSync } from "node:fs";
3
+ import { resolve } from "node:path";
4
+ import { runCommand } from "../src/commands.js";
5
+ import { renderCommandHelp, renderOverview, suggestCommand } from "../src/help.js";
6
+
7
+ const VERSION = (() => {
8
+ try {
9
+ return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
10
+ } catch {
11
+ return "0.0.0";
12
+ }
13
+ })();
14
+
15
+
16
+ function fail(message) {
17
+ process.stderr.write(`error: ${message}\n`);
18
+ process.exit(2);
19
+ }
20
+
21
+ function parseArgs(argv) {
22
+ const options = { names: [], cwd: process.cwd(), json: false, quiet: false, verbose: false };
23
+ let command = null;
24
+ const args = [...argv];
25
+
26
+ const takeValue = (flag, inline) => {
27
+ if (inline !== undefined) return inline;
28
+ const next = args.shift();
29
+ if (next === undefined) fail(`${flag} requires a value`);
30
+ return next;
31
+ };
32
+
33
+ while (args.length > 0) {
34
+ const arg = args.shift();
35
+ if (arg === "--") {
36
+ options.names.push(...args);
37
+ break;
38
+ }
39
+ if (arg.startsWith("--")) {
40
+ const eq = arg.indexOf("=");
41
+ const flag = eq === -1 ? arg : arg.slice(0, eq);
42
+ const inline = eq === -1 ? undefined : arg.slice(eq + 1);
43
+ switch (flag) {
44
+ case "--config": options.config = takeValue(flag, inline); break;
45
+ case "--socket": options.socket = takeValue(flag, inline); break;
46
+ case "--json": options.json = true; break;
47
+ case "--dry-run": options.dryRun = true; break;
48
+ case "--force": options.force = true; break;
49
+ case "--reconcile": options.reconcile = true; break;
50
+ case "--quiet": options.quiet = true; break;
51
+ case "--verbose": options.verbose = true; break;
52
+ case "--lines": options.lines = Number(takeValue(flag, inline)) || 200; break;
53
+ case "--no-enter": options.noEnter = true; break;
54
+ case "--print": options.print = true; break;
55
+ case "--watch": {
56
+ if (inline !== undefined) options.watch = Number(inline) || 300;
57
+ else if (args.length > 0 && /^\d+$/.test(args[0])) options.watch = Number(args.shift());
58
+ else options.watch = 300;
59
+ break;
60
+ }
61
+ case "--dir": options.dir = takeValue(flag, inline); break;
62
+ case "--agent": options.agent = takeValue(flag, inline); break;
63
+ case "--log": options.log = true; break;
64
+ case "--save": options.save = true; break;
65
+ case "--attach": options.attach = true; break;
66
+ case "--no-remote-pi": options.noRemotePi = true; break;
67
+ case "--local": options.local = true; break;
68
+ case "--path": options.path = takeValue(flag, inline); break;
69
+ case "--help": process.exit(showHelp(command));
70
+ case "--version": process.stdout.write(`${VERSION}\n`); process.exit(0); break;
71
+ default: fail(`unknown option: ${arg}`);
72
+ }
73
+ continue;
74
+ }
75
+ if (arg === "-C") { options.dir = takeValue(arg); continue; }
76
+ if (arg === "-a") { options.attach = true; continue; }
77
+ if (arg === "-c" || arg === "-q" || arg === "-v" || arg === "-n" || arg === "-h" || arg === "-V") {
78
+ switch (arg) {
79
+ case "-c": options.config = takeValue(arg); break;
80
+ case "-q": options.quiet = true; break;
81
+ case "-v": options.verbose = true; break;
82
+ case "-n": options.lines = Number(takeValue(arg)) || 200; break;
83
+ case "-h": process.exit(showHelp(command));
84
+ case "-V": process.stdout.write(`${VERSION}\n`); process.exit(0); break;
85
+ }
86
+ continue;
87
+ }
88
+ if (arg.startsWith("-") && arg !== "-") fail(`unknown option: ${arg}`);
89
+ if (!command) command = arg;
90
+ else options.names.push(arg);
91
+ }
92
+
93
+ return { command, options };
94
+ }
95
+
96
+ function scriptPath() {
97
+ const argv1 = process.argv[1];
98
+ try {
99
+ return realpathSync(resolve(argv1));
100
+ } catch {
101
+ return resolve(argv1);
102
+ }
103
+ }
104
+
105
+ function showHelp(name) {
106
+ if (!name) {
107
+ process.stdout.write(renderOverview(VERSION));
108
+ return 0;
109
+ }
110
+ const text = renderCommandHelp(VERSION, name);
111
+ if (text) {
112
+ process.stdout.write(text);
113
+ return 0;
114
+ }
115
+ process.stderr.write(`error: unknown command: ${name}\n`);
116
+ const suggestion = suggestCommand(name);
117
+ if (suggestion) process.stderr.write(`did you mean 'pp help ${suggestion}'?\n`);
118
+ else process.stderr.write("run 'pp help' to see the command list\n");
119
+ return 2;
120
+ }
121
+
122
+ const { command, options } = parseArgs(process.argv.slice(2));
123
+ options.scriptPath = scriptPath();
124
+
125
+ if (!command) process.exit(showHelp(null));
126
+ if (command === "version") {
127
+ process.stdout.write(`${VERSION}\n`);
128
+ process.exit(0);
129
+ }
130
+ if (command === "help") process.exit(showHelp(options.names[0]));
131
+
132
+ try {
133
+ await runCommand(command, options);
134
+ } catch (err) {
135
+ process.stderr.write(`error: ${err?.message ?? String(err)}\n`);
136
+ if (options.verbose && err?.stack) process.stderr.write(`${err.stack}\n`);
137
+ process.exit(1);
138
+ }
@@ -0,0 +1,66 @@
1
+ #compdef pp pi-plus
2
+ # zsh completion for pp (pi-plus)
3
+ _pp() {
4
+ local -a commands
5
+ commands=(
6
+ 'new:start a one-off session in a directory (alias n)'
7
+ 'n:alias for new'
8
+ 'create:alias for new'
9
+ 'up:start sessions in the background'
10
+ 'start:alias for up'
11
+ 'down:stop sessions'
12
+ 'stop:alias for down'
13
+ 'restart:restart sessions'
14
+ 'status:show tmux/pi/remote-pi state'
15
+ 'ls:alias for status'
16
+ 'attach:attach to a session (starts it if needed)'
17
+ 'logs:print pane output'
18
+ 'send:type text into a pane'
19
+ 'check:validate the config'
20
+ 'doctor:environment diagnostics'
21
+ 'init:write an example config'
22
+ 'install:install reboot autostart'
23
+ 'uninstall:remove autostart'
24
+ 'version:print version'
25
+ 'help:show help (help <command> for one command)'
26
+ )
27
+
28
+ _arguments -C \
29
+ '(-c --config)'{-c,--config}'[config file]:file:_files' \
30
+ '(-h --help)'{-h,--help}'[show help]' \
31
+ '(-V --version)'{-V,--version}'[print version]' \
32
+ '--socket[tmux socket name]:socket:' \
33
+ '--json[machine-readable output]' \
34
+ '--dry-run[print actions without touching tmux]' \
35
+ '--force[recreate running sessions]' \
36
+ '--reconcile[autostart mode: skip sessions stopped by hand]' \
37
+ '--path[init destination]:file:_files' \
38
+ '(-q --quiet)'{-q,--quiet}'[only errors]' \
39
+ '(-v --verbose)'{-v,--verbose}'[echo tmux commands]' \
40
+ '(-C --dir)'{-C,--dir}'[directory for pp new]:dir:_files -/' \
41
+ '--agent[agent command for pp new]:command:' \
42
+ '--log[keep output in ~/.pi/plus/logs]' \
43
+ '--save[append the session to the config file]' \
44
+ '(-a --attach)'{-a,--attach}'[attach after pp new]' \
45
+ '--no-remote-pi[do not set a remote-pi name for pp new]' \
46
+ '(-n --lines)'{-n,--lines}'[scrollback lines]:lines:' \
47
+ '--no-enter[do not press Enter after send]' \
48
+ '--watch[reconcile interval for install]:seconds:' \
49
+ '--print[print autostart unit and exit]' \
50
+ '1:command:->command' \
51
+ '*:session:->session'
52
+
53
+ case $state in
54
+ command) _describe 'command' commands ;;
55
+ session)
56
+ local cfg=${(v)opt_args[(i)-c|--config]}
57
+ [[ -z $cfg ]] && cfg=$HOME/.pi/plus.yml
58
+ if [[ -r $cfg ]]; then
59
+ local -a names
60
+ names=(${(f)"$(sed -n 's/^[[:space:]-]*name:[[:space:]]*\([^[:space:]#]*\).*/\1/p' $cfg)"})
61
+ _describe 'session' names
62
+ fi
63
+ ;;
64
+ esac
65
+ }
66
+ _pp "$@"
@@ -0,0 +1,44 @@
1
+ # bash completion for pp (pi-plus)
2
+ _pp() {
3
+ local cur prev words cword
4
+ COMPREPLY=()
5
+ cur="${COMP_WORDS[COMP_CWORD]}"
6
+ prev="${COMP_WORDS[COMP_CWORD-1]}"
7
+ local commands="new n create up start down stop restart status ls list attach a logs log send check validate doctor init install autostart uninstall version help"
8
+
9
+ case "$prev" in
10
+ -c|--config)
11
+ COMPREPLY=( $(compgen -f -- "$cur") )
12
+ return 0
13
+ ;;
14
+ --socket|--lines|-n|--agent|-C|--dir)
15
+ return 0
16
+ ;;
17
+ attach|a|logs|log|send|down|stop|restart|up|start)
18
+ local cfg="" i
19
+ for ((i = 1; i < COMP_CWORD; i++)); do
20
+ if [[ "${COMP_WORDS[i]}" == "-c" || "${COMP_WORDS[i]}" == "--config" ]]; then
21
+ cfg="${COMP_WORDS[i+1]}"
22
+ fi
23
+ done
24
+ if [[ -n "$cfg" && -r "$cfg" ]]; then
25
+ COMPREPLY=( $(compgen -W "$(sed -n 's/^[[:space:]-]*name:[[:space:]]*\([^[:space:]#]*\).*/\1/p' "$cfg")" -- "$cur") )
26
+ fi
27
+ return 0
28
+ ;;
29
+ esac
30
+
31
+ if [[ "$cur" == -* ]]; then
32
+ COMPREPLY=( $(compgen -W "--config --socket --json --dry-run --force --reconcile --quiet --verbose --lines --watch --print --path --no-enter --attach --log --save --no-remote-pi --dir --agent --help --version" -- "$cur") )
33
+ return 0
34
+ fi
35
+ if [[ $COMP_CWORD -eq 2 && "${COMP_WORDS[1]}" == "help" ]]; then
36
+ COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
37
+ return 0
38
+ fi
39
+ if [[ $COMP_CWORD -eq 1 ]]; then
40
+ COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
41
+ return 0
42
+ fi
43
+ }
44
+ complete -F _pp pp pi-plus