portless-studio 0.1.2 → 0.1.3

package/dist/cli/cli-args.js

@@ -17,6 +17,10 @@ Usage:
                                       what is wrong (exit code 1 when something fails)
   portless-studio list [--json]       List named routes and ports without a name, from the running
                                       Studio (or read directly when it is not running)
+  portless-studio env [--prefix P] [--strip S] [--direct] [--json] [name...]
+                                      Print KEY=url lines for a .env file, one per route
+                                      (api.acme -> API_ACME_URL); a name also picks its *.name
+                                      routes (docs/cli.md)
   portless-studio mcp                 Run an MCP server on stdio so AI agents can list, name and
                                       stop dev servers through the running Studio (docs/mcp.md)
   portless-studio run [--name <name>] [--cwd <dir>] -- <command...>
@@ -32,7 +36,10 @@ Options:
   --no-open        Do not open the browser
   --no-register    Do not register the "studio" portless alias for the dashboard
   -y, --yes        With init and uninstall: accept every default without asking
-  --json           With doctor, config and list: print JSON for scripts and agents
+  --json           With doctor, config, list and env: print JSON for scripts and agents
+  --prefix <p>     With env: put p in front of every key, e.g. VITE_ or NEXT_PUBLIC_
+  --strip <s>      With env: drop the .s suffix from names before they become keys
+  --direct         With env: use http://localhost:<port> instead of the named URL
   --name <name>    With run: name for the port the command opens (default: the suggested one)
   --cwd <dir>      With run: folder to run in (default: the current folder)
   -h, --help       Show this help
