portless-studio 0.1.2 → 0.1.4

package/README.md

@@ -16,7 +16,7 @@ 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, searching routes with Ctrl+K, filtering with the Filter popover 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 opening a route's terminal in the right-hand pane](docs/images/demo.gif)
 
 The screenshots use the built-in sample data (`?demo`), not a real machine.
 

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",
@@ -373,7 +423,9 @@ function terminalTools(client) {
             name: "list_terminals",
             title: "List Studio terminals",
             description: "Lists the terminals Studio runs: id, title, folder, command, project, whether it still " +
-                "runs, exit code and the port it named.",
+                "runs, exit code, the port it named and who started it. Terminals that were running when " +
+                "Studio last stopped are listed with stopped_by_restart: true; restart_terminal runs them " +
+                "again.",
             inputSchema: NO_INPUT,
             call: async () => {
                 const result = await client.readPrivate(API_PATHS.terminals);
@@ -381,8 +433,12 @@ function terminalTools(client) {
                     return failure(result.error);
                 const { terminals } = result.value;
                 const running = terminals.filter((terminal) => terminal.status === "running").length;
+                const stopped = terminals.filter((terminal) => terminal.stoppedByRestart === true).length;
+                const restorable = stopped > 0
+                    ? `, ${stopped} stopped by a Studio restart: run ${stopped === 1 ? "it" : "them"} again with restart_terminal`
+                    : "";
                 return {
-                    summary: `${plural(terminals.length, "terminal")} (${running} running).`,
+                    summary: `${plural(terminals.length, "terminal")} (${running} running${restorable}).`,
                     data: terminals.map(terminalItem),
                 };
             },
@@ -506,6 +562,32 @@ function terminalTools(client) {
                 return { summary: `Stopping ${id.value}. list_terminals shows when it has exited.` };
             },
         },
+        {
+            name: "restart_terminal",
+            title: "Run a terminal's command again",
+            description: "Runs a terminal's command again in the same terminal: stops it first when it still runs. " +
+                "Use it for a terminal stopped by a Studio restart (stopped_by_restart in list_terminals) " +
+                "or one whose command ended.",
+            inputSchema: {
+                type: "object",
+                properties: { id: TERMINAL_ID_SCHEMA },
+                required: ["id"],
+                additionalProperties: false,
+            },
+            call: async (args) => {
+                const id = readString(args, "id");
+                if (!id.ok)
+                    return invalid(id.error);
+                const result = await client.write("POST", API_PATHS.terminalRestart(id.value));
+                if (!result.ok)
+                    return failure(result.error);
+                const terminal = result.value;
+                return {
+                    summary: `Running ${terminal.id} again in ${terminal.cwd}: ${terminal.command || "shell"}. Read its output with read_terminal {"id": "${terminal.id}"}.`,
+                    data: terminalItem(terminal),
+                };
+            },
+        },
         {
             name: "focus_studio",
             title: "Show something in Studio",
@@ -561,6 +643,8 @@ function terminalItem(terminal) {
         pid: terminal.pid,
         named: terminal.naming?.name ?? null,
         port: terminal.naming?.port ?? null,
+        started_by: terminal.startedBy ?? null,
+        stopped_by_restart: terminal.stoppedByRestart === true,
     };
 }
 async function readSnapshot(client, includeStudio = false) {

package/dist/cli/studio-items.js

@@ -8,6 +8,7 @@ export function routeItem(route) {
         project: route.project?.name ?? null,
         worktree: route.project?.worktree ?? null,
         pid: route.listenerPid ?? route.pid,
+        startedAt: route.startedAt ?? null,
     };
 }
 export function detectedItem(port) {
@@ -19,6 +20,7 @@ export function detectedItem(port) {
         suggestedName: port.suggestedName,
         project: port.project?.name ?? null,
         worktree: port.project?.worktree ?? null,
+        startedAt: port.startedAt ?? null,
     };
 }
 export function proxyItem(proxy) {

package/dist/core/api/contract.js

@@ -51,6 +51,8 @@ export const API_PATHS = {
      * Studio shows.
      */
     terminalsInFolder: "/api/terminals/in-folder",
+    /** GET returns `RecentCommandsResponse`: the last commands run in each folder. */
+    terminalsRecentCommands: "/api/terminals/recent-commands",
     /**
      * GET returns `TerminalInfo`; PATCH `RenameTerminalRequest` renames it; DELETE stops the command
      * if it runs and closes the terminal.
@@ -67,7 +69,10 @@ export const API_PATHS = {
     terminalInput: (id) => `/api/terminals/${encodeURIComponent(id)}/input`,
     /** POST: Ctrl+C, then SIGTERM, then SIGKILL until the command ends. */
     terminalStop: (id) => `/api/terminals/${encodeURIComponent(id)}/stop`,
-    /** POST: runs the same command again in the same terminal. */
+    /**
+     * POST: runs the same command again in the same terminal; also starts a terminal that was
+     * stopped by a Studio restart.
+     */
     terminalRestart: (id) => `/api/terminals/${encodeURIComponent(id)}/restart`,
     /** POST `FocusRequest`: brings a Studio page to the front showing a route, port or terminal. */
     focus: "/api/focus",

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

@@ -2,6 +2,14 @@ import { DEFAULT_NAME_TEMPLATE, parseNameTemplate } from "../ports/name-template
 import { projectIconKind } from "../projects/project-icon.js";
 import { err, ok } from "../result.js";
 import { DEFAULT_VIEW, isItemKey, parseViews } from "../views/view.js";
+export const DEFAULT_TERMINAL_APPEARANCE = {
+    fontSize: 12,
+    lineHeight: 1.2,
+    cursorStyle: "block",
+    cursorBlink: true,
+    scrollback: 10_000,
+    theme: "studio",
+};
 export const DEFAULT_CONFIG = {
     port: 4949,
     autoName: false,
@@ -38,6 +46,10 @@ export const DEFAULT_CONFIG = {
     checkForUpdates: true,
     shortUrls: false,
     showStudioRoute: false,
+    showEphemeralPorts: false,
+    terminal: DEFAULT_TERMINAL_APPEARANCE,
+    restoreTerminals: "ask",
+    defaultEditor: null,
 };
 const MIN_SCAN_INTERVAL_MS = 1000;
 /**
@@ -61,6 +73,7 @@ export function parseConfig(input) {
         "checkForUpdates",
         "shortUrls",
         "showStudioRoute",
+        "showEphemeralPorts",
     ]) {
         const value = raw[key];
         if (value === undefined)
@@ -145,8 +158,80 @@ export function parseConfig(input) {
             return err(`"nameTemplate" ${parsed.error}`);
         config.nameTemplate = template;
     }
+    if (raw.terminal !== undefined) {
+        const terminal = parseTerminalAppearance(raw.terminal);
+        if (!terminal.ok)
+            return terminal;
+        config.terminal = terminal.value;
+    }
+    if (raw.restoreTerminals !== undefined) {
+        const value = raw.restoreTerminals;
+        if (value !== "ask" && value !== "always" && value !== "never") {
+            return err(`"restoreTerminals" must be "ask", "always" or "never".`);
+        }
+        config.restoreTerminals = value;
+    }
+    if (raw.defaultEditor !== undefined) {
+        const value = raw.defaultEditor;
+        if (value !== null && (typeof value !== "string" || !APP_ID.test(value))) {
+            return err(`"defaultEditor" must be the id of an app in Open with, like "vscode", or null.`);
+        }
+        config.defaultEditor = value;
+    }
     return ok(config);
 }
+/** The shape of open-with app ids: `vscode`, `vscode-insiders`, `custom-1`. */
+const APP_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
+function parseTerminalAppearance(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        return err(`"terminal" must be an object.`);
+    }
+    const raw = input;
+    const terminal = { ...DEFAULT_TERMINAL_APPEARANCE };
+    if (raw.fontSize !== undefined) {
+        if (!isWholeBetween(raw.fontSize, 10, 24)) {
+            return err(`"terminal.fontSize" must be a whole number from 10 to 24.`);
+        }
+        terminal.fontSize = raw.fontSize;
+    }
+    if (raw.lineHeight !== undefined) {
+        const value = raw.lineHeight;
+        if (typeof value !== "number" || !Number.isFinite(value) || value < 1 || value > 2) {
+            return err(`"terminal.lineHeight" must be a number from 1 to 2.`);
+        }
+        terminal.lineHeight = value;
+    }
+    if (raw.cursorStyle !== undefined) {
+        const value = raw.cursorStyle;
+        if (value !== "block" && value !== "bar" && value !== "underline") {
+            return err(`"terminal.cursorStyle" must be "block", "bar" or "underline".`);
+        }
+        terminal.cursorStyle = value;
+    }
+    if (raw.cursorBlink !== undefined) {
+        if (typeof raw.cursorBlink !== "boolean") {
+            return err(`"terminal.cursorBlink" must be true or false.`);
+        }
+        terminal.cursorBlink = raw.cursorBlink;
+    }
+    if (raw.scrollback !== undefined) {
+        if (!isWholeBetween(raw.scrollback, 1000, 100_000)) {
+            return err(`"terminal.scrollback" must be a whole number from 1000 to 100000.`);
+        }
+        terminal.scrollback = raw.scrollback;
+    }
+    if (raw.theme !== undefined) {
+        const value = raw.theme;
+        if (value !== "studio" && value !== "dark" && value !== "light") {
+            return err(`"terminal.theme" must be "studio", "dark" or "light".`);
+        }
+        terminal.theme = value;
+    }
+    return ok(terminal);
+}
+function isWholeBetween(value, min, max) {
+    return typeof value === "number" && Number.isInteger(value) && value >= min && value <= max;
+}
 /** Empty names and values are dropped, so clearing a field in the panel removes its icon. */
 function parseProjectIcons(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))

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}`;
+}