portless-studio 0.1.1 → 0.1.3

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

@@ -1,26 +1,101 @@
 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,
         ...context.config.ignoredPorts,
     ]);
     const ignored = context.config.ignoredProcesses.map((name) => name.toLowerCase());
+    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.
-    const candidates = (await scanner.scan()).filter((port) => port.pid !== null &&
+    // never to a dev server this person started. A container's port is shown as the container.
+    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));
+    const fromContainers = [...published];
     // Probes run in parallel; a port that never answers costs its timeout once, not per port.
-    const answers = await Promise.all(candidates.map((port) => scanner.answersHttp(port.port)));
-    return candidates
-        .filter((port, index) => answers[index] && isDevServer(port, projects))
-        .map((port) => toDetected(port, projects, context.config.nameTemplate))
-        .sort((a, b) => a.port - b.port);
+    const [answers, containerAnswers] = await Promise.all([
+        Promise.all(candidates.map((port) => scanner.answersHttp(port.port))),
+        Promise.all(fromContainers.map(([port]) => scanner.answersHttp(port))),
+    ]);
+    const template = context.config.nameTemplate;
+    const found = [
+        ...candidates
+            .filter((port, index) => answers[index] && isDevServer(port, projects))
+            .map((port) => toDetected(port, projects, template)),
+        ...fromContainers
+            .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) {
+    const ports = new Map();
+    if (isIgnoredProcess(CONTAINER_PROCESS, ignored))
+        return ports;
+    for (const container of containers) {
+        for (const port of container.ports) {
+            if (!skippedPorts.has(port) && !ports.has(port))
+                ports.set(port, container);
+        }
+    }
+    return ports;
+}
+/** What a container's row shows as its process, and what `ignoredProcesses` matches. */
+const CONTAINER_PROCESS = "docker";
+function containerDetected(port, container, nameTemplate) {
+    const project = container.composeProject;
+    return {
+        port,
+        pid: null,
+        processName: CONTAINER_PROCESS,
+        cwd: null,
+        suggestedName: suggestName(containerProjectInfo(container), nameTemplate, port),
+        ...(project === null ? {} : { project: { name: project, worktree: null } }),
+        container: {
+            name: container.name,
+            image: container.image,
+            composeProject: project,
+        },
+    };
 }
 // Interpreters dev servers run on. Anything else counts only when it was built inside the
 // project, like `target/debug/api`, so editors, chat apps and background tools stay out.

package/dist/server/application/short-urls.js

