@pulse-labs/server-pulse 0.0.0-stage → 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.0.2] - 2026-10-15
+
+### Changed
+
+- README: step-by-step guide for using the package in a project (install, Express CommonJS/ESM/TypeScript, NestJS, dashboard credentials via environment variables, opening the dashboard, mounting rules, updating).
+
+## [0.0.1] - 2026-10-14
+
+First public preview on npm as `@pulse-labs/server-pulse`. Scaffold only: the middleware is a pass-through. (Briefly published as `@mukesh-singh9862/server-pulse`, which was unpublished.)
+
+### Added
+
+- Project scaffold: TypeScript build (tsup, CJS + ESM + types), Vitest 4, ESLint, Prettier, CI workflow.
+- `npm run smoke`: runner-free smoke test of the built package (also runs on Node 18.15 in CI).
+- Pass-through `serverPulse()` middleware with the public API surface.
+- `examples/express4-basic`.
+- MIT license; published publicly to npm under the `@pulse-labs` scope.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pulse-labs
+
+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

@@ -1,3 +1,201 @@
-# Temporary Holding Version
+# server-pulse
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Live server monitoring dashboard for Node.js apps, served from your own base URL (for example `https://api.example.com/monitor`).
+
+> **Status:** early preview (`0.0.x`, milestone M0 — project scaffold). The middleware is currently a pass-through and does not collect anything yet. Do not use it in production before `1.0.0`. Sections marked _TODO_ are completed in later milestones.
+
+## Use it in your project (step by step)
+
+> In `0.0.x` the setup below already installs and runs, but the dashboard at `/monitor` is not served yet. Your setup code stays the same when the full version is released.
+
+### Step 1: Check your Node.js version
+
+```bash
+node -v
+```
+
+You need Node.js **18.15 or newer**.
+
+### Step 2: Install the package
+
+Run this in your project folder (the one that contains your project's `package.json`):
+
+```bash
+npm install @pulse-labs/server-pulse
+```
+
+The package has **no runtime dependencies** and ships its own TypeScript types, so you don't need a separate `@types` package.
+
+### Step 3: Add it to your app
+
+Works with **Express 4 and Express 5** (the two current major versions of Express). The code is the same for both.
+
+**Express (CommonJS, `require`)**
+
+```js
+const express = require('express');
+const { serverPulse } = require('@pulse-labs/server-pulse');
+
+const app = express();
+
+const pulse = serverPulse({
+  auth: { username: process.env.PULSE_USER, password: process.env.PULSE_PASS },
+});
+app.use(pulse); // 1. must be the FIRST middleware
+
+app.use(express.json()); // 2. your other middleware comes after it
+app.get('/api/products', (req, res) => res.json([]));
+// ... your routes ...
+
+app.use(pulse.errorHandler()); // 3. optional, AFTER your routes: shows error messages in "Recent errors"
+
+app.listen(3000);
+```
+
+**Express with ESM or TypeScript (`import`)**
+
+```ts
+import express from 'express';
+import { serverPulse } from '@pulse-labs/server-pulse';
+
+const app = express();
+const pulse = serverPulse({
+  auth: { username: process.env.PULSE_USER!, password: process.env.PULSE_PASS! },
+});
+app.use(pulse);
+// ... your routes ...
+app.use(pulse.errorHandler());
+app.listen(3000);
+```
+
+**NestJS** (in `main.ts`; NestJS uses Express by default)
+
+```ts
+import { NestFactory } from '@nestjs/core';
+import { serverPulse } from '@pulse-labs/server-pulse';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  const pulse = serverPulse({
+    auth: { username: process.env.PULSE_USER!, password: process.env.PULSE_PASS! },
+  });
+  app.use(pulse);
+  // optional: call pulse.captureError(err, req) inside your global exception filter
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+### Step 4: Set the dashboard login
+
+Never write the username and password in your code. Use environment variables:
+
+| Variable       | Purpose                                                                                                  |
+| -------------- | -------------------------------------------------------------------------------------------------------- |
+| `PULSE_USER`   | Dashboard username                                                                                       |
+| `PULSE_PASS`   | Dashboard password (use a strong one)                                                                    |
+| `PULSE_SECRET` | Long random string that signs login sessions. If it is not set, everyone is logged out on every restart. |
+
+PowerShell (Windows):
+
+```powershell
+$env:PULSE_USER="admin"
+$env:PULSE_PASS="a-strong-password"
+$env:PULSE_SECRET="a-long-random-string"
+node server.js
+```
+
+macOS / Linux:
+
+```bash
+PULSE_USER=admin PULSE_PASS=a-strong-password PULSE_SECRET=a-long-random-string node server.js
+```
+
+Or in a `.env` file, if your project uses [dotenv](https://www.npmjs.com/package/dotenv). Do not commit the `.env` file to git.
+
+```dotenv
+PULSE_USER=admin
+PULSE_PASS=a-strong-password
+PULSE_SECRET=a-long-random-string
+```
+
+To create a random secret: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`
+
+### Step 5: Open the dashboard
+
+```text
+http://localhost:3000/monitor
+```
+
+Sign in with `PULSE_USER` / `PULSE_PASS`. In production this is your API's own URL, for example `https://api.example.com/monitor`. Serve it over HTTPS.
+
+### Rules to follow
+
+1. Register `app.use(pulse)` **first**, at the application root, before any other middleware, especially before `compression()` (compression buffers the live updates).
+2. Do **not** mount it under a sub-path: `app.use('/admin', pulse)` is not supported. To change the URL, use the `basePath` option instead:
+
+   ```js
+   serverPulse({ basePath: '/admin/monitor', auth: { username: '...', password: '...' } });
+   ```
+
+3. Call `serverPulse()` only once per process and reuse the returned `pulse` object.
+
+### Update to a newer version
+
+```bash
+npm install @pulse-labs/server-pulse@latest   # update
+npm ls @pulse-labs/server-pulse               # show the installed version
+```
+
+## PM2 cluster
+
+_TODO (M9). The monitor process is started with `./node_modules/@pulse-labs/server-pulse/dist/cli.cjs monitor --port 9100`._
+
+## Options
+
+_TODO (M2)._
+
+## Environment variables
+
+_TODO (M2)._
+
+## Nginx
+
+_TODO._
+
+## Security notes
+
+_TODO._
+
+## Troubleshooting
+
+_TODO._
+
+## Development
+
+```bash
+npm install
+npm run build      # tsup + copy src/ui to dist/ui
+npm test           # vitest
+npm run lint
+npm run typecheck
+npm run smoke      # smoke test of the built package
+```
+
+## Publishing
+
+Published publicly to npm as `@pulse-labs/server-pulse` (MIT).
+
+```bash
+npm login                 # once per machine
+npm whoami                # your account must be a member of the pulse-labs npm organization
+npm pack --dry-run        # review the files that will be published
+npm publish               # runs lint, typecheck and tests first (prepublishOnly)
+```
+
+Next release: `npm version patch|minor|major` (updates package.json and creates a git tag), update CHANGELOG.md, then `npm publish`. A published version number can never be reused, even after unpublishing.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/dist/cli.cjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+"use strict";
+
+// package.json
+var version = "0.0.2";
+
+// src/cli.ts
+var USAGE = `server-pulse ${version}
+
+Usage:
+  server-pulse monitor [--port 9100] [--host 127.0.0.1]
+`;
+function main(argv) {
+  const [command] = argv;
+  if (command === "--version" || command === "-v") {
+    process.stdout.write(version + "\n");
+    return 0;
+  }
+  if (command === "monitor") {
+    process.stderr.write("server-pulse: the monitor command is not implemented yet.\n");
+    return 1;
+  }
+  process.stdout.write(USAGE);
+  return command === void 0 || command === "--help" || command === "-h" ? 0 : 1;
+}
+process.exitCode = main(process.argv.slice(2));
+//# sourceMappingURL=cli.cjs.map

package/dist/cli.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../package.json","../src/cli.ts"],"sourcesContent":["{\n  \"name\": \"@pulse-labs/server-pulse\",\n  \"version\": \"0.0.2\",\n  \"license\": \"MIT\",\n  \"description\": \"Live server monitoring dashboard for Node.js apps, served from your own base URL.\",\n  \"engines\": {\n    \"node\": \">=18.15\"\n  },\n  \"type\": \"commonjs\",\n  \"main\": \"./dist/index.cjs\",\n  \"module\": \"./dist/index.mjs\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"import\": {\n        \"types\": \"./dist/index.d.mts\",\n        \"default\": \"./dist/index.mjs\"\n      },\n      \"require\": {\n        \"types\": \"./dist/index.d.ts\",\n        \"default\": \"./dist/index.cjs\"\n      }\n    },\n    \"./package.json\": \"./package.json\"\n  },\n  \"bin\": {\n    \"server-pulse\": \"dist/cli.cjs\"\n  },\n  \"files\": [\n    \"dist\",\n    \"README.md\",\n    \"CHANGELOG.md\"\n  ],\n  \"publishConfig\": {\n    \"access\": \"public\"\n  },\n  \"scripts\": {\n    \"build\": \"tsup && node scripts/copy-ui.mjs\",\n    \"prepare\": \"npm run build\",\n    \"prepublishOnly\": \"npm run lint && npm run typecheck && npm test\",\n    \"dev\": \"tsup --watch\",\n    \"lint\": \"eslint .\",\n    \"format\": \"prettier --write .\",\n    \"typecheck\": \"tsc --noEmit\",\n    \"test\": \"vitest run\",\n    \"test:watch\": \"vitest\",\n    \"smoke\": \"node scripts/smoke-dist.mjs\",\n    \"test:pm2\": \"vitest run test/integration/pm2.test.ts\",\n    \"test:ui\": \"node test/ui/run.mjs\",\n    \"bench\": \"node bench/overhead.mjs\"\n  },\n  \"peerDependencies\": {\n    \"pm2\": \">=5\"\n  },\n  \"peerDependenciesMeta\": {\n    \"pm2\": {\n      \"optional\": true\n    }\n  },\n  \"devDependencies\": {\n    \"@eslint/js\": \"^9.39.5\",\n    \"@types/express\": \"^5.0.6\",\n    \"@types/node\": \"^20.19.43\",\n    \"@types/supertest\": \"^7.2.1\",\n    \"@vitest/coverage-v8\": \"^4.1.11\",\n    \"eslint\": \"^9.39.5\",\n    \"express4\": \"npm:express@^4.22.3\",\n    \"express5\": \"npm:express@^5.3.0\",\n    \"globals\": \"^17.13.0\",\n    \"prettier\": \"^3.9.10\",\n    \"supertest\": \"^7.3.1\",\n    \"tsup\": \"^8.5.1\",\n    \"typescript\": \"~5.9.3\",\n    \"typescript-eslint\": \"^8.71.2\",\n    \"vite\": \"^6.4.4\",\n    \"vitest\": \"^4.1.11\"\n  },\n  \"overrides\": {\n    \"tsup\": {\n      \"esbuild\": \"^0.28.2\",\n      \"bundle-require\": {\n        \"esbuild\": \"^0.28.2\"\n      }\n    }\n  },\n  \"keywords\": [\n    \"monitoring\",\n    \"dashboard\",\n    \"express\",\n    \"nestjs\",\n    \"pm2\",\n    \"metrics\",\n    \"sse\"\n  ]\n}\n","#!/usr/bin/env node\n// `server-pulse monitor [--port 9100] [--host 127.0.0.1]` — the PM2 monitor process (spec 11.4).\n// M0 scaffold: argument handling only; the monitor itself is implemented in M9.\nimport { version } from '../package.json';\n\nconst USAGE = `server-pulse ${version}\n\nUsage:\n  server-pulse monitor [--port 9100] [--host 127.0.0.1]\n`;\n\nfunction main(argv: string[]): number {\n  const [command] = argv;\n  if (command === '--version' || command === '-v') {\n    process.stdout.write(version + '\\n');\n    return 0;\n  }\n  if (command === 'monitor') {\n    process.stderr.write('server-pulse: the monitor command is not implemented yet.\\n');\n    return 1;\n  }\n  process.stdout.write(USAGE);\n  return command === undefined || command === '--help' || command === '-h' ? 0 : 1;\n}\n\nprocess.exitCode = main(process.argv.slice(2));\n"],"mappings":";;;;AAEE,cAAW;;;ACGb,IAAM,QAAQ,gBAAgB,OAAO;AAAA;AAAA;AAAA;AAAA;AAMrC,SAAS,KAAK,MAAwB;AACpC,QAAM,CAAC,OAAO,IAAI;AAClB,MAAI,YAAY,eAAe,YAAY,MAAM;AAC/C,YAAQ,OAAO,MAAM,UAAU,IAAI;AACnC,WAAO;AAAA,EACT;AACA,MAAI,YAAY,WAAW;AACzB,YAAQ,OAAO,MAAM,6DAA6D;AAClF,WAAO;AAAA,EACT;AACA,UAAQ,OAAO,MAAM,KAAK;AAC1B,SAAO,YAAY,UAAa,YAAY,YAAY,YAAY,OAAO,IAAI;AACjF;AAEA,QAAQ,WAAW,KAAK,QAAQ,KAAK,MAAM,CAAC,CAAC;","names":[]}

