procdeck 0.3.0 → 0.4.0

package/dist/public.d.ts

@@ -57,6 +57,12 @@ export type ProcdeckConfig = {
     readonly name?: string;
     /** Port for the web UI and the `*.localhost` proxy. Defaults to 4820. */
     readonly port?: number;
+    /**
+     * Interface the UI and proxy bind to. Defaults to "127.0.0.1" (loopback
+     * only — the UI types into real terminals). "0.0.0.0" to reach the deck
+     * from another machine or from a container's host.
+     */
+    readonly host?: string;
     readonly procs: ReadonlyArray<ProcSpec>;
 };
 /** Identity helper that gives config files their types. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "procdeck",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Interactive dev-process multiplexer with a web UI: terminal panes in a browser tab, declarative dependencies, assigned ports and a *.localhost reverse proxy.",
   "keywords": [
     "cli",
@@ -50,11 +50,13 @@
   },
   "devDependencies": {
     "@effect/platform-browser": "4.0.0-beta.106",
-    "effect": "4.0.0-beta.106",
+    "@effect/platform-node-shared": "4.0.0-beta.106",
     "@types/node": "^22.10.1",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/addon-search": "^0.16.0",
+    "@xterm/addon-web-links": "^0.12.0",
     "@xterm/xterm": "^6.0.0",
+    "effect": "4.0.0-beta.106",
     "foldkit": "^0.141.2",
     "tsup": "^8.5.1",
     "typescript": "^7.0.2",

package/readme.md

@@ -44,27 +44,40 @@ which port is which**.
   callback server mid-handshake.
 - **Alerts.** Regexes matched against a rolling tail of pane output; a match raises a
   badge in the UI ("needs login").
+- **Knows when you're not looking.** Crashed, blocked or alerting procs and unread error
+  lines count into the tab title (`(2) garage`) and a red dot on the favicon; turn on the
+  bell and a crash or alert while the tab is hidden becomes a system notification.
 - **Whole-tree restarts.** `pnpm` → `wrangler` → `workerd`: killing the pid would leave
   the grandchild holding the port. procdeck signals the process group, escalating
   SIGTERM → SIGKILL, and Ctrl-C tears down every tree it spawned.
 - **Single or grid layout.** One pane at a time with a sidebar, or every pane tiled
-  (⌥G); each pane header carries its address, status and restart/stop/clear.
+  (⌥G, ⌥Z zooms one tile in and out); each pane header carries its address, status and
+  restart/stop/clear. Too many tiles? **Pin** the ones you watch (📌, ⌥P) — the grid
+  shows only those and the rest collapse into a tray strip with their status dots and
+  badges, one click from a peek. Layout, pins, selected pane and theme (system / light /
+  dark — terminals included) survive a reload.
+- **Runs in the background.** `procdeck up` starts the deck, opens the UI and returns
+  — no terminal tab kept hostage. `down`, `restart`, `status`, `logs` and `open` work
+  from anywhere inside the project; `procdeck ls` lists every deck on the machine;
+  ⏻ in the UI shuts one down. Prefer a terminal? `up --fg`.
 - **Installable as an app.** The UI ships a web-app manifest named after the deck
   (`name` in the config, else the directory), so "⤓ install" in the bar — or File →
   Add to Dock in Safari — gives each project its own window and Dock icon. Works over
-  plain `http://localhost`, no HTTPS needed.
+  plain `http://localhost`, no HTTPS needed. Several projects? The deck name in the
+  bar lists the other running decks, one click away.
 
 ## Install
 
-Nothing to install, if you don't want to — write a `procdeck.config.json` (see
-[Config](#config)) and run:
+Nothing to install, if you don't want to:
 
 ```sh
+npx procdeck init                 # writes procdeck.config.json from your workspace's dev scripts
 npx procdeck                      # picks up ./procdeck.config.json
 npx procdeck decks/backend.json   # or point it at any config file
 ```
 
-Open <http://localhost:4820> for the panes. Requires **Node ≥ 22**.
+The deck comes up in the background, the UI opens at <http://localhost:4820>, and the
+terminal is yours again. Requires **Node ≥ 22**.
 
 Or add it to the project, which is what you want if you keep the config in TypeScript:
 
@@ -72,16 +85,42 @@ Or add it to the project, which is what you want if you keep the config in TypeS
 pnpm add -D procdeck      # npm i -D procdeck · bun add -d procdeck
 ```
 
+## Commands
+
+```sh
+procdeck init               # write procdeck.config.json: one proc per workspace dev script
+procdeck up [config]        # start (detached) and open the UI — idempotent
+procdeck down               # stop: every process tree is terminated
+procdeck restart            # down + up — after editing the config or updating procdeck
+procdeck status             # this project's deck: address, uptime, every proc's state
+procdeck ls                 # every running deck on this machine
+procdeck open               # open the UI — no port to remember
+procdeck logs [-f]          # procdeck's own log (startup, shutdown, errors)
+procdeck up --fg            # foreground instead: Ctrl-C stops the deck
+```
+
+`procdeck` alone is `procdeck up`. Without a config path, the nearest
+`procdeck.config.{json,ts,js,mjs}` up from the current directory is used, so every
+command works from any subdirectory of the project. Running decks register in
+`~/.procdeck/instances/` (one JSON per deck — that is how `down`, `ls` and the UI's
+deck switcher find them; stale entries are pruned by pid), and a detached deck's own
+output goes to `~/.procdeck/logs/`. `--no-open` skips the browser. Updating procdeck
+needs a `procdeck restart` — the running deck keeps the old code until then.
+
+The server binds **127.0.0.1 only** — the UI types into real terminals, so it is not
+something to put on the LAN by accident. `"host": "0.0.0.0"` in the config opens it up
+(a devcontainer whose browser is on the host, a VM). No telemetry, no service worker.
+
 ## Try the example
 
 In a clone of this repo:
 
 ```sh
 pnpm install
-pnpm dev          # builds the UI, starts the example stack
+pnpm dev          # builds the UI, starts the example stack in the foreground
 ```
 
-> **Install footprint.** ~1.8 MB, one dependency. The server is shipped as a bundle, so
+> **Install footprint.** ~2 MB, one dependency. The server is shipped as a bundle, so
 > nothing but the PTY bindings is installed — and those are
 > [`@lydell/node-pty`](https://github.com/lydell/node-pty): the same sources as
 > [node-pty](https://github.com/microsoft/node-pty), distributed as per-platform packages.
@@ -94,6 +133,16 @@ ports) entirely through `${port}` templates. See [`example/`](example/).
 
 ## Config
 
+`procdeck init` writes a first one from what is already there, trying in order: a
+**Procfile** (already a list of processes); **workspaces** (`pnpm-workspace.yaml`,
+`workspaces` in `package.json`) — one proc per package with a `dev` (or `start:dev`,
+`serve`, `watch`, `start`) script, run through the package manager your lockfile
+points at (`pnpm --filter web dev`, `yarn workspace web dev`, …); **plain
+subdirectories** — `backend/`, `frontend/`, each with its own `package.json` (its own
+lockfile decides the manager) or a recognisable non-JS project (Django, Go, Rust, Rails,
+Phoenix, docker compose), run with `cwd` set; and finally the **root itself**. Ports and
+dependencies are yours to add; the tips it prints say how.
+
 Two formats, one schema. **JSON** needs nothing from your toolchain — no TypeScript, and
 procdeck itself doesn't have to be a dependency. Point `$schema` at the published schema
 and the editor completes and validates every field:
@@ -181,7 +230,10 @@ Tips:
 | `supervisor.ts` | Effect layer: scoped lifecycle, port assignment, `PubSub` fan-out, per-proc state.                   |
 | `ports.ts`      | Free-port allocation and `pgrep`+`lsof` listening-port discovery.                                    |
 | `server.ts`     | `effect/unstable/http` router behind a small Node↔web-handler bridge; SSE downstream, POST upstream; `Host`-routed reverse proxy with WebSocket pass-through. |
-| `cli.ts`        | Entry point and signal handling.                                                                     |
+| `registry.ts`   | `~/.procdeck/instances/<id>.json` per running deck: how `down`/`ls`/the deck switcher find decks.     |
+| `lifecycle.ts`  | Detaching (`up` re-spawns itself as `up --fg` and waits for the registry entry), `down`, port probe.   |
+| `init.ts`       | `procdeck init`: workspace scan → a first config (one proc per package with a dev script).            |
+| `cli.ts`        | `effect/unstable/cli` commands; `up --fg` is the server, everything else talks to the registry/API.    |
 
 Design notes worth keeping:
 
@@ -195,11 +247,21 @@ Design notes worth keeping:
 - **SSE, not WebSocket.** Logs only flow towards the browser; commands are ordinary
   POSTs. No upgrade handshake, no extra dependency, and `EventSource` reconnects by
   itself.
-- **`PubSub.sliding({ capacity, replay })`** doubles as the fan-out to every open tab
-  _and_ the scrollback ring buffer — a tab opened late replays the backlog for free.
+- **Per-proc backlog, one stream per subscriber.** Each proc keeps its last 256 KB of
+  output; a subscriber (an SSE connection) gets every proc's backlog and status, a
+  `synced` marker, then live events from a `PubSub` it subscribed to *before* the
+  snapshot — no gap, and a per-proc chunk counter cuts the duplicate at the seam. A
+  tab opened on a deck that has run for days still shows every pane's history, and
+  the UI knows exactly which chunks are news (unread tallies, notifications).
 - **The supervisor is `Effect.acquireRelease`.** Shutdown is not a code path anyone has
   to remember to call: closing the scope terminates every process tree. The SSE response
   stream lives in the request scope, so a dropped tab cleans up its subscription too.
+  Ctrl-C, `procdeck down` and the UI's ⏻ are all the same SIGTERM into the same scope.
+- **Detached is just `up --fg` in the background.** No daemon, no IPC: `up` spawns
+  itself detached with its output in a log file, and waits for the child's registry
+  entry to appear — written only after `listen` succeeds — so "up" means reachable.
+  The registry is plain files pruned by pid; every deck serves its own UI, and the
+  deck switcher is a list of links.
 
 ## Tests
 
@@ -220,8 +282,6 @@ self-heal — if it still fails, PTY allocation itself is probably blocked (sand
 
 ## Status
 
-A working prototype, macOS/Linux only (PTYs, `pgrep`, `lsof`). Known prototype-grade
-shortcuts: the replay buffer counts events rather than bytes (a chatty proc can evict a
-quiet one's history), and statuses are a mutated map rather than `SubscriptionRef`s.
-Not done yet: an injected FAB overlay inside the developed apps, dependency-death
-policy (a dependency dying does _not_ cascade — deliberately), and an npm release.
+macOS/Linux only (PTYs, `pgrep`, `lsof`). Known shortcut: statuses are a mutated map
+rather than `SubscriptionRef`s. Not done yet: an injected FAB overlay inside the developed apps, and a dependency-death
+policy (a dependency dying does _not_ cascade — deliberately).

package/schema.json

@@ -31,6 +31,19 @@
         }
       ]
     },
+    "host": {
+      "type": "string",
+      "description": "Interface the UI and proxy bind to. Defaults to \"127.0.0.1\" — loopback only, because the UI types into real terminals. Set \"0.0.0.0\" to reach the deck from another machine or from a container's host.",
+      "examples": [
+        "127.0.0.1",
+        "0.0.0.0"
+      ],
+      "allOf": [
+        {
+          "minLength": 1
+        }
+      ]
+    },
     "procs": {
       "type": "array",
       "items": {