@mnemom/mnemom 0.17.2-next.7 → 0.17.2-next.8

package/dist/lib/update/system.js

@@ -0,0 +1,104 @@
+/**
+ * The real-world side of the updater: spawn npm, read credentials, read prefs.
+ * Each function takes its process-level dependencies as injectable parameters
+ * so the branches are testable without touching the machine.
+ */
+import { execFile as nodeExecFile } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { win32 } from "node:path";
+import { getAuthInfo, resolveAuth } from "../auth.js";
+import { loadCliConfig } from "../cli-config.js";
+import { PACKAGE_NAME } from "./decide.js";
+import { isValidVersion } from "./semver.js";
+export const INSTALL_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * Never `shell: true` (npm's registry-/header-derived arguments must not reach
+ * a shell). POSIX runs `npm` directly. On Windows `npm` is a `.cmd` shim that
+ * can't be spawned without a shell, so run the npm CLI script with this node
+ * binary instead — it ships beside node.exe in every standard Windows install.
+ * No such script → null, and the caller treats npm as unavailable (notify only).
+ */
+export function npmInvocation(platform = process.platform, execPath = process.execPath, exists = existsSync) {
+    if (platform !== "win32")
+        return { file: "npm", prefix: [] };
+    const cli = win32.join(win32.dirname(execPath), "node_modules", "npm", "bin", "npm-cli.js");
+    return exists(cli) ? { file: execPath, prefix: [cli] } : null;
+}
+function run(inv, args, timeout, execFile) {
+    return new Promise((resolve) => {
+        execFile(inv.file, [...inv.prefix, ...args], { timeout, windowsHide: true }, (err, stdout, stderr) => resolve({ err, stdout: String(stdout ?? ""), stderr: String(stderr ?? "") }));
+    });
+}
+/** `npm root -g`, or undefined when npm isn't available / fails. */
+export async function npmGlobalRoot(execFile = nodeExecFile, inv = npmInvocation()) {
+    if (!inv)
+        return undefined;
+    const { err, stdout } = await run(inv, ["root", "-g"], 15_000, execFile);
+    const root = stdout.trim();
+    return err || !root ? undefined : root;
+}
+/** Permission failures can't be fixed by retrying — the caller switches to notify. */
+export function isPermissionError(text) {
+    return /\bE(ACCES|PERM)\b/.test(text);
+}
+/**
+ * `npm install -g @mnemom/mnemom@<exact version>` — exact, never a tag (no
+ * tag-move race). The version is re-validated here, at the sink, even though
+ * `pickTarget` already filtered it.
+ */
+export async function npmInstallGlobal(version, execFile = nodeExecFile, inv = npmInvocation()) {
+    if (!isValidVersion(version)) {
+        return {
+            ok: false,
+            eacces: false,
+            message: `refusing to install invalid version '${version}'`,
+        };
+    }
+    if (!inv)
+        return { ok: false, eacces: false, message: "npm is not available" };
+    const { err, stderr } = await run(inv, ["install", "-g", "--no-fund", "--no-audit", `${PACKAGE_NAME}@${version}`], INSTALL_TIMEOUT_MS, execFile);
+    if (!err)
+        return { ok: true };
+    const detail = `${err.message}\n${stderr}`;
+    const lastLine = stderr.trim().split("\n").pop() || err.message;
+    return { ok: false, eacces: isPermissionError(detail), message: lastLine.slice(0, 300) };
+}
+/** realpath of the entry script (the global bin is a symlink); falls back to the raw path. */
+export function entryRealpath(argv1, realpath = realpathSync) {
+    if (!argv1)
+        return "";
+    try {
+        return realpath(argv1);
+    }
+    catch {
+        return argv1;
+    }
+}
+/**
+ * Credential for the BACKGROUND worker. Deliberately never refreshes: a
+ * detached refresh racing a foreground command could rotate the refresh token
+ * out from under it. An expired stored token just means "unauthenticated" for
+ * this pass (the cached entitlement still applies).
+ */
+export function backgroundCredential(env = process.env, auth = getAuthInfo(), nowSec = Math.floor(Date.now() / 1000)) {
+    if (env.MNEMOM_TOKEN)
+        return { name: "Authorization", value: `Bearer ${env.MNEMOM_TOKEN}` };
+    if (auth && auth.expiresAt > nowSec + 60) {
+        return { name: "Authorization", value: `Bearer ${auth.accessToken}` };
+    }
+    if (env.MNEMOM_API_KEY)
+        return { name: "X-Mnemom-Api-Key", value: env.MNEMOM_API_KEY };
+    return null;
+}
+/** Credential for the FOREGROUND `mnemom update` — normal resolution, refresh allowed. */
+export async function foregroundCredential(resolve = resolveAuth) {
+    const cred = await resolve();
+    if (cred.type === "jwt")
+        return { name: "Authorization", value: `Bearer ${cred.token}` };
+    if (cred.type === "api-key")
+        return { name: "X-Mnemom-Api-Key", value: cred.key };
+    return null;
+}
+export function loadUpdatePrefs() {
+    return loadCliConfig().update ?? {};
+}

