zswarm 0.1.0 → 0.1.2

package/README.md

@@ -1,173 +1,14 @@
-# zSwarm
+# zswarm
 
-Coordinate CLI AI crews across **Zellij** terminal panes. Control agents, pass prompts between panes, manage git worktrees, inspect outputs, and sync crew tasks via CLI or Model Context Protocol (MCP).
+Meta-package for a global install. Puts `zswarm` (CLI) and `zswarm-mcp` (MCP server) on your PATH.
 
-```text
-                       you ──▶ any agent ──┐
-                                           │ zswarm({op:"send", to:"reviewer"})
-                                           ▼
-      every pane can call zswarm ──▶ ┌─────────┐
-      so agents drive each other     │ zswarm  │
-                                     │ cli/mcp │
-                                     └────┬────┘
-                       paste + Enter ┌────┴────┐ read screen / pushed state
-                                     ▼         ▼
- ══ this machine ══════════════════════════════╗ ══ ssh user@build-01 ═════════╗
-   zellij "crew"                               ║   zellij "ci"                 ║
-                                               ║                               ║
-   ┌────────────┐  send   ┌────────────┐       ║   ┌────────────┐              ║
-   │ codex      │────────▶│ claude     │───────╫──▶│ opencode   │              ║
-   │ builder    │◀────────│ reviewer   │  send ║   │ test-runner│              ║
-   │ wt:feat-a  │ signal  │ wt:rev-a   │       ║   │ wt:feat-a  │              ║
-   └────────────┘         └────────────┘       ║   └──────┬─────┘              ║
-   ┌────────────┐         ┌────────────┐       ║   ┌──────▼─────┐              ║
-   │ cursor     │         │ agy        │       ║   │ pi         │              ║
-   │ refactor   │         │ docs       │       ║   │ deploy     │              ║
-   │ wt:feat-b  │         │ wt:docs    │       ║   │ cwd:/srv   │              ║
-   └────────────┘         └────────────┘       ║   └────────────┘              ║
- ═══════════════════════════════════════════════╝ ══════════════════════════════╝
-     one pane = one agent + one role + optionally its own worktree
-     any pane can drive any other, on this machine or across the ssh boundary
-```
-
----
-
-## ⚡ Quick Start
-
-### Requirements
-- **Zellij** ≥ 0.42 on `PATH` (or set `ZSWARM_BIN` / `ZSWARM_PATH`)
-- **Node.js** ≥ 20
-
-### Installation
 ```bash
 npm i -g zswarm
 zswarm list
 ```
 
