homegraph 1.2.0 → 1.5.0

package/dist/upgrade/remove-binary.js

@@ -0,0 +1,289 @@
+"use strict";
+/**
+ * CLI binary removal for `homegraph uninstall` (the #1071 shadow, uninstall
+ * edition).
+ *
+ * Before this module, three disconnected paths each removed PART of an
+ * installation and none removed it all: `homegraph uninstall` swept agent
+ * configs only, `install.sh --uninstall` deleted the bundle only, and npm's
+ * `preuninstall` hook cleaned configs when npm removed its own package. A
+ * user with more than one install method (the common drift: npm first, the
+ * bundle later — or vice versa) ran `homegraph uninstall` and still had a
+ * working `homegraph` on PATH.
+ *
+ * This module makes `homegraph uninstall` complete: PLAN every binary
+ * install present on the machine (bundle layout(s), the npm global package,
+ * the bin-dir shim), then EXECUTE the removals. Split planner/executor with
+ * injected side effects, same convention as the upgrade orchestrator.
+ *
+ * Safety rules:
+ *   - A source checkout is REPORTED, never deleted — a git repo is the
+ *     user's working tree, not an "install".
+ *   - A project-local npm install is left alone — the project's
+ *     package.json owns it, not the machine-level uninstaller.
+ *   - On unix the default install dir (`~/.homegraph`) doubles as the
+ *     machine-level state dir (telemetry choice, daemon records, the
+ *     update-check cache) — only the install ARTIFACTS (`versions/`,
+ *     `current`) are removed there, never the whole dir. A dedicated
+ *     install dir (Windows `%LOCALAPPDATA%\homegraph`, or a custom
+ *     `HOMEGRAPH_INSTALL_DIR`) is removed wholesale.
+ *   - The bin-dir shim is removed only when it verifiably points into a
+ *     detected install dir — a user's unrelated `homegraph` file survives.
+ *   - Windows cannot DELETE a running exe but CAN rename it (the same
+ *     trick the in-place upgrade uses): a locked `node.exe` is renamed
+ *     aside and reported as a leftover for the user to delete after the
+ *     window closes, instead of failing the whole removal.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultProbes = defaultProbes;
+exports.planBinaryRemoval = planBinaryRemoval;
+exports.defaultRemoveDeps = defaultRemoveDeps;
+exports.executeBinaryRemoval = executeBinaryRemoval;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const child_process_1 = require("child_process");
+const index_1 = require("./index");
+function defaultProbes(filename) {
+    return {
+        filename,
+        platform: process.platform,
+        cwd: process.cwd(),
+        env: process.env,
+        homedir: os.homedir(),
+        exists: fs.existsSync,
+        readlink: (p) => {
+            try {
+                return fs.readlinkSync(p);
+            }
+            catch {
+                return null;
+            }
+        },
+        capture: (cmd, args) => {
+            const res = (0, child_process_1.spawnSync)(cmd, args, { encoding: 'utf8', windowsHide: true, timeout: 30_000 });
+            if (res.error || typeof res.status !== 'number')
+                return null;
+            return { code: res.status, stdout: res.stdout ?? '' };
+        },
+    };
+}
+/**
+ * Path math keyed on the TARGET platform (not the host) — same convention as
+ * `detectInstallMethod`, so the planner is deterministic when unit-tested with
+ * a win32 fixture on a POSIX host and vice versa. In production the probe's
+ * platform always matches the running host.
+ */
+function pathFor(platform) {
+    return platform === 'win32' ? path.win32 : path.posix;
+}
+/** The machine-level state dir that must survive an artifacts-only removal. */
+function stateDir(p) {
+    return pathFor(p.platform).join(p.homedir, '.homegraph');
+}
+/** Candidate bundle install dirs: the running binary's own, plus the defaults. */
+function installDirCandidates(p) {
+    const P = pathFor(p.platform);
+    const dirs = [];
+    const method = (0, index_1.detectInstallMethod)({
+        filename: p.filename,
+        platform: p.platform,
+        cwd: p.cwd,
+        exists: p.exists,
+    });
+    if (method.kind === 'bundle' && method.installDir)
+        dirs.push(method.installDir);
+    if (p.env.HOMEGRAPH_INSTALL_DIR)
+        dirs.push(p.env.HOMEGRAPH_INSTALL_DIR);
+    // Platform defaults — probed even when the RUNNING binary is npm/source,
+    // because the whole point is clearing installs the user forgot about.
+    if (p.platform === 'win32') {
+        if (p.env.LOCALAPPDATA)
+            dirs.push(P.join(p.env.LOCALAPPDATA, 'homegraph'));
+    }
+    else {
+        dirs.push(stateDir(p));
+    }
+    return [...new Set(dirs.map((d) => P.resolve(d)))];
+}
+function planBinaryRemoval(p) {
+    const P = pathFor(p.platform);
+    const plan = {
+        paths: [],
+        npmGlobal: false,
+        npmRoot: null,
+        sourceRoot: null,
+        summary: [],
+    };
+    const method = (0, index_1.detectInstallMethod)({
+        filename: p.filename,
+        platform: p.platform,
+        cwd: p.cwd,
+        exists: p.exists,
+    });
+    if (method.kind === 'source') {
+        plan.sourceRoot = method.root;
+    }
+    // --- Bundle install(s) ----------------------------------------------------
+    const installDirs = [];
+    for (const dir of installDirCandidates(p)) {
+        // A dir counts as a bundle install only when it carries install artifacts.
+        const artifacts = ['versions', 'current']
+            .map((a) => P.join(dir, a))
+            .filter((a) => p.exists(a) || p.readlink(a) !== null); // `current` is a symlink on unix
+        if (artifacts.length === 0)
+            continue;
+        installDirs.push(dir);
+        if (P.resolve(dir) === P.resolve(stateDir(p))) {
+            // Shared with machine-level state: remove artifacts only.
+            plan.paths.push(...artifacts);
+            plan.summary.push(`bundle install at ${dir} (versions/ and current — state files kept)`);
+        }
+        else {
+            plan.paths.push(dir);
+            plan.summary.push(`bundle install at ${dir}`);
+        }
+    }
+    // --- Bin-dir shim (unix installer's symlink) --------------------------------
+    const binDir = p.env.HOMEGRAPH_BIN_DIR
+        ?? (p.platform === 'win32' ? null : P.join(p.homedir, '.local', 'bin'));
+    if (binDir) {
+        const shim = P.join(binDir, 'homegraph');
+        const target = p.readlink(shim);
+        // Only when the link demonstrably points into a bundle install dir —
+        // resolved against the link's own directory, since install.sh links an
+        // absolute target but a hand-made relative link must still verify.
+        if (target !== null) {
+            const resolved = P.resolve(binDir, target);
+            const ours = installDirs.some((d) => resolved.startsWith(P.resolve(d) + P.sep))
+                || resolved.includes(`${P.sep}.homegraph${P.sep}`);
+            if (ours) {
+                plan.paths.push(shim);
+                plan.summary.push(`launcher link at ${shim}`);
+            }
+        }
+    }
+    // --- npm global package -----------------------------------------------------
+    // Asking npm (not guessing prefixes) keeps this correct under nvm/fnm/volta.
+    // A LOCAL npm install (project dependency) is deliberately not offered.
+    const rootInv = (0, index_1.npmInvocation)(p.platform, ['root', '-g']);
+    const rootRes = p.capture(rootInv.cmd, rootInv.args);
+    if (rootRes && rootRes.code === 0) {
+        const pkgDir = P.join(rootRes.stdout.trim(), index_1.NPM_PACKAGE);
+        if (rootRes.stdout.trim() && p.exists(pkgDir)) {
+            plan.npmGlobal = true;
+            plan.npmRoot = rootRes.stdout.trim();
+            plan.summary.push(`npm global package (${index_1.NPM_PACKAGE})`);
+        }
+    }
+    return plan;
+}
+function defaultRemoveDeps() {
+    return {
+        platform: process.platform,
+        execPath: process.execPath,
+        rm: (p) => fs.rmSync(p, { recursive: true, force: true }),
+        rename: (from, to) => fs.renameSync(from, to),
+        run: (cmd, args) => {
+            const res = (0, child_process_1.spawnSync)(cmd, args, { stdio: 'inherit', windowsHide: true, timeout: 120_000 });
+            return typeof res.status === 'number' ? res.status : -1;
+        },
+    };
+}
+/**
+ * Rename the running (locked) node.exe out of `dir` so the rest of the tree
+ * deletes cleanly — Windows allows renaming a mapped image, just not deleting
+ * it. Returns the leftover path, or null when nothing needed moving.
+ */
+function moveLockedExeAside(dir, deps) {
+    if (deps.platform !== 'win32')
+        return null;
+    const P = pathFor(deps.platform);
+    const resolvedDir = P.resolve(dir) + P.sep;
+    if (!P.resolve(deps.execPath).startsWith(resolvedDir))
+        return null;
+    const leftover = P.join(P.dirname(P.resolve(dir)), `homegraph-old-node-${process.pid}.exe`);
+    try {
+        deps.rename(deps.execPath, leftover);
+        return leftover;
+    }
+    catch {
+        return null; // rename failed too — the rm error will surface the dir
+    }
+}
+function executeBinaryRemoval(plan, deps = defaultRemoveDeps()) {
+    const result = { removed: [], leftovers: [], npm: 'skipped' };
+    const P = pathFor(deps.platform);
+    for (const p of plan.paths) {
+        // Planner-emitted paths are always deep, specific artifacts; this guard
+        // exists so no future planner bug can ever hand the executor a root.
+        if (P.resolve(p) === P.parse(P.resolve(p)).root) {
+            result.leftovers.push(p);
+            continue;
+        }
+        try {
+            deps.rm(p);
+            result.removed.push(p);
+        }
+        catch {
+            // Windows: the running exe inside this tree is deletable-after-rename.
+            const moved = moveLockedExeAside(p, deps);
+            try {
+                deps.rm(p);
+                result.removed.push(p);
+                if (moved)
+                    result.leftovers.push(moved);
+            }
+            catch {
+                result.leftovers.push(p);
+            }
+        }
+    }
+    if (plan.npmGlobal) {
+        // If we are RUNNING from the npm install on Windows, npm's delete will
+        // hit the same lock — move the exe aside first.
+        let moved = null;
+        if (plan.npmRoot)
+            moved = moveLockedExeAside(plan.npmRoot, deps);
+        const inv = (0, index_1.npmInvocation)(deps.platform, ['uninstall', '-g', index_1.NPM_PACKAGE]);
+        const code = deps.run(inv.cmd, inv.args);
+        result.npm = code === 0 ? 'removed' : 'failed';
+        if (moved)
+            result.leftovers.push(moved);
+    }
+    return result;
+}
+//# sourceMappingURL=remove-binary.js.map

package/dist/upgrade/remove-binary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remove-binary.js","sourceRoot":"","sources":["../../src/upgrade/remove-binary.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,92 @@
+/**
+ * Background update-availability check for long-lived servers (#1243).
+ *
+ * The recommended MCP config launches the LOCAL `homegraph` binary, so the
+ * server (and the prompt hook alongside it) silently stays on whatever version
+ * was last manually upgraded — users discover the drift only when something
+ * breaks. This module gives the running server *visibility* without changing
+ * behavior: a non-blocking check against the latest GitHub release, surfaced
+ * as a one-line notice (stderr log, MCP initialize instructions, and
+ * `homegraph_status`) telling the user to run `homegraph upgrade`.
+ *
+ * Invariants (mirrors the telemetry module's contract):
+ *   - Never stdout — stdio is the MCP protocol channel.
+ *   - Never blocking: the network refresh is fire-and-forget; every reader
+ *     (`getUpdateNotice`) is a cheap synchronous cache read, so the #172
+ *     respond-fast handshake contract holds.
+ *   - Fail silent: offline / rate-limited / disk-full all degrade to "no
+ *     notice", never an error, never a retry loop.
+ *   - Off is off: `HOMEGRAPH_NO_UPDATE_CHECK` (dedicated) or `DO_NOT_TRACK`
+ *     (broad don't-phone-home convention — set by e.g. the Pro container's
+ *     data plane) suppresses the network call AND the notice entirely.
+ *
+ * The check itself reuses `resolveLatestVersion` — the GitHub release-redirect
+ * trick with the API fallback — so version resolution can't drift from what
+ * `homegraph upgrade` installs. Results are cached in `~/.homegraph/` (the
+ * same global state dir telemetry and the daemon registry use) with a 24h TTL
+ * on success and a 1h backoff after failure, shared across every proxy /
+ * daemon process on the machine.
+ */
+/** Re-check the release feed after this long (successful checks). */
+export declare const UPDATE_CHECK_TTL_MS: number;
+/** Back off this long after a failed check (offline, rate-limited). */
+export declare const UPDATE_CHECK_FAILURE_BACKOFF_MS: number;
+export interface UpdateCheckCacheFile {
+    /** Last time a network check was attempted (ms epoch). */
+    lastAttemptAt: number;
+    /** Last time a network check succeeded (ms epoch). */
+    lastSuccessAt?: number;
+    /** Latest release tag from the last successful check (e.g. `v1.4.1`). */
+    latest?: string;
+}
+export interface UpdateCheckDeps {
+    /** Global state dir; defaults to ~/.homegraph. Tests inject a temp dir. */
+    dir?: string;
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
+    resolveLatest?: () => Promise<string>;
+    currentVersion?: string;
+}
+/**
+ * True when the update check must not run at all — no network call, no
+ * notice. `DO_NOT_TRACK` uses the same truthiness the telemetry opt-out does.
+ */
+export declare function updateCheckDisabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function updateCheckCachePath(dir: string): string;
+export declare function readUpdateCheckCache(dir: string): UpdateCheckCacheFile | null;
+/**
+ * Rebuild a canonical `vX.Y.Z[-pre]` tag from the PARSED semver fields, or
+ * null when the input isn't version-shaped. The notice ends up inside the MCP
+ * initialize instructions — agent-visible, system-prompt-adjacent text — and
+ * the `latest` value arrives from a network redirect via an on-disk cache, so
+ * only a reconstructed canonical string may ever be interpolated, never the
+ * raw value. (`parseSemver`'s regex is not end-anchored: a value like
+ * `1.2.3-x <arbitrary text>` parses "valid" while the raw string would carry
+ * the trailing text straight into every session's instructions.)
+ */
+export declare function canonicalVersionTag(v: string): string | null;
+/** One user-facing sentence; every surface (stderr, instructions, status) shows this. */
+export declare function formatUpdateNotice(current: string, latest: string): string;
+/**
+ * Ensure the on-disk cache is fresh (hitting the network only past the TTL /
+ * backoff) and return the current notice, or null. Never throws.
+ */
+export declare function refreshUpdateCheck(deps?: UpdateCheckDeps): Promise<string | null>;
+/**
+ * The current update notice from the on-disk cache — synchronous and cheap
+ * (memoized disk read), safe on the initialize respond-fast path. When the
+ * cache has gone stale (e.g. a daemon that has been up for weeks), kicks a
+ * background refresh so the NEXT reader sees a current answer; this call
+ * still returns immediately from the stale cache.
+ */
+export declare function getUpdateNotice(deps?: UpdateCheckDeps): string | null;
+/** Test hook: clear the per-process memo. */
+export declare function resetUpdateNoticeMemo(): void;
+/**
+ * Fire-and-forget entry point for server startup: refresh the cache in the
+ * background and, if an update is available, emit ONE stderr line (stderr is
+ * the MCP-safe channel; hosts surface it in their server logs). Never throws,
+ * never blocks, never writes stdout.
+ */
+export declare function checkForUpdateInBackground(deps?: UpdateCheckDeps, log?: (line: string) => void): void;
+//# sourceMappingURL=update-check.d.ts.map

