om-memory-system 4.9.0 → 4.11.0-next.96

package/dist/cli/index.js

@@ -15,6 +15,7 @@ Commands:
   import-claude-history     Import Claude Code history into omms
   web                       Start the web app in the foreground
   web install|uninstall|status  Manage the web app login item
+  web update                Update the global install and restart the web app
   memory <mode> [options]   Search, add, list, or forget memories (run with --help)
   profile-catch-up          Analyse every prompt waiting for profile learning (run with --help)
   claude-hook <event>       Run a Claude Code hook (used by the Claude Code plugin)

package/dist/cli/web-command.d.ts

@@ -7,4 +7,4 @@ export interface WebHandoverDeps {
     version?: string;
 }
 /** Run the standalone web app or manage its per-user login item. */
-export declare function runWebCommand(args: string[], options?: WebAutostartOptions, online?: () => Promise<boolean>, handover?: WebHandoverDeps): Promise<number>;
+export declare function runWebCommand(args: string[], options?: WebAutostartOptions, online?: () => Promise<boolean>, handover?: WebHandoverDeps, update?: Partial<import("./web-update-command.js").WebUpdateCommandDeps>): Promise<number>;

package/dist/cli/web-command.js

@@ -31,23 +31,30 @@ async function announceHandover(ctx, handover) {
     }
 }
 /** Run the standalone web app or manage its per-user login item. */
