procdeck 0.1.0

package/dist/config.d.ts

@@ -0,0 +1,147 @@
+import { Effect, Schema } from "effect";
+export declare const PreflightSchema: Schema.Struct<{
+    /** Shell command; exit 0 lets the proc spawn. */
+    readonly shell: Schema.String;
+    /**
+     * Regex that must also match the check's output. For checks that exit 0
+     * either way — `wrangler whoami` reports "not authenticated" with exit 0 —
+     * so the config doesn't need `| grep` pipelines.
+     */
+    readonly expect: Schema.optionalKey<Schema.String>;
+    /** What the human should do when the check fails. */
+    readonly hint: Schema.optionalKey<Schema.String>;
+}>;
+export type Preflight = typeof PreflightSchema.Type;
+/** A regex watched in the pane output; a match raises a badge in the UI. */
+export declare const AlertSchema: Schema.Struct<{
+    readonly pattern: Schema.String;
+    /** Badge text. */
+    readonly label: Schema.String;
+}>;
+export type Alert = typeof AlertSchema.Type;
+export declare const ProcSpecSchema: Schema.Struct<{
+    /** Stable identifier, also the tab label. */
+    readonly id: Schema.String;
+    /** Command line handed to `$SHELL -c`. */
+    readonly shell: Schema.optionalKey<Schema.String>;
+    /** argv, executed without a shell. */
+    readonly cmd: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    /** Working directory; defaults to the config file's directory. */
+    readonly cwd: Schema.optionalKey<Schema.String>;
+    /** Extra environment on top of the inherited one. */
+    readonly env: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    /** Spawn on startup. Defaults to true. */
+    readonly autostart: Schema.optionalKey<Schema.Boolean>;
+    /** URL this process serves, shown in the UI as a link. */
+    readonly url: Schema.optionalKey<Schema.String>;
+    /**
+     * Names of procs that must be ready before this one spawns. Declarative:
+     * readiness is auto-detected, no port numbers in the config.
+     */
+    readonly needs: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    /**
+     * What "ready" means for dependents: "listening" (default) — the process
+     * tree opened a TCP port; "started" — it merely spawned (for procs that
+     * never listen).
+     */
+    readonly readyWhen: Schema.optionalKey<Schema.Literals<readonly ["listening", "started"]>>;
+    /** Check that must pass before this proc spawns; failure shows as "blocked". */
+    readonly preflight: Schema.optionalKey<Schema.Struct<{
+        /** Shell command; exit 0 lets the proc spawn. */
+        readonly shell: Schema.String;
+        /**
+         * Regex that must also match the check's output. For checks that exit 0
+         * either way — `wrangler whoami` reports "not authenticated" with exit 0 —
+         * so the config doesn't need `| grep` pipelines.
+         */
+        readonly expect: Schema.optionalKey<Schema.String>;
+        /** What the human should do when the check fails. */
+        readonly hint: Schema.optionalKey<Schema.String>;
+    }>>;
+    /** Output patterns that raise a badge when they appear in the pane. */
+    readonly alerts: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly pattern: Schema.String;
+        /** Badge text. */
+        readonly label: Schema.String;
+    }>>>;
+}>;
+export type ProcSpec = typeof ProcSpecSchema.Type;
+/** Default port of the UI + proxy server. */
+export declare const DEFAULT_UI_PORT = 4820;
+/** Whether the spec asks procdeck to assign it a port (`${port}` anywhere). */
+export declare const usesOwnPort: (spec: ProcSpec) => boolean;
+/** Substitute `${port}` / `${port:id}` with the ports assigned at startup. */
+export declare const resolveSpec: (spec: ProcSpec, assigned: Map<string, number>) => ProcSpec;
+export declare const ProcdeckConfigSchema: Schema.Struct<{
+    /**
+     * Deck name — the tab title and the name of the installed web app.
+     * Defaults to the config directory's basename.
+     */
+    readonly name: Schema.optionalKey<Schema.String>;
+    /** Port for the web UI. Defaults to 4820. */
+    readonly port: Schema.optionalKey<Schema.Number>;
+    readonly procs: Schema.$Array<Schema.Struct<{
+        /** Stable identifier, also the tab label. */
+        readonly id: Schema.String;
+        /** Command line handed to `$SHELL -c`. */
+        readonly shell: Schema.optionalKey<Schema.String>;
+        /** argv, executed without a shell. */
+        readonly cmd: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        /** Working directory; defaults to the config file's directory. */
+        readonly cwd: Schema.optionalKey<Schema.String>;
+        /** Extra environment on top of the inherited one. */
+        readonly env: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+        /** Spawn on startup. Defaults to true. */
+        readonly autostart: Schema.optionalKey<Schema.Boolean>;
+        /** URL this process serves, shown in the UI as a link. */
+        readonly url: Schema.optionalKey<Schema.String>;
+        /**
+         * Names of procs that must be ready before this one spawns. Declarative:
+         * readiness is auto-detected, no port numbers in the config.
+         */
+        readonly needs: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        /**
+         * What "ready" means for dependents: "listening" (default) — the process
+         * tree opened a TCP port; "started" — it merely spawned (for procs that
+         * never listen).
+         */
+        readonly readyWhen: Schema.optionalKey<Schema.Literals<readonly ["listening", "started"]>>;
+        /** Check that must pass before this proc spawns; failure shows as "blocked". */
+        readonly preflight: Schema.optionalKey<Schema.Struct<{
+            /** Shell command; exit 0 lets the proc spawn. */
+            readonly shell: Schema.String;
+            /**
+             * Regex that must also match the check's output. For checks that exit 0
+             * either way — `wrangler whoami` reports "not authenticated" with exit 0 —
+             * so the config doesn't need `| grep` pipelines.
+             */
+            readonly expect: Schema.optionalKey<Schema.String>;
+            /** What the human should do when the check fails. */
+            readonly hint: Schema.optionalKey<Schema.String>;
+        }>>;
+        /** Output patterns that raise a badge when they appear in the pane. */
+        readonly alerts: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+            readonly pattern: Schema.String;
+            /** Badge text. */
+            readonly label: Schema.String;
+        }>>>;
+    }>>;
+}>;
+export type ProcdeckConfig = typeof ProcdeckConfigSchema.Type;
+/** Identity helper that gives config files their types. */
+export declare const defineConfig: (config: ProcdeckConfig) => ProcdeckConfig;
+export type LoadedConfig = {
+    config: ProcdeckConfig;
+    /** Directory of the config file — the default cwd for every process. */
+    root: string;
+    /** `config.name`, or the root directory's basename. */
+    name: string;
+};
+declare const ConfigError_base: Schema.Class<ConfigError, Schema.TaggedStruct<"ConfigError", {
+    readonly file: Schema.String;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class ConfigError extends ConfigError_base {
+}
+export declare const loadConfig: (file: string) => Effect.Effect<LoadedConfig, ConfigError, never>;
+export {};

package/dist/config.js

@@ -0,0 +1,24 @@
+import {
+  AlertSchema,
+  ConfigError,
+  DEFAULT_UI_PORT,
+  PreflightSchema,
+  ProcSpecSchema,
+  ProcdeckConfigSchema,
+  defineConfig,
+  loadConfig,
+  resolveSpec,
+  usesOwnPort
+} from "./chunk-SBVZ6G4G.js";
+export {
+  AlertSchema,
+  ConfigError,
+  DEFAULT_UI_PORT,
+  PreflightSchema,
+  ProcSpecSchema,
+  ProcdeckConfigSchema,
+  defineConfig,
+  loadConfig,
+  resolveSpec,
+  usesOwnPort
+};

package/license

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksandr Kondaurov
+
+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/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "procdeck",
+  "version": "0.1.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",
+    "dev-server",
+    "multiplexer",
+    "process-manager",
+    "pty",
+    "reverse-proxy",
+    "terminal",
+    "xterm"
+  ],
+  "homepage": "https://github.com/kondaurovDev/procdeck",
+  "bugs": "https://github.com/kondaurovDev/procdeck/issues",
+  "license": "MIT",
+  "author": {
+    "name": "Aleksandr Kondaurov",
+    "email": "kondaurov.dev@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kondaurovDev/procdeck",
+    "directory": "packages/procdeck"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.18"
+  },
+  "files": [
+    "dist",
+    "ui/dist"
+  ],
+  "bin": {
+    "procdeck": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "effect": "4.0.0-beta.106",
+    "node-pty": "^1.1.0"
+  },
+  "devDependencies": {
+    "@effect/platform-browser": "4.0.0-beta.106",
+    "@types/node": "^22.10.1",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-search": "^0.16.0",
+    "@xterm/xterm": "^6.0.0",
+    "foldkit": "^0.141.2",
+    "tsup": "^8.5.1",
+    "typescript": "^7.0.2",
+    "vite": "^6.2.0",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "ui:dev": "vite ui",
+    "build": "pnpm run build:meta && pnpm run build:ui && pnpm run build:js && pnpm run build:types",
+    "build:meta": "cp ../../readme.md ../../license .",
+    "build:ui": "vite build ui",
+    "build:js": "tsup",
+    "build:types": "tsc -p tsconfig.build.json",
+    "check:types": "tsc --noEmit && tsc -p ui --noEmit",
+    "test": "vitest run"
+  }
+}

