feat(client): experimental env-driven exthook and doctor integration

Author: Cod-e-Codes

ARCHITECTURE.md

@@ -37,6 +37,7 @@ The client is a standalone terminal user interface built with the Bubble Tea fra
 - **`hotkeys.go`**: Key binding definitions and methods
 - **`render.go`**: Message rendering and UI display logic (optional per-line metadata: message id and encrypted flag)
 - **`websocket.go`**: WebSocket connection management, send/receive, and E2E encryption helpers
+- **`exthook/`**: Optional, experimental subprocess hooks for local automation (stdin JSON per event); see **CLIENT_HOOKS.md**
 - **`commands.go`**: Help text generation and command-related utilities
 - **`notification_manager.go`**: Desktop/bell notification system
 
@@ -108,7 +109,7 @@ The server package contains the core server logic and components that are used b
 
 #### Core Components
 
-- **WebSocket Handlers**: Connection management and message routing
+- **WebSocket Handlers**: Connection management and message routing; failed handshakes close with **RFC 6455** close frames (registered status code + UTF-8 reason, not a raw text payload—see `PROTOCOL.md`)
 - **Database Layer**: Pluggable SQL backends (SQLite/PostgreSQL/MySQL) with dialect-aware schema and query helpers
 - **Admin Interfaces**: Both TUI and web-based administrative panels
 - **Plugin Integration**: Plugin command handling and execution
@@ -209,7 +210,7 @@ The **client** stores `config.json`, `profiles.json`, keystore, themes, and debu
 
 ### Diagnostics (`internal/doctor`)
 
-Shared package invoked by **`marchat-client`** and **`marchat-server`** when passed **`-doctor`** (human-readable report) or **`-doctor-json`** (JSON on stdout). It summarizes Go/OS, resolved config directories, known `MARCHAT_*` variables with secrets masked, role-specific checks (client: profiles, clipboard, TTY; server: `.env`, validation, detected DB dialect, DB connection-string format validation, DB/TLS ping checks), and optionally compares the embedded version to the latest GitHub release. For **server** doctor, the `MARCHAT_*` listing is captured **after** `LoadConfigWithoutValidation` applies **`godotenv.Overload`** on `config/.env`, matching effective runtime env; **client** doctor still reflects only the client process environment. The **text** report is **colorized** when stdout is a terminal and **`NO_COLOR`** is unset (otherwise plain); **`-doctor-json`** is always unstyled JSON. Set **`MARCHAT_DOCTOR_NO_NETWORK=1`** to skip the release check (e.g. air-gapped environments).
+Shared package invoked by **`marchat-client`** and **`marchat-server`** when passed **`-doctor`** (human-readable report) or **`-doctor-json`** (JSON on stdout). It summarizes Go/OS, resolved config directories, known `MARCHAT_*` variables with secrets masked, role-specific checks (client: profiles, clipboard, TTY, and optional **experimental client hook** env vars plus executable path validation when receive/send paths are set; server: `.env`, validation, detected DB dialect, DB connection-string format validation, DB/TLS ping checks), and optionally compares the embedded version to the latest GitHub release. For **server** doctor, the `MARCHAT_*` listing is captured **after** `LoadConfigWithoutValidation` applies **`godotenv.Overload`** on `config/.env`, matching effective runtime env; **client** doctor still reflects only the client process environment. **Server** doctor omits client-only hook keys from the environment section entirely, even when they are set in the process (for example the same shell session used to start the client). The **text** report is **colorized** when stdout is a terminal and **`NO_COLOR`** is unset (otherwise plain); **`-doctor-json`** is always unstyled JSON. Set **`MARCHAT_DOCTOR_NO_NETWORK=1`** to skip the release check (e.g. air-gapped environments).
 
 ### Command Line Tools (`cmd/`)
 

CLIENT_HOOKS.md

