@jaato/web-coder-ui 0.1.0

package/README.md

@@ -0,0 +1,169 @@
+# jaato-web-coder-ui
+
+Browser client for a jaato daemon — the web counterpart of `jaato-tui`.
+It connects to `python -m server --web-socket …` over the daemon's
+WebSocket transport through the TypeScript SDK (`@jaato/sdk`, in
+`../jaato-sdk-ts`), and renders the same session a TUI can be attached to.
+
+Design notes, stack rationale and the input model live in
+[`docs/web-client-design.md`](../docs/web-client-design.md).
+
+## Stack
+
+| Layer | Choice | Why |
+|---|---|---|
+| UI | React 19 + Vite 7 | largest widget ecosystem for the pieces a client like this needs (virtualised lists, docking, terminals) |
+| State | Zustand, one event-sourced reducer | the protocol is a stream of typed events; the store folds them, components subscribe to slices |
+| Protocol | `@jaato/sdk` (workspace `file:` dep, source-aliased) | codegen'd event types stay in lockstep with `events.py`; no hand-written event mirror |
+| Styling | Tailwind v4 + CSS variables | the eleven base colours of the TUI's `themes/*.json` become CSS custom properties, so both clients share one palette definition |
+| Rendering | own `<j-*>` + markdown parsers, no `innerHTML` | the server emits neutral markup (`<j-code>`, `<j-table>`, Pygments token classes); the client only maps classes to theme colours |
+| Tests | Vitest (protocol, store) + Playwright (UI against a scripted mock daemon) | |
+
+## Commands are words, not `/verbs`
+
+jaato commands are typed as bare words: `model gpt-4o`, `tools enable cli`,
+`permissions status`. The composer proposes matching commands while the
+first word is typed; **Esc on the proposal means "I mean this word
+verbatim"** and the line is sent to the model as text even though it starts
+with a command word. A hint under the box always states what Enter will do.
+`@path`, `@@path`, `%prompt` and `/name` (workspace commands under
+`.jaato/commands/`) pass through untouched and disable command proposals,
+as in the TUI. See `src/protocol/commands.ts` for the routing rules, which
+are a port of `jaato-tui/client_commands.py`.
+
+## Run it
+
+The client is published on npm as `@jaato/web-coder-ui`; the package is the built
+bundle plus a dependency-free launcher, so `npx` fetches it in one go:
+
+```bash
+.venv/bin/python -m server --web-socket :8080 --daemon   # the daemon, on this machine
+npx @jaato/web-coder-ui                                            # serves the client, opens the browser
+```
+
+The launcher serves `dist/` on `http://127.0.0.1:5180/`, hands the page the
+daemon URL and — for a local daemon — the token from `~/.jaato/ws.token`, and
+the page connects on its own. Against a daemon elsewhere:
+
+```bash
+npx @jaato/web-coder-ui --daemon ws://build-box:8080 --token-file ./ws.token
+npx @jaato/web-coder-ui --daemon wss://jaato.example.org --no-token     # type the token in the form
+```
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--daemon URL` | `ws://127.0.0.1:8080` | the daemon's `--web-socket` address |
+| `--token TOKEN` / `--token-file PATH` | `~/.jaato/ws.token` when the daemon is loopback and the file exists | bearer token handed to the page |
+| `--no-token` | | hand out no token; the form asks for it (or leave it empty for `--ws-unsafe-no-auth`) |
+| `--host HOST` / `--port PORT` | `127.0.0.1` / `5180` (`0` = any free port) | where the client is served |
+| `--no-open` | | do not open a browser |
+| `--root DIR` | the package's `dist/` | serve another build |
+
+The token is only ever handed to the page on a loopback bind: with
+`--host 0.0.0.0` the launcher serves the client to the network and the
+person at the browser types the token. On loopback the `Host` header must
+name the bound address, so a DNS-rebinding page cannot fetch it either.
+
+### Hosting the bundle yourself
+
+`dist/` is static (assets are referenced relatively, so it can sit under any
+path) and connects to whatever daemon URL the form is given. Put it behind
+nginx, a CDN or a file server, and optionally publish a `config.json` next to
+`index.html` to pre-fill the form:
+
+```json
+{"daemon": "wss://jaato.example.org", "autoConnect": true}
+```
+
+`token` is also accepted there, but a token in a file every visitor can read
+is only right when the file server is as private as the daemon. Every
+publish run of the npm workflow attaches `jaato-web-coder-ui-dist-<version>.tar.gz`
+(the contents of `dist/`) to the GitHub Release `web-coder-ui-v<version>` for
+this use; `npm run build` produces the same directory from a checkout.
+
+### Knowing what you deployed
+
+The SDK is compiled into the bundle, so the build stamps what it speaks:
+`dist/build-info.json` carries the UI version, the `@jaato/sdk` revision,
+its protocol floor and the commit. The connect screen and the status bar
+show the same line, and the launcher prints it:
+
+```bash
+npx @jaato/web-coder-ui --version
+# 0.1.0
+# @jaato/sdk 0.6.0 · protocol ≥ 1.0 · cb65e5e · built 2026-09-15T20:40:00.000Z
+```
+
+## Develop
+
+```bash
+# once: build the SDK declarations the type-check uses
+npm --prefix ../jaato-sdk-ts install && npm --prefix ../jaato-sdk-ts run build
+
+npm install
+npm run dev              # http://localhost:5173, proxies /ws → ws://127.0.0.1:8080
+```
+
+Against a real daemon:
+
+```bash
+.venv/bin/python -m server --web-socket :8080 --workspace-root /srv/workspaces   # or without --workspace-root
+cat ~/.jaato/ws.token                                                            # paste into the connect form
+```
+
+Against the scripted mock (no provider needed):
+
+```bash
+npm run mock-daemon      # ws://127.0.0.1:8090 — try: code, tool, permit, ask, fail, subagent
+```
+
+Connect the form to `ws://127.0.0.1:8090`. `MOCK_WORKSPACES=1` turns on the
+workspace-first flow, `MOCK_TOKEN=x` enforces bearer auth.
+
+## Verify
+
+```bash
+npm run typecheck        # builds the SDK, then tsc
+npm test                 # vitest (protocol, store) + node --test (launcher)
+npm run build            # production bundle in dist/
+npm start -- --no-open   # the launcher, serving that dist/
+npm run e2e              # Playwright, starts the mock daemon and Vite itself
+npm pack                 # the npm tarball (refuses without a dist/)
+```
+
+Publishing is manual: the *Publish @jaato/web-coder-ui to npm* workflow
+(`.github/workflows/publish-npm-web-coder-ui.yml`) runs the same gates as CI,
+refuses a version already on the registry, builds, and **stages** the version
+with the `@jaato` org's stage-only token; a maintainer with 2FA promotes it
+(`npm stage list @jaato/web-coder-ui`, then `npm stage approve <stage-id>
+--otp <code>`). It needs `@jaato/sdk` published first only at build time, from
+the sibling checkout. Bump `version` in `package.json` first.
+
+Set `PLAYWRIGHT_CHROMIUM=/path/to/chrome` to use a pre-installed browser
+instead of Playwright's download.
+
+## Layout
+
+```
+bin/         jaato-web-coder-ui.js — the launcher shipped as the package's `bin` (static server + config.json + browser open), tested with node --test
+src/
+  app/         actions.ts (what a submitted line does), launcherConfig.ts (the page's side of config.json)
+  protocol/    commands.ts (routing + completion), jmarkup.ts, markdown.ts, pygments.ts — pure, unit-tested
+  store/       types.ts, store.ts (reduce(state, event)) — event-sourced client state
+  sdk/         connection.ts — JaatoClient lifecycle, frame-batched dispatch, workspace verbs
+  app/         actions.ts — what a submitted line does (prompt answers, client/server commands, messages)
+  components/  output/ (JMarkup, ToolBlockView, OutputPane, ToolOutputPopup, MediaView)
+               input/Composer.tsx   prompts/ (Permission, Clarification, ReferenceSelection)
+               panels/ (Plan, Budget, Workspace, AgentTabs)   layout/StatusBar.tsx
+  screens/     ConnectScreen, WorkspaceScreen, SessionScreen
+  theme/       themes.ts (imports ../jaato-tui/themes/*.json), theme.css
+mock/daemon.ts scripted daemon speaking the wire protocol, for dev + e2e
+e2e/           Playwright smoke suite
+```
+
+## Keys
+
+`Enter` send · `Shift+Enter` newline · `Tab` complete / re-arm proposals ·
+`Esc` dismiss proposal (send verbatim) · `Ctrl+P` plan · `Ctrl+B` budget ·
+`Alt+W` files · `Ctrl+T` expand/collapse tools · `Ctrl+A` next agent ·
+`Ctrl+O` next running tool in the popup · `Ctrl+C` (nothing selected) stop.

