@zswarm/core 0.1.0

package/dist/zellij/panes.d.ts

@@ -0,0 +1,21 @@
+export type ZellijPane = {
+    id: string;
+    numericId: number;
+    isPlugin: boolean;
+    title: string;
+    command?: string | null;
+    cwd?: string | null;
+    tabName?: string | null;
+    tabId?: number | null;
+    focused: boolean;
+    exited: boolean;
+    floating: boolean;
+};
+export declare function normalizePaneId(raw: string, isPlugin?: boolean): string;
+/** Parse `list-panes --json` output. */
+export declare function parsePaneList(stdout: string): ZellijPane[];
+/**
+ * Find a pane by typed id, bare number, exact title, command, then partial
+ * title. Ambiguity is an error rather than a guess.
+ */
+export declare function resolvePane(panes: ZellijPane[], to: string): ZellijPane;

package/dist/zellij/panes.js

@@ -0,0 +1,110 @@
+import { ZellijError } from "../errors.js";
+export function normalizePaneId(raw, isPlugin = false) {
+    const t = raw.trim();
+    if (!t)
+        throw new ZellijError("invalid_pane", "empty pane id");
+    if (/^(terminal|plugin)_\d+$/i.test(t))
+        return t.toLowerCase();
+    if (/^\d+$/.test(t)) {
+        return isPlugin ? `plugin_${t}` : `terminal_${t}`;
+    }
+    return t;
+}
+function parsePaneRow(row) {
+    const numericId = Number(row.id);
+    if (!Number.isFinite(numericId))
+        return null;
+    const isPlugin = row.is_plugin === true;
+    const id = isPlugin ? `plugin_${numericId}` : `terminal_${numericId}`;
+    const title = String(row.title ?? "");
+    const command = (typeof row.pane_command === "string" && row.pane_command) ||
+        (typeof row.terminal_command === "string" && row.terminal_command) ||
+        null;
+    return {
+        id,
+        numericId,
+        isPlugin,
+        title,
+        command,
+        cwd: typeof row.pane_cwd === "string" ? row.pane_cwd : null,
+        tabName: typeof row.tab_name === "string" ? row.tab_name : null,
+        tabId: typeof row.tab_id === "number" ? row.tab_id : null,
+        focused: row.is_focused === true,
+        exited: row.exited === true,
+        floating: row.is_floating === true,
+    };
+}
+/** Parse `list-panes --json` output. */
+export function parsePaneList(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        throw new ZellijError("zellij_failed", "list-panes returned non-JSON output");
+    }
+    if (!Array.isArray(parsed)) {
+        throw new ZellijError("zellij_failed", "list-panes JSON was not an array");
+    }
+    const panes = [];
+    for (const row of parsed) {
+        if (row && typeof row === "object") {
+            const pane = parsePaneRow(row);
+            if (pane)
+                panes.push(pane);
+        }
+    }
+    return panes;
+}
+/**
+ * Find a pane by typed id, bare number, exact title, command, then partial
+ * title. Ambiguity is an error rather than a guess.
+ */
+export function resolvePane(panes, to) {
+    const key = to.trim();
+    if (!key) {
+        throw new ZellijError("peer_not_found", "to (pane id or title) required");
+    }
+    const byTypedId = panes.find((p) => p.id === key.toLowerCase());
+    if (byTypedId)
+        return byTypedId;
+    if (/^\d+$/.test(key)) {
+        const terminals = panes.filter((p) => !p.isPlugin && String(p.numericId) === key);
+        if (terminals.length === 1)
+            return terminals[0];
+        const any = panes.filter((p) => String(p.numericId) === key);
+        if (any.length === 1)
+            return any[0];
+        if (any.length > 1) {
+            throw new ZellijError("peer_ambiguous", `pane id ${key} matches both terminal and plugin; use terminal_${key} or plugin_${key}`);
+        }
+    }
+    const lowered = key.toLowerCase();
+    const titleMatches = panes.filter((p) => !p.isPlugin && p.title.toLowerCase() === lowered);
+    if (titleMatches.length === 1)
+        return titleMatches[0];
+    if (titleMatches.length > 1) {
+        throw new ZellijError("peer_ambiguous", `multiple panes titled "${key}"; use pane id from list`);
+    }
+    const cmdMatches = panes.filter((p) => {
+        if (p.isPlugin || !p.command)
+            return false;
+        const base = p.command.replace(/\\/g, "/").split("/").pop() ?? "";
+        const baseNoExt = base.replace(/\.(exe|cmd|bat)$/i, "");
+        return (base.toLowerCase() === lowered ||
+            baseNoExt.toLowerCase() === lowered ||
+            p.command.toLowerCase().includes(lowered));
+    });
+    if (cmdMatches.length === 1)
+        return cmdMatches[0];
+    if (cmdMatches.length > 1) {
+        throw new ZellijError("peer_ambiguous", `multiple panes match command "${key}"; use pane id from list`);
+    }
+    const titlePartial = panes.filter((p) => !p.isPlugin && p.title.toLowerCase().includes(lowered));
+    if (titlePartial.length === 1)
+        return titlePartial[0];
+    if (titlePartial.length > 1) {
+        throw new ZellijError("peer_ambiguous", `multiple panes match "${key}"; use pane id from list`);
+    }
+    throw new ZellijError("peer_not_found", `no Zellij pane matching "${key}"; zswarm({op:"list"}) to list`);
+}

package/dist/zellij/session.d.ts

