portless-studio 0.1.1 → 0.1.3

package/dist/server/infrastructure/terminal/process-tree.js

@@ -0,0 +1,71 @@
+import * as fs from "node:fs";
+import { runProcess } from "../system/process-runner.js";
+/** Deeper than any real chain of shells and tools; a guard against a bad read. */
+const MAX_DEPTH = 64;
+/** One `ps` answer serves every pid of a scan on macOS. */
+const PS_CACHE_MS = 2_000;
+/** The parent pid in the text of `/proc/<pid>/stat`; the name in parentheses may hold anything. */
+export function parseStatParent(stat) {
+    const fields = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+    const parent = Number(fields[1]);
+    return stat.includes(")") && Number.isInteger(parent) ? parent : null;
+}
+/** Every pid's parent from `ps -A -o pid=,ppid=`. */
+export function parsePsParents(output) {
+    const parents = new Map();
+    for (const line of output.split("\n")) {
+        const match = /^\s*(\d+)\s+(\d+)\s*$/.exec(line);
+        if (match)
+            parents.set(Number(match[1]), Number(match[2]));
+    }
+    return parents;
+}
+/** The parent, its parent and so on, ending before pid 0 or at a pid already seen. */
+export function walkAncestors(pid, parentOf) {
+    const ancestors = [];
+    const seen = new Set([pid]);
+    let current = parentOf(pid);
+    while (current !== null && current > 0 && !seen.has(current) && ancestors.length < MAX_DEPTH) {
+        ancestors.push(current);
+        seen.add(current);
+        current = parentOf(current);
+    }
+    return ancestors;
+}
+/**
+ * Parent processes on this machine: `/proc` on Linux, one `ps` on macOS. Windows answers nothing,
+ * so terminals there list no ports.
+ */
+export function systemProcessTree(platform = process.platform) {
+    if (platform === "linux") {
+        return {
+            ancestors: async (pid) => walkAncestors(pid, (current) => {
+                try {
+                    return parseStatParent(fs.readFileSync(`/proc/${current}/stat`, "utf8"));
+                }
+                catch {
+                    return null;
+                }
+            }),
+        };
+    }
+    if (platform === "darwin") {
+        let cached = null;
+        const table = () => {
+            if (!cached || Date.now() - cached.at > PS_CACHE_MS) {
+                cached = {
+                    at: Date.now(),
+                    parents: runProcess("ps", ["-A", "-o", "pid=,ppid="], { timeoutMs: 3_000 }).then((outcome) => parsePsParents(outcome.exitCode === 0 ? outcome.stdout : "")),
+                };
+            }
+            return cached.parents;
+        };
+        return {
+            ancestors: async (pid) => {
+                const parents = await table();
+                return walkAncestors(pid, (current) => parents.get(current) ?? null);
+            },
+        };
+    }
+    return { ancestors: async () => [] };
+}