package/dist/cli.d.mts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
+};
+var __commonJS = (cb, mod) => function __require() {
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
+};
+
+// node_modules/tsup/assets/esm_shims.js
+import path from "path";
+import { fileURLToPath } from "url";
+var init_esm_shims = __esm({
+  "node_modules/tsup/assets/esm_shims.js"() {
+    "use strict";
+  }
+});
+
+// package.json
+var version;
+var init_package = __esm({
+  "package.json"() {
+    version = "0.0.2";
+  }
+});
+
+// src/cli.ts
+var require_cli = __commonJS({
+  "src/cli.ts"() {
+    init_esm_shims();
+    init_package();
+    var USAGE = `server-pulse ${version}
+
+Usage:
+  server-pulse monitor [--port 9100] [--host 127.0.0.1]
+`;
+    function main(argv) {
+      const [command] = argv;
+      if (command === "--version" || command === "-v") {
+        process.stdout.write(version + "\n");
+        return 0;
+      }
+      if (command === "monitor") {
+        process.stderr.write("server-pulse: the monitor command is not implemented yet.\n");
+        return 1;
+      }
+      process.stdout.write(USAGE);
+      return command === void 0 || command === "--help" || command === "-h" ? 0 : 1;
+    }
+    process.exitCode = main(process.argv.slice(2));
+  }
+});
+export default require_cli();
+//# sourceMappingURL=cli.mjs.map

