om-memory-system 5.7.0-next.218 → 5.9.0

package/dist/services/host-copies.js

@@ -0,0 +1,150 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { isOlderVersion } from "./version-compare.js";
+// OpenCode 2.2 installs each update of a plugin to a new folder:
+// `<cache>/om-memory-system@latest/<ms timestamp>/node_modules/om-memory-system/`.
+// It never removes the old ones. This module lists the copies next to the
+// running one, so the update check can see whether the new version reached the
+// disk and the OpenCode service can remove copies that no process needs.
+// It takes paths as arguments and imports no config, so tests need no real home.
+/** The clean-up leaves everything alone until the running copy is this old. */
+export const CACHE_PRUNE_MIN_AGE_MS = 24 * 60 * 60 * 1000;
+const PACKAGE_FOLDER = "/node_modules/om-memory-system";
+/**
+ * OpenCode names the cache folder after the package and the version spec, such as
+ * `om-memory-system@latest`. The `@` is required: a plain `om-memory-system` folder is
+ * a checkout or project, and its numeric folders are not OpenCode installs.
+ */
+const CACHE_FOLDER = /^om-memory-system@.+$/;
+function versionAt(root) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The same path with one separator and no trailing one, for comparing roots. */
+const samePath = (path) => path.replaceAll("\\", "/").replace(/\/+$/, "");
+/**
+ * A key that is equal for two paths to the same folder. The device and inode
+ * match through a symbolic link or a different letter case; a path that cannot
+ * be read falls back to its text.
+ */
+function folderKey(path) {
+    try {
+        const { dev, ino } = statSync(path);
+        if (ino !== 0)
+            return `inode:${dev}:${ino}`;
+    }
+    catch {
+        // Compare the text below.
+    }
+    return `path:${samePath(path)}`;
+}
+/**
+ * The running copy and, when it sits in a timestamp folder, the other copies in
+ * the same cache folder. Null when `modulePath` is not inside
+ * `node_modules/om-memory-system/`. Never throws.
+ */
+export function listHostCopies(modulePath) {
+    const normal = modulePath.replaceAll("\\", "/");
+    const at = normal.lastIndexOf(`${PACKAGE_FOLDER}/`);
+    if (at < 0)
+        return null;
+    // Replacing a backslash with a slash keeps the length, so the index fits the original path.
+    const root = modulePath.slice(0, at + PACKAGE_FOLDER.length);
+    const stampFolder = modulePath.slice(0, at);
+    const parts = stampFolder.replaceAll("\\", "/").split("/");
+    const name = parts[parts.length - 1] ?? "";
+    const result = { root, version: versionAt(root), stamp: null, siblings: [] };
+    if (!/^\d+$/.test(name))
+        return result;
+    const cache = stampFolder.slice(0, stampFolder.length - name.length);
+    // Only OpenCode's `om-memory-system@<spec>` folder holds timestamp copies. A project
+    // folder with a number for a name is not one, and the clean-up must never delete its siblings.
+    const cacheName = cache.replaceAll("\\", "/").split("/").filter(Boolean).pop() ?? "";
+    if (!CACHE_FOLDER.test(cacheName))
+        return result;
+    result.stamp = Number(name);
+    try {
+        const names = readdirSync(cache, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && /^\d+$/.test(entry.name) && entry.name !== name)
+            .map((entry) => entry.name)
+            .sort((a, b) => Number(a) - Number(b));
+        for (const sibling of names) {
+            const siblingRoot = join(cache, sibling, "node_modules", "om-memory-system");
+            result.siblings.push({
+                root: siblingRoot,
+                version: versionAt(siblingRoot),
+                stamp: Number(sibling),
+            });
+        }
+    }
+    catch {
+        // An unreadable cache folder lists no siblings.
+    }
+    return result;
+}
+/**
+ * The versions on disk: the running copy's and each sibling's. Pi updates in
+ * place, so its running copy shows the new version after `pi update`. OpenCode
+ * shows it in a new sibling folder. Never throws.
+ */
+export function installedVersions(modulePath) {
+    const copies = listHostCopies(modulePath);
+    if (!copies)
+        return [];
+    const versions = [copies.version, ...copies.siblings.map((copy) => copy.version)];
+    return versions.filter((version) => version !== null);
+}
+/**
+ * Remove old OMMS copies from the running copy's cache folder. A copy goes only
+ * when its timestamp and its version are both older than the running copy's,
+ * it is not in `keepRoots`, and the running copy is at least
+ * `CACHE_PRUNE_MIN_AGE_MS` old. A copy that cannot be removed stays. Logs one
+ * `OpenCode cache clean-up` record with counts for each pass in a timestamp
+ * folder, also when the counts are zero. Never throws.
+ */
+export async function pruneOldCacheCopies(options) {
+    const counts = { removed: 0, kept: 0 };
+    try {
+        const copies = listHostCopies(options.modulePath);
+        if (!copies || copies.stamp === null)
+            return counts;
+        const older = copies.siblings.filter((copy) => copy.stamp < copies.stamp);
+        const keep = new Set(options.keepRoots.map(folderKey));
+        const old = options.now - copies.stamp >= CACHE_PRUNE_MIN_AGE_MS;
+        const remove = options.remove ?? ((folder) => rm(folder, { recursive: true, force: true }));
+        for (const copy of older) {
+            const removable = old &&
+                copy.version !== null &&
+                isOlderVersion(copy.version, options.runningVersion) &&
+                !keep.has(folderKey(copy.root));
+            if (removable) {
+                try {
+                    // The timestamp folder holds the whole install, not only the package folder.
+                    await remove(join(copy.root, "..", ".."));
+                    counts.removed++;
+                    continue;
+                }
+                catch {
+                    // A locked or busy folder stays.
+                }
+            }
+            counts.kept++;
+        }
+        try {
+            void Promise.resolve(options.log("OpenCode cache clean-up", { ...counts })).catch(() => { });
+        }
+        catch {
+            // A failed log write must not change the result.
+        }
+    }
+    catch {
+        // The clean-up is housekeeping. It never breaks the service.
+    }
+    return counts;
+}

