pi-farm 0.2.2 → 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/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,6 +36,16 @@ import {
25
36
  systemdUserDir,
26
37
  } from "./autostart.js";
27
38
  import { clearStopped, isStopped, markStopped } from "./state.js";
39
+ import {
40
+ BROADCAST_TARGET,
41
+ connectPeer,
42
+ describeEnvelope,
43
+ livePeersFor,
44
+ MeshError,
45
+ peerPc,
46
+ probePeers,
47
+ sessionMeshAddress,
48
+ } from "./mesh.js";
28
49
  import { findCommand, suggestCommand } from "./help.js";
29
50
  import { EXAMPLE_CONFIG } from "./example.js";
30
51
 
@@ -544,6 +565,361 @@ function cmdSend(config, options, ui) {
544
565
  ui.info(`sent to ${session.name}`);
545
566
  }
546
567
 
568
+ function sessionForAddress(config, address) {
569
+ if (!config) return null;
570
+ for (const session of config.sessions) {
571
+ const base = sessionMeshAddress(session);
572
+ if (base && (address === base || address.startsWith(`${base}#`))) return session;
573
+ }
574
+ return null;
575
+ }
576
+
577
+ function meshUsage(ui) {
578
+ ui.error('usage: pp mesh <ls|send|resolve> ... (see "pp help mesh")');
579
+ process.exit(2);
580
+ }
581
+
582
+ async function cmdMesh(config, options, ui) {
583
+ const [sub, ...rest] = options.names;
584
+ switch (sub) {
585
+ case undefined:
586
+ case "ls":
587
+ case "list":
588
+ case "peers":
589
+ return cmdMeshLs(config, options, ui);
590
+ case "send":
591
+ case "msg":
592
+ return cmdMeshSend(config, { ...options, names: rest }, ui);
593
+ case "resolve":
594
+ case "addr":
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);
600
+ default:
601
+ ui.error(`unknown mesh subcommand: ${sub}`);
602
+ return meshUsage(ui);
603
+ }
604
+ }
605
+
606
+ async function cmdMeshLs(config, options, ui) {
607
+ let peers;
608
+ try {
609
+ peers = await probePeers({ timeoutMs: options.wait ?? 3000 });
610
+ } catch (err) {
611
+ ui.error(err.message);
612
+ process.exit(1);
613
+ }
614
+ const rows = peers.map((address, index) => {
615
+ const session = sessionForAddress(config, address);
616
+ return {
617
+ index: index + 1,
618
+ address,
619
+ pc: peerPc(address),
620
+ session: session ? session.name : null,
621
+ };
622
+ });
623
+ if (ui.json) {
624
+ ui.out(JSON.stringify(rows, null, 2));
625
+ return;
626
+ }
627
+ if (rows.length === 0) {
628
+ ui.info("no peers in the mesh");
629
+ return;
630
+ }
631
+ const headers = ["#", "ADDRESS", "PC", "SESSION"];
632
+ const table = rows.map((r) => [String(r.index), r.address, r.pc ?? "-", r.session ?? "-"]);
633
+ const widths = headers.map((h, i) => Math.max(h.length, ...table.map((row) => row[i].length)));
634
+ const pad = (value, width) => value + " ".repeat(Math.max(0, width - value.length));
635
+ ui.out(ui.paint("bold", headers.map((h, i) => pad(h, widths[i])).join(" ").trimEnd()));
636
+ table.forEach((row, i) => {
637
+ const cells = [...row];
638
+ cells[0] = ui.paint("dim", cells[0]);
639
+ if (rows[i].session) cells[3] = ui.paint("green", cells[3]);
640
+ ui.out(cells.map((cell, idx) => pad(cell, widths[idx])).join(" ").trimEnd());
641
+ });
642
+ if (!options.quiet) {
643
+ const local = rows.filter((r) => !r.pc).length;
644
+ ui.out(`\n${rows.length} peer(s): ${local} local, ${rows.length - local} cross-PC`);
645
+ }
646
+ }
647
+
648
+ async function cmdMeshResolve(config, options, ui) {
649
+ if (!config) {
650
+ ui.error("no config found; cannot resolve session names (use a raw mesh address instead)");
651
+ process.exit(2);
652
+ }
653
+ const sessions = selectSessions(config, options.names, ui, { all: true });
654
+ let peers = [];
655
+ try {
656
+ peers = await probePeers({ timeoutMs: options.wait ?? 3000 });
657
+ } catch {
658
+ peers = []; // resolving is useful offline; just report the offline state
659
+ }
660
+ const rows = sessions.map((session) => {
661
+ const base = sessionMeshAddress(session);
662
+ const live = livePeersFor(peers, base);
663
+ return {
664
+ name: session.name,
665
+ address: base,
666
+ online: live.length > 0,
667
+ matches: live,
668
+ };
669
+ });
670
+ if (ui.json) {
671
+ ui.out(JSON.stringify(rows, null, 2));
672
+ return;
673
+ }
674
+ for (const row of rows) {
675
+ if (!row.address) {
676
+ ui.out(`${row.name}: no remote-pi name (remote_pi_mode: off?)`);
677
+ continue;
678
+ }
679
+ const state = row.online ? ui.paint("green", `online x${row.matches.length}`) : ui.paint("dim", "offline");
680
+ ui.out(`${row.name} → ${row.address} ${state}`);
681
+ if (row.matches.length > 1) {
682
+ for (const match of row.matches) ui.out(` ${ui.paint("dim", match)}`);
683
+ }
684
+ }
685
+ }
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
+
751
+ async function cmdMeshSend(config, options, ui) {
752
+ const hasBodyJson = options.bodyJson !== undefined;
753
+ if (options.names.length < (hasBodyJson ? 1 : 2)) {
754
+ ui.error('usage: pp mesh send <target...> "text" [--wait <ms>] [--reply <ms>] [--no-wait] [--body-json <json>]');
755
+ process.exit(2);
756
+ }
757
+ const text = hasBodyJson ? null : options.names[options.names.length - 1];
758
+ const rawTargets = hasBodyJson ? options.names : options.names.slice(0, -1);
759
+ let body = text;
760
+ if (hasBodyJson) {
761
+ try {
762
+ body = JSON.parse(options.bodyJson);
763
+ } catch (err) {
764
+ ui.error(`--body-json is not valid JSON: ${err.message}`);
765
+ process.exit(2);
766
+ }
767
+ }
768
+
769
+ // Resolve names/config first: then "unknown session" and a missing config are
770
+ // reported before we bother the broker.
771
+ const wanted = [];
772
+ let broadcast = false;
773
+ for (const raw of rawTargets) {
774
+ if (raw === "all" || raw === "broadcast" || raw === "*") {
775
+ broadcast = true;
776
+ continue;
777
+ }
778
+ if (raw.includes("@") || /^[A-Za-z0-9._-]+:\//.test(raw)) {
779
+ wanted.push({ kind: "address", value: raw });
780
+ continue;
781
+ }
782
+ if (!config) {
783
+ ui.error(`no config found; cannot resolve session "${raw}" (pass a full mesh address instead)`);
784
+ process.exit(2);
785
+ }
786
+ const [session] = selectSessions(config, [raw], ui);
787
+ const base = sessionMeshAddress(session);
788
+ if (!base) {
789
+ ui.error(`"${session.name}" has no remote-pi name (remote_pi_mode: off?)`);
790
+ process.exit(2);
791
+ }
792
+ wanted.push({ kind: "session", value: base, session });
793
+ }
794
+
795
+ let peers = [];
796
+ if (!options.dryRun || wanted.length > 0 || broadcast) {
797
+ try {
798
+ peers = await probePeers({ timeoutMs: options.wait ?? 3000 });
799
+ } catch (err) {
800
+ if (!(err instanceof MeshError) || err.code !== "no_broker") throw err;
801
+ ui.error(err.message);
802
+ process.exit(1);
803
+ }
804
+ }
805
+
806
+ const targets = [];
807
+ for (const item of wanted) {
808
+ const live = livePeersFor(peers, item.value);
809
+ if (live.length === 0) {
810
+ if (item.kind === "address") ui.error(`no peer online at ${item.value}`);
811
+ else ui.error(`"${item.session.name}" is not in the mesh yet (${item.value} is offline; is the session running?)`);
812
+ process.exit(1);
813
+ }
814
+ targets.push(...live);
815
+ }
816
+
817
+ const unique = [...new Set(targets)];
818
+ const multicast = broadcast || unique.length > 1;
819
+ if (!broadcast && unique.length === 0) {
820
+ ui.error("no targets");
821
+ process.exit(2);
822
+ }
823
+ if (options.dryRun) {
824
+ const envelope = { from: options.as ?? "pp-mesh", to: broadcast ? BROADCAST_TARGET : multicast ? unique : unique[0], body };
825
+ ui.info(`[dry-run] ${JSON.stringify(envelope)}`);
826
+ return;
827
+ }
828
+
829
+ let peer;
830
+ try {
831
+ peer = await connectPeer({ name: options.as ?? "pp-mesh", cwd: process.cwd() });
832
+ } catch (err) {
833
+ ui.error(err.message);
834
+ process.exit(1);
835
+ }
836
+ let sendId = null;
837
+ let waitingForFirstReply = null;
838
+ const replies = [];
839
+ const collecting = options.reply !== undefined && options.reply > 0;
840
+ if (collecting) {
841
+ peer.onMessage((envelope) => {
842
+ if (!envelope || envelope.re !== sendId) return;
843
+ replies.push(envelope);
844
+ if (!ui.json) {
845
+ ui.out(`${ui.paint("green", `reply from ${envelope.from}`)}: ${formatMeshBody(envelope.body)}`);
846
+ }
847
+ waitingForFirstReply?.();
848
+ waitingForFirstReply = null;
849
+ });
850
+ }
851
+ const collect = async (single = true) => {
852
+ if (!collecting) return;
853
+ await new Promise((resolve) => {
854
+ const timer = setTimeout(resolve, options.reply);
855
+ if (!single) return;
856
+ waitingForFirstReply = () => {
857
+ clearTimeout(timer);
858
+ resolve();
859
+ };
860
+ });
861
+ waitingForFirstReply = null;
862
+ if (ui.json) {
863
+ ui.out(JSON.stringify(replies, null, 2));
864
+ return replies.length;
865
+ }
866
+ if (replies.length === 0) ui.info(`no reply within ${options.reply}ms (the peer may still be working)`);
867
+ return replies.length;
868
+ };
869
+ try {
870
+ if (broadcast) {
871
+ sendId = peer.send(BROADCAST_TARGET, body);
872
+ ui.info(`broadcast to ${peers.length} peer(s) as ${peer.address} (${sendId})`);
873
+ await collect(false);
874
+ return;
875
+ }
876
+ if (multicast) {
877
+ sendId = peer.send(unique, body);
878
+ ui.info(`sent to ${unique.length} peer(s) as ${peer.address} (${sendId})`);
879
+ for (const target of unique) ui.out(` ${ui.paint("dim", target)}`);
880
+ await collect(false);
881
+ return;
882
+ }
883
+ const target = unique[0];
884
+ if (options.noWait) {
885
+ sendId = peer.send(target, body);
886
+ ui.info(`sent to ${target} (${sendId})`);
887
+ await collect();
888
+ return;
889
+ }
890
+ const ack = await peer.sendWithAck(target, body, options.wait ?? 5000);
891
+ sendId = ack.id;
892
+ if (ack.status === "received") {
893
+ ui.info(`delivered to ${target} (${ack.id})`);
894
+ await collect();
895
+ return;
896
+ }
897
+ if (ack.status === "busy") {
898
+ ui.error(`${target} is mid-turn: broker dropped the message (busy). Retry later or use --no-wait.`);
899
+ process.exitCode = 1;
900
+ return;
901
+ }
902
+ if (ack.status === "denied") {
903
+ ui.error(`delivery to ${target} was denied by the broker`);
904
+ process.exitCode = 1;
905
+ return;
906
+ }
907
+ ui.error(`no ACK from ${target} within ${options.wait ?? 5000}ms (the message may still arrive)`);
908
+ process.exitCode = 1;
909
+ } finally {
910
+ peer.close();
911
+ }
912
+ }
913
+
914
+ function formatMeshBody(body) {
915
+ if (typeof body === "string") return body;
916
+ try {
917
+ return JSON.stringify(body);
918
+ } catch {
919
+ return String(body);
920
+ }
921
+ }
922
+
547
923
  function cmdCheck(config, options, ui) {
548
924
  const tmux = makeTmux(config, options);
549
925
  const problems = [];
@@ -635,6 +1011,8 @@ function cmdDoctor(config, options, ui) {
635
1011
  // A missing server is normal (tmux starts on demand) — not a failure.
636
1012
  add("tmux server", true, hasServer ? "running" : "not running (starts on demand)");
637
1013
  add("pi", commandExists("pi"), resolveExecutable("pi"));
1014
+ const names = inspectCommandNames({ target: scriptPath(options) });
1015
+ add("command name", names.ok, describeCommandNames(names));
638
1016
  add("config", Boolean(config), config?.path ?? "not found");
639
1017
  const autostart = autostartState();
640
1018
  add("autostart", Boolean(autostart.kind) && autostart.installed && autostart.enabled, describeAutostart(autostart));
@@ -652,6 +1030,12 @@ function cmdDoctor(config, options, ui) {
652
1030
  ui.out(`${mark} ${check.label.padEnd(14)} ${ui.paint("dim", check.detail ?? "")}`);
653
1031
  }
654
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
+ }
655
1039
  if (autostart.kind === "systemd") {
656
1040
  ui.out(`\n${ui.paint("dim", "systemd unit dir:")} ${systemdUserDir()}`);
657
1041
  ui.out(`${ui.paint("dim", "hint:")} systemctl --user status pi-plus`);
@@ -682,15 +1066,19 @@ function cmdInit(options, ui) {
682
1066
  ui.info(`start with: pp up --config ${target}`);
683
1067
  }
684
1068
 
1069
+ function scriptPath(options = {}) {
1070
+ return options.scriptPath ?? resolve(process.argv[1]);
1071
+ }
1072
+
685
1073
  function cmdInstall(config, options, ui) {
686
- const scriptPath = options.scriptPath ?? resolve(process.argv[1]);
1074
+ const scriptPath_ = scriptPath(options);
687
1075
  const watch = options.watch === true ? 300 : Number(options.watch) || 0;
688
1076
  if (options.watch !== undefined && watch < 30) {
689
1077
  ui.error("--watch interval must be at least 30 seconds");
690
1078
  process.exit(2);
691
1079
  }
692
1080
  const result = installAutostart({
693
- scriptPath,
1081
+ scriptPath: scriptPath_,
694
1082
  configPath: config.path,
695
1083
  watch,
696
1084
  print: options.print,
@@ -737,6 +1125,92 @@ function cmdUninstall(options, ui) {
737
1125
  ui.info(`removed ${result.removed.join(", ")}`);
738
1126
  }
739
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
+
740
1214
  export async function runCommand(command, options) {
741
1215
  const ui = makeUi(options);
742
1216
  if (options.json) ui.quiet = true;
@@ -789,6 +1263,15 @@ export async function runCommand(command, options) {
789
1263
  const config = requireConfig(options, ui);
790
1264
  return cmdSend(config, options, ui);
791
1265
  }
1266
+ case "mesh": {
1267
+ let config = null;
1268
+ try {
1269
+ config = loadConfig({ configPath: options.config, cwd: options.cwd });
1270
+ } catch {
1271
+ config = null; // raw addresses and `pp mesh ls` work without a config
1272
+ }
1273
+ return cmdMesh(config, options, ui);
1274
+ }
792
1275
  case "check":
793
1276
  case "validate": {
794
1277
  const config = requireConfig(options, ui);
@@ -812,6 +1295,10 @@ export async function runCommand(command, options) {
812
1295
  const config = requireConfig(options, ui);
813
1296
  return cmdInstall(config, options, ui);
814
1297
  }
1298
+ case "alias":
1299
+ case "link": {
1300
+ return cmdAlias(null, options, ui); // aliasing does not need a config
1301
+ }
815
1302
  case "uninstall": {
816
1303
  return cmdUninstall(options, ui);
817
1304
  }
package/src/help.js CHANGED
@@ -154,6 +154,52 @@ export const COMMANDS = [
154
154
  examples: ['pp send backend "run the tests"', 'pp send 3 "yes" --no-enter'],
155
155
  see: ["logs", "attach"],
156
156
  },
157
+ {
158
+ name: "mesh",
159
+ aliases: [],
160
+ summary: "Talk to the remote-pi agent mesh (ls / send / resolve / inbox)",
161
+ usage: "pp mesh <ls|send|resolve|inbox> ...",
162
+ details: [
163
+ "pp talks to remote-pi's local broker directly over its UNIX socket",
164
+ "(~/.pi/remote/sessions/local/broker.sock) — no dependencies, no pi needed.",
165
+ "",
166
+ " ls list every peer in the mesh (read-only probe: it never registers,",
167
+ " so nobody sees a peer_joined/peer_left because of it)",
168
+ " resolve map a configured session to its mesh address and online state",
169
+ " send register as an ephemeral peer (default name pp-mesh), deliver the",
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)",
173
+ "",
174
+ "Targets may be a session name or #index (resolved through the config), a raw",
175
+ "mesh address (<cwd>@<name>, or macbook:/path@name for cross-PC), `all`, or",
176
+ "`broadcast`. One target = unicast with ACK (received/busy/denied/timeout);",
177
+ "several targets or `all` = multicast, fire-and-forget.",
178
+ "",
179
+ "A busy peer drops the message (broker ACK `busy`) — retry later or --no-wait.",
180
+ "Cross-PC delivery rides the broker leader's relay bridge, so no pairing.",
181
+ ].join("\n"),
182
+ options: [
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)",
185
+ "--wait <ms> ACK timeout, default 5000",
186
+ "--no-wait fire-and-forget: do not wait for the ACK",
187
+ "--reply <ms> keep listening after the ACK and print the reply envelope(s)",
188
+ "--body-json <json> send structured JSON instead of plain text",
189
+ "--dry-run print the envelope instead of sending it",
190
+ ],
191
+ examples: [
192
+ "pp mesh ls",
193
+ "pp mesh resolve backend",
194
+ 'pp mesh send backend "the build is green"',
195
+ 'pp mesh send 1 3 "heads up: rebooting the box"',
196
+ 'pp mesh send all "standup in 5"',
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",
200
+ ],
201
+ see: ["send", "status"],
202
+ },
157
203
  {
158
204
  name: "check",
159
205
  aliases: ["validate"],
@@ -222,6 +268,31 @@ export const COMMANDS = [
222
268
  examples: ["pp uninstall"],
223
269
  see: ["install"],
224
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
+ },
225
296
  {
226
297
  name: "version",
227
298
  summary: "Print the version",