@@ -0,0 +1,118 @@
+# Client external hooks (experimental)
+
+**Status:** experimental. The hook protocol, environment variables, and payload fields may change or be removed in a future release without a major version bump. If you build integrations on this, pin a marchat version and watch release notes.
+
+Client hooks run **local executables** you choose, fed one JSON object per event on **stdin** (newline-terminated). They are **not** server plugins: they only see what **your** client process sees, after decrypt on receive and before encrypt on send.
+
+## Why this exists
+
+- **Server plugins** automate hub-side behavior and see server-wide trust boundaries.
+- **Built-in notifications** cover in-TUI alerts with a fixed feature set.
+- **Client hooks** fill the gap: pipe chat events to **your** scripts, loggers, bridges, or external notification systems **without** new client dependencies or server changes.
+
+Hooks are **side-effect only**: they cannot modify, block, or transform messages (runs are asynchronous).
+
+## Security and trust
+
+1. **Plaintext:** A receive hook runs after the client decrypts; a send hook runs with the plaintext you typed. Anyone who can read hook logs or the hook binary's behavior gets the same material as the TUI. This does **not** weaken wire encryption (the server still sees ciphertext for E2E traffic); it widens **local** exposure to whatever you execute.
+2. **Absolute paths only:** `MARCHAT_CLIENT_HOOK_RECEIVE` and `MARCHAT_CLIENT_HOOK_SEND` must be absolute paths to a regular file. Relative paths are rejected to avoid surprising `PATH` / working-directory behavior.
+3. **Trust the binary:** Hooks run as your user. Only point at programs you trust, same as running them manually.
+4. **Timeouts:** Each invocation is killed if it exceeds the configured timeout (default 5s, max 120s) so a stuck script does not pile up forever.
+5. **File messages:** Payloads include file **metadata** (`filename`, `size`) only; raw file bytes are never sent to hooks.
+
+## Environment variables
+
+| Variable | Meaning |
+|----------|---------|
+| `MARCHAT_CLIENT_HOOK_RECEIVE` | Absolute path to executable for inbound events (`message_received`). |
+| `MARCHAT_CLIENT_HOOK_SEND` | Absolute path to executable for outbound composer sends (`message_send`). |
+| `MARCHAT_CLIENT_HOOK_TIMEOUT_SEC` | Optional. Per-hook timeout in seconds (default `5`, max `120`). |
+| `MARCHAT_CLIENT_HOOK_RECEIVE_TYPING` | Set to `1`, `true`, or `yes` to deliver **typing** indicators to the receive hook. Default: **off** (reduces log noise). |
+| `MARCHAT_CLIENT_HOOK_DEBUG` | Set to `1`, `true`, or `yes` to log successful hook completion (duration) and label stdout as a debug preview. |
+| `MARCHAT_HOOK_LOG` | Optional log file path for the **bundled** `example_hook` binary only. The marchat client does not read this variable. |
+
+Unset hook paths mean that hook is disabled.
+
+## Diagnostics (`-doctor`)
+
+Run **`marchat-client -doctor`** (or **`-doctor-json`**) to inspect your client environment:
+
+- The **Environment** section lists hook-related variables, including `MARCHAT_HOOK_LOG` for visibility, even though only `example_hook` uses it (with the same masking and truncation rules as other doctor output).
+- If **`MARCHAT_CLIENT_HOOK_RECEIVE`** or **`MARCHAT_CLIENT_HOOK_SEND`** is set, doctor runs a **path check**: the value must be an absolute path to an existing regular file, matching what the client enforces at runtime.
+
+Server doctor does **not** list client-only hook variables, even if they are set in the environment (the server never reads them; hiding them avoids noise when client and server are run from the same shell).
+
+## Protocol
+
+### Transport
+
+- One UTF-8 JSON object per invocation, written to the process **stdin**, terminated with a single newline (`\n`).
+- The client waits for the process to exit, up to the timeout. **Stdout** and **stderr** are captured; non-empty stdout is logged at INFO (see debug flag above). A non-zero exit or timeout is logged as a failure.
+
+### Envelope
+
+```json
+{
+  "event": "message_received | message_send",
+  "version": 1,
+  "message": { }
+}
+```
+
+- **`version`:** Integer. Incremented when incompatible payload changes are introduced; until then, treat as `1`.
+- **`event`:**
+  - **`message_received`:** Fired for each inbound `shared.Message` on the chat WebSocket path after the client has applied decrypt when E2E is on. Typing is **excluded** unless `MARCHAT_CLIENT_HOOK_RECEIVE_TYPING` is enabled.
+  - **`message_send`:** Fired for outbound text from the main composer path: global plaintext, global E2E (plaintext before encrypt), DMs, and `:` server/admin lines sent as `AdminCommandType`. Other UI actions (e.g. code snippet, file picker) may not invoke the send hook.
+
+### `message` object
+
+Mirrors [`shared.Message`](shared/types.go) fields where applicable, as a JSON object:
+
+| Field | Notes |
+|-------|--------|
+| `type` | e.g. `text`, `dm`, `typing`, `reaction`, `admin_command`, … May be empty if the server omitted it on older history. |
+| `sender`, `content`, `encrypted`, `message_id`, `recipient`, `edited`, `channel` | Same meaning as wire types. |
+| `created_at` | RFC3339 nano UTC. **Omitted** when the client has no real timestamp (zero time), so you will not see `0001-01-01` sentinels. |
+| `reaction` | Present for reaction events (`emoji`, `target_id`, `is_removal`). |
+| `file` | For file messages: `{ "filename", "size" }` only; no `data`. |
+
+Filter scripts on `message.type` / `event` as needed.
+
+## Example: append-only logger
+
+Build the bundled sample (from repo root):
+
+```bash
+go build -o /tmp/marchat-hook-log ./client/exthook/example_hook
+```
+
+Run the client with hooks (paths must be absolute on your OS):
+
+```bash
+export MARCHAT_CLIENT_HOOK_RECEIVE=/tmp/marchat-hook-log
+export MARCHAT_CLIENT_HOOK_SEND=/tmp/marchat-hook-log
+# Optional: override log path (otherwise uses $TMPDIR/marchat-client-hook.log)
+export MARCHAT_HOOK_LOG=$HOME/marchat-hook.log
+go run ./client
+```
+
+On Windows (PowerShell), use `Resolve-Path` for absolute paths and run `go run ./client` from the repository root (not `go run .`).
+
+## Use cases (illustrative)
+
+- Custom logging or archival to your own storage
+- Webhooks or bridges to other chat systems
+- Keyword-triggered local alerts beyond built-in notifications
+- Development and integration testing
+
+## Relationship to other systems
+
+| Mechanism | Where it runs | Typical use |
+|-----------|----------------|-------------|
+| Server plugins | Server | Commands, hub automation, shared bots |
+| Client hooks | Your machine | Personal automation, local pipelines |
+| Second WebSocket client | Your machine / elsewhere | Full bots, independent sessions |
+
+## Stability
+
+Treat this document and the `version` field as the reference for experiments. For production-like integrations, prefer discussing on GitHub issues so breaking changes can be coordinated.

