@zswarm/core 0.1.0

package/dist/zellij/args.d.ts

@@ -0,0 +1,93 @@
+export type PaneDirection = "right" | "left" | "up" | "down";
+export type NewPaneInput = {
+    session: string;
+    command?: string[];
+    cwd?: string | null;
+    name?: string | null;
+    direction?: PaneDirection | null;
+    floating?: boolean;
+    closeOnExit?: boolean;
+    tabId?: number | null;
+    width?: string | null;
+    height?: string | null;
+};
+export type NewTabInput = {
+    session: string;
+    command?: string[];
+    cwd?: string | null;
+    name?: string | null;
+    layout?: string | null;
+    closeOnExit?: boolean;
+};
+export type PipeInput = {
+    session: string;
+    /** `file:` url of the plugin wasm. */
+    url: string;
+    /** Value of the `instance` configuration key — see buildPipeArgs. */
+    configKey: string;
+    name?: string;
+    payload: string;
+};
+/** JSON pipe payload for a multi-pane scrollback read. Keys match the frozen contract. */
+export type ScrollbackRequest = {
+    panes: string[];
+    full?: boolean;
+};
+/**
+ * Emit `{op, panes, full}` in that order. Callers must not hand-roll this JSON —
+ * a payload that does not start with `{` is treated as a bare-word bus command.
+ */
+export declare function scrollbackPayload(req: ScrollbackRequest): string;
+/** A wait the plugin serves by holding the pipe until it resolves. */
+export type WaitRequest = {
+    pane: string;
+    for: "idle" | "match" | "either";
+    match?: string | null;
+    ignoreCase?: boolean;
+    idleMs?: number;
+    timeoutMs?: number;
+    pollMs?: number;
+};
+/**
+ * `regex` is deliberately absent: the plugin has no regex engine, refuses such
+ * requests, and the caller falls back to polling where its own engine decides.
+ */
+export declare function waitPayload(req: WaitRequest): string;
+/** Screens plus "did this move since you last asked", so status needs no gap. */
+export declare function changedPayload(panes: string[]): string;
+export type LaunchPluginInput = {
+    session: string;
+    url: string;
+    configKey: string;
+    floating?: boolean;
+    skipCache?: boolean;
+};
+export declare function sessionPrefix(session: string | undefined): string[];
+/**
+ * Ask the event-bus plugin a question over a CLI pipe.
+ *
+ * The configuration is not decoration: Zellij treats the same plugin under a
+ * different configuration as a different pipe destination, so a distinct
+ * `instance` key is what stops a dead instance from swallowing the message.
+ */
+export declare function buildPipeArgs(input: PipeInput): string[];
+/**
+ * Load the plugin in a visible pane. A pipe-launched plugin has no pane, so its
+ * permission prompt cannot be answered — the first load has to be this one.
+ */
+export declare function buildLaunchPluginArgs(input: LaunchPluginInput): string[];
+export declare function buildListPanesArgs(session: string): string[];
+export declare function buildPasteArgs(session: string, paneId: string, text: string): string[];
+export declare function buildSendEnterArgs(session: string, paneId: string): string[];
+export declare function buildDumpArgs(session: string, paneId: string, full?: boolean): string[];
+export declare function buildSendKeysArgs(session: string, paneId: string, keys: string[]): string[];
+export declare function buildWriteCharsArgs(session: string, paneId: string, chars: string): string[];
+export declare function buildRenamePaneArgs(session: string, paneId: string, name: string): string[];
+export declare function buildRenameTabArgs(session: string, tabId: number, name: string): string[];
+export declare function buildFocusPaneArgs(session: string, paneId: string): string[];
+export declare function buildListTabsArgs(session: string): string[];
+export declare function buildDumpLayoutArgs(session: string): string[];
+export declare function buildStackPanesArgs(session: string, paneIds: string[]): string[];
+export declare function buildClosePaneArgs(session: string, paneId: string): string[];
+export declare function buildNewPaneArgs(input: NewPaneInput): string[];
+export declare function buildNewTabArgs(input: NewTabInput): string[];

package/dist/zellij/args.js

