@shoppingjaws/peer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ShoppingJaws
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# @shoppingjaws/peer
+
+A CLI tool for managing WezTerm panes, peer groups, and inter-pane messaging.
+
+## Prerequisites
+
+- [Bun](https://bun.sh/) runtime
+- [WezTerm](https://wezfurlong.org/wezterm/) terminal
+
+## Install
+
+```bash
+npm install -g @shoppingjaws/peer
+```
+
+## Commands
+
+```
+peer <list|peek|inbox|new-pane|new-tab|history|clean>
+```
+
+### `peer list`
+
+List panes in the same tab and peer group.
+
+```bash
+peer list
+```
+
+```
+WINID  TABID  PANEID  RELATION  WORKSPACE  SIZE       TITLE
+0      0      0       self      default    120x40     ~
+0      0      1       child     default    120x20     ~
+```
+
+`RELATION` shows the relationship from your perspective:
+- `self` — current pane
+- `child` — pane you created
+- `parent` — pane that created you
+- `none` — same tab but no peer relation
+
+### `peer peek <pane-id>`
+
+Read terminal output from a pane. Only works for panes in the same tab or peer group.
+
+```bash
+peer peek 1
+peer peek 1 --start-line 0 --end-line 50
+```
+
+| Option | Description |
+|---|---|
+| `--start-line N` | Start reading from line N |
+| `--end-line N` | Stop reading at line N |
+
+### `peer new-pane [opts] [-- cmd]`
+
+Split a new pane in the current tab and register it as a child in the peer group. Options are passed through to `wezterm cli split-pane`.
+
+```bash
+peer new-pane
+peer new-pane --horizontal
+peer new-pane -- bash
+```
+
+### `peer new-tab [opts] [-- cmd]`
+
+Spawn a new tab and register it as a child in the peer group. Options are passed through to `wezterm cli spawn`.
+
+```bash
+peer new-tab
+peer new-tab -- zsh
+```
+
+### `peer inbox send <pane-id> <message>`
+
+Send a message to the specified pane.
+
+```bash
+peer inbox send 1 "build done"
+```
+
+### `peer inbox open`
+
+Show unread messages and mark them as read.
+
+```bash
+peer inbox open
+```
+
+```
+[#1 from:0 2025-04-05 12:00:00] build done
+1 message(s) marked as read.
+```
+
+### `peer history [pane-id]`
+
+Show message history. Optionally filter by a specific pane.
+
+```bash
+peer history
+peer history 1
+```
+
+### `peer clean`
+
+Delete all messages for the current session.
+
+```bash
+peer clean
+```
+
+## Data Storage
+
+Messages and peer group data are stored in `/tmp/peer/peer.db` (SQLite), isolated per session (`WEZTERM_UNIX_SOCKET`).
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,345 @@
+#!/usr/bin/env bun
+// @bun
+
+// db.ts
+import { Database } from "bun:sqlite";
+import { existsSync, mkdirSync } from "fs";
+var DB_DIR = "/tmp/peer";
+var DB_PATH = `${DB_DIR}/peer.db`;
+function initDb() {
+  if (!existsSync(DB_DIR)) {
+    mkdirSync(DB_DIR, { recursive: true });
+  }
+  const db = new Database(DB_PATH, { create: true });
+  db.run(`
+		CREATE TABLE IF NOT EXISTS messages (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			session_id TEXT NOT NULL,
+			from_pane TEXT NOT NULL,
+			to_pane TEXT NOT NULL,
+			message TEXT NOT NULL,
+			created_at TEXT NOT NULL DEFAULT (datetime('now')),
+			read_at TEXT DEFAULT NULL
+		)
+	`);
+  db.run(`
+		CREATE INDEX IF NOT EXISTS idx_messages_to_pane ON messages(session_id, to_pane, read_at)
+	`);
+  db.run(`
+		CREATE TABLE IF NOT EXISTS peer_edges (
+			session_id TEXT NOT NULL,
+			from_pane_id TEXT NOT NULL,
+			to_pane_id TEXT NOT NULL,
+			relation TEXT NOT NULL CHECK(relation IN ('parent', 'child')),
+			created_at TEXT NOT NULL DEFAULT (datetime('now')),
+			PRIMARY KEY (session_id, from_pane_id, to_pane_id)
+		)
+	`);
+  return db;
+}
+
+// pane.ts
+var {$ } = globalThis.Bun;
+function getMyPaneId() {
+  const paneId = process.env.WEZTERM_PANE;
+  if (!paneId) {
+    console.error("Error: WEZTERM_PANE environment variable is not set.");
+    process.exit(1);
+  }
+  return paneId;
+}
+function getSessionId() {
+  const socket = process.env.WEZTERM_UNIX_SOCKET;
+  if (!socket) {
+    console.error("Error: WEZTERM_UNIX_SOCKET environment variable is not set.");
+    process.exit(1);
+  }
+  return socket;
+}
+async function listPanes() {
+  const result = await $`wezterm cli list --format json`.quiet();
+  const panes = JSON.parse(result.stdout.toString());
+  return panes.map((p) => ({
+    window_id: p.window_id,
+    tab_id: p.tab_id,
+    pane_id: p.pane_id,
+    workspace: p.workspace,
+    size: `${p.size.cols}x${p.size.rows}`,
+    title: p.title
+  }));
+}
+async function getTabPaneIds() {
+  const myPaneId = getMyPaneId();
+  const panes = await listPanes();
+  const myPane = panes.find((p) => p.pane_id === Number(myPaneId));
+  if (!myPane)
+    return new Set;
+  return new Set(panes.filter((p) => p.tab_id === myPane.tab_id).map((p) => p.pane_id));
+}
+function getPeerGroupPaneIds(db) {
+  const sessionId = getSessionId();
+  const myPaneId = getMyPaneId();
+  const rows = db.prepare("SELECT DISTINCT to_pane_id FROM peer_edges WHERE session_id = ? AND from_pane_id = ?").all(sessionId, myPaneId);
+  return new Set(rows.map((r) => r.to_pane_id));
+}
+function registerPeerEdge(db, fromPaneId, toPaneId, relation) {
+  const sessionId = getSessionId();
+  const reverseRelation = relation === "child" ? "parent" : "child";
+  db.prepare("INSERT OR IGNORE INTO peer_edges (session_id, from_pane_id, to_pane_id, relation) VALUES (?, ?, ?, ?)").run(sessionId, fromPaneId, toPaneId, relation);
+  db.prepare("INSERT OR IGNORE INTO peer_edges (session_id, from_pane_id, to_pane_id, relation) VALUES (?, ?, ?, ?)").run(sessionId, toPaneId, fromPaneId, reverseRelation);
+}
+function getPeerRelation(db, paneId) {
+  const sessionId = getSessionId();
+  const myPaneId = getMyPaneId();
+  const row = db.prepare("SELECT relation FROM peer_edges WHERE session_id = ? AND from_pane_id = ? AND to_pane_id = ?").get(sessionId, myPaneId, paneId);
+  return row?.relation ?? null;
+}
+
+// commands/clean.ts
+function cmdClean() {
+  const sessionId = getSessionId();
+  const db = initDb();
+  const result = db.prepare("SELECT COUNT(*) as count FROM messages WHERE session_id = ?").get(sessionId);
+  db.prepare("DELETE FROM messages WHERE session_id = ?").run(sessionId);
+  console.log(`Deleted ${result.count} messages. Database cleaned.`);
+  db.close();
+}
+
+// commands/history.ts
+function cmdHistory(filterPaneId) {
+  const myPaneId = getMyPaneId();
+  const sessionId = getSessionId();
+  const db = initDb();
+  let messages;
+  if (filterPaneId) {
+    messages = db.prepare(`SELECT id, from_pane, to_pane, message, created_at, read_at FROM messages
+				 WHERE session_id = ? AND ((from_pane = ? AND to_pane = ?) OR (from_pane = ? AND to_pane = ?))
+				 ORDER BY created_at ASC`).all(sessionId, myPaneId, filterPaneId, filterPaneId, myPaneId);
+  } else {
+    messages = db.prepare(`SELECT id, from_pane, to_pane, message, created_at, read_at FROM messages
+				 WHERE session_id = ? AND (from_pane = ? OR to_pane = ?)
+				 ORDER BY created_at ASC`).all(sessionId, myPaneId, myPaneId);
+  }
+  if (messages.length === 0) {
+    console.log("No messages.");
+    db.close();
+    return;
+  }
+  for (const m of messages) {
+    const status = m.read_at ? "\u2713read" : "unread";
+    console.log(`[#${m.id} from:${m.from_pane} \u2192 to:${m.to_pane} ${m.created_at} ${status}]`);
+    console.log(m.message);
+  }
+  db.close();
+}
+
+// commands/list.ts
+async function cmdList() {
+  const myPaneId = getMyPaneId();
+  const panes = await listPanes();
+  const myPane = panes.find((p) => p.pane_id === Number(myPaneId));
+  if (!myPane) {
+    console.error(`Error: Current pane ${myPaneId} not found.`);
+    process.exit(1);
+  }
+  const db = initDb();
+  const peerPaneIds = getPeerGroupPaneIds(db);
+  const sameTabIds = new Set(panes.filter((p) => p.tab_id === myPane.tab_id).map((p) => p.pane_id));
+  const visiblePanes = panes.filter((p) => sameTabIds.has(p.pane_id) || peerPaneIds.has(String(p.pane_id)));
+  console.log("WINID\tTABID\tPANEID\tRELATION\tWORKSPACE\tSIZE\tTITLE");
+  for (const p of visiblePanes) {
+    const relation = p.pane_id === Number(myPaneId) ? "self" : getPeerRelation(db, String(p.pane_id)) ?? "none";
+    console.log(`${p.window_id}	${p.tab_id}	${p.pane_id}	${relation}	${p.workspace}	${p.size}	${p.title}`);
+  }
+  db.close();
+}
+
+// commands/new-pane.ts
+var {$: $2 } = globalThis.Bun;
+async function cmdNewPane(args) {
+  const myPaneId = getMyPaneId();
+  const splitArgs = [];
+  let commandArgs = [];
+  const separatorIndex = args.indexOf("--");
+  if (separatorIndex >= 0) {
+    splitArgs.push(...args.slice(0, separatorIndex));
+    commandArgs = args.slice(separatorIndex + 1);
+  } else {
+    splitArgs.push(...args);
+  }
+  if (commandArgs.length > 0) {
+    splitArgs.push("--", ...commandArgs);
+  }
+  const result = await $2`wezterm cli split-pane ${splitArgs}`.quiet();
+  const newPaneId = result.stdout.toString().trim();
+  if (!newPaneId) {
+    console.error("Error: Failed to create new pane.");
+    process.exit(1);
+  }
+  const db = initDb();
+  registerPeerEdge(db, myPaneId, newPaneId, "child");
+  db.close();
+  console.log(`Created pane ${newPaneId} and added to peer group.`);
+}
+
+// commands/new-tab.ts
+var {$: $3 } = globalThis.Bun;
+async function cmdNewTab(args) {
+  const myPaneId = getMyPaneId();
+  const spawnArgs = [];
+  let commandArgs = [];
+  const separatorIndex = args.indexOf("--");
+  if (separatorIndex >= 0) {
+    spawnArgs.push(...args.slice(0, separatorIndex));
+    commandArgs = args.slice(separatorIndex + 1);
+  } else {
+    spawnArgs.push(...args);
+  }
+  if (commandArgs.length > 0) {
+    spawnArgs.push("--", ...commandArgs);
+  }
+  const result = await $3`wezterm cli spawn ${spawnArgs}`.quiet();
+  const newPaneId = result.stdout.toString().trim();
+  if (!newPaneId) {
+    console.error("Error: Failed to create new tab.");
+    process.exit(1);
+  }
+  const db = initDb();
+  registerPeerEdge(db, myPaneId, newPaneId, "child");
+  db.close();
+  console.log(`Created tab with pane ${newPaneId} and added to peer group.`);
+}
+
+// commands/open.ts
+function cmdOpen() {
+  const myPaneId = getMyPaneId();
+  const sessionId = getSessionId();
+  const db = initDb();
+  const messages = db.prepare("SELECT id, from_pane, message, created_at FROM messages WHERE session_id = ? AND to_pane = ? AND read_at IS NULL ORDER BY created_at ASC").all(sessionId, myPaneId);
+  if (messages.length === 0) {
+    console.log("No unread messages.");
+    db.close();
+    return;
+  }
+  for (const m of messages) {
+    console.log(`[#${m.id} from:${m.from_pane} ${m.created_at}] ${m.message}`);
+  }
+  const ids = messages.map((m) => m.id);
+  const placeholders = ids.map(() => "?").join(",");
+  db.prepare(`UPDATE messages SET read_at = datetime('now') WHERE id IN (${placeholders})`).run(...ids);
+  console.log(`${messages.length} message(s) marked as read.`);
+  db.close();
+}
+
+// commands/peek.ts
+var {$: $4 } = globalThis.Bun;
+async function cmdPeek(paneId, args) {
+  const myPaneId = getMyPaneId();
+  const tabPanes = await getTabPaneIds();
+  const db = initDb();
+  const peerPaneIds = getPeerGroupPaneIds(db);
+  db.close();
+  if (!tabPanes.has(Number(paneId)) && !peerPaneIds.has(paneId)) {
+    console.error(`Error: Pane ${paneId} is not in the same tab or peer group as pane ${myPaneId}.`);
+    process.exit(1);
+  }
+  const opts = [];
+  for (let i = 0;i < args.length; i++) {
+    const arg = args[i];
+    const next = args[i + 1];
+    if (arg === "--start-line" && next) {
+      opts.push("--start-line", next);
+      i++;
+    } else if (arg === "--end-line" && next) {
+      opts.push("--end-line", next);
+      i++;
+    }
+  }
+  const result = await $4`wezterm cli get-text --pane-id ${paneId} ${opts}`.quiet();
+  console.log(result.stdout.toString());
+}
+
+// commands/send.ts
+async function cmdSend(paneId, message) {
+  const myPaneId = getMyPaneId();
+  const sessionId = getSessionId();
+  const tabPanes = await getTabPaneIds();
+  const db = initDb();
+  const peerPaneIds = getPeerGroupPaneIds(db);
+  if (!tabPanes.has(Number(paneId)) && !peerPaneIds.has(paneId)) {
+    console.error(`Error: Pane ${paneId} is not in the same tab or peer group as pane ${myPaneId}.`);
+    db.close();
+    process.exit(1);
+  }
+  const stmt = db.prepare("INSERT INTO messages (session_id, from_pane, to_pane, message) VALUES (?, ?, ?, ?)");
+  const result = stmt.run(sessionId, myPaneId, paneId, message);
+  console.log(`Sent message to pane ${paneId} (id: ${result.lastInsertRowid})`);
+  db.close();
+}
+
+// index.ts
+var [command, ...args] = process.argv.slice(2);
+switch (command) {
+  case "list":
+    await cmdList();
+    break;
+  case "peek": {
+    const paneId = args[0];
+    if (!paneId) {
+      console.error("Usage: peer peek <pane-id> [--start-line N] [--end-line N]");
+      process.exit(1);
+    }
+    await cmdPeek(paneId, args.slice(1));
+    break;
+  }
+  case "inbox": {
+    const subcommand = args[0];
+    switch (subcommand) {
+      case "send": {
+        const paneId = args[1];
+        const message = args.slice(2).join(" ");
+        if (!paneId || !message) {
+          console.error("Usage: peer inbox send <pane-id> <message>");
+          process.exit(1);
+        }
+        await cmdSend(paneId, message);
+        break;
+      }
+      case "open":
+        cmdOpen();
+        break;
+      default:
+        console.log("Usage: peer inbox <open|send>");
+        console.log("");
+        console.log("Subcommands:");
+        console.log("  open                   Show and mark as read unread messages");
+        console.log("  send <pane-id> <msg>   Send a message to a pane");
+        process.exit(subcommand ? 1 : 0);
+    }
+    break;
+  }
+  case "new-pane":
+    await cmdNewPane(args);
+    break;
+  case "new-tab":
+    await cmdNewTab(args);
+    break;
+  case "history":
+    cmdHistory(args[0]);
+    break;
+  case "clean":
+    cmdClean();
+    break;
+  default:
+    console.log("Usage: peer <list|peek|inbox|new-pane|new-tab|history|clean>");
+    console.log("");
+    console.log("Commands:");
+    console.log("  list                   List panes (same tab + peer group)");
+    console.log("  peek <pane-id>         Read terminal text from a pane");
+    console.log("  inbox <open|send>      Manage inbox messages");
+    console.log("  new-pane [opts] [-- cmd]  Split a new pane in current tab");
+    console.log("  new-tab  [opts] [-- cmd]  Spawn a new tab and add to peer group");
+    console.log("  history [pane-id]      Show message history");
+    console.log("  clean                  Reset the message database");
+    process.exit(command ? 1 : 0);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+	"name": "@shoppingjaws/peer",
+	"version": "0.1.0",
+	"description": "CLI tool for managing wezterm panes, peer groups, and inter-pane messaging",
+	"type": "module",
+	"bin": {
+		"peer": "dist/index.js"
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "bun build index.ts --outdir dist --target bun",
+		"prepublishOnly": "bun run build",
+		"test": "docker build -f Dockerfile.test -t template-bun-test . && docker run --rm template-bun-test",
+		"format": "biome format --write",
+		"format:check": "biome format",
+		"lint": "biome lint --fix",
+		"lint:check": "biome lint",
+		"typecheck": "tsc --noEmit"
+	},
+	"keywords": [
+		"wezterm",
+		"terminal",
+		"pane",
+		"cli"
+	],
+	"author": "ShoppingJaws",
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/shoppingjaws/wezterm-peer.git"
+	},
+	"devDependencies": {
+		"@types/bun": "latest"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	}
+}