package/dist/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../node_modules/tsup/assets/esm_shims.js","../package.json","../src/cli.ts"],"sourcesContent":["// Shim globals in esm bundle\nimport path from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\nconst getFilename = () => fileURLToPath(import.meta.url)\nconst getDirname = () => path.dirname(getFilename())\n\nexport const __dirname = /* @__PURE__ */ getDirname()\nexport const __filename = /* @__PURE__ */ getFilename()\n","{\n  \"name\": \"@pulse-labs/server-pulse\",\n  \"version\": \"0.0.2\",\n  \"license\": \"MIT\",\n  \"description\": \"Live server monitoring dashboard for Node.js apps, served from your own base URL.\",\n  \"engines\": {\n    \"node\": \">=18.15\"\n  },\n  \"type\": \"commonjs\",\n  \"main\": \"./dist/index.cjs\",\n  \"module\": \"./dist/index.mjs\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"import\": {\n        \"types\": \"./dist/index.d.mts\",\n        \"default\": \"./dist/index.mjs\"\n      },\n      \"require\": {\n        \"types\": \"./dist/index.d.ts\",\n        \"default\": \"./dist/index.cjs\"\n      }\n    },\n    \"./package.json\": \"./package.json\"\n  },\n  \"bin\": {\n    \"server-pulse\": \"dist/cli.cjs\"\n  },\n  \"files\": [\n    \"dist\",\n    \"README.md\",\n    \"CHANGELOG.md\"\n  ],\n  \"publishConfig\": {\n    \"access\": \"public\"\n  },\n  \"scripts\": {\n    \"build\": \"tsup && node scripts/copy-ui.mjs\",\n    \"prepare\": \"npm run build\",\n    \"prepublishOnly\": \"npm run lint && npm run typecheck && npm test\",\n    \"dev\": \"tsup --watch\",\n    \"lint\": \"eslint .\",\n    \"format\": \"prettier --write .\",\n    \"typecheck\": \"tsc --noEmit\",\n    \"test\": \"vitest run\",\n    \"test:watch\": \"vitest\",\n    \"smoke\": \"node scripts/smoke-dist.mjs\",\n    \"test:pm2\": \"vitest run test/integration/pm2.test.ts\",\n    \"test:ui\": \"node test/ui/run.mjs\",\n    \"bench\": \"node bench/overhead.mjs\"\n  },\n  \"peerDependencies\": {\n    \"pm2\": \">=5\"\n  },\n  \"peerDependenciesMeta\": {\n    \"pm2\": {\n      \"optional\": true\n    }\n  },\n  \"devDependencies\": {\n    \"@eslint/js\": \"^9.39.5\",\n    \"@types/express\": \"^5.0.6\",\n    \"@types/node\": \"^20.19.43\",\n    \"@types/supertest\": \"^7.2.1\",\n    \"@vitest/coverage-v8\": \"^4.1.11\",\n    \"eslint\": \"^9.39.5\",\n    \"express4\": \"npm:express@^4.22.3\",\n    \"express5\": \"npm:express@^5.3.0\",\n    \"globals\": \"^17.13.0\",\n    \"prettier\": \"^3.9.10\",\n    \"supertest\": \"^7.3.1\",\n    \"tsup\": \"^8.5.1\",\n    \"typescript\": \"~5.9.3\",\n    \"typescript-eslint\": \"^8.71.2\",\n    \"vite\": \"^6.4.4\",\n    \"vitest\": \"^4.1.11\"\n  },\n  \"overrides\": {\n    \"tsup\": {\n      \"esbuild\": \"^0.28.2\",\n      \"bundle-require\": {\n        \"esbuild\": \"^0.28.2\"\n      }\n    }\n  },\n  \"keywords\": [\n    \"monitoring\",\n    \"dashboard\",\n    \"express\",\n    \"nestjs\",\n    \"pm2\",\n    \"metrics\",\n    \"sse\"\n  ]\n}\n","#!/usr/bin/env node\n// `server-pulse monitor [--port 9100] [--host 127.0.0.1]` — the PM2 monitor process (spec 11.4).\n// M0 scaffold: argument handling only; the monitor itself is implemented in M9.\nimport { version } from '../package.json';\n\nconst USAGE = `server-pulse ${version}\n\nUsage:\n  server-pulse monitor [--port 9100] [--host 127.0.0.1]\n`;\n\nfunction main(argv: string[]): number {\n  const [command] = argv;\n  if (command === '--version' || command === '-v') {\n    process.stdout.write(version + '\\n');\n    return 0;\n  }\n  if (command === 'monitor') {\n    process.stderr.write('server-pulse: the monitor command is not implemented yet.\\n');\n    return 1;\n  }\n  process.stdout.write(USAGE);\n  return command === undefined || command === '--help' || command === '-h' ? 0 : 1;\n}\n\nprocess.exitCode = main(process.argv.slice(2));\n"],"mappings":";;;;;;;;;;;;;;;;;;;AACA,OAAO,UAAU;AACjB,SAAS,qBAAqB;AAF9B;AAAA;AAAA;AAAA;AAAA;;;ACAA,IAEE;AAFF;AAAA;AAEE,cAAW;AAAA;AAAA;;;ACFb;AAAA;AAAA;AAGA;AAEA,QAAM,QAAQ,gBAAgB,OAAO;AAAA;AAAA;AAAA;AAAA;AAMrC,aAAS,KAAK,MAAwB;AACpC,YAAM,CAAC,OAAO,IAAI;AAClB,UAAI,YAAY,eAAe,YAAY,MAAM;AAC/C,gBAAQ,OAAO,MAAM,UAAU,IAAI;AACnC,eAAO;AAAA,MACT;AACA,UAAI,YAAY,WAAW;AACzB,gBAAQ,OAAO,MAAM,6DAA6D;AAClF,eAAO;AAAA,MACT;AACA,cAAQ,OAAO,MAAM,KAAK;AAC1B,aAAO,YAAY,UAAa,YAAY,YAAY,YAAY,OAAO,IAAI;AAAA,IACjF;AAEA,YAAQ,WAAW,KAAK,QAAQ,KAAK,MAAM,CAAC,CAAC;AAAA;AAAA;","names":[]}

package/dist/index.cjs