-Enable the optional Zellij event-bus plugin once per machine for zero-polling state updates:
-```bash
-zswarm bus --install
-```
-
-### MCP Server Setup
-Configure `zswarm-mcp` (stdio MCP server bundled with the package) in your MCP host:
-
-```json
-{
-  "mcpServers": {
-    "zswarm": {
-      "command": "/absolute/path/to/zswarm-mcp",
-      "env": {
-        "ZSWARM_SESSION": "my-zellij-session"
-      }
-    }
-  }
-}
-```
-> **Note:** Use the absolute path to `zswarm-mcp` and specify `ZSWARM_SESSION` to prevent ambiguous session errors when multiple Zellij sessions run.
-
----
-
-## Usage & Quick Syntax
-
-Every operation is supported both via **CLI** (`zswarm <op> [flags]`) and **MCP** (`zswarm({ op: "<op>", ... })`).
-
-### Essential Examples
-
-```bash
-# 1. Inspect Panes & Status
-zswarm list                                     # List active panes
-zswarm status                                   # Check status: busy | waiting | idle | exited
-
-# 2. Spawn Panes & Worktrees
-zswarm spawn --command "claude" --name reviewer # Spawn agent pane
-zswarm spawn --command "codex" --worktree feature-auth --name auth-dev   # Isolated git worktree pane
-
-# 3. Pass Prompts & Input
-zswarm send --to reviewer --body "Review changes in src/" --submit auto
-zswarm keys --to reviewer --key "Ctrl c"        # Send special keys / interrupts
-
-# 4. Read Outputs & Wait
-zswarm dump --to reviewer --max 4000            # Read recent screen tail
-zswarm tail --to reviewer                       # Incremental read since last check
-zswarm wait --to reviewer --match "DONE"        # Block until pattern matched or pane idle
-
-# 5. Coordinate Crew & Sync Signals
-zswarm broadcast --all --group builder --body "Run test suite"  # group matches pane title or command
-zswarm signal --channel tests --payload ok      # Send signal to durable channel
-zswarm await --channel tests --count 3          # Wait for 3 worker signals
-```
-
----
-
-## 📋 Operations Reference
-
-| Operation | Purpose | Key Parameters / Flags |
-|---|---|---|
-| `list` / `sessions` | List panes or live Zellij sessions | `verbose` |
-| `status` | Panes classified by state (`idle`, `busy`, `waiting`, `exited`) | `to`, `sampleMs`, `since-last` |
-| `spawn` | Launch command in new pane, tab, or git worktree | `command`, `name`, `cwd`, `worktree`, `tab`, `newTab` |
-| `send` | Send text / prompt into a pane | `to`, `body`, `submit` (`auto`\|`double-enter`\|`none`), `expect` |
-| `dump` | Read screen content (screen tail) | `to`, `max` (default 8000) |
-| `tail` | Incremental screen read since last cursor | `to`, `reset` |
-| `wait` | Block until quiet, pattern match, or idle | `to`, `match`, `for` (`idle`), `idleMs`, `timeoutMs` |
-| `broadcast` | Send one prompt to multiple panes | `to`, `tab`, `all`, `group`, `body` |
-| `keys` / `interrupt` | Send key combos (`Ctrl c`, `Esc`) or raw chars | `to`, `keys`, `chars`, `enter`, `hard` |
-| `close` | Close a pane | `to`, `force` |
-| `signal` / `signals` / `await` | Durable message channels & barrier sync | `channel`, `payload`, `count` |
-| `worktrees` / `unworktree` | List or remove managed git worktrees | `cwd`, `branch`, `path`, `force` |
-| `diff` / `checkpoint` | Inspect peer worktree patch or autocommit WIP | `branch`, `path`, `stat`, `message` |
-| `rename` / `focus` | Retitle pane/tab or focus pane | `to`, `tab`, `name` |
-| `tabs` / `layout` / `stack` | Inspect tabs, layout KDL, or stack panes | `to`, `max` |
-| `bus` / `log` | Event bus plugin management & delivery log | `install`, `clear`, `failed`, `limit` |
-
----
-
-## 🛡️ Safety & Policy Guards
-
-- **Self-Target Guard:** Operations refuse to modify zSwarm's own pane (`allowSelf: true` to override).
-- **Execution & Exited Guards:** Prevents writing to exited panes (`force: true` to override).
-- **Prompt Safety (`expect`):** `send --expect <text>` ensures target pane screen contains `<text>` before writing (prevents accidental shell execution).
-- **Submission Verification (`submit`):** `auto` verifies text submission into TUI composers and retries Enter if unsubmitted.
-
-### Environment Security Controls
-
-| Env Variable | Effect |
-|---|---|
-| `ZSWARM_READONLY=1` | Disable all write ops (`send`, `spawn`, `close`, etc.) |
-| `ZSWARM_ALLOW_PANES` / `ZSWARM_DENY_PANES` | Comma-separated list/patterns of allowed/denied pane titles |
-| `ZSWARM_ALLOW_SPAWN=0` | Disable spawning new panes |
-| `ZSWARM_ALLOW_CLOSE=0` | Disable closing panes |
-| `ZSWARM_ALLOW_WORKTREE_REMOVE=0` | Disable removing git worktrees |
-
----
-
-## ⚙️ Environment Variables
-
-| Variable | Description |
-|---|---|
-| `ZSWARM_BIN` / `ZSWARM_PATH` | Path to `zellij` executable |
-| `ZSWARM_SESSION` | Default Zellij session name |
-| `ZELLIJ_SESSION_NAME` | Active Zellij session (set automatically inside Zellij panes) |
-| `ZSWARM_WORKTREE_ROOT` | Directory for linked worktrees (default: `<repo>-worktrees`) |
-| `ZSWARM_STATE_DIR` | State storage directory for logs, signals, and cursors (default: `~/.zswarm`) |
-| `ZSWARM_SSH` | `user@host` — Route Zellij commands across SSH |
-
----
-
-## 📦 Monorepo Structure
-
-| Package | Purpose |
-|---|---|
-| `zswarm` | Main meta-package (`npm i -g zswarm`) |
-| `@zswarm/core` | Core Zellij client and shared dispatch engine |
-| `@zswarm/cli` | `zswarm` command line interface |
-| `@zswarm/mcp` | Stdio MCP server (`zswarm-mcp`) |
-| `@zswarm/wasm` | Precompiled Rust event-bus WASM plugin |
-| `@zswarm/pi` | Extension bridge for harnesses without native MCP support |
-
----
+Ops, env, MCP setup, and the event bus: the [repo README](../../README.md).
 
