portless-studio 0.1.1 → 0.1.2

package/dist/server/application/doctor.js

@@ -10,11 +10,13 @@ export function diagnose(facts) {
         pushIf(checks, proxyCountCheck(facts));
         pushIf(checks, httpsTrustCheck(facts));
         pushIf(checks, routesFileCheck(facts));
+        pushIf(checks, shorterUrlsCheck(facts));
     }
     checks.push(studioPortCheck(facts));
     pushIf(checks, loginServiceCheck(facts));
     pushIf(checks, safariCheck(facts));
     pushIf(checks, notificationsCheck(facts));
+    pushIf(checks, dockerCheck(facts));
     return checks;
 }
 export function createDoctorService(deps) {
@@ -42,15 +44,59 @@ async function runAction(action, facts, deps) {
         return deps.controlProxy("start");
     if (action === "restart-proxy")
         return deps.controlProxy("restart");
-    const saved = await deps.updateConfig({ ...facts.config, proxyPort: 1355, proxyHttps: false });
+    if (action === "use-short-urls")
+        return turnOnShortUrls(facts, deps);
+    const http = { ...facts.config, proxyPort: 1355, proxyHttps: false };
+    return applyProxyConfig(http, "HTTP on port 1355", facts, deps);
+}
+/**
+ * Turns `shortUrls` on and checks that Studio really listens on port 80. The proxy keeps its
+ * port and keeps running; when the listen fails, the previous config comes back.
+ */
+async function turnOnShortUrls(facts, deps) {
+    const config = { ...facts.config, shortUrls: true };
+    const saved = await deps.updateConfig(config);
     if (!saved.ok)
         return saved;
-    if (!facts.proxy.running)
-        return deps.controlProxy("start");
-    if (facts.proxyOwner === "you")
-        return deps.controlProxy("restart");
-    return ok(`Saved HTTP on port 1355. Stop the current proxy with \`${stopProxyAsAdminCommand(facts.platform)}\` ` +
-        `${adminWords(facts.platform)}, then start the new one from the proxy menu.`);
+    const status = await deps.syncShortUrls(config);
+    if (status.state === "listening") {
+        return ok("Names now open as http://name.localhost: Studio forwards port " +
+            `${status.port} to the proxy on port ${status.target}.`);
+    }
+    await deps.updateConfig(facts.config);
+    await deps.syncShortUrls(facts.config);
+    const why = status.state === "failed" ? `${status.message} ` : "";
+    const code = status.state === "failed" && status.reason === "in-use" ? "port_in_use" : "command_failed";
+    return err(appError(code, `${why}Studio kept the previous settings, so names still open with ` +
+        `:${facts.config.proxyPort}.`));
+}
+/**
+ * Saves the proxy settings, then starts or restarts the proxy with them when Studio may. When
+ * that start fails, the previous settings come back and a proxy that was running starts again on
+ * them, so names keep working.
+ */
+async function applyProxyConfig(config, what, facts, deps) {
+    const saved = await deps.updateConfig(config);
+    if (!saved.ok)
+        return saved;
+    if (facts.proxy.running && facts.proxyOwner !== "you") {
+        return ok(`Saved ${what}. Stop the current proxy with \`${stopProxyAsAdminCommand(facts.platform)}\` ` +
+            `${adminWords(facts.platform)}, then start the new one from the proxy menu.`);
+    }
+    const started = await deps.controlProxy(facts.proxy.running ? "restart" : "start");
+    if (started.ok)
+        return started;
+    await deps.updateConfig(facts.config);
+    let back = "Studio went back to the previous settings.";
+    if (facts.proxy.running) {
+        const again = await deps.controlProxy("start");
+        if (again.ok) {
+            back =
+                "Studio went back to the previous settings and started the proxy on port " +
+                    `${facts.config.proxyPort} again.`;
+        }
+    }
+    return err({ ...started.error, message: `${started.error.message} ${back}` });
 }
 function portlessCheck({ portless }) {
     if (portless.installed) {
@@ -106,8 +152,9 @@ function proxyRunningCheck(facts) {
         status: "warn",
         title: "The proxy is not running",
         detail: needsSudo
-            ? `Names do not open until it runs. Port ${config.proxyPort} needs sudo, so Studio cannot ` +
-                "start it; HTTP on port 1355 needs nothing."
+            ? `Names do not open until it runs. portless asks for sudo below port 1024, so Studio ` +
+                `cannot start it on port ${config.proxyPort}; HTTP on port 1355 needs nothing, and short ` +
+                "URLs drop the port from names."
             : "Names do not open until it runs.",
         fix: needsSudo
             ? { label: "Use HTTP on port 1355", action: "use-http-1355" }
@@ -327,6 +374,149 @@ function notificationsCheck({ config, systemNotifier }) {
         fix: { label: "Install notify-send", command: "sudo apt install libnotify-bin" },
     };
 }
+const UNPRIVILEGED_PORT_SETTING = "net.ipv4.ip_unprivileged_port_start=80";
+/**
+ * Short URLs drop the port number from every name (`http://name.localhost`). Studio itself listens
+ * on port 80 and forwards to the proxy, only when a test bind shows this user may listen there
+ * without sudo; it never changes the system.
+ */
+function shorterUrlsCheck(facts) {
+    const { proxy, config, platform, port80, shortUrls } = facts;
+    const https = proxy.running ? proxy.https : config.proxyHttps;
+    if (https) {
+        if (!config.shortUrls)
+            return null;
+        return {
+            id: "shorter-urls",
+            status: "ok",
+            title: "Short URLs work over HTTP only",
+            detail: "The proxy serves HTTPS, so names keep their port. Switch the proxy to HTTP to open " +
+                "them as http://name.localhost.",
+        };
+    }
+    const port = (proxy.running ? proxy.port : null) ?? config.proxyPort;
+    if (port === 80) {
+        return {
+            id: "shorter-urls",
+            status: "ok",
+            title: "Names open without a port number",
+            detail: "The proxy uses port 80, so names open as http://name.localhost.",
+        };
+    }
+    if (shortUrls?.state === "listening") {
+        return {
+            id: "shorter-urls",
+            status: "ok",
+            title: "Names open without a port number",
+            detail: `Studio listens on port ${shortUrls.port} and forwards to the proxy on port ` +
+                `${shortUrls.target}, so names open as http://name.localhost.`,
+        };
+    }
+    const now = `Names open as http://name.localhost:${port}`;
+    if (config.shortUrls)
+        return failedShortUrlsCheck(facts, now);
+    if (port80 === undefined)
+        return null;
+    if (port80 === "free") {
+        return {
+            id: "shorter-urls",
+            status: "ok",
+            title: "Shorter URLs: port 80 is available",
+            detail: `${now}. This user can listen on port 80 without sudo, so Studio can listen there and ` +
+                `forward to the proxy, and names open as http://name.localhost. The proxy stays on ` +
+                `port ${port}.`,
+            fix: { label: "Use short URLs", action: "use-short-urls" },
+        };
+    }
+    if (port80 === "in-use") {
+        return {
+            id: "shorter-urls",
+            status: "ok",
+            title: "Port 80 is taken by another program",
+            detail: `${now}. Stop the program on port 80 to drop the port number from names.`,
+        };
+    }
+    if (platform !== "linux") {
+        return {
+            id: "shorter-urls",
+            status: "ok",
+            title: "Shorter URLs: this system does not allow port 80",
+            detail: `${now}. This user cannot listen on port 80 here, so names keep the port.`,
+        };
+    }
+    return {
+        id: "shorter-urls",
+        status: "ok",
+        title: "Shorter URLs need a one-time system setting",
+        detail: `${now}. ${SYSCTL_ADVICE} Then run the checks again and choose Use short URLs.`,
+        fix: SYSCTL_FIX,
+    };
+}
+/** `shortUrls` is on and Studio does not listen: names still work, with the port. */
+function failedShortUrlsCheck(facts, now) {
+    const { platform, port80, shortUrls } = facts;
+    const reason = shortUrls?.state === "failed" ? shortUrls.reason : port80;
+    const retry = port80 === "free"
+        ? { fix: { label: "Try port 80 again", action: "use-short-urls" } }
+        : {};
+    if (reason === "in-use") {
+        return {
+            id: "shorter-urls",
+            status: "warn",
+            title: "Short URLs are on, but port 80 is taken by another program",
+            detail: `${now}. Stop the program on port 80, then run the checks again.`,
+            ...retry,
+        };
+    }
+    if (reason === "denied" && platform === "linux" && port80 !== "free") {
+        return {
+            id: "shorter-urls",
+            status: "warn",
+            title: "Short URLs are on, but Linux does not let this user listen on port 80",
+            detail: `${now}. ${SYSCTL_ADVICE} Then run the checks again and choose Try port 80 again.`,
+            fix: SYSCTL_FIX,
+        };
+    }
+    return {
+        id: "shorter-urls",
+        status: "warn",
+        title: "Short URLs are on, but Studio does not listen on port 80",
+        detail: shortUrls?.state === "failed"
+            ? `${now}. Studio could not listen there: ${shortUrls.message}`
+            : `${now}. Studio is not running, or has not tried port 80 yet.`,
+        ...retry,
+    };
+}
+const SYSCTL_ADVICE = "Linux lets only root listen on ports below 1024. The command lets every user on this machine " +
+    "listen on port 80 and up until the next restart; Studio never runs it. To keep it after a " +
+    `restart, also run \`echo '${UNPRIVILEGED_PORT_SETTING}' | sudo tee ` +
+    "/etc/sysctl.d/99-portless-studio.conf`.";
+const SYSCTL_FIX = {
+    label: "Allow port 80 until the next restart",
+    command: `sudo sysctl -w ${UNPRIVILEGED_PORT_SETTING}`,
+};
+/** Information only: without Docker, container ports simply do not show. */
+function dockerCheck({ docker }) {
+    if (docker === undefined || docker.state === "missing")
+        return null;
+    if (docker.state === "ok") {
+        const count = docker.containers === 1 ? "1 running container" : `${docker.containers} running containers`;
+        return {
+            id: "docker",
+            status: "ok",
+            title: "Studio reads Docker containers",
+            detail: `docker ps lists ${count}; the ports they publish show under Detected.`,
+        };
+    }
+    return {
+        id: "docker",
+        status: "ok",
+        title: "Studio cannot read Docker containers",
+        detail: "The docker command is installed, but docker ps did not answer: Docker is not running, " +
+            "or this user may not use it (on Linux, the docker group). Ports of containers do not " +
+            "show under Detected until it answers.",
+    };
+}
 function startCommand(config) {
     const tls = config.proxyHttps ? "--https" : "--no-tls";
     return `portless proxy start --port ${config.proxyPort} ${tls}`;

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

@@ -1,4 +1,5 @@
 import { projectOf, suggestName, } from "../../core/ports/detected-port.js";
+import { containerProjectInfo } from "../../core/ports/docker-container.js";
 /**
  * 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.
@@ -10,17 +11,59 @@ export async function discoverPorts(scanner, projects, context) {
         ...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.
+    // 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 &&
         !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;
+    return [
+        ...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);
+}
+/** 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

@@ -42,6 +42,9 @@ export class StudioRuntime {
     #events = new EventLog();
     #icons;
     #routeProjectStore;
+    #containers;
+    #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 +84,9 @@ export class StudioRuntime {
         this.#autoNamedStore = options.autoNamedStore ?? memoryAutoNamedStore();
         this.#notifier = options.notifier ?? null;
         this.#routeProjectStore = options.routeProjectStore ?? memoryRouteProjectStore();
+        this.#containers = options.containers ?? null;
+        this.#shortUrls = options.shortUrls ?? null;
+        this.#shortUrls?.onChange(() => this.#notify());
         const noIcons = {
             served: async () => null,
             remote: async () => null,
@@ -98,11 +104,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,11 +139,12 @@ 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);
@@ -147,7 +159,18 @@ export class StudioRuntime {
             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() {
@@ -259,11 +282,18 @@ export class StudioRuntime {
             scan: async () => scan.ports,
             answersHttp: (port) => this.#scanner.answersHttp(port),
         };
-        const excludedPorts = [this.#studioPort, state.proxy.port, ...scan.proxyPorts].filter((port) => port !== null);
+        const forwarderPort = this.#shortUrls?.publicPort() ?? null;
+        const excludedPorts = [
+            this.#studioPort,
+            forwarderPort,
+            state.proxy.port,
+            ...scan.proxyPorts,
+        ].filter((port) => port !== null);
         const found = await discoverPorts(cached, this.#projects, {
             config,
             routes: state.routes,
             excludedPorts,
+            containers: scan.containers,
         });
         return found.map((item) => {
             if (item.cwd === null || !item.project)
@@ -276,14 +306,21 @@ export class StudioRuntime {
     #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;
     }
+    /** 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;
@@ -444,7 +481,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 +610,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)