package/readme.md

@@ -0,0 +1,203 @@
+# procdeck
+
+An interactive dev-process multiplexer with a **web UI** instead of a TUI — the thing
+`mprocs`/`overmind` do, but the panes live in a browser tab, and the tool also solves
+the two problems terminal multiplexers can't touch: **port conflicts** and **remembering
+which port is which**.
+
+```
+┌──────────┬───────────────────────────────────────────────┐
+│ ● api    │  Restart  Stop  Start   api.localhost:4820    │
+│ ● web    ├───────────────────────────────────────────────┤
+│ ● clock  │  $ node servers/api.mjs                       │
+│ ● flaky ⚠│  api listening on :52341                      │
+│          │  GET /                                        │
+└──────────┴───────────────────────────────────────────────┘
+```
+
+## What it does
+
+- **Terminal panes in the browser.** Every process runs in a real PTY and renders in
+  xterm.js — colours, spinners, cursor redraws and interactive hotkeys work exactly like
+  in a terminal. Keystrokes are posted back into the PTY.
+- **Assigned ports.** Write `${port}` in a proc's command, env or url and procdeck hands
+  it a free port before spawning (also exported as `PORT`). `${port:api}` references
+  another proc's assigned port — so dependents get wired
+  (`API_URL=http://localhost:${port:api}`) without a single hardcoded number. Nothing
+  can conflict: ports are assigned once per run and never collide.
+- **A reverse proxy on `*.localhost`.** Every pane is reachable at a stable, memorable
+  address on the UI's own port — `api.localhost:4820`, `web.localhost:4820` — whatever
+  port the process actually got. Browsers hardcode `*.localhost` → 127.0.0.1, so there
+  is zero system setup. WebSocket upgrades pass through (vite HMR works); the `Host`
+  header is rewritten upstream so host-allowlisting dev servers need no config.
+- **Port auto-detection.** A 1s poll asks the OS (`pgrep` + `lsof`) which TCP ports each
+  process _group_ listens on; they render as links in the UI. No cooperation from the
+  process needed.
+- **Declarative dependencies.** `needs: ["api"]` parks a proc in `waiting` until every
+  dependency is ready. Ready = "listening on its port" by default, or
+  `readyWhen: "started"` for procs that never listen. Unknown names, duplicates and
+  cycles are rejected by the config schema.
+- **Preflight gates.** A shell command that must pass before the proc spawns (plus an
+  optional `expect` regex for checks that exit 0 either way, like `wrangler whoami`).
+  Failure parks the pane in `blocked` with the output and a hint for the human — keeps
+  interactive auth flows out of supervised panes, where a restart would kill an OAuth
+  callback server mid-handshake.
+- **Alerts.** Regexes matched against a rolling tail of pane output; a match raises a
+  badge in the UI ("needs login").
+- **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.
+- **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.
+
+## Install
+
+```sh
+pnpm add -D procdeck      # npm i -D procdeck · bun add -d procdeck
+```
+
+Requires **Node ≥ 22.18**: `procdeck.config.ts` is a TypeScript file, loaded through
+Node's built-in type stripping.
+
+Write a `procdeck.config.ts` next to your `package.json` (see [Config](#config)), then:
+
+```sh
+npx procdeck                    # defaults to ./procdeck.config.ts
+npx procdeck decks/backend.ts   # or point it at any config file
+```
+
+Open <http://localhost:4820> for the panes.
+
+## Try the example
+
+In a clone of this repo:
+
+```sh
+pnpm install
+pnpm dev          # builds the UI, starts the example stack
+```
+
+> **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).
+
+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
+ports) entirely through `${port}` templates. See [`example/`](example/).
+
+## Config
+
+`procdeck.config.ts` — a TypeScript file, validated by an Effect schema:
+
+```ts
+import { defineConfig } from "procdeck"
+
+export default defineConfig({
+  port: 4820, // UI + proxy port
+  procs: [
+    {
+      id: "api",                        // pane name and the proxy subdomain
+      shell: "pnpm --filter api dev",   // or cmd: ["node", "server.js"]
+      env: { PORT: "${port}" },         // ask procdeck for a free port
+      preflight: {                      // gate: must pass before spawning
+        shell: "wrangler whoami",
+        expect: "You are logged in",
+        hint: "run `wrangler login`, then Start",
+      },
+      alerts: [{ pattern: "ERROR", label: "check me" }],
+    },
+    {
+      id: "web",
+      shell: "pnpm --filter web dev",
+      env: { PORT: "${port}", API_URL: "http://localhost:${port:api}" },
+      needs: ["api"],                   // wait until api is listening
+    },
+    {
+      id: "worker",
+      shell: "node worker.js",
+      readyWhen: "started",             // never listens; running = ready
+    },
+  ],
+})
+```
+
+Full field reference: [`packages/procdeck/src/config.ts`](packages/procdeck/src/config.ts)
+(the schema is the documentation).
+
+Tips:
+
+- Give tools that auto-increment on a busy port (vite) a `strictPort` flag, so a
+  violated port assignment fails loudly instead of drifting.
+- A good pattern for app dev scripts: `vite dev --port ${PORT:-3000} --strictPort` —
+  fixed default when run by hand, assigned port under procdeck.
+- The proxy is for humans and browsers. Scripts and server-to-server calls should use
+  the injected env (`${port:api}`) — system resolvers don't all know `*.localhost`.
+
+## How it fits together
+
+| Path                    | What                                                                                                  |
+| ----------------------- | ----------------------------------------------------------------------------------------------------- |
+| `packages/procdeck/src` | The server: plain-Node PTY layer, Effect supervisor, HTTP/SSE server with the reverse proxy.          |
+| `packages/procdeck/ui`  | [Foldkit](https://foldkit.dev) (Elm-on-Effect) app; built by vite, served statically by the server.   |
+| `example/`              | Self-contained demo stack (Node one-liners) exercising every feature.                                 |
+
+| File            | What                                                                                                 |
+| --------------- | ---------------------------------------------------------------------------------------------------- |
+| `proc.ts`       | Plain Node: PTY spawn, process-group kill, SIGTERM → SIGKILL escalation.                             |
+| `config.ts`     | Effect `Schema` for the config, `${port}` templating, loader.                                        |
+| `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.                                                                     |
+
+Design notes worth keeping:
+
+- **Effect end to end.** The server is Effect; the UI is a Foldkit app — one Model (a
+  Schema), pure `update`, side effects as Commands. Terminals are imperative islands via
+  `Mount.defineStream`; PTY log chunks bypass the Model (`ReceivedLog` → `WriteTerminal`
+  Command into a module-level terminal registry — the view never renders them); the SSE
+  subscription is gated on a Model condition ("every pane mounted"), so the replayed
+  backlog ordering is declarative, not sequenced by hand.
+- **The server has no bundler.** It runs as `.ts` via Node type stripping (Node ≥ 22.18).
+- **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.
+- **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.
+
+## Tests
+
+```sh
+pnpm test
+```
+
+Integration tests with real (tiny) processes — `node -e` one-liners and shells with
+background children — because the risks live at the OS boundary: PTY detection, group
+kills, SIGTERM-ignoring survivors, scope teardown. Mocking any of that would test the
+mock. They need a real PTY (`/dev/ptmx`), so they won't run inside sandboxes that block
+PTY allocation.
+
+Gotcha: if every spawn fails with `posix_spawnp failed.`, the usual culprit is the
+node-pty `spawn-helper` prebuild arriving without its execute bit (pnpm/Bun skipping
+its install script). `proc.ts` restores the bit at import time, so this should
+self-heal — if it still fails, PTY allocation itself is probably blocked (sandboxes).
+
+## 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.