@zswarm/core 0.1.7 → 0.1.9

package/dist/zellij/binary.d.ts

@@ -1,9 +1,16 @@
+import { ZellijError } from "../errors.js";
 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;
+/** Where a missing/wrong-Zellij failure was produced. */
+export type ZellijFailureOrigin = "local_spawn" | "local_preflight" | "remote";
 export declare const DEFAULT_TIMEOUT_MS = 15000;
 export { NOT_FOUND_EXIT };
+/** Local Node spawn failure vs a process that actually started. */
+export declare function originFromExecResult(result: ExecResult): Exclude<ZellijFailureOrigin, "local_preflight">;
+export declare function zellijExecDetails(result: ExecResult): Record<string, unknown>;
+export declare function zellijMissingError(zellijPath: string, result: ExecResult): ZellijError;
 /** Expand a leading `~/` or `~\` using USERPROFILE/HOME. */
 export declare function expandHomePath(input: string, env?: NodeJS.ProcessEnv): string;
 /**

package/dist/zellij/binary.js

@@ -7,6 +7,19 @@ import { applyIpcTmpEnv } from "./ipc.js";
 export { createSshExec };
 export const DEFAULT_TIMEOUT_MS = 15_000;
 export { NOT_FOUND_EXIT };
+/** Local Node spawn failure vs a process that actually started. */
+export function originFromExecResult(result) {
+    return result.spawn?.origin === "local" ? "local_spawn" : "remote";
+}
+export function zellijExecDetails(result) {
+    const origin = originFromExecResult(result);
+    return result.spawn
+        ? { origin, spawn: { origin: result.spawn.origin, errno: result.spawn.errno, bin: result.spawn.bin } }
+        : { origin };
+}
+export function zellijMissingError(zellijPath, result) {
+    return new ZellijError("zellij_missing", `zellij binary not found (${zellijPath}); install Zellij ≥ 0.42, add it to PATH, or set ZSWARM_BIN / ZSWARM_PATH`, zellijExecDetails(result));
+}
 /** Expand a leading `~/` or `~\` using USERPROFILE/HOME. */
 export function expandHomePath(input, env = process.env) {
     const trimmed = input.trim();
@@ -51,7 +64,7 @@ export function looksLikeZswarmBinary(path) {
 export function assertZellijBinaryPath(path) {
     if (!looksLikeZswarmBinary(path))
         return;
-    throw new ZellijError("zellij_wrong_bin", `ZSWARM_BIN/ZSWARM_PATH points at zswarm (${path}), not Zellij. Set it to the zellij binary (e.g. ~/.local/bin/zellij)`);
+    throw new ZellijError("zellij_wrong_bin", `ZSWARM_BIN/ZSWARM_PATH points at zswarm (${path}), not Zellij. Set it to the zellij binary (e.g. ~/.local/bin/zellij)`, { origin: "local_preflight", bin: path });
 }
 /**
  * ZSWARM_SSH is a destination, not a full ssh argv.
@@ -127,10 +140,10 @@ export async function ensureZellijIdentity(exec, zellijPath, timeoutMs = 3_000,
     });
     const text = `${result.stdout}\n${result.stderr}`;
     if (/usage:\s*zswarm/i.test(text) || /unknown arg:/i.test(text)) {
-        throw new ZellijError("zellij_wrong_bin", `resolved binary is zswarm, not Zellij (${zellijPath}). Set ZSWARM_BIN to the zellij executable`);
+        throw new ZellijError("zellij_wrong_bin", `resolved binary is zswarm, not Zellij (${zellijPath}). Set ZSWARM_BIN to the zellij executable`, zellijExecDetails(result));
     }
     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`);
+        throw zellijMissingError(zellijPath, result);
     }
     if (result.code === 0) {
         if (signal?.aborted)
@@ -139,7 +152,7 @@ export async function ensureZellijIdentity(exec, zellijPath, timeoutMs = 3_000,
             identityCache.add(cacheKey);
             return true;
         }
-        throw new ZellijError("zellij_wrong_bin", `resolved binary is not Zellij (${zellijPath}); --version returned: ${result.stdout.trim() || result.stderr.trim() || "empty"}`);
+        throw new ZellijError("zellij_wrong_bin", `resolved binary is not Zellij (${zellijPath}); --version returned: ${result.stdout.trim() || result.stderr.trim() || "empty"}`, zellijExecDetails(result));
     }
     // Timeout / transport failure: leave unresolved so a later call retries.
     return false;
@@ -161,10 +174,10 @@ export async function ensureZellijCapabilities(exec, zellijPath, timeoutMs = 3_0
     });
     const text = `${result.stdout}\n${result.stderr}`;
     if (/usage:\s*zswarm/i.test(text)) {
-        throw new ZellijError("zellij_wrong_bin", `resolved binary is zswarm, not Zellij (${zellijPath})`);
+        throw new ZellijError("zellij_wrong_bin", `resolved binary is zswarm, not Zellij (${zellijPath})`, zellijExecDetails(result));
     }
     if (result.code === NOT_FOUND_EXIT) {
-        throw new ZellijError("zellij_missing", `zellij binary not found (${zellijPath})`);
+        throw zellijMissingError(zellijPath, result);
     }
     // Require the flags this client always passes.
     if (result.code === 0 &&
@@ -176,7 +189,7 @@ export async function ensureZellijCapabilities(exec, zellijPath, timeoutMs = 3_0
         return true;
     }
     if (result.code === 0) {
-        throw new ZellijError("zellij_incompatible", `Zellij at ${zellijPath} does not advertise list-sessions --no-formatting; upgrade Zellij (≥ 0.42) or zswarm`);
+        throw new ZellijError("zellij_incompatible", `Zellij at ${zellijPath} does not advertise list-sessions --no-formatting; upgrade Zellij (≥ 0.42) or zswarm`, zellijExecDetails(result));
     }
     // Soft: leave unresolved on transport failure.
     return false;

package/dist/zellij/client.js

@@ -4,7 +4,7 @@ import { buildClosePaneArgs, buildDumpArgs, buildDumpLayoutArgs, buildFocusPaneA
 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, ensureZellijProbes, identityCacheKey, resolveSshTarget, resolveZellijBinary, sanitizeZellijEnv, } from "./binary.js";
+import { DEFAULT_TIMEOUT_MS, NOT_FOUND_EXIT, defaultExec, ensureZellijProbes, identityCacheKey, resolveSshTarget, resolveZellijBinary, sanitizeZellijEnv, zellijExecDetails, zellijMissingError, } from "./binary.js";
 import { normalizePaneId, parsePaneList, resolvePane, } from "./panes.js";
 import { isZellijNoSessionsOutput, parseSessionList, resolveSelfPaneId, sessionFromEnv, sessionFromList, } from "./session.js";
 /** Zellij wrapper with bounded caches of completed discovery observations. */
@@ -119,14 +119,14 @@ export function createZellijClient(options = {}) {
         await ensureIdentity(remaining);
         const result = await exec(args, { 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`);
+            throw zellijMissingError(zellijPath, result);
         }
         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}`);
+                throw new ZellijError("zellij_wrong_bin", `resolved binary looks like zswarm, not Zellij (${zellijPath}): ${detail}`, zellijExecDetails(result));
             }
-            throw new ZellijError("zellij_failed", `${label} failed (exit ${result.code}): ${detail}`);
+            throw new ZellijError("zellij_failed", `${label} failed (exit ${result.code}): ${detail}`, zellijExecDetails(result));
         }
         return result;
     }
@@ -159,16 +159,16 @@ export function createZellijClient(options = {}) {
                 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`);
+                throw zellijMissingError(zellijPath, result);
             }
             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}`);
+                    throw new ZellijError("zellij_wrong_bin", `resolved binary looks like zswarm, not Zellij (${zellijPath}): ${detail}`, zellijExecDetails(result));
                 }
                 if (isZellijNoSessionsOutput(result.stdout, result.stderr))
                     return [];
-                throw new ZellijError("zellij_failed", `zellij list-sessions failed (exit ${result.code}): ${detail}`);
+                throw new ZellijError("zellij_failed", `zellij list-sessions failed (exit ${result.code}): ${detail}`, zellijExecDetails(result));
             }
             return parseSessionList(result.stdout);
         });

package/package.json

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