-## 📜 License
+## License
 
-[MIT](LICENSE)
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zswarm",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "Coordinate CLI agent crews in Zellij panes",
   "engines": {
@@ -22,17 +22,11 @@
     "README.md"
   ],
   "dependencies": {
-    "@zswarm/cli": "0.1.0",
-    "@zswarm/mcp": "0.1.0"
+    "@zswarm/mcp": "0.1.1",
+    "@zswarm/cli": "0.1.1"
   },
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "pnpm -r run build",
-    "build:plugin": "cd plugin/zswarm-events && cargo build --release --target wasm32-wasip1 && node -e \"require('node:fs').copyFileSync('target/wasm32-wasip1/release/zswarm-events.wasm','../../packages/wasm/zswarm-bus-v3.wasm')\"",
-    "test": "pnpm --dir packages/core test",
-    "cli": "pnpm --dir packages/cli exec node dist/cli.js",
-    "mcp": "pnpm --dir packages/mcp exec node dist/mcp-server.js"
-  }
+  "scripts": {}
 }

package/bin/launch-mcp.mjs

@@ -1,85 +0,0 @@
-#!/usr/bin/env node
-/**
- * Cross-host MCP launcher for zSwarm (Cursor / Codex / Claude).
- * Windows-safe: hosts must exec `node` + this file.
- */
-import { spawn } from "node:child_process";
-import { existsSync, statSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const home = process.env.USERPROFILE || process.env.HOME || homedir();
-const thisFile = fileURLToPath(import.meta.url);
-const pluginRoot = join(dirname(thisFile), "..");
-
-function isFile(p) {
-  try {
-    return statSync(p).isFile();
-  } catch {
-    return false;
-  }
-}
-
-function enrichPath(env) {
-  const sep = process.platform === "win32" ? ";" : ":";
-  const extras = [
-    process.platform === "win32"
-      ? join(env.LOCALAPPDATA || join(home, "AppData", "Local"), "Zellij")
-      : "",
-    join(home, ".local", "bin"),
-    join(home, ".cargo", "bin"),
-  ].filter(Boolean);
-  const current = env.PATH || env.Path || "";
-  const merged = [...extras, ...current.split(sep).filter(Boolean)];
-  const seen = new Set();
-  const path = merged
-    .filter((p) => {
-      const key = p.toLowerCase();
-      if (seen.has(key)) return false;
-      seen.add(key);
-      return true;
-    })
-    .join(sep);
-  return { ...env, PATH: path, Path: path };
-}
-
-const script = join(pluginRoot, "packages", "mcp", "dist", "mcp-server.js");
-if (!isFile(script)) {
-  console.error(
-    "zswarm: missing packages/mcp/dist/mcp-server.js — run: pnpm install && pnpm run build",
-  );
-  process.exit(127);
-}
-
-const env = enrichPath(process.env);
-
-function expandHome(p) {
-  if (typeof p !== "string") return p;
-  const t = p.trim();
-  if (!t.startsWith("~/") && !t.startsWith("~\\")) return p;
-  return join(home, t.slice(2));
-}
-if (env.ZSWARM_BIN) env.ZSWARM_BIN = expandHome(env.ZSWARM_BIN);
-if (env.ZSWARM_PATH) env.ZSWARM_PATH = expandHome(env.ZSWARM_PATH);
-
-const zellijExe = join(
-  env.LOCALAPPDATA || join(home, "AppData", "Local"),
-  "Zellij",
-  "zellij.exe",
-);
-if (!env.ZSWARM_BIN && !env.ZSWARM_PATH && isFile(zellijExe)) {
-  env.ZSWARM_BIN = zellijExe;
-}
-
-const child = spawn(process.execPath, [script, ...process.argv.slice(2)], {
-  stdio: "inherit",
-  env,
-  windowsHide: true,
-  shell: false,
-});
-child.on("exit", (code) => process.exit(code ?? 1));
-child.on("error", (error) => {
-  console.error(error.message);
-  process.exit(1);
-});