@@ -0,0 +1,95 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  serverPulse: () => serverPulse
+});
+module.exports = __toCommonJS(index_exports);
+var import_node_os = __toESM(require("os"));
+
+// package.json
+var version = "0.0.2";
+
+// src/index.ts
+var DEFAULT_THRESHOLDS = {
+  cpuPercent: [70, 85],
+  memoryPercent: [75, 90],
+  diskPercent: [80, 90],
+  heapPercent: [70, 85],
+  eventLoopLagMs: [50, 100],
+  errorRatePercent: [1, 3]
+};
+var BUCKETS_WIRE = [5, 10, 25, 50, 75, 100, 150, 250, 350, 500, 750, 1e3, 1500, 2500, 5e3, 1e4, 3e4, null];
+function serverPulse(_options) {
+  const startedAt = Date.now();
+  const middleware = ((_req, _res, next) => {
+    next();
+  });
+  middleware.errorHandler = () => (err, _req, _res, next) => next(err);
+  middleware.captureError = () => {
+  };
+  middleware.snapshot = () => ({
+    meta: {
+      version,
+      title: import_node_os.default.hostname(),
+      host: import_node_os.default.hostname(),
+      node: process.version,
+      platform: process.platform,
+      mode: "memory",
+      workers: 1,
+      appStartedAt: Math.round(Date.now() - process.uptime() * 1e3),
+      monitorStartedAt: startedAt,
+      cores: import_node_os.default.availableParallelism?.() ?? import_node_os.default.cpus().length
+    },
+    config: {
+      buckets: [...BUCKETS_WIRE],
+      defaultTargetMs: 500,
+      apdexThresholdMs: 300,
+      thresholds: structuredClone(DEFAULT_THRESHOLDS),
+      windowSeconds: 900,
+      user: ""
+    },
+    totals: { requests: 0, since: startedAt },
+    history: [],
+    routes: [],
+    workers: [],
+    errors: []
+  });
+  middleware.stop = async () => {
+  };
+  Object.defineProperty(middleware, "mode", { value: "disabled", enumerable: true });
+  return middleware;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  serverPulse
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../package.json"],"sourcesContent":["import type { IncomingMessage, ServerResponse } from 'node:http';\nimport os from 'node:os';\nimport type { ServerPulseOptions, Thresholds } from './options';\nimport type { InitPayload, TickPayload } from './engine/payloads';\nimport { version } from '../package.json';\n\nexport interface ServerPulseMiddleware {\n  (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void): void;\n  /** Express error middleware that records the error, then calls next(err). */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  errorHandler(): (err: unknown, req: any, res: any, next: (err?: unknown) => void) => void;\n  /** Record an error manually (e.g. from a NestJS exception filter). */\n  captureError(err: unknown, req?: IncomingMessage): void;\n  /** Current snapshot (same shape as the SSE init payload). For tests and scripts. */\n  snapshot(): InitPayload;\n  /** Stop timers, close SSE connections, disable event loop monitoring. */\n  stop(): Promise<void>;\n  /** Resolved mode: 'memory' | 'pm2' | 'disabled'. */\n  readonly mode: 'memory' | 'pm2' | 'disabled';\n}\n\n// M0 scaffold: pass-through middleware. Collection, dashboard and PM2 mode arrive in later milestones.\nconst DEFAULT_THRESHOLDS: Thresholds = {\n  cpuPercent: [70, 85],\n  memoryPercent: [75, 90],\n  diskPercent: [80, 90],\n  heapPercent: [70, 85],\n  eventLoopLagMs: [50, 100],\n  errorRatePercent: [1, 3],\n};\n\nconst BUCKETS_WIRE = [5, 10, 25, 50, 75, 100, 150, 250, 350, 500, 750, 1000, 1500, 2500, 5000, 10000, 30000, null];\n\nexport function serverPulse(_options?: ServerPulseOptions): ServerPulseMiddleware {\n  const startedAt = Date.now();\n\n  const middleware = ((_req: IncomingMessage, _res: ServerResponse, next: (err?: unknown) => void) => {\n    next();\n  }) as ServerPulseMiddleware;\n\n  middleware.errorHandler = () => (err, _req, _res, next) => next(err);\n  middleware.captureError = () => {};\n  middleware.snapshot = () => ({\n    meta: {\n      version,\n      title: os.hostname(),\n      host: os.hostname(),\n      node: process.version,\n      platform: process.platform,\n      mode: 'memory',\n      workers: 1,\n      appStartedAt: Math.round(Date.now() - process.uptime() * 1000),\n      monitorStartedAt: startedAt,\n      cores: os.availableParallelism?.() ?? os.cpus().length,\n    },\n    config: {\n      buckets: [...BUCKETS_WIRE],\n      defaultTargetMs: 500,\n      apdexThresholdMs: 300,\n      thresholds: structuredClone(DEFAULT_THRESHOLDS),\n      windowSeconds: 900,\n      user: '',\n    },\n    totals: { requests: 0, since: startedAt },\n    history: [],\n    routes: [],\n    workers: [],\n    errors: [],\n  });\n  middleware.stop = async () => {};\n  Object.defineProperty(middleware, 'mode', { value: 'disabled', enumerable: true });\n\n  return middleware;\n}\n\nexport type { ServerPulseOptions, InitPayload, TickPayload };\n","{\n  \"name\": \"@pulse-labs/server-pulse\",\n  \"version\": \"0.0.2\",\n  \"license\": \"MIT\",\n  \"description\": \"Live server monitoring dashboard for Node.js apps, served from your own base URL.\",\n  \"engines\": {\n    \"node\": \">=18.15\"\n  },\n  \"type\": \"commonjs\",\n  \"main\": \"./dist/index.cjs\",\n  \"module\": \"./dist/index.mjs\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"import\": {\n        \"types\": \"./dist/index.d.mts\",\n        \"default\": \"./dist/index.mjs\"\n      },\n      \"require\": {\n        \"types\": \"./dist/index.d.ts\",\n        \"default\": \"./dist/index.cjs\"\n      }\n    },\n    \"./package.json\": \"./package.json\"\n  },\n  \"bin\": {\n    \"server-pulse\": \"dist/cli.cjs\"\n  },\n  \"files\": [\n    \"dist\",\n    \"README.md\",\n    \"CHANGELOG.md\"\n  ],\n  \"publishConfig\": {\n    \"access\": \"public\"\n  },\n  \"scripts\": {\n    \"build\": \"tsup && node scripts/copy-ui.mjs\",\n    \"prepare\": \"npm run build\",\n    \"prepublishOnly\": \"npm run lint && npm run typecheck && npm test\",\n    \"dev\": \"tsup --watch\",\n    \"lint\": \"eslint .\",\n    \"format\": \"prettier --write .\",\n    \"typecheck\": \"tsc --noEmit\",\n    \"test\": \"vitest run\",\n    \"test:watch\": \"vitest\",\n    \"smoke\": \"node scripts/smoke-dist.mjs\",\n    \"test:pm2\": \"vitest run test/integration/pm2.test.ts\",\n    \"test:ui\": \"node test/ui/run.mjs\",\n    \"bench\": \"node bench/overhead.mjs\"\n  },\n  \"peerDependencies\": {\n    \"pm2\": \">=5\"\n  },\n  \"peerDependenciesMeta\": {\n    \"pm2\": {\n      \"optional\": true\n    }\n  },\n  \"devDependencies\": {\n    \"@eslint/js\": \"^9.39.5\",\n    \"@types/express\": \"^5.0.6\",\n    \"@types/node\": \"^20.19.43\",\n    \"@types/supertest\": \"^7.2.1\",\n    \"@vitest/coverage-v8\": \"^4.1.11\",\n    \"eslint\": \"^9.39.5\",\n    \"express4\": \"npm:express@^4.22.3\",\n    \"express5\": \"npm:express@^5.3.0\",\n    \"globals\": \"^17.13.0\",\n    \"prettier\": \"^3.9.10\",\n    \"supertest\": \"^7.3.1\",\n    \"tsup\": \"^8.5.1\",\n    \"typescript\": \"~5.9.3\",\n    \"typescript-eslint\": \"^8.71.2\",\n    \"vite\": \"^6.4.4\",\n    \"vitest\": \"^4.1.11\"\n  },\n  \"overrides\": {\n    \"tsup\": {\n      \"esbuild\": \"^0.28.2\",\n      \"bundle-require\": {\n        \"esbuild\": \"^0.28.2\"\n      }\n    }\n  },\n  \"keywords\": [\n    \"monitoring\",\n    \"dashboard\",\n    \"express\",\n    \"nestjs\",\n    \"pm2\",\n    \"metrics\",\n    \"sse\"\n  ]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AACA,qBAAe;;;ACCb,cAAW;;;ADoBb,IAAM,qBAAiC;AAAA,EACrC,YAAY,CAAC,IAAI,EAAE;AAAA,EACnB,eAAe,CAAC,IAAI,EAAE;AAAA,EACtB,aAAa,CAAC,IAAI,EAAE;AAAA,EACpB,aAAa,CAAC,IAAI,EAAE;AAAA,EACpB,gBAAgB,CAAC,IAAI,GAAG;AAAA,EACxB,kBAAkB,CAAC,GAAG,CAAC;AACzB;AAEA,IAAM,eAAe,CAAC,GAAG,IAAI,IAAI,IAAI,IAAI,KAAK,KAAK,KAAK,KAAK,KAAK,KAAK,KAAM,MAAM,MAAM,KAAM,KAAO,KAAO,IAAI;AAE1G,SAAS,YAAY,UAAsD;AAChF,QAAM,YAAY,KAAK,IAAI;AAE3B,QAAM,cAAc,CAAC,MAAuB,MAAsB,SAAkC;AAClG,SAAK;AAAA,EACP;AAEA,aAAW,eAAe,MAAM,CAAC,KAAK,MAAM,MAAM,SAAS,KAAK,GAAG;AACnE,aAAW,eAAe,MAAM;AAAA,EAAC;AACjC,aAAW,WAAW,OAAO;AAAA,IAC3B,MAAM;AAAA,MACJ;AAAA,MACA,OAAO,eAAAA,QAAG,SAAS;AAAA,MACnB,MAAM,eAAAA,QAAG,SAAS;AAAA,MAClB,MAAM,QAAQ;AAAA,MACd,UAAU,QAAQ;AAAA,MAClB,MAAM;AAAA,MACN,SAAS;AAAA,MACT,cAAc,KAAK,MAAM,KAAK,IAAI,IAAI,QAAQ,OAAO,IAAI,GAAI;AAAA,MAC7D,kBAAkB;AAAA,MAClB,OAAO,eAAAA,QAAG,uBAAuB,KAAK,eAAAA,QAAG,KAAK,EAAE;AAAA,IAClD;AAAA,IACA,QAAQ;AAAA,MACN,SAAS,CAAC,GAAG,YAAY;AAAA,MACzB,iBAAiB;AAAA,MACjB,kBAAkB;AAAA,MAClB,YAAY,gBAAgB,kBAAkB;AAAA,MAC9C,eAAe;AAAA,MACf,MAAM;AAAA,IACR;AAAA,IACA,QAAQ,EAAE,UAAU,GAAG,OAAO,UAAU;AAAA,IACxC,SAAS,CAAC;AAAA,IACV,QAAQ,CAAC;AAAA,IACT,SAAS,CAAC;AAAA,IACV,QAAQ,CAAC;AAAA,EACX;AACA,aAAW,OAAO,YAAY;AAAA,EAAC;AAC/B,SAAO,eAAe,YAAY,QAAQ,EAAE,OAAO,YAAY,YAAY,KAAK,CAAC;AAEjF,SAAO;AACT;","names":["os"]}

package/dist/index.d.mts

@@ -0,0 +1,244 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+/** Warning / danger thresholds used for colours and the health badge (spec 4.3). */
+interface Thresholds {
+    /** Default [70, 85]. */
+    cpuPercent: [warn: number, danger: number];
+    /** Default [75, 90]. */
+    memoryPercent: [warn: number, danger: number];
+    /** Default [80, 90]. */
+    diskPercent: [warn: number, danger: number];
+    /** Default [70, 85] (of heap_size_limit). */
+    heapPercent: [warn: number, danger: number];
+    /** Default [50, 100] (p99 per second). */
+    eventLoopLagMs: [warn: number, danger: number];
+    /** Default [1, 3] (5xx share). */
+    errorRatePercent: [warn: number, danger: number];
+}
+interface AuthCommon {
+    sessionSecret?: string;
+    sessionTtlMinutes?: number;
+    secureCookie?: 'auto' | boolean;
+}
+interface ServerPulseOptions {
+    /** Turn everything off (middleware becomes a pass-through). Default: true. Env: PULSE_ENABLED=false */
+    enabled?: boolean;
+    /** URL path of the dashboard. Default: '/monitor'. Must start with '/', no trailing slash. */
+    basePath?: string;
+    /** 'auto' | 'memory' | 'pm2'. Default: 'auto' (section 11.1). Env: PULSE_MODE */
+    mode?: 'auto' | 'memory' | 'pm2';
+    /**
+     * Dashboard credentials. Either one user, a list of users, or false.
+     * Env fallbacks: PULSE_USER, PULSE_PASS, PULSE_SECRET.
+     * false is only allowed when NODE_ENV !== 'production'.
+     */
+    auth?: ({
+        username: string;
+        password: string;
+    } & AuthCommon) | ({
+        users: Array<{
+            username: string;
+            password: string;
+        }>;
+    } & AuthCommon) | false;
+    /** Only these client IPs may reach the dashboard (exact IPv4/IPv6 or IPv4 CIDR). Others get 404. Default: allow all. */
+    ipAllowList?: string[];
+    /** Trust X-Forwarded-For / X-Forwarded-Proto (set true behind Nginx or a load balancer). Default: false. */
+    trustProxy?: boolean;
+    /** Extra requests to exclude from statistics. basePath is always excluded. */
+    ignore?: Array<string | RegExp | ((req: IncomingMessage) => boolean)>;
+    /** Apply the default ignore list (/health, /favicon.ico, static files). Default: true. */
+    ignoreDefaults?: boolean;
+    routes?: {
+        /** Per-route response-time targets in ms, keyed "METHOD /normalized/path". */
+        targets?: Record<string, number>;
+        /** Target for routes not listed above. Default: 500. */
+        defaultTargetMs?: number;
+        /** Maximum distinct routes tracked; extra routes go to "OTHER". Default: 500. */
+        maxRoutes?: number;
+        /** Custom normalizer; return null to fall back to the built-in one. */
+        normalize?: (req: IncomingMessage) => string | null;
+    };
+    /** Apdex threshold T in ms. Default: 300. */
+    apdexThresholdMs?: number;
+    /** Warning / danger thresholds used for colours and the health badge (section 4.3). */
+    thresholds?: Partial<Thresholds>;
+    /** Path used for the disk metric. Default: '/' (Windows: drive of process.cwd()). */
+    diskPath?: string;
+    pm2?: {
+        /** Monitor process host and port. Defaults: '127.0.0.1', 9100. Env: PULSE_MONITOR_HOST, PULSE_MONITOR_PORT */
+        monitorHost?: string;
+        monitorPort?: number;
+    };
+    ui?: {
+        /** Title shown in the header. Default: os.hostname(). */
+        title?: string;
+        /** Load IBM Plex Sans from Google Fonts. Default: false (system font stack, no external requests). */
+        webFonts?: boolean;
+    };
+    /** Optional health endpoint, outside basePath, no auth. Default: false. */
+    health?: false | {
+        path?: string;
+        checks?: Record<string, () => boolean | Promise<boolean>>;
+    };
+    /** Logger. Default: console with "[server-pulse]" prefix. */
+    logger?: Pick<Console, 'info' | 'warn' | 'error'>;
+}
+
+/** Histogram counts, length 18, in BUCKETS order. */
+type Hist = number[];
+/** One second of aggregated data (spec 7.1). */
+interface Tick {
+    /** Epoch ms, start of the second. */
+    t: number;
+    req: {
+        /** Finished requests in this second. */
+        total: number;
+        c2: number;
+        c3: number;
+        c4: number;
+        c5: number;
+        aborted: number;
+        /** Value at the end of the second. */
+        inFlight: number;
+    };
+    /** Per-second histograms. */
+    hist: {
+        all: Hist;
+        ok: Hist;
+        fail: Hist;
+    };
+    apdex: {
+        s: number;
+        t: number;
+        f: number;
+    };
+    sys: {
+        /** Percent. */
+        cpu: number;
+        /** Bytes. */
+        memUsed: number;
+        memTotal: number;
+        memKind: 'system' | 'container';
+        /** Bytes; null while the disk metric is unavailable (see DECISIONS.md). */
+        diskUsed: number | null;
+        diskTotal: number | null;
+        load1: number | null;
+    };
+    /** Aggregated for the resources panel. */
+    proc: {
+        /** Busiest worker. */
+        heapPct: number;
+        /** Bytes, busiest worker. */
+        heapUsed: number;
+        heapLimit: number;
+        /** Ms, worst worker. */
+        lagP99: number;
+    };
+}
+interface RouteRow {
+    key: string;
+    method: string;
+    path: string;
+    count: number;
+    rps: number;
+    avg: number;
+    p95: number | null;
+    target: number;
+    errRate: number;
+}
+interface WorkerRow {
+    /** pm_id */
+    id: number;
+    pid: number;
+    status: 'online' | 'blocked' | 'stale' | 'stopped' | 'errored';
+    /** % of one core. */
+    cpu: number;
+    heapUsed: number;
+    heapLimit: number;
+    lagP99: number;
+    /** Last 10 s. */
+    rps: number;
+    /** pm2_env.restart_time */
+    restarts: number;
+    uptimeSec: number;
+}
+interface ErrorEntry {
+    t: number;
+    method: string;
+    route: string;
+    status: number;
+    message: string;
+    worker: number | null;
+}
+/** SSE `init` event and `GET basePath/api/snapshot` (spec 7.2). */
+interface InitPayload {
+    meta: {
+        /** Package version. */
+        version: string;
+        /** ui.title or hostname. */
+        title: string;
+        host: string;
+        node: string;
+        platform: string;
+        mode: 'memory' | 'pm2';
+        /** 1 in memory mode. */
+        workers: number;
+        /** Epoch ms (oldest worker in PM2 mode). */
+        appStartedAt: number;
+        /** Epoch ms ("Requests since start" counts from here). */
+        monitorStartedAt: number;
+        cores: number;
+    };
+    config: {
+        /** BUCKETS, Infinity sent as null. */
+        buckets: Array<number | null>;
+        defaultTargetMs: number;
+        apdexThresholdMs: number;
+        thresholds: Thresholds;
+        windowSeconds: 900;
+        /** Logged-in username, shown in header menu. */
+        user: string;
+    };
+    totals: {
+        requests: number;
+        since: number;
+    };
+    /** Up to 900, oldest first. */
+    history: Tick[];
+    routes: RouteRow[];
+    /** Empty in memory mode. */
+    workers: WorkerRow[];
+    /** Newest first, up to 50. */
+    errors: ErrorEntry[];
+}
+/** SSE `tick` event, every second (spec 7.3). */
+interface TickPayload {
+    tick: Tick;
+    totals: {
+        requests: number;
+        since: number;
+    };
+    /** Full table (≤ maxRoutes rows). */
+    routes: RouteRow[];
+    workers: WorkerRow[];
+    /** Errors since previous tick. */
+    newErrors: ErrorEntry[];
+}
+
+interface ServerPulseMiddleware {
+    (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void): void;
+    /** Express error middleware that records the error, then calls next(err). */
+    errorHandler(): (err: unknown, req: any, res: any, next: (err?: unknown) => void) => void;
+    /** Record an error manually (e.g. from a NestJS exception filter). */
+    captureError(err: unknown, req?: IncomingMessage): void;
+    /** Current snapshot (same shape as the SSE init payload). For tests and scripts. */
+    snapshot(): InitPayload;
+    /** Stop timers, close SSE connections, disable event loop monitoring. */
+    stop(): Promise<void>;
+    /** Resolved mode: 'memory' | 'pm2' | 'disabled'. */
+    readonly mode: 'memory' | 'pm2' | 'disabled';
+}
+declare function serverPulse(_options?: ServerPulseOptions): ServerPulseMiddleware;
+
+export { type InitPayload, type ServerPulseMiddleware, type ServerPulseOptions, type TickPayload, serverPulse };

package/dist/index.d.ts

@@ -0,0 +1,244 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+/** Warning / danger thresholds used for colours and the health badge (spec 4.3). */
+interface Thresholds {
+    /** Default [70, 85]. */
+    cpuPercent: [warn: number, danger: number];
+    /** Default [75, 90]. */
+    memoryPercent: [warn: number, danger: number];
+    /** Default [80, 90]. */
+    diskPercent: [warn: number, danger: number];
+    /** Default [70, 85] (of heap_size_limit). */
+    heapPercent: [warn: number, danger: number];
+    /** Default [50, 100] (p99 per second). */
+    eventLoopLagMs: [warn: number, danger: number];
+    /** Default [1, 3] (5xx share). */
+    errorRatePercent: [warn: number, danger: number];
+}
+interface AuthCommon {
+    sessionSecret?: string;
+    sessionTtlMinutes?: number;
+    secureCookie?: 'auto' | boolean;
+}
+interface ServerPulseOptions {
+    /** Turn everything off (middleware becomes a pass-through). Default: true. Env: PULSE_ENABLED=false */
+    enabled?: boolean;
+    /** URL path of the dashboard. Default: '/monitor'. Must start with '/', no trailing slash. */
+    basePath?: string;
+    /** 'auto' | 'memory' | 'pm2'. Default: 'auto' (section 11.1). Env: PULSE_MODE */
+    mode?: 'auto' | 'memory' | 'pm2';
+    /**
+     * Dashboard credentials. Either one user, a list of users, or false.
+     * Env fallbacks: PULSE_USER, PULSE_PASS, PULSE_SECRET.
+     * false is only allowed when NODE_ENV !== 'production'.
+     */
+    auth?: ({
+        username: string;
+        password: string;
+    } & AuthCommon) | ({
+        users: Array<{
+            username: string;
+            password: string;
+        }>;
+    } & AuthCommon) | false;
+    /** Only these client IPs may reach the dashboard (exact IPv4/IPv6 or IPv4 CIDR). Others get 404. Default: allow all. */
+    ipAllowList?: string[];
+    /** Trust X-Forwarded-For / X-Forwarded-Proto (set true behind Nginx or a load balancer). Default: false. */
+    trustProxy?: boolean;
+    /** Extra requests to exclude from statistics. basePath is always excluded. */
+    ignore?: Array<string | RegExp | ((req: IncomingMessage) => boolean)>;
+    /** Apply the default ignore list (/health, /favicon.ico, static files). Default: true. */
+    ignoreDefaults?: boolean;
+    routes?: {
+        /** Per-route response-time targets in ms, keyed "METHOD /normalized/path". */
+        targets?: Record<string, number>;
+        /** Target for routes not listed above. Default: 500. */
+        defaultTargetMs?: number;
+        /** Maximum distinct routes tracked; extra routes go to "OTHER". Default: 500. */
+        maxRoutes?: number;
+        /** Custom normalizer; return null to fall back to the built-in one. */
+        normalize?: (req: IncomingMessage) => string | null;
+    };
+    /** Apdex threshold T in ms. Default: 300. */
+    apdexThresholdMs?: number;
+    /** Warning / danger thresholds used for colours and the health badge (section 4.3). */
+    thresholds?: Partial<Thresholds>;
+    /** Path used for the disk metric. Default: '/' (Windows: drive of process.cwd()). */
+    diskPath?: string;
+    pm2?: {
+        /** Monitor process host and port. Defaults: '127.0.0.1', 9100. Env: PULSE_MONITOR_HOST, PULSE_MONITOR_PORT */
+        monitorHost?: string;
+        monitorPort?: number;
+    };
+    ui?: {
+        /** Title shown in the header. Default: os.hostname(). */
+        title?: string;
+        /** Load IBM Plex Sans from Google Fonts. Default: false (system font stack, no external requests). */
+        webFonts?: boolean;
+    };
+    /** Optional health endpoint, outside basePath, no auth. Default: false. */
+    health?: false | {
+        path?: string;
+        checks?: Record<string, () => boolean | Promise<boolean>>;
+    };
+    /** Logger. Default: console with "[server-pulse]" prefix. */
+    logger?: Pick<Console, 'info' | 'warn' | 'error'>;
+}
+
+/** Histogram counts, length 18, in BUCKETS order. */
+type Hist = number[];
+/** One second of aggregated data (spec 7.1). */
+interface Tick {
+    /** Epoch ms, start of the second. */
+    t: number;
+    req: {
+        /** Finished requests in this second. */
+        total: number;
+        c2: number;
+        c3: number;
+        c4: number;
+        c5: number;
+        aborted: number;
+        /** Value at the end of the second. */
+        inFlight: number;
+    };
+    /** Per-second histograms. */
+    hist: {
+        all: Hist;
+        ok: Hist;
+        fail: Hist;
+    };
+    apdex: {
+        s: number;
+        t: number;
+        f: number;
+    };
+    sys: {
+        /** Percent. */
+        cpu: number;
+        /** Bytes. */
+        memUsed: number;
+        memTotal: number;
+        memKind: 'system' | 'container';
+        /** Bytes; null while the disk metric is unavailable (see DECISIONS.md). */
+        diskUsed: number | null;
+        diskTotal: number | null;
+        load1: number | null;
+    };
+    /** Aggregated for the resources panel. */
+    proc: {
+        /** Busiest worker. */
+        heapPct: number;
+        /** Bytes, busiest worker. */
+        heapUsed: number;
+        heapLimit: number;
+        /** Ms, worst worker. */
+        lagP99: number;
+    };
+}
+interface RouteRow {
+    key: string;
+    method: string;
+    path: string;
+    count: number;
+    rps: number;
+    avg: number;
+    p95: number | null;
+    target: number;
+    errRate: number;
+}
+interface WorkerRow {
+    /** pm_id */
+    id: number;
+    pid: number;
+    status: 'online' | 'blocked' | 'stale' | 'stopped' | 'errored';
+    /** % of one core. */
+    cpu: number;
+    heapUsed: number;
+    heapLimit: number;
+    lagP99: number;
+    /** Last 10 s. */
+    rps: number;
+    /** pm2_env.restart_time */
+    restarts: number;
+    uptimeSec: number;
+}
+interface ErrorEntry {
+    t: number;
+    method: string;
+    route: string;
+    status: number;
+    message: string;
+    worker: number | null;
+}
+/** SSE `init` event and `GET basePath/api/snapshot` (spec 7.2). */
+interface InitPayload {
+    meta: {
+        /** Package version. */
+        version: string;
+        /** ui.title or hostname. */
+        title: string;
+        host: string;
+        node: string;
+        platform: string;
+        mode: 'memory' | 'pm2';
+        /** 1 in memory mode. */
+        workers: number;
+        /** Epoch ms (oldest worker in PM2 mode). */
+        appStartedAt: number;
+        /** Epoch ms ("Requests since start" counts from here). */
+        monitorStartedAt: number;
+        cores: number;
+    };
+    config: {
+        /** BUCKETS, Infinity sent as null. */
+        buckets: Array<number | null>;
+        defaultTargetMs: number;
+        apdexThresholdMs: number;
+        thresholds: Thresholds;
+        windowSeconds: 900;
+        /** Logged-in username, shown in header menu. */
+        user: string;
+    };
+    totals: {
+        requests: number;
+        since: number;
+    };
+    /** Up to 900, oldest first. */
+    history: Tick[];
+    routes: RouteRow[];
+    /** Empty in memory mode. */
+    workers: WorkerRow[];
+    /** Newest first, up to 50. */
+    errors: ErrorEntry[];
+}
+/** SSE `tick` event, every second (spec 7.3). */
+interface TickPayload {
+    tick: Tick;
+    totals: {
+        requests: number;
+        since: number;
+    };
+    /** Full table (≤ maxRoutes rows). */
+    routes: RouteRow[];
+    workers: WorkerRow[];
+    /** Errors since previous tick. */
+    newErrors: ErrorEntry[];
+}
+
+interface ServerPulseMiddleware {
+    (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void): void;
+    /** Express error middleware that records the error, then calls next(err). */
+    errorHandler(): (err: unknown, req: any, res: any, next: (err?: unknown) => void) => void;
+    /** Record an error manually (e.g. from a NestJS exception filter). */
+    captureError(err: unknown, req?: IncomingMessage): void;
+    /** Current snapshot (same shape as the SSE init payload). For tests and scripts. */
+    snapshot(): InitPayload;
+    /** Stop timers, close SSE connections, disable event loop monitoring. */
+    stop(): Promise<void>;
+    /** Resolved mode: 'memory' | 'pm2' | 'disabled'. */
+    readonly mode: 'memory' | 'pm2' | 'disabled';
+}
+declare function serverPulse(_options?: ServerPulseOptions): ServerPulseMiddleware;
+
+export { type InitPayload, type ServerPulseMiddleware, type ServerPulseOptions, type TickPayload, serverPulse };

package/dist/index.mjs

@@ -0,0 +1,60 @@
+// src/index.ts
+import os from "os";
+
+// package.json
+var version = "0.0.2";
+
+// src/index.ts
+var DEFAULT_THRESHOLDS = {
+  cpuPercent: [70, 85],
+  memoryPercent: [75, 90],
+  diskPercent: [80, 90],
+  heapPercent: [70, 85],
+  eventLoopLagMs: [50, 100],
+  errorRatePercent: [1, 3]
+};
+var BUCKETS_WIRE = [5, 10, 25, 50, 75, 100, 150, 250, 350, 500, 750, 1e3, 1500, 2500, 5e3, 1e4, 3e4, null];
+function serverPulse(_options) {
+  const startedAt = Date.now();
+  const middleware = ((_req, _res, next) => {
+    next();
+  });
+  middleware.errorHandler = () => (err, _req, _res, next) => next(err);
+  middleware.captureError = () => {
+  };
+  middleware.snapshot = () => ({
+    meta: {
+      version,
+      title: os.hostname(),
+      host: os.hostname(),
+      node: process.version,
+      platform: process.platform,
+      mode: "memory",
+      workers: 1,
+      appStartedAt: Math.round(Date.now() - process.uptime() * 1e3),
+      monitorStartedAt: startedAt,
+      cores: os.availableParallelism?.() ?? os.cpus().length
+    },
+    config: {
+      buckets: [...BUCKETS_WIRE],
+      defaultTargetMs: 500,
+      apdexThresholdMs: 300,
+      thresholds: structuredClone(DEFAULT_THRESHOLDS),
+      windowSeconds: 900,
+      user: ""
+    },
+    totals: { requests: 0, since: startedAt },
+    history: [],
+    routes: [],
+    workers: [],
+    errors: []
+  });
+  middleware.stop = async () => {
+  };
+  Object.defineProperty(middleware, "mode", { value: "disabled", enumerable: true });
+  return middleware;
+}
+export {
+  serverPulse
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../package.json"],"sourcesContent":["import type { IncomingMessage, ServerResponse } from 'node:http';\nimport os from 'node:os';\nimport type { ServerPulseOptions, Thresholds } from './options';\nimport type { InitPayload, TickPayload } from './engine/payloads';\nimport { version } from '../package.json';\n\nexport interface ServerPulseMiddleware {\n  (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void): void;\n  /** Express error middleware that records the error, then calls next(err). */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  errorHandler(): (err: unknown, req: any, res: any, next: (err?: unknown) => void) => void;\n  /** Record an error manually (e.g. from a NestJS exception filter). */\n  captureError(err: unknown, req?: IncomingMessage): void;\n  /** Current snapshot (same shape as the SSE init payload). For tests and scripts. */\n  snapshot(): InitPayload;\n  /** Stop timers, close SSE connections, disable event loop monitoring. */\n  stop(): Promise<void>;\n  /** Resolved mode: 'memory' | 'pm2' | 'disabled'. */\n  readonly mode: 'memory' | 'pm2' | 'disabled';\n}\n\n// M0 scaffold: pass-through middleware. Collection, dashboard and PM2 mode arrive in later milestones.\nconst DEFAULT_THRESHOLDS: Thresholds = {\n  cpuPercent: [70, 85],\n  memoryPercent: [75, 90],\n  diskPercent: [80, 90],\n  heapPercent: [70, 85],\n  eventLoopLagMs: [50, 100],\n  errorRatePercent: [1, 3],\n};\n\nconst BUCKETS_WIRE = [5, 10, 25, 50, 75, 100, 150, 250, 350, 500, 750, 1000, 1500, 2500, 5000, 10000, 30000, null];\n\nexport function serverPulse(_options?: ServerPulseOptions): ServerPulseMiddleware {\n  const startedAt = Date.now();\n\n  const middleware = ((_req: IncomingMessage, _res: ServerResponse, next: (err?: unknown) => void) => {\n    next();\n  }) as ServerPulseMiddleware;\n\n  middleware.errorHandler = () => (err, _req, _res, next) => next(err);\n  middleware.captureError = () => {};\n  middleware.snapshot = () => ({\n    meta: {\n      version,\n      title: os.hostname(),\n      host: os.hostname(),\n      node: process.version,\n      platform: process.platform,\n      mode: 'memory',\n      workers: 1,\n      appStartedAt: Math.round(Date.now() - process.uptime() * 1000),\n      monitorStartedAt: startedAt,\n      cores: os.availableParallelism?.() ?? os.cpus().length,\n    },\n    config: {\n      buckets: [...BUCKETS_WIRE],\n      defaultTargetMs: 500,\n      apdexThresholdMs: 300,\n      thresholds: structuredClone(DEFAULT_THRESHOLDS),\n      windowSeconds: 900,\n      user: '',\n    },\n    totals: { requests: 0, since: startedAt },\n    history: [],\n    routes: [],\n    workers: [],\n    errors: [],\n  });\n  middleware.stop = async () => {};\n  Object.defineProperty(middleware, 'mode', { value: 'disabled', enumerable: true });\n\n  return middleware;\n}\n\nexport type { ServerPulseOptions, InitPayload, TickPayload };\n","{\n  \"name\": \"@pulse-labs/server-pulse\",\n  \"version\": \"0.0.2\",\n  \"license\": \"MIT\",\n  \"description\": \"Live server monitoring dashboard for Node.js apps, served from your own base URL.\",\n  \"engines\": {\n    \"node\": \">=18.15\"\n  },\n  \"type\": \"commonjs\",\n  \"main\": \"./dist/index.cjs\",\n  \"module\": \"./dist/index.mjs\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"import\": {\n        \"types\": \"./dist/index.d.mts\",\n        \"default\": \"./dist/index.mjs\"\n      },\n      \"require\": {\n        \"types\": \"./dist/index.d.ts\",\n        \"default\": \"./dist/index.cjs\"\n      }\n    },\n    \"./package.json\": \"./package.json\"\n  },\n  \"bin\": {\n    \"server-pulse\": \"dist/cli.cjs\"\n  },\n  \"files\": [\n    \"dist\",\n    \"README.md\",\n    \"CHANGELOG.md\"\n  ],\n  \"publishConfig\": {\n    \"access\": \"public\"\n  },\n  \"scripts\": {\n    \"build\": \"tsup && node scripts/copy-ui.mjs\",\n    \"prepare\": \"npm run build\",\n    \"prepublishOnly\": \"npm run lint && npm run typecheck && npm test\",\n    \"dev\": \"tsup --watch\",\n    \"lint\": \"eslint .\",\n    \"format\": \"prettier --write .\",\n    \"typecheck\": \"tsc --noEmit\",\n    \"test\": \"vitest run\",\n    \"test:watch\": \"vitest\",\n    \"smoke\": \"node scripts/smoke-dist.mjs\",\n    \"test:pm2\": \"vitest run test/integration/pm2.test.ts\",\n    \"test:ui\": \"node test/ui/run.mjs\",\n    \"bench\": \"node bench/overhead.mjs\"\n  },\n  \"peerDependencies\": {\n    \"pm2\": \">=5\"\n  },\n  \"peerDependenciesMeta\": {\n    \"pm2\": {\n      \"optional\": true\n    }\n  },\n  \"devDependencies\": {\n    \"@eslint/js\": \"^9.39.5\",\n    \"@types/express\": \"^5.0.6\",\n    \"@types/node\": \"^20.19.43\",\n    \"@types/supertest\": \"^7.2.1\",\n    \"@vitest/coverage-v8\": \"^4.1.11\",\n    \"eslint\": \"^9.39.5\",\n    \"express4\": \"npm:express@^4.22.3\",\n    \"express5\": \"npm:express@^5.3.0\",\n    \"globals\": \"^17.13.0\",\n    \"prettier\": \"^3.9.10\",\n    \"supertest\": \"^7.3.1\",\n    \"tsup\": \"^8.5.1\",\n    \"typescript\": \"~5.9.3\",\n    \"typescript-eslint\": \"^8.71.2\",\n    \"vite\": \"^6.4.4\",\n    \"vitest\": \"^4.1.11\"\n  },\n  \"overrides\": {\n    \"tsup\": {\n      \"esbuild\": \"^0.28.2\",\n      \"bundle-require\": {\n        \"esbuild\": \"^0.28.2\"\n      }\n    }\n  },\n  \"keywords\": [\n    \"monitoring\",\n    \"dashboard\",\n    \"express\",\n    \"nestjs\",\n    \"pm2\",\n    \"metrics\",\n    \"sse\"\n  ]\n}\n"],"mappings":";AACA,OAAO,QAAQ;;;ACCb,cAAW;;;ADoBb,IAAM,qBAAiC;AAAA,EACrC,YAAY,CAAC,IAAI,EAAE;AAAA,EACnB,eAAe,CAAC,IAAI,EAAE;AAAA,EACtB,aAAa,CAAC,IAAI,EAAE;AAAA,EACpB,aAAa,CAAC,IAAI,EAAE;AAAA,EACpB,gBAAgB,CAAC,IAAI,GAAG;AAAA,EACxB,kBAAkB,CAAC,GAAG,CAAC;AACzB;AAEA,IAAM,eAAe,CAAC,GAAG,IAAI,IAAI,IAAI,IAAI,KAAK,KAAK,KAAK,KAAK,KAAK,KAAK,KAAM,MAAM,MAAM,KAAM,KAAO,KAAO,IAAI;AAE1G,SAAS,YAAY,UAAsD;AAChF,QAAM,YAAY,KAAK,IAAI;AAE3B,QAAM,cAAc,CAAC,MAAuB,MAAsB,SAAkC;AAClG,SAAK;AAAA,EACP;AAEA,aAAW,eAAe,MAAM,CAAC,KAAK,MAAM,MAAM,SAAS,KAAK,GAAG;AACnE,aAAW,eAAe,MAAM;AAAA,EAAC;AACjC,aAAW,WAAW,OAAO;AAAA,IAC3B,MAAM;AAAA,MACJ;AAAA,MACA,OAAO,GAAG,SAAS;AAAA,MACnB,MAAM,GAAG,SAAS;AAAA,MAClB,MAAM,QAAQ;AAAA,MACd,UAAU,QAAQ;AAAA,MAClB,MAAM;AAAA,MACN,SAAS;AAAA,MACT,cAAc,KAAK,MAAM,KAAK,IAAI,IAAI,QAAQ,OAAO,IAAI,GAAI;AAAA,MAC7D,kBAAkB;AAAA,MAClB,OAAO,GAAG,uBAAuB,KAAK,GAAG,KAAK,EAAE;AAAA,IAClD;AAAA,IACA,QAAQ;AAAA,MACN,SAAS,CAAC,GAAG,YAAY;AAAA,MACzB,iBAAiB;AAAA,MACjB,kBAAkB;AAAA,MAClB,YAAY,gBAAgB,kBAAkB;AAAA,MAC9C,eAAe;AAAA,MACf,MAAM;AAAA,IACR;AAAA,IACA,QAAQ,EAAE,UAAU,GAAG,OAAO,UAAU;AAAA,IACxC,SAAS,CAAC;AAAA,IACV,QAAQ,CAAC;AAAA,IACT,SAAS,CAAC;AAAA,IACV,QAAQ,CAAC;AAAA,EACX;AACA,aAAW,OAAO,YAAY;AAAA,EAAC;AAC/B,SAAO,eAAe,YAAY,QAAQ,EAAE,OAAO,YAAY,YAAY,KAAK,CAAC;AAEjF,SAAO;AACT;","names":[]}

package/package.json

@@ -1,6 +1,95 @@
 {
   "name": "@pulse-labs/server-pulse",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "license": "MIT",
+  "description": "Live server monitoring dashboard for Node.js apps, served from your own base URL.",
+  "engines": {
+    "node": ">=18.15"
+  },
+  "type": "commonjs",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "server-pulse": "dist/cli.cjs"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup && node scripts/copy-ui.mjs",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm test",
+    "dev": "tsup --watch",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "smoke": "node scripts/smoke-dist.mjs",
+    "test:pm2": "vitest run test/integration/pm2.test.ts",
+    "test:ui": "node test/ui/run.mjs",
+    "bench": "node bench/overhead.mjs"
+  },
+  "peerDependencies": {
+    "pm2": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "pm2": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@types/express": "^5.0.6",
+    "@types/node": "^20.19.43",
+    "@types/supertest": "^7.2.1",
+    "@vitest/coverage-v8": "^4.1.11",
+    "eslint": "^9.39.5",
+    "express4": "npm:express@^4.22.3",
+    "express5": "npm:express@^5.3.0",
+    "globals": "^17.13.0",
+    "prettier": "^3.9.10",
+    "supertest": "^7.3.1",
+    "tsup": "^8.5.1",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.71.2",
+    "vite": "^6.4.4",
+    "vitest": "^4.1.11"
+  },
+  "overrides": {
+    "tsup": {
+      "esbuild": "^0.28.2",
+      "bundle-require": {
+        "esbuild": "^0.28.2"
+      }
+    }
+  },
+  "keywords": [
+    "monitoring",
+    "dashboard",
+    "express",
+    "nestjs",
+    "pm2",
+    "metrics",
+    "sse"
+  ]
+}