@zswarm/core 0.1.8 → 0.2.0

package/dist/host/host.js

@@ -0,0 +1,165 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { ZellijError } from "../errors.js";
+import { dispatchZswarm } from "../ops/dispatch.js";
+import { validateSshDestination } from "../zellij/binary.js";
+/**
+ * `zswarm host install` puts Node.js, zswarm and Zellij on a Linux or macOS
+ * host over SSH (or prints the script, for callers with their own root
+ * channel). `zswarm host doctor` checks a host: tools, disk, sessions and
+ * services over SSH, then serve, the session and its panes through the
+ * normal transport.
+ */
+export function hostScriptPath(name) {
+    return fileURLToPath(new URL(`../../assets/${name}`, import.meta.url));
+}
+export const defaultSsh = (dest, remoteCommand, stdin) => {
+    const res = spawnSync("ssh", ["-o", "BatchMode=yes", dest, ...remoteCommand], {
+        input: stdin,
+        encoding: "utf8",
+        timeout: 600_000,
+        maxBuffer: 16 * 1024 * 1024,
+    });
+    return { status: res.status ?? 255, stdout: res.stdout ?? "", stderr: res.stderr ?? (res.error?.message ?? "") };
+};
+/** Single-quote for the remote POSIX shell. */
+function shq(word) {
+    return /^[A-Za-z0-9_@%+=:,./-]+$/.test(word) ? word : `'${word.replace(/'/g, "'\\''")}'`;
+}
+export function hostInstallArgs(input) {
+    const args = [];
+    if (input.prefix)
+        args.push("--prefix", input.prefix);
+    if (input.binDir)
+        args.push("--bin-dir", input.binDir);
+    if (input.node)
+        args.push("--node", input.node);
+    if (input.zellij)
+        args.push("--zellij", input.zellij);
+    // Unpinned, the script installs the latest published zswarm.
+    if (input.zswarm)
+        args.push("--zswarm", input.zswarm);
+    return args;
+}
+export function hostInstall(input) {
+    if (!input.ssh)
+        throw new ZellijError("usage", "host install needs --ssh <destination> (or --script to print the script)");
+    const dest = validateSshDestination(input.ssh);
+    const script = readFileSync(hostScriptPath("host-install.sh"), "utf8");
+    const remote = [...(input.sudo ? ["sudo", "-n"] : []), "sh", "-s", "--", ...hostInstallArgs(input).map(shq)];
+    const res = (input.run ?? defaultSsh)(dest, remote, script);
+    if (res.status !== 0) {
+        throw new ZellijError("failed", `host install on ${dest} failed (exit ${res.status})`, {
+            stdout: res.stdout.slice(-2000),
+            stderr: res.stderr.slice(-2000),
+        });
+    }
+    const steps = {};
+    for (const line of res.stdout.split("\n")) {
+        const m = /^(\S+)\s+(.+)$/.exec(line.trim());
+        if (m)
+            steps[m[1]] = m[2];
+    }
+    return { steps, output: res.stdout };
+}
+/** KEY=VALUE lines from host-report.sh; `service=` lines are collected. */
+export function parseHostReport(text) {
+    const facts = {};
+    const services = [];
+    for (const line of text.split("\n")) {
+        const i = line.indexOf("=");
+        if (i <= 0)
+            continue;
+        const key = line.slice(0, i).trim();
+        const value = line.slice(i + 1).trim();
+        if (key === "service")
+            services.push(value);
+        else
+            facts[key] = value;
+    }
+    return { facts, services };
+}
+export function hostChecks(facts, services, session) {
+    const checks = [];
+    const tool = (id, required, hint) => {
+        const v = facts[id];
+        checks.push(v ? { id, state: "pass", detail: v } : { id, state: required ? "fail" : "warn", detail: `missing; ${hint}` });
+    };
+    tool("node", true, "zswarm host install");
+    tool("zswarm", true, "zswarm host install");
+    tool("zellij", true, "zswarm host install");
+    tool("python3", false, "zswarm slot needs Python 3.9+");
+    for (const id of ["disk_home_gb", "disk_tmp_gb"]) {
+        const gb = Number(facts[id]);
+        if (!Number.isFinite(gb) || facts[id] === "")
+            continue;
+        checks.push({ id, state: gb < 5 ? "fail" : gb < 15 ? "warn" : "pass", detail: `${gb} GB free` });
+    }
+    if (facts.os === "Linux" && services.length > 0) {
+        checks.push({
+            id: "linger",
+            state: facts.linger === "yes" ? "pass" : "fail",
+            detail: facts.linger === "yes" ? "on" : `off: services stop at logout (sudo loginctl enable-linger ${facts.user ?? "<user>"})`,
+        });
+    }
+    for (const svc of services) {
+        // Linux: "<unit> <active> <sub>"; macOS: "<label> pid=<pid|-> last=<code>".
+        const failed = /\sfailed\b/.test(svc) || (/last=(\d+)/.exec(svc)?.[1] ?? "0") !== "0";
+        checks.push({ id: `service ${svc.split(" ")[0]}`, state: failed ? "fail" : "pass", detail: svc });
+    }
+    if (session) {
+        const live = (facts.sessions ?? "").split(/\s+/).includes(session);
+        checks.push({ id: `session ${session}`, state: live ? "pass" : "fail", detail: live ? "live" : "not running (zswarm crew status)" });
+    }
+    return checks;
+}
+export async function hostDoctor(input) {
+    const env = input.env ?? process.env;
+    const checks = [];
+    let facts;
+    if (input.ssh) {
+        const dest = validateSshDestination(input.ssh);
+        const script = readFileSync(hostScriptPath("host-report.sh"), "utf8");
+        const res = (input.run ?? defaultSsh)(dest, ["sh", "-s", "--", ...(input.session ? [shq(input.session)] : [])], script);
+        if (res.status !== 0) {
+            checks.push({ id: "ssh", state: "fail", detail: `ssh ${dest} failed (exit ${res.status}): ${res.stderr.trim().slice(0, 200)}` });
+        }
+        else {
+            checks.push({ id: "ssh", state: "pass", detail: dest });
+            const parsed = parseHostReport(res.stdout);
+            facts = parsed.facts;
+            checks.push(...hostChecks(parsed.facts, parsed.services, input.session));
+        }
+    }
+    let transport;
+    const serve = input.serve?.trim() || env.ZSWARM_SERVE?.trim();
+    if (serve) {
+        const call = input.call ?? ((args, e) => dispatchZswarm(args, undefined, { env: e }));
+        const remote = { ...env, ZSWARM_SERVE: serve, ZSWARM_BUS: "0" };
+        const doctorArgs = { op: "doctor" };
+        if (input.session)
+            doctorArgs.session = input.session;
+        const doctor = await call(doctorArgs, remote);
+        transport = doctor.ok ? doctor.data : doctor.error;
+        checks.push({ id: "serve doctor", state: doctor.ok ? "pass" : "fail", detail: doctor.ok ? serve : `${doctor.error.code}: ${doctor.error.message.slice(0, 200)}` });
+        if (doctor.ok && input.session) {
+            const listed = await call({ op: "list", session: input.session }, remote);
+            if (listed.ok) {
+                const panes = listed.data.panes ?? [];
+                const dead = panes.filter((p) => p.exited).map((p) => p.title ?? "?");
+                checks.push({
+                    id: "panes",
+                    state: panes.length === 0 || dead.length > 0 ? "fail" : "pass",
+                    detail: dead.length ? `exited: ${dead.join(", ")}` : `${panes.length} alive`,
+                });
+            }
+            else {
+                checks.push({ id: "panes", state: "fail", detail: `${listed.error.code}: ${listed.error.message.slice(0, 200)}` });
+            }
+        }
+    }
+    if (!input.ssh && !serve)
+        throw new ZellijError("usage", "host doctor needs --ssh <destination> and/or --serve <target>");
+    return { ok: checks.every((c) => c.state !== "fail"), checks, facts, transport };
+}