@@ -0,0 +1,261 @@
+import { ZellijError } from "../errors.js";
+import { BUS_PIPE_NAME } from "./bus.js";
+import { normalizePaneId } from "./panes.js";
+/**
+ * Emit `{op, panes, full}` in that order. Callers must not hand-roll this JSON —
+ * a payload that does not start with `{` is treated as a bare-word bus command.
+ */
+export function scrollbackPayload(req) {
+    if (req.panes.length === 0) {
+        throw new ZellijError("bad_arg", "scrollback panes must be a non-empty list");
+    }
+    return JSON.stringify({
+        op: "scrollback",
+        panes: req.panes,
+        full: req.full === true,
+    });
+}
+/**
+ * `regex` is deliberately absent: the plugin has no regex engine, refuses such
+ * requests, and the caller falls back to polling where its own engine decides.
+ */
+export function waitPayload(req) {
+    if (!req.pane.trim()) {
+        throw new ZellijError("bad_arg", "wait needs a pane");
+    }
+    if (req.for !== "idle" && !req.match) {
+        throw new ZellijError("bad_arg", "match waits need a needle");
+    }
+    return JSON.stringify({
+        op: "wait",
+        pane: req.pane,
+        for: req.for,
+        match: req.match ?? null,
+        ignoreCase: req.ignoreCase === true,
+        idleMs: req.idleMs ?? 2000,
+        timeoutMs: req.timeoutMs ?? 60000,
+        pollMs: req.pollMs ?? 50,
+    });
+}
+/** Screens plus "did this move since you last asked", so status needs no gap. */
+export function changedPayload(panes) {
+    if (panes.length === 0) {
+        throw new ZellijError("bad_arg", "changed needs a non-empty pane list");
+    }
+    return JSON.stringify({ op: "changed", panes });
+}
+export function sessionPrefix(session) {
+    return session ? ["--session", session] : [];
+}
+/**
+ * Ask the event-bus plugin a question over a CLI pipe.
+ *
+ * The configuration is not decoration: Zellij treats the same plugin under a
+ * different configuration as a different pipe destination, so a distinct
+ * `instance` key is what stops a dead instance from swallowing the message.
+ */
+export function buildPipeArgs(input) {
+    return [
+        ...sessionPrefix(input.session),
+        "pipe",
+        "--plugin",
+        input.url,
+        "--plugin-configuration",
+        `instance=${input.configKey}`,
+        "--name",
+        input.name ?? BUS_PIPE_NAME,
+        "--",
+        input.payload,
+    ];
+}
+/**
+ * Load the plugin in a visible pane. A pipe-launched plugin has no pane, so its
+ * permission prompt cannot be answered — the first load has to be this one.
+ */
+export function buildLaunchPluginArgs(input) {
+    const args = [
+        ...sessionPrefix(input.session),
+        "action",
+        "launch-or-focus-plugin",
+        "--configuration",
+        `instance=${input.configKey}`,
+    ];
+    if (input.floating)
+        args.push("--floating");
+    if (input.skipCache)
+        args.push("--skip-plugin-cache");
+    args.push(input.url);
+    return args;
+}
+export function buildListPanesArgs(session) {
+    return [
+        ...sessionPrefix(session),
+        "action",
+        "list-panes",
+        "--json",
+        "--command",
+        "--state",
+        "--tab",
+    ];
+}
+export function buildPasteArgs(session, paneId, text) {
+    return [
+        ...sessionPrefix(session),
+        "action",
+        "paste",
+        "--pane-id",
+        normalizePaneId(paneId),
+        // Without the end-of-options marker, a body starting with `-` is parsed
+        // as a zellij flag instead of being typed.
+        "--",
+        text,
+    ];
+}
+export function buildSendEnterArgs(session, paneId) {
+    return [
+        ...sessionPrefix(session),
+        "action",
+        "send-keys",
+        "--pane-id",
+        normalizePaneId(paneId),
+        "Enter",
+    ];
+}
+export function buildDumpArgs(session, paneId, full = false) {
+    const args = [
+        ...sessionPrefix(session),
+        "action",
+        "dump-screen",
+        "--pane-id",
+        normalizePaneId(paneId),
+    ];
+    if (full)
+        args.push("--full");
+    return args;
+}
+export function buildSendKeysArgs(session, paneId, keys) {
+    for (const key of keys) {
+        if (key.length > 1 && key.startsWith("-")) {
+            throw new ZellijError("bad_key", `key "${key}" looks like a flag`);
+        }
+    }
+    return [
+        ...sessionPrefix(session),
+        "action",
+        "send-keys",
+        "--pane-id",
+        normalizePaneId(paneId),
+        ...keys,
+    ];
+}
+export function buildWriteCharsArgs(session, paneId, chars) {
+    return [
+        ...sessionPrefix(session),
+        "action",
+        "write-chars",
+        "--pane-id",
+        normalizePaneId(paneId),
+        "--",
+        chars,
+    ];
+}
+export function buildRenamePaneArgs(session, paneId, name) {
+    return [
+        ...sessionPrefix(session),
+        "action",
+        "rename-pane",
+        "--pane-id",
+        normalizePaneId(paneId),
+        "--",
+        name,
+    ];
+}
+export function buildRenameTabArgs(session, tabId, name) {
+    return [
+        ...sessionPrefix(session),
+        "action",
+        "rename-tab-by-id",
+        String(tabId),
+        "--",
+        name,
+    ];
+}
+export function buildFocusPaneArgs(session, paneId) {
+    return [
+        ...sessionPrefix(session),
+        "action",
+        "focus-pane-id",
+        normalizePaneId(paneId),
+    ];
+}
+export function buildListTabsArgs(session) {
+    return [
+        ...sessionPrefix(session),
+        "action",
+        "list-tabs",
+        "--json",
+        "--panes",
+        "--state",
+        "--layout",
+    ];
+}
+export function buildDumpLayoutArgs(session) {
+    return [...sessionPrefix(session), "action", "dump-layout"];
+}
+export function buildStackPanesArgs(session, paneIds) {
+    return [
+        ...sessionPrefix(session),
+        "action",
+        "stack-panes",
+        "--",
+        ...paneIds.map((id) => normalizePaneId(id)),
+    ];
+}
+export function buildClosePaneArgs(session, paneId) {
+    return [
+        ...sessionPrefix(session),
+        "action",
+        "close-pane",
+        "--pane-id",
+        normalizePaneId(paneId),
+    ];
+}
+export function buildNewPaneArgs(input) {
+    const args = [...sessionPrefix(input.session), "action", "new-pane"];
+    if (input.cwd)
+        args.push("--cwd", input.cwd);
+    if (input.name)
+        args.push("--name", input.name);
+    if (input.direction)
+        args.push("--direction", input.direction);
+    if (input.floating)
+        args.push("--floating");
+    if (input.width)
+        args.push("--width", input.width);
+    if (input.height)
+        args.push("--height", input.height);
+    if (typeof input.tabId === "number") {
+        args.push("--tab-id", String(input.tabId));
+    }
+    if (input.closeOnExit)
+        args.push("--close-on-exit");
+    if (input.command && input.command.length > 0) {
+        args.push("--", ...input.command);
+    }
+    return args;
+}
+export function buildNewTabArgs(input) {
+    const args = [...sessionPrefix(input.session), "action", "new-tab"];
+    if (input.cwd)
+        args.push("--cwd", input.cwd);
+    if (input.name)
+        args.push("--name", input.name);
+    if (input.layout)
+        args.push("--layout", input.layout);
+    if (input.closeOnExit)
+        args.push("--close-on-exit");
+    if (input.command && input.command.length > 0) {
+        args.push("--", ...input.command);
+    }
+    return args;
+}

