@zswarm/core 0.1.8 → 0.2.0

package/dist/host/relay.js

@@ -0,0 +1,476 @@
+import { spawn, spawnSync } from "node:child_process";
+import { appendFileSync, chmodSync, copyFileSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { ZellijError } from "../errors.js";
+import { dispatchZswarm } from "../ops/dispatch.js";
+import { resolveServeCliLaunch } from "../ops/serve-install.js";
+import { defaultStateDir } from "../state.js";
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** Spread over about an hour: Zellij on a loaded machine can stall for minutes. */
+const DEFAULT_DELAYS = [0, 30, 60, 120, 300, 600, 900, 1500];
+/** Consecutive matches of the done regex without a passing check before UNCONFIRMED. */
+const CONFIRM_TRIES = 3;
+const SERVE_DOWN_TRIES = 3;
+/** A wait that only finds `seen` lines returns at once; poll no faster than this. */
+const STALE_MATCH_POLL_MS = 15_000;
+export function relaysDir(env = process.env) {
+    return join(defaultStateDir(env), "relays");
+}
+function writePrivate(path, text) {
+    writeFileSync(path, text, { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+function delaysFrom(env, given) {
+    if (given)
+        return given;
+    const raw = env.ZSWARM_RELAY_DELAYS?.trim();
+    if (!raw)
+        return DEFAULT_DELAYS;
+    const parsed = raw.split(",").map((x) => Number(x.trim()));
+    return parsed.every((n) => Number.isFinite(n) && n >= 0) ? parsed : DEFAULT_DELAYS;
+}
+function serveEnv(cfg, env) {
+    const out = { ...env, ZSWARM_SERVE: cfg.serve, ZSWARM_BUS: "0", ZSWARM_LOG: "0" };
+    if (cfg.token)
+        out.ZSWARM_SERVE_TOKEN = cfg.token;
+    delete out.ZSWARM_SSH;
+    return out;
+}
+function localEnv(env) {
+    const out = { ...env };
+    for (const key of ["ZSWARM_SERVE", "ZSWARM_SERVE_TOKEN", "ZSWARM_SSH"])
+        delete out[key];
+    return out;
+}
+function defaultRunCheck(script, env) {
+    const res = spawnSync(script, [], { env, encoding: "utf8", timeout: 120_000 });
+    return { status: res.status ?? 1, stdout: res.stdout ?? "" };
+}
+/** Lines of `screen` that match the done regex, as the relay compares them. */
+export function doneLines(screen, done) {
+    const re = new RegExp(done);
+    return screen.split("\n").map((line) => line.trimEnd()).filter((line) => re.test(line));
+}
+/**
+ * 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 function freshDoneLine(screen, done, seen = []) {
+    const lines = doneLines(screen, done);
+    if (lines.length === 0)
+        return new RegExp(done, "m").exec(screen)?.[0] ?? null;
+    const left = new Map();
+    for (const line of seen)
+        left.set(line, (left.get(line) ?? 0) + 1);
+    for (const line of lines) {
+        const n = left.get(line) ?? 0;
+        if (n === 0)
+            return line;
+        left.set(line, n - 1);
+    }
+    return null;
+}
+/** Fill {id} {status} {note} {match} {output} {pane} in a message template. */
+export function fillMessage(template, fields) {
+    return template.replace(/\{(id|status|note|match|output|pane)\}/g, (_m, key) => fields[key] ?? "");
+}
+const DEFAULT_TEMPLATE = "RELAY {id} STATUS {status} pane {pane}\n{output}{note}\n";
+const NOTES = {
+    TIMEOUT: "no done line or passing check before the deadline; dump the pane once, do not resend blindly.",
+    PANE_DIED: "the target pane is gone or exited; check the crew (zswarm crew status) before resending.",
+    SERVE_DOWN: "serve was unreachable for three checks in a row; run zswarm doctor against it.",
+    UNCONFIRMED: "the pane printed the done line but the check never passed; dump the pane once for the error.",
+};
+/** Paste `body` into the reply pane, retrying with backoff; false leaves it in undelivered/. */
+export async function deliverMessage(cfg, body, dir, deps = {}) {
+    const env = deps.env ?? process.env;
+    const call = deps.call ?? ((args, e) => dispatchZswarm(args, undefined, { env: e }));
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const log = deps.log ?? (() => { });
+    writeFileSync(join(dir, "message.txt"), body);
+    const delays = delaysFrom(env, deps.delays);
+    for (const [i, delay] of delays.entries()) {
+        await sleep(delay * 1000);
+        // Generous Zellij budgets: this runs exactly when the machine is busiest.
+        const args = {
+            op: "send", to: cfg.replyTo, body, from: cfg.from, fresh: true, settleMs: 800, observeMs: 30_000, timeoutMs: 60_000,
+        };
+        if (cfg.replySession)
+            args.session = cfg.replySession;
+        const res = await call(args, localEnv(env)).catch((err) => ({ ok: false, error: { code: "failed", message: String(err) } }));
+        if (res.ok) {
+            log(`message attempt ${i + 1}: delivered, submitted=${String(res.data?.submitted)}`);
+            return true;
+        }
+        log(`message attempt ${i + 1} failed: ${res.error.code}: ${res.error.message.slice(0, 200)}`);
+    }
+    const fallback = join(relaysDir(env), "undelivered");
+    mkdirSync(fallback, { recursive: true, mode: 0o700 });
+    writeFileSync(join(fallback, `${cfg.id}.txt`), body);
+    log(`message not delivered after ${delays.length} attempts; left in ${join(fallback, `${cfg.id}.txt`)}`);
+    return false;
+}
+/** The waiting loop; returns the final status and the message it delivered or left behind. */
+export async function relayLoop(dir, deps = {}) {
+    const env = deps.env ?? process.env;
+    const cfg = JSON.parse(readFileSync(join(dir, "config.json"), "utf8"));
+    const call = deps.call ?? ((args, e) => dispatchZswarm(args, undefined, { env: e }));
+    const runCheck = deps.runCheck ?? defaultRunCheck;
+    const now = deps.now ?? Date.now;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const log = deps.log ?? ((line) => appendFileSync(join(dir, "relay.log"), `${new Date().toISOString()} ${line}\n`));
+    const remote = serveEnv(cfg, env);
+    const check = cfg.check ? join(dir, cfg.check) : undefined;
+    const checkEnv = (status, match) => ({
+        ...localEnv(env),
+        ZSWARM_RELAY_ID: cfg.id,
+        ZSWARM_RELAY_STATUS: status,
+        ZSWARM_RELAY_MATCH: match,
+        ZSWARM_RELAY_PANE: cfg.to,
+        ZSWARM_RELAY_DIR: dir,
+    });
+    const deadline = now() + cfg.timeoutMin * 60_000;
+    let status = "TIMEOUT";
+    let output = "";
+    let match = "";
+    let confirmTries = 0;
+    let serveDown = 0;
+    log(`relay start id=${cfg.id} to=${cfg.to} serve=${cfg.serve} done=${cfg.done}`);
+    while (now() < deadline) {
+        const started = now();
+        const chunk = Math.floor(Math.min(600_000, Math.max(5_000, deadline - now())));
+        const args = { op: "wait", to: cfg.to, for: "match", regex: true, match: cfg.done, timeoutMs: chunk, max: 3000 };
+        if (cfg.session)
+            args.session = cfg.session;
+        const res = await call(args, remote).catch((err) => ({ ok: false, error: { code: "failed", message: String(err) } }));
+        const reportedMatch = res.ok && res.data?.reason === "match";
+        let matched = false;
+        let stale = false;
+        if (reportedMatch) {
+            const text = String(res.data?.matched ?? res.data?.text ?? "");
+            const line = freshDoneLine(text, cfg.done, cfg.seen);
+            matched = line !== null;
+            stale = !matched;
+            if (line !== null)
+                match = new RegExp(cfg.done).exec(line)?.[0] ?? line;
+        }
+        if (check) {
+            const r = runCheck(check, checkEnv(matched ? "MATCHED" : "POLL", match));
+            log(`wait ok=${res.ok} matched=${matched}${stale ? " (seen before start)" : ""} check=${r.status}`);
+            if (r.status === 0) {
+                status = "DONE";
+                output = r.stdout;
+                break;
+            }
+        }
+        else {
+            log(`wait ok=${res.ok} matched=${matched}${stale ? " (seen before start)" : ""}`);
+            if (matched) {
+                status = "DONE";
+                break;
+            }
+        }
+        if (!res.ok) {
+            // Tell a dead pane from a dead tunnel: list the session once.
+            const listArgs = { op: "list" };
+            if (cfg.session)
+                listArgs.session = cfg.session;
+            const listed = await call(listArgs, remote).catch((err) => ({ ok: false, error: { code: "failed", message: String(err) } }));
+            if (listed.ok) {
+                const panes = listed.data.panes ?? [];
+                const pane = panes.find((p) => p.title === cfg.to || p.id === cfg.to);
+                if (!pane || pane.exited) {
+                    status = "PANE_DIED";
+                    break;
+                }
+                serveDown = 0;
+            }
+            else if (++serveDown >= SERVE_DOWN_TRIES) {
+                status = "SERVE_DOWN";
+                break;
+            }
+            await sleep(60_000);
+            continue;
+        }
+        serveDown = 0;
+        // A wait normally blocks for its chunk; never spin on one that returns early,
+        // and a line that matched before the start keeps matching until it scrolls off.
+        if (stale)
+            await sleep(STALE_MATCH_POLL_MS);
+        else if (!matched && now() - started < 1_000)
+            await sleep(5_000);
+        if (matched && check && ++confirmTries >= CONFIRM_TRIES) {
+            status = "UNCONFIRMED";
+            break;
+        }
+        if (matched)
+            await sleep(30_000); // the done line stays on screen; give the check time
+    }
+    let body;
+    if (status !== "DONE" && check) {
+        const r = runCheck(check, checkEnv(status, match));
+        if (r.status === 0 && r.stdout.trim())
+            output = r.stdout;
+    }
+    if (status === "DONE" && output.trim()) {
+        body = output;
+    }
+    else {
+        const template = cfg.message ? readFileSync(join(dir, cfg.message), "utf8") : DEFAULT_TEMPLATE;
+        body = fillMessage(template, {
+            id: cfg.id,
+            status,
+            note: status === "DONE" ? "" : NOTES[status],
+            match,
+            output: output && !output.endsWith("\n") ? `${output}\n` : output,
+            pane: cfg.to,
+        });
+    }
+    log(`relay end status=${status}`);
+    const delivered = await deliverMessage(cfg, body, dir, { ...deps, log });
+    return { status, delivered };
+}
+/** Write the relay directory: config (600), snapshots of the check and template. */
+export function prepareRelay(cfg, sources, env) {
+    if (!ID.test(cfg.id))
+        throw new ZellijError("bad_arg", `invalid relay id ${JSON.stringify(cfg.id)}`);
+    try {
+        new RegExp(cfg.done);
+    }
+    catch {
+        throw new ZellijError("bad_arg", `--done is not a valid regex: ${cfg.done}`);
+    }
+    const dir = join(relaysDir(env), `${cfg.id}-${Math.floor(Date.now() / 1000)}`);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // A new relay under this id supersedes the last one's result: --wait must not
+    // return it (a restart within the same second even reuses the directory).
+    rmSync(join(dir, "message.txt"), { force: true });
+    rmSync(join(relaysDir(env), "undelivered", `${cfg.id}.txt`), { force: true });
+    const out = { ...cfg };
+    if (sources.check) {
+        if (!existsSync(sources.check))
+            throw new ZellijError("usage", `check script ${sources.check} not found`);
+        out.check = `check-${basename(sources.check)}`;
+        copyFileSync(sources.check, join(dir, out.check));
+        chmodSync(join(dir, out.check), 0o700);
+    }
+    if (sources.message) {
+        if (!existsSync(sources.message))
+            throw new ZellijError("usage", `message template ${sources.message} not found`);
+        out.message = "message.tmpl";
+        copyFileSync(sources.message, join(dir, out.message));
+    }
+    writePrivate(join(dir, "config.json"), `${JSON.stringify(out, null, 1)}\n`);
+    return dir;
+}
+function updateConfig(dir, patch) {
+    const path = join(dir, "config.json");
+    const cfg = { ...JSON.parse(readFileSync(path, "utf8")), ...patch };
+    writePrivate(path, `${JSON.stringify(cfg, null, 1)}\n`);
+}
+/** Remove the token copy once the relay no longer needs it. */
+export function scrubRelayToken(dir) {
+    const path = join(dir, "config.json");
+    try {
+        const cfg = JSON.parse(readFileSync(path, "utf8"));
+        delete cfg.token;
+        writePrivate(path, `${JSON.stringify(cfg, null, 1)}\n`);
+    }
+    catch {
+        // already gone
+    }
+}
+/** Start the detached relay so it outlives the caller (and the caller's process group). */
+export function launchRelay(dir, env = process.env) {
+    const launch = resolveServeCliLaunch({ env });
+    const argv = [launch.execPath, launch.scriptPath, "relay", "--run", dir];
+    const log = join(dir, "relay.log");
+    const name = basename(dir).replace(/[^A-Za-z0-9._-]/g, "-");
+    if (process.platform === "darwin") {
+        const label = `zswarm.relay.${name}`;
+        const res = spawnSync("launchctl", [
+            "submit", "-l", label, "-o", log, "-e", log, "--",
+            "/usr/bin/env", `PATH=${env.PATH ?? "/usr/bin:/bin"}`, `HOME=${env.HOME ?? ""}`,
+            ...(env.ZSWARM_STATE_DIR ? [`ZSWARM_STATE_DIR=${env.ZSWARM_STATE_DIR}`] : []),
+            `ZSWARM_RELAY_LABEL=${label}`, ...argv,
+        ], { encoding: "utf8" });
+        if (res.status !== 0)
+            throw new ZellijError("failed", `launchctl submit failed: ${(res.stderr ?? "").trim().slice(0, 200)}`);
+        return `launchd job ${label}`;
+    }
+    if (process.platform === "linux" && spawnSync("systemctl", ["--user", "is-system-running"], { encoding: "utf8" }).status !== null) {
+        const unit = `zswarm-relay-${name}`;
+        const res = spawnSync("systemd-run", ["--user", "--collect", "--quiet", `--unit=${unit}`,
+            `--setenv=PATH=${env.PATH ?? "/usr/bin:/bin"}`,
+            ...(env.ZSWARM_STATE_DIR ? [`--setenv=ZSWARM_STATE_DIR=${env.ZSWARM_STATE_DIR}`] : []),
+            ...argv], { encoding: "utf8" });
+        if (res.status === 0)
+            return `systemd unit ${unit}`;
+    }
+    const out = openLog(log);
+    const child = spawn(argv[0], argv.slice(1), { detached: true, stdio: ["ignore", out, out], env, windowsHide: true });
+    child.unref();
+    return `pid ${child.pid}`;
+}
+/** A file descriptor the detached child can inherit. */
+function openLog(path) {
+    return openSync(path, "a");
+}
+/** Send the body now, then leave a relay waiting for the done line. */
+export async function startRelay(input) {
+    const env = input.env ?? process.env;
+    const serve = input.serve?.trim() || env.ZSWARM_SERVE?.trim();
+    if (!serve)
+        throw new ZellijError("usage", "relay needs --serve or ZSWARM_SERVE (the host that owns the target pane)");
+    if (!input.to || !input.replyTo || !input.done)
+        throw new ZellijError("usage", "relay needs --to, --done and --reply-to");
+    const id = input.id?.trim() || `relay-${Date.now().toString(36)}`;
+    const cfg = {
+        id,
+        serve,
+        token: env.ZSWARM_SERVE_TOKEN?.trim() || undefined,
+        session: input.session,
+        to: input.to,
+        done: input.done,
+        replyTo: input.replyTo,
+        // The detached job gets a minimal env, so pin the caller's session now.
+        replySession: input.replySession?.trim() || env.ZSWARM_SESSION?.trim() || env.ZELLIJ_SESSION_NAME?.trim() || undefined,
+        from: input.from?.trim() || "zswarm-relay",
+        timeoutMin: input.timeoutMin ?? 240,
+    };
+    // Read the body before the relay directory (and its token copy) exists.
+    const body = input.bodyFile ? readFileSync(input.bodyFile, "utf8") : undefined;
+    const dir = prepareRelay(cfg, { check: input.check, message: input.message }, env);
+    const call = input.deps?.call ?? ((args, e) => dispatchZswarm(args, undefined, { env: e }));
+    const remote = serveEnv(cfg, env);
+    const target = (args) => cfg.session ? { ...args, session: cfg.session } : args;
+    let sent;
+    let warning;
+    let how;
+    try {
+        if (body !== undefined) {
+            const res = await call(target({ op: "send", to: cfg.to, body, from: cfg.from, settleMs: 800 }), remote);
+            if (!res.ok)
+                throw new ZellijError(res.error.code, `send failed: ${res.error.message}`, res.error.details);
+            sent = res.data?.submitted === true ? "submitted" : "unverified";
+            if (sent !== "submitted") {
+                // One dump; one Enter if the body still sits in the composer.
+                const dump = await call(target({ op: "dump", to: cfg.to, max: 2000 }), remote);
+                const screen = dump.ok ? String(dump.data.text ?? "") : "";
+                const tail = screen.trim().split("\n").slice(-4).join("\n");
+                const firstLine = body.trim().split("\n")[0]?.slice(0, 60) ?? "";
+                if ((firstLine && tail.includes(firstLine)) || tail.includes("[zswarm from=") || tail.includes("[Pasted text")) {
+                    await call(target({ op: "keys", to: cfg.to, keys: "Enter" }), remote);
+                    sent = "enter-pressed";
+                }
+            }
+            if (doneLines(body, cfg.done).length > 0) {
+                warning = "--done matches a line of the body; that line is ignored while it stays on screen, so an identical done line is only seen once it scrolls off";
+            }
+        }
+        // Whatever already matches --done (the echoed body, an earlier task's done
+        // line) is not this task finishing; the relay ignores those lines.
+        const baseline = await call(target({ op: "dump", to: cfg.to, max: 3000 }), remote);
+        const seen = baseline.ok ? doneLines(String(baseline.data.text ?? ""), cfg.done) : [];
+        cfg.seen = seen;
+        updateConfig(dir, { seen });
+        if (!input.foreground)
+            how = (input.launch ?? launchRelay)(dir, env);
+    }
+    catch (err) {
+        // Nothing will run from this directory: take the token copy with it.
+        rmSync(dir, { recursive: true, force: true });
+        throw err;
+    }
+    const extra = warning ? { warning } : {};
+    if (input.foreground) {
+        const result = await relayLoop(dir, input.deps).finally(() => scrubRelayToken(dir));
+        return { id, dir, sent: sent ?? null, ...extra, ...result };
+    }
+    return { id, dir, sent: sent ?? null, ...extra, relay: how };
+}
+/** What `zswarm relay --run <dir>` does inside the detached job. */
+export async function runRelayDir(dir, deps = {}) {
+    const stop = (sig) => () => {
+        appendFileSync(join(dir, "relay.log"), `${new Date().toISOString()} relay stopped by ${sig}\n`);
+        scrubRelayToken(dir);
+        process.exit(143);
+    };
+    const onTerm = stop("SIGTERM");
+    const onHup = stop("SIGHUP");
+    process.once("SIGTERM", onTerm);
+    process.once("SIGHUP", onHup);
+    let code = 1;
+    try {
+        const res = await relayLoop(dir, deps);
+        code = res.delivered ? 0 : 3;
+    }
+    finally {
+        scrubRelayToken(dir);
+        process.off("SIGTERM", onTerm);
+        process.off("SIGHUP", onHup);
+        const label = (deps.env ?? process.env).ZSWARM_RELAY_LABEL;
+        if (label && process.platform === "darwin") {
+            // Remove this relay's own launchd job so launchd neither keeps nor restarts it.
+            spawnSync("launchctl", ["remove", label]);
+        }
+    }
+    return code;
+}
+/**
+ * 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 async function waitForRelay(id, opts = {}) {
+    const env = opts.env ?? process.env;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = opts.now ?? Date.now;
+    const deadline = now() + (opts.timeoutMin ?? 240) * 60_000;
+    const root = relaysDir(env);
+    // Only this id's runs (`build`, not `build-2`), and only the newest one: an
+    // older run's message is not this relay's result.
+    const own = new RegExp(`^${id.replace(/[.]/g, "\\.")}-(\\d+)$`);
+    const nonEmpty = (path) => existsSync(path) && statSync(path).size > 0;
+    for (;;) {
+        const runs = existsSync(root)
+            ? readdirSync(root).flatMap((name) => {
+                const m = own.exec(name);
+                return m ? [{ dir: join(root, name), startedMs: Number(m[1]) * 1000 }] : [];
+            }).sort((a, b) => b.startedMs - a.startedMs)
+            : [];
+        const newest = runs[0];
+        const message = newest ? join(newest.dir, "message.txt") : undefined;
+        if (message && nonEmpty(message))
+            return readFileSync(message, "utf8");
+        const undelivered = join(root, "undelivered", `${id}.txt`);
+        if (nonEmpty(undelivered) && (!newest || statSync(undelivered).mtimeMs >= newest.startedMs)) {
+            return readFileSync(undelivered, "utf8");
+        }
+        if (now() >= deadline)
+            return null;
+        await sleep(opts.pollMs ?? 15_000);
+    }
+}
+/** Remove relay directories and undelivered messages older than `days`. */
+export function pruneRelays(days = 14, env = process.env) {
+    const root = relaysDir(env);
+    if (!existsSync(root))
+        return [];
+    const cutoff = Date.now() - days * 86_400_000;
+    const removed = [];
+    for (const sub of [root, join(root, "undelivered")]) {
+        if (!existsSync(sub))
+            continue;
+        for (const name of readdirSync(sub)) {
+            const path = join(sub, name);
+            if (name === "undelivered")
+                continue;
+            if (statSync(path).mtimeMs < cutoff) {
+                rmSync(path, { recursive: true, force: true });
+                removed.push(path);
+            }
+        }
+    }
+    return removed;
+}

package/dist/host/serve-service.d.ts

@@ -0,0 +1,51 @@
+import type { OpsResult } from "../ops/types.js";
+import { type Runner, type ServiceAccount, type ServiceHost, type ServiceSpec } from "./services.js";
+/** Env a service-run serve reads its token from (never the unit or plist). */
+export declare const SERVE_TOKEN_FILE_ENV = "ZSWARM_SERVE_TOKEN_FILE";
+/** Env that makes serve wait (ms) for its --session to exist before listening. */
+export declare const SERVE_AWAIT_SESSION_ENV = "ZSWARM_SERVE_AWAIT_SESSION_MS";
+export type ServeServiceInput = {
+    listen?: string;
+    session?: string;
+    runAs?: string;
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    /** Injected in tests. */
+    account?: ServiceAccount;
+    run?: Runner;
+    fs?: ServiceHost["fs"];
+    writeSecret?: (account: ServiceAccount, path: string, text: string) => void;
+    readSecret?: (path: string) => string | undefined;
+    probe?: (target: string, token: string) => Promise<OpsResult>;
+    list?: (target: string, session: string, token: string) => Promise<OpsResult>;
+    launch?: {
+        execPath: string;
+        scriptPath: string;
+    };
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+};
+export declare function serveServiceName(session?: string): string;
+export declare function serveTokenPath(account: ServiceAccount, session: string | undefined, env: NodeJS.ProcessEnv): string;
+/** Read the token a service-run serve uses: ZSWARM_SERVE_TOKEN, else ZSWARM_SERVE_TOKEN_FILE. */
+export declare function serveTokenFromEnv(env: NodeJS.ProcessEnv, read?: (path: string) => string | undefined): string | undefined;
+/** The unit or plist for a serve service; exported for tests and docs. */
+export declare function serveServiceSpec(input: {
+    account: ServiceAccount;
+    listen: string;
+    session?: string;
+    tokenPath: string;
+    launch: {
+        execPath: string;
+        scriptPath: string;
+    };
+    env: NodeJS.ProcessEnv;
+}): ServiceSpec;
+/**
+ * serve --install on Linux and macOS: a token file (kept across reinstalls
+ * unless ZSWARM_SERVE_TOKEN is given), a daemon service, then wait for an
+ * authenticated hello and, with --session, the session's pane list.
+ */
+export declare function installServeService(input?: ServeServiceInput): Promise<Record<string, unknown>>;
+/** serve --clear on Linux and macOS: stop and remove the service; the token file stays. */
+export declare function uninstallServeService(input?: ServeServiceInput): Record<string, unknown>;

package/dist/host/serve-service.js

@@ -0,0 +1,150 @@
+import { randomBytes } from "node:crypto";
+import { posix } from "node:path";
+import { ZellijError } from "../errors.js";
+import { resolveServeCliLaunch, serveTaskChildEnv } from "../ops/serve-install.js";
+import { callServe, parseListenAddress, probeServe } from "../ops/serve.js";
+import { defaultStateDir } from "../state.js";
+import { defaultRunner, installServices, readSecretFile, removeServices, serviceAccount, serviceStates, writeSecretFile, } from "./services.js";
+// Service accounts are Linux or macOS accounts: their paths are POSIX paths
+// even when this code runs (in tests) on Windows.
+const { join } = posix;
+/** Env a service-run serve reads its token from (never the unit or plist). */
+export const SERVE_TOKEN_FILE_ENV = "ZSWARM_SERVE_TOKEN_FILE";
+/** Env that makes serve wait (ms) for its --session to exist before listening. */
+export const SERVE_AWAIT_SESSION_ENV = "ZSWARM_SERVE_AWAIT_SESSION_MS";
+const SESSION = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const FOREIGN_PATH = "/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin";
+export function serveServiceName(session) {
+    return session ? `serve-${session}` : "serve";
+}
+function stateDirFor(account, env) {
+    if (!account.foreign && env.ZSWARM_STATE_DIR?.trim())
+        return defaultStateDir(env);
+    return join(account.home, ".zswarm");
+}
+export function serveTokenPath(account, session, env) {
+    return join(stateDirFor(account, env), "serve", `${serveServiceName(session)}.token`);
+}
+/** Read the token a service-run serve uses: ZSWARM_SERVE_TOKEN, else ZSWARM_SERVE_TOKEN_FILE. */
+export function serveTokenFromEnv(env, read = readSecretFile) {
+    const direct = env.ZSWARM_SERVE_TOKEN?.trim();
+    if (direct)
+        return direct;
+    const file = env[SERVE_TOKEN_FILE_ENV]?.trim();
+    if (!file)
+        return undefined;
+    const text = read(file);
+    if (text === undefined)
+        throw new ZellijError("serve_auth", `cannot read ${SERVE_TOKEN_FILE_ENV} (${file})`);
+    return text.trim() || undefined;
+}
+function checkSession(session) {
+    const s = session?.trim();
+    if (!s)
+        return undefined;
+    if (!SESSION.test(s))
+        throw new ZellijError("bad_arg", `invalid session name ${JSON.stringify(s)}`);
+    return s;
+}
+/** The unit or plist for a serve service; exported for tests and docs. */
+export function serveServiceSpec(input) {
+    const { account, session } = input;
+    const base = account.foreign
+        ? { PATH: FOREIGN_PATH, ...(input.env.ZSWARM_BIN ? { ZSWARM_BIN: input.env.ZSWARM_BIN } : {}) }
+        : serveTaskChildEnv(input.env);
+    const env = { ...base, [SERVE_TOKEN_FILE_ENV]: input.tokenPath };
+    if (session) {
+        env.ZSWARM_SESSION = session;
+        env[SERVE_AWAIT_SESSION_ENV] = "60000";
+    }
+    return {
+        name: serveServiceName(session),
+        description: `zswarm serve on ${input.listen}${session ? ` for session ${session}` : ""}`,
+        kind: "daemon",
+        argv: [
+            input.launch.execPath,
+            input.launch.scriptPath,
+            "serve",
+            "--listen",
+            input.listen,
+            ...(session ? ["--session", session] : []),
+        ],
+        env,
+        after: session ? [`crew-${session}`] : undefined,
+    };
+}
+/**
+ * serve --install on Linux and macOS: a token file (kept across reinstalls
+ * unless ZSWARM_SERVE_TOKEN is given), a daemon service, then wait for an
+ * authenticated hello and, with --session, the session's pane list.
+ */
+export async function installServeService(input = {}) {
+    const env = input.env ?? process.env;
+    const run = input.run ?? defaultRunner;
+    const account = input.account ?? serviceAccount(input.runAs, run);
+    const session = checkSession(input.session);
+    const { label } = parseListenAddress(input.listen);
+    // Resolve everything that can fail before the first write.
+    const launch = input.launch ?? resolveServeCliLaunch({ env });
+    const tokenPath = serveTokenPath(account, session, env);
+    const read = input.readSecret ?? readSecretFile;
+    const write = input.writeSecret ?? writeSecretFile;
+    let token = env.ZSWARM_SERVE_TOKEN?.trim() || read(tokenPath)?.trim();
+    const minted = !token;
+    if (!token)
+        token = randomBytes(24).toString("hex");
+    write(account, tokenPath, `${token}\n`);
+    const spec = serveServiceSpec({ account, listen: label, session, tokenPath, launch, env });
+    const done = installServices({ account, run, fs: input.fs }, [spec]);
+    const now = input.now ?? Date.now;
+    const sleep = input.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const deadline = now() + Math.max(1_000, input.timeoutMs ?? 30_000);
+    const probe = input.probe ?? ((target, tok) => probeServe(target, { token: tok, timeoutMs: 5_000 }));
+    const list = input.list ??
+        ((target, s, tok) => callServe(target, { op: "list", session: s }, { token: tok, timeoutMs: 10_000 }));
+    let last;
+    let ready = false;
+    while (now() < deadline) {
+        last = await probe(label, token);
+        if (last.ok && session)
+            last = await list(label, session, token);
+        if (last.ok) {
+            ready = true;
+            break;
+        }
+        await sleep(1_000);
+    }
+    const result = {
+        installed: true,
+        ready,
+        service: spec.name,
+        user: account.user,
+        listen: label,
+        session: session ?? null,
+        tokenFile: tokenPath,
+        tokenMinted: minted,
+        actions: done.lines,
+        notes: done.notes,
+    };
+    if (!ready) {
+        throw new ZellijError("serve_not_ready", `serve service installed but not ready on ${label}`, {
+            ...result,
+            lastError: last && !last.ok ? last.error : undefined,
+            remedy: account.platform === "linux"
+                ? `journalctl --user -u zswarm-${spec.name} (as ${account.user})`
+                : `${account.home}/Library/Logs/zswarm/${spec.name}.log`,
+        });
+    }
+    return result;
+}
+/** serve --clear on Linux and macOS: stop and remove the service; the token file stays. */
+export function uninstallServeService(input = {}) {
+    const run = input.run ?? defaultRunner;
+    const account = input.account ?? serviceAccount(input.runAs, run);
+    const session = checkSession(input.session);
+    const name = serveServiceName(session);
+    const host = { account, run, fs: input.fs };
+    const before = serviceStates(host, [{ name, kind: "daemon" }])[0];
+    const lines = removeServices(host, [{ name, kind: "daemon" }]);
+    return { removed: true, service: name, user: account.user, wasActive: before?.active ?? false, actions: lines };
+}