portless-studio 0.1.0 → 0.1.2

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)

package/dist/server/application/terminals.js

@@ -23,6 +23,8 @@ export class TerminalManager {
     #graceMs;
     #maxTerminals;
     #namingTimeoutMs;
+    #processTree;
+    #homeDir;
     #entries = new Map();
     #watchers = new Set();
     /** Folders a local program ran a terminal in. */
@@ -30,6 +32,8 @@ export class TerminalManager {
     #nextId = 1;
     #stopWorkspaceWatch;
     #naming = false;
+    #refreshingPorts = false;
+    #portsAgain = false;
     constructor(options) {
         this.#spawner = options.spawner;
         this.#workspace = options.workspace;
@@ -39,6 +43,8 @@ export class TerminalManager {
         this.#graceMs = options.graceMs ?? DEFAULT_GRACE_MS;
         this.#maxTerminals = options.maxTerminals ?? DEFAULT_MAX_TERMINALS;
         this.#namingTimeoutMs = options.namingTimeoutMs ?? DEFAULT_NAMING_TIMEOUT_MS;
+        this.#processTree = options.processTree;
+        this.#homeDir = options.homeDir;
     }
     get mode() {
         return this.#spawner.mode;
@@ -53,7 +59,21 @@ export class TerminalManager {
     /** Calls `onChange` when a terminal starts, ends, is named or closes. */
     watch(onChange) {
         this.#watchers.add(onChange);
-        return () => this.#watchers.delete(onChange);
+        this.#updateWorkspaceWatch();
+        return () => {
+            this.#watchers.delete(onChange);
+            this.#updateWorkspaceWatch();
+        };
+    }
+    /** Gives the terminal a name of its own; an empty one gives back the default title. */
+    rename(id, title) {
+        const entry = this.#entries.get(id);
+        if (!entry)
+            return notFound(id);
+        const wanted = title.trim().slice(0, MAX_TITLE_CHARS);
+        entry.info = { ...entry.info, title: wanted || entry.defaultTitle };
+        this.#publishStatus(entry);
+        return ok({ ...entry.info });
     }
     async create(request, origin) {
         if (this.#entries.size >= this.#maxTerminals) {
@@ -71,14 +91,20 @@ export class TerminalManager {
         const cols = readSize(request.cols, DEFAULT_COLS);
         const rows = readSize(request.rows, DEFAULT_ROWS);
         const naming = readNaming(request.name);
-        const title = (request.title?.trim() || command.value || "shell").slice(0, MAX_TITLE_CHARS);
+        const defaultTitle = (command.value || this.#spawner.shellName || "shell").slice(0, MAX_TITLE_CHARS);
+        const title = request.title?.trim().slice(0, MAX_TITLE_CHARS) || defaultTitle;
+        const project = await this.#projectOf(cwd.value);
         const entry = {
+            defaultTitle,
             info: {
                 id,
                 title,
                 cwd: cwd.value,
                 command: command.value ?? "",
-                project: await this.#projectOf(cwd.value),
+                project: project?.name ?? null,
+                worktree: project?.worktree ?? null,
+                branch: project?.branch ?? null,
+                ports: [],
                 status: "running",
                 exitCode: null,
                 startedAt: this.#now(),
@@ -117,7 +143,11 @@ export class TerminalManager {
         this.#entries.set(id, entry);
         if (naming)
             this.#startNaming(entry);
+        else
+            this.#updateWorkspaceWatch();
         this.#changed();
+        if (this.#watchers.size > 0)
+            void this.#refreshPorts();
         return ok({ ...entry.info });
     }
     input(id, text) {
@@ -157,6 +187,9 @@ export class TerminalManager {
         entry.info = { ...entry.info, status: "running", exitCode: null, endedAt: null };
         entry.info.startedAt = this.#now();
         this.#publishStatus(entry);
+        this.#updateWorkspaceWatch();
+        if (this.#watchers.size > 0)
+            void this.#refreshPorts();
         return ok({ ...entry.info });
     }
     /** Closes the terminal; its command, if still running, is killed. */
@@ -170,7 +203,7 @@ export class TerminalManager {
             entry.process.kill();
         entry.process = null;
         entry.watchers.clear();
-        this.#updateNamingWatch();
+        this.#updateWorkspaceWatch();
         this.#changed();
         return ok(undefined);
     }
@@ -232,7 +265,9 @@ export class TerminalManager {
                     message: "The command ended before it opened a port.",
                 });
             }
+            entry.info.ports = [];
             this.#publishStatus(entry);
+            this.#updateWorkspaceWatch();
         });
         return ok(undefined);
     }
@@ -270,6 +305,8 @@ export class TerminalManager {
             watcher();
     }
     async #resolveFolder(request, origin) {
+        if (origin.picked)
+            return this.#pickedFolder(request.cwd);
         if (typeof request.project === "string" && request.project !== "" && !request.cwd) {
             const folder = await this.#projectFolder(request.project);
             if (folder === null) {
@@ -294,6 +331,24 @@ export class TerminalManager {
             return ok(folder);
         return err(appError("path_not_allowed", "Terminals run only in project folders Studio shows. Start it from the CLI to use another folder."));
     }
+    /** A folder typed in the page's picker: any existing folder, with `~` as the home folder. */
+    #pickedFolder(typed) {
+        if (typeof typed !== "string" || typed.trim() === "") {
+            return err(appError("invalid_request", "Give the folder to open."));
+        }
+        let wanted = typed.trim();
+        if (this.#homeDir && (wanted === "~" || /^~[\\/]/.test(wanted))) {
+            wanted = `${this.#homeDir}${wanted.slice(1)}`;
+        }
+        if (!isAbsolute(wanted)) {
+            return err(appError("invalid_request", "The folder must be an absolute path or start with ~."));
+        }
+        const folder = this.#folders.directory(wanted);
+        if (folder === null) {
+            return err(appError("path_not_allowed", `${wanted} is not a folder on this machine.`));
+        }
+        return ok(folder);
+    }
     async #projectFolder(name) {
         const { routes, detected } = await this.#workspace.snapshot();
         for (const item of [...routes, ...detected]) {
@@ -303,6 +358,7 @@ export class TerminalManager {
         }
         return null;
     }
+    /** The project whose folder holds `cwd`, the innermost one when several do. */
     async #projectOf(cwd) {
         const { routes, detected } = await this.#workspace.snapshot();
         let best = null;
@@ -310,10 +366,70 @@ export class TerminalManager {
             const path = item.project?.path;
             if (!item.project || !path || !this.#folders.contains(path, cwd))
                 continue;
-            if (!best || path.length > best.length)
-                best = { name: item.project.name, length: path.length };
+            if (!best?.path || path.length > best.path.length)
+                best = item.project;
+        }
+        return best;
+    }
+    /**
+     * Links every listening process to the running terminal it descends from, and publishes the
+     * terminals whose ports changed. Calls that arrive while one runs make it run once more.
+     */
+    async #refreshPorts() {
+        const tree = this.#processTree;
+        if (!tree)
+            return;
+        if (this.#refreshingPorts) {
+            this.#portsAgain = true;
+            return;
+        }
+        this.#refreshingPorts = true;
+        try {
+            do {
+                this.#portsAgain = false;
+                await this.#linkPorts(tree);
+            } while (this.#portsAgain);
+        }
+        finally {
+            this.#refreshingPorts = false;
+        }
+    }
+    async #linkPorts(tree) {
+        const running = [...this.#entries.values()].filter((entry) => entry.info.status === "running" && entry.info.pid !== null);
+        if (running.length === 0)
+            return;
+        const { routes, detected } = await this.#workspace.snapshot();
+        const listeners = new Map();
+        for (const item of detected) {
+            if (item.pid !== null)
+                listeners.set(item.port, { port: item.port, route: null, url: null });
+        }
+        const pids = new Map();
+        for (const item of detected)
+            if (item.pid !== null)
+                pids.set(item.port, item.pid);
+        for (const item of routes) {
+            if (item.listenerPid === undefined)
+                continue;
+            pids.set(item.port, item.listenerPid);
+            listeners.set(item.port, { port: item.port, route: item.name, url: item.url });
+        }
+        const ancestry = new Map();
+        for (const pid of new Set(pids.values())) {
+            ancestry.set(pid, await tree.ancestors(pid).catch(() => []));
+        }
+        for (const entry of running) {
+            const pid = entry.info.pid;
+            const ports = [...pids]
+                .filter(([, listener]) => listener === pid || ancestry.get(listener)?.includes(pid ?? -1))
+                .map(([port]) => listeners.get(port))
+                .filter((port) => port !== undefined)
+                .sort((a, b) => a.port - b.port);
+            if (JSON.stringify(ports) === JSON.stringify(entry.info.ports))
+                continue;
+            entry.info = { ...entry.info, ports };
+            this.#publishStatus(entry);
         }
-        return best?.name ?? null;
     }
     async #portsInUse() {
         const { routes, detected } = await this.#workspace.snapshot();
@@ -330,18 +446,29 @@ export class TerminalManager {
             this.#publishStatus(entry);
         }, this.#namingTimeoutMs);
         entry.namingTimer.unref?.();
-        this.#updateNamingWatch();
+        this.#updateWorkspaceWatch();
     }
     #waitingEntries() {
         return [...this.#entries.values()].filter((entry) => entry.info.naming?.state === "waiting");
     }
-    /** Watches the workspace, which keeps Studio scanning, only while a terminal waits for a port. */
-    #updateNamingWatch() {
-        const waiting = this.#waitingEntries().length > 0;
-        if (waiting && !this.#stopWorkspaceWatch) {
-            this.#stopWorkspaceWatch = this.#workspace.watch(() => void this.#nameNewPorts());
+    /**
+     * Watches the workspace, which keeps Studio scanning, only while a terminal waits for a port,
+     * or while someone watches the list and a terminal runs, so the ports it opened stay current.
+     */
+    #updateWorkspaceWatch() {
+        const linking = this.#processTree !== undefined &&
+            this.#watchers.size > 0 &&
+            [...this.#entries.values()].some((entry) => entry.info.status === "running");
+        const needed = linking || this.#waitingEntries().length > 0;
+        if (needed && !this.#stopWorkspaceWatch) {
+            this.#stopWorkspaceWatch = this.#workspace.watch(() => {
+                if (this.#waitingEntries().length > 0)
+                    void this.#nameNewPorts();
+                if (this.#watchers.size > 0)
+                    void this.#refreshPorts();
+            });
         }
-        else if (!waiting && this.#stopWorkspaceWatch) {
+        else if (!needed && this.#stopWorkspaceWatch) {
             this.#stopWorkspaceWatch();
             this.#stopWorkspaceWatch = undefined;
         }
@@ -357,7 +484,7 @@ export class TerminalManager {
         }
         finally {
             this.#naming = false;
-            this.#updateNamingWatch();
+            this.#updateWorkspaceWatch();
         }
     }
     async #nameFor(entry, routes, detected) {

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

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

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

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