package/dist/zellij/binary.d.ts

@@ -0,0 +1,17 @@
+import { createSshExec, NOT_FOUND_EXIT, type ExecFn, type ExecResult, type SshTarget } from "../exec.js";
+export { createSshExec, type SshTarget };
+export type ZellijExecResult = ExecResult;
+export type ZellijExecFn = ExecFn;
+export declare const DEFAULT_TIMEOUT_MS = 15000;
+export { NOT_FOUND_EXIT };
+/** Expand a leading `~/` or `~\` using USERPROFILE/HOME. */
+export declare function expandHomePath(input: string, env?: NodeJS.ProcessEnv): string;
+export declare function resolveZellijBinary(env?: NodeJS.ProcessEnv): string;
+export declare function sanitizeZellijEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Remote crew: `ZSWARM_SSH=user@host` routes every zellij call over ssh.
+ * `ZSWARM_SSH_OPTS` is split on whitespace; `BatchMode` keeps it non-interactive.
+ */
+export declare function resolveSshTarget(env?: NodeJS.ProcessEnv): SshTarget | null;
+/** Runner bound to the resolved zellij binary and a cleaned environment. */
+export declare function defaultExec(zellijPath: string, env: NodeJS.ProcessEnv): ZellijExecFn;

package/dist/zellij/binary.js