package/dist/host/relay.d.ts

@@ -0,0 +1,116 @@
+import type { OpsResult } from "../ops/types.js";
+/**
+ * `zswarm relay`: hand a body to a pane on another host and tell a local pane
+ * when the work is done, without anyone polling.
+ *
+ * The calling process sends the body and returns. A detached relay (a launchd
+ * job on macOS, a transient systemd user unit on Linux, a detached process
+ * elsewhere) then waits over serve for the `--done` regex on the target
+ * pane's screen, optionally confirms with a check script, and pastes a
+ * message into the `--reply-to` pane, retrying with backoff; a message that
+ * never lands is left in relays/undelivered/<id>.txt.
+ *
+ * A relay runs from its own directory, ~/.zswarm/relays/<id>-<ts>/: config.json
+ * (mode 600, with a copy of the serve token that is deleted when the relay
+ * ends), a snapshot of the check script and message template, relay.log and
+ * message.txt. It reads nothing else, so moving or updating the caller's files
+ * while it waits cannot break it.
+ */
+export type RelayStatus = "DONE" | "TIMEOUT" | "PANE_DIED" | "SERVE_DOWN" | "UNCONFIRMED";
+export type RelayConfig = {
+    id: string;
+    serve: string;
+    token?: string;
+    session?: string;
+    to: string;
+    done: string;
+    replyTo: string;
+    replySession?: string;
+    from: string;
+    timeoutMin: number;
+    check?: string;
+    message?: string;
+    /**
+     * Screen lines that already matched `done` when the relay started (the
+     * pasted body, an earlier task's done line). Only a line beyond these counts.
+     */
+    seen?: string[];
+};
+export type RelayDeps = {
+    /** dispatchZswarm with an env; injected in tests. */
+    call?: (args: Record<string, unknown>, env: NodeJS.ProcessEnv) => Promise<OpsResult>;
+    /** Runs the check script: exit status and stdout. */
+    runCheck?: (script: string, env: NodeJS.ProcessEnv) => {
+        status: number;
+        stdout: string;
+    };
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    log?: (line: string) => void;
+    env?: NodeJS.ProcessEnv;
+    /** Delivery retry delays in seconds (ZSWARM_RELAY_DELAYS). */
+    delays?: number[];
+};
+export declare function relaysDir(env?: NodeJS.ProcessEnv): string;
+/** Lines of `screen` that match the done regex, as the relay compares them. */
+export declare function doneLines(screen: string, done: string): string[];
+/**
+ * The first done line in `screen` that is not accounted for by `seen`,
+ * counting repeats: a line seen once still counts when it shows up twice.
+ * A regex that only matches across lines cannot be baselined; its match counts.
+ */
+export declare function freshDoneLine(screen: string, done: string, seen?: readonly string[]): string | null;
+/** Fill {id} {status} {note} {match} {output} {pane} in a message template. */
+export declare function fillMessage(template: string, fields: Record<string, string>): string;
+/** Paste `body` into the reply pane, retrying with backoff; false leaves it in undelivered/. */
+export declare function deliverMessage(cfg: RelayConfig, body: string, dir: string, deps?: RelayDeps): Promise<boolean>;
+/** The waiting loop; returns the final status and the message it delivered or left behind. */
+export declare function relayLoop(dir: string, deps?: RelayDeps): Promise<{
+    status: RelayStatus;
+    delivered: boolean;
+}>;
+export type RelayStartInput = {
+    id?: string;
+    serve?: string;
+    session?: string;
+    to: string;
+    bodyFile?: string;
+    from?: string;
+    done: string;
+    replyTo: string;
+    replySession?: string;
+    check?: string;
+    message?: string;
+    timeoutMin?: number;
+    foreground?: boolean;
+    env?: NodeJS.ProcessEnv;
+    deps?: RelayDeps;
+    /** Starts the detached relay; injected in tests. */
+    launch?: (dir: string, env: NodeJS.ProcessEnv) => string;
+};
+/** Write the relay directory: config (600), snapshots of the check and template. */
+export declare function prepareRelay(cfg: RelayConfig, sources: {
+    check?: string;
+    message?: string;
+}, env: NodeJS.ProcessEnv): string;
+/** Remove the token copy once the relay no longer needs it. */
+export declare function scrubRelayToken(dir: string): void;
+/** Start the detached relay so it outlives the caller (and the caller's process group). */
+export declare function launchRelay(dir: string, env?: NodeJS.ProcessEnv): string;
+/** Send the body now, then leave a relay waiting for the done line. */
+export declare function startRelay(input: RelayStartInput): Promise<Record<string, unknown>>;
+/** What `zswarm relay --run <dir>` does inside the detached job. */
+export declare function runRelayDir(dir: string, deps?: RelayDeps): Promise<number>;
+/**
+ * The pull path: block until relay `id` has its final message (delivered or
+ * not) and return it. Needs no paste, so a busy Zellij cannot lose it.
+ */
+export declare function waitForRelay(id: string, opts?: {
+    timeoutMin?: number;
+    pollMs?: number;
+    env?: NodeJS.ProcessEnv;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}): Promise<string | null>;
+/** Remove relay directories and undelivered messages older than `days`. */
+export declare function pruneRelays(days?: number, env?: NodeJS.ProcessEnv): string[];