pi-farm 0.2.3 → 0.3.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/README.md +18 -0
- package/bin/pp.js +1 -0
- package/completions/_pp +4 -1
- package/completions/pp.bash +7 -3
- package/docs/architecture.md +2 -1
- package/docs/cli.md +18 -0
- package/docs/troubleshooting.md +22 -0
- package/package.json +4 -2
- package/src/aliases.js +204 -0
- package/src/commands.js +193 -3
- package/src/help.js +33 -4
- package/src/mesh.js +15 -0
package/README.md
CHANGED
|
@@ -46,6 +46,22 @@ cd pi-plus && ./install.sh
|
|
|
46
46
|
|
|
47
47
|
依赖:Node.js ≥ 18、tmux、pi(非 pi 的 agent 也可以,见 `agent` 字段)。
|
|
48
48
|
|
|
49
|
+
### 命令名被别的程序占了?(macOS 自带 `/usr/bin/pp`)
|
|
50
|
+
|
|
51
|
+
macOS 上 `/usr/bin/pp` 是一个 ASN.1 转换工具,`pp ls` 会打出它的用法说明。除了 `pp`,安装时还会一起装两个名字:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
pifarm ls # 等价于 pp ls
|
|
55
|
+
pi-plus ls
|
|
56
|
+
|
|
57
|
+
pp alias add pif # 或者自己起个短名字(软链到同一个脚本,升级不会失效)
|
|
58
|
+
pp alias ls # 看有哪些别名、目录是否在 PATH 里
|
|
59
|
+
pp alias rm pif
|
|
60
|
+
pp doctor # 会提示 PATH 上的 pp 到底是不是我们
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
`install.sh` 也支持换名字:`PP_BIN_NAME=pifarm ./install.sh`(或 `PP_BIN_NAME="pp pif"`)。
|
|
64
|
+
|
|
49
65
|
> 若你的 `npm config get registry` 指向内网镜像(例如 Nexus),装不到这个包时显式指定公共源:
|
|
50
66
|
> `npm i -g pi-farm --registry https://registry.npmjs.org/`
|
|
51
67
|
|
|
@@ -284,6 +300,7 @@ pp doctor 环境诊断(含自启状态、WSL 提示)
|
|
|
284
300
|
pp init 写示例配置
|
|
285
301
|
pp install [--watch N] 安装开机自启(别名 autostart)
|
|
286
302
|
pp uninstall 卸载自启
|
|
303
|
+
pp alias [ls|add|rm] 换/加一个命令名(pp 被别的程序占用时用)
|
|
287
304
|
pp help [命令] 帮助(不带参数为总览)
|
|
288
305
|
pp version 打印版本
|
|
289
306
|
```
|
|
@@ -378,6 +395,7 @@ sessions:
|
|
|
378
395
|
| remote-pi 名字不对 | 看 `<cwd>/.pi/remote-pi/config.json` 的 `agent_name`;同名冲突时 broker 可能显示 `name#2` |
|
|
379
396
|
| 自启没生效 | `systemctl --user status pi-plus`;WSL 确认 systemd 开启;`pp doctor` |
|
|
380
397
|
| pi 找不到 | systemd 的 PATH 由 `install` 自动写入 node 所在目录;自定义路径用 `agent: /abs/path/pi` |
|
|
398
|
+
| `pp ls` 打出一大段 ASN.1 用法 | 那是 macOS 自带的 `/usr/bin/pp`。用 `pifarm ls`,或 `pp alias add pif` 换个名字(见[安装](#命令名被别的程序占了macos-自带-usrbinpp)) |
|
|
381
399
|
|
|
382
400
|
## 开发
|
|
383
401
|
|
package/bin/pp.js
CHANGED
|
@@ -68,6 +68,7 @@ function parseArgs(argv) {
|
|
|
68
68
|
case "--wait": options.wait = Number(takeValue(flag, inline)) || 5000; break;
|
|
69
69
|
case "--no-wait": options.noWait = true; break;
|
|
70
70
|
case "--body-json": options.bodyJson = takeValue(flag, inline); break;
|
|
71
|
+
case "--bin-dir": options.binDir = takeValue(flag, inline); break;
|
|
71
72
|
case "--reply": options.reply = Number(takeValue(flag, inline)) || 0; break;
|
|
72
73
|
case "--local": options.local = true; break;
|
|
73
74
|
case "--path": options.path = takeValue(flag, inline); break;
|
package/completions/_pp
CHANGED
|
@@ -16,12 +16,14 @@ _pp() {
|
|
|
16
16
|
'attach:attach to a session (starts it if needed)'
|
|
17
17
|
'logs:print pane output'
|
|
18
18
|
'send:type text into a pane'
|
|
19
|
-
'mesh:remote-pi mesh (ls/send/resolve)'
|
|
19
|
+
'mesh:remote-pi mesh (ls/send/resolve/inbox)'
|
|
20
20
|
'check:validate the config'
|
|
21
21
|
'doctor:environment diagnostics'
|
|
22
22
|
'init:write an example config'
|
|
23
23
|
'install:install reboot autostart'
|
|
24
24
|
'uninstall:remove autostart'
|
|
25
|
+
'alias:add another command name (ls/add/rm)'
|
|
26
|
+
'link:alias for alias'
|
|
25
27
|
'version:print version'
|
|
26
28
|
'help:show help (help <command> for one command)'
|
|
27
29
|
)
|
|
@@ -51,6 +53,7 @@ _pp() {
|
|
|
51
53
|
'--reply[wait for a reply after the ACK]:ms:' \
|
|
52
54
|
'--no-wait[do not wait for the mesh ACK]' \
|
|
53
55
|
'--body-json[mesh body as JSON]:json:' \
|
|
56
|
+
'--bin-dir[directory for pp alias symlinks]:dir:_files -/' \
|
|
54
57
|
'--watch[reconcile interval for install]:seconds:' \
|
|
55
58
|
'--print[print autostart unit and exit]' \
|
|
56
59
|
'1:command:->command' \
|
package/completions/pp.bash
CHANGED
|
@@ -4,7 +4,7 @@ _pp() {
|
|
|
4
4
|
COMPREPLY=()
|
|
5
5
|
cur="${COMP_WORDS[COMP_CWORD]}"
|
|
6
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 mesh check validate doctor init install autostart uninstall version help"
|
|
7
|
+
local commands="new n create up start down stop restart status ls list attach a logs log send mesh check validate doctor init install autostart uninstall alias link version help"
|
|
8
8
|
|
|
9
9
|
case "$prev" in
|
|
10
10
|
-c|--config)
|
|
@@ -15,7 +15,11 @@ _pp() {
|
|
|
15
15
|
return 0
|
|
16
16
|
;;
|
|
17
17
|
mesh)
|
|
18
|
-
COMPREPLY=( $(compgen -W "ls list resolve send" -- "$cur") )
|
|
18
|
+
COMPREPLY=( $(compgen -W "ls list resolve send inbox listen watch" -- "$cur") )
|
|
19
|
+
return 0
|
|
20
|
+
;;
|
|
21
|
+
alias|link)
|
|
22
|
+
COMPREPLY=( $(compgen -W "ls list add create link rm remove delete unlink" -- "$cur") )
|
|
19
23
|
return 0
|
|
20
24
|
;;
|
|
21
25
|
attach|a|logs|log|send|down|stop|restart|up|start)
|
|
@@ -38,7 +42,7 @@ _pp() {
|
|
|
38
42
|
esac
|
|
39
43
|
|
|
40
44
|
if [[ "$cur" == -* ]]; then
|
|
41
|
-
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 --as --wait --reply --no-wait --body-json --help --version" -- "$cur") )
|
|
45
|
+
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 --as --wait --reply --no-wait --body-json --bin-dir --help --version" -- "$cur") )
|
|
42
46
|
return 0
|
|
43
47
|
fi
|
|
44
48
|
if [[ $COMP_CWORD -eq 2 && "${COMP_WORDS[1]}" == "help" ]]; then
|
package/docs/architecture.md
CHANGED
|
@@ -20,8 +20,9 @@ src/remote-pi.js 读写 <cwd>/.pi/remote-pi/config.json,构造 REMOTE_PI_DIR
|
|
|
20
20
|
src/state.js 手动停止记录(XDG state),给 restart 策略用
|
|
21
21
|
src/mesh.js remote-pi broker 的零依赖客户端(探测 / 注册 / 发送 / ACK)
|
|
22
22
|
src/autostart.js systemd / launchd 单元渲染与安装/卸载/状态查询
|
|
23
|
-
src/commands.js 各子命令实现(up/down/restart/status/attach/logs/send/mesh/check/doctor/init/install/new)
|
|
23
|
+
src/commands.js 各子命令实现(up/down/restart/status/attach/logs/send/mesh/check/doctor/init/install/new/alias)
|
|
24
24
|
src/help.js COMMANDS 单一数据源 + 总览/单命令页/拼写建议
|
|
25
|
+
src/aliases.js 备用命令名(pifarm/pi-plus/自定义软链)+ PATH 上 pp 归属判定
|
|
25
26
|
src/example.js `pp init` 写入的示例配置
|
|
26
27
|
```
|
|
27
28
|
|
package/docs/cli.md
CHANGED
|
@@ -31,6 +31,7 @@ pp <command> [names...] [options]
|
|
|
31
31
|
| `--reply <ms>` | `mesh send` 收到 ACK 后继续监听回复的时长(单播收到第一条即返回) |
|
|
32
32
|
| `--no-wait` | `mesh send` 只发不等 ACK |
|
|
33
33
|
| `--body-json <json>` | `mesh send` 发结构化 JSON(默认发纯文本) |
|
|
34
|
+
| `--bin-dir <dir>` | `alias` 的软链目录,默认 `~/.local/bin` 或 `$PP_BIN_DIR` |
|
|
34
35
|
| `--print` | `install` 只打印单元文件 |
|
|
35
36
|
| `--watch [secs]` | `install` 额外装一个定时器,每 N 秒(默认 300)巡检一次 |
|
|
36
37
|
| `-h, --help` | 帮助(`pp help`、`pp <cmd> --help` 等价) |
|
|
@@ -132,6 +133,23 @@ pp mesh send api --body-json '{"task":"test","id":42}' # 结构化消息
|
|
|
132
133
|
- 地址后缀 `#N` 是 broker 对同 `(cwd, name)` 重复身份的自动去重,`livePeersFor` 会把它一并算作同一个会话
|
|
133
134
|
- 跨机投递走 broker leader 的 relay 桥,发送端不需要做任何配对
|
|
134
135
|
|
|
136
|
+
### `pp alias [ls|add|rm]`
|
|
137
|
+
|
|
138
|
+
管理备用命令名。macOS 自带 `/usr/bin/pp`(ASN.1 工具),所以包内自带 `pifarm`、`pi-plus` 两个名字;`alias` 再加任意短名。
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
pp alias ls # 列出指向本 CLI 的软链 + 目录是否在 PATH
|
|
142
|
+
pp alias add pif # ~/.local/bin/pif → 本 CLI
|
|
143
|
+
pp alias add p --bin-dir /usr/local/bin
|
|
144
|
+
pp alias rm pif
|
|
145
|
+
pp alias ls --json
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
- 默认目录 `~/.local/bin`,可用 `$PP_BIN_DIR` 或 `--bin-dir` 覆盖;不在 PATH 时会提示怎么加
|
|
149
|
+
- 软链指向脚本本身,`npm i -g` 升级后别名自动跟随
|
|
150
|
+
- `add` 遇到同名**非软链**文件会拒绝(`--force` 才替换);`rm` 遇到指向别的程序的软链也会拒绝
|
|
151
|
+
- `pp doctor` 的 `command name` 行会写明哪个名字是我们的、哪个是别人的,以及装在 PATH 上那份的版本
|
|
152
|
+
|
|
135
153
|
### `pp check [name|#...]`
|
|
136
154
|
|
|
137
155
|
只校验配置,不碰 tmux。失败项进 stderr 并退出 1;`notes` 是提示(`restart: no`、手动停过、共享目录写同名等)。JSON:`{ "ok": true, "problems": [], "notes": [], "config": "..." }`。
|
package/docs/troubleshooting.md
CHANGED
|
@@ -2,6 +2,28 @@
|
|
|
2
2
|
|
|
3
3
|
按「你看到的原文」查。每条都附上验证命令。
|
|
4
4
|
|
|
5
|
+
## 命令名类
|
|
6
|
+
|
|
7
|
+
### 敲 `pp ls` 却打出 `Usage: pp [-t type] [-a] [-i input] ...`
|
|
8
|
+
|
|
9
|
+
那是 macOS(以及部分发行版)自带的 ASN.1 工具 `/usr/bin/pp`,不是我们。PATH 里谁靠前谁生效,而 `/usr/bin` 常常压过 npm 的全局 bin。
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
type -a pp # 看 PATH 上有几个 pp
|
|
13
|
+
pp doctor # 会直接写:ours: pp 0.3.0 (installed) / pp → /usr/bin/pp (not pi-plus)
|
|
14
|
+
pifarm ls # 安装时就带的备用名字(另一个是 pi-plus)
|
|
15
|
+
pp alias add pif # 自己起名字:~/.local/bin/pif → 同一个脚本
|
|
16
|
+
pp alias ls # 看已有别名 + 目录是否在 PATH
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
- 别名的默认目录是 `~/.local/bin`(可用 `--bin-dir` 或 `$PP_BIN_DIR` 改),它会提示该目录是否在 PATH 里
|
|
20
|
+
- `pp alias rm <name>` 只删指向本 CLI 的软链;指向别的东西会拒绝,交给你自己处理
|
|
21
|
+
- `install.sh` 也能一步换名:`PP_BIN_NAME=pifarm ./install.sh`,或 `PP_BIN_NAME="pp pif" ./install.sh`
|
|
22
|
+
|
|
23
|
+
### `error: ... is not a valid command name`
|
|
24
|
+
|
|
25
|
+
别名只接受 `[A-Za-z0-9._-]`,且不能以 `-` 开头(避免被当成 flag)。
|
|
26
|
+
|
|
5
27
|
## 启动类
|
|
6
28
|
|
|
7
29
|
### `session "backend" exited immediately`
|
package/package.json
CHANGED
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-farm",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "Declarative tmux sessions for pi coding agents (CLI: pp). One YAML drives the tmux session, pi session id/name and remote-pi mesh name, and survives reboots.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
7
|
-
"pp": "bin/pp.js"
|
|
7
|
+
"pp": "bin/pp.js",
|
|
8
|
+
"pifarm": "bin/pp.js",
|
|
9
|
+
"pi-plus": "bin/pp.js"
|
|
8
10
|
},
|
|
9
11
|
"files": [
|
|
10
12
|
"bin",
|
package/src/aliases.js
ADDED
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
// Alternate command names for people whose `pp` is already taken.
|
|
2
|
+
//
|
|
3
|
+
// macOS ships /usr/bin/pp (an ASN.1 pretty printer) and a few Linux distros
|
|
4
|
+
// do too, so `pp ls` can land on a binary that knows nothing about sessions.
|
|
5
|
+
// The package ships `pifarm` and `pi-plus` as well, and this module manages
|
|
6
|
+
// extra symlinks (pp alias add pif) plus the doctor check that notices when
|
|
7
|
+
// the name on PATH is not us.
|
|
8
|
+
import {
|
|
9
|
+
lstatSync,
|
|
10
|
+
readFileSync,
|
|
11
|
+
mkdirSync,
|
|
12
|
+
readdirSync,
|
|
13
|
+
readlinkSync,
|
|
14
|
+
realpathSync,
|
|
15
|
+
symlinkSync,
|
|
16
|
+
unlinkSync,
|
|
17
|
+
} from "node:fs";
|
|
18
|
+
import { homedir } from "node:os";
|
|
19
|
+
import { delimiter, dirname, join, resolve } from "node:path";
|
|
20
|
+
import { expandPath } from "./config.js";
|
|
21
|
+
import { resolveExecutable } from "./tmux.js";
|
|
22
|
+
|
|
23
|
+
const ALIAS_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
|
|
24
|
+
|
|
25
|
+
/** Names `npm i -g pi-farm` / install.sh create without any extra work. */
|
|
26
|
+
export const BUILTIN_NAMES = ["pp", "pifarm", "pi-plus"];
|
|
27
|
+
|
|
28
|
+
export class AliasError extends Error {
|
|
29
|
+
constructor(message, code = "alias") {
|
|
30
|
+
super(message);
|
|
31
|
+
this.name = "AliasError";
|
|
32
|
+
this.code = code;
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
export function aliasDir(env = process.env, override = null) {
|
|
37
|
+
if (override) return resolve(expandPath(override));
|
|
38
|
+
if (env.PP_BIN_DIR) return resolve(expandPath(env.PP_BIN_DIR));
|
|
39
|
+
return join(homedir(), ".local", "bin");
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
export function assertAliasName(name) {
|
|
43
|
+
if (!name || name.startsWith("-")) {
|
|
44
|
+
throw new AliasError("alias name is required, e.g. pp alias add pif", "usage");
|
|
45
|
+
}
|
|
46
|
+
if (!ALIAS_NAME_RE.test(name) || name === "." || name === "..") {
|
|
47
|
+
throw new AliasError(
|
|
48
|
+
`"${name}" is not a valid command name; use letters, digits, "-", "_" and "."`,
|
|
49
|
+
"invalid_name",
|
|
50
|
+
);
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
function readlink(path) {
|
|
55
|
+
try {
|
|
56
|
+
return readlinkSync(path);
|
|
57
|
+
} catch {
|
|
58
|
+
return null;
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
export function sameTarget(linkPath, target) {
|
|
63
|
+
try {
|
|
64
|
+
return realpathSync(linkPath) === realpathSync(target);
|
|
65
|
+
} catch {
|
|
66
|
+
return false;
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** `{name, path, symlink, target}` or null when nothing is there. */
|
|
71
|
+
export function readAlias(dir, name) {
|
|
72
|
+
const path = join(dir, name);
|
|
73
|
+
let stat;
|
|
74
|
+
try {
|
|
75
|
+
stat = lstatSync(path);
|
|
76
|
+
} catch {
|
|
77
|
+
return null;
|
|
78
|
+
}
|
|
79
|
+
const symlink = stat.isSymbolicLink();
|
|
80
|
+
return { name, path, symlink, target: symlink ? readlink(path) : null };
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
export function listAliases({ dir, target }) {
|
|
84
|
+
let entries;
|
|
85
|
+
try {
|
|
86
|
+
entries = readdirSync(dir);
|
|
87
|
+
} catch {
|
|
88
|
+
return [];
|
|
89
|
+
}
|
|
90
|
+
const aliases = [];
|
|
91
|
+
for (const name of entries.sort()) {
|
|
92
|
+
const alias = readAlias(dir, name);
|
|
93
|
+
if (!alias?.symlink) continue;
|
|
94
|
+
if (target && !sameTarget(alias.path, target)) continue;
|
|
95
|
+
aliases.push(alias);
|
|
96
|
+
}
|
|
97
|
+
return aliases;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
export function addAlias(name, { dir, target, force = false }) {
|
|
101
|
+
assertAliasName(name);
|
|
102
|
+
const path = join(dir, name);
|
|
103
|
+
mkdirSync(dir, { recursive: true });
|
|
104
|
+
const existing = readAlias(dir, name);
|
|
105
|
+
if (existing && !existing.symlink && !force) {
|
|
106
|
+
throw new AliasError(`${path} already exists and is not a symlink (use --force to replace)`, "exists");
|
|
107
|
+
}
|
|
108
|
+
if (existing?.symlink && sameTarget(path, target)) return { path, changed: false };
|
|
109
|
+
if (existing) unlinkSync(path); // a symlink (re-point) or, with --force, a real file
|
|
110
|
+
symlinkSync(target, path);
|
|
111
|
+
return { path, changed: true };
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
export function removeAlias(name, { dir, target }) {
|
|
115
|
+
assertAliasName(name);
|
|
116
|
+
const path = join(dir, name);
|
|
117
|
+
const existing = readAlias(dir, name);
|
|
118
|
+
if (!existing) return false;
|
|
119
|
+
if (!existing.symlink) {
|
|
120
|
+
throw new AliasError(`${path} is not a symlink; remove it yourself`, "not_symlink");
|
|
121
|
+
}
|
|
122
|
+
if (target && !sameTarget(path, target)) {
|
|
123
|
+
throw new AliasError(`${path} points at ${existing.target}, not at ${target}; remove it yourself`, "foreign");
|
|
124
|
+
}
|
|
125
|
+
unlinkSync(path);
|
|
126
|
+
return true;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
export function dirOnPath(dir, env = process.env) {
|
|
130
|
+
const wanted = (() => {
|
|
131
|
+
try {
|
|
132
|
+
return realpathSync(dir);
|
|
133
|
+
} catch {
|
|
134
|
+
return dir;
|
|
135
|
+
}
|
|
136
|
+
})();
|
|
137
|
+
return String(env.PATH ?? "")
|
|
138
|
+
.split(delimiter)
|
|
139
|
+
.filter(Boolean)
|
|
140
|
+
.some((entry) => {
|
|
141
|
+
try {
|
|
142
|
+
return realpathSync(entry) === wanted;
|
|
143
|
+
} catch {
|
|
144
|
+
return entry === dir;
|
|
145
|
+
}
|
|
146
|
+
});
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
function installedVersion(realPath) {
|
|
150
|
+
try {
|
|
151
|
+
const manifest = JSON.parse(readFileSync(join(dirname(dirname(realPath)), "package.json"), "utf8"));
|
|
152
|
+
return typeof manifest.version === "string" ? manifest.version : null;
|
|
153
|
+
} catch {
|
|
154
|
+
return null;
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Is `path` one of ours? `this` is the running script, `installed` is another
|
|
160
|
+
* copy of pi-farm (npm global, ~/.local/bin) — a dev checkout running the repo
|
|
161
|
+
* copy still owns the globally installed `pp`.
|
|
162
|
+
*/
|
|
163
|
+
export function installInfo(path, target) {
|
|
164
|
+
let real;
|
|
165
|
+
try {
|
|
166
|
+
real = realpathSync(path);
|
|
167
|
+
} catch {
|
|
168
|
+
return null;
|
|
169
|
+
}
|
|
170
|
+
const version = installedVersion(real);
|
|
171
|
+
if (sameTarget(path, target)) return { kind: "this", version };
|
|
172
|
+
if (/(^|\/)node_modules\/pi-farm\/bin\/pp(\.js)?$/.test(real)) return { kind: "installed", version };
|
|
173
|
+
return null;
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
/**
|
|
177
|
+
* Which of the shipped names point at *us*? A machine can have our `pifarm`
|
|
178
|
+
* on PATH and Apple's `pp` earlier in PATH at the same time.
|
|
179
|
+
*/
|
|
180
|
+
export function inspectCommandNames({ target, env = process.env, names = BUILTIN_NAMES }) {
|
|
181
|
+
const resolved = names.map((name) => {
|
|
182
|
+
const found = resolveExecutable(name, env);
|
|
183
|
+
const path = found && found.includes("/") ? found : null;
|
|
184
|
+
const info = path ? installInfo(path, target) : null;
|
|
185
|
+
return { name, path, ours: Boolean(info), kind: info?.kind ?? null, version: info?.version ?? null };
|
|
186
|
+
});
|
|
187
|
+
return { ok: resolved.some((entry) => entry.ours), names: resolved };
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
export function describeCommandNames(info) {
|
|
191
|
+
const ours = info.names.filter((entry) => entry.ours);
|
|
192
|
+
const foreign = info.names.filter((entry) => entry.path && !entry.ours);
|
|
193
|
+
const parts = [];
|
|
194
|
+
if (ours.length > 0) {
|
|
195
|
+
parts.push(
|
|
196
|
+
`ours: ${ours
|
|
197
|
+
.map((entry) => `${entry.name}${entry.version ? ` ${entry.version}` : ""}${entry.kind === "installed" ? " (installed)" : ""}`)
|
|
198
|
+
.join(", ")}`,
|
|
199
|
+
);
|
|
200
|
+
}
|
|
201
|
+
for (const entry of foreign) parts.push(`${entry.name} → ${entry.path} (not pi-plus)`);
|
|
202
|
+
if (parts.length === 0) return "not on PATH";
|
|
203
|
+
return parts.join("; ");
|
|
204
|
+
}
|
package/src/commands.js
CHANGED
|
@@ -13,6 +13,17 @@ import {
|
|
|
13
13
|
shellQuote,
|
|
14
14
|
} from "./config.js";
|
|
15
15
|
import { readRemotePiConfig, remotePiConfigPath, writeRemotePiName } from "./remote-pi.js";
|
|
16
|
+
import {
|
|
17
|
+
addAlias,
|
|
18
|
+
aliasDir,
|
|
19
|
+
BUILTIN_NAMES,
|
|
20
|
+
AliasError,
|
|
21
|
+
describeCommandNames,
|
|
22
|
+
dirOnPath,
|
|
23
|
+
inspectCommandNames,
|
|
24
|
+
listAliases,
|
|
25
|
+
removeAlias,
|
|
26
|
+
} from "./aliases.js";
|
|
16
27
|
import { resolveExecutable, Tmux } from "./tmux.js";
|
|
17
28
|
import {
|
|
18
29
|
installAutostart,
|
|
@@ -25,7 +36,16 @@ import {
|
|
|
25
36
|
systemdUserDir,
|
|
26
37
|
} from "./autostart.js";
|
|
27
38
|
import { clearStopped, isStopped, markStopped } from "./state.js";
|
|
28
|
-
import {
|
|
39
|
+
import {
|
|
40
|
+
BROADCAST_TARGET,
|
|
41
|
+
connectPeer,
|
|
42
|
+
describeEnvelope,
|
|
43
|
+
livePeersFor,
|
|
44
|
+
MeshError,
|
|
45
|
+
peerPc,
|
|
46
|
+
probePeers,
|
|
47
|
+
sessionMeshAddress,
|
|
48
|
+
} from "./mesh.js";
|
|
29
49
|
import { findCommand, suggestCommand } from "./help.js";
|
|
30
50
|
import { EXAMPLE_CONFIG } from "./example.js";
|
|
31
51
|
|
|
@@ -573,6 +593,10 @@ async function cmdMesh(config, options, ui) {
|
|
|
573
593
|
case "resolve":
|
|
574
594
|
case "addr":
|
|
575
595
|
return cmdMeshResolve(config, { ...options, names: rest }, ui);
|
|
596
|
+
case "inbox":
|
|
597
|
+
case "listen":
|
|
598
|
+
case "watch":
|
|
599
|
+
return cmdMeshInbox(config, { ...options, names: rest }, ui);
|
|
576
600
|
default:
|
|
577
601
|
ui.error(`unknown mesh subcommand: ${sub}`);
|
|
578
602
|
return meshUsage(ui);
|
|
@@ -660,6 +684,70 @@ async function cmdMeshResolve(config, options, ui) {
|
|
|
660
684
|
}
|
|
661
685
|
}
|
|
662
686
|
|
|
687
|
+
async function cmdMeshInbox(config, options, ui) {
|
|
688
|
+
const name = options.as ?? "pp-inbox";
|
|
689
|
+
let peer;
|
|
690
|
+
try {
|
|
691
|
+
peer = await connectPeer({ name, cwd: options.cwd ?? process.cwd(), timeoutMs: options.wait ?? 5000 });
|
|
692
|
+
} catch (err) {
|
|
693
|
+
ui.error(err.message);
|
|
694
|
+
process.exit(1);
|
|
695
|
+
}
|
|
696
|
+
let received = 0;
|
|
697
|
+
let closing = false;
|
|
698
|
+
const leave = (reason) => {
|
|
699
|
+
if (closing) return;
|
|
700
|
+
closing = true;
|
|
701
|
+
try {
|
|
702
|
+
peer.close();
|
|
703
|
+
} catch {
|
|
704
|
+
/* socket already gone */
|
|
705
|
+
}
|
|
706
|
+
if (reason === "signal") {
|
|
707
|
+
if (!ui.json) ui.info(`left the mesh as ${peer.address} (${received} message(s))`);
|
|
708
|
+
process.exit(0);
|
|
709
|
+
}
|
|
710
|
+
};
|
|
711
|
+
const onBrokerFrame = (envelope) => {
|
|
712
|
+
if (!ui.verbose) return;
|
|
713
|
+
const event = envelope?.body ?? {};
|
|
714
|
+
ui.out(ui.paint("dim", `${event.type ?? "event"}: ${event.address ?? event.name ?? "?"}`));
|
|
715
|
+
};
|
|
716
|
+
peer.onMessage((envelope) => {
|
|
717
|
+
// The broker pushes its own lifecycle events as envelopes from "broker"
|
|
718
|
+
// (peer_joined / peer_left); they are not messages for us.
|
|
719
|
+
const eventType = envelope?.body?.type;
|
|
720
|
+
if (envelope?.from === "broker" || eventType === "peer_joined" || eventType === "peer_left") {
|
|
721
|
+
onBrokerFrame(envelope);
|
|
722
|
+
return;
|
|
723
|
+
}
|
|
724
|
+
if (!envelope || eventType === "ack") return; // ACKs belong to senders
|
|
725
|
+
received += 1;
|
|
726
|
+
const message = describeEnvelope(envelope);
|
|
727
|
+
if (ui.json) {
|
|
728
|
+
ui.out(JSON.stringify(message));
|
|
729
|
+
return;
|
|
730
|
+
}
|
|
731
|
+
const header = message.re ? `from ${message.from} re=${message.re}` : `from ${message.from}`;
|
|
732
|
+
ui.out(`${ui.paint("green", header)}`);
|
|
733
|
+
for (const line of message.body.split("\n")) ui.out(` ${line}`);
|
|
734
|
+
});
|
|
735
|
+
for (const signal of ["SIGINT", "SIGTERM"]) process.on(signal, () => leave("signal"));
|
|
736
|
+
peer.socket.on("close", () => {
|
|
737
|
+
if (closing) return;
|
|
738
|
+
ui.error(`mesh connection closed by the broker (was ${peer.address})`);
|
|
739
|
+
process.exitCode = 1;
|
|
740
|
+
process.exit(1);
|
|
741
|
+
});
|
|
742
|
+
if (!ui.json) {
|
|
743
|
+
const where = config?.path ? ` config: ${config.path}` : "";
|
|
744
|
+
ui.out(`${ui.paint("green", `listening as ${peer.address}`)}${where}`);
|
|
745
|
+
ui.out(ui.paint("dim", "Ctrl-C to leave; messages are printed as they arrive"));
|
|
746
|
+
}
|
|
747
|
+
// keep the process alive while the socket is open
|
|
748
|
+
await new Promise(() => {});
|
|
749
|
+
}
|
|
750
|
+
|
|
663
751
|
async function cmdMeshSend(config, options, ui) {
|
|
664
752
|
const hasBodyJson = options.bodyJson !== undefined;
|
|
665
753
|
if (options.names.length < (hasBodyJson ? 1 : 2)) {
|
|
@@ -923,6 +1011,8 @@ function cmdDoctor(config, options, ui) {
|
|
|
923
1011
|
// A missing server is normal (tmux starts on demand) — not a failure.
|
|
924
1012
|
add("tmux server", true, hasServer ? "running" : "not running (starts on demand)");
|
|
925
1013
|
add("pi", commandExists("pi"), resolveExecutable("pi"));
|
|
1014
|
+
const names = inspectCommandNames({ target: scriptPath(options) });
|
|
1015
|
+
add("command name", names.ok, describeCommandNames(names));
|
|
926
1016
|
add("config", Boolean(config), config?.path ?? "not found");
|
|
927
1017
|
const autostart = autostartState();
|
|
928
1018
|
add("autostart", Boolean(autostart.kind) && autostart.installed && autostart.enabled, describeAutostart(autostart));
|
|
@@ -940,6 +1030,12 @@ function cmdDoctor(config, options, ui) {
|
|
|
940
1030
|
ui.out(`${mark} ${check.label.padEnd(14)} ${ui.paint("dim", check.detail ?? "")}`);
|
|
941
1031
|
}
|
|
942
1032
|
if (!config) ui.out(`\n${ui.paint("dim", "hint:")} no config found; run pp init`);
|
|
1033
|
+
if (!names.ok) {
|
|
1034
|
+
ui.out(
|
|
1035
|
+
`${ui.paint("dim", "hint:")} another program owns the name on PATH; pick one with ` +
|
|
1036
|
+
`pp alias add pif (or use pifarm / pi-plus) — see pp help alias`,
|
|
1037
|
+
);
|
|
1038
|
+
}
|
|
943
1039
|
if (autostart.kind === "systemd") {
|
|
944
1040
|
ui.out(`\n${ui.paint("dim", "systemd unit dir:")} ${systemdUserDir()}`);
|
|
945
1041
|
ui.out(`${ui.paint("dim", "hint:")} systemctl --user status pi-plus`);
|
|
@@ -970,15 +1066,19 @@ function cmdInit(options, ui) {
|
|
|
970
1066
|
ui.info(`start with: pp up --config ${target}`);
|
|
971
1067
|
}
|
|
972
1068
|
|
|
1069
|
+
function scriptPath(options = {}) {
|
|
1070
|
+
return options.scriptPath ?? resolve(process.argv[1]);
|
|
1071
|
+
}
|
|
1072
|
+
|
|
973
1073
|
function cmdInstall(config, options, ui) {
|
|
974
|
-
const
|
|
1074
|
+
const scriptPath_ = scriptPath(options);
|
|
975
1075
|
const watch = options.watch === true ? 300 : Number(options.watch) || 0;
|
|
976
1076
|
if (options.watch !== undefined && watch < 30) {
|
|
977
1077
|
ui.error("--watch interval must be at least 30 seconds");
|
|
978
1078
|
process.exit(2);
|
|
979
1079
|
}
|
|
980
1080
|
const result = installAutostart({
|
|
981
|
-
scriptPath,
|
|
1081
|
+
scriptPath: scriptPath_,
|
|
982
1082
|
configPath: config.path,
|
|
983
1083
|
watch,
|
|
984
1084
|
print: options.print,
|
|
@@ -1025,6 +1125,92 @@ function cmdUninstall(options, ui) {
|
|
|
1025
1125
|
ui.info(`removed ${result.removed.join(", ")}`);
|
|
1026
1126
|
}
|
|
1027
1127
|
|
|
1128
|
+
function cmdAlias(config, options, ui) {
|
|
1129
|
+
const sub = options.names[0] ?? "ls";
|
|
1130
|
+
const rest = options.names.slice(1);
|
|
1131
|
+
const target = scriptPath(options);
|
|
1132
|
+
const dir = aliasDir(process.env, options.binDir);
|
|
1133
|
+
const onPath = dirOnPath(dir);
|
|
1134
|
+
|
|
1135
|
+
const show = (payload) => {
|
|
1136
|
+
if (ui.json) {
|
|
1137
|
+
ui.out(JSON.stringify(payload, null, 2));
|
|
1138
|
+
return true;
|
|
1139
|
+
}
|
|
1140
|
+
return false;
|
|
1141
|
+
};
|
|
1142
|
+
|
|
1143
|
+
try {
|
|
1144
|
+
switch (sub) {
|
|
1145
|
+
case "ls":
|
|
1146
|
+
case "list": {
|
|
1147
|
+
const aliases = listAliases({ dir, target });
|
|
1148
|
+
if (show({ dir, onPath, aliases })) return;
|
|
1149
|
+
if (aliases.length === 0) {
|
|
1150
|
+
ui.out(`no aliases in ${dir}`);
|
|
1151
|
+
} else {
|
|
1152
|
+
for (const alias of aliases) {
|
|
1153
|
+
ui.out(`${ui.paint("bold", alias.name.padEnd(12))} ${ui.paint("dim", alias.path)}`);
|
|
1154
|
+
}
|
|
1155
|
+
}
|
|
1156
|
+
ui.out(
|
|
1157
|
+
ui.paint(
|
|
1158
|
+
"dim",
|
|
1159
|
+
`${onPath ? "" : `note: ${dir} is not on PATH; `}built in: ${BUILTIN_NAMES.join(", ")}`,
|
|
1160
|
+
),
|
|
1161
|
+
);
|
|
1162
|
+
ui.out(ui.paint("dim", "add one with: pp alias add pif"));
|
|
1163
|
+
return;
|
|
1164
|
+
}
|
|
1165
|
+
case "add":
|
|
1166
|
+
case "create":
|
|
1167
|
+
case "link": {
|
|
1168
|
+
const name = rest[0];
|
|
1169
|
+
assertAliasNameSafe(name);
|
|
1170
|
+
const result = addAlias(name, { dir, target, force: options.force });
|
|
1171
|
+
if (show({ ...result, dir, onPath })) return;
|
|
1172
|
+
ui.info(`${result.changed ? "linked" : "already linked"} ${result.path} → ${target}`);
|
|
1173
|
+
if (!onPath) {
|
|
1174
|
+
ui.info(ui.paint("yellow", `note: ${dir} is not on PATH; add it, e.g. export PATH="${dir}:$PATH"`));
|
|
1175
|
+
}
|
|
1176
|
+
ui.info(ui.paint("dim", `try: ${name} ls`));
|
|
1177
|
+
return;
|
|
1178
|
+
}
|
|
1179
|
+
case "rm":
|
|
1180
|
+
case "remove":
|
|
1181
|
+
case "delete":
|
|
1182
|
+
case "unlink": {
|
|
1183
|
+
const name = rest[0];
|
|
1184
|
+
assertAliasNameSafe(name);
|
|
1185
|
+
const removed = removeAlias(name, { dir, target });
|
|
1186
|
+
if (show({ name, removed, dir })) return;
|
|
1187
|
+
if (!removed) {
|
|
1188
|
+
ui.info(`nothing to remove at ${join(dir, name)}`);
|
|
1189
|
+
return;
|
|
1190
|
+
}
|
|
1191
|
+
ui.info(`removed ${join(dir, name)}`);
|
|
1192
|
+
return;
|
|
1193
|
+
}
|
|
1194
|
+
default:
|
|
1195
|
+
ui.error(`unknown alias subcommand: ${sub}`);
|
|
1196
|
+
ui.error("usage: pp alias [ls | add <name> | rm <name>] [--bin-dir <dir>]");
|
|
1197
|
+
process.exit(2);
|
|
1198
|
+
}
|
|
1199
|
+
} catch (err) {
|
|
1200
|
+
if (err instanceof AliasError) {
|
|
1201
|
+
ui.error(err.message);
|
|
1202
|
+
process.exit(err.code === "usage" ? 2 : 1);
|
|
1203
|
+
}
|
|
1204
|
+
throw err;
|
|
1205
|
+
}
|
|
1206
|
+
}
|
|
1207
|
+
|
|
1208
|
+
function assertAliasNameSafe(name) {
|
|
1209
|
+
if (!name) {
|
|
1210
|
+
throw new AliasError("alias name is required, e.g. pp alias add pif", "usage");
|
|
1211
|
+
}
|
|
1212
|
+
}
|
|
1213
|
+
|
|
1028
1214
|
export async function runCommand(command, options) {
|
|
1029
1215
|
const ui = makeUi(options);
|
|
1030
1216
|
if (options.json) ui.quiet = true;
|
|
@@ -1109,6 +1295,10 @@ export async function runCommand(command, options) {
|
|
|
1109
1295
|
const config = requireConfig(options, ui);
|
|
1110
1296
|
return cmdInstall(config, options, ui);
|
|
1111
1297
|
}
|
|
1298
|
+
case "alias":
|
|
1299
|
+
case "link": {
|
|
1300
|
+
return cmdAlias(null, options, ui); // aliasing does not need a config
|
|
1301
|
+
}
|
|
1112
1302
|
case "uninstall": {
|
|
1113
1303
|
return cmdUninstall(options, ui);
|
|
1114
1304
|
}
|
package/src/help.js
CHANGED
|
@@ -157,8 +157,8 @@ export const COMMANDS = [
|
|
|
157
157
|
{
|
|
158
158
|
name: "mesh",
|
|
159
159
|
aliases: [],
|
|
160
|
-
summary: "Talk to the remote-pi agent mesh (ls / send / resolve)",
|
|
161
|
-
usage: "pp mesh <ls|send|resolve> ...",
|
|
160
|
+
summary: "Talk to the remote-pi agent mesh (ls / send / resolve / inbox)",
|
|
161
|
+
usage: "pp mesh <ls|send|resolve|inbox> ...",
|
|
162
162
|
details: [
|
|
163
163
|
"pp talks to remote-pi's local broker directly over its UNIX socket",
|
|
164
164
|
"(~/.pi/remote/sessions/local/broker.sock) — no dependencies, no pi needed.",
|
|
@@ -168,6 +168,8 @@ export const COMMANDS = [
|
|
|
168
168
|
" resolve map a configured session to its mesh address and online state",
|
|
169
169
|
" send register as an ephemeral peer (default name pp-mesh), deliver the",
|
|
170
170
|
" text, and wait for the broker ACK",
|
|
171
|
+
" inbox register and stay online, printing every message that arrives",
|
|
172
|
+
" (default name pp-inbox; Ctrl-C to leave)",
|
|
171
173
|
"",
|
|
172
174
|
"Targets may be a session name or #index (resolved through the config), a raw",
|
|
173
175
|
"mesh address (<cwd>@<name>, or macbook:/path@name for cross-PC), `all`, or",
|
|
@@ -178,8 +180,8 @@ export const COMMANDS = [
|
|
|
178
180
|
"Cross-PC delivery rides the broker leader's relay bridge, so no pairing.",
|
|
179
181
|
].join("\n"),
|
|
180
182
|
options: [
|
|
181
|
-
"--json JSON output (ls/resolve)",
|
|
182
|
-
"--as <name> mesh name to register as (default: pp-mesh)",
|
|
183
|
+
"--json JSON output (ls/resolve; one JSON object per line for inbox)",
|
|
184
|
+
"--as <name> mesh name to register as (default: pp-mesh / pp-inbox)",
|
|
183
185
|
"--wait <ms> ACK timeout, default 5000",
|
|
184
186
|
"--no-wait fire-and-forget: do not wait for the ACK",
|
|
185
187
|
"--reply <ms> keep listening after the ACK and print the reply envelope(s)",
|
|
@@ -193,6 +195,8 @@ export const COMMANDS = [
|
|
|
193
195
|
'pp mesh send 1 3 "heads up: rebooting the box"',
|
|
194
196
|
'pp mesh send all "standup in 5"',
|
|
195
197
|
"pp mesh send macbook:/Users/me/code/api@api \"ping\" --wait 2000",
|
|
198
|
+
"pp mesh inbox --as pp-worker",
|
|
199
|
+
"pp mesh inbox --json --as pp-worker | tee mesh.jsonl",
|
|
196
200
|
],
|
|
197
201
|
see: ["send", "status"],
|
|
198
202
|
},
|
|
@@ -264,6 +268,31 @@ export const COMMANDS = [
|
|
|
264
268
|
examples: ["pp uninstall"],
|
|
265
269
|
see: ["install"],
|
|
266
270
|
},
|
|
271
|
+
{
|
|
272
|
+
name: "alias",
|
|
273
|
+
aliases: ["link"],
|
|
274
|
+
summary: "Add another command name when `pp` is taken by another program",
|
|
275
|
+
usage: "pp alias [ls | add <name> | rm <name>] [--bin-dir <dir>]",
|
|
276
|
+
details: [
|
|
277
|
+
"macOS ships /usr/bin/pp (an ASN.1 pretty printer) and a few Linux distros do too, so typing `pp ls` can reach a binary that knows nothing about sessions. npm already installs two extra names for this reason: `pifarm` and `pi-plus`.",
|
|
278
|
+
"`pp alias add <name>` puts a symlink to this CLI into a bin directory that is on PATH, so any short name you like works: pp alias add pif → pif ls.",
|
|
279
|
+
"Default directory: ~/.local/bin, or $PP_BIN_DIR; `--bin-dir` overrides it for one call. The symlink points at this script, so upgrading through npm keeps the alias valid.",
|
|
280
|
+
"`pp alias rm <name>` removes only symlinks that point at this CLI; anything else is left alone (delete it yourself).",
|
|
281
|
+
"pp doctor reports which names resolve to us and which belong to another program.",
|
|
282
|
+
].join("\n"),
|
|
283
|
+
options: [
|
|
284
|
+
"--bin-dir <dir> directory to link into (default ~/.local/bin)",
|
|
285
|
+
"--force replace an existing non-symlink file",
|
|
286
|
+
"--json machine-readable output",
|
|
287
|
+
],
|
|
288
|
+
examples: [
|
|
289
|
+
"pp alias ls",
|
|
290
|
+
"pp alias add pif",
|
|
291
|
+
"pp alias add p --bin-dir /usr/local/bin",
|
|
292
|
+
"pp alias rm pif",
|
|
293
|
+
],
|
|
294
|
+
see: ["doctor", "install"],
|
|
295
|
+
},
|
|
267
296
|
{
|
|
268
297
|
name: "version",
|
|
269
298
|
summary: "Print the version",
|
package/src/mesh.js
CHANGED
|
@@ -50,6 +50,21 @@ export function sessionMeshAddress(session) {
|
|
|
50
50
|
* two agents in the same directory ask for the same name, so an exact match is
|
|
51
51
|
* not enough.
|
|
52
52
|
*/
|
|
53
|
+
/**
|
|
54
|
+
* Normalise an inbound envelope for display: remote-pi renders string bodies
|
|
55
|
+
* verbatim and JSON-stringifies everything else, so we do the same.
|
|
56
|
+
*/
|
|
57
|
+
export function describeEnvelope(envelope) {
|
|
58
|
+
const body =
|
|
59
|
+
typeof envelope?.body === "string" ? envelope.body : JSON.stringify(envelope?.body ?? null);
|
|
60
|
+
return {
|
|
61
|
+
from: typeof envelope?.from === "string" ? envelope.from : "unknown",
|
|
62
|
+
re: typeof envelope?.re === "string" ? envelope.re : null,
|
|
63
|
+
id: typeof envelope?.id === "string" ? envelope.id : null,
|
|
64
|
+
body,
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
|
|
53
68
|
export function livePeersFor(peers, address) {
|
|
54
69
|
if (!address) return [];
|
|
55
70
|
return peers.filter((peer) => peer === address || peer.startsWith(`${address}#`));
|