@@ -0,0 +1,96 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { createExec, createSshExec, NOT_FOUND_EXIT, } from "../exec.js";
+export { createSshExec };
+export const DEFAULT_TIMEOUT_MS = 15_000;
+export { NOT_FOUND_EXIT };
+/** Expand a leading `~/` or `~\` using USERPROFILE/HOME. */
+export function expandHomePath(input, env = process.env) {
+    const trimmed = input.trim();
+    if (!trimmed.startsWith("~/") && !trimmed.startsWith("~\\"))
+        return trimmed;
+    const home = env.USERPROFILE || env.HOME || homedir();
+    if (!home)
+        return trimmed;
+    return join(home, trimmed.slice(2));
+}
+export function resolveZellijBinary(env = process.env) {
+    const fromEnv = expandHomePath((env.ZSWARM_BIN ?? env.ZSWARM_PATH ?? env.ZELLIJ_BIN ?? "")
+        .trim()
+        .replace(/^['"]|['"]$/g, ""), env);
+    if (fromEnv && existsSync(fromEnv)) {
+        if (/\.cmd$/i.test(fromEnv)) {
+            const exe = fromEnv.replace(/\.cmd$/i, ".exe");
+            if (existsSync(exe))
+                return exe;
+            const wingetExe = join(env.LOCALAPPDATA ||
+                join(env.USERPROFILE || env.HOME || homedir(), "AppData", "Local"), "Zellij", "zellij.exe");
+            if (existsSync(wingetExe))
+                return wingetExe;
+        }
+        return fromEnv;
+    }
+    const home = env.USERPROFILE || env.HOME || homedir();
+    const localAppData = env.LOCALAPPDATA || (home ? join(home, "AppData", "Local") : "");
+    const candidates = [
+        localAppData ? join(localAppData, "Zellij", "zellij.exe") : "",
+        home ? join(home, ".local", "bin", "zellij") : "",
+        home ? join(home, ".cargo", "bin", "zellij") : "",
+        home ? join(home, ".cargo", "bin", "zellij.exe") : "",
+        "/usr/local/bin/zellij",
+        "/opt/homebrew/bin/zellij",
+        ...(env.PATH ?? env.Path ?? "")
+            .split(delimiter)
+            .filter(Boolean)
+            .flatMap((dir) => process.platform === "win32"
+            ? [join(dir, "zellij.exe"), join(dir, "zellij")]
+            : [join(dir, "zellij")]),
+    ].filter(Boolean);
+    for (const cand of candidates) {
+        if (existsSync(cand))
+            return cand;
+    }
+    return process.platform === "win32" ? "zellij.exe" : "zellij";
+}
+export function sanitizeZellijEnv(env) {
+    const out = {};
+    for (const key of Object.keys(env)) {
+        const value = env[key];
+        if (typeof value === "string")
+            out[key] = value;
+    }
+    if (process.platform === "win32") {
+        if (!out.SystemRoot && !out.SYSTEMROOT) {
+            out.SystemRoot = process.env.SystemRoot || "C:\\Windows";
+        }
+        if (out.PATH && !out.Path)
+            out.Path = out.PATH;
+        if (out.Path && !out.PATH)
+            out.PATH = out.Path;
+    }
+    return out;
+}
+/**
+ * Remote crew: `ZSWARM_SSH=user@host` routes every zellij call over ssh.
+ * `ZSWARM_SSH_OPTS` is split on whitespace; `BatchMode` keeps it non-interactive.
+ */
+export function resolveSshTarget(env = process.env) {
+    const host = env.ZSWARM_SSH?.trim();
+    if (!host)
+        return null;
+    const options = (env.ZSWARM_SSH_OPTS ?? "").trim().split(/\s+/).filter(Boolean);
+    if (!options.some((o) => o.startsWith("BatchMode"))) {
+        options.unshift("-o", "BatchMode=yes");
+    }
+    return {
+        ssh: env.ZSWARM_SSH_BIN?.trim() || "ssh",
+        host,
+        remoteBin: env.ZSWARM_REMOTE_BIN?.trim() || "zellij",
+        options,
+    };
+}
+/** Runner bound to the resolved zellij binary and a cleaned environment. */
+export function defaultExec(zellijPath, env) {
+    return createExec(zellijPath, sanitizeZellijEnv(env));
+}

package/dist/zellij/bus.d.ts

@@ -0,0 +1,91 @@
+import type { ZellijPane } from "./panes.js";
+/**
+ * The event-bus side of zswarm: Zellij pushes pane and tab state into a WASM
+ * plugin as it changes, and one CLI pipe reads it back out of memory. Parsing
+ * and path resolution live here; the process calls live in the client, and the
+ * fallback policy lives in `ops/bus.ts`.
+ */
+export declare const BUS_PIPE_NAME = "zswarm";
+export declare const DEFAULT_BUS_KEY = "zswarm-bus";
+/** A stalled instance answers nothing, so the pipe must not inherit the long timeout. */
+export declare const DEFAULT_BUS_TIMEOUT_MS = 2500;
+export type BusPane = {
+    id: string;
+    title: string;
+    exited: boolean;
+    focused: boolean;
+    command: string | null;
+    tab: number;
+};
+export type BusSnapshot = {
+    /** False until Zellij has pushed a manifest — a cold instance, not an empty session. */
+    ready: boolean;
+    paneUpdates: number;
+    tabUpdates: number;
+    tabs: string[];
+    panes: BusPane[];
+};
+export type BusMarker = {
+    plugin: string;
+    configKey: string;
+    installedAt: number;
+};
+export type BusScrollbackPane = {
+    id: string;
+    viewport: string[];
+    above: string[];
+    below: string[];
+};
+export type BusScrollback = {
+    ready: boolean;
+    panes: BusScrollbackPane[];
+    missing: string[];
+};
+export type BusWait = {
+    reason: "match" | "idle" | "timeout" | "gone";
+    pane: string;
+    screen: string;
+};
+export type BusChangedPane = {
+    id: string;
+    screen: string;
+    changed: boolean;
+    /** True the first time the plugin has been asked about this pane. */
+    first: boolean;
+};
+export type BusChanged = {
+    ready: boolean;
+    panes: BusChangedPane[];
+    missing: string[];
+};
+/** A held wait answers once, late. Same scan as every other bus reply. */
+export declare function parseWaitReply(stdout: string): BusWait | null;
+export declare function parseChangedReply(stdout: string): BusChanged | null;
+/** Absolute path of the plugin wasm, or null when there is nothing to load. */
+export declare function resolveBusPlugin(env?: NodeJS.ProcessEnv): string | null;
+/** Zellij wants a `file:` url with forward slashes, including on Windows. */
+export declare function busPluginUrl(pluginPath: string): string;
+/** zswarm-bus → zswarm-bus-2 → zswarm-bus-3: a fresh pipe destination each time. */
+export declare function nextConfigKey(key: string): string;
+/**
+ * Pull the plugin's answer out of the pipe. Zellij interleaves its own notices
+ * ("Action CliPipe did not complete within 1s timeout" shows up on successful
+ * runs too), so scan for the first line that is our JSON rather than parsing
+ * the whole of stdout.
+ */
+export declare function parseBusReply(stdout: string): BusSnapshot | null;
+/**
+ * Same scan as parseBusReply: Zellij prints "Action CliPipe did not complete
+ * within 1s timeout" on successful pipes, so the JSON is never the whole of
+ * stdout. First line with ok===true and a panes array wins; anything else is
+ * no reply and the caller falls back.
+ */
+export declare function parseScrollbackReply(stdout: string): BusScrollback | null;
+/** Rebuild dump-screen-shaped text. Byte-identity with dump-screen is unproven. */
+export declare function scrollbackToScreen(pane: BusScrollbackPane): string;
+/**
+ * Shape the snapshot like `list-panes` output. `cwd` and `floating` are not in
+ * the manifest Zellij pushes, so they read as unknown here — callers that need
+ * them (anything verbose) must take the polling path instead.
+ */
+export declare function busToPanes(snapshot: BusSnapshot): ZellijPane[];