@zswarm/core 0.1.6 → 0.1.7

package/dist/zellij/client.js

@@ -1,12 +1,13 @@
 import { ZellijError } from "../errors.js";
+import { ListingCache, executorIdentity, listingTtl, routingEnvironment, sharedListings } from "./cache.js";
 import { buildClosePaneArgs, buildDumpArgs, buildDumpLayoutArgs, buildFocusPaneArgs, buildLaunchPluginArgs, buildListPanesArgs, buildListTabsArgs, buildNewPaneArgs, buildNewTabArgs, buildPasteArgs, buildPipeArgs, buildRenamePaneArgs, buildRenameTabArgs, buildSendEnterArgs, buildSendKeysArgs, buildStackPanesArgs, buildWriteCharsArgs, changedPayload, scrollbackPayload, waitPayload, } from "./args.js";
 import { DEFAULT_BUS_TIMEOUT_MS, parseBusReply, parseChangedReply, parseScrollbackReply, parseWaitReply, } from "./bus.js";
 import { parseTabList, resolveTab } from "./tabs.js";
 import { createSshExec } from "../exec.js";
-import { DEFAULT_TIMEOUT_MS, NOT_FOUND_EXIT, defaultExec, ensureZellijCapabilities, ensureZellijIdentity, identityCacheKey, resolveSshTarget, resolveZellijBinary, sanitizeZellijEnv, } from "./binary.js";
+import { DEFAULT_TIMEOUT_MS, NOT_FOUND_EXIT, defaultExec, ensureZellijProbes, identityCacheKey, resolveSshTarget, resolveZellijBinary, sanitizeZellijEnv, } from "./binary.js";
 import { normalizePaneId, parsePaneList, resolvePane, } from "./panes.js";
 import { isZellijNoSessionsOutput, parseSessionList, resolveSelfPaneId, sessionFromEnv, sessionFromList, } from "./session.js";
