@aron98/load-lock 1.3.0 → 1.5.0

package/dist/cli/main.js

@@ -2,17 +2,17 @@
 /**
  * load-lock CLI: inspection, recovery, scriptable flows, execution helper.
  *
- * Exit codes: 0 ok; 64 usage; 65 protocol/data error; 68 not granted yet
- * (queued/registered); 69 offer/claim failed; 70 internal.
+ * Exit codes: 0 ok; 1 update available (`update --check`); 64 usage; 65
+ * protocol/data error; 68 not granted yet (queued/registered); 69
+ * offer/claim failed; 70 internal.
  */
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync, rmSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { connect } from "node:net";
-import { setTimeout as delay } from "node:timers/promises";
 import { LLClient, withClient } from "../shared/client.js";
 import { ProtocolError } from "../shared/protocol.js";
 import { waitForTurn } from "../shared/wait-turn.js";
+import { waitForTrackedJob } from "../shared/wait-completion.js";
 import { stateDir, socketPath } from "../core/persist.js";
 import { isWindows, probeTransport, killProcessGroup } from "../shared/transport.js";
 import { packageVersion, compareVersions } from "../shared/version.js";
@@ -20,6 +20,8 @@ import { findInstalledCopies } from "./copies.js";
 import { installCommand, uninstallCommand } from "./install.js";
 import { hookCommand } from "./hook.js";
 import { topCommand } from "./top.js";
+import { awaitDaemonUpgraded, serviceRestart, serviceStart, serviceStop, ServiceError } from "./service.js";
+import { updateCommand } from "./update.js";
 // ---------------------------------------------------------------- arg parsing
 const argv = process.argv.slice(2);
 let flags = {};