package/dist/upgrade/update-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-check.d.ts","sourceRoot":"","sources":["../../src/upgrade/update-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAQH,qEAAqE;AACrE,eAAO,MAAM,mBAAmB,QAAsB,CAAC;AACvD,uEAAuE;AACvE,eAAO,MAAM,+BAA+B,QAAiB,CAAC;AAI9D,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,aAAa,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACtC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAyBD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAEjF;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAS7E;AAWD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI5D;AAED,yFAAyF;AACzF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAK1E;AAyBD;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA2B3F;AAOD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,eAAoB,GAAG,MAAM,GAAG,IAAI,CAiBzE;AAED,6CAA6C;AAC7C,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,GAAE,eAAoB,EAC1B,GAAG,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAA2C,GACjE,IAAI,CAQN"}

package/dist/upgrade/update-check.js

@@ -0,0 +1,258 @@
+"use strict";
+/**
+ * Background update-availability check for long-lived servers (#1243).
+ *
+ * The recommended MCP config launches the LOCAL `homegraph` binary, so the
+ * server (and the prompt hook alongside it) silently stays on whatever version
+ * was last manually upgraded — users discover the drift only when something
+ * breaks. This module gives the running server *visibility* without changing
+ * behavior: a non-blocking check against the latest GitHub release, surfaced
+ * as a one-line notice (stderr log, MCP initialize instructions, and
+ * `homegraph_status`) telling the user to run `homegraph upgrade`.
+ *
+ * Invariants (mirrors the telemetry module's contract):
+ *   - Never stdout — stdio is the MCP protocol channel.
+ *   - Never blocking: the network refresh is fire-and-forget; every reader
+ *     (`getUpdateNotice`) is a cheap synchronous cache read, so the #172
+ *     respond-fast handshake contract holds.
+ *   - Fail silent: offline / rate-limited / disk-full all degrade to "no
+ *     notice", never an error, never a retry loop.
+ *   - Off is off: `HOMEGRAPH_NO_UPDATE_CHECK` (dedicated) or `DO_NOT_TRACK`
+ *     (broad don't-phone-home convention — set by e.g. the Pro container's
+ *     data plane) suppresses the network call AND the notice entirely.
+ *
+ * The check itself reuses `resolveLatestVersion` — the GitHub release-redirect
+ * trick with the API fallback — so version resolution can't drift from what
+ * `homegraph upgrade` installs. Results are cached in `~/.homegraph/` (the
+ * same global state dir telemetry and the daemon registry use) with a 24h TTL
+ * on success and a 1h backoff after failure, shared across every proxy /
+ * daemon process on the machine.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UPDATE_CHECK_FAILURE_BACKOFF_MS = exports.UPDATE_CHECK_TTL_MS = void 0;
+exports.updateCheckDisabled = updateCheckDisabled;
+exports.updateCheckCachePath = updateCheckCachePath;
+exports.readUpdateCheckCache = readUpdateCheckCache;
+exports.canonicalVersionTag = canonicalVersionTag;
+exports.formatUpdateNotice = formatUpdateNotice;
+exports.refreshUpdateCheck = refreshUpdateCheck;
+exports.getUpdateNotice = getUpdateNotice;
+exports.resetUpdateNoticeMemo = resetUpdateNoticeMemo;
+exports.checkForUpdateInBackground = checkForUpdateInBackground;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const index_1 = require("./index");
+const version_1 = require("../mcp/version");
+/** Re-check the release feed after this long (successful checks). */
+exports.UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+/** Back off this long after a failed check (offline, rate-limited). */
+exports.UPDATE_CHECK_FAILURE_BACKOFF_MS = 60 * 60 * 1000;
+/** Short network budget — the refresh is background work, not a handshake. */
+const UPDATE_CHECK_NETWORK_TIMEOUT_MS = 5000;
+function resolveDeps(deps = {}) {
+    return {
+        dir: deps.dir ?? path.join(os.homedir(), '.homegraph'),
+        env: deps.env ?? process.env,
+        now: deps.now ?? Date.now,
+        resolveLatest: deps.resolveLatest ?? (() => (0, index_1.resolveLatestVersion)(undefined, UPDATE_CHECK_NETWORK_TIMEOUT_MS)),
+        currentVersion: deps.currentVersion ?? version_1.HomeGraphPackageVersion,
+    };
+}
+function envTruthy(raw) {
+    return raw !== undefined && raw !== '' && raw !== '0' && raw.toLowerCase() !== 'false';
+}
+/**
+ * True when the update check must not run at all — no network call, no
+ * notice. `DO_NOT_TRACK` uses the same truthiness the telemetry opt-out does.
+ */
+function updateCheckDisabled(env = process.env) {
+    return envTruthy(env.HOMEGRAPH_NO_UPDATE_CHECK) || envTruthy(env.DO_NOT_TRACK);
+}
+function updateCheckCachePath(dir) {
+    return path.join(dir, 'update-check.json');
+}
+function readUpdateCheckCache(dir) {
+    try {
+        const raw = fs.readFileSync(updateCheckCachePath(dir), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.lastAttemptAt !== 'number')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null; // missing / torn / unparseable — same as no cache
+    }
+}
+function writeUpdateCheckCache(dir, cache) {
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(updateCheckCachePath(dir), JSON.stringify(cache));
+    }
+    catch {
+        /* fail silent — a read-only home dir must not break the server */
+    }
+}
+/**
+ * Rebuild a canonical `vX.Y.Z[-pre]` tag from the PARSED semver fields, or
+ * null when the input isn't version-shaped. The notice ends up inside the MCP
+ * initialize instructions — agent-visible, system-prompt-adjacent text — and
+ * the `latest` value arrives from a network redirect via an on-disk cache, so
+ * only a reconstructed canonical string may ever be interpolated, never the
+ * raw value. (`parseSemver`'s regex is not end-anchored: a value like
+ * `1.2.3-x <arbitrary text>` parses "valid" while the raw string would carry
+ * the trailing text straight into every session's instructions.)
+ */
+function canonicalVersionTag(v) {
+    const s = (0, index_1.parseSemver)(v);
+    if (!s)
+        return null;
+    return `v${s.major}.${s.minor}.${s.patch}${s.pre ? `-${s.pre}` : ''}`;
+}
+/** One user-facing sentence; every surface (stderr, instructions, status) shows this. */
+function formatUpdateNotice(current, latest) {
+    return (`HomeGraph ${latest} is available (this server is running ` +
+        `${current}). Update with \`homegraph upgrade\`.`);
+}
+function noticeFrom(cache, d) {
+    if (!cache?.latest)
+        return null;
+    // A dev build whose package.json couldn't be read reports the sentinel
+    // version; any comparison against it would always claim an update.
+    if (d.currentVersion === '0.0.0-unknown')
+        return null;
+    // Canonicalize BOTH sides before comparing or rendering — a non-semver
+    // `latest` (garbage redirect, tampered cache) yields no notice at all
+    // rather than flowing into agent-visible text.
+    const latest = canonicalVersionTag(cache.latest);
+    const current = canonicalVersionTag(d.currentVersion);
+    if (!latest || !current)
+        return null;
+    return (0, index_1.isUpdateAvailable)(current, latest) ? formatUpdateNotice(current, latest) : null;
+}
+function cacheIsFresh(cache, nowMs) {
+    if (!cache)
+        return false;
+    if (cache.lastSuccessAt !== undefined && nowMs - cache.lastSuccessAt < exports.UPDATE_CHECK_TTL_MS) {
+        return true;
+    }
+    // No recent success: only the failure backoff holds the network call off.
+    return nowMs - cache.lastAttemptAt < exports.UPDATE_CHECK_FAILURE_BACKOFF_MS;
+}
+/**
+ * Ensure the on-disk cache is fresh (hitting the network only past the TTL /
+ * backoff) and return the current notice, or null. Never throws.
+ */
+async function refreshUpdateCheck(deps = {}) {
+    const d = resolveDeps(deps);
+    if (updateCheckDisabled(d.env))
+        return null;
+    const cached = readUpdateCheckCache(d.dir);
+    const nowMs = d.now();
+    if (cacheIsFresh(cached, nowMs))
+        return noticeFrom(cached, d);
+    try {
+        const latest = canonicalVersionTag(await d.resolveLatest());
+        // A response that isn't version-shaped is a failure, not a result —
+        // fall through to the backoff path and keep the previous known-good tag.
+        if (!latest)
+            throw new Error('release feed returned a non-version tag');
+        const next = { lastAttemptAt: nowMs, lastSuccessAt: nowMs, latest };
+        writeUpdateCheckCache(d.dir, next);
+        return noticeFrom(next, d);
+    }
+    catch {
+        // Record the attempt (starts the backoff) but KEEP the previous latest —
+        // a transient outage must not hide an already-known update.
+        const next = {
+            lastAttemptAt: nowMs,
+            lastSuccessAt: cached?.lastSuccessAt,
+            latest: cached?.latest,
+        };
+        writeUpdateCheckCache(d.dir, next);
+        return noticeFrom(next, d);
+    }
+}
+// Per-process memo so the sync read path (MCP initialize, homegraph_status)
+// touches the disk at most once a minute, not once per handshake.
+const NOTICE_MEMO_TTL_MS = 60 * 1000;
+let noticeMemo = null;
+/**
+ * The current update notice from the on-disk cache — synchronous and cheap
+ * (memoized disk read), safe on the initialize respond-fast path. When the
+ * cache has gone stale (e.g. a daemon that has been up for weeks), kicks a
+ * background refresh so the NEXT reader sees a current answer; this call
+ * still returns immediately from the stale cache.
+ */
+function getUpdateNotice(deps = {}) {
+    const d = resolveDeps(deps);
+    if (updateCheckDisabled(d.env))
+        return null;
+    const useMemo = deps.dir === undefined && deps.now === undefined;
+    const nowMs = d.now();
+    if (useMemo && noticeMemo && nowMs - noticeMemo.at < NOTICE_MEMO_TTL_MS) {
+        return noticeMemo.value;
+    }
+    const cached = readUpdateCheckCache(d.dir);
+    if (!cacheIsFresh(cached, nowMs)) {
+        void refreshUpdateCheck(deps).catch(() => { });
+    }
+    const value = noticeFrom(cached, d);
+    if (useMemo)
+        noticeMemo = { at: nowMs, value };
+    return value;
+}
+/** Test hook: clear the per-process memo. */
+function resetUpdateNoticeMemo() {
+    noticeMemo = null;
+}
+/**
+ * Fire-and-forget entry point for server startup: refresh the cache in the
+ * background and, if an update is available, emit ONE stderr line (stderr is
+ * the MCP-safe channel; hosts surface it in their server logs). Never throws,
+ * never blocks, never writes stdout.
+ */
+function checkForUpdateInBackground(deps = {}, log = (line) => process.stderr.write(line)) {
+    refreshUpdateCheck(deps)
+        .then((notice) => {
+        // The shared notice sentence starts with "HomeGraph …"; drop the word
+        // after the log tag so the line doesn't read "[HomeGraph] HomeGraph …".
+        if (notice)
+            log(`[HomeGraph] ${notice.replace(/^HomeGraph /, '')}\n`);
+    })
+        .catch(() => { });
+}
+//# sourceMappingURL=update-check.js.map

package/dist/upgrade/update-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-check.js","sourceRoot":"","sources":["../../src/upgrade/update-check.ts"],"names":[],"mappings":"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"}