package/dist/server/infrastructure/terminal/terminal-spawner.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { runProcess, stopProcessTree } from "../system/process-runner.js";
+import { nodeWindowsLookup, resolveWindowsCommand, runProcess, stopProcessTree, } from "../system/process-runner.js";
 /** Output still in the pipes when a process exits arrives right after; a child holding them does not. */
 const DRAIN_AFTER_EXIT_MS = 500;
 /**
@@ -15,6 +15,16 @@ export function planTerminal(request, context) {
     const env = { ...request.env };
     if (context.platform === "win32") {
         env.FORCE_COLOR = "1";
+        if (request.command === null && context.windowsShell) {
+            // With pipes PowerShell shows no prompt, but reads and runs each line it is given.
+            return {
+                file: context.windowsShell,
+                args: ["-NoLogo", "-Command", "-"],
+                env,
+                detached: false,
+                windowsVerbatimArguments: false,
+            };
+        }
         const args = request.command === null ? ["/d"] : ["/d", "/s", "/c", `"${request.command}"`];
         return {
             file: context.comSpec,
@@ -27,11 +37,12 @@ export function planTerminal(request, context) {
     if (context.mode === "pipes") {
         env.FORCE_COLOR = "1";
         const args = request.command === null
-            ? ["-c", `exec ${quote(context.shell)} -i`]
+            ? ["-c", `exec ${quote(context.shell)} -l -i`]
             : ["-c", request.command];
         return { file: "/bin/sh", args, env, detached: true, windowsVerbatimArguments: false };
     }
-    const run = request.command ?? `exec ${quote(context.shell)}`;
+    // A login shell reads the profile the person's own terminal reads (PATH, nvm and the like).
+    const run = request.command ?? `exec ${quote(context.shell)} -l`;
     const inner = `stty cols ${request.cols} rows ${request.rows} 2>/dev/null; ${run}`;
     // util-linux script runs `$SHELL -c`; /bin/sh keeps the command's meaning the same everywhere.
     env.SHELL = "/bin/sh";
@@ -40,6 +51,15 @@ export function planTerminal(request, context) {
         : ["-q", "-f", "-e", "-c", inner, "/dev/null"];
     return { file: "script", args, env, detached: true, windowsVerbatimArguments: false };
 }
+/** The interactive shell's short name, e.g. `zsh` or `pwsh`: the default title of a shell terminal. */
+export function shellName(context) {
+    if (context.platform === "win32") {
+        if (!context.windowsShell)
+            return "cmd";
+        return path.win32.basename(context.windowsShell).replace(/\.exe$/i, "");
+    }
+    return path.posix.basename(context.shell) || "shell";
+}
 /**
  * Whether this machine can run pseudo-terminals through `script`: util-linux's on Linux (BusyBox
  * and others take different flags), the system one on macOS, never on Windows.
@@ -62,9 +82,15 @@ export function createTerminalSpawner(options) {
         mode,
         shell: baseEnv.SHELL || "/bin/sh",
         comSpec: baseEnv.ComSpec ?? "cmd.exe",
+        windowsShell: platform === "win32"
+            ? options.windowsShell === undefined
+                ? findWindowsShell()
+                : options.windowsShell
+            : null,
     };
     return {
         mode,
+        shellName: shellName(context),
         spawn: async (request) => {
             const plan = planTerminal(request, context);
             const child = spawn(plan.file, plan.args, {
@@ -171,6 +197,21 @@ export function nodeTerminalFolders(platform = process.platform) {
         },
     };
 }
+/** The short name of the shell a terminal with no command starts on this machine. */
+export function interactiveShellName(platform = process.platform, env = process.env) {
+    return shellName({
+        platform,
+        mode: "pipes",
+        shell: env.SHELL || "/bin/sh",
+        comSpec: env.ComSpec ?? "cmd.exe",
+        windowsShell: platform === "win32" ? findWindowsShell() : null,
+    });
+}
+/** `pwsh` when installed, else Windows PowerShell, else null for cmd.exe. */
+function findWindowsShell() {
+    const lookup = nodeWindowsLookup();
+    return resolveWindowsCommand("pwsh", lookup) ?? resolveWindowsCommand("powershell", lookup);
+}
 /** Single quotes for sh, with any single quote inside closed, escaped and reopened. */
 function quote(value) {
     return `'${value.replaceAll("'", `'\\''`)}'`;

package/dist/server/interface/http/http-server.js

@@ -1,5 +1,5 @@
 import { createServer } from "node:http";
-import { API_PATHS, STUDIO_HEADER, TOKEN_HEADER, TOKEN_PARAM, } from "../../../core/api/contract.js";
+import { API_PATHS, INCLUDE_STUDIO_PARAM, STUDIO_HEADER, TOKEN_HEADER, TOKEN_PARAM, } from "../../../core/api/contract.js";
 import { createAlias, installPortless, removeAlias, renameAlias, } from "../../application/route-use-cases.js";
 import { FocusBroker, focusQuery, resolveFocusTarget } from "./focus-broker.js";
 import { MAX_BODY_BYTES, readJsonBody, sendError, sendJson } from "./json-io.js";
@@ -13,6 +13,7 @@ const DOCTOR_FIX = /^\/api\/doctor\/fix\/([^/]+)$/;
 const PROXY_ACTION = /^\/api\/proxy\/(start|stop|restart)$/;
 const STUDIO_ACTION = /^\/api\/studio\/(restart|stop)$/;
 const STOP_PROCESS = /^\/api\/processes\/([^/]+)\/stop$/;
+const STOP_CONTAINER = /^\/api\/containers\/([^/]+)\/stop$/;
 const TERMINAL = /^\/api\/terminals\/([^/]+)(?:\/(output|stream|input|stop|restart))?$/;
 /** Lets the 202 reach the browser before Studio restarts or exits. */
 const STUDIO_ACTION_DELAY_MS = 200;
@@ -99,7 +100,8 @@ export function createHttpServer(options) {
             return;
         }
         if (pathname === API_PATHS.snapshot && method === "GET") {
-            sendJson(res, 200, await options.studio.readSnapshot());
+            const includeStudio = query.get(INCLUDE_STUDIO_PARAM) === "1";
+            sendJson(res, 200, await options.studio.readSnapshot({ includeStudio }));
             return;
         }
         if (pathname === API_PATHS.update && method === "GET") {
@@ -176,6 +178,16 @@ export function createHttpServer(options) {
             res.writeHead(204, { "Cache-Control": "no-store" }).end();
             return;
         }
+        const stopBox = STOP_CONTAINER.exec(pathname);
+        if (stopBox?.[1] && method === "POST") {
+            if (!options.stopContainer)
+                return sendAppError(res, unsupported);
+            const result = await options.stopContainer(decodeName(stopBox[1]) ?? "");
+            if (!result.ok)
+                return sendAppError(res, result.error);
+            res.writeHead(204, { "Cache-Control": "no-store" }).end();
+            return;
+        }
         if (pathname.startsWith(`${API_PATHS.openWith}/`) || pathname === API_PATHS.openWith) {
             return handleOpenWith(req, res, pathname, method);
         }
@@ -235,6 +247,18 @@ export function createHttpServer(options) {
             terminalStreams.list(res);
             return;
         }
+        if (pathname === API_PATHS.terminalsInFolder && method === "POST") {
+            const body = await readJsonBody(req);
+            if (!body.ok)
+                return sendBodyError(res, body.error);
+            const created = await terminals.create(toTerminalRequest(body.value), {
+                trusted: isLocalProgram(req),
+                picked: true,
+            });
+            if (!created.ok)
+                return sendAppError(res, created.error);
+            return sendJson(res, 201, created.value);
+        }
         const match = TERMINAL.exec(pathname);
         const id = match?.[1] ? decodeName(match[1]) : null;
         if (id === null)
@@ -246,6 +270,18 @@ export function createHttpServer(options) {
                 return sendError(res, "not_found", `No terminal has the id "${id}".`);
             return sendJson(res, 200, info);
         }
+        if (action === undefined && method === "PATCH") {
+            const body = await readJsonBody(req);
+            if (!body.ok)
+                return sendBodyError(res, body.error);
+            const title = asRecord(body.value).title;
+            if (typeof title !== "string")
+                return sendError(res, "invalid_request", "title must be text.");
+            const renamed = terminals.rename(id, title);
+            if (!renamed.ok)
+                return sendAppError(res, renamed.error);
+            return sendJson(res, 200, renamed.value);
+        }
         if (action === undefined && method === "DELETE") {
             return sendResult(res, terminals.remove(id), 204);
         }

package/dist/server/main.js

@@ -2,11 +2,13 @@ import { randomBytes } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { stopContainer } from "./application/container-source.js";
 import { createDoctorService } from "./application/doctor.js";
 import { OpenWith } from "./application/open-with.js";
 import { controlProxy } from "./application/proxy-control.js";
 import { confirmProxyStarts } from "./application/proxy-start-check.js";
 import { createAlias, renameAlias } from "./application/route-use-cases.js";
+import { publicUrls, SHORT_URL_PORT, ShortUrls } from "./application/short-urls.js";
 import { stopProcess } from "./application/stop-process.js";
 import { StudioRuntime } from "./application/studio-runtime.js";
 import { TerminalManager } from "./application/terminals.js";
@@ -20,19 +22,29 @@ import { JsonUpdateCache, updateCheckPathFor } from "./infrastructure/config/jso
 import { proxyStartRecordPathFor, readProxyStartRecord, recordProxyStarts, } from "./infrastructure/config/proxy-start-record.js";
 import { PortlessRegistry } from "./infrastructure/portless/portless-registry.js";
 import { inspectRoutesFile, resolveStateDir } from "./infrastructure/portless/state-files.js";
-import { collectDoctorFacts, proxyPidsAmong } from "./infrastructure/system/doctor-facts.js";
+import { DockerContainers } from "./infrastructure/system/docker-containers.js";
+import { collectDoctorFacts, proxyPidsAmong, reachesPortless, testBind, } from "./infrastructure/system/doctor-facts.js";
+import { ephemeralRangeReader } from "./infrastructure/system/ephemeral-ports.js";
 import { FaviconFetcher } from "./infrastructure/system/favicon-fetcher.js";
 import { fetchLatestVersion } from "./infrastructure/system/npm-registry.js";
 import { OsNotifier } from "./infrastructure/system/os-notifier.js";
+import { startForwarder } from "./infrastructure/system/port-forwarder.js";
 import { ProjectInfoReader } from "./infrastructure/system/project-info.js";
 import { nodeSystemIo } from "./infrastructure/system/system-io.js";
 import { createPortScanner, listPortsFor, probeHttpResponse, } from "./infrastructure/system/system-port-scanner.js";
 import { SystemProcessControl } from "./infrastructure/system/system-process-control.js";
-import { createTerminalSpawner, detectTerminalMode, nodeTerminalFolders, } from "./infrastructure/terminal/terminal-spawner.js";
+import { systemProcessTree } from "./infrastructure/terminal/process-tree.js";
+import { createTerminalSpawner, detectTerminalMode, interactiveShellName, nodeTerminalFolders, } from "./infrastructure/terminal/terminal-spawner.js";
 import { createHttpServer } from "./interface/http/http-server.js";
 export { defaultConfigPath } from "./infrastructure/config/json-config-store.js";
 /** Only this machine can connect; see docs/architecture.md, Security. */
 const LOOPBACK = "127.0.0.1";
+/** `PORTLESS_STUDIO_SHORT_URL_PORT`, when it is a valid port; port 80 otherwise. */
+export function shortUrlPortFrom(env) {
+    const raw = env.PORTLESS_STUDIO_SHORT_URL_PORT;
+    const port = raw === undefined ? Number.NaN : Number(raw);
+    return Number.isInteger(port) && port >= 1 && port <= 65535 ? port : SHORT_URL_PORT;
+}
 // Lets startServer reuse the runtime behind services built here, so both share one scan cache.
 const runtimes = new WeakMap();
 export function createStudioServices(options = {}) {
@@ -45,11 +57,18 @@ export function createStudioServices(options = {}) {
     });
     const scanner = createPortScanner();
     const proxyPids = (pids) => proxyPidsAmong(process.platform, nodeSystemIo, pids);
+    const shortUrls = new ShortUrls({
+        forwarding: { listen: (port, target) => startForwarder({ port, targetPort: target }) },
+        port: options.shortUrlPort ?? shortUrlPortFrom(process.env),
+        log: (line) => console.log(line),
+        reachesProxy: (port) => reachesPortless(port),
+    });
     // A start counts only once the proxy listens, and every proxy Studio starts is written down,
-    // so `uninstall` stops only Studio's own.
-    const registry = recordProxyStarts(confirmProxyStarts(portless, { scan: () => scanner.scan(), proxyPids }), proxyStartRecordPathFor(configPath));
+    // so `uninstall` stops only Studio's own. Route URLs drop the port while Studio forwards it.
+    const registry = publicUrls(recordProxyStarts(confirmProxyStarts(portless, { scan: () => scanner.scan(), proxyPids }), proxyStartRecordPathFor(configPath)), () => shortUrls.publicPort());
     const configStore = new JsonConfigStore(configPath);
     const notifier = new OsNotifier({ platform: process.platform });
+    const containers = new DockerContainers();
     const runtime = new StudioRuntime({
         registry,
         scanner,
@@ -62,6 +81,9 @@ export function createStudioServices(options = {}) {
         notifier,
         icons: new FaviconFetcher(),
         routeProjectStore: new JsonRouteProjectStore(routeProjectsPathFor(configPath)),
+        containers,
+        shortUrls,
+        ephemeralRange: ephemeralRangeReader(process.platform, nodeSystemIo),
     });
     const openWith = new OpenWith({
         catalog: systemAppCatalog(),
@@ -72,6 +94,8 @@ export function createStudioServices(options = {}) {
     const terminals = new TerminalManager({
         spawner: lazySpawner(),
         folders: nodeTerminalFolders(),
+        processTree: systemProcessTree(),
+        homeDir: os.homedir(),
         workspace: {
             openableFolders: () => runtime.openableFolders(),
             snapshot: () => runtime.readSnapshot(),
@@ -104,9 +128,13 @@ export function createStudioServices(options = {}) {
             ...(studioService ? { loginService: () => studioService.status() } : {}),
             systemNotifier: () => notifier.availability(),
             routesFile: () => inspectRoutesFile(stateDir),
+            docker: () => containers.read(),
+            lowPort: testBind,
+            shortUrls: (config) => shortUrls.inspect(config),
         }),
         controlProxy: proxy,
         updateConfig: (config) => runtime.updateConfig(config),
+        syncShortUrls: (config) => shortUrls.sync(config),
     });
     const version = options.version;
     const updates = version === undefined
@@ -129,11 +157,13 @@ export function createStudioServices(options = {}) {
             stoppablePids: () => runtime.stoppablePids(),
             selfPid: process.pid,
         }),
+        stopContainer: (name) => stopContainer(name, containers),
         studioService,
         openWith,
         terminals,
         openUrl: options.openUrl,
         updates,
+        shortUrls,
     };
     runtimes.set(services, runtime);
     return services;
@@ -178,6 +208,7 @@ export async function startServer(options) {
             scanner: services.scanner,
             configStore: services.configStore,
             projects: new ProjectInfoReader(),
+            ...(services.shortUrls ? { shortUrls: services.shortUrls } : {}),
         });
     const token = randomBytes(32).toString("base64url");
     const http = createHttpServer({
@@ -188,6 +219,7 @@ export async function startServer(options) {
         doctor: services.doctor,
         controlProxy: services.controlProxy,
         stopProcess: services.stopProcess,
+        stopContainer: services.stopContainer,
         ...(services.studioService ? { studioService: services.studioService } : {}),
         ...(services.openWith ? { openWith: services.openWith } : {}),
         ...(services.terminals ? { terminals: services.terminals } : {}),
@@ -204,6 +236,8 @@ export async function startServer(options) {
     const { port } = http.server.address();
     studio.setStudioPort(port);
     studio.start();
+    // The short-URL forwarder settles before anyone prints or registers a URL.
+    await studio.ready();
     return {
         url: `http://${LOOPBACK}:${port}`,
         port,
@@ -214,8 +248,10 @@ export async function startServer(options) {
             studio.stop();
             services.terminals?.closeAll();
             http.closeStreams();
-            http.server.close(() => resolve());
-            http.server.closeAllConnections();
+            void (services.shortUrls?.close() ?? Promise.resolve()).finally(() => {
+                http.server.close(() => resolve());
+                http.server.closeAllConnections();
+            });
         }),
     };
 }
@@ -230,6 +266,7 @@ function lazySpawner() {
         get mode() {
             return mode;
         },
+        shellName: interactiveShellName(),
         spawn: async (request) => {
             real ??= detectTerminalMode(process.platform).then((detected) => createTerminalSpawner({ mode: detected }));
             const spawner = await real;