-/** Thin, stateless wrapper over the `zellij` binary. */
+/** Zellij wrapper with bounded caches of completed discovery observations. */
 export function createZellijClient(options = {}) {
     const env = options.env ?? process.env;
     // A remote crew never resolves a local binary. An injected exec is a unit
@@ -21,13 +22,56 @@ export function createZellijClient(options = {}) {
                 : resolveZellijBinary(env));
     const sshExec = options.exec || !ssh
         ? null
-        : createSshExec(ssh, sanitizeZellijEnv(env));
+        : createSshExec(ssh, sanitizeZellijEnv(env), { pinIpc: true });
     const rawExec = options.exec ??
         (sshExec ? sshExec : defaultExec(zellijPath, env));
     const exec = (args, opts) => rawExec(args, { ...opts, signal: opts.signal ?? options.signal });
     const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const selfPaneId = resolveSelfPaneId(env);
-    const probeKey = identityCacheKey(zellijPath, ssh);
+    const probeKey = JSON.stringify([identityCacheKey(zellijPath, ssh), routingEnvironment(env)]);
+    const now = options.now ?? Date.now;
+    const cache = options.cache instanceof ListingCache ? options.cache : sharedListings;
+    const ttl = options.cache === false || (options.exec && !options.cache) ? 0 : listingTtl(env);
+    const baseContext = JSON.stringify([zellijPath, ssh, executorIdentity(options.exec), routingEnvironment(env)]);
+    const scopeFor = (session) => JSON.stringify([baseContext, session ?? null]);
+    const contextKey = () => JSON.stringify([baseContext, readTransport().ipc ?? null]);
+    const cacheUsable = () => {
+        const ipc = readTransport().ipc;
+        return ttl > 0 && (ipc?.requested?.toLowerCase() !== "auto" || ipc.status === "resolved");
+    };
+    function invalidateListings(session) {
+        cache.invalidate(scopeFor(session));
+        cache.invalidate(scopeFor());
+    }
+    function observeManifest(session, revision) {
+        if (cache.observe(scopeFor(session), revision))
+            cache.invalidate(scopeFor());
+    }
+    async function listing(kind, session, budget, fresh, read) {
+        const remaining = operationBudget(budget, `zellij ${kind}`);
+        remaining(); // An aborted/expired caller cannot consume a cached value.
+        // Resolve auto IPC before selecting the namespace, including cold reads.
+        // A sibling can refresh discovery while this read is in flight, so keep
+        // the original namespace and refuse to cache under a different one later.
+        if (ssh?.tmp?.trim().toLowerCase() === "auto") {
+            await sshExec.prepareIpc(remaining(), options.signal);
+            remaining();
+        }
+        const key = () => JSON.stringify([contextKey(), session ?? null, kind]);
+        const startedKey = key();
+        if (cacheUsable() && !fresh) {
+            const hit = cache.get(startedKey, now());
+            if (hit !== undefined)
+                return hit;
+        }
+        const scope = scopeFor(session);
+        const ticket = cache.begin(scope);
+        const value = await read(remaining);
+        remaining();
+        if (cacheUsable() && key() === startedKey)
+            cache.put(startedKey, scope, ticket, value, ttl, now());
+        return value;
+    }
     function readTransport() {
         if (!ssh)
             return { kind: "local", mode: "local" };
@@ -66,10 +110,11 @@ export function createZellijClient(options = {}) {
             return;
         // Only the helpers' positively verified results are cached. In-flight or
         // unresolved probes must not tie this call to another operation's budget.
-        await ensureZellijIdentity(exec, zellijPath, remaining(), probeKey);
-        await ensureZellijCapabilities(exec, zellijPath, remaining(), probeKey);
+        if (sshExec?.prepareIpc)
+            await sshExec.prepareIpc(remaining(), options.signal);
+        await ensureZellijProbes(exec, zellijPath, remaining(), probeKey, options.signal);
     }
-    async function run(args, label, callTimeoutMs = timeoutMs) {
+    async function runCommand(args, label, callTimeoutMs = timeoutMs) {
         const remaining = operationBudget(callTimeoutMs, label);
         await ensureIdentity(remaining);
         const result = await exec(args, { timeoutMs: remaining() });
@@ -85,34 +130,58 @@ export function createZellijClient(options = {}) {
         }
         return result;
     }
-    async function listSessions(callTimeoutMs = timeoutMs) {
-        const remaining = operationBudget(callTimeoutMs, "zellij list-sessions");
-        await ensureIdentity(remaining);
-        // Keep annotations (EXITED / current); --short drops them.
-        const result = await exec(["list-sessions", "--no-formatting"], {
-            timeoutMs: remaining(),
-        });
-        if (result.code === NOT_FOUND_EXIT) {
-            throw new ZellijError("zellij_missing", `zellij binary not found (${zellijPath}); install Zellij ≥ 0.42, add it to PATH, or set ZSWARM_BIN / ZSWARM_PATH`);
+    const mutations = new Set([
+        "new-pane", "new-tab", "close-pane", "rename-pane", "rename-tab-by-id",
+        "focus-pane-id", "stack-panes", "launch-or-focus-plugin", "paste", "send-keys", "write-chars",
+    ]);
+    async function run(args, label, callTimeoutMs = timeoutMs) {
+        const action = args[args.indexOf("action") + 1];
+        const index = args.indexOf("--session");
+        const session = index >= 0 ? args[index + 1] : undefined;
+        const mutation = session && mutations.has(action ?? "");
+        if (mutation)
+            invalidateListings(session);
+        try {
+            return await runCommand(args, label, callTimeoutMs);
         }
-        if (result.code !== 0) {
-            const detail = result.stderr.trim() || result.stdout.trim() || "no output";
-            if (/usage:\s*zswarm/i.test(detail) || /unknown arg:/i.test(detail)) {
-                throw new ZellijError("zellij_wrong_bin", `resolved binary looks like zswarm, not Zellij (${zellijPath}): ${detail}`);
-            }
-            if (isZellijNoSessionsOutput(result.stdout, result.stderr))
-                return [];
-            throw new ZellijError("zellij_failed", `zellij list-sessions failed (exit ${result.code}): ${detail}`);
+        finally {
+            // Failed/uncertain writes can still have reached Zellij. Drop both reads
+            // from before the write and reads that raced while it was in flight.
+            if (mutation)
+                invalidateListings(session);
         }
-        return parseSessionList(result.stdout);
+    }
+    async function listSessions(callTimeoutMs = timeoutMs, opts = {}) {
+        return listing("list-sessions", undefined, callTimeoutMs, opts.fresh === true, async (remaining) => {
+            await ensureIdentity(remaining);
+            // Keep annotations (EXITED / current); --short drops them.
+            const result = await exec(["list-sessions", "--no-formatting"], {
+                timeoutMs: remaining(),
+            });
+            if (result.code === NOT_FOUND_EXIT) {
+                throw new ZellijError("zellij_missing", `zellij binary not found (${zellijPath}); install Zellij ≥ 0.42, add it to PATH, or set ZSWARM_BIN / ZSWARM_PATH`);
+            }
+            if (result.code !== 0) {
+                const detail = result.stderr.trim() || result.stdout.trim() || "no output";
+                if (/usage:\s*zswarm/i.test(detail) || /unknown arg:/i.test(detail)) {
+                    throw new ZellijError("zellij_wrong_bin", `resolved binary looks like zswarm, not Zellij (${zellijPath}): ${detail}`);
+                }
+                if (isZellijNoSessionsOutput(result.stdout, result.stderr))
+                    return [];
+                throw new ZellijError("zellij_failed", `zellij list-sessions failed (exit ${result.code}): ${detail}`);
+            }
+            return parseSessionList(result.stdout);
+        });
     }
     async function resolveSession(explicit, callTimeoutMs = timeoutMs) {
         return (sessionFromEnv(env, explicit) ??
             sessionFromList(await listSessions(callTimeoutMs)));
     }
-    async function listPanes(session, callTimeoutMs = timeoutMs) {
-        const result = await run(buildListPanesArgs(session), "zellij action list-panes", callTimeoutMs);
-        return parsePaneList(result.stdout);
+    async function listPanes(session, callTimeoutMs = timeoutMs, opts = {}) {
+        return listing("list-panes", session, callTimeoutMs, opts.fresh === true, async (remaining) => {
+            const result = await run(buildListPanesArgs(session), "zellij action list-panes", remaining());
+            return parsePaneList(result.stdout);
+        });
     }
     async function injectPane(input) {
         const paneId = normalizePaneId(input.paneId);
@@ -164,9 +233,11 @@ export function createZellijClient(options = {}) {
         await run(buildFocusPaneArgs(input.session, paneId), "zellij action focus-pane-id");
         return { paneId, session: input.session };
     }
-    async function listTabs(session, callTimeoutMs = timeoutMs) {
-        const result = await run(buildListTabsArgs(session), "zellij action list-tabs", callTimeoutMs);
-        return parseTabList(result.stdout);
+    async function listTabs(session, callTimeoutMs = timeoutMs, opts = {}) {
+        return listing("list-tabs", session, callTimeoutMs, opts.fresh === true, async (remaining) => {
+            const result = await run(buildListTabsArgs(session), "zellij action list-tabs", remaining());
+            return parseTabList(result.stdout);
+        });
     }
     async function dumpLayout(session) {
         const result = await run(buildDumpLayoutArgs(session), "zellij action dump-layout");
@@ -282,6 +353,9 @@ export function createZellijClient(options = {}) {
     return {
         zellijPath,
         selfPaneId,
+        contextKey,
+        invalidateListings,
+        observeManifest,
         get transport() {
             return readTransport();
         },

package/package.json

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