@@ -34,7 +36,7 @@ for (let i = 0; i < argv.length; i++) {
         const eq = a.indexOf("=");
         if (eq !== -1)
             flags[a.slice(2, eq)] = a.slice(eq + 1);
-        else if (["json", "follow", "force", "admin", "quiet"].includes(a.slice(2)))
+        else if (["json", "follow", "force", "admin", "quiet", "check", "version"].includes(a.slice(2)))
             flags[a.slice(2)] = true;
         else if (i + 1 < argv.length && !argv[i + 1].startsWith("--"))
             flags[a.slice(2)] = argv[++i];
@@ -65,87 +67,6 @@ function defaultAgent() {
     return (process.env.LOAD_LOCK_AGENT ||
         "cli:" + (process.env.USER || "user") + "@" + (process.env.HOSTNAME || "localhost"));
 }
-// ------------------------------------------------- daemon service helpers
-/** daemon.json contents, or null when missing/unreadable. */
-function readDaemonInfo(dir) {
-    try {
-        return JSON.parse(readFileSync(join(dir, "daemon.json"), "utf8"));
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Version-less hello over a raw socket connection: deliberately does NOT
- * send clientVersion, so asking a daemon for its identity never orders it
- * to self-restart (used by `service stop` and post-restart confirmation).
- * Best-effort: resolves null on any failure.
- */
-function rawHello(sockPath, timeoutMs = 2000) {
-    return new Promise((resolve) => {
-        let settled = false;
-        let buf = "";
-        const done = (v) => {
-            if (settled)
-                return;
-            settled = true;
-            try {
-                sock.destroy();
-            }
-            catch {
-                /* ignore */
-            }
-            resolve(v);
-        };
-        const sock = connect(sockPath, () => {
-            sock.write(JSON.stringify({ id: 1, method: "hello", params: {} }) + "\n");
-        });
-        sock.on("data", (chunk) => {
-            buf += chunk.toString("utf8");
-            const idx = buf.indexOf("\n");
-            if (idx === -1)
-                return;
-            try {
-                const msg = JSON.parse(buf.slice(0, idx));
-                done(msg.ok ? msg.result : null);
-            }
-            catch {
-                done(null);
-            }
-        });
-        sock.on("error", () => done(null));
-        const timer = setTimeout(() => done(null), timeoutMs);
-        timer.unref?.();
-    });
-}
-/** Poll the socket until nothing answers there (bounded). */
-async function waitSocketFree(sockPath, timeoutMs) {
-    const deadline = Date.now() + Math.max(0, timeoutMs);
-    for (;;) {
-        if (!(await probeTransport(sockPath)))
-            return true;
-        if (Date.now() >= deadline)
-            return false;
-        await delay(100);
-    }
-}
-/**
- * After ordering a self-restart, wait for the daemon to come back running
- * at least `installed` (the version of this CLI copy). Resolves its hello
- * result, or null if it did not come back (or an older/pre-handshake
- * daemon answered again — e.g. the daemon's copy is not actually updated).
- */
-async function awaitDaemonUpgraded(sockPath, timeoutMs, installed) {
-    const deadline = Date.now() + Math.max(0, timeoutMs);
-    for (;;) {
-        const h = await rawHello(sockPath, 1500);
-        if (h && typeof h.daemonVersion === "string" && compareVersions(h.daemonVersion, installed) >= 0)
-            return h;
-        if (Date.now() >= deadline)
-            return null;
-        await delay(250);
-    }
-}
 const HELP_GROUPS = [
     {
         title: "permit operations",
@@ -162,7 +83,7 @@ const HELP_GROUPS = [
     {
         title: "waiting & running",
         items: [
-            { names: ["wait"], desc: "sleep until a queued request's turn, then auto-claim the offer: --id <request-id> [--timeout <ms>]" },
+            { names: ["wait"], desc: "sleep until a queued request's turn (--id <request-id>), auto-claiming the offer — or until a heavy job finishes (--job <request-id>): [--timeout <ms>]" },
             { names: ["run"], desc: "acquire (or reuse) a permit and run a command under it: run [--permit <token> | acquire flags] -- <cmd>" },
         ],
     },
@@ -176,12 +97,14 @@ const HELP_GROUPS = [
             { names: ["config", "get-config"], desc: "current configuration" },
             { names: ["configure"], desc: "change configuration (compare-and-swap): --reason required" },
             { names: ["dashboard", "top"], desc: "full-screen live dashboard, read-only (never acquires): [--once]" },
+            { names: ["version"], desc: "print this CLI copy's version" },
         ],
     },
     {
         title: "service & diagnostics",
         items: [
-            { names: ["service"], desc: "daemon lifecycle: start | stop | status (stop/start take --timeout <ms>)" },
+            { names: ["service"], desc: "daemon lifecycle: start | stop | restart | status (stop/start/restart take --timeout <ms> for the stop phase)" },
+            { names: ["update"], desc: "check npm for a newer version, install it via the detected package manager, then `service restart` (--check dry-run; refuses repo checkouts / opencode-managed copies)" },
             { names: ["doctor"], desc: "health report: state dir, socket, daemon, versions + copies, machine" },
             { names: ["recover"], desc: "list held permits with diagnostics; recover force-release --id <request-id>" },
         ],
@@ -215,10 +138,15 @@ function usage() {
         for (const item of g.items)
             lines.push(helpLine(item));
     }
-    lines.push("", "exit codes: 0 ok, 64 usage, 65 protocol, 68 not granted yet, 69 offer/claim failed, 70 internal");
+    lines.push("", "exit codes: 0 ok, 1 update available (update --check), 64 usage, 65 protocol, 68 not granted yet, 69 offer/claim failed, 70 internal");
     process.stdout.write(lines.join("\n") + "\n");
 }
 async function main() {
+    // `--version` prints this copy's version (same as the `version` command).
+    if (f["version"] === true) {
+        process.stdout.write(packageVersion() + "\n");
+        return;
+    }
     // `--help`, `-h` and a bare `load-lock` all print the same usage as `help`.
     if (f["help"] !== undefined || cmd === "-h" || (positional.length === 0 && argv.length === 0)) {
         usage();
@@ -388,19 +316,43 @@ async function main() {
             out(await withClient((c) => c.request("attach_pid", { permitToken: token, pid })));
             return;
         }
-        // ------------------------------------------------------- wait (offer -> permit)
+        // ------------------------------------------------------- wait (offer -> permit / job -> done)
         case "wait": {
-            // Watches a queued request; auto-claims the offer when capacity is
-            // handed to it and prints the permit token. Honest bounded blocking
-            // for scriptable flows (aider, plain shell scripts). Shares the exact
-            // implementation with the MCP wait_for_turn tool and the OpenCode
-            // plugin (src/shared/wait-turn.ts).
-            const id = S("id") || fail("wait: --id <request-id> required");
+            // Two honest bounded sleeps sharing one command:
+            //   --id  : queue phase — watches a queued request, auto-claims the
+            //           offer when capacity reaches it, prints the permit token.
+            //   --job : execution phase — sleeps until the daemon-tracked job for
+            //           that request-id finishes (liveness sweep wake; the permit
+            //           is released before you are woken). Structured result on
+            //           every path; still_running = checkpoint, call again.
+            // Both share the exact implementations with the MCP tools and the
+            // OpenCode plugin (src/shared/wait-turn.ts / wait-completion.ts).
             const timeoutMs = N("timeout", 600_000);
-            const agent = S("agent", defaultAgent());
             const c = new LLClient();
             await c.connect();
             try {
+                const job = S("job");
+                if (job) {
+                    const r = await waitForTrackedJob({ client: c, requestId: job, timeoutMs });
+                    out({
+                        state: r.state,
+                        request_id: r.requestId ?? job,
+                        exit_code: r.exitCode,
+                        duration_ms: r.durationMs,
+                        permit_released: r.permitReleased,
+                        waited_ms: r.waitedMs,
+                        effective_wait_ms: r.effectiveWaitMs,
+                        started_at: r.startedAt,
+                        detail: r.detail ?? r.nextAction,
+                    });
+                    if (r.state === "finished")
+                        return;
+                    if (r.state === "still_running")
+                        fail(`wait: job still running after ${r.waitedMs}ms (checkpoint — call again)`, 68);
+                    fail(`wait: job is ${r.state.replace(/_/g, " ")} — ${r.nextAction}`, 69);
+                }
+                const id = S("id") || fail("wait: --id <request-id> (queue wait) or --job <request-id> (job wait) required");
+                const agent = S("agent", defaultAgent());
                 const r = await waitForTurn({ client: c, agentId: agent, requestId: id, timeoutMs });
                 if (r.state === "granted" && r.entry?.permitToken) {
                     out({ permit_token: r.entry.permitToken, state: r.state, request_id: r.requestId, auto_claimed: r.autoClaimed ?? false });
@@ -427,130 +379,29 @@ async function main() {
         // --------------------------------------------------------------- service
         case "service": {
             const sub = rest[0] ?? "status";
+            const phase = (e) => {
+                if (e instanceof ServiceError)
+                    fail(e.message, e.exitCode);
+                throw e;
+            };
             if (sub === "stop") {
-                // Honest stop: signal the daemon, wait bounded for its socket to go
-                // silent, escalate to SIGKILL, and only report success once the
-                // endpoint is verifiably free. A leftover silent socket file or
-                // daemon.json (crash leftovers) is cleaned up either way.
-                const dir = stateDir();
-                const sock = socketPath();
-                const timeoutMs = N("timeout", 5000);
-                const info = readDaemonInfo(dir);
-                const answering = await probeTransport(sock);
-                if (!answering) {
-                    // Nothing is listening: no daemon to stop. Clean crash leftovers.
-                    try {
-                        if (!isWindows() && existsSync(sock))
-                            unlinkSync(sock);
-                    }
-                    catch {
-                        /* ignore */
-                    }
-                    try {
-                        rmSync(join(dir, "daemon.json"), { force: true });
-                    }
-                    catch {
-                        /* ignore */
-                    }
-                    process.stdout.write("load-lock: no running daemon found (stale files cleaned)\n");
-                    return;
-                }
-                // Identify the daemon: prefer daemon.json, else ask it directly
-                // (version-less hello — stopping must not order a self-restart).
-                let pid = typeof info?.pid === "number" ? info.pid : undefined;
-                if (!pid) {
-                    const hello = await rawHello(sock, 1500);
-                    if (hello && typeof hello.pid === "number")
-                        pid = hello.pid;
-                }
-                if (!pid) {
-                    fail(`the socket ${sock} answers but no pid could be identified (daemon did not respond and daemon.json names none) ` +
-                        `— cannot stop safely; run \`load-lock doctor\``, 70);
-                }
-                let how = "SIGTERM";
-                let stopped = false;
-                try {
-                    process.kill(pid, "SIGTERM");
-                }
-                catch (e) {
-                    if (e?.code === "ESRCH")
-                        stopped = true; // already gone
-                    else
-                        fail(`cannot signal daemon pid ${pid}: ${e?.message ?? e}`, 70);
-                }
-                if (!stopped)
-                    stopped = await waitSocketFree(sock, timeoutMs);
-                if (!stopped) {
-                    how = "SIGKILL";
-                    try {
-                        process.kill(pid, "SIGKILL");
-                    }
-                    catch {
-                        /* already dead */
-                    }
-                    stopped = await waitSocketFree(sock, timeoutMs);
-                }
-                if (!stopped) {
-                    fail(`daemon pid ${pid} did not stop within ${timeoutMs}ms even after SIGKILL — run \`load-lock doctor\``, 70);
-                }
-                try {
-                    if (!isWindows() && existsSync(sock))
-                        unlinkSync(sock);
-                }
-                catch {
-                    /* ignore */
-                }
-                try {
-                    rmSync(join(dir, "daemon.json"), { force: true });
-                }
-                catch {
-                    /* ignore */
-                }
-                process.stdout.write(`load-lock: daemon (pid ${pid}) stopped${how === "SIGKILL" ? " (required SIGKILL after SIGTERM)" : ""}\n`);
+                // Hardened stop: SIGTERM → bounded wait → SIGKILL → verified-free
+                // endpoint; crash leftovers cleaned either way.
+                process.stdout.write(`load-lock: ${await serviceStop(N("timeout", 5000)).catch(phase)}\n`);
                 return;
             }
             if (sub === "start") {
                 // Connecting auto-spawns a detached daemon (see shared/client.ts);
                 // hello confirms it is up. Refusals name the conflicting pid.
-                const timeoutMs = N("timeout", 10_000);
-                const sock = socketPath();
-                const installed = packageVersion();
-                try {
-                    const r = (await withClient((c) => c.request("hello", {}, timeoutMs)));
-                    const dv = typeof r.daemonVersion === "string" ? r.daemonVersion : undefined;
-                    if (dv && compareVersions(dv, installed) < 0) {
-                        // The handshake just ordered this old daemon to self-restart;
-                        // confirm it comes back on updated code.
-                        const up = await awaitDaemonUpgraded(sock, 8000, installed);
-                        if (up) {
-                            process.stdout.write(`load-lock: daemon self-restarted ${r.pid} -> ${up.pid} (v${dv} -> v${up.daemonVersion}), running on ${sock}\n`);
-                        }
-                        else {
-                            process.stdout.write(`load-lock: daemon running on pid ${r.pid} (${sock}), daemon v${dv} — older than this CLI v${installed}; ` +
-                                `self-restart ordered but not confirmed (its copy may not be updated in place — see docs/OPERATIONS.md)\n`);
-                        }
-                        return;
-                    }
-                    process.stdout.write(`load-lock: daemon running on pid ${r.pid} (${sock})${dv ? `, daemon v${dv}` : ""}\n`);
-                    return;
-                }
-                catch (e) {
-                    if (await probeTransport(sock)) {
-                        // Something owns the endpoint. Name it.
-                        const hello = await rawHello(sock, 1500);
-                        if (hello && typeof hello.pid === "number") {
-                            fail(`start refused: socket answered from pid ${hello.pid} — another daemon owns ${sock}; ` +
-                                `if it is stale, run \`load-lock service stop\` first`, 70);
-                        }
-                        const info = readDaemonInfo(stateDir());
-                        if (info && typeof info.pid === "number") {
-                            fail(`socket ${sock} answers but the daemon did not respond (daemon.json names pid ${info.pid}) — likely hung; ` +
-                                `run \`load-lock service stop\``, 70);
-                        }
-                        fail(`start refused: ${sock} is in use but nothing responsive owns it — run \`load-lock doctor\``, 70);
-                    }
-                    throw e;
-                }
+                process.stdout.write(`load-lock: ${await serviceStart(N("timeout", 10_000)).catch(phase)}\n`);
+                return;
+            }
+            if (sub === "restart") {
+                // Hardened stop, then honest start — both phases reported; a
+                // failure names the phase and reason (issue #38).
+                const r = await serviceRestart(N("timeout", 5000), 10_000).catch(phase);
+                process.stdout.write(`load-lock: ${r.stop}\nload-lock: ${r.start}\n`);
+                return;
             }
             if (sub === "status") {
                 const r = (await withClient((c) => c.request("hello", {})));
@@ -570,9 +421,23 @@ async function main() {
                 });
                 return;
             }
-            fail(`service: unknown subcommand "${sub}" (use start | stop | status)`);
+            fail(`service: unknown subcommand "${sub}" (use start | stop | restart | status)`);
+            return;
+        }
+        // ---------------------------------------------------------------- update
+        case "update": {
+            // issue #38: registry check → classify self → apply via the detected
+            // package manager (or refuse honestly) → `service restart` on
+            // success. Exit code comes from updateCommand (1 = update available
+            // under --check; 70 = failure/refusal in apply mode).
+            const code = await updateCommand({ check: B("check"), json: B("json") });
+            if (code !== 0)
+                process.exit(code);
             return;
         }
+        case "version":
+            process.stdout.write(packageVersion() + "\n");
+            return;
         case "doctor": {
             const report = {};
             report.node = process.version;

package/dist/cli/service.d.ts

@@ -0,0 +1,56 @@
+/** A service-phase failure with the exit code the CLI should use. */
+export declare class ServiceError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+/** daemon.json contents, or null when missing/unreadable. */
+export declare function readDaemonInfo(dir: string): {
+    pid?: number;
+    startedAt?: number;
+    socket?: string;
+} | null;
+/**
+ * Version-less hello over a raw socket connection: deliberately does NOT
+ * send clientVersion, so asking a daemon for its identity never orders it
+ * to self-restart (used by `service stop` and post-restart confirmation).
+ * Best-effort: resolves null on any failure.
+ */
+export declare function rawHello(sockPath: string, timeoutMs?: number): Promise<{
+    pid?: number;
+    daemonVersion?: string;
+    protocolVersion?: number;
+} | null>;
+/**
+ * After ordering a self-restart, wait for the daemon to come back running
+ * at least `installed` (the version of this CLI copy). Resolves its hello
+ * result, or null if it did not come back (or an older/pre-handshake
+ * daemon answered again — e.g. the daemon's copy is not actually updated).
+ */
+export declare function awaitDaemonUpgraded(sockPath: string, timeoutMs: number, installed: string): Promise<{
+    pid?: number;
+    daemonVersion?: string;
+} | null>;
+/**
+ * Hardened stop: signal the daemon, wait bounded for its socket to go
+ * silent, escalate to SIGKILL, and only report success once the endpoint
+ * is verifiably free. A leftover silent socket file or daemon.json (crash
+ * leftovers) is cleaned up either way. Returns the report line; throws
+ * ServiceError on failure.
+ */
+export declare function serviceStop(timeoutMs: number): Promise<string>;
+/**
+ * Honest start: connecting auto-spawns a detached daemon (see
+ * shared/client.ts); hello confirms it is up. Refusals name the
+ * conflicting pid. Returns the report line; throws ServiceError on
+ * failure.
+ */
+export declare function serviceStart(timeoutMs: number): Promise<string>;
+/**
+ * `service restart` (issue #38): hardened stop, then honest start — both
+ * phases reported; a failure names the phase and reason. Stopping when
+ * nothing runs is fine: the start phase simply spawns a fresh daemon.
+ */
+export declare function serviceRestart(stopTimeoutMs?: number, startTimeoutMs?: number): Promise<{
+    stop: string;
+    start: string;
+}>;