rbrowser 0.1.6__tar.gz

rbrowser-0.1.6/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include rbrowser_cli/frontend *
+include README.md

rbrowser-0.1.6/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: rbrowser
+Version: 0.1.6
+Summary: Launch RBrowser with a local or remote (SSH) directory as a file server
+Author: RBrowser Team
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: flask>=2.0
+Requires-Dist: flask-cors>=4.0
+
+# RBrowser CLI
+
+Launch [RBrowser](https://rbrowser.org) with a local or remote (SSH) directory
+as a file server backend. **The frontend UI is bundled inside the wheel** —
+one `pip install` and you're ready to go (no Node.js, no extra build step).
+
+## Install
+
+```bash
+pip install rbrowser-cli
+```
+
+## Usage
+
+```bash
+# Open current directory (UI served from http://localhost:<port>)
+rbrowser open .
+
+# Open a specific directory
+rbrowser open /data/myproject
+
+# Open a remote SSH directory (requires ssh-agent or key auth)
+rbrowser open user@host:/data/myproject
+
+# Use a custom port
+rbrowser open . --port 8888
+
+# Override the bundled UI with a hosted RBrowser
+rbrowser open . --frontend https://rbrowser.org
+```
+
+The CLI prints (and auto-opens) a URL like
+`http://localhost:<port>/#/main?fileServerUrl=...`, which jumps the user
+directly to the Main view's File Explorer panel — no home-page detour.
+
+When run on a remote SSH host, the URL is printed as a Ctrl+Click hyperlink so
+you can open it from your local terminal.
+
+---
+
+## Maintainer notes (release flow)
+
+End users do **not** need to do this. To produce a wheel that ships the UI:
+
+```bash
+# One-shot: install JS deps, build frontend, build sdist + wheel
+node rbrowser-cli/scripts/build_release.mjs
+
+# Skip the npm install (faster local iterations)
+node rbrowser-cli/scripts/build_release.mjs --skip-install
+
+# Or via npm:
+npm run release:cli                 # full pipeline
+npm run build:cli-wheel             # skip-install variant
+
+# Output is in rbrowser-cli/dist/  (sdist + wheel)
+```
+
+### Publishing to PyPI via GitHub Actions
+
+The workflow [`.github/workflows/publish-rbrowser-cli.yml`](../.github/workflows/publish-rbrowser-cli.yml)
+publishes a release to PyPI using **Trusted Publishing** (OIDC — no API
+token in repo secrets). To set it up once:
+
+1. On <https://pypi.org/manage/account/publishing/>, add a _pending publisher_:
+   - PyPI project name: `rbrowser-cli`
+   - Owner: `typekey` · Repository: `rna-browser`
+   - Workflow: `publish-rbrowser-cli.yml`
+   - Environment: `pypi`
+2. In the GitHub repo Settings → Environments, create an environment named
+   `pypi` (optionally with a required reviewer).
+
+Then to release:
+
+```bash
+# One-liner: bump patch version, build, commit, tag, push.
+# (PyPI is published automatically by the GitHub Action.)
+npm run release:cli:patch        # 0.1.0 -> 0.1.1
+npm run release:cli:minor        # 0.1.0 -> 0.2.0
+npm run release:cli:major        # 0.1.0 -> 1.0.0
+
+# Or pick an explicit version (and add --push when ready):
+node rbrowser-cli/scripts/release.mjs 0.2.3 --push
+
+# Dry-run / inspect first; create the tag locally without pushing:
+node rbrowser-cli/scripts/release.mjs patch              # local tag only
+node rbrowser-cli/scripts/release.mjs patch --dry-run    # print, don't mutate
+```
+
+What `release.mjs` does:
+
+1. Resolves the new version (explicit or `patch` / `minor` / `major` bump).
+2. Verifies the working tree is clean and on `main` (override with
+   `--allow-dirty` / `--branch=…`).
+3. Rewrites `pyproject.toml`'s version.
+4. Runs the full local build (skip with `--no-build`) so you can spot any
+   issue before the tag is pushed.
+5. Commits, creates the annotated tag `rbrowser-cli-vX.Y.Z`, and (with
+   `--push`) pushes both to `origin` — which fires the publish workflow.
+
+Manual fallback (no script):
+
+```bash
+# Update version in rbrowser-cli/pyproject.toml first.
+git commit -am "chore(rbrowser-cli): release v0.1.1"
+git tag rbrowser-cli-v0.1.1
+git push origin main rbrowser-cli-v0.1.1
+```
+
+`pyproject.toml` already declares `frontend/**/*` as `package-data`, so the
+built UI is included in the wheel automatically.

rbrowser-0.1.6/README.md

@@ -0,0 +1,111 @@
+# RBrowser CLI
+
+Launch [RBrowser](https://rbrowser.org) with a local or remote (SSH) directory
+as a file server backend. **The frontend UI is bundled inside the wheel** —
+one `pip install` and you're ready to go (no Node.js, no extra build step).
+
+## Install
+
+```bash
+pip install rbrowser-cli
+```
+
+## Usage
+
+```bash
+# Open current directory (UI served from http://localhost:<port>)
+rbrowser open .
+
+# Open a specific directory
+rbrowser open /data/myproject
+
+# Open a remote SSH directory (requires ssh-agent or key auth)
+rbrowser open user@host:/data/myproject
+
+# Use a custom port
+rbrowser open . --port 8888
+
+# Override the bundled UI with a hosted RBrowser
+rbrowser open . --frontend https://rbrowser.org
+```
+
+The CLI prints (and auto-opens) a URL like
+`http://localhost:<port>/#/main?fileServerUrl=...`, which jumps the user
+directly to the Main view's File Explorer panel — no home-page detour.
+
+When run on a remote SSH host, the URL is printed as a Ctrl+Click hyperlink so
+you can open it from your local terminal.
+
+---
+
+## Maintainer notes (release flow)
+
+End users do **not** need to do this. To produce a wheel that ships the UI:
+
+```bash
+# One-shot: install JS deps, build frontend, build sdist + wheel
+node rbrowser-cli/scripts/build_release.mjs
+
+# Skip the npm install (faster local iterations)
+node rbrowser-cli/scripts/build_release.mjs --skip-install
+
+# Or via npm:
+npm run release:cli                 # full pipeline
+npm run build:cli-wheel             # skip-install variant
+
+# Output is in rbrowser-cli/dist/  (sdist + wheel)
+```
+
+### Publishing to PyPI via GitHub Actions
+
+The workflow [`.github/workflows/publish-rbrowser-cli.yml`](../.github/workflows/publish-rbrowser-cli.yml)
+publishes a release to PyPI using **Trusted Publishing** (OIDC — no API
+token in repo secrets). To set it up once:
+
+1. On <https://pypi.org/manage/account/publishing/>, add a _pending publisher_:
+   - PyPI project name: `rbrowser-cli`
+   - Owner: `typekey` · Repository: `rna-browser`
+   - Workflow: `publish-rbrowser-cli.yml`
+   - Environment: `pypi`
+2. In the GitHub repo Settings → Environments, create an environment named
+   `pypi` (optionally with a required reviewer).
+
+Then to release:
+
+```bash
+# One-liner: bump patch version, build, commit, tag, push.
+# (PyPI is published automatically by the GitHub Action.)
+npm run release:cli:patch        # 0.1.0 -> 0.1.1
+npm run release:cli:minor        # 0.1.0 -> 0.2.0
+npm run release:cli:major        # 0.1.0 -> 1.0.0
+
+# Or pick an explicit version (and add --push when ready):
+node rbrowser-cli/scripts/release.mjs 0.2.3 --push
+
+# Dry-run / inspect first; create the tag locally without pushing:
+node rbrowser-cli/scripts/release.mjs patch              # local tag only
+node rbrowser-cli/scripts/release.mjs patch --dry-run    # print, don't mutate
+```
+
+What `release.mjs` does:
+
+1. Resolves the new version (explicit or `patch` / `minor` / `major` bump).
+2. Verifies the working tree is clean and on `main` (override with
+   `--allow-dirty` / `--branch=…`).
+3. Rewrites `pyproject.toml`'s version.
+4. Runs the full local build (skip with `--no-build`) so you can spot any
+   issue before the tag is pushed.
+5. Commits, creates the annotated tag `rbrowser-cli-vX.Y.Z`, and (with
+   `--push`) pushes both to `origin` — which fires the publish workflow.
+
+Manual fallback (no script):
+
+```bash
+# Update version in rbrowser-cli/pyproject.toml first.
+git commit -am "chore(rbrowser-cli): release v0.1.1"
+git tag rbrowser-cli-v0.1.1
+git push origin main rbrowser-cli-v0.1.1
+```
+
+`pyproject.toml` already declares `frontend/**/*` as `package-data`, so the
+built UI is included in the wheel automatically.

rbrowser-0.1.6/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rbrowser"
+version = "0.1.6"
+description = "Launch RBrowser with a local or remote (SSH) directory as a file server"
+readme = "README.md"
+requires-python = ">=3.8"
+authors = [{ name = "RBrowser Team" }]
+license = { text = "MIT" }
+dependencies = [
+    "click>=8.0",
+    "flask>=2.0",
+    "flask-cors>=4.0",
+]
+
+[project.scripts]
+rbrowser = "rbrowser_cli.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["rbrowser_cli*"]
+
+[tool.setuptools.package-data]
+rbrowser_cli = [
+    "frontend/**/*",
+    "frontend/index.html",
+]

rbrowser-0.1.6/rbrowser.egg-info/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: rbrowser
+Version: 0.1.6
+Summary: Launch RBrowser with a local or remote (SSH) directory as a file server
+Author: RBrowser Team
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: flask>=2.0
+Requires-Dist: flask-cors>=4.0
+
+# RBrowser CLI
+
+Launch [RBrowser](https://rbrowser.org) with a local or remote (SSH) directory
+as a file server backend. **The frontend UI is bundled inside the wheel** —
+one `pip install` and you're ready to go (no Node.js, no extra build step).
+
+## Install
+
+```bash
+pip install rbrowser-cli
+```
+
+## Usage
+
+```bash
+# Open current directory (UI served from http://localhost:<port>)
+rbrowser open .
+
+# Open a specific directory
+rbrowser open /data/myproject
+
+# Open a remote SSH directory (requires ssh-agent or key auth)
+rbrowser open user@host:/data/myproject
+
+# Use a custom port
+rbrowser open . --port 8888
+
+# Override the bundled UI with a hosted RBrowser
+rbrowser open . --frontend https://rbrowser.org
+```
+
+The CLI prints (and auto-opens) a URL like
+`http://localhost:<port>/#/main?fileServerUrl=...`, which jumps the user
+directly to the Main view's File Explorer panel — no home-page detour.
+
+When run on a remote SSH host, the URL is printed as a Ctrl+Click hyperlink so
+you can open it from your local terminal.
+
+---
+
+## Maintainer notes (release flow)
+
+End users do **not** need to do this. To produce a wheel that ships the UI:
+
+```bash
+# One-shot: install JS deps, build frontend, build sdist + wheel
+node rbrowser-cli/scripts/build_release.mjs
+
+# Skip the npm install (faster local iterations)
+node rbrowser-cli/scripts/build_release.mjs --skip-install
+
+# Or via npm:
+npm run release:cli                 # full pipeline
+npm run build:cli-wheel             # skip-install variant
+
+# Output is in rbrowser-cli/dist/  (sdist + wheel)
+```
+
+### Publishing to PyPI via GitHub Actions
+
+The workflow [`.github/workflows/publish-rbrowser-cli.yml`](../.github/workflows/publish-rbrowser-cli.yml)
+publishes a release to PyPI using **Trusted Publishing** (OIDC — no API
+token in repo secrets). To set it up once:
+
+1. On <https://pypi.org/manage/account/publishing/>, add a _pending publisher_:
+   - PyPI project name: `rbrowser-cli`
+   - Owner: `typekey` · Repository: `rna-browser`
+   - Workflow: `publish-rbrowser-cli.yml`
+   - Environment: `pypi`
+2. In the GitHub repo Settings → Environments, create an environment named
+   `pypi` (optionally with a required reviewer).
+
+Then to release:
+
+```bash
+# One-liner: bump patch version, build, commit, tag, push.
+# (PyPI is published automatically by the GitHub Action.)
+npm run release:cli:patch        # 0.1.0 -> 0.1.1
+npm run release:cli:minor        # 0.1.0 -> 0.2.0
+npm run release:cli:major        # 0.1.0 -> 1.0.0
+
+# Or pick an explicit version (and add --push when ready):
+node rbrowser-cli/scripts/release.mjs 0.2.3 --push
+
+# Dry-run / inspect first; create the tag locally without pushing:
+node rbrowser-cli/scripts/release.mjs patch              # local tag only
+node rbrowser-cli/scripts/release.mjs patch --dry-run    # print, don't mutate
+```
+
+What `release.mjs` does:
+
+1. Resolves the new version (explicit or `patch` / `minor` / `major` bump).
+2. Verifies the working tree is clean and on `main` (override with
+   `--allow-dirty` / `--branch=…`).
+3. Rewrites `pyproject.toml`'s version.
+4. Runs the full local build (skip with `--no-build`) so you can spot any
+   issue before the tag is pushed.
+5. Commits, creates the annotated tag `rbrowser-cli-vX.Y.Z`, and (with
+   `--push`) pushes both to `origin` — which fires the publish workflow.
+
+Manual fallback (no script):
+
+```bash
+# Update version in rbrowser-cli/pyproject.toml first.
+git commit -am "chore(rbrowser-cli): release v0.1.1"
+git tag rbrowser-cli-v0.1.1
+git push origin main rbrowser-cli-v0.1.1
+```
+
+`pyproject.toml` already declares `frontend/**/*` as `package-data`, so the
+built UI is included in the wheel automatically.

rbrowser-0.1.6/rbrowser.egg-info/SOURCES.txt

@@ -0,0 +1,122 @@
+MANIFEST.in
+README.md
+pyproject.toml
+rbrowser.egg-info/PKG-INFO
+rbrowser.egg-info/SOURCES.txt
+rbrowser.egg-info/dependency_links.txt
+rbrowser.egg-info/entry_points.txt
+rbrowser.egg-info/requires.txt
+rbrowser.egg-info/top_level.txt
+rbrowser_cli/__init__.py
+rbrowser_cli/cli.py
+rbrowser_cli/output.py
+rbrowser_cli/path_parser.py
+rbrowser_cli/server_local.py
+rbrowser_cli/server_ssh.py
+rbrowser_cli/frontend/favicon.ico
+rbrowser_cli/frontend/index.html
+rbrowser_cli/frontend/logo192.png
+rbrowser_cli/frontend/logo512.png
+rbrowser_cli/frontend/manifest.json
+rbrowser_cli/frontend/robots.txt
+rbrowser_cli/frontend/assets/fonts/desyrel/desyrel.png
+rbrowser_cli/frontend/assets/fonts/desyrel/desyrel.xml
+rbrowser_cli/frontend/assets/fonts/inter/Inter-16.png
+rbrowser_cli/frontend/assets/fonts/inter/Inter-16.xml
+rbrowser_cli/frontend/assets/fonts/inter/Inter-72.png
+rbrowser_cli/frontend/assets/fonts/inter/Inter-72.xml
+rbrowser_cli/frontend/assets/fonts/inter/Inter-ExtraLightBETA.png
+rbrowser_cli/frontend/assets/fonts/inter/Inter-ExtraLightBETA.xml
+rbrowser_cli/frontend/assets/fonts/inter/Inter-Light-18.png
+rbrowser_cli/frontend/assets/fonts/inter/Inter-Light-18.xml
+rbrowser_cli/frontend/assets/fonts/inter/Inter-Light-64.png
+rbrowser_cli/frontend/assets/fonts/inter/Inter-Light-64.xml
+rbrowser_cli/frontend/assets/fonts/inter/Inter-LightBETA-64.png
+rbrowser_cli/frontend/assets/fonts/inter/Inter-LightBETA-64.xml
+rbrowser_cli/frontend/assets/fonts/inter/Inter-LightBETA.png
+rbrowser_cli/frontend/assets/fonts/inter/Inter-LightBETA.xml
+rbrowser_cli/frontend/assets/fonts/inter/Inter-Regular.json
+rbrowser_cli/frontend/assets/fonts/inter/Inter-Regular.png
+rbrowser_cli/frontend/assets/fonts/inter/Inter-Regular.xml
+rbrowser_cli/frontend/assets/fonts/inter/Inter-SemiBold-64.png
+rbrowser_cli/frontend/assets/fonts/inter/Inter-SemiBold-64.xml
+rbrowser_cli/frontend/assets/fonts/inter/inter.xml
+rbrowser_cli/frontend/assets/fonts/inter/inter_0.png
+rbrowser_cli/frontend/assets/fonts/inter_regular/Inter-Regular.json
+rbrowser_cli/frontend/assets/fonts/inter_regular/Inter-Regular.ttf
+rbrowser_cli/frontend/assets/fonts/inter_regular/font.0.png
+rbrowser_cli/frontend/assets/fonts/inter_regular/font.1.png
+rbrowser_cli/frontend/assets/fonts/inter_regular/font.png
+rbrowser_cli/frontend/assets/fonts/opensans/OpenSans-Regular.json
+rbrowser_cli/frontend/assets/fonts/opensans/OpenSans-Regular.ttf
+rbrowser_cli/frontend/assets/fonts/opensans/font.png
+rbrowser_cli/frontend/assets/g3d/genome.g3d
+rbrowser_cli/frontend/assets/icon/settings.svg
+rbrowser_cli/frontend/assets/textures/arrow_down.png
+rbrowser_cli/frontend/assets/textures/arrow_up.png
+rbrowser_cli/frontend/assets/textures/ball_gray.png
+rbrowser_cli/frontend/assets/textures/ball_gray3.png
+rbrowser_cli/frontend/assets/textures/ball_gray_10x10.png
+rbrowser_cli/frontend/assets/textures/ball_gray_5x5.png
+rbrowser_cli/frontend/assets/textures/ball_white_100.png
+rbrowser_cli/frontend/assets/textures/ball_white_20.png
+rbrowser_cli/frontend/assets/textures/ball_white_40.png
+rbrowser_cli/frontend/assets/textures/base_A.png
+rbrowser_cli/frontend/assets/textures/base_C.png
+rbrowser_cli/frontend/assets/textures/base_G.png
+rbrowser_cli/frontend/assets/textures/base_T.png
+rbrowser_cli/frontend/assets/textures/base_U.png
+rbrowser_cli/frontend/assets/textures/circle_100.png
+rbrowser_cli/frontend/assets/textures/circle_black_100.png
+rbrowser_cli/frontend/assets/textures/circle_red.png
+rbrowser_cli/frontend/assets/textures/circle_white_100.png
+rbrowser_cli/frontend/assets/textures/diamond copy.png
+rbrowser_cli/frontend/assets/textures/diamond.png
+rbrowser_cli/frontend/assets/textures/diamond2.png
+rbrowser_cli/frontend/assets/textures/drop.png
+rbrowser_cli/frontend/assets/textures/drop_line.png
+rbrowser_cli/frontend/assets/textures/ele_gray.png
+rbrowser_cli/frontend/assets/textures/ele_grays.png
+rbrowser_cli/frontend/assets/textures/ele_green.png
+rbrowser_cli/frontend/assets/textures/ele_ocean.png
+rbrowser_cli/frontend/assets/textures/ele_red.png
+rbrowser_cli/frontend/assets/textures/ele_sky.png
+rbrowser_cli/frontend/assets/textures/ele_soft_gray.png
+rbrowser_cli/frontend/assets/textures/ele_yellow.png
+rbrowser_cli/frontend/assets/textures/texture.psd
+rbrowser_cli/frontend/assets/textures/texture_ATCG.psd
+rbrowser_cli/frontend/assets/textures/texture_circle_org.png
+rbrowser_cli/frontend/assets/textures/texture_diamond.psd
+rbrowser_cli/frontend/assets/textures/texture_grey_border_main.png
+rbrowser_cli/frontend/assets/textures/texture_grey_main.png
+rbrowser_cli/frontend/assets/textures/texture_grey_main.psd
+rbrowser_cli/frontend/assets/textures/triangle.png
+rbrowser_cli/frontend/static/css/index.ArNRqnY1.css
+rbrowser_cli/frontend/static/css/index.CroWzXsC.css
+rbrowser_cli/frontend/static/css/index.DPMyIVYU.css
+rbrowser_cli/frontend/static/js/AppstoreAddOutlined.D5ilOMxt.chunk.js
+rbrowser_cli/frontend/static/js/CheckCircleRounded.DVZy-MCf.chunk.js
+rbrowser_cli/frontend/static/js/ClearAllRounded.CUJRdVDQ.chunk.js
+rbrowser_cli/frontend/static/js/ExpandMore.C46BDO5j.chunk.js
+rbrowser_cli/frontend/static/js/Refresh.C83YUbTk.chunk.js
+rbrowser_cli/frontend/static/js/d3-vendor.D2vplkPo.chunk.js
+rbrowser_cli/frontend/static/js/datahub-data.BkMvslYe.chunk.js
+rbrowser_cli/frontend/static/js/index.B36BqAW0.chunk.js
+rbrowser_cli/frontend/static/js/index.B79vQDf2.chunk.js
+rbrowser_cli/frontend/static/js/index.D1QXMsT8.chunk.js
+rbrowser_cli/frontend/static/js/index.DICxSQgm.chunk.js
+rbrowser_cli/frontend/static/js/index.DezPsQiY.chunk.js
+rbrowser_cli/frontend/static/js/index.DhVVPnZF.chunk.js
+rbrowser_cli/frontend/static/js/index.DpkFDdug.js
+rbrowser_cli/frontend/static/js/index.JBr0C4Rc.chunk.js
+rbrowser_cli/frontend/static/js/index.Lr6WmsZR.chunk.js
+rbrowser_cli/frontend/static/js/index.Pv0g6RaM.chunk.js
+rbrowser_cli/frontend/static/js/index.WaMjEOTD.chunk.js
+rbrowser_cli/frontend/static/js/index.oG4Fdp8e.chunk.js
+rbrowser_cli/frontend/static/js/index.pFX21XGS.chunk.js
+rbrowser_cli/frontend/static/js/index.qnCfw2-y.chunk.js
+rbrowser_cli/frontend/static/js/mui-vendor.C2wT3-V2.chunk.js
+rbrowser_cli/frontend/static/js/pixi-vendor.DwNHHdM-.chunk.js
+rbrowser_cli/frontend/static/js/react-vendor.C018e_IG.chunk.js
+rbrowser_cli/frontend/static/js/redux-vendor.BYT4ly2K.chunk.js
+rbrowser_cli/frontend/static/media/logo.BdaLZdU8.png

rbrowser-0.1.6/rbrowser.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

rbrowser-0.1.6/rbrowser.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rbrowser = rbrowser_cli.cli:main

rbrowser-0.1.6/rbrowser.egg-info/requires.txt

@@ -0,0 +1,3 @@
+click>=8.0
+flask>=2.0
+flask-cors>=4.0

rbrowser-0.1.6/rbrowser.egg-info/top_level.txt

@@ -0,0 +1 @@
+rbrowser_cli

rbrowser-0.1.6/rbrowser_cli/__init__.py

@@ -0,0 +1,3 @@
+"""RBrowser CLI — launch RBrowser with a local or remote directory."""
+
+__version__ = "0.1.0"

rbrowser-0.1.6/rbrowser_cli/cli.py

@@ -0,0 +1,143 @@
+"""Click CLI entry-point for ``rbrowser``."""
+
+from __future__ import annotations
+
+import socket
+import sys
+from pathlib import Path
+from urllib.parse import quote, urlencode
+
+import click
+from werkzeug.serving import make_server
+
+from .output import is_remote_session, print_banner
+from .path_parser import parse_path
+
+
+FRONTEND_FALLBACK = "https://rbrowser.org"
+_BUNDLED_FRONTEND_DIR = Path(__file__).parent / "frontend"
+
+
+def _has_bundled_frontend() -> bool:
+    return (_BUNDLED_FRONTEND_DIR / "index.html").is_file()
+
+
+def _pick_port(preferred: int) -> int:
+    """Return an available port. If ``preferred`` is 0, OS picks one."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        try:
+            s.bind(("0.0.0.0", preferred))
+        except OSError as e:
+            raise click.ClickException(f"Port {preferred} is not available: {e}") from e
+        return s.getsockname()[1]
+
+
+def _detect_host_for_url(is_remote_cli: bool) -> str:
+    """Pick the host the user's browser should connect to.
+
+    - When the CLI runs locally, ``localhost`` is the safest default.
+    - When the CLI runs on a remote SSH server, fall back to the externally
+      visible hostname / first non-loopback IPv4 so the user's local browser
+      can reach it (or, if SSH port-forwarding is set up, ``localhost``).
+    """
+    if not is_remote_cli:
+        return "localhost"
+    try:
+        host = socket.gethostname()
+        ip = socket.gethostbyname(host)
+        if ip and not ip.startswith("127."):
+            return host
+    except OSError:
+        pass
+    return "localhost"
+
+
+@click.group()
+@click.version_option()
+def cli() -> None:
+    """RBrowser CLI."""
+
+
+@cli.command("open")
+@click.argument("path")
+@click.option("--port", "-p", type=int, default=0, show_default=False,
+              help="Port to bind (default: random free port).")
+@click.option("--frontend", default=None,
+              help=("RBrowser frontend. Default: bundled (if installed), else "
+                    f"{FRONTEND_FALLBACK}. Pass an http(s):// URL to override."))
+@click.option("--host", default="0.0.0.0", show_default=True,
+              help="Bind address for the file server.")
+def open_cmd(path: str, port: int, frontend: str | None, host: str) -> None:
+    """Start the file server for PATH and open RBrowser.
+
+    PATH may be a local directory or ``user@host:/remote/path``.
+    """
+    parsed = parse_path(path)
+
+    # Decide frontend mode: bundled (served from this same server) vs external URL.
+    use_bundled = False
+    if frontend is None:
+        if _has_bundled_frontend():
+            use_bundled = True
+        else:
+            frontend = FRONTEND_FALLBACK
+    elif frontend.lower() in ("bundled", "local"):
+        if not _has_bundled_frontend():
+            raise click.ClickException(
+                "Bundled frontend not found. Reinstall rbrowser-cli or pass --frontend URL."
+            )
+        use_bundled = True
+
+    static_dir = str(_BUNDLED_FRONTEND_DIR) if use_bundled else None
+
+    if parsed.is_remote:
+        from .server_ssh import create_app
+        app = create_app(parsed.ssh_target, parsed.path, static_dir=static_dir)
+    else:
+        from .server_local import create_app
+        app = create_app(parsed.path, static_dir=static_dir)
+
+    bound_port = _pick_port(port) if port else _pick_port(0)
+    remote_session = is_remote_session()
+    url_host = _detect_host_for_url(remote_session)
+
+    server_url = f"http://{url_host}:{bound_port}"
+    if use_bundled:
+        # Bundled frontend: served from the same origin → only need ?root=.
+        # The frontend infers fileServerUrl from window.location.
+        qs = urlencode({"root": parsed.display()}, quote_via=quote)
+        frontend_url = f"{server_url}/#/main?{qs}"
+    else:
+        # External UI: must include fileServerUrl (different origin).
+        qs = urlencode({
+            "fileServerUrl": server_url,
+            "root": parsed.display(),
+        }, quote_via=quote)
+        frontend_url = f"{frontend.rstrip('/')}/#/main?{qs}"
+
+    print_banner(
+        server_url=server_url,
+        frontend_url=frontend_url,
+        root_display=parsed.display(),
+        is_remote=remote_session,
+        bundled=use_bundled,
+    )
+
+    server = make_server(host, bound_port, app, threaded=True)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        click.echo("\nShutting down…")
+        server.shutdown()
+
+
+def main() -> None:
+    try:
+        cli()
+    except click.ClickException as e:
+        e.show()
+        sys.exit(e.exit_code)
+
+
+if __name__ == "__main__":
+    main()