om-memory-system 4.10.0 → 4.11.0

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());

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

@@ -0,0 +1,38 @@
+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;
+    /** Take the start lock. False when another caller holds a fresh one. */
+    takeStartLock: () => boolean;
+    /** Remove the start lock, only when this process holds it. */
+    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,211 @@
+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.
+    // A fresh lock of another caller is left alone, and so is that caller's start.
+    if (!deps.takeStartLock()) {
+        deps.print("Another start is running (a host start or another web update). Wait a few seconds, then run om-memory-system web update again.");
+        return finish(1, "lock-held", "lock-held");
+    }
+    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);
+            // A web app that hides its version cannot be told from an old waiter, so keep waiting.
+            if (current?.version && !askedAside.has(current.instance)) {
+                if ((compareVersions(current.version, deps.version) ?? 0) >= 0) {
+                    record.served = current.version;
+                    deps.print(`OMMS web app: ${deps.url} (version ${current.version})`);
+                    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, processAlive, removeStartLockFor, startLockPath, takeStartLock }, { 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;
+            }
+        },
+        takeStartLock: () => takeStartLock({
+            lockPath,
+            lockFs: nodeLockFs,
+            pid: process.pid,
+            now: () => Date.now(),
+            pidAlive: processAlive,
+        }),
+        removeStartLock: () => removeStartLockFor(process.pid, lockPath),
+        writeRetireMarker: (before) => writeRetireMarker(before, { home: options.home }),
+        print: (line) => console.log(line),
+        log,
+    };
+}

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

@@ -74,6 +74,7 @@ export declare const nodeLockFs: LockFs;
 export declare function renameRetrying(from: string, to: string, rename?: (from: string, to: string) => void, platform?: NodeJS.Platform, wait?: (ms: number) => void): void;
 /** Remove the start lock when it names `pid`. A restart copy calls this once it owns the port. */
 export declare function removeStartLockFor(pid: number, path?: string, lockFs?: LockFs): void;
+export declare function processAlive(pid: number): boolean;
 /** What taking the start lock needs; a test drives two callers through it step by step. */
 export type LockDeps = Pick<EnsureDeps, "lockPath" | "lockFs" | "pid" | "now" | "pidAlive">;
 /**

package/dist/services/web-ensure.js

@@ -111,7 +111,7 @@ export function removeStartLockFor(pid, path = startLockPath(), lockFs = nodeLoc
         /* An unreadable lock is stale and the next caller replaces it. */
     }
 }