package/dist/lib/update/worker.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The detached background worker (entry: src/update-worker.ts) and the real
+ * `RunDeps` wiring shared with `mnemom update`.
+ *
+ * The parent passes the settings it resolved (`<entry> <channel> <mode> <pid>`): the
+ * worker runs with stdio ignored, so re-resolving here would always see a
+ * non-TTY and force `off`.
+ */
+import { type ResolvedSettings } from "./decide.js";
+import { type ApiCredential } from "./registry.js";
+import { type InstallResult, type RunDeps, type RunResult } from "./run.js";
+export interface WorkerArgs {
+    entry: string;
+    settings: ResolvedSettings;
+    /** The CLI process that spawned us; installs wait until it has exited. */
+    parentPid?: number;
+}
+export declare function parseWorkerArgs(args: string[]): WorkerArgs | null;
+export declare const PARENT_POLL_MS = 5000;
+/** Give up waiting on a very long session; the next run picks the update up. */
+export declare const PARENT_WAIT_MAX_MS: number;
+/** `kill(pid, 0)` probes liveness without signalling. EPERM still means alive. */
+export declare function isAlive(pid: number, kill?: (pid: number, sig: 0) => void): boolean;
+/** Resolve true once `pid` is gone, false if it outlives `maxMs`. */
+export declare function waitForExit(pid: number | undefined, deps?: {
+    alive(pid: number): boolean;
+    sleep(ms: number): Promise<void>;
+    now(): number;
+}, maxMs?: number): Promise<boolean>;
+export declare function realRunDeps(entry: string, credential: () => ApiCredential | Promise<ApiCredential>): RunDeps;
+/**
+ * The install lock is held ONLY around `npm install` — never while waiting for
+ * the parent to exit (a 12h wait would look stale at LOCK_STALE_MS and let a
+ * second installer in). Lock busy → skip this pass; the other installer wins.
+ */
+export declare function lockedInstall(parentPid: number | undefined, deps: {
+    waitForExit(pid: number | undefined): Promise<boolean>;
+    acquireLock(): (() => void) | null;
+    install(version: string): Promise<InstallResult>;
+}): Pick<RunDeps, "beforeInstall" | "install">;
+export declare function runWorker(args: string[], run: (args: WorkerArgs) => Promise<RunResult>): Promise<"bad-args" | RunResult>;
+export declare function defaultWorkerRun(credential: () => ApiCredential): (args: WorkerArgs) => Promise<RunResult>;

package/dist/lib/update/worker.js

