ima2-gen 3.25.0 → 3.26.0

package/lib/updateCheck.js

@@ -0,0 +1,118 @@
+import { config } from "../config.js";
+import { errInfo } from "./errInfo.js";
+import { readVersionCache, updateVersionCache } from "./updateCache.js";
+import { PACKAGE_NAME, parseVersion } from "./updateVersion.js";
+export async function fetchLatestVersion(tag, deps = {}) {
+    const registry = (deps.registry ?? config.update.registry).replace(/\/+$/, "");
+    const timeout = AbortSignal.timeout(deps.timeoutMs ?? config.update.timeoutMs);
+    const signal = deps.signal ? AbortSignal.any([timeout, deps.signal]) : timeout;
+    const response = await (deps.fetchImpl ?? fetch)(`${registry}/${PACKAGE_NAME}/${tag}`, {
+        headers: { accept: "application/json" }, signal,
+    });
+    if (!response.ok)
+        throw new Error(`registry returned HTTP ${response.status}`);
+    const body = await response.json().catch((error) => {
+        throw new Error("registry returned invalid JSON", { cause: error });
+    });
+    if (!body || typeof body !== "object" || Array.isArray(body) || !("version" in body)
+        || typeof body.version !== "string" || !parseVersion(body.version)) {
+        throw new Error("registry returned an invalid version");
+    }
+    signal.throwIfAborted();
+    return body.version;
+}
+const inFlight = new Map();
+export function checkForUpdate(tag, deps = {}) {
+    const existing = inFlight.get(tag);
+    if (existing)
+        return existing;
+    const pending = fetchLatestVersion(tag, deps).then((latest_version) => {
+        deps.signal?.throwIfAborted();
+        return updateVersionCache({ latest_version, last_checked_at: (deps.now ?? Date.now)(), tag }, deps.cachePath);
+    }).finally(() => { inFlight.delete(tag); });
+    inFlight.set(tag, pending);
+    return pending;
+}
+export function isCacheFresh(cache, tag, now, maxAgeMs = config.update.freshMs) {
+    return cache.tag === tag && cache.last_checked_at !== null && now - cache.last_checked_at < maxAgeMs;
+}
+/**
+ * Automatic checks run only for real npm-launched servers: never for the desktop's bundled
+ * server (the app updates itself) and never under node --test, whose NODE_TEST_CONTEXT is
+ * inherited by servers that tests start, so suites stay offline and away from ~/.ima2.
+ */
+export function updateChecksEnabled(env, launcher) {
+    return env.IMA2_DISABLE_UPDATE_CHECK !== "1" && launcher !== "desktop" && !env.NODE_TEST_CONTEXT;
+}
+class UpdateScheduler {
+    opts;
+    controller = new AbortController();
+    deps;
+    setTimer;
+    clearTimer;
+    timer;
+    stopped = false;
+    pending = null;
+    delay = 0;
+    backoff;
+    constructor(opts) {
+        this.opts = opts;
+        this.deps = { ...opts.deps, signal: opts.deps?.signal
+                ? AbortSignal.any([this.controller.signal, opts.deps.signal]) : this.controller.signal };
+        this.setTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+        this.clearTimer = opts.clearTimer ?? ((timer) => clearTimeout(timer));
+        this.backoff = opts.backoffMinMs ?? config.update.backoffMinMs;
+        this.schedule(0);
+    }
+    checkNow() {
+        if (this.stopped)
+            return Promise.resolve(null);
+        if (this.pending)
+            return this.pending;
+        this.pending = checkForUpdate(this.opts.tag, this.deps).catch((error) => {
+            if (!this.stopped)
+                (this.opts.log ?? console.log)(`[update] check failed: ${errInfo(error).message}`);
+            return null;
+        }).finally(() => { this.pending = null; });
+        return this.pending;
+    }
+    async run() {
+        if (this.stopped)
+            return;
+        const cache = readVersionCache(this.deps.cachePath);
+        const fresh = isCacheFresh(cache, this.opts.tag, (this.deps.now ?? Date.now)(), this.opts.freshMs);
+        const succeeded = fresh || await this.checkNow() !== null;
+        if (this.stopped)
+            return;
+        if (succeeded) {
+            this.backoff = this.opts.backoffMinMs ?? config.update.backoffMinMs;
+            this.schedule(this.opts.tickMs ?? config.update.tickMs);
+        }
+        else {
+            this.schedule(this.backoff);
+            this.backoff = Math.min(this.backoff * 2, this.opts.backoffMaxMs ?? config.update.backoffMaxMs);
+        }
+    }
+    schedule(ms) {
+        if (this.stopped)
+            return;
+        this.delay = ms;
+        this.timer = this.setTimer(() => { void this.run(); }, ms);
+        if (this.timer && typeof this.timer === "object" && "unref" in this.timer && typeof this.timer.unref === "function") {
+            this.timer.unref();
+        }
+    }
+    stop() {
+        this.stopped = true;
+        if (this.timer !== undefined)
+            this.clearTimer(this.timer);
+        this.controller.abort();
+    }
+    nextDelayMs() { return this.delay; }
+}
+export function startUpdateScheduler(opts) {
+    const scheduler = new UpdateScheduler(opts);
+    return {
+        stop: () => scheduler.stop(), checkNow: () => scheduler.checkNow(), nextDelayMs: () => scheduler.nextDelayMs(),
+    };
+}