-export async function runWebCommand(args, options = {}, online, handover = {}) {
+export async function runWebCommand(args, options = {}, online, handover = {}, update = {}) {
     const home = options.home ?? homedir();
     const config = await import("../config.js");
     config.initConfig(home);
     const { installWebAutostart, removeWebAutostart, webAutostartStatus } = await import("../services/web-autostart.js");
     const [action, ...rest] = args;
     if (rest.length ||
-        (action && !["install", "uninstall", "status", "--login-item"].includes(action))) {
-        console.error("Usage: om-memory-system web [install|uninstall|status]");
+        (action && !["install", "uninstall", "status", "update", "--login-item"].includes(action))) {
+        console.error("Usage: om-memory-system web [install|uninstall|status|update]");
         return 1;
     }
-    if (action === "install" && !config.CONFIG.webServerEnabled) {
+    if ((action === "install" || action === "update") && !config.CONFIG.webServerEnabled) {
         console.error("OMMS web server is disabled (webServerEnabled is false)");
         return 1;
     }
     const { webServerUrl } = await import("../services/web-api-auth.js");
     const url = webServerUrl(config.CONFIG.webServerHost, config.CONFIG.webServerPort);
+    if (action === "update") {
+        const { productionWebUpdateDeps, runWebUpdate } = await import("./web-update-command.js");
+        return runWebUpdate({
+            ...(await productionWebUpdateDeps({ url, home, autostart: options })),
+            ...update,
+        });
+    }
     if (action === "install" || action === "uninstall") {
         const { readGlobalConfigRevision, writeGlobalConfigKeys } = await import("../services/global-config-writer.js");
         await writeGlobalConfigKeys({ webServerAutoStart: action === "install" }, readGlobalConfigRevision());
@@ -123,7 +130,7 @@ export async function runWebCommand(args, options = {}, online, handover = {}) {
     process.once("SIGTERM", stop);
     // The page's Stop and Restart buttons reach the same process through this callback.
     const { createPowerAction } = await import("./web-power.js");
-    server.setOnPowerAction(createPowerAction({
+    const powerAction = createPowerAction({
         stopServer: async () => {
             clearInterval(keeper);
             process.off("SIGINT", stop);
@@ -140,7 +147,16 @@ export async function runWebCommand(args, options = {}, online, handover = {}) {
         baseUrl: server.getUrl(),
         loginItem: action === "--login-item",
         autostart: options,
-    }));
+    });
+    server.setOnPowerAction(powerAction);
+    // The update button installs the npm release and restarts onto it through the launcher.
+    const { startWebUpdate } = await import("../services/web-update-runtime.js");
+    const { launcherPath } = await import("../services/runtime-record.js");
+    const { ommsDir } = await import("../services/runtime-handoff.js");
+    const { existsSync } = await import("node:fs");
+    // Every restart onto the new copy runs the launcher, the login item's included.
+    const canRestart = () => existsSync(launcherPath(ommsDir()));
+    server.setWebUpdate(startWebUpdate(() => powerAction("update"), canRestart));
     // A newer `web install` asked this web app to give up the port.
     server.setOnStepAside(async () => {
         clearInterval(keeper);

package/dist/cli/web-power.d.ts

@@ -1,6 +1,8 @@
 import type { WebAutostartOptions } from "../services/web-autostart.js";
 /** The two choices the page offers; the web server passes them through unchanged. */
 export type PowerAction = "stop" | "restart";
+/** A restart through the launcher, so the newest copy on the machine serves after an update. */
+export type ProcessAction = PowerAction | "update";
 interface SpawnedChild {
     pid?: number;
     unref(): void;
@@ -16,6 +18,7 @@ export interface PowerDeps {
         stdio: "ignore";
         cwd: string;
         windowsHide: true;
+        env: NodeJS.ProcessEnv;
     }) => SpawnedChild;
     /** Restart the login item through the service manager. False when it cannot. */
     restartLoginItem: () => boolean | Promise<boolean>;
@@ -23,14 +26,29 @@ export interface PowerDeps {
     writeStartLock: (pid: number) => void | Promise<void>;
     /** Remove the start lock when it names `pid`. */
     removeStartLock: (pid: number) => void | Promise<void>;
-    /** True when an OMMS web app answers health at `baseUrl`. */
-    probe: (baseUrl: string) => Promise<boolean>;
+    /**
+     * The OMMS web app that answers at `baseUrl`, or null when none does. The
+     * version is null when this process may not read it, for example behind basic auth.
+     */
+    readOwner: (baseUrl: string) => Promise<{
+        instance: string;
+        version: string | null;
+    } | null>;
+    /** Ask the web app at `baseUrl` to step aside for `version`. True when it agrees. */
+    stepAside: (baseUrl: string, version: string) => Promise<boolean>;
+    /** The instance id the copy reports, so the handoff knows its own copy. */
+    newInstance: () => string;
+    /** The version on disk now; an in-place upgrade changes it after this process started. */
+    version: () => string;
+    env: NodeJS.ProcessEnv;
     sleep: (ms: number) => Promise<void>;
     now: () => number;
     exit: (code: number) => void;
     /** The runtime and arguments of this process, for a detached copy. */
     execPath: string;
     args: string[];
+    /** The launcher at `~/.omms/bin`, or null when it is missing. */
+    launcher: string | null;
     cwd: string;
     pid: number;
     log: (message: string, data: Record<string, unknown>) => void | Promise<void>;
@@ -51,5 +69,5 @@ export declare function createPowerAction(options: {
     loginItem: boolean;
     autostart?: WebAutostartOptions;
     deps?: Partial<PowerDeps>;
-}): (action: PowerAction) => Promise<void>;
+}): (action: ProcessAction) => Promise<string | undefined>;
 export {};

package/dist/cli/web-power.js

@@ -1,10 +1,24 @@
 import { spawn as nodeSpawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
 import { homedir } from "node:os";
+import { packageVersion } from "../services/package-version.js";
+import { ommsDir } from "../services/runtime-handoff.js";
+import { launcherPath } from "../services/runtime-record.js";
+import { compareVersions } from "../services/version-compare.js";
 /** How long a fresh copy must stay up before the old process stops serving. */
 const SPAWN_CHECK_MS = 1_000;
 /** How long the old process waits for the copy to answer before it serves again. */
 export const HANDOFF_WAIT_MS = 15_000;
 const HANDOFF_POLL_MS = 250;
+let tokenHeader = null;
+/** The web app runs on this machine, so the local token file is enough. Read once. */
+function localTokenHeader() {
+    tokenHeader ??= import("../services/auth-token.js").then(({ AUTH_HEADER, getOrCreateAuthToken }) => ({
+        [AUTH_HEADER]: getOrCreateAuthToken(),
+    }));
+    return tokenHeader;
+}
 function productionDeps(options) {
     return {
         spawn: nodeSpawn,
@@ -14,23 +28,55 @@ function productionDeps(options) {
             nodeLockFs.replace(startLockPath(), JSON.stringify({ pid, at: Date.now() }));
         },
         removeStartLock: async (pid) => (await import("../services/web-ensure.js")).removeStartLockFor(pid),
-        probe: async (baseUrl) => {
+        readOwner: async (baseUrl) => {
+            // Health skips basic auth, so a restart can find its copy with basic auth on.
+            let instance;
+            try {
+                const health = await fetch(`${baseUrl}/api/health`, { signal: AbortSignal.timeout(1_000) });
+                const body = (await health.json());
+                if (!health.ok || typeof body.instance !== "string")
+                    return null;
+                instance = body.instance;
+            }
+            catch {
+                return null;
+            }
             try {
-                const response = await fetch(`${baseUrl}/api/health`, {
+                const response = await fetch(`${baseUrl}/api/web/status`, {
+                    headers: await localTokenHeader(),
                     signal: AbortSignal.timeout(1_000),
                 });
                 const body = (await response.json());
-                return response.ok && body.success === true && body.status === "ok";
+                const version = response.ok && typeof body.version === "string" ? body.version : null;
+                return { instance, version };
+            }
+            catch {
+                return { instance, version: null };
+            }
+        },
+        stepAside: async (baseUrl, version) => {
+            try {
+                const response = await fetch(`${baseUrl}/api/web/step-aside`, {
+                    method: "POST",
+                    headers: { ...(await localTokenHeader()), "content-type": "application/json" },
+                    body: JSON.stringify({ version }),
+                    signal: AbortSignal.timeout(1_000),
+                });
+                return response.status === 202;
             }
             catch {
                 return false;
             }
         },
+        newInstance: () => randomUUID(),
+        version: () => packageVersion(),
+        env: process.env,
         sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
         now: () => Date.now(),
         exit: (code) => process.exit(code),
         execPath: process.execPath,
         args: process.argv.slice(1),
+        launcher: existsSync(launcherPath(ommsDir())) ? launcherPath(ommsDir()) : null,
         cwd: homedir(),
         pid: process.pid,
         log: async (message, data) => (await import("../services/logger.js")).log(message, data),
@@ -49,14 +95,16 @@ export function createPowerAction(options) {
     const logFailure = (code) => Promise.resolve(deps.log("Web app restart failed", { code })).catch(() => undefined);
     let stopped = false;
     /** Start the copy, check it, stop serving, and wait until the copy answers. */
-    async function handOff() {
+    async function handOff(args) {
         let child;
+        const instance = deps.newInstance();
         try {
-            child = deps.spawn(deps.execPath, deps.args, {
+            child = deps.spawn(deps.execPath, args, {
                 detached: true,
                 stdio: "ignore",
                 cwd: deps.cwd,
                 windowsHide: true,
+                env: { ...deps.env, OMMS_WEB_INSTANCE: instance },
             });
         }
         catch {
@@ -82,12 +130,30 @@ export function createPowerAction(options) {
             stopped = true;
         }
         // The copy waits as a non-owner and takes the port within about 7 seconds.
-        const began = deps.now();
+        let began = deps.now();
+        // Each older owner is asked once; another older waiter can take the port after it.
+        const askedAside = new Set();
         while (deps.now() - began < HANDOFF_WAIT_MS) {
             if (exited)
                 return giveUp("copy-exit", copyPid);
-            if (await deps.probe(options.baseUrl))
-                return deps.exit(0);
+            const owner = await deps.readOwner(options.baseUrl);
+            if (owner?.instance === instance) {
+                deps.exit(0);
+                return undefined;
+            }
+            // Another web app that waited for the port took it first.
+            if (owner) {
+                const ownVersion = deps.version();
+                const order = owner.version === null ? null : compareVersions(owner.version, ownVersion);
+                if (order === null || order >= 0)
+                    return yieldTo(child, copyPid);
+                if (!askedAside.has(owner.instance)) {
+                    askedAside.add(owner.instance);
+                    // The copy needs a fresh wait once the older web app leaves.
+                    if (await deps.stepAside(options.baseUrl, ownVersion))
+                        began = deps.now();
+                }
+            }
             await deps.sleep(HANDOFF_POLL_MS);
         }
         if (exited)
@@ -96,7 +162,15 @@ export function createPowerAction(options) {
         child.kill("SIGTERM");
         return giveUp("handoff", copyPid);
     }
-    /** Keep or resume serving on the old process, and release the lock it wrote. */
+    /** A web app of the same or a newer version serves, so the copy would only wait. */
+    async function yieldTo(child, copyPid) {
+        child.kill("SIGTERM");
+        await deps.removeStartLock(copyPid);
+        await logFailure("other-owner");
+        deps.exit(0);
+        return undefined;
+    }
+    /** Keep or resume serving on the old process, and release the lock it wrote. Returns the code. */
     async function giveUp(code, copyPid) {
         if (copyPid !== undefined)
             await deps.removeStartLock(copyPid);
@@ -104,7 +178,7 @@ export function createPowerAction(options) {
             await deps.removeStartLock(deps.pid);
         await logFailure(code);
         if (!stopped)
-            return;
+            return code;
         try {
             await options.resumeServer();
             stopped = false;
@@ -113,29 +187,39 @@ export function createPowerAction(options) {
             await logFailure(error instanceof Error ? error.name : "resume-error");
             deps.exit(1);
         }
+        return code;
     }
     return async (action) => {
         if (action === "stop") {
             await options.stopServer();
             deps.exit(0);
-            return;
+            return undefined;
+        }
+        // After an update the copy of this process is the old version; the launcher picks the newest.
+        if (action === "update" && !deps.launcher) {
+            await logFailure("no-launcher");
+            return "no-launcher";
         }
+        const args = action === "update" ? [deps.launcher, "web"] : deps.args;
         stopped = false;
         try {
             if (options.loginItem) {
+                // The login item runs the launcher, so the service manager restart covers an update too.
                 await options.stopServer();
                 stopped = true;
-                if (await deps.restartLoginItem())
-                    return deps.exit(0);
+                if (await deps.restartLoginItem()) {
+                    deps.exit(0);
+                    return undefined;
+                }
             }
             else {
                 // Hold other hosts off until the copy owns the port.
                 await deps.writeStartLock(deps.pid);
             }
-            await handOff();
+            return await handOff(args);
         }
         catch (error) {
-            await giveUp(error instanceof Error ? error.name : "unknown");
+            return giveUp(error instanceof Error ? error.name : "unknown");
         }
     };
 }

package/dist/cli/web-update-command.d.ts

@@ -0,0 +1,36 @@
+import type { InstallResult } from "../services/web-update.js";
+/** How long the command waits for the fresh web app to answer. */
+export declare const FRESH_WAIT_MS = 15000;
+export interface WebUpdateCommandDeps {
+    url: string;
+    /** The local token header; the web app runs on this machine. */
+    headers: Record<string, string>;
+    /** The version this command runs as, the newest copy after the hand-off. */
+    version: string;
+    fetchFn: typeof fetch;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+    /** npm `latest`, or null when the registry does not answer. */
+    latest: () => Promise<string | null>;
+    /** The global install's version from its `package.json`, or null. */
+    globalVersion: () => string | null;
+    install: (target: string) => Promise<InstallResult>;
+    loginItemInstalled: () => boolean;
+    /** Restart the login item through the service manager. False when it cannot. */
+    restartLoginItem: () => boolean;
+    /** Start a detached web app through the launcher. False when there is nothing to start. */
+    startDetached: () => boolean;
+    writeStartLock: () => void;
+    removeStartLock: () => void;
+    writeRetireMarker: (before: number) => void;
+    print: (line: string) => void;
+    log: (message: string, data: Record<string, unknown>) => void;
+}
+/** Run `web update`. Returns the exit code. */
+export declare function runWebUpdate(deps: WebUpdateCommandDeps): Promise<number>;
+/** The real network, npm, login item, and launcher. */
+export declare function productionWebUpdateDeps(options: {
+    url: string;
+    home: string;
+    autostart: import("../services/web-autostart.js").WebAutostartOptions;
+}): Promise<WebUpdateCommandDeps>;

package/dist/cli/web-update-command.js

@@ -0,0 +1,203 @@
+import { compareVersions } from "../services/version-compare.js";
+// `om-memory-system web update`: bring the global install to npm `latest`, then
+// replace every standalone web app with one fresh web app on the newest copy.
+// No process is killed: each web app stops itself after a request.
+/** How long the command waits for the fresh web app to answer. */
+export const FRESH_WAIT_MS = 15_000;
+const POLL_MS = 250;
+const REQUEST_TIMEOUT_MS = 2_000;
+/** The web app on the port, or null when none answers. */
+async function readOwner(deps) {
+    let instance;
+    try {
+        // Health skips basic auth, so the command finds a web app with basic auth on.
+        const health = await deps.fetchFn(`${deps.url}/api/health`, {
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        const body = (await health.json());
+        if (!health.ok || typeof body.instance !== "string")
+            return null;
+        instance = body.instance;
+    }
+    catch {
+        return null;
+    }
+    try {
+        const response = await deps.fetchFn(`${deps.url}/api/web/status`, {
+            headers: deps.headers,
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        const body = (await response.json());
+        return {
+            instance,
+            version: response.ok && typeof body.version === "string" ? body.version : null,
+        };
+    }
+    catch {
+        return { instance, version: null };
+    }
+}
+/** Ask the web app on the port to step aside for a replace. True when it agrees. */
+async function stepAside(deps) {
+    try {
+        const reply = await deps.fetchFn(`${deps.url}/api/web/step-aside`, {
+            method: "POST",
+            headers: { ...deps.headers, "content-type": "application/json" },
+            body: JSON.stringify({ version: deps.version, replace: true }),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        return reply.status === 202;
+    }
+    catch {
+        return false;
+    }
+}
+/** Run `web update`. Returns the exit code. */
+export async function runWebUpdate(deps) {
+    const began = deps.now();
+    const record = { ownVersion: deps.version };
+    const finish = (exitCode, outcome, code = null) => {
+        deps.log("Web app update command", {
+            ...record,
+            outcome,
+            code,
+            durationMs: deps.now() - began,
+        });
+        return exitCode;
+    };
+    // 1. The global install.
+    const latest = await deps.latest();
+    const before = deps.globalVersion();
+    Object.assign(record, { latest, globalBefore: before });
+    if (latest === null) {
+        record.npm = "unreachable";
+        deps.print("Could not check npm for a release. Replacing the web app anyway.");
+    }
+    else if (before === null || (compareVersions(before, latest) ?? 0) < 0) {
+        record.npm = "ran";
+        deps.print(`Installing om-memory-system@${latest} globally (was ${before ?? "not installed"})`);
+        const { code } = await deps.install(latest);
+        const after = deps.globalVersion();
+        record.globalAfter = after;
+        const failure = code ?? (after === latest ? null : "version-mismatch");
+        if (failure) {
+            deps.print(`Global install failed (${failure}). The web app keeps running. Run: npm i -g om-memory-system@${latest}`);
+            return finish(1, "install-failed", failure);
+        }
+        deps.print(`Global install: ${latest}`);
+    }
+    else {
+        record.npm = "skipped";
+        deps.print(`Global install is up to date (${before}).`);
+    }
+    // 2. Replace every standalone web app. Hosts wait while no web app serves.
+    deps.writeStartLock();
+    try {
+        deps.writeRetireMarker(deps.now());
+        const owner = await readOwner(deps);
+        record.oldOwner = owner?.version ?? null;
+        // A web app before `replace` existed ignores the flag and steps aside only for a newer caller.
+        if (owner && !(await stepAside(deps))) {
+            const name = owner.version ? `OMMS ${owner.version}` : "Another web app";
+            deps.print(`${name} holds ${deps.url} and cannot hand it over. Stop that web app (Stop in its power menu, Ctrl+C in its terminal, or quit the session that runs it), then run om-memory-system web update again.`);
+            return finish(1, "stuck", "stuck");
+        }
+        // 3. Start one fresh web app on the newest copy.
+        const viaLoginItem = deps.loginItemInstalled() && deps.restartLoginItem();
+        record.start = viaLoginItem ? "login-item" : "launcher";
+        if (!viaLoginItem && !deps.startDetached()) {
+            deps.print("No OMMS copy to start. Run om-memory-system web to start the web app.");
+            return finish(1, "no-copy", "no-copy");
+        }
+        // 4. Wait for a web app that is not the old one.
+        const askedAside = new Set(owner ? [owner.instance] : []);
+        const deadline = deps.now() + FRESH_WAIT_MS;
+        while (deps.now() < deadline) {
+            const current = await readOwner(deps);
+            if (current && !askedAside.has(current.instance)) {
+                const older = current.version !== null && (compareVersions(current.version, deps.version) ?? 0) < 0;
+                if (!older) {
+                    record.served = current.version;
+                    deps.print(current.version
+                        ? `OMMS web app: ${deps.url} (version ${current.version})`
+                        : `OMMS web app: ${deps.url}`);
+                    return finish(0, "replaced");
+                }
+                // An older web app that waited for the port took it before the fresh one.
+                askedAside.add(current.instance);
+                await stepAside(deps);
+            }
+            await deps.sleep(POLL_MS);
+        }
+        deps.print(`No web app answered on ${deps.url} within ${FRESH_WAIT_MS / 1000} seconds. Run om-memory-system web status.`);
+        return finish(1, "no-answer", "no-answer");
+    }
+    finally {
+        deps.removeStartLock();
+    }
+}
+/** The real network, npm, login item, and launcher. */
+export async function productionWebUpdateDeps(options) {
+    const [{ spawn }, { existsSync }, { join }, { AUTH_HEADER, getOrCreateAuthToken }, { packageVersion }, { latestNpmVersion }, { globalCommandVersion }, { runGlobalInstall }, { nodeInstallDeps }, { restartWebAutostart, webAutostartStatus }, { launcherPath, recordedCopy }, { ommsDir }, { nodeLockFs, removeStartLockFor, startLockPath }, { writeRetireMarker }, { log },] = await Promise.all([
+        import("node:child_process"),
+        import("node:fs"),
+        import("node:path"),
+        import("../services/auth-token.js"),
+        import("../services/package-version.js"),
+        import("../services/update-check.js"),
+        import("../services/global-version.js"),
+        import("../services/web-update.js"),
+        import("../services/web-update-runtime.js"),
+        import("../services/web-autostart.js"),
+        import("../services/runtime-record.js"),
+        import("../services/runtime-handoff.js"),
+        import("../services/web-ensure.js"),
+        import("../services/web-retire.js"),
+        import("../services/logger.js"),
+    ]);
+    const dir = ommsDir(options.home);
+    const lockPath = startLockPath(options.home);
+    return {
+        url: options.url,
+        headers: { [AUTH_HEADER]: getOrCreateAuthToken() },
+        version: packageVersion(),
+        fetchFn: fetch,
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        now: () => Date.now(),
+        latest: () => latestNpmVersion(fetch),
+        // npm installs beside this Node.js, so read that install, not the first command on PATH.
+        globalVersion: () => globalCommandVersion({ find: () => null }).version,
+        install: (target) => runGlobalInstall(nodeInstallDeps(), target),
+        loginItemInstalled: () => webAutostartStatus(options.autostart).state === "installed",
+        restartLoginItem: () => restartWebAutostart(options.autostart),
+        startDetached: () => {
+            // The launcher picks the newest copy, the global install beside this Node.js included.
+            const launcher = launcherPath(dir);
+            const copy = recordedCopy(dir);
+            const script = existsSync(launcher)
+                ? launcher
+                : copy
+                    ? join(copy.root, "dist", "cli", "index.js")
+                    : null;
+            if (!script)
+                return false;
+            try {
+                spawn(process.execPath, [script, "web"], {
+                    detached: true,
+                    stdio: "ignore",
+                    cwd: options.home,
+                    windowsHide: true,
+                }).unref();
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        writeStartLock: () => nodeLockFs.replace(lockPath, JSON.stringify({ pid: process.pid, at: Date.now() })),
+        removeStartLock: () => removeStartLockFor(process.pid, lockPath),
+        writeRetireMarker: (before) => writeRetireMarker(before, { home: options.home }),
+        print: (line) => console.log(line),
+        log,
+    };
+}

package/dist/services/web-retire.d.ts

@@ -0,0 +1,12 @@
+import { type LockFs } from "./web-ensure.js";
+export declare function retireMarkerPath(home?: string): string;
+/** Ask every waiting web app started before `before` (epoch ms) to exit. */
+export declare function writeRetireMarker(before: number, options?: {
+    home?: string;
+    fs?: Pick<LockFs, "replace">;
+}): void;
+/** The marker's `before` time, or null when the marker is missing or damaged. */
+export declare function readRetireMarker(options?: {
+    home?: string;
+    fs?: Pick<LockFs, "read">;
+}): number | null;

package/dist/services/web-retire.js

@@ -0,0 +1,26 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { nodeLockFs } from "./web-ensure.js";
+// The retire marker that `web update` writes. A standalone web app that waits for
+// the port and started before `before` exits. A waiting web app holds no port, so
+// a file is the only way to reach it. The marker stays; the next update overwrites it.
+export function retireMarkerPath(home = homedir()) {
+    return join(home, ".omms", "web-retire.json");
+}
+/** Ask every waiting web app started before `before` (epoch ms) to exit. */
+export function writeRetireMarker(before, options = {}) {
+    (options.fs ?? nodeLockFs).replace(retireMarkerPath(options.home), `${JSON.stringify({ before })}\n`);
+}
+/** The marker's `before` time, or null when the marker is missing or damaged. */
+export function readRetireMarker(options = {}) {
+    const text = (options.fs ?? nodeLockFs).read(retireMarkerPath(options.home));
+    if (text === null)
+        return null;
+    try {
+        const { before } = JSON.parse(text);
+        return typeof before === "number" && Number.isFinite(before) ? before : null;
+    }
+    catch {
+        return null;
+    }
+}