portless-studio 0.1.0 → 0.1.2

package/README.md

@@ -1,5 +1,8 @@
 # portless studio
 
+[![npm](https://img.shields.io/npm/v/portless-studio)](https://www.npmjs.com/package/portless-studio)
+[![CI](https://github.com/keven-bardales/portless-studio/actions/workflows/ci.yml/badge.svg)](https://github.com/keven-bardales/portless-studio/actions/workflows/ci.yml)
+
 A local web dashboard for [portless](https://github.com/vercel-labs/portless): see every dev server
 on your machine, give each one a name like `web.myapp.localhost`, and open it from one page.
 
@@ -13,18 +16,36 @@ 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 as notebook.ml, searching routes with Ctrl+K 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 running pnpm dev in a Studio terminal](docs/images/demo.gif)
 
 The screenshots use the built-in sample data (`?demo`), not a real machine.
 
-## Quick start
+## Install
+
+Requirements: Node 22 or later on Linux, macOS or Windows. portless is installed for you if it is
+missing.
 
-Requires Node 24 or later.
+To try it, run it straight from npm:
 
 ```bash
 npx portless-studio init
 ```
 
+For everyday use, and always for "start at login", install it globally:
+
+```bash
+npm i -g portless-studio
+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 with `npm i -g portless-studio@latest`.
+To remove it, run `portless-studio uninstall`, then `npm rm -g portless-studio`.
+
+## Quick start
+
 `init` asks a few questions and leaves everything working:
 
 - Checks that portless is installed and offers to install it with `npm install -g portless`.
@@ -33,60 +54,52 @@ npx portless-studio init
 - 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, `npx 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.
+  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:
 
@@ -95,164 +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 24 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>`. |
-| `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. |
-
-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.
-
-## 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 24 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 `npx portless-studio uninstall`. 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. If you installed it globally, also run
-`npm uninstall -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
 
@@ -262,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/cli-args.js

@@ -162,14 +162,40 @@ function parseFlags(args, subcommand) {
                             open: { type: "boolean" },
                             register: { type: "boolean" },
                         };
-    const { values, positionals } = parseArgs({
-        args,
+    // parseArgs learned `allowNegative` in Node 22.4; reading `--no-<flag>` here keeps every Node 22.
+    const { args: positive, negated } = splitNegations(args, options);
+    const { values, positionals, tokens } = parseArgs({
+        args: positive,
         options,
-        allowNegative: true,
+        tokens: true,
         allowPositionals: subcommand === "service" || subcommand === "run" || subcommand === "open",
     });
+    for (const token of tokens) {
+        if (token.kind === "option" && options[token.name]?.type === "boolean") {
+            values[token.name] = !negated.has(token.index);
+        }
+    }
     return {
         positionals,
         values: values,
     };
 }
+/**
+ * Turns each `--no-<flag>` of a boolean option into `--<flag>` and remembers its position, so the
+ * last of `--open` and `--no-open` wins. Arguments after `--` are left alone.
+ */
+function splitNegations(args, options) {
+    const negated = new Set();
+    const end = args.indexOf("--");
+    const positive = args.map((arg, index) => {
+        if (end !== -1 && index > end)
+            return arg;
+        const match = /^--no-([^=]+)(=.*)?$/.exec(arg);
+        const name = match?.[1];
+        if (name === undefined || options[name]?.type !== "boolean")
+            return arg;
+        negated.add(index);
+        return `--${name}${match?.[2] ?? ""}`;
+    });
+    return { args: positive, negated };
+}

package/dist/cli/index.js

@@ -5,6 +5,7 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { API_PATHS } from "../core/api/contract.js";
 import { DEFAULT_CONFIG } from "../core/config/studio-config.js";
+import { updateMessage } from "../core/updates/version.js";
 import { createStudioServices, createUninstallServices, startServer, } from "../server/main.js";
 import { HELP, parseCliArgs, resolveStartSettings, } from "./cli-args.js";
 import { runCommand } from "./command-runner.js";
@@ -13,7 +14,7 @@ import { runDoctorCommand } from "./doctor-command.js";
 import { runOpenCommand } from "./focus-command.js";
 import { runInit } from "./init.js";
 import { runListCommand } from "./list-command.js";
-import { installService, resolveServiceEntry, serviceStatus, uninstallService, } from "./login-service.js";
+import { describeServiceInstall, installService, resolveServiceEntry, serviceStatus, uninstallService, } from "./login-service.js";
 import { createMcpServer, serveStdio } from "./mcp/mcp-server.js";
 import { createStudioClient, resolveStudioUrl } from "./mcp/studio-client.js";
 import { AGENT_INSTRUCTIONS, createStudioTools } from "./mcp/studio-tools.js";
@@ -162,6 +163,7 @@ async function start(overrides) {
         studioPort: settings.port,
         studioService,
         openUrl: openBrowser,
+        version: readVersion(),
     });
     const webDir = resolveWebDir();
     let server;
@@ -190,6 +192,11 @@ async function start(overrides) {
         print("  API only: the UI runs through `pnpm dev:web`.");
     if (settings.open && webDir)
         openBrowser(alias.url ?? server.url);
+    // Never holds up the start: the line shows up once npm answers, or never when it does not.
+    void services.updates?.status().then((update) => {
+        if (update.available && update.latest)
+            print(updateMessage(update.current, update.latest));
+    });
     let stopping = false;
     const stop = async () => {
         if (stopping)
@@ -220,7 +227,7 @@ async function init(yes) {
                 const env = await serviceEnv();
                 if (!env.ok)
                     return env;
-                return describeInstall(await installService(env.value), env.value);
+                return describeServiceInstall(await installService(env.value), env.value);
             },
         });
     }
@@ -272,7 +279,7 @@ async function service(action) {
         process.exit(1);
     }
     if (action === "install") {
-        const described = describeInstall(await installService(env.value), env.value);
+        const described = describeServiceInstall(await installService(env.value), env.value);
         if (!described.ok) {
             console.error(`Error: ${described.error}`);
             process.exit(1);
@@ -295,18 +302,6 @@ async function service(action) {
     print(`Start at login: ${state.installed ? "installed" : "not installed"} (${state.file})`);
     print(`Running:        ${state.running ? "yes" : "no"}`);
 }
-function describeInstall(installed, env) {
-    if (!installed.ok)
-        return installed;
-    const lines = [`Studio will start when you log in. Service file: ${installed.value.file}`];
-    if (env.platform === "win32")
-        lines.push("Start it now with: portless-studio");
-    if (env.entryPath.includes(`${path.sep}_npx${path.sep}`)) {
-        lines.push("Note: this runs from the npx cache, which npm can clear. Install Studio globally with " +
-            "`npm install -g portless-studio` and run `portless-studio service install` again.");
-    }
-    return { ok: true, value: lines.join("\n") };
-}
 async function serviceEnv() {
     const entry = resolveServiceEntry(import.meta.url);
     if (!entry.ok)

package/dist/cli/login-service.js

@@ -38,6 +38,22 @@ export function resolveServiceEntry(moduleUrl) {
     }
     return ok(fileURLToPath(moduleUrl));
 }
+/**
+ * What `service install` and `init` print after installing. A service started from the npx cache
+ * breaks once npm clears it, so that case ends with the commands that move it to a global install.
+ */
+export function describeServiceInstall(installed, env) {
+    if (!installed.ok)
+        return installed;
+    const lines = [`Studio will start when you log in. Service file: ${installed.value.file}`];
+    if (env.platform === "win32")
+        lines.push("Start it now with: portless-studio");
+    if (/[\\/]_npx[\\/]/.test(env.entryPath)) {
+        lines.push("Note: this runs Studio from the npx cache, which npm can clear, and then Studio no longer " +
+            "starts at login. Install Studio globally and set up the service again:", "  npm i -g portless-studio", "  portless-studio service install");
+    }
+    return ok(lines.join("\n"));
+}
 export async function installService(env) {
     const file = serviceFile(env);
     fs.mkdirSync(path.dirname(file), { recursive: true });

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`,
@@ -62,12 +73,19 @@ export const API_PATHS = {
     focus: "/api/focus",
     /** POST `FocusAck`: a page says whether it got the window to the front. */
     focusAck: "/api/focus/ack",
+    /** GET returns `UpdateStatus`: whether a newer portless-studio is on npm. Read-only. */
+    update: "/api/update",
 };
 /**
  * Query parameter that carries the token where a header cannot: the browser's EventSource sends
  * 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

@@ -35,6 +35,9 @@ export const DEFAULT_CONFIG = {
     systemNotifications: false,
     projectIcons: {},
     nameTemplate: DEFAULT_NAME_TEMPLATE,
+    checkForUpdates: true,
+    shortUrls: false,
+    showStudioRoute: false,
 };
 const MIN_SCAN_INTERVAL_MS = 1000;
 /**
@@ -55,6 +58,9 @@ export function parseConfig(input) {
         "proxyHttps",
         "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}`;
+}