@@ -0,0 +1,14 @@
+export type ZellijSessionResolve = {
+    session: string;
+    source: "arg" | "env_zswarm" | "env_zellij" | "sole_live";
+};
+/**
+ * Pane hosting the caller, so writes can refuse to loop back into it.
+ * `ZSWARM_SELF_PANE` wins; Zellij exports `ZELLIJ_PANE_ID` inside a pane.
+ */
+export declare function resolveSelfPaneId(env?: NodeJS.ProcessEnv): string | null;
+export declare function parseSessionList(stdout: string): string[];
+/** Session from an explicit argument or the environment, before asking Zellij. */
+export declare function sessionFromEnv(env: NodeJS.ProcessEnv, explicit?: string | null): ZellijSessionResolve | null;
+/** Pick a session when the environment gave no answer. */
+export declare function sessionFromList(sessions: string[]): ZellijSessionResolve;

package/dist/zellij/session.js

@@ -0,0 +1,44 @@
+import { ZellijError } from "../errors.js";
+/**
+ * Pane hosting the caller, so writes can refuse to loop back into it.
+ * `ZSWARM_SELF_PANE` wins; Zellij exports `ZELLIJ_PANE_ID` inside a pane.
+ */
+export function resolveSelfPaneId(env = process.env) {
+    const raw = (env.ZSWARM_SELF_PANE ?? env.ZELLIJ_PANE_ID ?? "").trim();
+    if (!raw || raw.toLowerCase() === "none")
+        return null;
+    if (/^\d+$/.test(raw))
+        return `terminal_${raw}`;
+    if (/^(terminal|plugin)_\d+$/i.test(raw))
+        return raw.toLowerCase();
+    return null;
+}
+export function parseSessionList(stdout) {
+    return stdout
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter(Boolean);
+}
+/** Session from an explicit argument or the environment, before asking Zellij. */
+export function sessionFromEnv(env, explicit) {
+    const arg = explicit?.trim();
+    if (arg)
+        return { session: arg, source: "arg" };
+    const swarmEnv = env.ZSWARM_SESSION?.trim();
+    if (swarmEnv)
+        return { session: swarmEnv, source: "env_zswarm" };
+    const zellijEnv = env.ZELLIJ_SESSION_NAME?.trim();
+    if (zellijEnv)
+        return { session: zellijEnv, source: "env_zellij" };
+    return null;
+}
+/** Pick a session when the environment gave no answer. */
+export function sessionFromList(sessions) {
+    if (sessions.length === 1) {
+        return { session: sessions[0], source: "sole_live" };
+    }
+    if (sessions.length === 0) {
+        throw new ZellijError("zellij_no_session", "no live Zellij sessions; start zellij or pass session=");
+    }
+    throw new ZellijError("zellij_session_ambiguous", `multiple Zellij sessions (${sessions.join(", ")}); pass session=`);
+}

package/dist/zellij/tabs.d.ts

@@ -0,0 +1,14 @@
+export type ZellijTab = {
+    id: number;
+    position: number;
+    name: string;
+    active: boolean;
+    panes: number;
+    fullscreen: boolean;
+    sync: boolean;
+    layout: string | null;
+};
+/** Parse `list-tabs --json` output. */
+export declare function parseTabList(stdout: string): ZellijTab[];
+/** Find a tab by name (case-insensitive), position, or stable id. */
+export declare function resolveTab(tabs: ZellijTab[], key: string): ZellijTab;

package/dist/zellij/tabs.js

@@ -0,0 +1,56 @@
+import { ZellijError } from "../errors.js";
+/** Parse `list-tabs --json` output. */
+export function parseTabList(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        throw new ZellijError("zellij_failed", "list-tabs returned non-JSON output");
+    }
+    if (!Array.isArray(parsed)) {
+        throw new ZellijError("zellij_failed", "list-tabs JSON was not an array");
+    }
+    const tabs = [];
+    for (const entry of parsed) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const row = entry;
+        const position = Number(row.position);
+        if (!Number.isFinite(position))
+            continue;
+        const id = Number(row.tab_id);
+        tabs.push({
+            id: Number.isFinite(id) ? id : position,
+            position,
+            name: String(row.name ?? ""),
+            active: row.active === true,
+            panes: Number(row.selectable_tiled_panes_count ?? 0),
+            fullscreen: row.is_fullscreen_active === true,
+            sync: row.is_sync_panes_active === true,
+            layout: typeof row.active_swap_layout_name === "string"
+                ? row.active_swap_layout_name
+                : null,
+        });
+    }
+    return tabs;
+}
+/** Find a tab by name (case-insensitive), position, or stable id. */
+export function resolveTab(tabs, key) {
+    const wanted = key.trim();
+    if (!wanted)
+        throw new ZellijError("tab_not_found", "tab name or id required");
+    const byName = tabs.filter((t) => t.name.toLowerCase() === wanted.toLowerCase());
+    if (byName.length === 1)
+        return byName[0];
+    if (byName.length > 1) {
+        throw new ZellijError("tab_ambiguous", `multiple tabs named "${key}"; use the tab id`);
+    }
+    if (/^\d+$/.test(wanted)) {
+        const n = Number(wanted);
+        const byId = tabs.find((t) => t.id === n) ?? tabs.find((t) => t.position === n);
+        if (byId)
+            return byId;
+    }
+    throw new ZellijError("tab_not_found", `no tab matching "${key}"`);
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@zswarm/core",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "zSwarm Zellij client and shared ops dispatch",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "22.14.1",
+    "typescript": "5.8.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@zswarm/wasm": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "pnpm run build && node --test tests/*.test.mjs"
+  }
+}