package/dist/services/host-self-update.d.ts

@@ -0,0 +1,108 @@
+/** A second session does not start another update for the same release within this time. */
+export declare const HOST_SELF_UPDATE_RETRY_MS: number;
+/** How often a running plugin reads the marker while an update is pending. */
+export declare const HOST_UPDATE_POLL_MS: number;
+/** How long a running plugin reads the marker before it gives up. */
+export declare const HOST_UPDATE_POLL_LIMIT_MS: number;
+export type HostSelfUpdateCode = "started" | "current" | "recent" | "disabled" | "unreachable" | "local" | "pinned" | "spawn-failed";
+/** How the host installed this copy. Only "npm" (unpinned) is updated. */
+export type HostInstallSource = "npm" | "local" | "pinned";
+export interface HostUpdateMarker {
+    version: string;
+    startedAt: number;
+    outcome?: "installed" | "failed";
+    finishedAt?: number;
+}
+export type HostUpdateStatus = "pending" | "installed" | "failed";
+export interface HostSelfUpdateDeps {
+    /** False when `OMMS_DISABLE_UPDATE_CHECK` is `1`. */
+    enabled: boolean;
+    /** Log message, for example `Pi plugin self-update`. */
+    logLabel: string;
+    currentVersion: string;
+    /** The host's own update command, for example `pi` with `["update", "npm:om-memory-system"]`. */
+    command: string;
+    args: string[];
+    /** The marker the detached process writes its result into. */
+    markerPath: string;
+    installSource: () => HostInstallSource;
+    fetch: typeof fetch;
+    now: () => number;
+    readMarker: () => HostUpdateMarker | null;
+    writeMarker: (value: HostUpdateMarker) => void;
+    /** The OMMS versions found on disk: the running copy's and, for OpenCode, its cache siblings. */
+    installedVersions: () => string[];
+    /** Start a process that outlives this session. */
+    spawnDetached: (command: string, args: string[]) => void;
+    log: (message: string, data: Record<string, unknown>) => void | Promise<void>;
+}
+export interface HostSelfUpdateResult {
+    code: HostSelfUpdateCode;
+    /** The newer release on npm, or null when there is none to report. */
+    update: string | null;
+}
+/** Arguments for the script runner (`node` or Bun) that runs the host command detached. */
+export declare function hostUpdateRunnerArgs(markerPath: string, marker: HostUpdateMarker, command: string, args: string[]): string[];
+/** Start a background host update when npm has a newer release. Never throws. */
+export declare function startHostSelfUpdate(deps: HostSelfUpdateDeps): Promise<HostSelfUpdateResult>;
+/** The state of the update for `version` that the marker records, or null. */
+export declare function markerStatus(marker: HostUpdateMarker | null, version: string): HostUpdateStatus | null;
+/**
+ * `installed` holds only when a copy on disk has the release (or a newer one,
+ * when a release landed during the update). The host command can exit with 0
+ * and install nothing; that outcome reads as `failed`. Other states pass through.
+ */
+export declare function confirmedStatus(status: HostUpdateStatus | null, version: string, installed: string[]): HostUpdateStatus | null;
+/** The marker's state for `version`, with `installed` confirmed against the copies on disk. */
+export declare function hostUpdateStatus(deps: Pick<HostSelfUpdateDeps, "readMarker" | "installedVersions">, version: string): HostUpdateStatus | null;
+/** Read a marker file. A missing, unreadable or malformed file is no marker. */
+export declare function readMarkerFile(path: string): HostUpdateMarker | null;
+/**
+ * Read the marker now, then every `intervalMs` until it holds an outcome or
+ * `maxMs` passes. Calls `onSettled` once with the outcome. Returns a stop function.
+ */
+export declare function watchHostUpdate(options: {
+    read: () => HostUpdateStatus | null;
+    onSettled: (status: "installed" | "failed") => void;
+    intervalMs?: number;
+    maxMs?: number;
+}): () => void;
+/** True when the module file sits in an npm install of om-memory-system. */
+export declare function installedFromNpm(modulePath: string): boolean;
+/**
+ * True when the module sits in a host package cache folder named
+ * `om-memory-system` or `om-memory-system@latest`. Any other folder, such as
+ * one with a version, counts as pinned. OpenCode 2.2 adds a timestamp folder
+ * between that folder and `node_modules`.
+ */
+export declare function unpinnedCacheFolder(modulePath: string): boolean;
+/**
+ * True when a settings file lists `npm:om-memory-system` in `packages` with no
+ * version. A file that cannot be read, or an entry with a version, counts as pinned.
+ */
+export declare function unpinnedPackageSource(settingsText: string | null): boolean;
+/** Footer text after the status glyph: a newer release, or one installed and waiting for a restart. */
+export declare function updateSuffix(update: string, state: "available" | "installed"): string;
+/** The one-time message for each update state. */
+export declare function updateNotice(options: {
+    hostName: string;
+    command: string;
+    /** How to restart the host, in lower case. Defaults to `restart <hostName>`. */
+    restart?: string;
+    current: string;
+    update: string;
+    state: "available" | "installing" | "installed";
+}): string;
+/** Production inputs: npm, the marker file, and a detached script runner. */
+export declare function hostSelfUpdateDeps(options: {
+    logLabel: string;
+    currentVersion: string;
+    command: string;
+    args: string[];
+    markerPath: string;
+    /** The file of the running module. The installed copies are found from it. */
+    modulePath: string;
+    installSource: () => HostInstallSource;
+    log: HostSelfUpdateDeps["log"];
+    env?: NodeJS.ProcessEnv;
+}): HostSelfUpdateDeps;

package/dist/services/host-self-update.js

@@ -0,0 +1,254 @@
+import { spawn } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { installedVersions } from "./host-copies.js";
+import { availableUpdate, latestNpmVersion } from "./update-check.js";
+import { compareVersions } from "./version-compare.js";
+// Pi and OpenCode install OMMS from npm, but neither updates its plugins by
+// itself. At session start OMMS compares the running copy with npm `latest`
+// and, when it is older, runs the host's own update command in a detached
+// process. That process writes the result into a marker file, which the
+// running plugin reads to tell the user to restart. Claude Code has its own
+// module (`src/adapters/claude-code/plugin-self-update.ts`).
+/** A second session does not start another update for the same release within this time. */
+export const HOST_SELF_UPDATE_RETRY_MS = 30 * 60 * 1000;
+/** How often a running plugin reads the marker while an update is pending. */
+export const HOST_UPDATE_POLL_MS = 60 * 1000;
+/** How long a running plugin reads the marker before it gives up. */
+export const HOST_UPDATE_POLL_LIMIT_MS = 10 * 60 * 1000;
+/** The longest time the detached process lets the host command run. */
+const HOST_COMMAND_TIMEOUT_MS = 120_000;
+/**
+ * Node or Bun script that runs the host command, then records the outcome in
+ * the marker. Arguments: marker path, marker JSON, command, command args.
+ * `BUN_BE_BUN` lets a compiled Bun host (OpenCode) run this script; the host
+ * command must not inherit it.
+ */
+const UPDATE_SCRIPT = `
+const { spawnSync } = require("node:child_process");
+const { writeFileSync } = require("node:fs");
+const [markerPath, markerJson, command, ...args] = process.argv.slice(1);
+const env = { ...process.env };
+delete env.BUN_BE_BUN;
+let ok = false;
+try {
+  const run = spawnSync(command, args, {
+    stdio: "ignore",
+    shell: process.platform === "win32",
+    windowsHide: true,
+    timeout: ${HOST_COMMAND_TIMEOUT_MS},
+    env,
+  });
+  ok = run.status === 0;
+} catch {}
+const marker = JSON.parse(markerJson);
+writeFileSync(markerPath, JSON.stringify({ ...marker, outcome: ok ? "installed" : "failed", finishedAt: Date.now() }));
+`;
+/** Arguments for the script runner (`node` or Bun) that runs the host command detached. */
+export function hostUpdateRunnerArgs(markerPath, marker, command, args) {
+    return ["-e", UPDATE_SCRIPT, markerPath, JSON.stringify(marker), command, ...args];
+}
+/** Start a background host update when npm has a newer release. Never throws. */
+export async function startHostSelfUpdate(deps) {
+    const result = await decide(deps);
+    if (result.code === "started" || result.code === "spawn-failed") {
+        try {
+            await deps.log(deps.logLabel, {
+                code: result.code,
+                current: deps.currentVersion,
+                latest: result.update,
+            });
+        }
+        catch {
+            // A failed log write must not change the update result.
+        }
+    }
+    return result;
+}
+async function decide(deps) {
+    if (!deps.enabled)
+        return { code: "disabled", update: null };
+    const latest = await latestNpmVersion(deps.fetch);
+    if (latest === null)
+        return { code: "unreachable", update: null };
+    const update = availableUpdate(deps.currentVersion, latest);
+    if (!update)
+        return { code: "current", update: null };
+    let source;
+    try {
+        source = deps.installSource();
+    }
+    catch {
+        source = "pinned";
+    }
+    if (source !== "npm")
+        return { code: source, update };
+    const marker = deps.readMarker();
+    const now = deps.now();
+    if (marker?.version === update && now - marker.startedAt <= HOST_SELF_UPDATE_RETRY_MS) {
+        return { code: "recent", update };
+    }
+    const started = { version: update, startedAt: now };
+    try {
+        // Write first, so a session that starts during the update does not start another.
+        deps.writeMarker(started);
+        deps.spawnDetached(process.execPath, hostUpdateRunnerArgs(deps.markerPath, started, deps.command, deps.args));
+    }
+    catch {
+        return { code: "spawn-failed", update };
+    }
+    return { code: "started", update };
+}
+/** The state of the update for `version` that the marker records, or null. */
+export function markerStatus(marker, version) {
+    if (!marker || marker.version !== version)
+        return null;
+    return marker.outcome ?? "pending";
+}
+/**
+ * `installed` holds only when a copy on disk has the release (or a newer one,
+ * when a release landed during the update). The host command can exit with 0
+ * and install nothing; that outcome reads as `failed`. Other states pass through.
+ */
+export function confirmedStatus(status, version, installed) {
+    if (status !== "installed")
+        return status;
+    const found = installed.some((have) => have === version || (compareVersions(have, version) ?? -1) >= 0);
+    return found ? "installed" : "failed";
+}
+/** The marker's state for `version`, with `installed` confirmed against the copies on disk. */
+export function hostUpdateStatus(deps, version) {
+    return confirmedStatus(markerStatus(deps.readMarker(), version), version, deps.installedVersions());
+}
+/** Read a marker file. A missing, unreadable or malformed file is no marker. */
+export function readMarkerFile(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof value.version !== "string" || typeof value.startedAt !== "number")
+            return null;
+        const marker = { version: value.version, startedAt: value.startedAt };
+        if (value.outcome === "installed" || value.outcome === "failed") {
+            marker.outcome = value.outcome;
+            if (typeof value.finishedAt === "number")
+                marker.finishedAt = value.finishedAt;
+        }
+        return marker;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the marker now, then every `intervalMs` until it holds an outcome or
+ * `maxMs` passes. Calls `onSettled` once with the outcome. Returns a stop function.
+ */
+export function watchHostUpdate(options) {
+    const intervalMs = options.intervalMs ?? HOST_UPDATE_POLL_MS;
+    const deadline = Date.now() + (options.maxMs ?? HOST_UPDATE_POLL_LIMIT_MS);
+    let timer;
+    let done = false;
+    const stop = () => {
+        done = true;
+        if (timer)
+            clearInterval(timer);
+    };
+    const check = () => {
+        if (done)
+            return;
+        const status = options.read();
+        if (status === "installed" || status === "failed") {
+            stop();
+            options.onSettled(status);
+        }
+        else if (Date.now() >= deadline) {
+            stop();
+        }
+    };
+    check();
+    if (!done) {
+        timer = setInterval(check, intervalMs);
+        timer.unref?.();
+    }
+    return stop;
+}
+/** True when the module file sits in an npm install of om-memory-system. */
+export function installedFromNpm(modulePath) {
+    return modulePath.replaceAll("\\", "/").includes("/node_modules/om-memory-system/");
+}
+/**
+ * True when the module sits in a host package cache folder named
+ * `om-memory-system` or `om-memory-system@latest`. Any other folder, such as
+ * one with a version, counts as pinned. OpenCode 2.2 adds a timestamp folder
+ * between that folder and `node_modules`.
+ */
+export function unpinnedCacheFolder(modulePath) {
+    const parts = modulePath.replaceAll("\\", "/").split("/");
+    const index = parts.lastIndexOf("node_modules");
+    if (index < 1 || parts[index + 1] !== "om-memory-system")
+        return false;
+    const above = parts[index - 1];
+    const folder = /^\d+$/.test(above) ? parts[index - 2] : above;
+    return folder === "om-memory-system" || folder === "om-memory-system@latest";
+}
+/**
+ * True when a settings file lists `npm:om-memory-system` in `packages` with no
+ * version. A file that cannot be read, or an entry with a version, counts as pinned.
+ */
+export function unpinnedPackageSource(settingsText) {
+    if (settingsText === null)
+        return false;
+    let packages;
+    try {
+        packages = JSON.parse(settingsText).packages;
+    }
+    catch {
+        return false;
+    }
+    if (!Array.isArray(packages))
+        return false;
+    return packages.some((entry) => {
+        const source = typeof entry === "string" ? entry : entry?.source;
+        return source === "npm:om-memory-system";
+    });
+}
+/** Footer text after the status glyph: a newer release, or one installed and waiting for a restart. */
+export function updateSuffix(update, state) {
+    return state === "installed" ? ` · ${update} installed, restart` : ` · ${update} available`;
+}
+/** The one-time message for each update state. */
+export function updateNotice(options) {
+    const { hostName, command, current, update, state } = options;
+    const restart = options.restart ?? `restart ${hostName}`;
+    if (state === "installing")
+        return `om-memory-system ${update} is installing in the background.`;
+    if (state === "installed")
+        return `om-memory-system ${update} installed. ${restart[0].toUpperCase()}${restart.slice(1)} to use it.`;
+    return `om-memory-system ${update} is available (running ${current}). Run: ${command}, then ${restart}.`;
+}
+/** Production inputs: npm, the marker file, and a detached script runner. */
+export function hostSelfUpdateDeps(options) {
+    const env = options.env ?? process.env;
+    const { modulePath, ...rest } = options;
+    return {
+        ...rest,
+        enabled: env.OMMS_DISABLE_UPDATE_CHECK !== "1",
+        fetch: globalThis.fetch.bind(globalThis),
+        now: Date.now,
+        readMarker: () => readMarkerFile(options.markerPath),
+        installedVersions: () => installedVersions(modulePath),
+        writeMarker: (value) => {
+            mkdirSync(dirname(options.markerPath), { recursive: true });
+            writeFileSync(options.markerPath, JSON.stringify(value));
+        },
+        spawnDetached: (command, args) => {
+            const child = spawn(command, args, {
+                detached: true,
+                stdio: "ignore",
+                windowsHide: true,
+                env: { ...env, BUN_BE_BUN: "1" },
+            });
+            child.on("error", () => { });
+            child.unref();
+        },
+    };
+}