@@ -0,0 +1,136 @@
+import { withPublicPort } from "../../core/routes/route.js";
+/** The port browsers use when a URL has none. */
+export const SHORT_URL_PORT = 80;
+/**
+ * Keeps Studio's port-80 forwarder in line with the config. portless asks for sudo to start its
+ * proxy below port 1024 on Linux and macOS even where the system allows the bind, so the proxy
+ * stays on `proxyPort` and Studio listens on port 80 itself, as the current user, never with sudo.
+ */
+export class ShortUrls {
+    #forwarding;
+    #port;
+    #log;
+    #reachesProxy;
+    #watchers = new Set();
+    #running = null;
+    #status = { state: "off" };
+    #queue = Promise.resolve();
+    #synced = false;
+    constructor(options) {
+        this.#forwarding = options.forwarding;
+        this.#port = options.port ?? SHORT_URL_PORT;
+        this.#log = options.log;
+        this.#reachesProxy = options.reachesProxy ?? null;
+    }
+    /** The port Studio listens on for short URLs, whether or not it listens right now. */
+    get port() {
+        return this.#port;
+    }
+    /** True once a sync ran in this process; a CLI command that never syncs has to ask elsewhere. */
+    get synced() {
+        return this.#synced;
+    }
+    /** The port in route URLs while the forwarder listens; null keeps the proxy port. */
+    publicPort() {
+        return this.#running?.port ?? null;
+    }
+    status() {
+        return this.#status;
+    }
+    /**
+     * The status for the doctor. In the server it is this process's own; elsewhere Studio may run
+     * in another process, so port 80 is asked whether it reaches the proxy. Undefined when unknown.
+     */
+    async inspect(config) {
+        if (this.#synced)
+            return this.#status;
+        const wanted = this.#wanted(config);
+        if (wanted.state !== "listening")
+            return wanted;
+        const reached = await (this.#reachesProxy?.(this.#port) ?? Promise.resolve(false));
+        return reached ? wanted : undefined;
+    }
+    /** Calls `onChange` when the public port changes. Returns an unsubscribe. */
+    onChange(onChange) {
+        this.#watchers.add(onChange);
+        return () => this.#watchers.delete(onChange);
+    }
+    /**
+     * Listens, moves or stops to match the config, one sync at a time. A failed listen is tried
+     * again on the next sync, so a doctor fix or a config save after `sysctl` picks it up.
+     */
+    sync(config) {
+        const next = this.#queue.then(() => this.#sync(config));
+        this.#queue = next.catch(() => { });
+        return next;
+    }
+    close() {
+        const next = this.#queue.then(async () => {
+            await this.#stop();
+            this.#status = { state: "off" };
+        });
+        this.#queue = next.catch(() => { });
+        return next;
+    }
+    async #sync(config) {
+        this.#synced = true;
+        const wanted = this.#wanted(config);
+        if (wanted.state !== "listening") {
+            await this.#stop();
+            this.#status = wanted;
+            return wanted;
+        }
+        const target = config.proxyPort;
+        if (this.#running?.target === target)
+            return this.#status;
+        await this.#stop();
+        const started = await this.#forwarding.listen(this.#port, target);
+        if (!started.ok) {
+            this.#status = { state: "failed", port: this.#port, ...started.error };
+            this.#log(`short URLs are off: ${started.error.message} Names keep :${target}.`);
+            return this.#status;
+        }
+        this.#running = { target, port: started.value.port, close: started.value.close };
+        this.#status = { state: "listening", port: started.value.port, target };
+        this.#log(`short URLs: port ${started.value.port} forwards to the proxy on port ${target}`);
+        this.#changed();
+        return this.#status;
+    }
+    #wanted(config) {
+        if (!config.shortUrls)
+            return { state: "off" };
+        if (config.proxyHttps)
+            return { state: "https" };
+        if (config.proxyPort === this.#port)
+            return { state: "proxy-on-port" };
+        return { state: "listening", port: this.#port, target: config.proxyPort };
+    }
+    async #stop() {
+        const running = this.#running;
+        if (!running)
+            return;
+        this.#running = null;
+        await running.close();
+        this.#changed();
+    }
+    #changed() {
+        for (const watcher of this.#watchers)
+            watcher();
+    }
+}
+/**
+ * The registry the rest of Studio reads: the same routes, with URLs on the public port while the
+ * forwarder listens, so the page, the CLI, MCP and notifications all show the URL that opens.
+ */
+export function publicUrls(registry, publicPort) {
+    return {
+        readSnapshot: async () => withPublicPort(await registry.readSnapshot(), publicPort()),
+        watch: (onChange) => registry.watch(onChange),
+        createAlias: (name, port, force) => registry.createAlias(name, port, force),
+        removeAlias: (name) => registry.removeAlias(name),
+        installPortless: () => registry.installPortless(),
+        startProxy: (port, https) => registry.startProxy(port, https),
+        stopProxy: () => registry.stopProxy(),
+        proxyPid: () => registry.proxyPid(),
+    };
+}

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. */
@@ -42,6 +42,10 @@ export class StudioRuntime {
     #events = new EventLog();
     #icons;
     #routeProjectStore;
+    #containers;
+    #ephemeralRange;
+    #shortUrls;
+    #ready = Promise.resolve();
     /** Last project seen per route name; null until read from the store. */
     #routeProjects = null;
     /** What the store last got, so an unchanged map is not written again. */
@@ -81,6 +85,10 @@ export class StudioRuntime {
         this.#autoNamedStore = options.autoNamedStore ?? memoryAutoNamedStore();
         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 = {
             served: async () => null,
             remote: async () => null,
@@ -98,11 +106,16 @@ export class StudioRuntime {
             return;
         this.#started = true;
         this.#stopConfigWatch = this.#store.watch(() => void this.#reloadConfig());
-        void Promise.all([this.#reloadConfig(), this.#loadAutoNamed()]).then(() => {
+        this.#ready = Promise.all([this.#reloadConfig(), this.#loadAutoNamed()]).then(async () => {
             this.#reschedule();
             void this.ensureProxy();
+            await this.#shortUrls?.sync(this.#config);
         });
     }
+    /** Resolves once `start` read the config and the short-URL forwarder settled. */
+    ready() {
+        return this.#ready;
+    }
     /**
      * Starts the portless proxy when the config asks for it and it is not running, so names work
      * without anyone running portless by hand. Called at start and after portless gets installed.
@@ -128,26 +141,39 @@ export class StudioRuntime {
         this.#stopRegistryWatch?.();
         this.#stopRegistryWatch = undefined;
         this.#watchers.clear();
+        void this.#shortUrls?.close();
     }
     setStudioPort(port) {
         this.#studioPort = port;
     }
-    async readSnapshot() {
+    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,
         };
         this.#observe(snapshot, config);
-        return this.#withIcons(snapshot, config);
+        const shown = options.includeStudio ? routes : this.#listedRoutes(routes, config);
+        return this.#withIcons({ ...snapshot, routes: shown }, config);
+    }
+    /**
+     * The routes people see: without Studio's own (`studio`, on Studio's port or its short-URL
+     * port) unless `showStudioRoute` is on. It only takes room, and the page is already open.
+     */
+    #listedRoutes(routes, config) {
+        if (config.showStudioRoute)
+            return routes;
+        const own = new Set([this.#studioPort, this.#shortUrls?.publicPort() ?? null]);
+        return routes.filter((route) => !own.has(route.port));
     }
     /** The last notable changes of this run, oldest first, for a page that connects later. */
     recentEvents() {
@@ -160,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() {
@@ -172,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);
@@ -192,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]) {
@@ -255,35 +283,62 @@ 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 excludedPorts = [this.#studioPort, state.proxy.port, ...scan.proxyPorts].filter((port) => port !== null);
-        const found = await discoverPorts(cached, this.#projects, {
+        const forwarderPort = this.#shortUrls?.publicPort() ?? null;
+        const excludedPorts = [
+            this.#studioPort,
+            forwarderPort,
+            state.proxy.port,
+            ...scan.proxyPorts,
+        ].filter((port) => port !== null);
+        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) {
         if (this.#scan && Date.now() - this.#scan.at < maxAgeMs)
             return Promise.resolve(this.#scan);
-        this.#scanning ??= this.#scanner.scan().then(async (ports) => {
+        this.#scanning ??= Promise.all([this.#scanner.scan(), this.#readContainers()]).then(async ([ports, containers]) => {
             const proxyPorts = await this.#proxyPortsAmong(ports).catch(() => []);
-            this.#scan = { ports, proxyPorts, at: Date.now() };
+            this.#scan = { ports, proxyPorts, containers, at: Date.now() };
             this.#scanning = null;
             return this.#scan;
         });
         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)
+            return [];
+        const reading = await this.#containers.read().catch(() => null);
+        return reading?.state === "ok" ? reading.containers : [];
+    }
     #reschedule() {
         clearTimeout(this.#timer);
         this.#timer = undefined;
@@ -303,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) {
@@ -444,7 +500,7 @@ export class StudioRuntime {
     /** Turns what changed since the last look into events, and tells the OS when nobody watches. */
     #observe(snapshot, config) {
         const next = {
-            routes: snapshot.routes,
+            routes: this.#listedRoutes(snapshot.routes, config),
             detected: snapshot.detected,
             proxy: snapshot.proxy,
         };
@@ -573,6 +629,8 @@ export class StudioRuntime {
         this.#config = config;
         this.#reschedule();
         this.#notify();
+        if (this.#started)
+            void this.#shortUrls?.sync(config);
     }
     #notify() {
         for (const watcher of this.#watchers)