portless-studio 0.1.0 → 0.1.1

package/README.md

@@ -1,5 +1,8 @@
 # portless studio
 
+[![npm](https://img.shields.io/npm/v/portless-studio)](https://www.npmjs.com/package/portless-studio)
+[![CI](https://github.com/keven-bardales/portless-studio/actions/workflows/ci.yml/badge.svg)](https://github.com/keven-bardales/portless-studio/actions/workflows/ci.yml)
+
 A local web dashboard for [portless](https://github.com/vercel-labs/portless): see every dev server
 on your machine, give each one a name like `web.myapp.localhost`, and open it from one page.
 
@@ -13,18 +16,45 @@ portless replaces port numbers with names: `portless api pnpm dev` serves your a
 with ten dev servers across several projects you have to remember which names exist and which
 ports have none. Studio shows both, live, and names a port in one click.
 
-![Naming port 8000 as notebook.ml, searching routes with Ctrl+K and running pnpm dev in a Studio terminal](docs/images/demo.gif)
+![Naming port 8000, searching routes with Ctrl+K, filtering with the Filter popover and running pnpm dev in a Studio terminal](docs/images/demo.gif)
 
 The screenshots use the built-in sample data (`?demo`), not a real machine.
 
-## Quick start
+## Install
+
+Requires Node 22 or later.
 
-Requires Node 24 or later.
+To try it, run it straight from npm:
 
 ```bash
 npx portless-studio init
 ```
 
+For everyday use, and always for "start at login", install it globally:
+
+```bash
+npm i -g portless-studio
+portless-studio init
+```
+
+The login service starts Studio from the files npm installed. Run through `npx`, those files sit in
+npm's cache, which npm can clear at any time, and then Studio stops starting at login.
+
+To update, install the latest version and restart Studio:
+
+```bash
+npm i -g portless-studio@latest
+```
+
+To remove it, undo the setup first, then remove the package:
+
+```bash
+portless-studio uninstall
+npm rm -g portless-studio
+```
+
+## Quick start
+
 `init` asks a few questions and leaves everything working:
 
 - Checks that portless is installed and offers to install it with `npm install -g portless`.
@@ -33,7 +63,7 @@ npx portless-studio init
 - Starts the portless proxy on port 1355 over HTTP, which needs no password, certificate or extra
   tool on macOS, Windows or Linux, and can set Studio to start when you log in.
 
-`init --yes` accepts every default without asking. After that, `npx portless-studio` starts
+`init --yes` accepts every default without asking. After that, `portless-studio` starts
 Studio at `http://127.0.0.1:4949`, registers it in portless as `studio` and opens your browser.
 Your apps open at names like `http://web.myapp.localhost:1355`: Chrome, Edge and Firefox send
 every `*.localhost` name to your own machine, with no hosts file and no DNS setup.
@@ -47,8 +77,9 @@ data, or `?demo&noportless` to walk through the install flow with a fake install
   or Cloudflare tunnel. It updates as soon as a route appears or goes away.
 - **Detected ports:** listening ports that answer HTTP but have no name yet, with the process, the
   project folder and a suggested name. Name one, name them all, or ignore one.
-- **Auto mode** (off by default): every new dev server gets its suggested name by itself. Names
-  auto mode gave are removed 10 minutes after their port closes.
+- **Auto mode** (off by default): every new dev server gets its suggested name by itself, once
+  it has shown up unnamed in two scans in a row, so a server started with `portless <name>` keeps
+  the name portless gives it. Names auto mode gave are removed 10 minutes after their port closes.
 - **Name a port** that portless did not start, such as a database in Docker (`db` gives
   `db.localhost`). Rename or remove those names later.
 - **Where each server runs:** every row shows the git branch, the linked worktree and the project
@@ -120,7 +151,7 @@ names the first port it opens and stops it on Ctrl+C. The terminal stays visible
 
 ## Platforms
 
-Studio runs on Linux, macOS and Windows with Node 24 and installs nothing beyond portless. Each
+Studio runs on Linux, macOS and Windows with Node 22 or later and installs nothing beyond portless. Each
 feature uses tools the system already has (`/proc` on Linux, `lsof` on macOS, `netstat` and
 PowerShell on Windows). [docs/platforms.md](docs/platforms.md) says what each system uses and what
 does not work the same everywhere.
@@ -157,6 +188,7 @@ does not work the same everywhere.
 | `PORTLESS_STATE_DIR` | portless state folder. Default `~/.portless`. |
 | `PORTLESS_BIN` | portless binary used to create and remove names. Default `portless`. |
 | `PORTLESS_STUDIO_URL` | Studio that `mcp`, `list`, `run` and `open` talk to. Default `http://127.0.0.1:<port>`. |
+| `PORTLESS_STUDIO_NO_UPDATE_CHECK` | `1` turns the daily update check off, whatever the config says. |
 | `EDITOR` | Editor that `config --edit` opens. |
 
 ## Config file
@@ -186,10 +218,22 @@ changes without a restart. Missing fields take their default.
 | `systemNotifications` | `false` | Asks the operating system to notify when no Studio tab is open. |
 | `nameTemplate` | `"{work}.{package}.{repo}"` | How suggested names are built. See [docs/naming.md](docs/naming.md). |
 | `projectIcons` | `{}` | Icon per project: an emoji, an http(s) image URL or a `data:image` URL. |
+| `checkForUpdates` | `true` | Once a day, asks npm whether a newer portless-studio exists. See "Update notice" below. |
 
 The `--port`, `--no-open` and `--no-register` flags win over the file for one run. Apps you add to
 the Open with menu live in `open-with.json` next to the config file.
 
+### Update notice
+
+Once a day Studio asks the npm registry for the latest version of portless-studio. When a newer
+one exists, it prints one line on start and shows a banner in the page with the command to update;
+dismissing the banner hides it until the next version. The request is a plain
+`GET https://registry.npmjs.org/portless-studio/latest`: Studio sends nothing about your machine,
+your projects or your routes. It gives up after 3 seconds and stays quiet when you are offline,
+and it keeps the time of the last check in `update-check.json` next to the config file. It never
+runs when the `CI` variable is set. Turn it off with `checkForUpdates: false`, the Settings
+switch, or `PORTLESS_STUDIO_NO_UPDATE_CHECK=1`.
+
 ## Keyboard shortcuts
 
 | Keys | Action |
@@ -237,7 +281,7 @@ that needs sudo once to start the proxy. For HTTPS, set `proxyHttps` to `true` a
 portless certificate: `portless-studio doctor` prints the exact command for your system, and the
 Health panel shows it too.
 
-**Does it work on Windows?** Yes, with Node 24 and PowerShell 5 (included in Windows 10 and 11).
+**Does it work on Windows?** Yes, with Node 22 or later and PowerShell 5 (included in Windows 10 and 11).
 Ports come from `netstat`, process details from PowerShell, and start at login uses a hidden
 script in the Startup folder. Windows has no service manager Studio can ask, so the page can stop
 Studio but not restart it, and the doctor only sees the proxy portless records.
@@ -248,10 +292,10 @@ made by its authors. It reads the state portless keeps in `~/.portless` and name
 the `portless` command, so anything you or an agent do with portless shows up in Studio, and
 Studio never changes how portless works.
 
-**How do I remove it?** Run `npx portless-studio uninstall`. It removes the login service, the
-names auto mode gave and the `studio` name, stops the proxy if Studio started it, and asks before
-deleting the settings folder. If you installed it globally, also run
-`npm uninstall -g portless-studio`. portless itself stays installed; remove it with
+**How do I remove it?** Run `portless-studio uninstall` (or `npx portless-studio uninstall` if you
+never installed it globally). It removes the login service, the names auto mode gave and the
+`studio` name, stops the proxy if Studio started it, and asks before deleting the settings folder.
+Then remove the package with `npm rm -g portless-studio`. portless itself stays installed; remove it with
 `npm uninstall -g portless`.
 
 ## Development

package/dist/cli/cli-args.js

@@ -162,14 +162,40 @@ function parseFlags(args, subcommand) {
                             open: { type: "boolean" },
                             register: { type: "boolean" },
                         };
-    const { values, positionals } = parseArgs({
-        args,
+    // parseArgs learned `allowNegative` in Node 22.4; reading `--no-<flag>` here keeps every Node 22.
+    const { args: positive, negated } = splitNegations(args, options);
+    const { values, positionals, tokens } = parseArgs({
+        args: positive,
         options,
-        allowNegative: true,
+        tokens: true,
         allowPositionals: subcommand === "service" || subcommand === "run" || subcommand === "open",
     });
+    for (const token of tokens) {
+        if (token.kind === "option" && options[token.name]?.type === "boolean") {
+            values[token.name] = !negated.has(token.index);
+        }
+    }
     return {
         positionals,
         values: values,
     };
 }
+/**
+ * Turns each `--no-<flag>` of a boolean option into `--<flag>` and remembers its position, so the
+ * last of `--open` and `--no-open` wins. Arguments after `--` are left alone.
+ */
+function splitNegations(args, options) {
+    const negated = new Set();
+    const end = args.indexOf("--");
+    const positive = args.map((arg, index) => {
+        if (end !== -1 && index > end)
+            return arg;
+        const match = /^--no-([^=]+)(=.*)?$/.exec(arg);
+        const name = match?.[1];
+        if (name === undefined || options[name]?.type !== "boolean")
+            return arg;
+        negated.add(index);
+        return `--${name}${match?.[2] ?? ""}`;
+    });
+    return { args: positive, negated };
+}

package/dist/cli/index.js

@@ -5,6 +5,7 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { API_PATHS } from "../core/api/contract.js";
 import { DEFAULT_CONFIG } from "../core/config/studio-config.js";
+import { updateMessage } from "../core/updates/version.js";
 import { createStudioServices, createUninstallServices, startServer, } from "../server/main.js";
 import { HELP, parseCliArgs, resolveStartSettings, } from "./cli-args.js";
 import { runCommand } from "./command-runner.js";
@@ -13,7 +14,7 @@ import { runDoctorCommand } from "./doctor-command.js";
 import { runOpenCommand } from "./focus-command.js";
 import { runInit } from "./init.js";
 import { runListCommand } from "./list-command.js";
-import { installService, resolveServiceEntry, serviceStatus, uninstallService, } from "./login-service.js";
+import { describeServiceInstall, installService, resolveServiceEntry, serviceStatus, uninstallService, } from "./login-service.js";
 import { createMcpServer, serveStdio } from "./mcp/mcp-server.js";
 import { createStudioClient, resolveStudioUrl } from "./mcp/studio-client.js";
 import { AGENT_INSTRUCTIONS, createStudioTools } from "./mcp/studio-tools.js";
@@ -162,6 +163,7 @@ async function start(overrides) {
         studioPort: settings.port,
         studioService,
         openUrl: openBrowser,
+        version: readVersion(),
     });
     const webDir = resolveWebDir();
     let server;
@@ -190,6 +192,11 @@ async function start(overrides) {
         print("  API only: the UI runs through `pnpm dev:web`.");
     if (settings.open && webDir)
         openBrowser(alias.url ?? server.url);
+    // Never holds up the start: the line shows up once npm answers, or never when it does not.
+    void services.updates?.status().then((update) => {
+        if (update.available && update.latest)
+            print(updateMessage(update.current, update.latest));
+    });
     let stopping = false;
     const stop = async () => {
         if (stopping)
@@ -220,7 +227,7 @@ async function init(yes) {
                 const env = await serviceEnv();
                 if (!env.ok)
                     return env;
-                return describeInstall(await installService(env.value), env.value);
+                return describeServiceInstall(await installService(env.value), env.value);
             },
         });
     }
@@ -272,7 +279,7 @@ async function service(action) {
         process.exit(1);
     }
     if (action === "install") {
-        const described = describeInstall(await installService(env.value), env.value);
+        const described = describeServiceInstall(await installService(env.value), env.value);
         if (!described.ok) {
             console.error(`Error: ${described.error}`);
             process.exit(1);
@@ -295,18 +302,6 @@ async function service(action) {
     print(`Start at login: ${state.installed ? "installed" : "not installed"} (${state.file})`);
     print(`Running:        ${state.running ? "yes" : "no"}`);
 }
-function describeInstall(installed, env) {
-    if (!installed.ok)
-        return installed;
-    const lines = [`Studio will start when you log in. Service file: ${installed.value.file}`];
-    if (env.platform === "win32")
-        lines.push("Start it now with: portless-studio");
-    if (env.entryPath.includes(`${path.sep}_npx${path.sep}`)) {
-        lines.push("Note: this runs from the npx cache, which npm can clear. Install Studio globally with " +
-            "`npm install -g portless-studio` and run `portless-studio service install` again.");
-    }
-    return { ok: true, value: lines.join("\n") };
-}
 async function serviceEnv() {
     const entry = resolveServiceEntry(import.meta.url);
     if (!entry.ok)

package/dist/cli/login-service.js

@@ -38,6 +38,22 @@ export function resolveServiceEntry(moduleUrl) {
     }
     return ok(fileURLToPath(moduleUrl));
 }
+/**
+ * What `service install` and `init` print after installing. A service started from the npx cache
+ * breaks once npm clears it, so that case ends with the commands that move it to a global install.
+ */
+export function describeServiceInstall(installed, env) {
+    if (!installed.ok)
+        return installed;
+    const lines = [`Studio will start when you log in. Service file: ${installed.value.file}`];
+    if (env.platform === "win32")
+        lines.push("Start it now with: portless-studio");
+    if (/[\\/]_npx[\\/]/.test(env.entryPath)) {
+        lines.push("Note: this runs Studio from the npx cache, which npm can clear, and then Studio no longer " +
+            "starts at login. Install Studio globally and set up the service again:", "  npm i -g portless-studio", "  portless-studio service install");
+    }
+    return ok(lines.join("\n"));
+}
 export async function installService(env) {
     const file = serviceFile(env);
     fs.mkdirSync(path.dirname(file), { recursive: true });

package/dist/core/api/contract.js

@@ -62,6 +62,8 @@ export const API_PATHS = {
     focus: "/api/focus",
     /** POST `FocusAck`: a page says whether it got the window to the front. */
     focusAck: "/api/focus/ack",
+    /** GET returns `UpdateStatus`: whether a newer portless-studio is on npm. Read-only. */
+    update: "/api/update",
 };
 /**
  * Query parameter that carries the token where a header cannot: the browser's EventSource sends

package/dist/core/config/studio-config.js

@@ -35,6 +35,7 @@ export const DEFAULT_CONFIG = {
     systemNotifications: false,
     projectIcons: {},
     nameTemplate: DEFAULT_NAME_TEMPLATE,
+    checkForUpdates: true,
 };
 const MIN_SCAN_INTERVAL_MS = 1000;
 /**
@@ -55,6 +56,7 @@ export function parseConfig(input) {
         "proxyHttps",
         "desktopNotifications",
         "systemNotifications",
+        "checkForUpdates",
     ]) {
         const value = raw[key];
         if (value === undefined)

package/dist/core/updates/version.js

@@ -0,0 +1,62 @@
+/** The command that installs the latest release globally, shown with every update notice. */
+export const UPDATE_COMMAND = "npm i -g portless-studio";
+const VERSION = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+/**
+ * Compares two semver versions: negative when `a` is older, positive when newer, 0 when equal.
+ * A prerelease sorts before its release. Returns null when either is not a version.
+ */
+export function compareVersions(a, b) {
+    const left = VERSION.exec(a.trim());
+    const right = VERSION.exec(b.trim());
+    if (!left || !right)
+        return null;
+    for (let index = 1; index <= 3; index++) {
+        const difference = Number(left[index]) - Number(right[index]);
+        if (difference !== 0)
+            return Math.sign(difference);
+    }
+    return comparePrereleases(left[4], right[4]);
+}
+/** True when `latest` is a newer version than `current`; false for anything unreadable. */
+export function isNewerVersion(latest, current) {
+    const order = compareVersions(latest, current);
+    return order !== null && order > 0;
+}
+/** The line Studio prints on start when a newer release exists. */
+export function updateMessage(current, latest) {
+    return (`A new version of portless-studio is available: ${current} -> ${latest}. ` +
+        `Update with: ${UPDATE_COMMAND}`);
+}
+function comparePrereleases(a, b) {
+    if (a === b)
+        return 0;
+    if (a === undefined)
+        return 1;
+    if (b === undefined)
+        return -1;
+    const left = a.split(".");
+    const right = b.split(".");
+    for (let index = 0; index < Math.max(left.length, right.length); index++) {
+        const x = left[index];
+        const y = right[index];
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        const xNumeric = /^\d+$/.test(x);
+        const yNumeric = /^\d+$/.test(y);
+        if (xNumeric && yNumeric) {
+            const difference = Number(x) - Number(y);
+            if (difference !== 0)
+                return Math.sign(difference);
+        }
+        else if (xNumeric !== yNumeric) {
+            // Numeric identifiers sort before alphanumeric ones.
+            return xNumeric ? -1 : 1;
+        }
+        else if (x !== y) {
+            return x < y ? -1 : 1;
+        }
+    }
+    return 0;
+}

package/dist/server/application/auto-namer.js

@@ -8,6 +8,8 @@ export class AutoNamer {
     #log;
     #hooks;
     #attempted = new Set();
+    /** In how many scans in a row each port and process pair showed up unnamed. */
+    #streaks = new Map();
     constructor(registry, log, hooks = {}) {
         this.#registry = registry;
         this.#log = log;
@@ -15,6 +17,8 @@ export class AutoNamer {
     }
     /** Returns how many ports got a name. */
     async name(detected) {
+        const stableScans = this.#hooks.stableScans ?? 2;
+        const streaks = new Map();
         let named = 0;
         for (const port of detected) {
             if (port.suggestedName === null)
@@ -22,13 +26,23 @@ export class AutoNamer {
             const key = `${port.port}:${port.pid}`;
             if (this.#attempted.has(key))
                 continue;
+            const streak = (this.#streaks.get(key) ?? 0) + 1;
+            streaks.set(key, streak);
+            if (streak < stableScans)
+                continue;
             this.#attempted.add(key);
             if (await this.#nameOne(port.port, port.suggestedName))
                 named += 1;
         }
+        // A port missing from this scan starts counting again when it comes back.
+        this.#streaks = streaks;
         return named;
     }
     async #nameOne(port, suggested) {
+        // The scan is a few seconds old; portless may have registered the port since.
+        const { routes } = await this.#registry.readSnapshot();
+        if (routes.some((route) => route.port === port))
+            return false;
         let lastError = "";
         // The second name keeps two servers of the same project apart: `web.acme-4321`.
         for (const candidate of [suggested, `${suggested}-${port}`]) {

package/dist/server/application/doctor.js

@@ -9,6 +9,7 @@ export function diagnose(facts) {
         pushIf(checks, proxyOwnerCheck(facts));
         pushIf(checks, proxyCountCheck(facts));
         pushIf(checks, httpsTrustCheck(facts));
+        pushIf(checks, routesFileCheck(facts));
     }
     checks.push(studioPortCheck(facts));
     pushIf(checks, loginServiceCheck(facts));
@@ -145,6 +146,31 @@ function proxyOwnerCheck({ proxy, proxyPid, proxyOwner, platform, }) {
         },
     };
 }
+/** portless is before 1.0 and may change its state files; Studio says so instead of hiding routes. */
+function routesFileCheck({ routesFile, portless }) {
+    if (!routesFile)
+        return null;
+    const version = portless.version ? `portless ${portless.version}` : "This portless";
+    const advice = "Update portless-studio, or report it with the portless version.";
+    if (routesFile.state === "unexpected") {
+        return {
+            id: "routes-file",
+            status: "warn",
+            title: "Studio cannot read routes.json",
+            detail: `${version} saved it in a format this version of Studio does not know, so no route is ` +
+                `shown. ${advice}`,
+        };
+    }
+    if (routesFile.state !== "ok" || routesFile.unreadable === 0)
+        return null;
+    return {
+        id: "routes-file",
+        status: "warn",
+        title: `Studio cannot read ${routesFile.unreadable} of the ${routesFile.entries} routes portless saved`,
+        detail: `${version} may have changed the format of routes.json, so those routes are not shown. ` +
+            advice,
+    };
+}
 function proxyCountCheck({ proxyProcesses, platform }) {
     if (proxyProcesses === null || proxyProcesses.length < 2)
         return null;

package/dist/server/application/proxy-start-check.js

@@ -0,0 +1,83 @@
+import { err, ok } from "../../core/result.js";
+import { appError } from "./app-error.js";
+const DEFAULT_ATTEMPTS = 12;
+const DEFAULT_INTERVAL_MS = 250;
+/**
+ * The same registry, but a proxy start counts only once the proxy portless recorded is alive and
+ * the port listens. `portless proxy start` can exit 0 while another proxy, with another state
+ * directory, already holds the port; without this check Studio would report a start that never
+ * happened.
+ */
+export function confirmProxyStarts(registry, deps) {
+    return {
+        readSnapshot: () => registry.readSnapshot(),
+        watch: (onChange) => registry.watch(onChange),
+        createAlias: (name, port, force) => registry.createAlias(name, port, force),
+        removeAlias: (name) => registry.removeAlias(name),
+        installPortless: () => registry.installPortless(),
+        stopProxy: () => registry.stopProxy(),
+        proxyPid: () => registry.proxyPid(),
+        startProxy: (port, https) => startConfirmed(registry, deps, port, https),
+    };
+}
+async function startConfirmed(registry, deps, port, https) {
+    const ownPid = await registry.proxyPid().catch(() => null);
+    const before = await holderOf(deps, port);
+    // Our own proxy may still hold the port for a moment after a stop, during a restart.
+    if (before !== null && before !== "unknown" && (before.pid === null || before.pid !== ownPid)) {
+        return err(await inUse(deps, port, before));
+    }
+    const started = await registry.startProxy(port, https);
+    if (!started.ok)
+        return started;
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const attempts = deps.attempts ?? DEFAULT_ATTEMPTS;
+    let holder = null;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        if (attempt > 0)
+            await sleep(deps.intervalMs ?? DEFAULT_INTERVAL_MS);
+        holder = await holderOf(deps, port);
+        const { proxy } = await registry.readSnapshot();
+        if (!proxy.running)
+            continue;
+        // Without a port list, a live recorded pid is all there is to go on.
+        if (holder === "unknown")
+            return ok(undefined);
+        if (holder !== null && (await isOurs(registry, deps, holder)))
+            return ok(undefined);
+    }
+    if (holder !== null && holder !== "unknown")
+        return err(await inUse(deps, port, holder));
+    return err(appError("command_failed", `portless reported a start, but no proxy listens on port ${port}. Run \`portless proxy ` +
+        "start` in a terminal to see why."));
+}
+/** The listener is the proxy portless recorded, or a portless proxy it forked. */
+async function isOurs(registry, deps, holder) {
+    if (holder.pid === null)
+        return true;
+    if (holder.pid === (await registry.proxyPid().catch(() => null)))
+        return true;
+    return (await proxyPidsAmong(deps, [holder.pid])).has(holder.pid);
+}
+async function holderOf(deps, port) {
+    try {
+        return (await deps.scan()).find((item) => item.port === port) ?? null;
+    }
+    catch {
+        return "unknown";
+    }
+}
+async function inUse(deps, port, holder) {
+    const { pid } = holder;
+    if (pid !== null && (await proxyPidsAmong(deps, [pid])).has(pid)) {
+        return appError("port_in_use", `port ${port} is already used by another portless proxy (pid ${pid}) that keeps its state ` +
+            "in a different folder. Stop that proxy, or set proxyPort to a free port.");
+    }
+    const who = [holder.processName, pid === null ? "" : `pid ${pid}`].filter(Boolean).join(", ");
+    return appError("port_in_use", `port ${port} is in use by another process${who === "" ? "" : ` (${who})`}.`);
+}
+async function proxyPidsAmong(deps, pids) {
+    if (!deps.proxyPids)
+        return new Set();
+    return deps.proxyPids(pids).catch(() => new Set());
+}

package/dist/server/application/update-check.js

@@ -0,0 +1,66 @@
+import { isNewerVersion, UPDATE_COMMAND } from "../../core/updates/version.js";
+export const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/** Says whether a newer portless-studio is on npm, asking the registry at most once a day. */
+export class UpdateChecker {
+    #options;
+    #now;
+    #pending = null;
+    constructor(options) {
+        this.#options = options;
+        this.#now = options.now ?? Date.now;
+    }
+    async status() {
+        const { current } = this.#options;
+        const latest = (await this.#options.enabled()) ? await this.#latest() : null;
+        return {
+            current,
+            latest,
+            available: latest !== null && isNewerVersion(latest, current),
+            command: UPDATE_COMMAND,
+        };
+    }
+    #latest() {
+        const cached = this.#readCache();
+        const now = this.#now();
+        if (cached && cached.checkedAt <= now && now - cached.checkedAt < UPDATE_CHECK_INTERVAL_MS) {
+            return Promise.resolve(cached.latest);
+        }
+        this.#pending ??= this.#check(cached).finally(() => {
+            this.#pending = null;
+        });
+        return this.#pending;
+    }
+    async #check(cached) {
+        const latest = await this.#options.fetchLatest().catch(() => null);
+        // A failed request is written down too, so an offline machine does not retry on every start.
+        const entry = { checkedAt: this.#now(), latest: latest ?? cached?.latest ?? null };
+        try {
+            this.#options.cache.write(entry);
+        }
+        catch {
+            // The notice is optional; a read-only config folder only means asking again next time.
+        }
+        return entry.latest;
+    }
+    #readCache() {
+        try {
+            return this.#options.cache.read();
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * Update checks never run in CI or tests, and `PORTLESS_STUDIO_NO_UPDATE_CHECK=1` turns them off
+ * whatever the config says.
+ */
+export function updateChecksAllowed(env) {
+    if (env.PORTLESS_STUDIO_NO_UPDATE_CHECK === "1")
+        return false;
+    if (env.CI)
+        return false;
+    if (env.VITEST)
+        return false;
+    return true;
+}

package/dist/server/infrastructure/config/json-update-cache.js

@@ -0,0 +1,35 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writeFileAtomic } from "./atomic-write.js";
+const FILE_NAME = "update-check.json";
+/** `update-check.json` in the config file's folder. */
+export function updateCheckPathFor(configPath) {
+    return path.join(path.dirname(configPath), FILE_NAME);
+}
+/** The last update check as `{ "checkedAt": <epoch ms>, "latest": "<version>" | null }`. */
+export class JsonUpdateCache {
+    #file;
+    constructor(file) {
+        this.#file = file;
+    }
+    read() {
+        try {
+            const json = JSON.parse(fs.readFileSync(this.#file, "utf8"));
+            if (typeof json !== "object" || json === null)
+                return null;
+            const checkedAt = Reflect.get(json, "checkedAt");
+            const latest = Reflect.get(json, "latest");
+            if (typeof checkedAt !== "number" || !Number.isFinite(checkedAt))
+                return null;
+            if (latest !== null && typeof latest !== "string")
+                return null;
+            return { checkedAt, latest };
+        }
+        catch {
+            return null;
+        }
+    }
+    write(cache) {
+        writeFileAtomic(this.#file, `${JSON.stringify(cache, null, 2)}\n`);
+    }
+}