package/dist/services/space-routes.d.ts

@@ -7,6 +7,15 @@ import { type SpaceErrorCode } from "./spaces/registry.js";
  */
 type Body = Record<string, unknown>;
 export declare const STATUS_BY_CODE: Record<SpaceErrorCode | "transfer-busy", number>;
+/** Starts a program with arguments, without a shell. Tests inject a fake. */
+export type FolderOpener = (command: string, args: string[]) => Promise<void>;
+/** What a spaces request carries besides its path. */
+export interface SpaceRouteOptions {
+    /** Peer address of the caller. Only a loopback caller may start a file manager. */
+    remoteAddress?: string;
+    /** Starts the platform file manager. Defaults to the real one; tests inject a recorder. */
+    startOpener?: FolderOpener;
+}
 /** What the status call reports: the space this process uses now. */
 export declare function spaceStatus(directory: string): {
     problem?: string | undefined;
@@ -14,5 +23,5 @@ export declare function spaceStatus(directory: string): {
     name: string;
     customStoragePath: boolean;
 };
-export declare function routeSpaces(path: string, method: string, readBody: () => Promise<Body>, cwd: string): Promise<RouteResult | undefined>;
+export declare function routeSpaces(path: string, method: string, readBody: () => Promise<Body>, cwd: string, options?: SpaceRouteOptions): Promise<RouteResult | undefined>;
 export {};