README.md

@@ -280,7 +280,7 @@ The repository’s `config/` directory holds **server** runtime files and the **
 
 ### Diagnostics (`-doctor`)
 
-Run **`./marchat-client -doctor`** or **`./marchat-server -doctor`** for a text report (paths, redacted `MARCHAT_*` secrets as length-only, other env values as shown, sanity checks). **Server** doctor lists `MARCHAT_*` **after** loading the resolved config directory’s **`.env`** (same as the running server), so values are not limited to what your shell exported. **Client** doctor only shows variables present in the client process (it does not read the server’s `config/.env`). Server doctor also reports the detected DB dialect, validates the configured DB connection string format, and attempts a DB ping. On a **color-capable terminal** (stdout is a TTY), the text report uses **ANSI colors** aligned with the server pre-TUI banner; set **`NO_COLOR`** or redirect to a file/pipe for **plain** output. Use **`-doctor-json`** for machine-readable output (never colorized). If both flags were passed, `-doctor-json` wins. Exits without starting the TUI or listening on a port. See [ARCHITECTURE.md](ARCHITECTURE.md) for details.
+Run **`./marchat-client -doctor`** or **`./marchat-server -doctor`** for a text report (paths, redacted `MARCHAT_*` secrets as length-only, other env values as shown, sanity checks). **Server** doctor lists `MARCHAT_*` **after** loading the resolved config directory’s **`.env`** (same as the running server), so values are not limited to what your shell exported. **Client** doctor only shows variables present in the client process (it does not read the server’s `config/.env`); it also lists **experimental client hook** env vars and validates receive/send hook paths when set (see [CLIENT_HOOKS.md](CLIENT_HOOKS.md)). **Server** doctor does **not** list those client-only hook variables, even if they are set in the shell (for example when you run client and server from the same session). Server doctor also reports the detected DB dialect, validates the configured DB connection string format, and attempts a DB ping. On a **color-capable terminal** (stdout is a TTY), the text report uses **ANSI colors** aligned with the server pre-TUI banner; set **`NO_COLOR`** or redirect to a file/pipe for **plain** output. Use **`-doctor-json`** for machine-readable output (never colorized). If both flags were passed, `-doctor-json` wins. Exits without starting the TUI or listening on a port. See [ARCHITECTURE.md](ARCHITECTURE.md) for details.
 
 ## Admin Commands
 
