portless-studio 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keven Bardales
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,322 @@
-# Temporary Holding Version
+# portless studio
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![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.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/dashboard-dark.png">
+  <img alt="The Studio dashboard: detected ports without a name at the top, named routes grouped by project below, each with its branch, folder, port and uptime" src="docs/images/dashboard-light.png" width="1280">
+</picture>
+
+portless replaces port numbers with names: `portless api pnpm dev` serves your app at
+`http://api.localhost:1355` instead of `http://localhost:3000`. It has no interface of its own, so
+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)
+
+The screenshots use the built-in sample data (`?demo`), not a real machine.
+
+## Install
+
+Requires Node 22 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:
+
+```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
+```
+
+## 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`.
+- Asks for the basic settings (auto mode, start at login, port, open the browser) and saves them.
+- Finds the dev servers already running, suggests a name for each and names them in portless.
+- 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.
+
+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.
+
+## 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.
+- **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.
+- **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).
+- **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.
+- **Keyboard first:** every action has a key, `?` lists them and `Ctrl+K` (`Cmd+K`) runs any of
+  them by name.
+
+## How naming works
+
+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.
+
+Anything that names a route through the portless CLI also shows up in Studio:
+
+```bash
+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:
+
+```bash
+claude mcp add --scope user portless-studio -- npx -y portless-studio mcp
+```
+
+[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.
+
+## Terminals
+
+```bash
+portless-studio run -- pnpm dev
+```
+
+`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 |
+
+## 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`.
+
+## Development
+
+```bash
+git clone https://github.com/keven-bardales/portless-studio
+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.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/dist/cli/cli-args.js

@@ -0,0 +1,201 @@
+import { parseArgs } from "node:util";
+import { err, ok } from "../core/result.js";
+import { parsePort } from "../core/routes/route-name.js";
+export const DEFAULT_PORT = 4949;
+export const HELP = `portless-studio: a local web dashboard for portless routes
+
+Usage:
+  portless-studio [options]           Start Studio
+  portless-studio init [--yes]        Set everything up: portless, settings, names, proxy
+  portless-studio uninstall [--yes]   Undo the setup: login service, names Studio gave, the
+                                      proxy it started; asks before deleting the settings
+  portless-studio service install     Start Studio when you log in
+  portless-studio service uninstall   Stop starting Studio when you log in
+  portless-studio service status      Say whether the login service is installed and running
+  portless-studio config [--edit]     Print the config file, or open it in $EDITOR
+  portless-studio doctor              Check portless, the proxy and Studio, and say how to fix
+                                      what is wrong (exit code 1 when something fails)
+  portless-studio list [--json]       List named routes and ports without a name, from the running
+                                      Studio (or read directly when it is not running)
+  portless-studio mcp                 Run an MCP server on stdio so AI agents can list, name and
+                                      stop dev servers through the running Studio (docs/mcp.md)
+  portless-studio run [--name <name>] [--cwd <dir>] -- <command...>
+                                      Run a command in a Studio terminal, name the port it
+                                      opens and print its output here until Ctrl+C, which stops
+                                      it (docs/terminals.md)
+  portless-studio open [target]       Bring Studio to the front showing a route, project,
+                                      terminal id or port:<n>
+
+Options:
+  --port <n>       Port for the dashboard, on 127.0.0.1 (default from the config, ${DEFAULT_PORT};
+                   0 picks a free one)
+  --no-open        Do not open the browser
+  --no-register    Do not register the "studio" portless alias for the dashboard
+  -y, --yes        With init and uninstall: accept every default without asking
+  --json           With doctor, config and list: print JSON for scripts and agents
+  --name <name>    With run: name for the port the command opens (default: the suggested one)
+  --cwd <dir>      With run: folder to run in (default: the current folder)
+  -h, --help       Show this help
+  -v, --version    Show the version
+
+Environment:
+  PORTLESS_STATE_DIR   portless state directory (default ~/.portless)
+  PORTLESS_BIN         portless binary used to create and remove aliases (default: portless)
+  EDITOR               Editor that \`config --edit\` opens
+  PORTLESS_STUDIO_URL  Studio that \`mcp\`, \`list\`, \`run\` and \`open\` talk to
+                       (default http://127.0.0.1:<port>)
+`;
+const SUBCOMMANDS = new Set([
+    "init",
+    "uninstall",
+    "service",
+    "config",
+    "doctor",
+    "list",
+    "mcp",
+    "run",
+    "open",
+]);
+const SERVICE_ACTIONS = new Set(["install", "uninstall", "status"]);
+/** Turns command-line arguments into options, or a message saying what is wrong with them. */
+export function parseCliArgs(argv) {
+    const first = argv[0];
+    const subcommand = first !== undefined && !first.startsWith("-") ? first : null;
+    if (subcommand !== null && !SUBCOMMANDS.has(subcommand)) {
+        return err(`Unknown command "${subcommand}".`);
+    }
+    const rest = subcommand === null ? argv : argv.slice(1);
+    let parsed;
+    try {
+        parsed = parseFlags(rest, subcommand);
+    }
+    catch (error) {
+        return err(error.message);
+    }
+    const { values, positionals } = parsed;
+    if (values.help)
+        return ok({ command: "help" });
+    if (values.version)
+        return ok({ command: "version" });
+    if (subcommand === "init")
+        return ok({ command: "init", yes: values.yes === true });
+    if (subcommand === "uninstall")
+        return ok({ command: "uninstall", yes: values.yes === true });
+    const json = values.json === true;
+    if (subcommand === "config") {
+        if (values.edit && json)
+            return err("Use either --edit or --json, not both.");
+        return ok({ command: "config", edit: values.edit === true, json });
+    }
+    if (subcommand === "doctor")
+        return ok({ command: "doctor", json });
+    if (subcommand === "list")
+        return ok({ command: "list", json });
+    if (subcommand === "mcp")
+        return ok({ command: "mcp" });
+    if (subcommand === "run") {
+        if (positionals.length === 0) {
+            return err('Give the command to run after "--", e.g. portless-studio run -- pnpm dev');
+        }
+        if (values.name !== undefined && values.name.trim() === "")
+            return err("--name needs a name.");
+        return ok({
+            command: "run",
+            cwd: values.cwd ?? null,
+            name: values.name?.trim() ?? null,
+            argv: positionals,
+        });
+    }
+    if (subcommand === "open") {
+        if (positionals.length > 1)
+            return err('Give one target to "open", e.g. web.myapp or t2.');
+        return ok({ command: "open", target: positionals[0] ?? null });
+    }
+    if (subcommand === "service") {
+        const action = positionals[0];
+        if (action === undefined || !SERVICE_ACTIONS.has(action) || positionals.length > 1) {
+            return err('Use "service install", "service uninstall" or "service status".');
+        }
+        return ok({ command: "service", action: action });
+    }
+    const overrides = {};
+    if (values.port !== undefined) {
+        const port = values.port.trim() === "0" ? ok(0) : parsePort(values.port);
+        if (!port.ok)
+            return err(`Invalid --port "${values.port}": use a number from 0 to 65535.`);
+        overrides.port = port.value;
+    }
+    if (values.open !== undefined)
+        overrides.open = values.open;
+    if (values.register !== undefined)
+        overrides.register = values.register;
+    return ok({ command: "start", overrides });
+}
+/** Settings for starting the server: the config, with any flag taking its place. */
+export function resolveStartSettings(overrides, config) {
+    return {
+        port: overrides.port ?? config.port,
+        open: overrides.open ?? config.openBrowser,
+        register: overrides.register ?? config.registerStudioAlias,
+    };
+}
+/** Each subcommand accepts only its own flags, so a typo fails instead of being ignored. */
+function parseFlags(args, subcommand) {
+    const common = {
+        help: { type: "boolean", short: "h" },
+        version: { type: "boolean", short: "v" },
+    };
+    const json = { type: "boolean" };
+    const options = subcommand === "init" || subcommand === "uninstall"
+        ? { ...common, yes: { type: "boolean", short: "y" } }
+        : subcommand === "config"
+            ? { ...common, edit: { type: "boolean" }, json }
+            : subcommand === "doctor" || subcommand === "list"
+                ? { ...common, json }
+                : subcommand === "service" || subcommand === "mcp" || subcommand === "open"
+                    ? common
+                    : subcommand === "run"
+                        ? { ...common, name: { type: "string" }, cwd: { type: "string" } }
+                        : {
+                            ...common,
+                            port: { type: "string" },
+                            open: { type: "boolean" },
+                            register: { type: "boolean" },
+                        };
+    // 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,
+        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/command-runner.js

@@ -0,0 +1,10 @@
+import { runProcess } from "../server/infrastructure/system/process-runner.js";
+/** The server's process runner, so Windows quoting and UTF-8 output work the same in the CLI. */
+export const runCommand = async (command, args, options = {}) => {
+    const outcome = await runProcess(command, args, { inherit: options.inherit === true });
+    return {
+        exitCode: outcome.exitCode,
+        output: outcome.error ?? outcome.combined.trim(),
+        missing: outcome.missing,
+    };
+};

package/dist/cli/config-command.js

@@ -0,0 +1,46 @@
+import * as fs from "node:fs";
+/** `portless-studio config`: where the file is and what Studio reads from it. */
+export async function printConfig(store, print) {
+    print(`Config file: ${store.path}`);
+    const read = await store.read();
+    if (!read.ok) {
+        print(`The file has a problem: ${read.error.message}`);
+        return;
+    }
+    print(JSON.stringify(read.value, null, 2));
+    if (!fs.existsSync(store.path))
+        print("(The file is not created yet; these are the defaults.)");
+}
+/** `portless-studio config --json`: the same `{ config, path }` shape `GET /api/config` answers. */
+export async function printConfigJson(store, print) {
+    const read = await store.read();
+    if (!read.ok) {
+        print(JSON.stringify({ error: read.error.message, path: store.path }, null, 2));
+        return 1;
+    }
+    const response = { config: read.value, path: store.path };
+    print(JSON.stringify(response, null, 2));
+    return 0;
+}
+/**
+ * `portless-studio config --edit`: opens the file in `editor` (`$EDITOR`, which may carry flags
+ * such as `code -w`). The file is created with the current values first so there is something to
+ * edit. Without an editor it prints the path.
+ */
+export async function editConfig(store, editor, run, print) {
+    if (!fs.existsSync(store.path)) {
+        const read = await store.read();
+        if (read.ok)
+            await store.write(read.value);
+    }
+    const [command, ...flags] = (editor ?? "").trim().split(/\s+/).filter(Boolean);
+    if (command === undefined) {
+        print(`Set $EDITOR to open it from here, or edit it directly: ${store.path}`);
+        return;
+    }
+    const result = await run(command, [...flags, store.path], { inherit: true });
+    if (result.exitCode !== 0)
+        print(`${command} did not open the file. Edit it at: ${store.path}`);
+    else
+        print("Saved changes reach a running Studio without a restart.");
+}

package/dist/cli/doctor-command.js

@@ -0,0 +1,36 @@
+import { overallStatus } from "../core/doctor/doctor-check.js";
+const MARKS = { ok: "✓", warn: "!", fail: "✗" };
+/** A readable checklist: one line per check, then what was found and the fix for each problem. */
+export function formatDoctorReport(checks) {
+    const lines = [];
+    for (const check of checks) {
+        lines.push(`  ${MARKS[check.status]} ${check.title}`);
+        if (check.status === "ok")
+            continue;
+        lines.push(`      ${check.detail}`);
+        if (check.fix?.command)
+            lines.push(`      Fix: ${check.fix.command}`);
+        else if (check.fix)
+            lines.push(`      Fix: "${check.fix.label}" in Studio's Health panel`);
+    }
+    lines.push("", summary(checks));
+    return lines.join("\n");
+}
+/** Prints the report; the exit code is 1 when any check fails, so scripts can rely on it. */
+export async function runDoctorCommand(check, print, options = {}) {
+    const checks = await check();
+    const status = overallStatus(checks);
+    print(options.json ? JSON.stringify({ status, checks }, null, 2) : formatDoctorReport(checks));
+    return status === "fail" ? 1 : 0;
+}
+function summary(checks) {
+    const failures = checks.filter((check) => check.status === "fail").length;
+    const warnings = checks.filter((check) => check.status === "warn").length;
+    if (failures === 0 && warnings === 0)
+        return "Everything looks good.";
+    const parts = [
+        failures > 0 ? `${failures} ${failures === 1 ? "problem" : "problems"}` : null,
+        warnings > 0 ? `${warnings} ${warnings === 1 ? "warning" : "warnings"}` : null,
+    ].filter(Boolean);
+    return `${parts.join(" and ")}.`;
+}

package/dist/cli/focus-command.js

@@ -0,0 +1,15 @@
+import { API_PATHS } from "../core/api/contract.js";
+import { describeFocus } from "./mcp/studio-tools.js";
+/**
+ * `portless-studio open [target]`: brings the Studio page to the front showing a route, a
+ * project, a terminal or a port. Returns the exit code.
+ */
+export async function runOpenCommand(client, target, print, printError) {
+    const result = await client.write("POST", API_PATHS.focus, target ? { target } : {});
+    if (!result.ok) {
+        printError(`Error: ${result.error.message}`);
+        return 1;
+    }
+    print(describeFocus(result.value));
+    return 0;
+}