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 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' \
@@ -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
@@ -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": "..." }`。
@@ -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.2.3",
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 { BROADCAST_TARGET, connectPeer, livePeersFor, MeshError, peerPc, probePeers, sessionMeshAddress } from "./mesh.js";
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 scriptPath = options.scriptPath ?? resolve(process.argv[1]);
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}#`));