@@ -52,6 +59,7 @@ const SUBCOMMANDS = new Set([
     "config",
     "doctor",
     "list",
+    "env",
     "mcp",
     "run",
     "open",
@@ -91,6 +99,16 @@ export function parseCliArgs(argv) {
         return ok({ command: "doctor", json });
     if (subcommand === "list")
         return ok({ command: "list", json });
+    if (subcommand === "env") {
+        return ok({
+            command: "env",
+            json,
+            direct: values.direct === true,
+            prefix: values.prefix?.trim() || null,
+            strip: values.strip?.trim() || null,
+            names: positionals.map((name) => name.trim()).filter((name) => name !== ""),
+        });
+    }
     if (subcommand === "mcp")
         return ok({ command: "mcp" });
     if (subcommand === "run") {
@@ -152,23 +170,34 @@ function parseFlags(args, subcommand) {
             ? { ...common, edit: { type: "boolean" }, json }
             : subcommand === "doctor" || subcommand === "list"
                 ? { ...common, json }
-                : subcommand === "service" || subcommand === "mcp" || subcommand === "open"
-                    ? common
-                    : subcommand === "run"
-                        ? { ...common, name: { type: "string" }, cwd: { type: "string" } }
-                        : {
-                            ...common,
-                            port: { type: "string" },
-                            open: { type: "boolean" },
-                            register: { type: "boolean" },
-                        };
+                : subcommand === "env"
+                    ? {
+                        ...common,
+                        json,
+                        direct: { type: "boolean" },
+                        prefix: { type: "string" },
+                        strip: { type: "string" },
+                    }
+                    : subcommand === "service" || subcommand === "mcp" || subcommand === "open"
+                        ? common
+                        : subcommand === "run"
+                            ? { ...common, name: { type: "string" }, cwd: { type: "string" } }
+                            : {
+                                ...common,
+                                port: { type: "string" },
+                                open: { type: "boolean" },
+                                register: { type: "boolean" },
+                            };
     // 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,
         tokens: true,
-        allowPositionals: subcommand === "service" || subcommand === "run" || subcommand === "open",
+        allowPositionals: subcommand === "service" ||
+            subcommand === "run" ||
+            subcommand === "open" ||
+            subcommand === "env",
     });
     for (const token of tokens) {
         if (token.kind === "option" && options[token.name]?.type === "boolean") {

package/dist/cli/env-command.js

@@ -0,0 +1,34 @@
+import { envEntries, formatEnvLine, selectEnvRoutes, } from "../core/routes/env-lines.js";
+/** `portless-studio env`: `KEY=url` lines for a `.env` file, one per named route. */
+export async function runEnvCommand(options) {
+    const fromStudio = await options.readFromStudio();
+    const routes = fromStudio.ok ? fromStudio.value : await options.readLocally();
+    const selected = selectEnvRoutes(routes, options.names);
+    if (!selected.ok)
+        return fail(options, selected.error);
+    const entries = envEntries(selected.value, {
+        direct: options.direct,
+        ...(options.prefix === null ? {} : { prefix: options.prefix }),
+        ...(options.strip === null ? {} : { strip: options.strip }),
+    });
+    if (!entries.ok)
+        return fail(options, entries.error);
+    if (options.json) {
+        const source = fromStudio.ok ? "studio" : "local";
+        options.print(JSON.stringify({ source, variables: entries.value }, null, 2));
+        return 0;
+    }
+    if (!fromStudio.ok) {
+        options.printError("(Studio is not running: read directly from portless.)");
+    }
+    if (entries.value.length === 0) {
+        options.printError("No named routes yet.");
+        return 0;
+    }
+    options.print(entries.value.map(formatEnvLine).join("\n"));
+    return 0;
+}
+function fail(options, message) {
+    options.printError(`Error: ${message}`);
+    return 1;
+}

package/dist/cli/index.js

@@ -11,6 +11,7 @@ import { HELP, parseCliArgs, resolveStartSettings, } from "./cli-args.js";
 import { runCommand } from "./command-runner.js";
 import { editConfig, printConfig, printConfigJson } from "./config-command.js";
 import { runDoctorCommand } from "./doctor-command.js";
+import { runEnvCommand } from "./env-command.js";
 import { runOpenCommand } from "./focus-command.js";
 import { runInit } from "./init.js";
 import { runListCommand } from "./list-command.js";
@@ -65,6 +66,9 @@ async function main() {
         case "list":
             await list(options.json);
             return;
+        case "env":
+            await env(options);
+            return;
         case "mcp":
             await mcp();
             return;
@@ -125,6 +129,21 @@ async function list(json) {
     // The local fallback may leave scan timers behind; the list is all this command does.
     process.exit(code);
 }
+async function env(options) {
+    const client = await studioClient();
+    const code = await runEnvCommand({
+        ...options,
+        print,
+        printError: (line) => console.error(line),
+        readFromStudio: async () => {
+            const snapshot = await client.read(API_PATHS.snapshot);
+            return snapshot.ok ? { ok: true, value: snapshot.value.routes } : snapshot;
+        },
+        readLocally: async () => (await createStudioServices().registry.readSnapshot()).routes,
+    });
+    // The local fallback may leave watchers behind; the lines are all this command prints.
+    process.exit(code);
+}
 /** stdout carries only protocol messages; warnings go to stderr through `console.error`. */
 async function mcp() {
     const client = await studioClient();

package/dist/cli/mcp/studio-tools.js

@@ -1,5 +1,6 @@
 import { API_PATHS, INCLUDE_STUDIO_PARAM, } from "../../core/api/contract.js";
 import { err, ok } from "../../core/result.js";
+import { envEntries, formatEnvLine, selectEnvRoutes } from "../../core/routes/env-lines.js";
 import { plainText } from "../../core/terminals/terminal.js";
 import { describeProxy, detectedItem, proxyItem, routeItem } from "../studio-items.js";
 const NAMING_HINT = "Make each name say what the work is: start it with the ticket key, PR number or a short task " +
@@ -15,6 +16,7 @@ export const AGENT_INSTRUCTIONS = [
     "Start dev servers with run_in_terminal (or `portless-studio run -- <command>` in a shell) instead",
     "of in your own shell, so the user can watch their output in Studio; read it with read_terminal.",
     "When the user asks to see something, call focus_studio.",
+    "To point an app at another one by name in a .env file, call env_lines and write its lines.",
     NAMING_HINT,
 ].join(" ");
 const PROXY_ACTIONS = ["start", "stop", "restart"];
@@ -61,6 +63,54 @@ export function createStudioTools(client) {
                 };
             },
         },
+        {
+            name: "env_lines",
+            title: "Build .env lines from route names",
+            description: "Returns KEY=url lines for a .env file, one per route: api.acme becomes " +
+                "API_ACME_URL=http://api.acme.localhost:1355, a URL that keeps working when the port " +
+                "changes. names keeps only those routes (acme also keeps every *.acme route); prefix puts " +
+                "VITE_ or NEXT_PUBLIC_ in front; strip drops a suffix like the project (acme turns api.acme " +
+                "into API_URL); direct uses http://localhost:<port> instead. It only returns text: write " +
+                "the lines into the user's .env.local yourself when they ask.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    names: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: 'Route names to keep, e.g. ["acme"]; all routes when absent',
+                    },
+                    prefix: { type: "string", description: "Put in front of every key, e.g. VITE_" },
+                    strip: { type: "string", description: "Suffix dropped from names, e.g. acme" },
+                    direct: { type: "boolean", description: "Use http://localhost:<port> (default false)" },
+                },
+                additionalProperties: false,
+            },
+            call: async (args) => {
+                const names = Array.isArray(args.names)
+                    ? args.names.filter((name) => typeof name === "string" && name !== "")
+                    : [];
+                const snapshot = await readSnapshot(client);
+                if (!snapshot.ok)
+                    return snapshot.error;
+                const selected = selectEnvRoutes(snapshot.value.routes, names);
+                if (!selected.ok)
+                    return { summary: selected.error, isError: true };
+                const entries = envEntries(selected.value, {
+                    direct: args.direct === true,
+                    ...(typeof args.prefix === "string" ? { prefix: args.prefix.trim() } : {}),
+                    ...(typeof args.strip === "string" ? { strip: args.strip } : {}),
+                });
+                if (!entries.ok)
+                    return { summary: entries.error, isError: true };
+                if (entries.value.length === 0)
+                    return { summary: "No named routes yet.", data: { variables: [] } };
+                return {
+                    summary: entries.value.map(formatEnvLine).join("\n"),
+                    data: { variables: entries.value },
+                };
+            },
+        },
         {
             name: "list_detected_ports",
             title: "List ports without a name",

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

@@ -38,6 +38,7 @@ export const DEFAULT_CONFIG = {
     checkForUpdates: true,
     shortUrls: false,
     showStudioRoute: false,
+    showEphemeralPorts: false,
 };
 const MIN_SCAN_INTERVAL_MS = 1000;
 /**
@@ -61,6 +62,7 @@ export function parseConfig(input) {
         "checkForUpdates",
         "shortUrls",
         "showStudioRoute",
+        "showEphemeralPorts",
     ]) {
         const value = raw[key];
         if (value === undefined)

package/dist/core/ports/helper-ports.js

@@ -0,0 +1,86 @@
+/** Where the operating systems hand out ports for port 0 when nobody changed the setting. */
+export const DEFAULT_EPHEMERAL_RANGES = {
+    linux: { first: 32768, last: 60999 },
+    darwin: { first: 49152, last: 65535 },
+    win32: { first: 49152, last: 65535 },
+};
+/** Node (`--inspect`) and Chrome (`--remote-debugging-port`) debugger defaults. */
+export const DEBUGGER_PORTS = [9229, 9222];
+/** True for the `/json/version` answer of a V8 inspector or a Chrome DevTools endpoint. */
+export function isDebuggerVersionInfo(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    return ["V8-Version", "Browser", "Protocol-Version"].some((key) => Object.hasOwn(value, key));
+}
+export function isInRange(port, range) {
+    return range !== null && port >= range.first && port <= range.last;
+}
+/**
+ * Splits detected ports into the main list and "Other ports". A debugger, another port of the
+ * process that serves a named route, and a port in the ephemeral range are helpers, not
+ * servers a person opens. The rest is grouped per process: the lowest port outside the ephemeral
+ * range is the row, the others are its `extraPorts`.
+ */
+export function arrangeDetected(input) {
+    const main = [];
+    const otherPorts = [];
+    for (const item of input.detected) {
+        const route = siblingRoute(item, input.routes);
+        const reason = otherReason(item, route, input);
+        if (reason === null) {
+            main.push(item);
+            continue;
+        }
+        otherPorts.push({ ...item, reason, ...(route === null ? {} : { routeName: route.name }) });
+    }
+    return {
+        detected: groupByProcess(main, input.ephemeralRange),
+        otherPorts: otherPorts.sort((a, b) => a.port - b.port),
+    };
+}
+function otherReason(item, route, input) {
+    const probe = input.debuggers.get(item.port) ?? "unknown";
+    if (probe === "debugger" || (probe === "unknown" && DEBUGGER_PORTS.includes(item.port))) {
+        return "debugger";
+    }
+    if (route !== null)
+        return "sibling";
+    // Docker picks a host port in this range for `-P`; people do open those.
+    if (!item.container && !input.showEphemeral && isInRange(item.port, input.ephemeralRange)) {
+        return "ephemeral";
+    }
+    return null;
+}
+/**
+ * The named route whose process also listens on this port, like an HMR socket. Another process
+ * in the same folder is a separate server (an app and its Storybook) and stays in the main list.
+ */
+function siblingRoute(item, routes) {
+    if (item.pid === null)
+        return null;
+    return routes.find((route) => route.pid === item.pid) ?? null;
+}
+function groupByProcess(items, range) {
+    const byPid = new Map();
+    const rows = [];
+    for (const item of items) {
+        if (item.pid === null) {
+            rows.push(item);
+            continue;
+        }
+        const group = byPid.get(item.pid);
+        if (group)
+            group.push(item);
+        else
+            byPid.set(item.pid, [item]);
+    }
+    for (const group of byPid.values()) {
+        const sorted = [...group].sort((a, b) => a.port - b.port);
+        const head = sorted.find((item) => !isInRange(item.port, range)) ?? sorted[0];
+        if (head === undefined)
+            continue;
+        const extraPorts = sorted.filter((item) => item !== head).map((item) => item.port);
+        rows.push(extraPorts.length === 0 ? head : { ...head, extraPorts });
+    }
+    return rows.sort((a, b) => a.port - b.port);
+}

package/dist/core/routes/env-lines.js

@@ -0,0 +1,72 @@
+import { directUrl } from "../ports/direct-url.js";
+import { err, ok } from "../result.js";
+const VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** `api.acme` -> `API_ACME_URL`, with the strip suffix removed and the prefix in front. */
+export function envKey(name, options = {}) {
+    const suffix = stripSuffix(options.strip);
+    const base = suffix !== null && name.endsWith(suffix) ? name.slice(0, -suffix.length) : name;
+    const words = base
+        .toUpperCase()
+        .replace(/[^A-Z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    const key = `${words === "" ? "" : `${words}_`}URL`;
+    const prefix = options.prefix ?? "";
+    if (prefix === "")
+        return /^[0-9]/.test(key) ? `_${key}` : key;
+    return `${prefix.endsWith("_") ? prefix : `${prefix}_`}${key}`;
+}
+/**
+ * Keeps the routes the names point at: a name matches itself and every route ending in `.<name>`,
+ * so `acme` picks `api.acme` and `web.acme`. No names keeps every route.
+ */
+export function selectEnvRoutes(routes, names) {
+    if (names.length === 0)
+        return ok([...routes]);
+    const matches = (route, name) => route.name === name || route.name.endsWith(`.${name}`);
+    const missing = names.find((name) => !routes.some((route) => matches(route, name)));
+    if (missing !== undefined)
+        return err(`No route matches "${missing}".`);
+    return ok(routes.filter((route) => names.some((name) => matches(route, name))));
+}
+/** One key and value per route, sorted by route name; fails on a bad prefix or a repeated key. */
+export function envEntries(routes, options = {}) {
+    const prefix = options.prefix ?? "";
+    if (prefix !== "" && !VARIABLE_NAME.test(prefix)) {
+        return err(`The prefix "${prefix}" must use letters, digits and _, and not start with a digit.`);
+    }
+    const sorted = [...routes].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    const entries = [];
+    for (const route of sorted) {
+        const key = envKey(route.name, options);
+        const taken = entries.find((entry) => entry.key === key);
+        if (taken) {
+            return err(`${taken.name} and ${route.name} both become ${key}. Pass only one of them, or change the strip suffix.`);
+        }
+        entries.push({
+            name: route.name,
+            key,
+            value: options.direct ? directUrl(route.port) : route.url,
+        });
+    }
+    return ok(entries);
+}
+/** `KEY=value` lines for a `.env` file, one per route. */
+export function envLines(routes, options = {}) {
+    const entries = envEntries(routes, options);
+    if (!entries.ok)
+        return entries;
+    return ok(entries.value.map(formatEnvLine));
+}
+export function formatEnvLine(entry) {
+    return `${entry.key}=${quoteEnvValue(entry.value)}`;
+}
+/** Double quotes only when a `.env` reader would otherwise cut or change the value. */
+function quoteEnvValue(value) {
+    if (value !== "" && !/[\s#"'`$\\]/.test(value))
+        return value;
+    return `"${value.replace(/[\\"]/g, (char) => `\\${char}`)}"`;
+}
+function stripSuffix(strip) {
+    const trimmed = strip?.trim().replace(/^\.+/, "") ?? "";
+    return trimmed === "" ? null : `.${trimmed}`;
+}

package/dist/server/application/port-discovery.js

@@ -1,10 +1,16 @@
 import { projectOf, suggestName, } from "../../core/ports/detected-port.js";
 import { containerProjectInfo } from "../../core/ports/docker-container.js";
+import { arrangeDetected, } from "../../core/ports/helper-ports.js";
+/** Only the main Detected list of `discoverPortGroups`. */
+export async function discoverPorts(scanner, projects, context) {
+    return (await discoverPortGroups(scanner, projects, context)).detected;
+}
 /**
  * Listening ports a person would want to name: they answer HTTP, have no portless route, and are
- * not Studio, the proxy or something the config ignores. Sorted by port.
+ * not Studio, the proxy or something the config ignores. Debuggers, ephemeral ports and ports of a
+ * server that already has a name go to `otherPorts` (see `arrangeDetected`). Sorted by port.
  */
-export async function discoverPorts(scanner, projects, context) {
+export async function discoverPortGroups(scanner, projects, context) {
     const skippedPorts = new Set([
         ...context.routes.map((route) => route.port),
         ...context.excludedPorts,
@@ -14,7 +20,8 @@ export async function discoverPorts(scanner, projects, context) {
     const published = containerPorts(context.containers ?? [], skippedPorts, ignored);
     // A port whose process we cannot read belongs to another user or the system (printing, DNS),
     // never to a dev server this person started. A container's port is shown as the container.
-    const candidates = (await scanner.scan()).filter((port) => port.pid !== null &&
+    const scanned = await scanner.scan();
+    const candidates = scanned.filter((port) => port.pid !== null &&
         !skippedPorts.has(port.port) &&
         !published.has(port.port) &&
         !isIgnoredProcess(port.processName, ignored));
@@ -25,7 +32,7 @@ export async function discoverPorts(scanner, projects, context) {
         Promise.all(fromContainers.map(([port]) => scanner.answersHttp(port))),
     ]);
     const template = context.config.nameTemplate;
-    return [
+    const found = [
         ...candidates
             .filter((port, index) => answers[index] && isDevServer(port, projects))
             .map((port) => toDetected(port, projects, template)),
@@ -33,6 +40,31 @@ export async function discoverPorts(scanner, projects, context) {
             .filter((_, index) => containerAnswers[index])
             .map(([port, container]) => containerDetected(port, container, template)),
     ].sort((a, b) => a.port - b.port);
+    return arrangeDetected({
+        detected: found,
+        debuggers: await debuggerProbes(scanner, found),
+        ephemeralRange: context.ephemeralRange ?? null,
+        showEphemeral: context.config.showEphemeralPorts,
+        routes: listeningRoutes(context.routes, scanned),
+    });
+}
+const UNKNOWN = "unknown";
+async function debuggerProbes(scanner, found) {
+    const probe = scanner.probeDebugger?.bind(scanner);
+    if (!probe)
+        return new Map();
+    const answers = await Promise.all(found.map((item) => probe(item.port).catch(() => UNKNOWN)));
+    return new Map(found.map((item, index) => [item.port, answers[index] ?? UNKNOWN]));
+}
+/** Routes whose port a readable process listens on now; a closed route claims no siblings. */
+function listeningRoutes(routes, scanned) {
+    const byPort = new Map(scanned.map((port) => [port.port, port]));
+    return routes.flatMap((route) => {
+        const listener = byPort.get(route.port);
+        if (!listener || listener.pid === null)
+            return [];
+        return [{ name: route.name, port: route.port, pid: listener.pid, cwd: listener.cwd }];
+    });
 }
 /** Published port -> container, without the ports the filters skip. */
 function containerPorts(containers, skippedPorts, ignored) {

package/dist/server/application/studio-runtime.js

@@ -8,7 +8,7 @@ import { appError } from "./app-error.js";
 import { memoryAutoNamedStore, } from "./auto-named-store.js";
 import { AutoNamer } from "./auto-namer.js";
 import { IconResolver } from "./icon-resolver.js";
-import { discoverPorts } from "./port-discovery.js";
+import { discoverPortGroups } from "./port-discovery.js";
 import { EventLog, eventsBetween } from "./studio-events.js";
 import { SYSTEM_NOTIFICATION_KINDS } from "./system-notifier.js";
 /** Keeps the projects in memory only; for tests and for `init`, which runs once. */
@@ -43,6 +43,7 @@ export class StudioRuntime {
     #icons;
     #routeProjectStore;
     #containers;
+    #ephemeralRange;
     #shortUrls;
     #ready = Promise.resolve();
     /** Last project seen per route name; null until read from the store. */
@@ -85,6 +86,7 @@ export class StudioRuntime {
         this.#notifier = options.notifier ?? null;
         this.#routeProjectStore = options.routeProjectStore ?? memoryRouteProjectStore();
         this.#containers = options.containers ?? null;
+        this.#ephemeralRange = options.ephemeralRange ?? null;
         this.#shortUrls = options.shortUrls ?? null;
         this.#shortUrls?.onChange(() => this.#notify());
         const noIcons = {
@@ -147,14 +149,15 @@ export class StudioRuntime {
     async readSnapshot(options = {}) {
         const state = await this.#registry.readSnapshot();
         const config = await this.#currentConfig();
-        const detected = await this.#detect(state, config, false);
-        this.#lastDetected = JSON.stringify(detected);
+        const found = await this.#detect(state, config, false);
+        this.#lastDetected = JSON.stringify(found);
         const routes = await this.#detailedRoutes(state.routes);
         const snapshot = {
             proxy: state.proxy,
             portless: state.portless,
             routes,
-            detected,
+            detected: found.detected,
+            otherPorts: found.otherPorts,
             autoName: config.autoName,
             readAt: state.readAt,
         };
@@ -183,7 +186,7 @@ export class StudioRuntime {
     /** One fresh scan with the current config, filtered the same way as the snapshot. */
     async detectPorts() {
         const state = await this.#registry.readSnapshot();
-        return this.#detect(state, await this.#currentConfig(), true);
+        return (await this.#detect(state, await this.#currentConfig(), true)).detected;
     }
     /** The config in effect: the file as last read, or the defaults while it is broken. */
     settings() {
@@ -195,11 +198,12 @@ export class StudioRuntime {
      */
     async stoppablePids() {
         const state = await this.#registry.readSnapshot();
-        const detected = await this.#detect(state, await this.#currentConfig(), true);
+        const found = await this.#detect(state, await this.#currentConfig(), true);
         const pids = new Map();
-        for (const item of detected)
+        for (const item of [...found.detected, ...found.otherPorts]) {
             if (item.pid !== null)
                 pids.set(item.pid, item.port);
+        }
         const pidByPort = this.#pidByPort();
         for (const route of state.routes) {
             const pid = pidByPort.get(route.port);
@@ -215,7 +219,8 @@ export class StudioRuntime {
      */
     async openableFolders() {
         const state = await this.#registry.readSnapshot();
-        const detected = await this.#detect(state, await this.#currentConfig(), false);
+        const found = await this.#detect(state, await this.#currentConfig(), false);
+        const detected = [...found.detected, ...found.otherPorts];
         const routes = await this.#detailedRoutes(state.routes);
         const folders = new Set();
         for (const item of [...routes, ...detected]) {
@@ -278,9 +283,11 @@ export class StudioRuntime {
     }
     async #detect(state, config, fresh) {
         const scan = await this.#scanPorts(fresh ? 0 : config.scanIntervalMs);
+        const probeDebugger = this.#scanner.probeDebugger?.bind(this.#scanner);
         const cached = {
             scan: async () => scan.ports,
             answersHttp: (port) => this.#scanner.answersHttp(port),
+            ...(probeDebugger ? { probeDebugger } : {}),
         };
         const forwarderPort = this.#shortUrls?.publicPort() ?? null;
         const excludedPorts = [
@@ -289,18 +296,23 @@ export class StudioRuntime {
             state.proxy.port,
             ...scan.proxyPorts,
         ].filter((port) => port !== null);
-        const found = await discoverPorts(cached, this.#projects, {
+        const found = await discoverPortGroups(cached, this.#projects, {
             config,
             routes: state.routes,
             excludedPorts,
             containers: scan.containers,
+            ephemeralRange: await this.#readEphemeralRange(),
         });
-        return found.map((item) => {
+        const withProject = (item) => {
             if (item.cwd === null || !item.project)
                 return item;
             const project = itemProjectAt(this.#projects.read(item.cwd), item.cwd);
             return project === null ? item : { ...item, project };
-        });
+        };
+        return {
+            detected: found.detected.map(withProject),
+            otherPorts: found.otherPorts.map(withProject),
+        };
     }
     /** Reuses a scan younger than `maxAgeMs`, and shares one scan between concurrent callers. */
     #scanPorts(maxAgeMs) {
@@ -314,6 +326,12 @@ export class StudioRuntime {
         });
         return this.#scanning;
     }
+    /** A range that cannot be read turns the ephemeral rule off rather than failing the scan. */
+    async #readEphemeralRange() {
+        if (!this.#ephemeralRange)
+            return null;
+        return this.#ephemeralRange().catch(() => null);
+    }
     /** Docker is optional: any failure to read it means no containers, never a failed scan. */
     async #readContainers() {
         if (!this.#containers)
@@ -340,19 +358,20 @@ export class StudioRuntime {
         try {
             let state = await this.#registry.readSnapshot();
             const config = await this.#currentConfig();
-            let detected = await this.#detect(state, config, true);
-            // Each step reads the routes again after the previous one changed them.
-            if (config.autoName && (await this.#namer.name(detected)) > 0) {
+            const first = await this.#detect(state, config, true);
+            // Each step reads the routes again after the previous one changed them. Other ports are
+            // helpers of a named server, debuggers or temporary ports: auto mode never names them.
+            if (config.autoName && (await this.#namer.name(first.detected)) > 0) {
                 state = await this.#registry.readSnapshot();
             }
             if (await this.#removeAbandonedAutoNames(state, config)) {
                 state = await this.#registry.readSnapshot();
             }
-            detected = await this.#detect(state, config, false);
+            const found = await this.#detect(state, config, false);
             const healthChanged = await this.#probeRoutes(state.routes);
             const routes = await this.#detailedRoutes(state.routes);
-            this.#observe({ ...state, routes, detected }, config);
-            if (healthChanged || JSON.stringify(detected) !== this.#lastDetected)
+            this.#observe({ ...state, routes, detected: found.detected }, config);
+            if (healthChanged || JSON.stringify(found) !== this.#lastDetected)
                 this.#notify();
         }
         catch (error) {