om-memory-system 4.4.0-next.67 → 4.4.0-next.70

package/dist/services/global-version.js

@@ -1,11 +1,6 @@
-import { execFile } from "node:child_process";
-import { accessSync, constants } from "node:fs";
-import { delimiter, isAbsolute, join } from "node:path";
-const TIMEOUT_MS = 3_000;
-const CACHE_MS = 10 * 60_000;
-const run = (file, args, options) => new Promise((resolve, reject) => {
-    execFile(file, args, { ...options, encoding: "utf8" }, (error, stdout) => error ? reject(error) : resolve(String(stdout)));
-});
+import { accessSync, constants, readFileSync, realpathSync } from "node:fs";
+import { delimiter, dirname, isAbsolute, join } from "node:path";
+import { compareVersions } from "./version-compare.js";
 function executable(path) {
     try {
         accessSync(path, constants.X_OK);
@@ -31,48 +26,83 @@ export function findGlobalCommand(env = process.env, platform = process.platform
     }
     return null;
 }
+/** The package folder of the install the command belongs to, or null. */
+function packageFolder(command, platform) {
+    // npm's Windows layout: the wrapper sits beside node_modules.
+    if (platform === "win32")
+        return join(dirname(command), "node_modules", "om-memory-system");
+    let dir = dirname(realpathSync(command));
+    for (;;) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+            if (pkg.name === "om-memory-system")
+                return dir;
+        }
+        catch {
+            /* Try the parent. */
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
 /**
- * The command and arguments that print the version without a user-controlled
- * shell. A Windows `.cmd` wrapper can only run through cmd.exe, so it runs
- * through the system's own cmd.exe with fixed arguments.
+ * Where a global npm install can be for a Node.js binary, the same places the
+ * launcher looks. Homebrew runs Node from a versioned `Cellar/node/<version>`
+ * folder, but npm installs under the prefix above `Cellar`.
  */
-export function versionInvocation(path, platform = process.platform, env = process.env) {
-    if (platform === "win32" && path.toLowerCase().endsWith(".cmd")) {
-        const cmd = env.SystemRoot ? `${env.SystemRoot}\\System32\\cmd.exe` : "cmd.exe";
-        return { file: cmd, args: ["/d", "/s", "/c", `"${path}" --version`] };
-    }
-    return { file: path, args: ["--version"] };
+function installsBesideRuntime(execPath, platform) {
+    if (!execPath)
+        return [];
+    if (platform === "win32")
+        return [join(dirname(execPath), "node_modules", "om-memory-system")];
+    const direct = join(dirname(dirname(execPath)), "lib", "node_modules", "om-memory-system");
+    const brew = /^(.*)[\\/]Cellar[\\/][^\\/]+[\\/][^\\/]+[\\/]bin[\\/][^\\/]+$/.exec(execPath);
+    return brew ? [direct, join(brew[1], "lib", "node_modules", "om-memory-system")] : [direct];
 }
-let cached = null;
-/** Look up the global command's version, at most once every 10 minutes. */
-export async function globalCommandVersion(options = {}) {
-    const now = (options.now ?? Date.now)();
-    if (cached && now - cached.at < CACHE_MS)
-        return cached.value;
+/** The version in an install's `package.json`, or null when it is not an OMMS install. */
+function installVersion(folder) {
+    const pkg = JSON.parse(readFileSync(join(folder, "package.json"), "utf8"));
+    return pkg.name === "om-memory-system" && typeof pkg.version === "string" ? pkg.version : null;
+}
+/**
+ * The global command's version, read from its install's `package.json`. The
+ * command does not run: after a hand-off it would print the newest copy's version.
+ * The login item runs with a minimal PATH, so with no command on PATH the install
+ * beside the running Node.js counts too.
+ */
+export function globalCommandVersion(options = {}) {
+    const platform = options.platform ?? process.platform;
     const path = (options.find ?? (() => findGlobalCommand()))();
-    let value;
     if (!path) {
-        value = { version: null, path: null };
-    }
-    else {
-        const { file, args } = versionInvocation(path, options.platform);
-        try {
-            const output = await (options.runner ?? run)(file, args, {
-                timeout: TIMEOUT_MS,
-                windowsHide: true,
-                shell: false,
-            });
-            const version = /\d+\.\d+\.\d+(?:[-+][\w.]+)?/.exec(output)?.[0] ?? null;
-            value = version ? { version, path } : { version: null, path, error: "failed" };
-        }
-        catch (error) {
-            const killed = error.killed;
-            value = { version: null, path, error: killed ? "timeout" : "failed" };
+        for (const folder of installsBesideRuntime(options.execPath ?? process.execPath, platform)) {
+            try {
+                const version = installVersion(folder);
+                if (version)
+                    return { version, path: folder };
+            }
+            catch {
+                /* No install there. */
+            }
         }
+        return { version: null, path: null };
+    }
+    try {
+        const folder = packageFolder(path, platform);
+        const version = folder ? installVersion(folder) : null;
+        return version ? { version, path } : { version: null, path, error: "failed" };
+    }
+    catch {
+        return { version: null, path, error: "failed" };
     }
-    cached = { at: now, value };
-    return value;
 }
-export function resetGlobalVersionCache() {
-    cached = null;
+/** How the global install compares with the running OMMS. */
+export function globalRelation(running, global) {
+    if (global === null)
+        return "missing";
+    const order = compareVersions(global, running);
+    if (order === null)
+        return "unknown";
+    return order === 0 ? "same" : order < 0 ? "older" : "newer";
 }

package/dist/services/runtime-handoff.d.ts

@@ -0,0 +1,60 @@
+import { type RegisterResult, type RuntimeCopy, type RuntimeLog } from "./runtime-record.js";
+export declare const ommsDir: (home?: string) => string;
+/** The package folder of the running copy, found from source or `dist/`. */
+export declare function ownPackageRoot(from?: string): string | null;
+/**
+ * Record the running copy when it is the newest. A failure is logged with a
+ * code and never thrown, so it cannot stop a session or a command.
+ */
+export declare function registerOwnCopy(options?: {
+    dir?: string;
+    root?: string | null;
+    log?: RuntimeLog;
+}): RegisterResult;
+export interface HandoffOptions {
+    dir?: string;
+    ownRoot?: string | null;
+    ownVersion?: string;
+    env?: NodeJS.ProcessEnv;
+    log?: RuntimeLog;
+    /** Injected so tests run no process. Resolves to the exit code, or null when the copy cannot start. */
+    spawn?: (command: string, args: string[], env: NodeJS.ProcessEnv) => Promise<number | null>;
+}
+/** The recorded copy this command must hand off to, or null. */
+export declare function handoffTarget(options: HandoffOptions & {
+    ownVersion: string;
+}): RuntimeCopy | null;
+/**
+ * The first step of the `om-memory-system` command. When the record names a
+ * newer valid copy, run that copy's command with the same arguments and return
+ * its exit code. Otherwise record this copy and return null, and the command
+ * continues with its own code. `OMMS_HANDED_OFF` stops a loop when two records disagree.
+ */
+export declare function handOffOrRegister(argv: string[], options?: HandoffOptions): Promise<number | null>;
+/** The version of the newest valid recorded copy, or null. This is the version a launcher start runs. */
+export declare function newestRecordedVersion(options?: {
+    dir?: string;
+    log?: RuntimeLog;
+}): string | null;
+/** What `ensureWebApp` needs to replace an older running web app. */
+export interface ReplaceOlder {
+    version: string;
+    headers: Record<string, string>;
+}
+/** The browser password settings a web app request needs, as `CONFIG` holds them. */
+export interface BasicAuthSettings {
+    webServerAuthPassword?: string;
+    webServerAuthUsername?: string;
+}
+/**
+ * Headers for the version lookup and the step-aside request. They carry the local
+ * token, and Basic Auth when a browser password is set: the web server checks Basic
+ * Auth first and refuses every other API request without it.
+ */
+export declare function replaceHeaders(token: string, settings?: BasicAuthSettings): Promise<Record<string, string>>;
+/**
+ * For a host start: record this copy, then name the version a running web app
+ * must reach. A web app older than it is asked to step aside. Without a
+ * recorded copy there is no target, so any running web app is used.
+ */
+export declare function hostReplaceOlder(settings?: BasicAuthSettings): Promise<ReplaceOlder | undefined>;

package/dist/services/runtime-handoff.js

@@ -0,0 +1,134 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { recordedCopy, registerCopy, } from "./runtime-record.js";
+import { compareVersions } from "./version-compare.js";
+// The newest-copy rule for the terminal command and the hosts: an old command
+// hands off to a newer recorded copy, and every copy that runs records itself.
+// Like `runtime-record.ts`, it imports no config.
+export const ommsDir = (home = homedir()) => join(home, ".omms");
+/** The package folder of the running copy, found from source or `dist/`. */
+export function ownPackageRoot(from = import.meta.url) {
+    let dir = dirname(fileURLToPath(from));
+    for (;;) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+            if (pkg.name === "om-memory-system")
+                return dir;
+        }
+        catch {
+            /* Try the parent. */
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** Log a code through the shared logger. A host calls this after its config is loaded. */
+const logCode = (code, data) => {
+    void import("./logger.js")
+        .then(({ log }) => log("Runtime record", { code, ...data }))
+        .catch(() => { });
+};
+/**
+ * Record the running copy when it is the newest. A failure is logged with a
+ * code and never thrown, so it cannot stop a session or a command.
+ */
+export function registerOwnCopy(options = {}) {
+    const root = options.root === undefined ? ownPackageRoot() : options.root;
+    if (!root)
+        return "skipped";
+    // Tests set this so that starting the real CLI never writes the developer's real record.
+    if (options.dir === undefined && process.env.OMMS_DISABLE_RUNTIME_RECORD === "1")
+        return "skipped";
+    try {
+        return registerCopy({ dir: options.dir ?? ommsDir(), root, log: options.log ?? logCode });
+    }
+    catch {
+        return "failed";
+    }
+}
+/**
+ * Run the child and resolve to its exit code, or null when it could not start.
+ * Standard input, output, and error flow through.
+ */
+function spawnCopy(command, args, env) {
+    return new Promise((resolve) => {
+        const child = nodeSpawn(command, args, { stdio: "inherit", env });
+        child.on("error", () => resolve(null));
+        child.on("close", (code) => resolve(code ?? 1));
+    });
+}
+/** The recorded copy this command must hand off to, or null. */
+export function handoffTarget(options) {
+    const env = options.env ?? process.env;
+    if (env.OMMS_NO_HANDOFF === "1" || env.OMMS_HANDED_OFF)
+        return null;
+    const copy = recordedCopy(options.dir ?? ommsDir(), options.log ?? logCode);
+    if (!copy || copy.root === options.ownRoot)
+        return null;
+    return (compareVersions(copy.version, options.ownVersion) ?? 0) > 0 ? copy : null;
+}
+/**
+ * The first step of the `om-memory-system` command. When the record names a
+ * newer valid copy, run that copy's command with the same arguments and return
+ * its exit code. Otherwise record this copy and return null, and the command
+ * continues with its own code. `OMMS_HANDED_OFF` stops a loop when two records disagree.
+ */
+export async function handOffOrRegister(argv, options = {}) {
+    const ownRoot = options.ownRoot === undefined ? ownPackageRoot() : options.ownRoot;
+    let ownVersion = options.ownVersion;
+    if (ownVersion === undefined) {
+        const { packageVersion } = await import("./package-version.js");
+        ownVersion = packageVersion();
+    }
+    const target = handoffTarget({ ...options, ownRoot, ownVersion });
+    if (target) {
+        const run = options.spawn ?? spawnCopy;
+        const code = await run(process.execPath, [join(target.root, "dist", "cli", "index.js"), ...argv], { ...(options.env ?? process.env), OMMS_HANDED_OFF: "1" });
+        if (code !== null)
+            return code;
+    }
+    registerOwnCopy({ dir: options.dir, root: ownRoot, log: options.log });
+    return null;
+}
+/** The version of the newest valid recorded copy, or null. This is the version a launcher start runs. */
+export function newestRecordedVersion(options = {}) {
+    return recordedCopy(options.dir ?? ommsDir(), options.log ?? logCode)?.version ?? null;
+}
+/**
+ * Headers for the version lookup and the step-aside request. They carry the local
+ * token, and Basic Auth when a browser password is set: the web server checks Basic
+ * Auth first and refuses every other API request without it.
+ */
+export async function replaceHeaders(token, settings = {}) {
+    const { AUTH_HEADER } = await import("./auth-token.js");
+    const headers = { [AUTH_HEADER]: token };
+    const password = (settings.webServerAuthPassword ?? "").trim();
+    if (!password)
+        return headers;
+    const { WebAuth } = await import("./web-auth.js");
+    const { username } = new WebAuth({
+        password,
+        username: settings.webServerAuthUsername,
+    }).getConfig();
+    headers.authorization = `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`;
+    return headers;
+}
+/**
+ * For a host start: record this copy, then name the version a running web app
+ * must reach. A web app older than it is asked to step aside. Without a
+ * recorded copy there is no target, so any running web app is used.
+ */
+export async function hostReplaceOlder(settings = {}) {
+    registerOwnCopy();
+    const version = newestRecordedVersion();
+    if (!version)
+        return undefined;
+    const { getOrCreateAuthToken } = await import("./auth-token.js");
+    // The web app runs on this machine, so the local token file is enough.
+    return { version, headers: await replaceHeaders(getOrCreateAuthToken(), settings) };
+}

package/dist/services/runtime-record.d.ts

@@ -0,0 +1,47 @@
+export interface RuntimeRecord {
+    root: string;
+    version: string;
+    updatedAt: string;
+}
+/** A valid copy: its package folder and the version in its `package.json`. */
+export interface RuntimeCopy {
+    root: string;
+    version: string;
+}
+/** A log call carries a code and identifiers only, never a path or file text. */
+export type RuntimeLog = (code: string, data: Record<string, unknown>) => void;
+export type RegisterResult = "written" | "kept" | "skipped" | "failed";
+export declare const recordPath: (dir: string) => string;
+export declare const launcherPath: (dir: string) => string;
+/**
+ * The version of a valid OMMS copy, or null. A copy is valid when its
+ * `package.json` names `om-memory-system`, its version can be compared, and it
+ * has `dist/cli/index.js`.
+ */
+export declare function copyVersion(root: string): string | null;
+/** The record as written, or null. A missing record is normal; any other failure logs a code. */
+export declare function readRuntimeRecord(dir: string, log?: RuntimeLog): RuntimeRecord | null;
+/** The copy the record names, when it is still valid. The version is read from its `package.json`. */
+export declare function recordedCopy(dir: string, log?: RuntimeLog): RuntimeCopy | null;
+/**
+ * Make sure a launcher exists at `~/.omms/bin`. An existing launcher stays, so an
+ * older copy never replaces it. When it is missing, the first source with a
+ * `bin/omms-launch.mjs` provides it. Returns whether a launcher exists afterwards.
+ */
+export declare function ensureLauncher(options: {
+    dir: string;
+    sources: readonly (string | null | undefined)[];
+    log?: RuntimeLog;
+}): boolean;
+/**
+ * Record this copy when the record is missing, names a copy that is no longer
+ * valid, or names an older version. An equal version keeps the record. The copy
+ * that holds the record also keeps the launcher at `~/.omms/bin`. A failure is
+ * logged with a code and never thrown.
+ */
+export declare function registerCopy(options: {
+    dir: string;
+    root: string;
+    log?: RuntimeLog;
+    now?: () => Date;
+}): RegisterResult;

package/dist/services/runtime-record.js

@@ -0,0 +1,143 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { compareVersions } from "./version-compare.js";
+export const recordPath = (dir) => join(dir, "runtime.json");
+export const launcherPath = (dir) => join(dir, "bin", "omms-launch.mjs");
+/**
+ * The version of a valid OMMS copy, or null. A copy is valid when its
+ * `package.json` names `om-memory-system`, its version can be compared, and it
+ * has `dist/cli/index.js`.
+ */
+export function copyVersion(root) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        if (pkg.name !== "om-memory-system" || typeof pkg.version !== "string")
+            return null;
+        if (compareVersions(pkg.version, pkg.version) === null)
+            return null;
+        return existsSync(join(root, "dist", "cli", "index.js")) ? pkg.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The record as written, or null. A missing record is normal; any other failure logs a code. */
+export function readRuntimeRecord(dir, log) {
+    let text;
+    try {
+        text = readFileSync(recordPath(dir), "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            log?.("runtime-record-read-failed", { reason: "read" });
+        return null;
+    }
+    try {
+        const value = JSON.parse(text);
+        if (!value ||
+            typeof value.root !== "string" ||
+            typeof value.version !== "string" ||
+            typeof value.updatedAt !== "string")
+            throw new Error("shape");
+        return { root: value.root, version: value.version, updatedAt: value.updatedAt };
+    }
+    catch {
+        log?.("runtime-record-read-failed", { reason: "parse" });
+        return null;
+    }
+}
+/** The copy the record names, when it is still valid. The version is read from its `package.json`. */
+export function recordedCopy(dir, log) {
+    const record = readRuntimeRecord(dir, log);
+    if (!record)
+        return null;
+    const version = copyVersion(record.root);
+    return version ? { root: record.root, version } : null;
+}
+/** Write a file in one step, so a reader never finds a partial file. */
+function writeAtomic(path, write) {
+    const temp = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    try {
+        write(temp);
+        renameSync(temp, path);
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+}
+function sameFile(a, b) {
+    try {
+        return readFileSync(a).equals(readFileSync(b));
+    }
+    catch {
+        return false;
+    }
+}
+/** Put the copy's launcher at the fixed path when it is missing or different. */
+function placeLauncher(dir, root, log) {
+    const source = join(root, "bin", "omms-launch.mjs");
+    if (!existsSync(source))
+        return;
+    const target = launcherPath(dir);
+    if (sameFile(source, target))
+        return;
+    try {
+        mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+        writeAtomic(target, (temp) => copyFileSync(source, temp));
+    }
+    catch {
+        log?.("runtime-launcher-write-failed", {});
+    }
+}
+/**
+ * Make sure a launcher exists at `~/.omms/bin`. An existing launcher stays, so an
+ * older copy never replaces it. When it is missing, the first source with a
+ * `bin/omms-launch.mjs` provides it. Returns whether a launcher exists afterwards.
+ */
+export function ensureLauncher(options) {
+    const target = launcherPath(options.dir);
+    if (existsSync(target))
+        return true;
+    for (const root of options.sources) {
+        if (root)
+            placeLauncher(options.dir, root, options.log);
+        if (existsSync(target))
+            return true;
+    }
+    return false;
+}
+/**
+ * Record this copy when the record is missing, names a copy that is no longer
+ * valid, or names an older version. An equal version keeps the record. The copy
+ * that holds the record also keeps the launcher at `~/.omms/bin`. A failure is
+ * logged with a code and never thrown.
+ */
+export function registerCopy(options) {
+    const { dir, root, log } = options;
+    const own = copyVersion(root);
+    if (!own)
+        return "skipped";
+    try {
+        const current = recordedCopy(dir, log);
+        const newer = !current || (compareVersions(own, current.version) ?? 0) > 0;
+        if (!newer) {
+            // The recorded copy owns the launcher, so it repairs a missing or damaged one.
+            if (current?.root === root)
+                placeLauncher(dir, root, log);
+            return "kept";
+        }
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const record = {
+            root,
+            version: own,
+            updatedAt: (options.now?.() ?? new Date()).toISOString(),
+        };
+        writeAtomic(recordPath(dir), (temp) => writeFileSync(temp, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 }));
+        placeLauncher(dir, root, log);
+        return "written";
+    }
+    catch {
+        log?.("runtime-record-write-failed", {});
+        return "failed";
+    }
+}

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

@@ -0,0 +1,4 @@
+/** The `latest` version on npm, or null when the registry cannot be reached. */
+export declare function latestNpmVersion(fetchFn: typeof fetch, timeoutMs?: number): Promise<string | null>;
+/** A newer release than `current`, ignoring prereleases; null otherwise. */
+export declare function availableUpdate(current: string, latest: string | null): string | null;

package/dist/services/update-check.js

@@ -0,0 +1,23 @@
+import { isOlderVersion } from "./version-compare.js";
+/** The `latest` version on npm, or null when the registry cannot be reached. */
+export async function latestNpmVersion(fetchFn, timeoutMs = 5_000) {
+    try {
+        const response = await fetchFn("https://registry.npmjs.org/om-memory-system/latest", {
+            signal: AbortSignal.timeout(timeoutMs),
+            headers: { accept: "application/json" },
+        });
+        if (!response.ok)
+            return null;
+        const body = (await response.json());
+        return typeof body.version === "string" ? body.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A newer release than `current`, ignoring prereleases; null otherwise. */
+export function availableUpdate(current, latest) {
+    if (!latest || latest.includes("-"))
+        return null;
+    return isOlderVersion(current, latest) ? latest : null;
+}

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

@@ -1,10 +1,13 @@
 import { CONFIG } from "../config.js";
-type State = "installed" | "not-installed" | "unsupported" | "no-runtime" | "no-package";
+type State = "installed" | "not-installed" | "unsupported" | "no-runtime" | "no-package" | "no-launcher";
 export type WebAutostartStatus = {
     state: State;
     path?: string;
     runtime?: string;
+    /** The copy the launcher starts now: the newest of the record, the global install, and this copy. */
     packagePath?: string;
+    /** The fixed launcher the item runs, `~/.omms/bin/omms-launch.mjs`. */
+    launcher?: string;
     command?: string;
 };
 export interface WebAutostartOptions {
@@ -12,19 +15,18 @@ export interface WebAutostartOptions {
     platform?: string;
     runtime?: string | null;
     packageRoot?: string | null;
+    /** The running copy, a launcher source when the chosen copy has none. Defaults to `packageRoot`, then this copy. */
+    ownRoot?: string | null;
     systemctlAvailable?: boolean;
     run?: (command: string, args: string[]) => void;
     start?: boolean;
 }
 /** OpenCode's executable is not a JavaScript runtime. */
 export declare function resolveWebRuntime(execPath?: string, platform?: NodeJS.Platform): string | null;
-/** The package folder a written login item runs, read back from its command line. */
-export declare function itemPackageRoot(file: string): string | null;
 /**
- * The newest OMMS copy among this one, the global install beside the runtime,
- * and the copy the item already runs. A host starts OMMS from its own cache,
- * which can be older than the global install; that copy must not downgrade
- * the login item.
+ * The newest valid OMMS copy among the candidates. On equal versions the first
+ * wins, so a host's cached copy goes last. This is the copy the launcher starts,
+ * and it matches the launcher's own choice.
  */
 export declare function preferredPackageRoot(candidates: readonly (string | null | undefined)[]): string | null;
 /** Read the login item's state without changing any system files. */