portless-studio 0.1.1 → 0.1.2

package/README.md

@@ -22,7 +22,8 @@ The screenshots use the built-in sample data (`?demo`), not a real machine.
 
 ## Install
 
-Requires Node 22 or later.
+Requirements: Node 22 or later on Linux, macOS or Windows. portless is installed for you if it is
+missing.
 
 To try it, run it straight from npm:
 
@@ -40,18 +41,8 @@ portless-studio init
 The login service starts Studio from the files npm installed. Run through `npx`, those files sit in
 npm's cache, which npm can clear at any time, and then Studio stops starting at login.
 
-To update, install the latest version and restart Studio:
-
-```bash
-npm i -g portless-studio@latest
-```
-
-To remove it, undo the setup first, then remove the package:
-
-```bash
-portless-studio uninstall
-npm rm -g portless-studio
-```
+To update, install the latest version and restart Studio with `npm i -g portless-studio@latest`.
+To remove it, run `portless-studio uninstall`, then `npm rm -g portless-studio`.
 
 ## Quick start
 
@@ -63,61 +54,52 @@ npm rm -g portless-studio
 - Starts the portless proxy on port 1355 over HTTP, which needs no password, certificate or extra
   tool on macOS, Windows or Linux, and can set Studio to start when you log in.
 