@@ -675,6 +675,15 @@ Profiles stored in platform-appropriate locations:
 ./marchat-client --non-interactive --server ws://localhost:8080/ws --username alice
 ```
 
+## Advanced features
+
+### Experimental client hooks (local automation)
+
+The TUI client can spawn **optional** external programs on send/receive and pass one JSON line on stdin per event, useful for custom logging, bridges, or local tooling. This is **experimental** (protocol may change); it does not replace server plugins or built-in notifications.
+
+- **Documentation:** [CLIENT_HOOKS.md](CLIENT_HOOKS.md) (security model, env vars, JSON shape).
+- **Entrypoint:** from the repo root, `go run ./client` (the client lives in `client/`, not the repo root).
+
 ## Security Best Practices
 
 1. **Generate Secure Keys**
@@ -820,6 +829,7 @@ go test ./...
 - **[PROTOCOL.md](PROTOCOL.md)** - WebSocket message types and payloads
 - **[deploy/CADDY-REVERSE-PROXY.md](deploy/CADDY-REVERSE-PROXY.md)** - Optional TLS reverse proxy (Caddy) for local or LAN `wss://`
 - **[NOTIFICATIONS.md](NOTIFICATIONS.md)** - Notification system guide (desktop, quiet hours, focus mode)
+- **[CLIENT_HOOKS.md](CLIENT_HOOKS.md)** - Experimental client-side external hooks (local automation)
 - **[THEMES.md](THEMES.md)** - Custom theme creation guide
 - **[PLUGIN_ECOSYSTEM.md](PLUGIN_ECOSYSTEM.md)** - Plugin development guide
 - **[ROADMAP.md](ROADMAP.md)** - Planned features and enhancements

SECURITY.md

@@ -59,6 +59,10 @@ It **does not cover**:
 
 The `-doctor` / `-doctor-json` commands print masked values for sensitive `MARCHAT_*` variables; avoid sharing raw process environment dumps alongside doctor output. For air-gapped hosts, set `MARCHAT_DOCTOR_NO_NETWORK=1` so doctor does not call the GitHub API.
 
+### Experimental client hooks (local)
+
+Optional **`MARCHAT_CLIENT_HOOK_*`** settings run programs you choose on your machine with **decrypted message content** (receive) or **plaintext before send** (send). That does not break wire encryption, but it **extends trust** to those binaries and anything that can read their output or logs. Treat hook paths like running arbitrary executables. See **[CLIENT_HOOKS.md](CLIENT_HOOKS.md)** for the experimental protocol and env vars.
+
 ### Client global E2E key
 
 When the client **auto-generates** a global E2E key, it does **not** print the full base64 key to stdout (only a Key ID). Distribute the key using **`MARCHAT_GLOBAL_E2E_KEY`**, **`keystore.dat`** plus passphrase, or another channel you treat as confidential; do not rely on terminal output for key material.

client/exthook/example_hook/main.go

@@ -0,0 +1,49 @@
+// Example stdin hook: append each JSON line to a log file for spike testing.
+//
+// Build: go build -o marchat-hook-log ./client/exthook/example_hook
+// Run client from repo root: go run ./client  (not go run .)
+// Env: MARCHAT_CLIENT_HOOK_RECEIVE=C:\full\path\marchat-hook-log.exe (and/or MARCHAT_CLIENT_HOOK_SEND)
+//
+// Default log: $TEMP/marchat-client-hook.log (Windows) or /tmp/marchat-client-hook.log
+package main
+
+import (
+	"bufio"
+	"io"
+	"log"
+	"os"
+	"path/filepath"
+)
+
+func main() {
+	logPath := os.Getenv("MARCHAT_HOOK_LOG")
+	if logPath == "" {
+		if d := os.Getenv("TEMP"); d != "" {
+			logPath = filepath.Join(d, "marchat-client-hook.log")
+		} else if d := os.Getenv("TMPDIR"); d != "" {
+			logPath = filepath.Join(d, "marchat-client-hook.log")
+		} else {
+			logPath = filepath.Join(os.TempDir(), "marchat-client-hook.log")
+		}
+	}
+	f, err := os.OpenFile(logPath, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o644)
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer f.Close()
+
+	r := bufio.NewReader(os.Stdin)
+	line, err := r.ReadBytes('\n')
+	if err != nil && err != io.EOF {
+		log.Fatal(err)
+	}
+	if len(line) == 0 {
+		return
+	}
+	if _, err := f.Write(line); err != nil {
+		log.Fatal(err)
+	}
+	if line[len(line)-1] != '\n' {
+		_, _ = f.Write([]byte{'\n'})
+	}
+}