package/bin/jaato-web-coder-ui.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Type declarations for the package's `exports` entry (`bin/jaato-web-coder-ui.js`).
+ * Hand-written: the launcher is plain JavaScript so that `npx @jaato/web-coder-ui`
+ * installs nothing but the bundle, and this file is what lets a TypeScript host
+ * (`jaato-web-coder-server`) import it.
+ */
+import type { IncomingMessage, Server, ServerResponse } from "node:http";
+
+/** The bundle this package ships (`<package>/dist`). */
+export declare const DIST_DIR: string;
+
+/** What `GET /config.json` answers; see `src/app/launcherConfig.ts` for the page's reading of it. */
+export interface StaticConfig {
+  daemon?: string;
+  token?: string;
+  ticketUrl?: string;
+  loginUrl?: string;
+  autoConnect?: boolean;
+}
+
+export interface StaticOptions {
+  /** Directory holding `index.html` and `assets/`. */
+  root: string;
+  config: StaticConfig;
+  /** `Host` header values accepted (lower-case `host:port`); `null` accepts any. */
+  allowedHosts: Set<string> | null;
+}
+
+export type StaticHandler = (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+
+export declare function createStaticHandler(opts: StaticOptions): StaticHandler;
+export declare function createStaticServer(opts: StaticOptions): Server;
+
+export interface LauncherOptions {
+  daemon: string;
+  token?: string;
+  tokenFile?: string;
+  noToken: boolean;
+  host: string;
+  port: number;
+  open: boolean;
+  root: string;
+  help: boolean;
+  version: boolean;
+}
+export declare function parseArgs(argv: string[]): LauncherOptions;
+export declare function isLoopbackHost(host: string): boolean;
+export declare function resolveToken(opts: Partial<LauncherOptions>, io?: { readFile?: (p: string) => string; exists?: (p: string) => boolean }): { token: string | undefined; source: string };
+
+export interface BuildInfo { ui: string; sdk: string; protocolMin: string; commit: string; builtAt: string }
+export declare function readBuildInfo(root?: string): BuildInfo | null;
+
+export declare function main(opts: LauncherOptions): Promise<Server | null>;

package/bin/jaato-web-coder-ui.js

@@ -0,0 +1,328 @@
+#!/usr/bin/env node
+/**
+ * ``jaato-web-coder-ui`` — the launcher that ships in the ``@jaato/web-coder-ui`` package.
+ *
+ * The browser client is a static bundle (``dist/``, produced by
+ * ``vite build``); all this script does is serve that bundle from a
+ * local port, tell the page which daemon to talk to, and open a browser
+ * on it.  It is deliberately dependency-free (Node's ``http`` and ``fs``
+ * only) so ``npx @jaato/web-coder-ui`` installs nothing but the bundle itself.
+ *
+ *     npx @jaato/web-coder-ui                              # ws://127.0.0.1:8080, token from ~/.jaato/ws.token
+ *     npx @jaato/web-coder-ui --daemon ws://build-box:8080 --token-file ./ws.token
+ *     npx @jaato/web-coder-ui --port 9000 --no-open
+ *
+ * How the page learns about the daemon
+ * ------------------------------------
+ * The bundle knows nothing about this launcher; it fetches ``./config.json``
+ * from wherever it was served and, when that answers with
+ * ``{"daemon": ..., "token": ..., "autoConnect": true}``, pre-fills the
+ * connect form and connects.  Anyone hosting ``dist/`` behind nginx or
+ * similar can publish the same file by hand, or none at all, in which
+ * case the form starts empty.  See ``src/app/launcherConfig.ts``.
+ *
+ * Importing this module
+ * ---------------------
+ * It is also the package's ``exports`` entry: ``createStaticServer``,
+ * ``createStaticHandler``, ``parseArgs``, ``resolveToken``, ``readBuildInfo``
+ * and ``DIST_DIR`` are
+ * what a host that serves the bundle itself (``jaato-web-coder-server``)
+ * reuses, and importing has no side effects — the CLI runs only when this
+ * file is the entry point.
+ *
+ * Where the token goes
+ * --------------------
+ * The daemon's bearer token grants full control of the agent, so the
+ * launcher only ever hands it to the page on a **loopback** bind: with
+ * ``--host 0.0.0.0`` the token is left out of ``config.json`` and the
+ * person at the browser types it.  Two more guards apply even on
+ * loopback: ``config.json`` is served as JSON with ``nosniff`` (a page on
+ * another origin cannot read it — a cross-origin ``fetch`` has no CORS
+ * grant and a ``<script src>`` of a JSON document does not execute), and
+ * every request must carry a ``Host`` header naming the address we bound,
+ * which closes the DNS-rebinding route to the same file.
+ */
+import { createServer } from "node:http";
+import { promises as fs, existsSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, extname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** The bundle this package ships; importable by a host that serves it itself (jaato-web-coder-server). */
+export const DIST_DIR = join(HERE, "..", "dist");
+const DEFAULT_ROOT = DIST_DIR;
+const DEFAULT_DAEMON = "ws://127.0.0.1:8080";
+const DEFAULT_TOKEN_FILE = join(homedir(), ".jaato", "ws.token");
+
+const MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".txt": "text/plain; charset=utf-8",
+};
+
+const USAGE = `Usage: jaato-web-coder-ui [options]
+
+Serve the jaato browser client and open it against a daemon started with
+\`python -m server --web-socket [HOST:]PORT\`.
+
+Options:
+  --daemon URL        WebSocket URL of the daemon (default ${DEFAULT_DAEMON})
+  --token TOKEN       Bearer token to hand to the page
+  --token-file PATH   Read the token from PATH (default ~/.jaato/ws.token when
+                      the daemon URL is a loopback address and the file exists)
+  --no-token          Do not pass any token; type it in the connect form
+  --host HOST         Address to serve on (default 127.0.0.1). The token is
+                      only handed out on a loopback bind.
+  --port PORT         Port to serve on (default 5180; 0 picks a free port)
+  --no-open           Do not open a browser
+  --root DIR          Serve this directory instead of the bundled dist/
+  -h, --help          Show this help
+  -v, --version       Print the package version
+`;
+
+/** Parse ``argv`` into launcher options; throws on an unknown flag. */
+export function parseArgs(argv) {
+  const opts = {
+    daemon: DEFAULT_DAEMON,
+    token: undefined,
+    tokenFile: undefined,
+    noToken: false,
+    host: "127.0.0.1",
+    port: 5180,
+    open: true,
+    root: DEFAULT_ROOT,
+    help: false,
+    version: false,
+  };
+  const takeValue = (i, flag) => {
+    const v = argv[i + 1];
+    if (v === undefined) throw new Error(`${flag} needs a value`);
+    return v;
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const eq = a.indexOf("=");
+    const flag = eq > 0 && a.startsWith("--") ? a.slice(0, eq) : a;
+    const inline = eq > 0 && a.startsWith("--") ? a.slice(eq + 1) : undefined;
+    const value = () => (inline !== undefined ? inline : (i++, takeValue(i - 1, flag)));
+    switch (flag) {
+      case "--daemon": opts.daemon = value(); break;
+      case "--token": opts.token = value(); break;
+      case "--token-file": opts.tokenFile = value(); break;
+      case "--no-token": opts.noToken = true; break;
+      case "--host": opts.host = value(); break;
+      case "--port": {
+        const n = Number(value());
+        if (!Number.isInteger(n) || n < 0 || n > 65535) throw new Error("--port must be an integer between 0 and 65535");
+        opts.port = n;
+        break;
+      }
+      case "--open": opts.open = true; break;
+      case "--no-open": opts.open = false; break;
+      case "--root": opts.root = resolve(value()); break;
+      case "-h": case "--help": opts.help = true; break;
+      case "-v": case "--version": opts.version = true; break;
+      default: throw new Error(`unknown option ${a}\n\n${USAGE}`);
+    }
+  }
+  return opts;
+}
+
+/** ``true`` for the hosts a loopback bind answers to. */
+export function isLoopbackHost(host) {
+  const h = host.replace(/^\[|\]$/g, "").toLowerCase();
+  return h === "localhost" || h === "::1" || /^127\.\d+\.\d+\.\d+$/.test(h);
+}
+
+function daemonHost(url) {
+  try { return new URL(url).hostname; } catch { return ""; }
+}
+
+/**
+ * Decide which token (if any) reaches the page.
+ *
+ * Explicit ``--token`` / ``--token-file`` win; otherwise the default
+ * token file is used only for a loopback daemon, because that file
+ * belongs to the daemon on *this* machine and would be the wrong secret
+ * for any other.
+ */
+export function resolveToken(opts, { readFile = (p) => readFileSync(p, "utf8"), exists = existsSync } = {}) {
+  if (opts.noToken) return { token: undefined, source: "disabled" };
+  if (opts.token !== undefined) return { token: opts.token, source: "flag" };
+  if (opts.tokenFile !== undefined) return { token: readFile(opts.tokenFile).trim(), source: opts.tokenFile };
+  if (isLoopbackHost(daemonHost(opts.daemon)) && exists(DEFAULT_TOKEN_FILE)) {
+    return { token: readFile(DEFAULT_TOKEN_FILE).trim(), source: DEFAULT_TOKEN_FILE };
+  }
+  return { token: undefined, source: "none" };
+}
+
+function send(res, status, body, headers = {}) {
+  res.writeHead(status, { "X-Content-Type-Options": "nosniff", ...headers });
+  res.end(body);
+}
+
+/**
+ * Build (but do not start) the static server.
+ *
+ * ``config`` is what ``GET /config.json`` answers; the caller decides
+ * whether it carries a token.  Everything under ``root`` is served
+ * read-only, with the SPA fallback (any path without a file behind it
+ * gets ``index.html``) and immutable caching for Vite's hashed assets.
+ * ``allowedHosts`` is the set of ``Host`` header values accepted (read
+ * on every request, so it may be filled after ``listen``); ``null``
+ * accepts any host.  A request naming another host is refused with 421.
+ */
+export function createStaticServer({ root, config, allowedHosts }) {
+  return createServer(createStaticHandler({ root, config, allowedHosts }));
+}
+
+/**
+ * The request listener behind :func:`createStaticServer`, for a host that
+ * answers its own routes first and falls through to the bundle
+ * (jaato-web-coder-server mounts it after ``/auth/*`` and ``/api/*``).
+ * Same contract: ``config`` answers ``GET /config.json``, ``allowedHosts``
+ * ``null`` accepts any ``Host``.
+ */
+export function createStaticHandler({ root, config, allowedHosts }) {
+  const rootAbs = resolve(root);
+  const configBody = JSON.stringify(config);
+  const hostOk = (req) => {
+    if (!allowedHosts) return true;
+    const h = (req.headers.host ?? "").toLowerCase();
+    return allowedHosts.has(h);
+  };
+
+  return async (req, res) => {
+    if (!hostOk(req)) return send(res, 421, "Misdirected Request\n", { "Content-Type": "text/plain" });
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      return send(res, 405, "Method Not Allowed\n", { "Content-Type": "text/plain", Allow: "GET, HEAD" });
+    }
+    let pathname;
+    try { pathname = decodeURIComponent(new URL(req.url ?? "/", "http://x").pathname); }
+    catch { return send(res, 400, "Bad Request\n", { "Content-Type": "text/plain" }); }
+
+    if (pathname === "/config.json") {
+      return send(res, 200, configBody, { "Content-Type": MIME[".json"], "Cache-Control": "no-store" });
+    }
+
+    let file = resolve(rootAbs, "." + pathname);
+    if (file !== rootAbs && !file.startsWith(rootAbs + sep)) {
+      return send(res, 403, "Forbidden\n", { "Content-Type": "text/plain" });
+    }
+    let stat = await fs.stat(file).catch(() => null);
+    if (stat?.isDirectory()) { file = join(file, "index.html"); stat = await fs.stat(file).catch(() => null); }
+    if (!stat?.isFile()) { file = join(rootAbs, "index.html"); stat = await fs.stat(file).catch(() => null); }
+    if (!stat?.isFile()) return send(res, 404, "Not Found\n", { "Content-Type": "text/plain" });
+
+    const ext = extname(file).toLowerCase();
+    const hashed = file.startsWith(join(rootAbs, "assets") + sep);
+    const headers = {
+      "Content-Type": MIME[ext] ?? "application/octet-stream",
+      "Content-Length": String(stat.size),
+      "Cache-Control": hashed ? "public, max-age=31536000, immutable" : "no-cache",
+    };
+    if (req.method === "HEAD") return send(res, 200, undefined, headers);
+    send(res, 200, await fs.readFile(file), headers);
+  };
+}
+
+function openBrowser(url) {
+  const [cmd, args] =
+    process.platform === "darwin" ? ["open", [url]]
+    : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]]
+    : ["xdg-open", [url]];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).on("error", () => {}).unref();
+  } catch { /* no opener on this box; the URL is printed anyway */ }
+}
+
+function packageVersion() {
+  try { return JSON.parse(readFileSync(join(HERE, "..", "package.json"), "utf8")).version; }
+  catch { return "unknown"; }
+}
+
+/**
+ * The build stamp vite writes beside the bundle (``dist/build-info.json``):
+ * UI version, the @jaato/sdk revision compiled in, its protocol floor and
+ * the commit.  ``null`` when the root carries none (a foreign ``--root``).
+ */
+export function readBuildInfo(root = DEFAULT_ROOT) {
+  try { return JSON.parse(readFileSync(join(root, "build-info.json"), "utf8")); }
+  catch { return null; }
+}
+
+function versionLines(root) {
+  const lines = [packageVersion()];
+  const b = readBuildInfo(root);
+  if (b) lines.push(`@jaato/sdk ${b.sdk} · protocol ≥ ${b.protocolMin} · ${b.commit} · built ${b.builtAt}`);
+  return lines.join("\n") + "\n";
+}
+
+/** Start serving per ``opts`` (from ``parseArgs``); resolves to the listening server. */
+export async function main(opts) {
+  if (opts.help) { process.stdout.write(USAGE); return null; }
+  if (opts.version) { process.stdout.write(versionLines(opts.root)); return null; }
+  if (!existsSync(join(opts.root, "index.html"))) {
+    throw new Error(`no index.html under ${opts.root} — run \`npm run build\` first, or pass --root`);
+  }
+
+  const loopback = isLoopbackHost(opts.host);
+  const { token, source } = resolveToken(opts);
+  const config = { daemon: opts.daemon, autoConnect: true };
+  if (token && loopback) config.token = token;
+
+  // On a loopback bind only the loopback names are accepted in ``Host``,
+  // so a request that names any other host (a rebinding attack) never
+  // sees the token.  A non-loopback bind serves no token, and the names
+  // people reach it by are not ours to know, so it takes any ``Host``.
+  const allowed = loopback ? new Set() : null;
+  const server = createStaticServer({ root: opts.root, config, allowedHosts: allowed });
+  await new Promise((ok, fail) => server.once("error", fail).listen(opts.port, opts.host, ok));
+  const { port } = server.address();
+  if (allowed) for (const h of ["localhost", "127.0.0.1", "[::1]", opts.host]) allowed.add(`${h}:${port}`.toLowerCase());
+
+  const wildcard = opts.host === "0.0.0.0" || opts.host === "::";
+  const hostForUrl = wildcard ? "localhost" : opts.host.includes(":") ? `[${opts.host}]` : opts.host;
+  const url = `http://${hostForUrl}:${port}/`;
+  const lines = [`jaato-web-coder-ui ${packageVersion()} serving ${opts.root}`, `  open      ${url}${wildcard ? "  (bound to all interfaces)" : ""}`, `  daemon    ${opts.daemon}`];
+  if (config.token) lines.push(`  token     from ${source}`);
+  else if (token && !loopback) lines.push(`  token     NOT handed to the page: ${opts.host} is not a loopback bind; type it in the form`);
+  else lines.push(`  token     none (${source}); type it in the form, or leave empty for --ws-unsafe-no-auth`);
+  process.stdout.write(lines.join("\n") + "\n");
+  if (opts.open) openBrowser(url);
+  return server;
+}
+
+// npm installs the bin as a symlink under node_modules/.bin, so argv[1]
+// must be resolved through the link before it can equal this module.
+function invokedDirectly() {
+  if (!process.argv[1]) return false;
+  try { return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url); }
+  catch { return false; }
+}
+const isMain = invokedDirectly();
+if (isMain) {
+  let opts;
+  try { opts = parseArgs(process.argv.slice(2)); }
+  catch (err) { process.stderr.write(`jaato-web-coder-ui: ${err.message}\n`); process.exit(2); }
+  main(opts).then((server) => {
+    if (!server) return;
+    const stop = () => server.close(() => process.exit(0));
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+  }).catch((err) => {
+    process.stderr.write(`jaato-web-coder-ui: ${err.message}\n`);
+    process.exit(1);
+  });
+}