-`init --yes` accepts every default without asking. After that, `portless-studio` starts
-Studio at `http://127.0.0.1:4949`, registers it in portless as `studio` and opens your browser.
-Your apps open at names like `http://web.myapp.localhost:1355`: Chrome, Edge and Firefox send
-every `*.localhost` name to your own machine, with no hosts file and no DNS setup.
+Then `portless-studio` starts Studio at `http://127.0.0.1:4949`, registers it in portless as
+`studio` and opens your browser. Your apps open at names like `http://web.myapp.localhost:1355`:
+Chrome, Edge and Firefox send every `*.localhost` name to your own machine, with no hosts file and
+no DNS setup. Turn on Short URLs in Settings to drop the `:1355` (`http://web.myapp.localhost`)
+where your system lets you listen on port 80; see
+[troubleshooting](docs/troubleshooting.md#names-have-1355-and-i-want-port-80).
 
-To try the page without portless, start Studio and open `http://127.0.0.1:4949/?demo` for sample
-data, or `?demo&noportless` to walk through the install flow with a fake install.
+[Getting started](docs/getting-started.md) walks through the first five minutes: naming a dev
+server, naming a port by hand, running a command in a Studio terminal and turning on auto mode.
+To try the page without portless, open `http://127.0.0.1:4949/?demo` for sample data.
 
 ## What it does
 
 - **Live list** of portless routes: name, URL, port, app or alias, uptime and any Tailscale, ngrok
   or Cloudflare tunnel. It updates as soon as a route appears or goes away.
 - **Detected ports:** listening ports that answer HTTP but have no name yet, with the process, the
-  project folder and a suggested name. Name one, name them all, or ignore one.
-- **Auto mode** (off by default): every new dev server gets its suggested name by itself, once
-  it has shown up unnamed in two scans in a row, so a server started with `portless <name>` keeps
-  the name portless gives it. Names auto mode gave are removed 10 minutes after their port closes.
+  project folder and a suggested name. Name one, name them all, or ignore one. Ports a running
+  Docker container publishes show here too.
+- **Auto mode** (off by default): every new dev server gets its suggested name by itself. Names
+  auto mode gave are removed 10 minutes after their port closes.
 - **Name a port** that portless did not start, such as a database in Docker (`db` gives
   `db.localhost`). Rename or remove those names later.
 - **Where each server runs:** every row shows the git branch, the linked worktree and the project
-  folder. A route whose server is down keeps the last place it ran.
-- **Views:** group by project, worktree, kind or status, or into your own groups; sort, and
-  filter by kind, status or project from the Filter button; save the combination as a named view
-  and pick the one that opens by default.
+  folder.
+- **Views:** group by project, worktree, kind or status, or into your own groups; filter, sort and
+  save the combination as a named view.
 - **Terminals:** run a command per project inside Studio and watch its output in a panel. You, the
-  CLI and your AI agents drive the same terminals. See [docs/terminals.md](docs/terminals.md).
+  CLI and your AI agents drive the same terminals.
 - **Agents:** an MCP server lets Claude Code, Cursor and other agents list, name and stop dev
-  servers and run commands in Studio terminals. See [docs/mcp.md](docs/mcp.md).
-- **Open with:** right-click a row to open its folder in an editor found on your machine (VS Code,
-  Cursor, Zed, WebStorm, IntelliJ IDEA, Sublime Text), reveal it in the file manager or copy its
-  path. Add your own apps in Settings.
-- **Health:** each route's dot says whether its port answers. The Health panel and
-  `portless-studio doctor` find a proxy left running as root, two proxies at once, an untrusted
-  certificate or a taken port, and give the fix.
-- **Proxy and Studio control:** start, stop or restart the portless proxy, and stop or restart
-  Studio, from the page.
-- **Stop a dev server** from its row, after a confirmation. Only your own processes on a port
-  Studio shows.
-- **Project icons:** the favicon the server serves, else one in the project folder, else the
-  project's initials. Set an emoji or an image per project in Settings.
-- **Notifications** in the page when a server is detected or named, and optionally from the
-  operating system.
-- **Install portless** from the page when the `portless` command is missing.
+  servers and run commands in Studio terminals.
+- **Health:** each route's dot says whether its port answers, and `portless-studio doctor` finds a
+  proxy left running as root, two proxies at once, an untrusted certificate or a taken port, and
+  gives the fix.
 - **Keyboard first:** every action has a key, `?` lists them and `Ctrl+K` (`Cmd+K`) runs any of
   them by name.
 
-## How naming works
+Also: start, stop or restart the proxy and Studio from the page, stop a dev server from its row,
+open a project in your editor, project icons, and notifications in the page or from the operating
+system.
+
+## Naming
 
 A suggested name says what the work is, then the app, then the repository. The package
 `@acme/web` in the `acme-monorepo` folder on the branch `feat/ED-1234-add-x` gets
-`ed-1234.web.acme`, so two worktrees of one repository get different names. That is the order
-portless uses for worktrees, `<branch>.<name>.localhost`.
-
-Change it with `nameTemplate`, for example `{ticket}.{repo}` or `{package}-{port}`.
-[docs/naming.md](docs/naming.md) lists every token and how empty or repeated parts are dropped.
+`ed-1234.web.acme`, so two worktrees of one repository get different names. Change the pattern
+with `nameTemplate`; [docs/naming.md](docs/naming.md) lists every token.
 
 Anything that names a route through the portless CLI also shows up in Studio:
 
@@ -126,177 +108,42 @@ portless web.myapp pnpm dev       # a dev server, at web.myapp.localhost
 portless alias db.myapp 5432      # a port something else opened, at db.myapp.localhost
 ```
 
-## Agents and MCP
-
-`portless-studio mcp` is an [MCP](https://modelcontextprotocol.io) server on stdio. It talks to the
-Studio already running, so whatever an agent changes shows up in the page at once. For Claude Code:
+## Agents and terminals
 
 ```bash
 claude mcp add --scope user portless-studio -- npx -y portless-studio mcp
+portless-studio run -- pnpm dev
 ```
 
-[docs/mcp.md](docs/mcp.md) has the setup for Cursor and other clients, the list of tools, and
-instructions to paste into your agent so it names dev servers after the ticket or pull request.
-`portless-studio list --json` and `doctor --json` give the same data to scripts.
+The first line connects Claude Code to Studio's MCP server. The second runs a dev server in a
+Studio terminal, prints its output in your shell and names the port it opens.
+[docs/agents.md](docs/agents.md) shows how to keep agents in sync with Studio, including
+instructions to paste and Claude Code hooks; [docs/mcp.md](docs/mcp.md) has the setup for other
+clients and [docs/terminals.md](docs/terminals.md) covers the terminal panel.
 
-## Terminals
+## Documentation
 
-```bash
-portless-studio run -- pnpm dev
-```
+- [Getting started](docs/getting-started.md) and [Troubleshooting](docs/troubleshooting.md)
+- [Command line](docs/cli.md), [Configuration](docs/configuration.md) and
+  [Keyboard shortcuts](docs/keyboard-shortcuts.md)
+- [Naming](docs/naming.md), [Terminals](docs/terminals.md) and
+  [Linux, macOS and Windows](docs/platforms.md)
+- [Agents](docs/agents.md) and [MCP server](docs/mcp.md)
+- [Every page, with one line each](docs/README.md)
+
+## How it relates to portless
 
-`run` starts the command in a Studio terminal in the current folder, prints its output here,
-names the first port it opens and stops it on Ctrl+C. The terminal stays visible in the page.
-[docs/terminals.md](docs/terminals.md) covers the panel, the CLI and the security rules.
-
-## Platforms
-
-Studio runs on Linux, macOS and Windows with Node 22 or later and installs nothing beyond portless. Each
-feature uses tools the system already has (`/proc` on Linux, `lsof` on macOS, `netstat` and
-PowerShell on Windows). [docs/platforms.md](docs/platforms.md) says what each system uses and what
-does not work the same everywhere.
-
-## Commands
-
-| Command | What it does |
-| --- | --- |
-| `portless-studio` | Starts Studio with the settings from the config file. |
-| `portless-studio init [--yes]` | The setup above. Safe to run again. |
-| `portless-studio uninstall [--yes]` | Undoes the setup: removes the login service, the names auto mode gave and the `studio` name, and stops the proxy if Studio started it. Names you or an agent gave stay. Asks before deleting the settings folder. |
-| `portless-studio service install` | Starts Studio when you log in: a systemd user unit on Linux, a LaunchAgent on macOS, a script in the Startup folder on Windows. |
-| `portless-studio service uninstall` | Undoes `service install`. |
-| `portless-studio service status` | Says whether the login service is installed and running. |
-| `portless-studio config [--edit] [--json]` | Prints the config file path and contents, or opens it in `$EDITOR`. |
-| `portless-studio doctor [--json]` | Checks portless, the proxy, the certificate, Studio's port and the login service, and prints the fix for each problem. Exits with 1 when something fails. |
-| `portless-studio list [--json]` | Lists named routes and ports without a name. |
-| `portless-studio mcp` | Runs the MCP server on stdio for AI agents. |
-| `portless-studio run [--name <name>] [--cwd <dir>] -- <command...>` | Runs a command in a Studio terminal and names the port it opens. |
-| `portless-studio open [target]` | Brings Studio to the front showing a route, project, terminal id or `port:<n>`. |
-
-| Flag | Effect |
-| --- | --- |
-| `--port <n>` | Port for the dashboard on 127.0.0.1. Default: `port` in the config, 4949. `0` picks a free one. |
-| `--no-open` | Do not open the browser. |
-| `--no-register` | Do not register the `studio` name in portless. |
-| `-y`, `--yes` | With `init` and `uninstall`: accept every default. |
-| `-h`, `--help` | Show the help. |
-| `-v`, `--version` | Show the version. |
-
-| Environment variable | What it does |
-| --- | --- |
-| `PORTLESS_STUDIO_CONFIG` | Path of the config file. |
-| `PORTLESS_STATE_DIR` | portless state folder. Default `~/.portless`. |
-| `PORTLESS_BIN` | portless binary used to create and remove names. Default `portless`. |
-| `PORTLESS_STUDIO_URL` | Studio that `mcp`, `list`, `run` and `open` talk to. Default `http://127.0.0.1:<port>`. |
-| `PORTLESS_STUDIO_NO_UPDATE_CHECK` | `1` turns the daily update check off, whatever the config says. |
-| `EDITOR` | Editor that `config --edit` opens. |
-
-## Config file
-
-Settings live in one JSON file: `~/.config/portless-studio/config.json` on Linux and macOS (or
-under `$XDG_CONFIG_HOME`), `%APPDATA%\portless-studio\config.json` on Windows. `portless-studio
-config` prints the path. Edit it by hand or from the Settings panel; a running Studio picks up the
-changes without a restart. Missing fields take their default.
-
-| Field | Default | What it does |
-| --- | --- | --- |
-| `port` | `4949` | Port Studio listens on, on 127.0.0.1. |
-| `autoName` | `false` | Gives every new dev server a portless name automatically. |
-| `autoRemoveAfterMinutes` | `10` | Minutes a name auto mode gave survives after its port closes. `0` keeps them. |
-| `openBrowser` | `true` | Opens the browser when Studio starts. |
-| `registerStudioAlias` | `true` | Registers Studio itself in portless as `studio`. |
-| `startProxy` | `true` | Starts the portless proxy when Studio starts and it is not running. |
-| `proxyPort` | `1355` | Port of that proxy. 1355 needs no administrator rights; 443 removes the port from URLs. |
-| `proxyHttps` | `false` | Serves the names over HTTPS. See the FAQ. |
-| `scanIntervalMs` | `3000` | How often Studio looks for new listening ports, in milliseconds (at least 1000). |
-| `ignoredPorts` | `[]` | Ports never shown as detected and never named automatically. |
-| `ignoredProcesses` | editors, chat apps, browsers | Process names whose ports are never shown. |
-| `views` | one view, `All`, grouped by project | Saved views: grouping, sort, filters and custom groups. |
-| `defaultViewId` | `"all"` | The view the page opens with. |
-| `favorites` | `[]` | Routes pinned above every group, by name or as `"port:3000"`. |
-| `desktopNotifications` | `false` | Notifies from an open Studio tab while it is in the background. |
-| `systemNotifications` | `false` | Asks the operating system to notify when no Studio tab is open. |
-| `nameTemplate` | `"{work}.{package}.{repo}"` | How suggested names are built. See [docs/naming.md](docs/naming.md). |
-| `projectIcons` | `{}` | Icon per project: an emoji, an http(s) image URL or a `data:image` URL. |
-| `checkForUpdates` | `true` | Once a day, asks npm whether a newer portless-studio exists. See "Update notice" below. |
-
-The `--port`, `--no-open` and `--no-register` flags win over the file for one run. Apps you add to
-the Open with menu live in `open-with.json` next to the config file.
-
-### Update notice
-
-Once a day Studio asks the npm registry for the latest version of portless-studio. When a newer
-one exists, it prints one line on start and shows a banner in the page with the command to update;
-dismissing the banner hides it until the next version. The request is a plain
-`GET https://registry.npmjs.org/portless-studio/latest`: Studio sends nothing about your machine,
-your projects or your routes. It gives up after 3 seconds and stays quiet when you are offline,
-and it keeps the time of the last check in `update-check.json` next to the config file. It never
-runs when the `CI` variable is set. Turn it off with `checkForUpdates: false`, the Settings
-switch, or `PORTLESS_STUDIO_NO_UPDATE_CHECK=1`.
-
-## Keyboard shortcuts
-
-| Keys | Action |
-| --- | --- |
-| `j` / `↓`, `k` / `↑` | Next and previous row |
-| `Home`, `End` | First and last row |
-| `/` | Search routes |
-| `Enter` or `o` | Open the selected route |
-| `c` | Copy its URL |
-| `r` | Rename an alias |
-| `Delete` or `Backspace` | Remove an alias |
-| `f` | Pin or unpin as favorite |
-| `.` or `Shift+F10` | Open with, copy path and more |
-| `t` | Open a terminal in its folder |
-| `n` | Name a port |
-| `v` / `Shift+V` | Next view / open the view menu |
-| `Shift+F` | Open the filters |
-| `[`, `]` | Collapse or expand all groups |
-| `Ctrl+K` / `Cmd+K` | Command menu |
-| `,` | Settings |
-| `?` | All keyboard shortcuts |
-| `Esc` | Close a dialog or cancel |
+Studio is an independent project, not part of portless and not made by its authors. It reads the
+state portless keeps in `~/.portless` and names routes through the `portless` command, so anything
+you or an agent do with portless shows up in Studio, and Studio never changes how portless works.
 
 ## Security
 
-Studio is a local tool and only listens on `127.0.0.1`. It rejects requests whose `Host` or
-`Origin` is not local, so other websites open in your browser cannot read your routes or call the
-API. Every change (naming, removing, installing portless, controlling the proxy or Studio, stopping
-a dev server, running terminals) also needs a token that changes on every run. The page reads it from
-Studio, and browsers only let pages served by Studio itself read it. The portless install always runs the same fixed command.
-A dev server can be stopped only when it belongs to your user and listens on a port Studio shows,
-and Studio never runs a command that needs sudo. See [SECURITY.md](SECURITY.md) to report a
-problem.
-
-## FAQ
-
-**Safari does not open `*.localhost` names.** Safari does not always send `.localhost` names to
-your machine. Open Studio at `http://127.0.0.1:4949` and each app at `http://127.0.0.1:<its port>`,
-or use Chrome, Edge or Firefox.
-
-**Why HTTP on port 1355, and how do I get HTTPS or port 443?** Port 1355 needs no administrator
-rights on any system, and browsers treat plain HTTP on a `.localhost` name as a secure context, so
-most apps work as they would on HTTPS. For URLs without a port, set `proxyPort` to `443`; on Linux
-that needs sudo once to start the proxy. For HTTPS, set `proxyHttps` to `true` and trust the
-portless certificate: `portless-studio doctor` prints the exact command for your system, and the
-Health panel shows it too.
-
-**Does it work on Windows?** Yes, with Node 22 or later and PowerShell 5 (included in Windows 10 and 11).
-Ports come from `netstat`, process details from PowerShell, and start at login uses a hidden
-script in the Startup folder. Windows has no service manager Studio can ask, so the page can stop
-Studio but not restart it, and the doctor only sees the proxy portless records.
-[docs/platforms.md](docs/platforms.md) lists every difference.
-
-**How does it relate to portless?** Studio is an independent project, not part of portless and not
-made by its authors. It reads the state portless keeps in `~/.portless` and names routes through
-the `portless` command, so anything you or an agent do with portless shows up in Studio, and
-Studio never changes how portless works.
-
-**How do I remove it?** Run `portless-studio uninstall` (or `npx portless-studio uninstall` if you
-never installed it globally). It removes the login service, the names auto mode gave and the
-`studio` name, stops the proxy if Studio started it, and asks before deleting the settings folder.
-Then remove the package with `npm rm -g portless-studio`. portless itself stays installed; remove it with
-`npm uninstall -g portless`.
+Studio only listens on `127.0.0.1` and rejects requests whose `Host` or `Origin` is not local, so
+other websites open in your browser cannot read your routes or call the API. Every change also
+needs a token that changes on every run and that only Studio's own page can read. A dev server can
+be stopped only when it belongs to your user, and Studio never runs a command that needs sudo.
+See [SECURITY.md](SECURITY.md) to report a problem.
 
 ## Development
 
@@ -306,16 +153,11 @@ cd portless-studio
 pnpm install
 pnpm dev          # API on :4949 and the web app with hot reload on :5173
 pnpm test         # unit and component tests
-pnpm typecheck
-pnpm check        # lint and format check
-pnpm build        # builds dist/, then `pnpm start` runs it
-pnpm smoke        # starts the built CLI on a free port and checks the API answers
 ```
 
-The code is split so the web app can talk to another backend later: see
-[docs/architecture.md](docs/architecture.md). Conventions are in
-[docs/conventions.md](docs/conventions.md), and [CONTRIBUTING.md](CONTRIBUTING.md) covers pull
-requests.
+[CONTRIBUTING.md](CONTRIBUTING.md) covers the checks to run and pull requests,
+[docs/architecture.md](docs/architecture.md) the layers and
+[docs/conventions.md](docs/conventions.md) the code conventions.
 
 ## License
 

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

@@ -1,4 +1,4 @@
-import { API_PATHS, } from "../../core/api/contract.js";
+import { API_PATHS, INCLUDE_STUDIO_PARAM, } from "../../core/api/contract.js";
 import { err, ok } from "../../core/result.js";
 import { plainText } from "../../core/terminals/terminal.js";
 import { describeProxy, detectedItem, proxyItem, routeItem } from "../studio-items.js";
@@ -37,10 +37,20 @@ export function createStudioTools(client) {
             title: "List named routes",
             description: "Lists every portless route Studio knows: name, browser URL, local port, kind (app or alias), " +
                 "health (up, error, down), project and git worktree it runs from, and pid. Use it to find the " +
-                "URL of a running app or which ports a worktree uses.",
-            inputSchema: NO_INPUT,
-            call: async () => {
-                const snapshot = await readSnapshot(client);
+                "URL of a running app or which ports a worktree uses. Studio's own route is left out unless " +
+                "include_studio is true.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    include_studio: {
+                        type: "boolean",
+                        description: "Also list Studio's own route (studio), hidden by default.",
+                    },
+                },
+                additionalProperties: false,
+            },
+            call: async (args) => {
+                const snapshot = await readSnapshot(client, args.include_studio === true);
                 if (!snapshot.ok)
                     return snapshot.error;
                 const { routes, proxy } = snapshot.value;
@@ -553,8 +563,11 @@ function terminalItem(terminal) {
         port: terminal.naming?.port ?? null,
     };
 }
-async function readSnapshot(client) {
-    const result = await client.read(API_PATHS.snapshot);
+async function readSnapshot(client, includeStudio = false) {
+    const path = includeStudio
+        ? `${API_PATHS.snapshot}?${INCLUDE_STUDIO_PARAM}=1`
+        : API_PATHS.snapshot;
+    const result = await client.read(path);
     if (!result.ok)
         return err(failure(result.error));
     return ok(result.value);

package/dist/cli/studio-items.js

@@ -22,10 +22,13 @@ export function detectedItem(port) {
     };
 }
 export function proxyItem(proxy) {
-    return { running: proxy.running, port: proxy.port };
+    const item = { running: proxy.running, port: proxy.port };
+    return proxy.publicPort == null ? item : { ...item, publicPort: proxy.publicPort };
 }
+/** `publicPort` is set while Studio forwards it to the proxy, for URLs without a port. */
 export function describeProxy(proxy) {
     if (!proxy.running)
         return "proxy stopped";
-    return proxy.port === null ? "proxy running" : `proxy running on port ${proxy.port}`;
+    const running = proxy.port === null ? "proxy running" : `proxy running on port ${proxy.port}`;
+    return proxy.publicPort == null ? running : `${running}, names open on port ${proxy.publicPort}`;
 }

package/dist/core/api/contract.js

@@ -29,6 +29,8 @@ export const API_PATHS = {
     studio: (action) => `/api/studio/${action}`,
     /** POST: stops a dev server listening on a detected or routed port. */
     stopProcess: (pid) => `/api/processes/${pid}/stop`,
+    /** POST: runs `docker stop` for a container the last `docker ps` listed. */
+    stopContainer: (name) => `/api/containers/${encodeURIComponent(name)}/stop`,
     /** GET: the editors found on this machine, the file manager and the custom apps. */
     openWithApps: "/api/open-with/apps",
     /** POST `OpenWithRequest`: opens a folder Studio knows with one of those apps. */
@@ -43,7 +45,16 @@ export const API_PATHS = {
     terminals: "/api/terminals",
     /** Server-sent events: `terminals` with the whole list on connect and after every change. */
     terminalsEvents: "/api/terminals/events",
-    /** GET returns `TerminalInfo`; DELETE stops the command if it runs and closes the terminal. */
+    /**
+     * POST `CreateTerminalRequest` from the page's folder picker: `cwd` may be any existing folder,
+     * typed by the person (`~` is the home folder). Every other page request runs only in folders
+     * Studio shows.
+     */
+    terminalsInFolder: "/api/terminals/in-folder",
+    /**
+     * GET returns `TerminalInfo`; PATCH `RenameTerminalRequest` renames it; DELETE stops the command
+     * if it runs and closes the terminal.
+     */
     terminal: (id) => `/api/terminals/${encodeURIComponent(id)}`,
     /** GET `?from=<seq>&max=<chars>` returns `TerminalOutputResponse`. */
     terminalOutput: (id) => `/api/terminals/${encodeURIComponent(id)}/output`,
@@ -70,6 +81,11 @@ export const API_PATHS = {
  * no custom headers.
  */
 export const TOKEN_PARAM = "token";
+/**
+ * `GET /api/snapshot?includeStudio=1` keeps Studio's own route in `routes`, which the snapshot
+ * leaves out unless `showStudioRoute` is on.
+ */
+export const INCLUDE_STUDIO_PARAM = "includeStudio";
 export const SNAPSHOT_EVENT = "snapshot";
 /** Server-sent event type that carries one `StudioEvent`. */
 export const STUDIO_EVENT = "event";

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

@@ -36,6 +36,8 @@ export const DEFAULT_CONFIG = {
     projectIcons: {},
     nameTemplate: DEFAULT_NAME_TEMPLATE,
     checkForUpdates: true,
+    shortUrls: false,
+    showStudioRoute: false,
 };
 const MIN_SCAN_INTERVAL_MS = 1000;
 /**
@@ -57,6 +59,8 @@ export function parseConfig(input) {
         "desktopNotifications",
         "systemNotifications",
         "checkForUpdates",
+        "shortUrls",
+        "showStudioRoute",
     ]) {
         const value = raw[key];
         if (value === undefined)

package/dist/core/doctor/platform-commands.js

@@ -27,9 +27,12 @@ export function killCommand(platform, pids, admin) {
 export function adminWords(platform) {
     return platform === "win32" ? "from a terminal opened with Run as Administrator" : "with sudo";
 }
-/** Whether binding this port needs root. Windows and macOS (10.14 and later) let anyone bind it. */
+/**
+ * Whether portless asks for sudo to start its proxy on this port. It does on Linux and macOS for
+ * every port below 1024, even where the system would let this user bind it; Windows never asks.
+ */
 export function portNeedsRoot(platform, port) {
-    return port < 1024 && platform !== "win32" && platform !== "darwin";
+    return port < 1024 && platform !== "win32";
 }
 /** Trusts the portless certificate authority in the store this system's browsers read. */
 export function trustCertificateCommand(platform, caFile) {

package/dist/core/ports/direct-url.js

@@ -0,0 +1,7 @@
+/**
+ * The address a dev server answers on without the portless proxy, e.g. `http://localhost:3000`.
+ * For a Docker container it is the host port the container publishes.
+ */
+export function directUrl(port) {
+    return `http://localhost:${port}`;
+}

package/dist/core/ports/docker-container.js

@@ -0,0 +1,85 @@
+// Docker's own rule for container names; it also keeps names from reading as flags.
+const CONTAINER_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
+// A host binding such as `0.0.0.0:8000-8002->8000-8002/tcp` or `[::]:8080->80/tcp`.
+const BINDING = /:(\d+)(?:-(\d+))?->\d+(?:-\d+)?\/(tcp|udp|sctp)$/;
+// A range wider than this is a mistake in the compose file, not something to probe port by port.
+const MAX_RANGE = 1000;
+export function isContainerName(value) {
+    return CONTAINER_NAME.test(value);
+}
+/** Host TCP ports from the `Ports` column; unpublished ports (`80/tcp`) and UDP are skipped. */
+export function parsePublishedPorts(text) {
+    const ports = new Set();
+    for (const part of text.split(",")) {
+        const match = BINDING.exec(part.trim());
+        if (match?.[3] !== "tcp")
+            continue;
+        const first = Number(match[1]);
+        const last = match[2] === undefined ? first : Number(match[2]);
+        if (last < first || last - first >= MAX_RANGE)
+            continue;
+        for (let port = first; port <= last; port += 1) {
+            if (port >= 1 && port <= 65535)
+                ports.add(port);
+        }
+    }
+    return [...ports].sort((a, b) => a - b);
+}
+/** Reads `docker ps --format '{{json .}}'`: one JSON object per line. Bad lines are skipped. */
+export function parseDockerPs(text) {
+    const containers = [];
+    for (const raw of text.split("\n")) {
+        const row = parseLine(raw.trim());
+        if (row === null)
+            continue;
+        const name = (stringField(row, "Names") ?? "").split(",")[0]?.trim() ?? "";
+        if (!isContainerName(name))
+            continue;
+        const labels = parseLabels(stringField(row, "Labels") ?? "");
+        containers.push({
+            name,
+            image: stringField(row, "Image") ?? "",
+            composeProject: labels.get("com.docker.compose.project") || null,
+            composeService: labels.get("com.docker.compose.service") || null,
+            ports: parsePublishedPorts(stringField(row, "Ports") ?? ""),
+        });
+    }
+    return containers;
+}
+/**
+ * What the name template reads for a container: the compose service as the package and the
+ * compose project as the repository (`api.acme`), else the container name as the folder.
+ */
+export function containerProjectInfo(container) {
+    return {
+        packageName: container.composeService,
+        repoName: container.composeProject,
+        folderName: container.name,
+        worktreeName: null,
+    };
+}
+function parseLine(line) {
+    if (!line.startsWith("{"))
+        return null;
+    try {
+        const value = JSON.parse(line);
+        return typeof value === "object" && value !== null ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function stringField(row, key) {
+    const value = row[key];
+    return typeof value === "string" ? value : null;
+}
+/** `a=1,b=2`; label values with commas are rare and only the compose labels matter here. */
+function parseLabels(text) {
+    const labels = new Map();
+    for (const pair of text.split(",")) {
+        const index = pair.indexOf("=");
+        if (index > 0)
+            labels.set(pair.slice(0, index).trim(), pair.slice(index + 1).trim());
+    }
+    return labels;
+}

package/dist/core/routes/route.js

@@ -19,10 +19,22 @@ export function nameFromHostname(hostname, tlds) {
     }
     return hostname;
 }
-/** Builds the browser URL; omits the port when it is the protocol default. */
+/**
+ * Builds the browser URL on the port names open on: the public port when there is one, else the
+ * proxy's. Omits the port when it is the protocol default.
+ */
 export function routeUrl(hostname, proxy) {
     const scheme = proxy.https ? "https" : "http";
     const defaultPort = proxy.https ? 443 : 80;
-    const port = proxy.port === null || proxy.port === defaultPort ? "" : `:${proxy.port}`;
+    const open = proxy.publicPort ?? proxy.port;
+    const port = open === null || open === defaultPort ? "" : `:${open}`;
     return `${scheme}://${hostname}${port}`;
 }
+/** Points every route URL at `publicPort`, the port Studio forwards to the proxy; null keeps them. */
+export function withPublicPort(state, publicPort) {
+    if (publicPort === null)
+        return state;
+    const proxy = { ...state.proxy, publicPort };
+    const routes = state.routes.map((route) => ({ ...route, url: routeUrl(route.hostname, proxy) }));
+    return { ...state, proxy, routes };
+}

package/dist/server/application/container-source.js

@@ -0,0 +1,19 @@
+import { isContainerName } from "../../core/ports/docker-container.js";
+import { err, ok } from "../../core/result.js";
+import { appError } from "./app-error.js";
+/**
+ * Stops a container from its row. Only a container the last `docker ps` listed can be stopped, so
+ * the endpoint cannot be used to stop anything else.
+ */
+export async function stopContainer(name, source) {
+    if (!isContainerName(name)) {
+        return err(appError("invalid_request", "That is not a Docker container name."));
+    }
+    const reading = await source.read();
+    const listed = reading.state === "ok" && reading.containers.some((item) => item.name === name);
+    if (!listed) {
+        return err(appError("process_not_allowed", `Container ${name} is not one Studio shows; it may have stopped.`));
+    }
+    const stopped = await source.stop(name);
+    return stopped.ok ? ok({ name }) : stopped;
+}