@@ -0,0 +1,104 @@
+/**
+ * The detached background worker (entry: src/update-worker.ts) and the real
+ * `RunDeps` wiring shared with `mnemom update`.
+ *
+ * The parent passes the settings it resolved (`<entry> <channel> <mode> <pid>`): the
+ * worker runs with stdio ignored, so re-resolving here would always see a
+ * non-TTY and force `off`.
+ */
+import { CLI_VERSION } from "../../version.js";
+import { getApiUrl } from "../config.js";
+import { isUpdateChannel, isUpdateMode } from "./decide.js";
+import { classifyInstall } from "./install-method.js";
+import { fetchChannelEntitlement, fetchDistTags } from "./registry.js";
+import { runUpdate } from "./run.js";
+import { acquireLock, loadUpdateState, saveUpdateState } from "./state.js";
+import { npmGlobalRoot, npmInstallGlobal } from "./system.js";
+export function parseWorkerArgs(args) {
+    const [entry, channel, mode, pid] = args;
+    if (!entry || !isUpdateChannel(channel) || !isUpdateMode(mode))
+        return null;
+    const parentPid = Number.parseInt(pid ?? "", 10);
+    return { entry, settings: { channel, mode }, parentPid: parentPid > 0 ? parentPid : undefined };
+}
+export const PARENT_POLL_MS = 5000;
+/** Give up waiting on a very long session; the next run picks the update up. */
+export const PARENT_WAIT_MAX_MS = 12 * 60 * 60 * 1000;
+/** `kill(pid, 0)` probes liveness without signalling. EPERM still means alive. */
+export function isAlive(pid, kill = (p, s) => void process.kill(p, s)) {
+    try {
+        kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/** Resolve true once `pid` is gone, false if it outlives `maxMs`. */
+export async function waitForExit(pid, deps = {
+    alive: (p) => isAlive(p),
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    now: Date.now,
+}, maxMs = PARENT_WAIT_MAX_MS) {
+    if (pid === undefined)
+        return true;
+    const deadline = deps.now() + maxMs;
+    while (deps.alive(pid)) {
+        if (deps.now() >= deadline)
+            return false;
+        await deps.sleep(PARENT_POLL_MS);
+    }
+    return true;
+}
+export function realRunDeps(entry, credential) {
+    return {
+        current: CLI_VERSION,
+        now: Date.now,
+        loadState: () => loadUpdateState(),
+        saveState: (patch) => saveUpdateState(patch),
+        fetchDistTags: () => fetchDistTags(fetch),
+        fetchEntitlement: async () => fetchChannelEntitlement(fetch, getApiUrl(), await credential()),
+        installMethod: async () => classifyInstall(entry, await npmGlobalRoot()),
+        install: (version) => npmInstallGlobal(version),
+    };
+}
+/**
+ * The install lock is held ONLY around `npm install` — never while waiting for
+ * the parent to exit (a 12h wait would look stale at LOCK_STALE_MS and let a
+ * second installer in). Lock busy → skip this pass; the other installer wins.
+ */
+export function lockedInstall(parentPid, deps) {
+    let release = null;
+    return {
+        beforeInstall: async () => {
+            if (!(await deps.waitForExit(parentPid)))
+                return false;
+            release = deps.acquireLock();
+            return release !== null;
+        },
+        install: async (version) => {
+            try {
+                return await deps.install(version);
+            }
+            finally {
+                release?.();
+            }
+        },
+    };
+}
+export async function runWorker(args, run) {
+    const parsed = parseWorkerArgs(args);
+    if (!parsed)
+        return "bad-args";
+    return run(parsed);
+}
+export function defaultWorkerRun(credential) {
+    return ({ entry, settings, parentPid }) => runUpdate({
+        ...realRunDeps(entry, credential),
+        ...lockedInstall(parentPid, {
+            waitForExit: (pid) => waitForExit(pid),
+            acquireLock: () => acquireLock(),
+            install: (version) => npmInstallGlobal(version),
+        }),
+    }, settings);
+}

package/dist/lib/version-gate.d.ts

@@ -28,8 +28,9 @@ export declare function isBelowVersion(current: string, floor: string): boolean;
  *
  * @param exit  injectable for tests; defaults to process.exit
  * @param write injectable for tests; defaults to process.stderr.write
+ * @param upgrade injectable for tests; defaults to the auto-update floor upgrade
  */
-export declare function enforceMinCliVersion(response: Pick<Response, "headers">, exit?: (code: number) => never, write?: (chunk: string) => void): void;
+export declare function enforceMinCliVersion(response: Pick<Response, "headers">, exit?: (code: number) => never, write?: (chunk: string) => void, upgrade?: (floor: string) => boolean): void;
 /**
  * Drop-in wrapper around global fetch for Mnemom API calls: issues the request,
  * enforces the advertised minimum CLI version on the response, then returns it.

package/dist/lib/version-gate.js

@@ -14,6 +14,7 @@
  * wrong outcome.
  */
 import { CLI_VERSION } from "../version.js";
+import { defaultFloorUpgradeDeps, upgradeToFloor } from "./update/min-version.js";
 const MIN_CLI_HEADER = "x-mnemom-min-cli";
 /**
  * Compare dotted numeric versions. Returns true iff `current` is strictly below
@@ -53,8 +54,9 @@ let exited = false;
  *
  * @param exit  injectable for tests; defaults to process.exit
  * @param write injectable for tests; defaults to process.stderr.write
+ * @param upgrade injectable for tests; defaults to the auto-update floor upgrade
  */
-export function enforceMinCliVersion(response, exit = process.exit, write = (chunk) => void process.stderr.write(chunk)) {
+export function enforceMinCliVersion(response, exit = process.exit, write = (chunk) => void process.stderr.write(chunk), upgrade = (floor) => upgradeToFloor(floor, defaultFloorUpgradeDeps())) {
     // Defensive: some callers/tests provide a Response-like object without a real
     // Headers instance. Treat a missing/incompatible headers bag as "no floor".
     const headers = response?.headers;
@@ -66,6 +68,12 @@ export function enforceMinCliVersion(response, exit = process.exit, write = (chu
     if (exited)
         return;
     exited = true;
+    // Auto-update on + self-updatable install: fix it now, then ask for a re-run
+    // (this process is still the old code).
+    if (upgrade(floor)) {
+        write(`\n✓ Updated the Mnemom CLI (was v${CLI_VERSION}; server minimum v${floor}). Re-run your command.\n\n`);
+        exit(1);
+    }
     write(`\n✖ Your Mnemom CLI (v${CLI_VERSION}) is too old for this server (minimum v${floor}).\n` +
         `  Old CLIs can silently drop newer request fields — e.g. \`--org\` on \`mnemom agent claim\`.\n\n` +
         `  Upgrade:  npm i -g @mnemom/mnemom@latest\n\n`);

package/dist/update-worker.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Detached auto-update worker — spawned by lib/update/startup.ts with
+ * `<entry> <channel> <mode> <parent-pid>`. All logic lives in lib/update/worker.ts; this
+ * driver only wires the real process in and swallows every error.
+ */
+export {};

package/dist/update-worker.js

@@ -0,0 +1,8 @@
+/**
+ * Detached auto-update worker — spawned by lib/update/startup.ts with
+ * `<entry> <channel> <mode> <parent-pid>`. All logic lives in lib/update/worker.ts; this
+ * driver only wires the real process in and swallows every error.
+ */
+import { backgroundCredential } from "./lib/update/system.js";
+import { defaultWorkerRun, runWorker } from "./lib/update/worker.js";
+runWorker(process.argv.slice(2), defaultWorkerRun(() => backgroundCredential())).catch(() => { });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.17.2-next.7",
+  "version": "0.17.2-next.8",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {