@zerotal/monitor 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog — @zerotal/monitor
+
+All notable changes to this package are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/); this package
+follows the Zerotal monorepo's unified versioning.
+
+**Maturity: `experimental`**
+
+## [Unreleased]
+
+## [1.0.0] — 2026-08-05
+
+_First public release._
+
+### Notes
+
+- Conforms to the Zerotal package conventions (provider in `src/provider/`, PascalCase config factory, `ZerotalError`-based errors, test coverage).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zerotal
+
+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/README.md

@@ -0,0 +1,174 @@
+# @zerotal/monitor
+
+A production monitoring & queue dashboard for Zerotal — the "Super Panel". It
+closes the _Prod monitoring dashboard_ gap in [`audit.md`](../../docs/audit.md): the
+framework already collects the data (telemetry, health, queues), this package
+gives it a UI.
+
+It's a server-driven **Flow** panel: component classes render on the server,
+interactions round-trip over the Flow WebSocket, no client store or API layer.
+Eight tabs, faithful to `super-panel.html`:
+
+**Overview · Requests · Exceptions · Queues · Mail · Database · Cache · System**
+
+## Install
+
+It's a workspace package. Add the provider after `FlowProvider`:
+
+```ts
+// bootstrap/providers.ts
+import { FlowProvider } from "@zerotal/flow";
+import { MonitorProvider } from "@zerotal/monitor";
+
+export default [FlowProvider, MonitorProvider];
+```
+
+Visit `/monitor`. That's it — every panel is populated out of the box.
+
+## Configure
+
+```ts
+// config/monitor.ts
+import { MonitorConfig } from "@zerotal/monitor";
+
+export default MonitorConfig({
+  path: "/monitor",
+  title: "Super Panel",
+  // Gate access. Default: allowed outside production only.
+  auth: (user) => user?.role === "admin",
+  record: true, // install the FrameworkEvents recorder
+  refreshMs: 3000, // live auto-refresh cadence
+  apdexTargetMs: 100, // Apdex satisfaction threshold (T)
+  slowQueryMs: 100, // "slow query" cut-off
+  slowRequestMs: 1000, // "slow request" cut-off (Slow Requests widget)
+  storage: "storage/monitor.sqlite", // bun:sqlite file (':memory:' for ephemeral)
+  retentionDays: 7, // history kept before pruning
+  retentionMode: "delete", // 'delete' or 'archive' past retention
+  metrics: true, // Prometheus endpoint
+  metricsPath: "/metrics",
+  alerts: true, // threshold alerts (see below)
+  alertThresholds: { errorRatePct: 5, p95Ms: 2000, queuePending: 500 },
+});
+```
+
+## Persistence & retention
+
+The panel persists every sample to **`bun:sqlite`**, so the **live / 1h / 24h / 7d**
+ranges trace real history and **survive restarts** — not just whatever happened
+since boot. Each event stream (requests, queries, exceptions, HTTP, cache, mail,
+jobs) is a timestamped table; `snapshot(range)` reads the rows inside the selected
+window, so every panel is range-consistent.
+
+Data older than `retentionDays` is pruned hourly (and on boot). With
+`retentionMode: 'archive'` the rows are moved to `*_archive` tables instead of being
+deleted, for cold storage. The **System tab** shows live row counts and the oldest
+record, plus two controls:
+
+- **Clean up now** — prune past-retention data immediately.
+- **Clear all** — wipe every recorded sample (with a confirm prompt).
+
+Both are also available programmatically on the store: `store.prune()`,
+`store.wipe()`, `store.storageInfo()`.
+
+## How data flows
+
+Everything is driven by core's `FrameworkEvents` bus — the same substrate the
+logger and telemetry read. One subscriber (`installMonitorEventBridge`) feeds every
+panel; there is **no sample data**. A quiet app shows honest zeros, never fabricated
+traffic.
+
+| Panel                                                                                                                                                                  | Event mapped                                                                           |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Requests, latency p50/p95/p99, throughput, error rate, Apdex, slow routes                                                                                              | `RequestHandled` / `RequestFailed`                                                     |
+| Per-request user, IP, memory; slow requests, top users, top-memory routes                                                                                              | `RequestHandled` (+ `ctx.user` / `ctx.ip()`)                                           |
+| Per-request SQL queries (correlated by HttpContext) + N+1 flag                                                                                                         | `QueryExecuted` / `NPlusOneDetected`                                                   |
+| Exceptions (grouped by type + route)                                                                                                                                   | `RequestFailed`                                                                        |
+| Slow queries + DB stats                                                                                                                                                | `QueryExecuted`                                                                        |
+| Cache hit-rate + hot keys                                                                                                                                              | `CacheQueried`                                                                         |
+| Sent / queued / failed mail                                                                                                                                            | `MessageSent` / `MessageFailed`                                                        |
+| Outgoing HTTP — per-host calls, p95, error rate                                                                                                                        | `OutgoingRequestCompleted`                                                             |
+| Job throughput + slowest jobs                                                                                                                                          | `JobRan`                                                                               |
+| **Realtime** — active WS connections, actions/min, busiest/slowest components, and per-action **user / IP / SQL queries** (Flow re-runs middleware on each round-trip) | `WebSocketConnected` / `WebSocketDisconnected` / `FlowActionHandled`                   |
+| **Security** — logins, logouts, denials, tokens                                                                                                                        | `LoginSucceeded` / `LoginFailed` / `LoggedOut` / `AuthorizationDenied` / `TokenIssued` |
+| **Logs** — every entry, level-filterable, request-correlated                                                                                                           | `LogManager.tap` (core logger)                                                         |
+| **Database** — transactions, migrations, N+1 offenders                                                                                                                 | `TransactionCommitted` / `TransactionRolledBack` / `MigrationRan` / `NPlusOneDetected` |
+| Cache evictions                                                                                                                                                        | `CacheEvicted`                                                                         |
+| Scheduled-task run history + check-ins                                                                                                                                 | `TaskRan` / `TaskFailed` / `TaskSkipped` (+ `@zerotal/scheduler`)                      |
+| Queues, workers, failed jobs (+ retry)                                                                                                                                 | `@zerotal/queue` (if installed)                                                        |
+| Health, CPU/memory gauges, uptime, deploy SHA                                                                                                                          | `Health` + process + git/env                                                           |
+
+For anything outside the event bus (a deploy marker, a third-party call you make
+without the `Http` client), the `Monitor` facade still works and takes precedence:
+
+```ts
+import { Monitor } from "@zerotal/monitor";
+
+Monitor.recordDeploy(gitSha);
+Monitor.recordHttp({ host: "api.stripe.com", ms: 412, error: false });
+
+// Attach metadata to the current request/action — shows on its trace:
+Monitor.context({ tenant: tenant.id, plan: user.plan });
+```
+
+Every `Monitor.*` call is a no-op until the provider boots, so it's safe to call
+unconditionally from anywhere.
+
+## Prometheus
+
+A Prometheus text-exposition endpoint is served at **`/metrics`** (on by default;
+configure with `metrics` / `metricsPath`). It exports HTTP counters (cumulative
+since boot), latency/Apdex/cache/queue/WS/exception gauges, system gauges, and
+per-route latency — ready for Grafana and Alertmanager. Protect the path at the
+network layer; it isn't behind the panel's auth so scrapers can reach it.
+
+```
+zerotal_http_requests_total 1284
+zerotal_http_request_duration_ms_p95 318
+zerotal_apdex 0.94
+zerotal_ws_connections 12
+zerotal_route_duration_ms_avg{method="GET",route="/dashboard"} 612
+```
+
+## Alerting
+
+Threshold alerts (error-rate spike, slow p95, queue backlog, transaction
+rollbacks) are evaluated every 15s, edge-triggered (each fires once when it
+crosses, resets on recovery). A firing alert is logged, recorded (so it shows in
+the panel), and dispatched to any handlers you register — wire those to
+notifications:
+
+```ts
+import { onAlert } from "@zerotal/monitor";
+import { Notification } from "@zerotal/notifications";
+
+onAlert((alert) => Notification.route("slack", SLACK_WEBHOOK).notify(new OpsAlert(alert)));
+```
+
+Tune via config: `alerts: true`, `alertThresholds: { errorRatePct: 5, p95Ms: 2000, queuePending: 500 }`.
+
+## Architecture
+
+```
+src/
+  MonitorStore.ts        aggregation: reads windowed rows from SQLite → MonitorSnapshot
+  store/                 MonitorDb (bun:sqlite persistence), percentile helpers, types
+  recorder/              MonitorEventBridge — the single FrameworkEvents → store subscriber
+  sources/               live adapters: queue, scheduler, health, system
+  facades/Monitor.ts     app-facing record* API
+  ui/
+    MonitorLayout.tsx    head (fonts, Tailwind), shell
+    MonitorPage.tsx      the Flow component — 8 tabs, all interactivity
+    charts.tsx           sparkline / area-chart SVG helpers
+    icons.ts, tones.ts   nav icons + value→colour helpers
+  provider/              MonitorProvider — binds store, middleware, route
+  config.ts              MonitorConfig()
+```
+
+> Tailwind is loaded from the Play CDN in `MonitorLayout` so the panel is styled
+> with zero build setup — fine for an internal ops tool. Swap it for a compiled
+> stylesheet in `MonitorLayout.head` for production hardening.
+
+## Status
+
+`maturity: experimental`. The live adapters degrade gracefully when an optional
+peer (`queue`, `scheduler`, `telemetry`) isn't installed.

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@zerotal/monitor",
+  "version": "1.0.0",
+  "license": "MIT",
+  "maturity": "experimental",
+  "private": false,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/__fixtures__/**"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zerotal/core": "1.0.0",
+    "@zerotal/flow-ui": "1.0.0",
+    "@zerotal/flow": "1.0.0"
+  },
+  "devDependencies": {
+    "@zerotal/queue": "1.0.0",
+    "@zerotal/scheduler": "1.0.0",
+    "@zerotal/telemetry": "1.0.0"
+  },
+  "peerDependencies": {
+    "@zerotal/queue": "^1.0.0",
+    "@zerotal/scheduler": "^1.0.0",
+    "@zerotal/telemetry": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@zerotal/queue": {
+      "optional": true
+    },
+    "@zerotal/scheduler": {
+      "optional": true
+    },
+    "@zerotal/telemetry": {
+      "optional": true
+    }
+  },
+  "description": "Operational monitoring panel and metrics for Zerotal — requests, exceptions, queries, and alerts.",
+  "keywords": [
+    "zerotal",
+    "bun",
+    "typescript",
+    "framework",
+    "monitoring",
+    "metrics",
+    "prometheus"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerotaldev/zerotal.git",
+    "directory": "packages/monitor"
+  },
+  "homepage": "https://github.com/zerotaldev/zerotal/tree/main/packages/monitor#readme",
+  "bugs": "https://github.com/zerotaldev/zerotal/issues"
+}