mulmoterminal 0.4.0 → 0.5.0

package/README.md

@@ -25,7 +25,7 @@ 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
+npx mulmoterminal           # start on http://localhost:34567 and open the browser
 # or install globally:
 npm install -g mulmoterminal
 mulmoterminal
@@ -36,7 +36,7 @@ prints a one-line notice when a newer version is available (`npm i -g mulmotermi
 to update). Disable with `MULMOTERMINAL_NO_UPDATE_CHECK=1` (or `NO_UPDATE_NOTIFIER=1`).
 
 Options: `--cwd <dir>` (working directory — relative paths allowed; defaults to the
-directory you run the command from), `--port <n>` (default 3456), `--no-open`,
+directory you run the command from), `--port <n>` (default 34567), `--no-open`,
 `--version`, `--help`.
 
 ```bash
@@ -96,8 +96,11 @@ server, and opens the browser. For local development from a clone, see
 - **Script commands** (`yarn dev`, tests, …), launched from a cell's directory
   picker, run in their own ephemeral PTY over a separate WebSocket (`/ws/run`);
   they are not Claude sessions. See [Scripts (Run menu)](#scripts-run-menu).
-- The Vite dev server proxies `/ws` (covers `/ws/run`), `/ws/pubsub`, and `/api` to
-  the backend; in production the backend serves the built client from `dist/`.
+- In dev (`yarn dev`) the Vite dev server runs on its own port (`CLIENT_PORT`,
+  default `6856`) and proxies `/ws` (covers `/ws/run`), `/ws/pubsub`, and `/api` to
+  the backend (`PORT`, default `34567`) — so you open the Vite port (e.g.
+  `http://localhost:6856`). In production the backend serves the built client from
+  `dist/` on `PORT`, and you open that.
 
 ---
 
@@ -139,7 +142,8 @@ the server runs without one.
 
 | Variable     | Default        | Description |
 | ------------ | -------------- | ----------- |
-| `PORT`       | `3456`         | HTTP/WebSocket port. |
+| `PORT`        | `34567`        | Backend HTTP/WebSocket port (prod: the URL you open). |
+| `CLIENT_PORT` | `6856`         | Vite dev-server port (dev only: the URL you open with `yarn dev`). |
 | `CLAUDE_BIN` | `claude`       | The Claude Code binary to spawn. |
 | `CLAUDE_CWD` | current dir    | Working directory each `claude` PTY runs in; determines which project's sessions the sidebar lists. Via `npx mulmoterminal` it defaults to the directory you ran the command from (override with `--cwd <dir>`, relative allowed); when the server is run directly it falls back to `~/mulmoclaude`. A value read from `.env` must be an absolute path (`~` is not expanded). |
 
@@ -166,6 +170,37 @@ chime) or in the config file; the server streams that file at `GET /api/sound` a
 the client decodes it (falling back to the chime if it's missing or not audio). It's
 your own local file referenced by absolute path — nothing is added to the package.
 
+### Per-directory settings (`<project>/.mulmoterminal.json`)
+
+Drop a `.mulmoterminal.json` in a project directory to give terminals opened **in
+that directory** their own look and sound. It applies per terminal (per grid cell) —
+the rest of the app keeps your chosen theme — and a directory's theme overrides your
+manual theme pick for that terminal only. Every field is optional; a missing or
+malformed file is ignored.
+
+```jsonc
+{
+  "name": "PROD · payments",            // badge shown on this directory's terminals
+  "badgeColor": "#cf222e",              // badge color (hex #rrggbb)
+  "theme": "nord",                      // terminal palette: midnight | nord | daylight | solarized
+  "colors": { "background": "#190a23", "cursor": "#ff2e63" }, // per-key palette overrides
+  "sound": "./.mulmoterminal/alert.mp3" // attention sound, RELATIVE to this directory
+}
+```
+
+| Field        | Meaning |
+| ------------ | ------- |
+| `name`       | Label shown as a badge in the terminal/cell header. |
+| `badgeColor` | Badge background color (`#rrggbb`); text auto-contrasts. |
+| `theme`      | xterm palette for terminals in this directory (one of the built-in theme ids). |
+| `colors`     | Per-key xterm palette overrides applied on top of `theme` (or the app theme when `theme` is unset). Keys are xterm `ITheme` names (`background`, `foreground`, `cursor`, `selectionBackground`, the 16 ANSI colors, …); values are hex (`#rgb` / `#rrggbb` / `#rrggbbaa`). Unknown keys / bad values are dropped. |
+| `sound`      | Attention sound for this directory's sessions, a path **relative to the directory** (served at `GET /api/dir-sound`). |
+
+**Security.** `sound` is a directory-relative path only — absolute paths and any
+`../` that escapes the directory are rejected, and the path is never taken from the
+HTTP request, so an opened project can't point the player at arbitrary files.
+Changes take effect when the terminal is next opened (no live file watch).
+
 ---
 
 ## Running
@@ -173,14 +208,14 @@ your own local file referenced by absolute path — nothing is added to the pack
 ```bash
 yarn install            # postinstall fixes node-pty prebuilt binary perms
 
-yarn dev                # server (:3456) + Vite dev server, concurrently
+yarn dev                # backend (:34567) + Vite UI (:6856), concurrently — open http://localhost:6856
 # 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 server             # run backend; serves dist/ + the APIs on :34567
 yarn test               # vitest run
 ```
 
@@ -189,8 +224,8 @@ 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`.
+`:34567`. In production, run `yarn build` then `yarn server` and open
+`http://localhost:34567`.
 
 ---
 
@@ -245,7 +280,7 @@ command, so the file is the allowlist of what can run.
 
 ## Server API specification
 
-Base URL: `http://localhost:$PORT` (default `http://localhost:3456`).
+Base URL: `http://localhost:$PORT` (default `http://localhost:34567`).
 
 ### HTTP: `GET /api/sessions`
 
@@ -468,6 +503,12 @@ Key rules:
 - **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`.
+- **One live viewer per session**: a session is bound to a single socket. Opening
+  it in a second place (another tab, or another grid cell pointed at the same dir)
+  reattaches there and **supersedes** the first, which detaches. To avoid doing
+  this by accident, a grid launcher's resume list **flags rows already open in
+  another terminal** (`● open`) and **asks for confirmation** before taking one
+  over.
 - 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.
@@ -534,9 +575,10 @@ src/
     Sidebar.vue       Session list; working dot + waiting bold; pub/sub driven
     Sidebar.spec.ts   Vitest component tests
     Terminal.vue      xterm.js terminal; /ws (or /ws/run); single-view ▶ Run menu
-    GridView.vue      Grid toolbar (auto-layout, ＋ Terminal); runs handed-off scripts
+    AppToolbar.vue    Shared header (single + grid); grid-only ＋ Terminal + ⇅/↔ cell-order toggle
+    GridView.vue      Grid view: auto-layout, pages, manual/auto cell order; runs handed-off scripts
     RunMenu.vue       ▶ Run dropdown: lists a dir's script.json, emits the pick
-    TerminalCell.vue  A cell: Claude launcher (dir picker + resume + run-a-script)
+    TerminalCell.vue  A cell: Claude launcher (dir picker + resume + run-a-script); ◀▶ to reorder
     TerminalGrid.vue  Grid of cells; auto-sizes by count; zoom lines up every tab
     CommandCell.vue   A grid cell that runs a script.json command (ephemeral)
   composables/

package/bin/mulmoterminal.js

@@ -17,7 +17,7 @@ import { fetchLatestVersion, isNewerVersion } from "./update-check.js";
 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 DEFAULT_PORT = 34567;
 const READY_TIMEOUT_MS = 15_000;
 const MAX_BIND_RETRIES = 5;
 // Server exit code meaning "port taken at bind time" — keep in sync with