-function processAlive(pid) {
+export function processAlive(pid) {
     try {
         process.kill(pid, 0);
         return true;

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;
+    }
+}

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

@@ -26,6 +26,8 @@ interface WebServerConfig {
     apiToken?: string;
     /** How long a stepped-aside server waits before it may take the port back. */
     stepAsideHoldOffMs?: number;
+    /** Test seam: the retire marker's time, or null. Defaults to `~/.omms/web-retire.json`. */
+    readRetireMarker?: () => number | null;
 }
 type PowerAction = "stop" | "restart";
 export declare class WebServer {
@@ -37,6 +39,8 @@ export declare class WebServer {
     private onTakeoverCallback;
     private onPortsExhaustedCallback;
     private onStepAsideCallback;
+    /** `web update` retires waiting web apps that started before its marker. */
+    private readonly startedAt;
     private onPowerActionCallback;
     private webUpdate;
     private powerActionRunning;
@@ -83,6 +87,10 @@ export declare class WebServer {
     start(): Promise<void>;
     private _start;
     private startHealthCheckLoop;
+    /** One check of a web app that waits for the port. */
+    private waiterTick;
+    /** True when `web update` asked web apps started before this one to retire. */
+    private retiredByUpdate;
     private ownerIsNewer;
     private stopHealthCheckLoop;
     private attemptTakeover;

package/dist/services/web-server.js

@@ -164,6 +164,8 @@ export class WebServer {
     onTakeoverCallback = null;
     onPortsExhaustedCallback = null;
     onStepAsideCallback = null;
+    /** `web update` retires waiting web apps that started before its marker. */
+    startedAt = Date.now();
     onPowerActionCallback = null;
     webUpdate = null;
     powerActionRunning = false;
@@ -490,16 +492,19 @@ export class WebServer {
         const callerVersion = body && typeof body.version === "string"
             ? body.version.slice(0, 40)
             : "";
+        // `web update` replaces a web app of any version; other callers must be newer.
+        const replace = Boolean(body && body.replace === true);
         const record = (outcome) => log("Web server step-aside request", {
             outcome,
             ownVersion: packageVersion(),
             callerVersion,
+            replace,
         });
         if (!isLoopbackAddress(remoteAddress)) {
             record("refused_auth");
             return this.jsonResponse({ success: false, error: "Loopback caller required" }, 403);
         }
-        if (!callerVersion || !isOlderVersion(packageVersion(), callerVersion)) {
+        if (!callerVersion || (!replace && !isOlderVersion(packageVersion(), callerVersion))) {
             record("refused_not_newer");
             return this.jsonResponse({ success: false, error: "Caller is not newer" }, 409);
         }
@@ -572,24 +577,45 @@ export class WebServer {
         if (this.healthCheckInterval) {
             return;
         }
-        this.healthCheckInterval = setInterval(async () => {
-            const isAvailable = await this.checkServerAvailable();
-            if (!isAvailable) {
-                this.stopHealthCheckLoop();
-                await this.attemptTakeover();
-            }
-            else if (this.onStepAsideCallback && (await this.ownerIsNewer())) {
-                // A standalone web app behind a newer one would serve old code after a restart.
-                this.stopHealthCheckLoop();
-                log("Web server waiter retired", { ownVersion: packageVersion() });
-                try {
-                    await this.onStepAsideCallback();
-                }
-                catch (error) {
-                    log("Step-aside callback error", { error: String(error) });
-                }
-            }
-        }, 5000);
+        this.healthCheckInterval = setInterval(() => void this.waiterTick(), 5000);
+    }
+    /** One check of a web app that waits for the port. */
+    async waiterTick() {
+        const isAvailable = await this.checkServerAvailable();
+        if (!isAvailable) {
+            this.stopHealthCheckLoop();
+            await this.attemptTakeover();
+            return;
+        }
+        if (!this.onStepAsideCallback)
+            return;
+        // A standalone web app behind a newer one would serve old code after a restart.
+        const reason = (await this.retiredByUpdate())
+            ? "update"
+            : (await this.ownerIsNewer())
+                ? "newer-owner"
+                : null;
+        if (!reason)
+            return;
+        this.stopHealthCheckLoop();
+        log("Web server waiter retired", { ownVersion: packageVersion(), reason });
+        try {
+            await this.onStepAsideCallback();
+        }
+        catch (error) {
+            log("Step-aside callback error", { error: String(error) });
+        }
+    }
+    /** True when `web update` asked web apps started before this one to retire. */
+    async retiredByUpdate() {
+        try {
+            const read = this.config.readRetireMarker ?? (await import("./web-retire.js")).readRetireMarker;
+            const before = read();
+            return before !== null && this.startedAt < before;
+        }
+        catch {
+            return false;
+        }
     }
     async ownerIsNewer() {
         try {

package/dist/services/web-update-runtime.d.ts

@@ -1,3 +1,5 @@
-import { WebUpdate } from "./web-update.js";
+import { WebUpdate, type InstallDeps } from "./web-update.js";
 /** The npm check and installer of a standalone web app, with the real process, npm, and clock. */
 export declare function startWebUpdate(restart: () => Promise<string | undefined>, canRestart: () => boolean): WebUpdate;
+/** The real npm process, shared by the update button and `web update`. */
+export declare function nodeInstallDeps(): InstallDeps;

package/dist/services/web-update-runtime.js

@@ -12,18 +12,27 @@ export function startWebUpdate(restart, canRestart) {
         fetch,
         setInterval: (callback, ms) => setInterval(callback, ms),
         log,
+        ...nodeInstallDeps(),
+        exists: existsSync,
+        // npm installs beside this Node.js, so read that install, not the first command on PATH.
+        globalVersion: () => globalCommandVersion({ find: () => null }).version,
+        restart,
+        canRestart,
+        now: () => Date.now(),
+    });
+    update.start();
+    return update;
+}
+/** The real npm process, shared by the update button and `web update`. */
+export function nodeInstallDeps() {
+    return {
         execPath: process.execPath,
         platform: process.platform,
-        exists: existsSync,
         spawn: (command, args, options) => spawn(command, args, {
             shell: options.shell,
             stdio: ["ignore", "ignore", "pipe"],
             windowsHide: true,
         }),
-        // npm installs beside this Node.js, so read that install, not the first command on PATH.
-        globalVersion: () => globalCommandVersion({ find: () => null }).version,
-        restart,
-        canRestart,
         // Resolves once npm has stopped. `taskkill /T` also stops npm under the cmd.exe
         // wrapper that `shell: true` starts; the child's own exit confirms it.
         killTree: (child) => new Promise((resolve) => {
@@ -40,8 +49,5 @@ export function startWebUpdate(restart, canRestart) {
         }),
         setTimeout: (callback, ms) => setTimeout(callback, ms),
         clearTimeout: (handle) => clearTimeout(handle),
-        now: () => Date.now(),
-    });
-    update.start();
-    return update;
+    };
 }

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

@@ -65,12 +65,23 @@ export declare class WebUpdate {
     start(): void;
     /** Read npm `latest`. A failed read keeps the last result. */
     check(): Promise<void>;
-    /** The npm that installs into the prefix the launcher reads. */
-    private npmPath;
     status(): UpdateStatus;
     private canInstall;
     /** Start the install and the restart. A request while one runs joins it. */
     requestInstall(): InstallRequest;
     private install;
-    private runNpm;
 }
+/** The parts of the update deps that run npm. */
+export type InstallDeps = Pick<WebUpdateDeps, "execPath" | "platform" | "spawn" | "killTree" | "setTimeout" | "clearTimeout">;
+/** A failure code, or null when npm exited with code 0. */
+export interface InstallResult {
+    code: string | null;
+    exitCode?: number | null;
+}
+/** The npm that installs into the prefix the launcher reads. */
+export declare function npmBesideRuntime(deps: Pick<WebUpdateDeps, "execPath" | "platform">): string;
+/**
+ * Run `npm install -g om-memory-system@<target>` and stop it after 5 minutes.
+ * The web app's update button and `web update` share it.
+ */
+export declare function runGlobalInstall(deps: InstallDeps, target: string): Promise<InstallResult>;