@zswarm/core 0.4.2 → 0.6.0

package/dist/zellij/server-identity.js

@@ -0,0 +1,405 @@
+import { execFile } from "node:child_process";
+import { readFileSync, readdirSync } from "node:fs";
+const WINDOWS_PROCESS_SCRIPT = 'Get-CimInstance Win32_Process | ForEach-Object { "$($_.ProcessId)`t$($_.ParentProcessId)`t$($_.CommandLine)" }';
+/** Cap on how far an ancestor walk goes; guards against malformed tables. */
+const MAX_ANCESTOR_HOPS = 64;
+const defaultRunner = (file, args, options) => new Promise((resolve, reject) => {
+    execFile(file, args, {
+        timeout: options.timeout,
+        windowsHide: options.windowsHide,
+        maxBuffer: 8 * 1024 * 1024,
+        encoding: "utf8",
+    }, (err, stdout, stderr) => {
+        if (err)
+            reject(err);
+        else
+            resolve({ stdout: String(stdout), stderr: String(stderr) });
+    });
+});
+function parsePsOutput(stdout) {
+    const rows = [];
+    for (const line of stdout.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const match = /^(\d+)\s+(\d+)\s+(.*)$/.exec(trimmed);
+        if (!match)
+            continue;
+        rows.push({
+            pid: Number(match[1]),
+            ppid: Number(match[2]),
+            args: match[3].trim(),
+        });
+    }
+    return rows;
+}
+function parseWindowsOutput(stdout) {
+    const rows = [];
+    for (const line of stdout.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        const parts = line.split("\t");
+        if (parts.length < 3)
+            continue;
+        const pid = Number(parts[0]);
+        const ppid = Number(parts[1]);
+        if (!Number.isInteger(pid) || !Number.isInteger(ppid))
+            continue;
+        rows.push({
+            pid,
+            ppid,
+            args: parts.slice(2).join("\t").trim(),
+        });
+    }
+    return rows;
+}
+/** Linux: /proc/<pid>/stat for the parent and cmdline for the command. */
+function readProcTable() {
+    const rows = [];
+    let entries;
+    try {
+        entries = readdirSync("/proc");
+    }
+    catch {
+        return [];
+    }
+    for (const name of entries) {
+        if (!/^\d+$/.test(name))
+            continue;
+        try {
+            const stat = readFileSync(`/proc/${name}/stat`, "utf8");
+            // comm may contain spaces and parentheses: parse from the LAST ')'.
+            const close = stat.lastIndexOf(")");
+            if (close < 0)
+                continue;
+            const fields = stat.slice(close + 1).trim().split(/\s+/);
+            // state is fields[0]; ppid is fields[1].
+            const ppid = Number(fields[1]);
+            if (!Number.isInteger(ppid))
+                continue;
+            let args = "";
+            try {
+                args = readFileSync(`/proc/${name}/cmdline`, "utf8")
+                    .replace(/\0/g, " ")
+                    .trim();
+            }
+            catch {
+                // Kernel threads have no cmdline; the ppid chain still matters.
+            }
+            rows.push({ pid: Number(name), ppid, args });
+        }
+        catch {
+            // Vanished between readdir and read.
+        }
+    }
+    return rows;
+}
+/**
+ * Snapshot the local process table. Never throws: a failure returns [].
+ * Linux reads /proc; macOS/other POSIX shells out to `ps`; Windows asks
+ * PowerShell for Win32_Process. Both external reads are bounded at 5s.
+ */
+export async function readProcessTable(opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const runner = opts.runner ?? defaultRunner;
+    try {
+        if (platform === "linux")
+            return readProcTable();
+        if (platform === "win32") {
+            const result = await runner("powershell", ["-NoProfile", "-Command", WINDOWS_PROCESS_SCRIPT], { timeout: 5_000, windowsHide: true });
+            return parseWindowsOutput(result.stdout);
+        }
+        const result = await runner("ps", ["-axo", "pid=,ppid=,command="], {
+            timeout: 5_000,
+        });
+        return parsePsOutput(result.stdout);
+    }
+    catch {
+        return [];
+    }
+}
+/** Strip one layer of matching surrounding quotes from a single token. */
+function unquoteToken(token) {
+    for (const quote of ['"', "'"]) {
+        if (token.length >= 2 && token.startsWith(quote) && token.endsWith(quote)) {
+            return token.slice(1, -1);
+        }
+    }
+    return token;
+}
+/**
+ * Whitespace-split a command line, dropping one layer of surrounding quotes
+ * per token. `Prog  "a b"  c` and `Prog a b c` normalize the same way; this is
+ * the comparison form used for server args versus Zellij's pane_command.
+ */
+function commandTokens(args) {
+    return String(args)
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean)
+        .map(unquoteToken);
+}
+function normalizeCommand(args) {
+    return commandTokens(args).join(" ");
+}
+/**
+ * Parse the argv of a `zellij --server <socketPath>` server process.
+ * Returns null for anything that is not a Zellij server. The creation name is
+ * the last path segment of the socket path (the name the session had when its
+ * server started; renames do not touch it).
+ */
+export function parseServerArgs(args) {
+    const tokens = commandTokens(args);
+    const argv0 = tokens[0];
+    if (!argv0)
+        return null;
+    const base = argv0.replace(/\\/g, "/").split("/").pop() ?? "";
+    if (!/^zellij(\.exe)?$/i.test(base))
+        return null;
+    const index = tokens.indexOf("--server");
+    if (index < 0 || index + 1 >= tokens.length)
+        return null;
+    const socketPath = tokens[index + 1];
+    if (!socketPath)
+        return null;
+    const segments = socketPath.split(/[\\/]/).filter(Boolean);
+    const creationName = segments[segments.length - 1] ?? "";
+    if (!creationName)
+        return null;
+    return { socketPath, creationName };
+}
+/**
+ * Walk parents from `pid` (up to 64 hops, stopping on a cycle or a missing
+ * row) and return the first Zellij server found, or null.
+ */
+export function findAncestorServer(table, pid) {
+    const byPid = new Map(table.map((proc) => [proc.pid, proc]));
+    const seen = new Set();
+    let current = pid;
+    for (let hops = 0; hops < MAX_ANCESTOR_HOPS; hops++) {
+        if (seen.has(current))
+            return null;
+        seen.add(current);
+        const proc = byPid.get(current);
+        if (!proc)
+            return null;
+        const parsed = parseServerArgs(proc.args);
+        if (parsed) {
+            return { pid: proc.pid, creationName: parsed.creationName, socketPath: parsed.socketPath };
+        }
+        if (!Number.isInteger(proc.ppid) || proc.ppid <= 0)
+            return null;
+        current = proc.ppid;
+    }
+    return null;
+}
+/** Every Zellij server currently present in the table. */
+export function liveServers(table) {
+    const servers = [];
+    for (const proc of table) {
+        const parsed = parseServerArgs(proc.args);
+        if (!parsed)
+            continue;
+        servers.push({ pid: proc.pid, creationName: parsed.creationName, socketPath: parsed.socketPath });
+    }
+    return servers;
+}
+/** True when a pane row is the requested (non-plugin) pane id. */
+export function paneMatchesId(pane, paneId) {
+    const key = paneId.trim().toLowerCase();
+    if (!key || pane.isPlugin)
+        return false;
+    return (pane.id.toLowerCase() === key ||
+        String(pane.numericId) === key ||
+        `terminal_${pane.numericId}` === key);
+}
+/** The live panes of a session that can take one of a server's children. */
+function paneCommandsFor(session) {
+    const commands = [];
+    for (const pane of session.panes) {
+        // A held pane ("exited, press Enter to re-run") has no running process,
+        // so it cannot take one of the server's children.
+        if (pane.isPlugin || pane.exited || pane.held)
+            continue;
+        commands.push(pane.command && pane.command.trim() ? normalizeCommand(pane.command) : null);
+    }
+    return commands;
+}
+/** Does this session's live panes fit these server children one-to-one? */
+function sessionMatchesChildSets(session, childSets) {
+    return hasPerfectMatching(paneCommandsFor(session), childSets);
+}
+/**
+ * The direct child of `serverPid` on `pid`'s parent chain, or null when `pid`
+ * is not below the server. Every pane's shell is a direct child, so this maps
+ * each process to the pane that owns it.
+ */
+function owningChild(byPid, serverPid, pid) {
+    let current = pid;
+    let last = null;
+    for (let hops = 0; hops < MAX_ANCESTOR_HOPS; hops++) {
+        if (current === serverPid)
+            return last;
+        last = current;
+        const parent = byPid.get(current);
+        if (!parent || parent.ppid === current)
+            return null;
+        current = parent.ppid;
+    }
+    return null;
+}
+/**
+ * Candidate commands for each direct child of the server: the child's own argv
+ * plus every descendant's (Zellij's `pane_command` may be the pane's shell or
+ * a foreground process below it). One set per child, in child order.
+ */
+function childCommandSets(serverPid, table) {
+    const byPid = new Map(table.map((proc) => [proc.pid, proc]));
+    const childIndex = new Map();
+    let order = 0;
+    for (const proc of table) {
+        if (proc.pid === serverPid || proc.ppid !== serverPid)
+            continue;
+        childIndex.set(proc.pid, order++);
+    }
+    const sets = Array.from({ length: childIndex.size }, () => new Set());
+    for (const proc of table) {
+        const child = owningChild(byPid, serverPid, proc.pid);
+        if (child === null)
+            continue;
+        const index = childIndex.get(child);
+        if (index === undefined)
+            continue;
+        sets[index].add(normalizeCommand(proc.args));
+    }
+    return sets;
+}
+/**
+ * Can every pane take a distinct direct child (augmenting paths; pane counts
+ * are small)? An empty pane command accepts any child, and equal commands
+ * still need different children — duplicates are counted, not collapsed.
+ */
+function hasPerfectMatching(paneCommands, childSets) {
+    if (paneCommands.length === 0 || paneCommands.length !== childSets.length)
+        return false;
+    const childTakenBy = new Array(childSets.length).fill(-1);
+    const augment = (pane, seen) => {
+        const command = paneCommands[pane];
+        for (let child = 0; child < childSets.length; child++) {
+            if (seen[child])
+                continue;
+            if (command !== null && !childSets[child].has(command))
+                continue;
+            seen[child] = true;
+            const owner = childTakenBy[child];
+            if (owner === -1 || augment(owner, seen)) {
+                childTakenBy[child] = pane;
+                return true;
+            }
+        }
+        return false;
+    };
+    for (let pane = 0; pane < paneCommands.length; pane++) {
+        if (!augment(pane, new Array(childSets.length).fill(false)))
+            return false;
+    }
+    return true;
+}
+/**
+ * Pick the one live session whose panes belong to `serverPid`.
+ *
+ * The server's direct children are its panes' processes. A session matches
+ * when it has exactly as many non-plugin, non-exited, non-held panes as the
+ * server has direct children, and the panes can be assigned one-to-one to
+ * distinct children whose subtree argv (child plus descendants) contains the
+ * pane's command. With `opts.paneId`, the session must also contain that
+ * pane. Zero or several matches return null — this never guesses.
+ */
+export function matchServerToSession(serverPid, table, sessions, opts = {}) {
+    const childSets = childCommandSets(serverPid, table);
+    const matches = [];
+    for (const session of sessions) {
+        if (opts.paneId && !session.panes.some((pane) => paneMatchesId(pane, opts.paneId))) {
+            continue;
+        }
+        if (!sessionMatchesChildSets(session, childSets))
+            continue;
+        matches.push(session.name);
+    }
+    return matches.length === 1 ? matches[0] : null;
+}
+/**
+ * Pair live servers with live sessions using forced assignments only:
+ *
+ * 1. A server whose creation name is a live session name is pinned to it when
+ *    that session fits. A creation name shared by two fitting servers (name
+ *    reuse) is a guess, so neither is pinned and the session stays unassigned.
+ * 2. Repeat until stable: an unpinned server with exactly one unpinned fitting
+ *    session is pinned to it, and an unpinned session fitted by exactly one
+ *    unpinned server pins that pair. Nothing else: no backtracking, no
+ *    picking among ties.
+ *
+ * Returns only the pinned pairs. Servers and sessions left ambiguous are
+ * absent; the caller still has the pane-id-filtered single-match test.
+ */
+export function assignServersToSessions(table, sessions) {
+    const servers = liveServers(table);
+    const childSetsByServer = new Map();
+    for (const server of servers) {
+        childSetsByServer.set(server.pid, childCommandSets(server.pid, table));
+    }
+    const fits = (serverPid, session) => sessionMatchesChildSets(session, childSetsByServer.get(serverPid) ?? []);
+    const assigned = new Map();
+    const takenSessions = new Set();
+    // A reused name fitted by two servers cannot be told apart; never assign it.
+    const contestedSessions = new Set();
+    // 1. Creation-name pins.
+    const serversByCreation = new Map();
+    for (const server of servers) {
+        const group = serversByCreation.get(server.creationName) ?? [];
+        group.push(server);
+        serversByCreation.set(server.creationName, group);
+    }
+    const sessionByName = new Map(sessions.map((session) => [session.name, session]));
+    for (const [creationName, group] of serversByCreation) {
+        const session = sessionByName.get(creationName);
+        if (!session)
+            continue;
+        const fitting = group.filter((server) => fits(server.pid, session));
+        if (fitting.length === 1) {
+            assigned.set(fitting[0].pid, creationName);
+            takenSessions.add(creationName);
+        }
+        else if (fitting.length > 1) {
+            contestedSessions.add(creationName);
+        }
+    }
+    // 2. Propagation of single remaining candidates.
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const server of servers) {
+            if (assigned.has(server.pid))
+                continue;
+            const candidates = sessions.filter((session) => !takenSessions.has(session.name) &&
+                !contestedSessions.has(session.name) &&
+                fits(server.pid, session));
+            if (candidates.length === 1) {
+                assigned.set(server.pid, candidates[0].name);
+                takenSessions.add(candidates[0].name);
+                changed = true;
+            }
+        }
+        for (const session of sessions) {
+            if (takenSessions.has(session.name) || contestedSessions.has(session.name))
+                continue;
+            const candidates = servers.filter((server) => !assigned.has(server.pid) && fits(server.pid, session));
+            if (candidates.length === 1) {
+                assigned.set(candidates[0].pid, session.name);
+                takenSessions.add(session.name);
+                changed = true;
+            }
+        }
+    }
+    return assigned;
+}

package/dist/zellij/session.d.ts

@@ -1,6 +1,8 @@
 export type ZellijSessionResolve = {
     session: string;
-    source: "arg" | "env_zswarm" | "env_zellij" | "sole_live";
+    source: "arg" | "env_zswarm" | "env_zellij" | "sole_live" | "alias" | "renamed";
+    /** The name the caller asked for, when resolution changed it (alias/renamed). */
+    requested?: string;
 };
 /** One row from `zellij list-sessions --no-formatting` (not `--short`). */
 export type ZellijSession = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zswarm/core",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "type": "module",
   "description": "zSwarm Zellij client and shared ops dispatch",
   "exports": {