portless-studio 0.1.3 → 0.1.5

package/README.md

@@ -16,7 +16,7 @@ portless replaces port numbers with names: `portless api pnpm dev` serves your a
 with ten dev servers across several projects you have to remember which names exist and which
 ports have none. Studio shows both, live, and names a port in one click.
 
-![Naming port 8000, searching routes with Ctrl+K, filtering with the Filter popover and running pnpm dev in a Studio terminal](docs/images/demo.gif)
+![Naming port 8000, searching routes with Ctrl+K, filtering with the Filter popover and opening a route's terminal in the right-hand pane](docs/images/demo.gif)
 
 The screenshots use the built-in sample data (`?demo`), not a real machine.
 

package/dist/cli/mcp/studio-tools.js

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

package/dist/cli/studio-items.js

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

package/dist/core/api/contract.js

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

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

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

package/dist/core/terminals/terminal-history.js

@@ -0,0 +1,53 @@
+/**
+ * What Studio keeps about terminals between runs, in `terminals.json` next to the config: the
+ * terminals that were running when it stopped, so they can run again, and the last commands run
+ * in each folder, offered when a new terminal opens there. See docs/terminals.md.
+ */
+export const EMPTY_TERMINAL_HISTORY = { running: [], recentCommands: {} };
+/** Commands remembered per folder. */
+export const MAX_RECENT_COMMANDS = 20;
+/** Reads `terminals.json`; anything it cannot read is left out rather than failing. */
+export function parseTerminalHistory(input) {
+    if (typeof input !== "object" || input === null)
+        return { running: [], recentCommands: {} };
+    const raw = input;
+    const running = Array.isArray(raw.running) ? raw.running.filter(isSavedTerminal) : [];
+    const recentCommands = {};
+    if (typeof raw.recentCommands === "object" && raw.recentCommands !== null) {
+        for (const [folder, list] of Object.entries(raw.recentCommands)) {
+            if (folder === "__proto__" || !Array.isArray(list))
+                continue;
+            const commands = list.filter((item) => typeof item === "string" && item.trim() !== "");
+            if (commands.length > 0)
+                recentCommands[folder] = commands.slice(0, MAX_RECENT_COMMANDS);
+        }
+    }
+    return { running, recentCommands };
+}
+/** Puts `command` first in the folder's list, once, and keeps the newest `MAX_RECENT_COMMANDS`. */
+export function rememberCommand(recent, cwd, command) {
+    const wanted = command.trim();
+    const copy = {};
+    for (const [folder, list] of Object.entries(recent))
+        copy[folder] = [...list];
+    if (wanted === "")
+        return copy;
+    const list = (copy[cwd] ?? []).filter((item) => item !== wanted);
+    copy[cwd] = [wanted, ...list].slice(0, MAX_RECENT_COMMANDS);
+    return copy;
+}
+function isSavedTerminal(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const item = value;
+    const optionalText = (field) => field === null || typeof field === "string";
+    return (typeof item.command === "string" &&
+        typeof item.cwd === "string" &&
+        item.cwd !== "" &&
+        typeof item.title === "string" &&
+        typeof item.startedAt === "number" &&
+        (item.startedBy === "program" || item.startedBy === "person") &&
+        optionalText(item.project) &&
+        optionalText(item.worktree) &&
+        optionalText(item.branch));
+}

package/dist/core/terminals/terminal.js

@@ -1,7 +1,3 @@
-/**
- * A terminal Studio runs: one command in one project folder, with its output kept so the page,
- * the CLI and agents can read it. See docs/terminals.md.
- */
 // Control sequences: CSI (colors, cursor), OSC (window title) and two-character escapes.
 const ESCAPES = new RegExp([
     String.raw `\u001b\[[0-?]*[ -/]*[@-~]`,

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

@@ -143,5 +143,6 @@ function toDetected(port, projects, nameTemplate) {
         cwd: port.cwd,
         suggestedName: info === null ? null : suggestName(info, nameTemplate, port.port),
         ...(project === null ? {} : { project }),
+        ...(port.startedAt === undefined ? {} : { startedAt: port.startedAt }),
     };
 }

package/dist/server/application/stop-process.js

@@ -5,7 +5,7 @@ import { appError } from "./app-error.js";
  * Stops a dev server from its row. Only a process of the current user that listens on a port the
  * UI shows can be stopped, so the endpoint cannot be used to kill anything else on the machine.
  */
-export async function stopProcess(input, deps) {
+export async function stopProcess(input, deps, all = false) {
     if (!/^\d+$/.test(input) || Number(input) < 1) {
         return err(appError("invalid_request", "The pid must be a whole number above 0."));
     }
@@ -19,6 +19,47 @@ export async function stopProcess(input, deps) {
         const who = owner === "root" ? "root" : owner === "other" ? "another user" : "an unknown user";
         return err(appError("process_not_allowed", `Process ${pid} on port ${port} belongs to ${who}; stop it from a terminal.`, killCommand(deps.platform ?? process.platform, [pid], true)));
     }
-    const stopped = await deps.processes.terminate(pid);
-    return stopped.ok ? ok({ pid, port }) : stopped;
+    const targets = all ? await deps.processes.devTree?.(pid) : [pid];
+    if (!targets?.length) {
+        return err(appError("unsupported", "Could not identify the development command tree. Stop it from its terminal."));
+    }
+    // Check the entire plan before sending any signal. A tree must never include Studio.
+    for (const target of targets) {
+        if (target === deps.selfPid || (await deps.processes.ownerOf(target)) !== "you") {
+            return err(appError("process_not_allowed", "The development command tree includes a protected process. Stop it from its terminal."));
+        }
+    }
+    const watchedPorts = new Set([port]);
+    for (const listener of (await deps.listeners?.()) ?? []) {
+        if (listener.pid !== null && targets.includes(listener.pid))
+            watchedPorts.add(listener.port);
+    }
+    try {
+        for (const target of targets) {
+            const stopped = await deps.processes.terminate(target);
+            if (!stopped.ok)
+                return stopped;
+        }
+        if (deps.listeners || deps.portClosed) {
+            // Observe a settling window too: a supervisor may immediately restart the listener.
+            await new Promise((resolve) => setTimeout(resolve, deps.settleMs ?? 750));
+            const listeners = (await deps.listeners?.()) ?? [];
+            for (const watchedPort of watchedPorts) {
+                const survivor = listeners.find((item) => item.port === watchedPort);
+                const closed = deps.portClosed ? await deps.portClosed(watchedPort) : !survivor;
+                if (!closed) {
+                    const reason = !survivor
+                        ? "The port could not be confirmed closed"
+                        : targets.includes(survivor.pid ?? -1)
+                            ? `Process ${survivor.pid} is still listening`
+                            : `Process ${survivor.pid ?? "unknown"} is now listening; a parent or another program may have restarted the server`;
+                    return err(appError("port_in_use", `Port ${watchedPort} did not stay closed. ${reason}. Try Stop all to stop the development command, or stop it from its terminal.`));
+                }
+            }
+        }
+        return ok({ pid, port });
+    }
+    finally {
+        await deps.refresh?.();
+    }
 }

package/dist/server/application/studio-runtime.js

@@ -196,6 +196,15 @@ export class StudioRuntime {
      * pid -> port for every process listening on a detected or routed port, from a fresh scan.
      * These are the only processes the UI may stop.
      */
+    /** Refresh listeners and health immediately after a process action and broadcast the snapshot. */
+    async refreshProcesses() {
+        // A scan started before the stop may still contain the listener that just exited.
+        await this.#scanning;
+        const state = await this.#registry.readSnapshot();
+        await this.#detect(state, await this.#currentConfig(), true);
+        await this.#probeRoutes(state.routes);
+        this.#notify();
+    }
     async stoppablePids() {
         const state = await this.#registry.readSnapshot();
         const found = await this.#detect(state, await this.#currentConfig(), true);
@@ -403,6 +412,7 @@ export class StudioRuntime {
             return {
                 ...route,
                 ...(listener?.pid == null ? {} : { listenerPid: listener.pid }),
+                ...(listener?.startedAt === undefined ? {} : { startedAt: listener.startedAt }),
                 ...(project === null ? {} : { project }),
                 ...(health === undefined ? {} : { health }),
             };