procdeck 0.2.0 → 0.4.0

package/dist/public.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The package's public entry point — everything a `procdeck.config.ts` needs.
+ *
+ * The types are written out structurally instead of being derived from the
+ * Effect schema in `config.ts`, because a derived type makes the emitted `.d.ts`
+ * import `effect`, and effect is bundled into the CLI rather than installed:
+ * consumers would be typechecking against a package they don't have.
+ *
+ * `tests/public.test.ts` asserts at the type level that this mirrors the schema
+ * exactly, so the two cannot drift apart silently.
+ */
+/** A check that must pass before the proc spawns; failure parks it in `blocked`. */
+export type Preflight = {
+    /** Shell command; exit 0 lets the proc spawn. */
+    readonly shell: string;
+    /** Regex the check's output must also match, for checks that exit 0 either way. */
+    readonly expect?: string;
+    /** What the human should do when the check fails. */
+    readonly hint?: string;
+};
+/** A regex watched in the pane output; a match raises a badge in the UI. */
+export type Alert = {
+    readonly pattern: string;
+    /** Badge text. */
+    readonly label: string;
+};
+/** A single supervised process. Exactly one of `shell` / `cmd` is used. */
+export type ProcSpec = {
+    /** Pane label and proxy subdomain (`api` → http://api.localhost:4820). */
+    readonly id: string;
+    /** Command line handed to `$SHELL -c`. */
+    readonly shell?: string;
+    /** argv, executed without a shell. */
+    readonly cmd?: ReadonlyArray<string>;
+    /** Working directory; defaults to the config file's directory. */
+    readonly cwd?: string;
+    /** Extra environment; values may use `${port}` / `${port:other}`. */
+    readonly env?: {
+        readonly [key: string]: string;
+    };
+    /** Spawn on startup. Defaults to true. */
+    readonly autostart?: boolean;
+    /** URL this process serves, shown in the UI as a link. */
+    readonly url?: string;
+    /** Ids of procs that must be ready before this one spawns. */
+    readonly needs?: ReadonlyArray<string>;
+    /** What "ready" means for dependents. Defaults to "listening". */
+    readonly readyWhen?: "listening" | "started";
+    readonly preflight?: Preflight;
+    readonly alerts?: ReadonlyArray<Alert>;
+};
+/** A procdeck deck: the web UI's settings and the processes it supervises. */
+export type ProcdeckConfig = {
+    /** Only meaningful in a JSON config; accepted here for symmetry. */
+    readonly $schema?: string;
+    /** Deck name; defaults to the config directory's basename. */
+    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. */
+export declare const defineConfig: (config: ProcdeckConfig) => ProcdeckConfig;

package/dist/public.js

@@ -0,0 +1,7 @@
+import "./chunk-MLKGABMK.js";
+
+// src/public.ts
+var defineConfig = (config) => config;
+export {
+  defineConfig
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "procdeck",
-  "version": "0.2.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",
@@ -38,23 +38,25 @@
   },
   "exports": {
     ".": {
-      "types": "./dist/config.d.ts",
-      "import": "./dist/config.js"
+      "types": "./dist/public.d.ts",
+      "import": "./dist/public.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "effect": "4.0.0-beta.106",
-    "node-pty": "^1.1.0"
+    "@lydell/node-pty": "1.2.0-beta.15"
   },
   "devDependencies": {
     "@effect/platform-browser": "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,23 +85,47 @@ 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
 ```
 
-> **Native dependency note.** procdeck runs panes through [node-pty](https://github.com/microsoft/node-pty),
-> which ships a native prebuild. npm and yarn set it up automatically. pnpm ≥ 10 and Bun
-> block dependency install scripts by default — in your own project run
-> `pnpm approve-builds` and allow `node-pty` (Bun: add it to `trustedDependencies`).
-> procdeck also repairs the most common fallout by itself at startup (the darwin
-> `spawn-helper` prebuild arriving without its execute bit), so approving is only
-> strictly required when node-pty must compile from source (no prebuild for your
-> platform).
+> **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.
+> Nothing compiles and no install script runs, so there is no `pnpm approve-builds` /
+> `trustedDependencies` detour, and no compiler is needed on Linux.
 
 Open <http://localhost:4820> for the panes, then <http://web.localhost:4820> and
 <http://api.localhost:4820> — the example's two servers found each other (and their own
@@ -96,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:
@@ -183,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:
 
@@ -197,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
 
@@ -222,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": {