mulmoterminal 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Receptron
+
+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

@@ -0,0 +1,420 @@
+# mulmoterminal
+
+A browser-based terminal for running [Claude Code](https://claude.com/claude-code)
+sessions, with a sidebar that lists the current project's chat sessions and shows
+live, hook-driven activity for each one.
+
+Each session runs as a real PTY on the server (`claude` in a pseudo-terminal) and
+is streamed to an [xterm.js](https://xtermjs.org/) terminal in the browser over a
+WebSocket. A sidebar lists every Claude session for the project and reflects, in
+real time, which sessions are **working** (Claude is thinking) and which **need
+attention** (waiting for input, or finished with output you haven't seen).
+
+---
+
+## Install & run
+
+Requires the [`claude`](https://claude.com/claude-code) CLI on your `PATH` and
+**Node ≥ 22.9**.
+
+```bash
+npx mulmoterminal           # start on http://localhost:3456 and open the browser
+# or install globally:
+npm install -g mulmoterminal
+mulmoterminal
+```
+
+Options: `--port <n>` (default 3456), `--no-open`, `--version`, `--help`.
+
+The published package ships the server (run via `tsx`) plus the pre-built web UI;
+`npx mulmoterminal` checks for the `claude` CLI, picks a free port, starts the
+server, and opens the browser. For local development from a clone, see
+[Running](#running).
+
+---
+
+## Contents
+
+- [Architecture](#architecture)
+- [Why a PTY?](#why-a-pty)
+- [Tech stack](#tech-stack)
+- [Configuration](#configuration)
+- [Running](#running)
+- [Server API specification](#server-api-specification)
+  - [HTTP: `GET /api/sessions`](#http-get-apisessions)
+  - [HTTP: `POST /api/hook`](#http-post-apihook)
+  - [WebSocket: `/ws` (terminal)](#websocket-ws-terminal)
+  - [Socket.IO: `/ws/pubsub` (activity pub/sub)](#socketio-wspubsub-activity-pubsub)
+- [Session model](#session-model)
+- [Session lifecycle](#session-lifecycle)
+- [Claude hook injection](#claude-hook-injection)
+- [Session discovery & titles](#session-discovery--titles)
+- [Project structure](#project-structure)
+- [Testing](#testing)
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────┐         ┌─────────────────────────────────────────────┐
+│ Browser (Vue 3 + xterm.js)            │         │ Server (Express + Node)                       │
+│                                       │         │                                               │
+│  Sidebar.vue ──subscribe("sessions")──┼──SIO───►│  socket.io  /ws/pubsub   ── publish ──┐       │
+│      ▲  refetch on any push           │         │                                       │       │
+│      └──── GET /api/sessions ─────────┼──HTTP──►│  Express   /api/sessions              │       │
+│                                       │         │            /api/hook  ◄──curl── hooks │       │
+│  Terminal.vue ── ws JSON msgs ────────┼──WS────►│  ws        /ws  ──► node-pty ─► `claude`──hooks┘
+│      (input / resize / output)        │         │                     (one PTY per session)     │
+└──────────────────────────────────────┘         └─────────────────────────────────────────────┘
+```
+
+- **Terminal I/O** flows over a raw WebSocket (`/ws`), one PTY per session.
+- **Session list** is fetched over HTTP (`/api/sessions`).
+- **Live activity** is pushed over a Socket.IO pub/sub channel (`/ws/pubsub`);
+  the server learns of activity from **Claude hooks** that POST to `/api/hook`.
+- The Vite dev server proxies `/ws`, `/ws/pubsub`, and `/api` to the backend;
+  in production the backend serves the built client from `dist/`.
+
+---
+
+## Why a PTY?
+
+Claude Code's interactive mode renders its UI with [Ink](https://github.com/vadimdemedes/ink)
+(a React-based TUI framework), which requires a real **TTY** to be attached. A
+plain `child_process.spawn()` provides no TTY, so interactive Claude won't start
+(it stays silent). [node-pty](https://github.com/microsoft/node-pty) allocates a
+real **pseudo-terminal** at the OS level, so from Claude's point of view it's
+running in an ordinary terminal — full TUI rendering, cursor movement, colors,
+and tool-approval prompts all work. We don't use `-p`/headless mode or the Agent
+SDK; we drive the real interactive CLI and relay its TTY over the WebSocket.
+
+> **macOS note:** node-pty's bundled `spawn-helper` binary ships without the
+> execute bit (mode 644), which causes a `posix_spawnp failed` error. The
+> `postinstall` script (`server/fix-pty-perms.js`) fixes it to 755 automatically.
+
+---
+
+## Tech stack
+
+| Layer    | Technology |
+| -------- | ---------- |
+| Frontend | Vue 3 (`<script setup>` + TypeScript), Vite, xterm.js (`@xterm/*`), socket.io-client |
+| Backend  | Node (ESM, TypeScript run via `tsx`), Express 5, `ws` (terminal WebSocket), `node-pty`, socket.io |
+| Tests    | Vitest + @vue/test-utils + jsdom |
+
+Requires **Node ≥ 22.9** (uses `node --env-file-if-exists`) and the `claude` CLI on `PATH`.
+
+---
+
+## Configuration
+
+The server is configured entirely through environment variables, optionally
+loaded from a `.env` file via `node --env-file-if-exists=.env` (wired into the
+npm scripts). The `.env` is optional — every variable below has a default, so
+the server runs without one.
+
+| Variable     | Default        | Description |
+| ------------ | -------------- | ----------- |
+| `PORT`       | `3456`         | HTTP/WebSocket port. |
+| `CLAUDE_BIN` | `claude`       | The Claude Code binary to spawn. |
+| `CLAUDE_CWD` | `$HOME`        | Working directory each `claude` PTY runs in. Determines which project's sessions the sidebar lists. **Must be an absolute path** — `~` is not expanded for values read from `.env`. |
+
+Example `.env` (gitignored):
+
+```
+CLAUDE_CWD=/Users/you/my-project
+```
+
+---
+
+## Running
+
+```bash
+yarn install            # postinstall fixes node-pty prebuilt binary perms
+
+yarn dev                # server (:3456) + Vite dev server, concurrently
+# or individually:
+yarn dev:server         # backend only  (node --import tsx --env-file-if-exists=.env server/index.ts)
+yarn dev:client         # Vite dev server only
+
+yarn build              # type-check (vue-tsc) + vite build -> dist/
+yarn typecheck:server   # type-check the server (tsconfig.server.json)
+yarn server             # run backend; serves dist/ + the APIs on :3456
+yarn test               # vitest run
+```
+
+The backend is TypeScript run directly via `tsx` (no build step); `server/` is
+type-checked separately through `tsconfig.server.json` (`strict`), kept out of
+the main `build` so the two type-check independently.
+
+In dev, open the Vite URL; its proxy forwards `/ws`, `/ws/pubsub`, and `/api` to
+`:3456`. In production, run `yarn build` then `yarn server` and open
+`http://localhost:3456`.
+
+---
+
+## Server API specification
+
+Base URL: `http://localhost:$PORT` (default `http://localhost:3456`).
+
+### HTTP: `GET /api/sessions`
+
+Lists the most-recent chat sessions for the current project (`CLAUDE_CWD`),
+newest first, including freshly-created sessions that aren't yet written to disk.
+
+**Response `200 application/json`**
+
+```jsonc
+{
+  "cwd": "/Users/you/my-project",
+  "sessions": [
+    {
+      "id": "d16f43f3-ef63-4a5e-b273-debaccb3522a", // session UUID (= .jsonl basename)
+      "title": "Review available skills list",        // see "Session discovery & titles"
+      "mtime": 1781471064511.22,                       // last-modified, ms epoch (sort key)
+      "working": false,                                // Claude is mid-turn (blue dot)
+      "waiting": false                                 // needs attention (bold)
+    }
+    // ...
+  ]
+}
+```
+
+- Sessions are read from `~/.claude/projects/<encoded CLAUDE_CWD>/*.jsonl` and
+  merged with in-memory sessions started this run but not yet persisted (those
+  have `title: "New session"` and `mtime` = creation time).
+- Sorted by `mtime` descending and capped at the **50** most recent. Files are
+  ranked by a cheap `stat`-only pass; only the top 50 are read and parsed for
+  titles, so the endpoint stays cheap regardless of how many sessions exist.
+- `500 { "error": string }` on an unexpected filesystem error. A missing project
+  directory is **not** an error — it yields an empty `sessions` array.
+
+### HTTP: `POST /api/hook`
+
+**Internal endpoint.** Claude hooks (injected per session — see
+[Claude hook injection](#claude-hook-injection)) POST their event payload here.
+You normally don't call this yourself.
+
+**Request `application/json`** — the Claude hook payload; only these fields are used:
+
+```jsonc
+{
+  "session_id": "d16f43f3-...",        // the session the event is for
+  "hook_event_name": "UserPromptSubmit" // "UserPromptSubmit" | "Stop" | "Notification"
+}
+```
+
+Effect (see [Session model](#session-model)):
+
+| `hook_event_name`  | Effect |
+| ------------------ | ------ |
+| `UserPromptSubmit` | `working = true` for the session. |
+| `Stop`             | `working = false`; if the session is **backgrounded**, also `waiting = true`. |
+| `Notification`     | If the session is **backgrounded**, `waiting = true`. |
+
+Any resulting state change is published on the `sessions` pub/sub channel.
+
+**Response `200 application/json`**: `{ "ok": true }` (always, even for unknown events).
+
+### WebSocket: `/ws` (terminal)
+
+A raw WebSocket carrying the terminal stream for one session. One PTY per
+connection (or reattach to an existing background PTY).
+
+**Connect**
+
+- `ws://host/ws` — start a **new** session (server generates a UUID and spawns
+  `claude --session-id <uuid> --settings <hooks>`).
+- `ws://host/ws?session=<id>` — **resume/reattach** a session. If a live
+  background PTY exists for `<id>`, the socket reattaches to it (and its recent
+  output buffer is replayed); otherwise the server spawns
+  `claude --resume <id> --settings <hooks>`.
+
+**Server → client** (JSON text frames):
+
+| Message | Meaning |
+| ------- | ------- |
+| `{ "type": "session", "id": string }` | Sent immediately on connect — the session id this socket is bound to (lets the client learn a new session's generated id). |
+| `{ "type": "output", "data": string }` | PTY output to write to the terminal. On reattach, the first `output` frame is the replayed tail buffer (≤ 64 KB). |
+| `{ "type": "exit", "exitCode": number, "signal": number }` | The `claude` process exited; the socket then closes. |
+
+**Client → server** (JSON text frames):
+
+| Message | Meaning |
+| ------- | ------- |
+| `{ "type": "input", "data": string }` | Keystrokes / bytes to write to the PTY. |
+| `{ "type": "resize", "cols": number, "rows": number }` | Resize the PTY. |
+
+A non-JSON frame is written to the PTY verbatim (fallback).
+
+**Disconnect** — when the socket closes, if Claude is still `working` the PTY is
+**kept alive** in the background; otherwise it's killed. See
+[Session lifecycle](#session-lifecycle).
+
+### Socket.IO: `/ws/pubsub` (activity pub/sub)
+
+A minimal Socket.IO pub/sub for live session-activity updates. Channel names are
+Socket.IO rooms.
+
+- **Path**: `/ws/pubsub`, transport: `websocket`.
+- **Client → server events**:
+  - `subscribe` with a channel name (string) → join the room.
+  - `unsubscribe` with a channel name (string) → leave the room.
+- **Server → client event**: `data` with `{ channel: string, data: <payload> }`.
+
+**Channel `"sessions"`** — payloads describe a single session change:
+
+```jsonc
+// activity change (working/waiting flipped)
+{ "id": "d16f43f3-...", "working": false, "waiting": true, "event": "Stop" }
+
+// a brand-new session was created
+{ "id": "…", "working": false, "event": "created" }
+
+// a session's PTY was closed/reaped
+{ "id": "…", "working": false, "event": "closed" }
+```
+
+`event` is the originating hook (`UserPromptSubmit` | `Stop` | `Notification`) or
+a lifecycle marker (`created` | `closed` | `null`). The client treats **any**
+`sessions` message as a signal to refetch `GET /api/sessions` (the server is the
+single source of truth for the list), so payload details are advisory.
+
+---
+
+## Session model
+
+Per-session state lives on the server (`activity` map) and is surfaced as two
+booleans on every session record:
+
+| Flag      | Set when | Cleared when | UI |
+| --------- | -------- | ------------ | -- |
+| `working` | `UserPromptSubmit` hook fires (Claude started a turn) | `Stop` hook fires (turn finished) | **Blue dot** next to the title |
+| `waiting` | A **background** session fires `Notification` (waiting for input — permission / question / idle) **or** `Stop` (finished, output unseen, ready for another message) | The session is brought to the **foreground** (a WebSocket attaches to it) | **Bold** title |
+
+"Foreground" = a session that currently has an attached terminal WebSocket (the
+one you're viewing). `waiting` is only ever set for **background** sessions,
+because a foreground session is already on screen.
+
+---
+
+## Session lifecycle
+
+```
+        new ws /ws                         ws /ws?session=<id>
+            │                                      │
+            ▼                                      ▼
+   generate UUID, spawn               live bg PTY?  ──yes──►  reattach + replay buffer
+   claude --session-id <uuid>              │ no
+   register "New session",                 ▼
+   publish "created"               spawn claude --resume <id>
+            │                                      │
+            └───────────────┬──────────────────────┘
+                            ▼
+                   attached (foreground)  ── setWaiting(false) ──► not bold
+                            │
+              ws close (switch away / disconnect)
+                            │
+            ┌───────── working? ──────────┐
+           yes                            no
+            │                             │
+   keep PTY alive (background)        kill PTY (reap), publish "closed"
+            │
+   Stop hook in background:
+   waiting=true (bold), working=false, reap PTY
+   (flag persists via on-disk record → stays listed & bold until viewed)
+```
+
+Key rules:
+
+- **Switching away never interrupts Claude mid-turn** — a `working` session's PTY
+  survives in the background.
+- A background session that goes **idle** (`Stop`) is **reaped** (killed). If it
+  finished with unseen output, its `waiting` flag persists via the on-disk
+  session record, so it stays listed and **bold** until you open it.
+- **Reattach over respawn**: selecting a session that still has a live background
+  PTY reattaches to it (replaying a ≤ 64 KB output tail) instead of spawning a
+  duplicate `claude`.
+- Brand-new sessions appear in the sidebar **immediately** (before their `.jsonl`
+  exists) via the in-memory `knownSessions` registry + a `created` push; an
+  unused one disappears when its PTY is reaped.
+
+---
+
+## Claude hook injection
+
+Activity is detected via Claude Code hooks injected **per spawn**, without
+touching the user's `~/.claude/settings.json` or project settings. The server
+passes `claude --settings '<json>'` where the JSON registers a command hook for
+`UserPromptSubmit`, `Stop`, and `Notification`, each of which pipes the hook
+payload to the server:
+
+```jsonc
+{
+  "hooks": {
+    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "curl -s -X POST http://localhost:$PORT/api/hook -H 'content-type: application/json' -d @-" }] }],
+    "Stop":             [{ "hooks": [{ "type": "command", "command": "curl … -d @-" }] }],
+    "Notification":     [{ "hooks": [{ "type": "command", "command": "curl … -d @-" }] }]
+  }
+}
+```
+
+Because the server spawns each new session with `--session-id <uuid>`, it always
+knows the live session's id — even before the session's `.jsonl` file exists.
+
+---
+
+## Session discovery & titles
+
+Claude stores each project's sessions as JSONL files under
+`~/.claude/projects/<encoded-cwd>/<session-id>.jsonl`, where the absolute `cwd`
+has its `/` and `.` characters replaced with `-` (e.g.
+`/Users/you/proj` → `-Users-you-proj`).
+
+A session's display **title** is derived by scanning its JSONL for, in order of
+preference:
+
+1. the latest `ai-title` record's `aiTitle`,
+2. else the latest `last-prompt` record's `lastPrompt`,
+3. else the first real user message (slash/local-command wrappers like
+   `<local-command-…>` are skipped),
+4. else `"(untitled session)"`.
+
+In-memory sessions not yet persisted show as `"New session"` until their file
+appears, at which point the on-disk title takes over.
+
+---
+
+## Project structure
+
+```
+server/
+  index.js        Express app, /api routes, terminal WebSocket, PTY lifecycle,
+                  session state, hook injection, session discovery
+  pubsub.js       createPubSub(server) — socket.io pub/sub at /ws/pubsub
+  fix-pty-perms.js  postinstall: fixes node-pty prebuilt binary permissions
+src/
+  App.vue         Layout (sidebar + terminal); owns the active session id
+  components/
+    Sidebar.vue       Session list; working dot + waiting bold; pub/sub driven
+    Sidebar.spec.ts   Vitest component tests
+    Terminal.vue      xterm.js terminal; /ws connection, reconnect on switch
+  composables/
+    usePubSub.ts      socket.io-client pub/sub composable (subscribe/unsubscribe)
+vite.config.ts    Dev proxy for /ws, /ws/pubsub, /api
+vitest.config.ts  jsdom test environment
+```
+
+---
+
+## Testing
+
+```bash
+yarn test
+```
+
+`src/components/Sidebar.spec.ts` covers the sidebar: rendering the server's
+session list, the working dot, the `waiting` bold state, refetching on a pub/sub
+push, and emitting `select` on click. The pub/sub composable and `fetch` are
+mocked so the tests run without a server.

package/bin/mulmoterminal.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+
+// MulmoTerminal launcher — `npx mulmoterminal` entry point.
+//
+// Ships the server source (TypeScript) + a pre-built client (Vite dist/), and
+// runs the server via tsx. Mirrors the mulmoclaude launcher.
+
+import { execSync, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { get as httpGet } from "node:http";
+import { createRequire } from "node:module";
+import { createServer } from "node:net";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_DIR = join(__dirname, "..");
+const SERVER_ENTRY = join(PKG_DIR, "server", "index.ts");
+const DEFAULT_PORT = 3456;
+const READY_TIMEOUT_MS = 15_000;
+const MAX_PORT_PROBES = 20;
+
+// Single source of truth: read the version from the shipped package.json so
+// `--version` never drifts from the published version.
+const { version: VERSION } = createRequire(import.meta.url)("../package.json");
+
+const log = (msg) => console.log(`\x1b[36m[mulmoterminal]\x1b[0m ${msg}`);
+const error = (msg) => console.error(`\x1b[31m[mulmoterminal]\x1b[0m ${msg}`);
+
+function claudeInstalled() {
+  try {
+    // Intentionally resolves `claude` from the user's PATH — detecting their
+    // Claude Code CLI install is the whole point of this pre-flight check.
+    // eslint-disable-next-line sonarjs/no-os-command-from-path
+    execSync("claude --version", { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function pickOpenCommand() {
+  if (process.platform === "darwin") return "open";
+  if (process.platform === "win32") return "start";
+  return "xdg-open";
+}
+
+// Resolve with true if nothing is listening on `port`, false otherwise.
+function isPortFree(port) {
+  return new Promise((resolve) => {
+    const probe = createServer();
+    probe.once("error", () => resolve(false));
+    probe.once("listening", () => probe.close(() => resolve(true)));
+    probe.listen(port, "127.0.0.1");
+  });
+}
+
+async function findAvailablePort(start) {
+  for (let port = start; port < start + MAX_PORT_PROBES; port++) {
+    if (await isPortFree(port)) return port;
+  }
+  return null;
+}
+
+// Poll the server until it answers, then call onReady; give up after the timeout
+// so the launcher never hangs on a crash loop.
+function waitUntilReady(port, onReady) {
+  const startedAt = Date.now();
+  const attempt = () => {
+    const req = httpGet({ host: "127.0.0.1", port, path: "/", timeout: 1000 }, (res) => {
+      res.resume();
+      onReady();
+    });
+    req.on("error", retry);
+    req.on("timeout", () => {
+      req.destroy();
+      retry();
+    });
+  };
+  const retry = () => {
+    if (Date.now() - startedAt > READY_TIMEOUT_MS) return;
+    setTimeout(attempt, 300);
+  };
+  attempt();
+}
+
+function printReadyBanner(url) {
+  const bar = "\x1b[32m" + "─".repeat(48) + "\x1b[0m";
+  console.log(`\n${bar}`);
+  console.log(`\x1b[32m  ✓ MulmoTerminal is ready\x1b[0m`);
+  console.log(`\x1b[32m  → ${url}\x1b[0m`);
+  console.log(`\x1b[32m  Press Ctrl+C to stop.\x1b[0m`);
+  console.log(`${bar}\n`);
+}
+
+function parsePortArg(args) {
+  const idx = args.indexOf("--port");
+  if (idx === -1) return { requestedPort: DEFAULT_PORT, portExplicit: false };
+  const raw = args[idx + 1];
+  const parsed = Number.parseInt(raw ?? "", 10);
+  if (!Number.isInteger(parsed) || String(parsed) !== raw || parsed < 1 || parsed > 65535) {
+    error(`Invalid --port value: "${raw ?? ""}" (expected integer 1..65535)`);
+    process.exit(1);
+  }
+  return { requestedPort: parsed, portExplicit: true };
+}
+
+async function choosePort(requested, explicit) {
+  if (await isPortFree(requested)) return requested;
+  if (explicit) {
+    error(`Port ${requested} is already in use. Stop the other process or pick a different --port.`);
+    process.exit(1);
+  }
+  const fallback = await findAvailablePort(requested + 1);
+  if (fallback === null) {
+    error(`Port ${requested} is in use and no free port found nearby.`);
+    process.exit(1);
+  }
+  log(`Port ${requested} busy → using ${fallback} instead. (Pass --port <N> to pin.)`);
+  return fallback;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(`
+Usage: npx mulmoterminal [options]
+
+Options:
+  --port <number>   Server port (default: ${DEFAULT_PORT})
+  --no-open         Don't open the browser automatically
+  --version         Show version
+  --help            Show this help
+`);
+    return;
+  }
+  if (args.includes("--version")) {
+    console.log(`mulmoterminal ${VERSION}`);
+    return;
+  }
+
+  if (!claudeInstalled()) {
+    error("Claude Code CLI not found.");
+    error("Install it first:  npm install -g @anthropic-ai/claude-code  &&  claude auth login");
+    process.exit(1);
+  }
+  log("Claude Code CLI ✓");
+
+  if (!existsSync(SERVER_ENTRY)) {
+    error(`Server entry not found at ${SERVER_ENTRY}`);
+    process.exit(1);
+  }
+
+  const { requestedPort, portExplicit } = parsePortArg(args);
+  const port = await choosePort(requestedPort, portExplicit);
+
+  log(`Starting MulmoTerminal on port ${port}...`);
+  const server = spawn(process.execPath, ["--import", "tsx", SERVER_ENTRY], {
+    cwd: PKG_DIR,
+    env: { ...process.env, NODE_ENV: "production", PORT: String(port) },
+    stdio: "inherit",
+  });
+
+  const url = `http://localhost:${port}`;
+  const noOpen = args.includes("--no-open");
+  waitUntilReady(port, () => {
+    printReadyBanner(url);
+    if (noOpen) return;
+    try {
+      // The command is a hardcoded literal; url is http://localhost:<numeric port>.
+      // eslint-disable-next-line sonarjs/os-command
+      execSync(`${pickOpenCommand()} ${url}`, { stdio: "pipe" });
+    } catch {
+      log(`Open your browser: ${url}`);
+    }
+  });
+
+  const shutdown = () => {
+    server.kill("SIGTERM");
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+  server.on("exit", (code) => process.exit(code ?? 1));
+}
+
+main();

package/dist/assets/index-Bhcnvx68.css

@@ -0,0 +1 @@
+*{box-sizing:border-box;margin:0;padding:0}body{background:#1a1a2e;overflow:hidden}.chip[data-v-0d423d77]{color:#9aa5c4;cursor:pointer;background:#1b2647;border:1px solid #2a2a4e;border-radius:9999px;align-items:center;padding:2px 10px;font-size:11px;line-height:16px;transition:background .12s,color .12s,border-color .12s;display:inline-flex}.chip[data-v-0d423d77]:hover{color:#cfe0ff;background:#224a86}.chip.active[data-v-0d423d77]{color:#fff;background:#2563eb;border-color:#2563eb}.sidebar[data-v-65add4c2]{color:#e0e0e0;background:#16213e;border-right:1px solid #2a2a4e;flex-direction:column;flex-shrink:0;width:260px;font-family:system-ui,sans-serif;display:flex;overflow:hidden}.sidebar-header[data-v-65add4c2]{justify-content:space-between;align-items:center;padding:10px 14px;display:flex}.heading[data-v-65add4c2]{text-transform:uppercase;letter-spacing:.05em;color:#9aa5c4;font-size:13px;font-weight:600}.icon-btn[data-v-65add4c2]{color:#9aa5c4;cursor:pointer;background:0 0;border:none;font-size:16px;line-height:1}.icon-btn[data-v-65add4c2]:hover{color:#e0e0e0}.new-btn[data-v-65add4c2]{color:#cfe0ff;cursor:pointer;background:#1b3a6b;border:none;border-radius:6px;margin:0 12px 8px;padding:8px;font-size:13px}.new-btn[data-v-65add4c2]:hover{background:#224a86}.filters[data-v-65add4c2]{align-items:center;gap:6px;padding:0 12px 8px;display:flex}.sort-btn[data-v-65add4c2]{margin-left:auto;font-size:14px}.state[data-v-65add4c2]{color:#9aa5c4;padding:12px 14px;font-size:13px}.state.error[data-v-65add4c2]{color:#ef9a9a}.list[data-v-65add4c2]{flex:1;margin:0;padding:0;list-style:none;overflow-y:auto}.item[data-v-65add4c2]{cursor:pointer;border-left:3px solid #0000;flex-direction:column;gap:2px;padding:10px 14px;display:flex}.item[data-v-65add4c2]:hover{background:#1d2b4e}.item.active[data-v-65add4c2]{background:#1d2b4e;border-left-color:#4a8cff}.item-title[data-v-65add4c2]{white-space:nowrap;text-overflow:ellipsis;font-size:13px;overflow:hidden}.item.waiting .item-title[data-v-65add4c2]{color:#fff;font-weight:700}.spinner[data-v-65add4c2]{vertical-align:middle;border:2px solid #4a8cff4d;border-top-color:#4a8cff;border-radius:50%;width:10px;height:10px;margin-right:5px;animation:.9s linear infinite sidebar-spin-65add4c2;display:inline-block}@keyframes sidebar-spin-65add4c2{to{transform:rotate(360deg)}}.item-time[data-v-65add4c2]{color:#7c87a8;font-size:11px}.tabbar[data-v-09487b28]{color:#e0e0e0;background:#16213e;border-bottom:1px solid #2a2a4e;flex-shrink:0;align-items:center;gap:8px;height:40px;padding:0 10px;font-family:system-ui,sans-serif;display:flex;overflow:hidden}.new-btn[data-v-09487b28]{color:#cfe0ff;cursor:pointer;background:#1b3a6b;border:none;border-radius:6px;flex-shrink:0;width:26px;height:26px;font-size:16px;line-height:1}.new-btn[data-v-09487b28]:hover{background:#224a86}.filters[data-v-09487b28]{flex-shrink:0;align-items:center;gap:6px;display:flex}.sort-btn[data-v-09487b28]{font-size:14px}.tabs[data-v-09487b28]{flex:1;gap:6px;min-width:0;display:flex;overflow:hidden}.tab[data-v-09487b28]{color:#cdd5ee;cursor:pointer;background:0 0;border:1px solid #0000;border-radius:6px;flex:1 1 0;align-items:center;gap:5px;min-width:0;max-width:200px;height:28px;padding:0 10px;font-size:12px;transition:background .12s;display:flex;position:relative}.tab[data-v-09487b28]:hover{background:#1d2b4e}.tab.active[data-v-09487b28]{background:#1d2b4e;border-color:#4a8cff}.tab-title[data-v-09487b28]{white-space:nowrap;text-overflow:ellipsis;overflow:hidden}.tab.waiting .tab-title[data-v-09487b28]{color:#fff;font-weight:700}.unread-dot[data-v-09487b28]{background:#ef4444;border-radius:50%;flex-shrink:0;width:7px;height:7px;box-shadow:0 0 0 2px #16213e}.spinner[data-v-09487b28]{border:2px solid #4a8cff4d;border-top-color:#4a8cff;border-radius:50%;flex-shrink:0;width:10px;height:10px;animation:.9s linear infinite tabbar-spin-09487b28}@keyframes tabbar-spin-09487b28{to{transform:rotate(360deg)}}.actions[data-v-09487b28]{flex-shrink:0;align-items:center;gap:8px;display:flex}.icon-btn[data-v-09487b28]{color:#9aa5c4;cursor:pointer;background:0 0;border:none;font-size:16px;line-height:1}.icon-btn[data-v-09487b28]:hover{color:#e0e0e0}.xterm{cursor:text;-webkit-user-select:none;user-select:none;position:relative}.xterm.focus,.xterm:focus{outline:none}.xterm .xterm-helpers{z-index:5;position:absolute;top:0}.xterm .xterm-helper-textarea{opacity:0;z-index:-5;white-space:nowrap;resize:none;border:0;width:0;height:0;margin:0;padding:0;position:absolute;top:0;left:-9999em;overflow:hidden}.xterm .composition-view{color:#fff;white-space:nowrap;z-index:1;background:#000;display:none;position:absolute}.xterm .composition-view.active{display:block}.xterm .xterm-viewport{cursor:default;background-color:#000;position:absolute;inset:0;overflow-y:scroll}.xterm .xterm-screen{position:relative}.xterm .xterm-screen canvas{position:absolute;top:0;left:0}.xterm-char-measure-element{visibility:hidden;line-height:normal;display:inline-block;position:absolute;top:0;left:-9999em}.xterm.enable-mouse-events{cursor:default}.xterm.xterm-cursor-pointer,.xterm .xterm-cursor-pointer{cursor:pointer}.xterm.column-select.focus{cursor:crosshair}.xterm .xterm-accessibility:not(.debug),.xterm .xterm-message{z-index:10;color:#0000;pointer-events:none;position:absolute;inset:0}.xterm .xterm-accessibility-tree:not(.debug) ::selection{color:#0000}.xterm .xterm-accessibility-tree{-webkit-user-select:text;user-select:text;white-space:pre;font-family:monospace}.xterm .xterm-accessibility-tree>div{transform-origin:0;width:fit-content}.xterm .live-region{width:1px;height:1px;position:absolute;left:-9999px;overflow:hidden}.xterm-dim{opacity:1!important}.xterm-underline-1{text-decoration:underline}.xterm-underline-2{-webkit-text-decoration:underline double;text-decoration:underline double}.xterm-underline-3{-webkit-text-decoration:underline wavy;text-decoration:underline wavy}.xterm-underline-4{-webkit-text-decoration:underline dotted;text-decoration:underline dotted}.xterm-underline-5{-webkit-text-decoration:underline dashed;text-decoration:underline dashed}.xterm-overline{text-decoration:overline}.xterm-overline.xterm-underline-1{text-decoration:underline overline}.xterm-overline.xterm-underline-2{-webkit-text-decoration:overline double underline;text-decoration:overline double underline}.xterm-overline.xterm-underline-3{-webkit-text-decoration:overline wavy underline;text-decoration:overline wavy underline}.xterm-overline.xterm-underline-4{-webkit-text-decoration:overline dotted underline;text-decoration:overline dotted underline}.xterm-overline.xterm-underline-5{-webkit-text-decoration:overline dashed underline;text-decoration:overline dashed underline}.xterm-strikethrough{text-decoration:line-through}.xterm-screen .xterm-decoration-container .xterm-decoration{z-index:6;position:absolute}.xterm-screen .xterm-decoration-container .xterm-decoration.xterm-decoration-top-layer{z-index:7}.xterm-decoration-overview-ruler{z-index:8;pointer-events:none;position:absolute;top:0;right:0}.xterm-decoration-top{z-index:2;position:relative}.xterm .xterm-scrollable-element>.scrollbar{cursor:default}.xterm .xterm-scrollable-element>.scrollbar>.scra{cursor:pointer;font-size:11px!important}.xterm .xterm-scrollable-element>.visible{opacity:1;z-index:11;background:0 0;transition:opacity .1s linear}.xterm .xterm-scrollable-element>.invisible{opacity:0;pointer-events:none}.xterm .xterm-scrollable-element>.invisible.fade{transition:opacity .8s linear}.xterm .xterm-scrollable-element>.shadow{display:none;position:absolute}.xterm .xterm-scrollable-element>.shadow.top{width:100%;height:3px;box-shadow:var(--vscode-scrollbar-shadow,#000) 0 6px 6px -6px inset;display:block;top:0;left:3px}.xterm .xterm-scrollable-element>.shadow.left{width:3px;height:100%;box-shadow:var(--vscode-scrollbar-shadow,#000) 6px 0 6px -6px inset;display:block;top:3px;left:0}.xterm .xterm-scrollable-element>.shadow.top-left-corner{width:3px;height:3px;display:block;top:0;left:0}.xterm .xterm-scrollable-element>.shadow.top.left{box-shadow:var(--vscode-scrollbar-shadow,#000) 6px 0 6px -6px inset}.terminal-wrapper[data-v-0a7d9e9b]{background:#1a1a2e;flex-direction:column;flex:1;min-width:0;height:100%;display:flex}.header[data-v-0a7d9e9b]{color:#e0e0e0;background:#16213e;align-items:center;gap:12px;padding:8px 16px;font-family:system-ui,sans-serif;font-size:14px;display:flex}.title[data-v-0a7d9e9b]{font-weight:600}.status[data-v-0a7d9e9b]{border-radius:4px;padding:2px 8px;font-size:12px}.status.connected[data-v-0a7d9e9b]{color:#a5d6a7;background:#1b5e20}.status.connecting[data-v-0a7d9e9b]{color:#ffcc80;background:#e65100}.status.disconnected[data-v-0a7d9e9b]{color:#ef9a9a;background:#b71c1c}.terminal-container[data-v-0a7d9e9b]{flex:1;padding:4px}.plugin-frame-host[data-v-5e7324b3]{display:block}.gui-panel[data-v-51ab822d]{background:#11162a;border-left:1px solid #2a2a4e;flex-direction:column;flex:1;min-width:0;height:100%;display:flex}.header[data-v-51ab822d]{color:#e0e0e0;background:#16213e;justify-content:space-between;align-items:center;padding:8px 16px;font-family:system-ui,sans-serif;font-size:14px;display:flex}.title[data-v-51ab822d]{font-weight:600}.gear[data-v-51ab822d]{color:#7c87a8;cursor:pointer;background:0 0;border:none;border-radius:4px;padding:2px 4px;font-size:15px;line-height:1}.gear[data-v-51ab822d]:hover{color:#e0e0e0}.gear.active[data-v-51ab822d]{color:#4a8cff}.content[data-v-51ab822d]{color:#e0e0e0;flex:1;padding:12px 16px;font-family:system-ui,sans-serif;font-size:14px;line-height:1.5;overflow-y:auto}.empty[data-v-51ab822d]{color:#7c87a8;font-size:13px}.empty code[data-v-51ab822d]{background:#1d2b4e;border-radius:4px;padding:1px 5px}.frame+.frame[data-v-51ab822d]{border-top:1px solid #2a2a4e;margin-top:16px;padding-top:16px}.tools-pane[data-v-167cc06d]{background:#0d1124;border-left:1px solid #2a2a4e;flex-direction:column;flex-shrink:0;width:340px;height:100%;display:flex}.header[data-v-167cc06d]{color:#e0e0e0;background:#16213e;padding:8px 16px;font-family:system-ui,sans-serif;font-size:14px}.title[data-v-167cc06d]{font-weight:600}.content[data-v-167cc06d]{color:#e0e0e0;flex:1;font-family:system-ui,sans-serif;font-size:13px;overflow-y:auto}.section[data-v-167cc06d]{border-bottom:1px solid #2a2a4e;padding:10px 12px}.section-title[data-v-167cc06d]{text-transform:uppercase;letter-spacing:.04em;color:#7c87a8;margin-bottom:8px;font-size:11px;font-weight:700}.section-title--with-action[data-v-167cc06d]{justify-content:space-between;align-items:center;gap:8px;display:flex}.copy-history[data-v-167cc06d]{text-transform:none;letter-spacing:.02em;color:#9aa5c4;cursor:pointer;background:#1d2b4e;border:1px solid #2a2a4e;border-radius:4px;padding:2px 8px;font-size:10px;font-weight:600;transition:color .15s,background .15s}.copy-history[data-v-167cc06d]:hover:not(:disabled){color:#cfe0ff;background:#243763}.copy-history[data-v-167cc06d]:disabled{opacity:.4;cursor:not-allowed}.muted[data-v-167cc06d]{color:#7c87a8;font-size:12px}.italic[data-v-167cc06d]{font-style:italic}.tool+.tool[data-v-167cc06d]{margin-top:4px}.tool-head[data-v-167cc06d],.call-head[data-v-167cc06d]{cursor:pointer;text-align:left;width:100%;color:inherit;background:0 0;border:none;justify-content:space-between;align-items:center;gap:8px;padding:4px 0;display:flex}.tool-name[data-v-167cc06d],.call-name[data-v-167cc06d]{color:#cfe0ff;word-break:break-all;background:#1d2b4e;border-radius:4px;padding:2px 6px;font-family:JetBrains Mono,monospace;font-size:12px}.caret[data-v-167cc06d]{color:#7c87a8;font-size:10px}.tool-desc[data-v-167cc06d]{color:#9aa5c4;white-space:pre-wrap;margin:2px 0 6px;font-size:12px}.call[data-v-167cc06d]{background:#11162a;border:1px solid #2a2a4e;border-radius:6px;margin-top:6px;padding:6px 8px}.call-meta[data-v-167cc06d]{flex-shrink:0;align-items:center;gap:8px;display:flex}.badge[data-v-167cc06d]{border-radius:999px;padding:1px 6px;font-size:10px}.badge.running[data-v-167cc06d]{color:#ffcc80;background:#4a3a10}.badge.done[data-v-167cc06d]{color:#a5d6a7;background:#14361c}.badge.failed[data-v-167cc06d]{color:#ef9a9a;background:#4a1414}.time[data-v-167cc06d]{color:#6b769a;font-variant-numeric:tabular-nums;font-size:11px}.call-body[data-v-167cc06d]{margin-top:6px}.label[data-v-167cc06d]{text-transform:uppercase;letter-spacing:.04em;color:#7c87a8;margin:6px 0 2px;font-size:10px}.block[data-v-167cc06d]{white-space:pre-wrap;word-break:break-word;background:#0a0e1f;border:1px solid #20284a;border-radius:4px;max-height:220px;margin:0;padding:6px 8px;font-family:JetBrains Mono,monospace;font-size:11.5px;overflow:auto}.block.result[data-v-167cc06d]{border-color:#1c3a24}.block.error[data-v-167cc06d]{color:#ef9a9a;border-color:#4a1414}.app[data-v-be189b61]{width:100vw;height:100vh;display:flex;overflow:hidden}.app-vertical[data-v-be189b61]{flex-direction:row}.app-horizontal[data-v-be189b61]{flex-direction:column}.main[data-v-be189b61]{flex:1;min-width:0;min-height:0;display:flex}.terminal-pane[data-v-be189b61]{min-width:0}.splitter[data-v-be189b61]{cursor:col-resize;background:#16213e;border-left:1px solid #2a2a4e;border-right:1px solid #2a2a4e;flex:0 0 5px}.splitter[data-v-be189b61]:hover{background:#2a3b66}.splitter[data-v-be189b61]:focus-visible{background:#4a8cff;outline:none}