package/lib/updateVersion.js

@@ -0,0 +1,59 @@
+export const PACKAGE_NAME = "ima2-gen";
+const VERSION_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+export function parseVersion(v) {
+    const match = VERSION_RE.exec(v);
+    if (!match)
+        return null;
+    const core = [Number(match[1]), Number(match[2]), Number(match[3])];
+    if (!core.every(Number.isSafeInteger))
+        return null;
+    const pre = match[4]?.split(".") ?? [];
+    if (pre.some((part) => /^\d+$/.test(part) && part.length > 1 && part.startsWith("0")))
+        return null;
+    return { core, pre };
+}
+function compareIdentifier(a, b) {
+    if (a === b)
+        return 0;
+    const aNumeric = /^\d+$/.test(a);
+    const bNumeric = /^\d+$/.test(b);
+    if (aNumeric && bNumeric && a.length !== b.length)
+        return a.length > b.length ? 1 : -1;
+    if (aNumeric !== bNumeric)
+        return aNumeric ? -1 : 1;
+    return a > b ? 1 : -1;
+}
+export function compareVersions(a, b) {
+    const left = parseVersion(a);
+    const right = parseVersion(b);
+    if (!left || !right)
+        return left ? 1 : right ? -1 : 0;
+    for (const index of [0, 1, 2]) {
+        if (left.core[index] !== right.core[index])
+            return left.core[index] > right.core[index] ? 1 : -1;
+    }
+    if (!left.pre.length || !right.pre.length)
+        return left.pre.length ? -1 : right.pre.length ? 1 : 0;
+    for (let index = 0; index < Math.max(left.pre.length, right.pre.length); index++) {
+        const l = left.pre[index];
+        const r = right.pre[index];
+        if (l === undefined || r === undefined)
+            return l === undefined ? -1 : 1;
+        const order = compareIdentifier(l, r);
+        if (order)
+            return order;
+    }
+    return 0;
+}
+export function isNewer(candidate, current) {
+    return typeof candidate === "string" && parseVersion(candidate) !== null && compareVersions(candidate, current) > 0;
+}
+export function defaultTag(current) {
+    return /-preview/.test(current) ? "preview" : "latest";
+}
+export function isUpdateTag(v) {
+    return v === "latest" || v === "preview";
+}
+export function releaseUrl(version) {
+    return `https://github.com/lidge-ai/ima2-gen/releases/tag/v${version}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ima2-gen",
-  "version": "3.25.0",
+  "version": "3.26.0",
   "packageManager": "npm@11.18.0",
   "description": "Local-first visual generation runtime and studio for people and coding agents, with reproducible image and video workflows across multiple providers.",
   "type": "module",
@@ -131,5 +131,5 @@
     "typescript-eslint": "8.70.0",
     "yaml": "2.9.1"
   },
-  "gitHead": "057de2c0639cd451c65bff6f484ae397e86d7447"
+  "gitHead": "f7857a52d057ce628f04d3402ac460fd029f92f9"
 }

package/routes/events.js

@@ -1,5 +1,6 @@
 import { subscribe, replaySince, hasReplayGap, replayOldestId, latestEventId, MAX_SSE_LISTENERS } from "../lib/eventBus.js";
 import { SSE_STREAM_POLICY } from "../lib/eventsPolicy.js";
+import { updateHintFrame } from "./update.js";
 let activeConnections = 0;
 const HEARTBEAT_MS = 15_000;
 function formatSse(ev) {
@@ -20,16 +21,18 @@ class EventConnection {
     req;
     res;
     cursor;
+    hint;
     closed = false;
     pumping = false;
     blocked = false;
     unsubscribe = () => { };
     heartbeat;
     deadline;
-    constructor(req, res, cursor) {
+    constructor(req, res, cursor, hint = null) {
         this.req = req;
         this.res = res;
         this.cursor = cursor;
+        this.hint = hint;
     }
     start() {
         activeConnections++;
@@ -46,6 +49,8 @@ class EventConnection {
             this.res.flushHeaders?.();
             if (this.closed)
                 return;
+            if (this.hint)
+                this.write(this.hint);
             this.unsubscribe = subscribe(this.live);
             this.pump();
             if (!this.closed)
@@ -150,7 +155,7 @@ class EventConnection {
             this.res.destroy();
     };
 }
-export function registerEventsRoute(app, _ctx) {
+export function registerEventsRoute(app, ctx) {
     app.get("/api/events", (req, res) => {
         if (activeConnections >= MAX_SSE_LISTENERS) {
             return res.status(503).json({
@@ -161,6 +166,6 @@ export function registerEventsRoute(app, _ctx) {
         const queryLastId = parseInt(String(req.query.lastEventId ?? ""), 10);
         const lastId = Number.isSafeInteger(headerLastId) ? headerLastId : queryLastId;
         const cursor = Number.isSafeInteger(lastId) ? Math.max(0, lastId) : latestEventId();
-        new EventConnection(req, res, cursor).start();
+        new EventConnection(req, res, cursor, updateHintFrame(ctx)).start();
     });
 }

package/routes/index.js

@@ -2,6 +2,7 @@ import { registerCapabilitiesRoutes } from "./capabilities.js";
 import { registerModelsRoutes } from "./models.js";
 import { registerEventsRoute } from "./events.js";
 import { registerHealthRoutes } from "./health.js";
+import { registerUpdateRoutes } from "./update.js";
 import { registerGithubRoutes } from "./github.js";
 import { registerAdminRoutes } from "./admin.js";
 import { registerHistoryRoutes } from "./history.js";
@@ -47,6 +48,7 @@ export function configureRoutes(app, ctxRaw) {
     const ctx = requireRuntimeContext(ctxRaw);
     registerEventsRoute(app, ctx);
     registerHealthRoutes(app, ctx);
+    registerUpdateRoutes(app, ctx);
     registerGithubRoutes(app);
     registerAdminRoutes(app, ctx);
     registerCapabilitiesRoutes(app, ctx);

package/routes/update.js

@@ -0,0 +1,67 @@
+import { errInfo } from "../lib/errInfo.js";
+import { requireRuntimeContext } from "../lib/runtimeContext.js";
+import { buildBadge, claimUpdatedNotice, readVersionCache, updateVersionCache, versionCachePath } from "../lib/updateCache.js";
+import { checkForUpdate, updateChecksEnabled } from "../lib/updateCheck.js";
+import { defaultTag, parseVersion } from "../lib/updateVersion.js";
+/**
+ * One SSE frame with the cached badge, written when a browser opens GET /api/events. It is the
+ * web UI's only cue that this server has update routes: the UI makes no update request until it
+ * sees it, so fixture servers and e2e route harnesses never receive one. No id line, so replay
+ * cursors are unchanged. Null for desktop-launched servers and for contexts without a version.
+ */
+export function updateHintFrame(ctxRaw, deps = {}) {
+    const raw = ctxRaw;
+    if (typeof raw?.packageVersion !== "string" || raw.launcher === "desktop")
+        return null;
+    try {
+        const ctx = requireRuntimeContext(ctxRaw);
+        const badge = buildBadge({
+            cache: readVersionCache(deps.cachePath ?? versionCachePath(ctx.config.storage.configDir)),
+            current: ctx.packageVersion, tag: defaultTag(ctx.packageVersion), surface: "npm",
+            enabled: updateChecksEnabled(deps.env ?? process.env, ctx.launcher),
+            now: (deps.now ?? Date.now)(), staleMs: ctx.config.update.staleMs,
+        });
+        return `event: update\ndata: ${JSON.stringify(badge)}\n\n`;
+    }
+    catch {
+        return null; // The hint is optional; an unreadable cache must not break the event stream.
+    }
+}
+export function registerUpdateRoutes(app, ctxRaw, deps = {}) {
+    const ctx = requireRuntimeContext(ctxRaw);
+    const surface = ctx.launcher === "desktop" ? "desktop" : "npm";
+    const tag = defaultTag(ctx.packageVersion);
+    const path = deps.cachePath ?? versionCachePath(ctx.config.storage.configDir);
+    const badge = () => buildBadge({
+        cache: readVersionCache(path), current: ctx.packageVersion, tag, surface,
+        enabled: updateChecksEnabled(deps.env ?? process.env, ctx.launcher),
+        now: (deps.now ?? Date.now)(), staleMs: ctx.config.update.staleMs,
+    });
+    app.get("/api/update/badge", (_req, res) => { res.json(badge()); });
+    app.post("/api/update/check", async (_req, res) => {
+        if (surface === "desktop") {
+            res.json(badge());
+            return;
+        }
+        try {
+            await (deps.check ?? checkForUpdate)(tag, { cachePath: path, now: deps.now ?? Date.now });
+            res.json(badge());
+        }
+        catch (error) {
+            res.status(503).json({ ok: false, code: "UPDATE_CHECK_FAILED", message: errInfo(error).message, badge: badge() });
+        }
+    });
+    app.post("/api/update/dismiss", (req, res) => {
+        const body = req.body;
+        const version = body && typeof body === "object" && "version" in body ? body.version : undefined;
+        if (typeof version !== "string" || !parseVersion(version)) {
+            res.status(400).json({ ok: false, code: "INVALID_VERSION" });
+            return;
+        }
+        updateVersionCache({ dismissed_version: version }, path);
+        res.json(badge());
+    });
+    app.post("/api/update/notice", (_req, res) => {
+        res.json({ updatedTo: surface === "desktop" ? null : claimUpdatedNotice(ctx.packageVersion, path) });
+    });
+}

package/server.js

@@ -14,6 +14,8 @@ import { configureLogger, logError, logWarn } from "./lib/logger.js";
 import { createRequestLogger } from "./lib/requestLogger.js";
 import { configureApiCachePolicy } from "./lib/apiCachePolicy.js";
 import { configureRoutes } from "./routes/index.js";
+import { startUpdateScheduler, updateChecksEnabled } from "./lib/updateCheck.js";
+import { defaultTag } from "./lib/updateVersion.js";
 import { API_REQUEST_POLICY, config } from "./config.js";
 import { createApiRequestBudget } from "./lib/apiRequestBudget.js";
 import { createLocalLanAccess, createLanApiGuard as tokenOnlyLanApiGuard } from "./lib/localLanAccess.js";
@@ -496,8 +498,10 @@ export async function startServer(overrides = {}) {
     ctx.markOAuthReady({ url: ctx.oauthUrl, port: ctx.oauthPort });
     let server;
     let reapTimer;
+    let updateScheduler = null;
     let tempReferenceReapTimer;
     onShutdown(async () => {
+        updateScheduler?.stop();
         unadvertise(ctx);
         try {
             oauthChild?.stop?.();
@@ -543,6 +547,9 @@ export async function startServer(overrides = {}) {
     console.log(`Image Gen running at ${ctx.serverUrl}`);
     console.log(`Provider policy: GPT OAuth, API-key Responses, and Grok (xAI OAuth or API key) providers. GPT OAuth ${ctx.oauthTransport === "native" ? "calls ChatGPT directly" : `uses ${ctx.oauthUrl}`}.`);
     advertise(ctx);
+    if (updateChecksEnabled(process.env, ctx.launcher)) {
+        updateScheduler = startUpdateScheduler({ tag: defaultTag(ctx.packageVersion), log: (m) => console.log(m) });
+    }
     try {
         const s = ensureDefaultSession();
         if (s)

package/skills/ima2/SKILL.md

@@ -48,6 +48,10 @@ needs `ima2 stop --service`; a server started by the desktop app is restarted fr
 
 Use `ima2 doctor` when setup, GPT OAuth, storage, or package integrity is unclear.
 
+Update a global install with `ima2 update --check` (report only) or `ima2 update --yes`
+(install, restart the service or background server, verify the new version). Add `--json`
+for one machine-readable result. It refuses source checkouts and npx runs.
+
 ## Generate Images
 
 List ready image lanes, choose a persistent CLI target, then generate: