chore: bump version to 0.4.8

Collector failures, service-API errors, WS connection lifecycle, and
config reload/discovery events were previously invisible outside the
browser (or, for a few config/discovery cases, logged with an
inconsistent ad-hoc console.error). Add a small scoped logger
(lib/logger.ts, level via LOG_LEVEL) and wire it through server.ts,
the scheduler, service collector, config loader/effective store, and
the WS server so operators can see failures via `docker logs`.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastian Krüger
+
+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.

README.md

@@ -1,20 +1,25 @@
 # PulseNode
 
 A self-hosted infrastructure dashboard: system stats, Docker containers,
-databases, and HTTP/Traefik health, configured entirely through a YAML file
-and pushed to the browser live over WebSockets. No database of its own -
-`config.yml` is the source of truth, metrics are ephemeral.
+databases, HTTP checks, and combined docker+API service widgets, configured
+entirely through a YAML file and pushed to the browser live over WebSockets.
+No database of its own - `config.yml` is the source of truth, metrics are
+ephemeral.
 
 ## Features
 
 - **YAML-configured** widgets and layout, hot-reloaded - edit `config.yml`
   and connected browsers update without a page refresh
 - **Secrets via `.env`**, interpolated into `config.yml` at load time
-  (`${VAR}` / `${VAR:-default}`), never sent to the browser
+  (`${VAR}` / `${VAR:-default}`). Widget fields named `apiToken`/`apiKey`/
+  `password` are stripped before the config ever reaches the browser
+  (`lib/config/public.ts`) - collectors run server-side and use the real
+  values, the client never sees them
 - **Live updates over WebSocket** - each widget subscribes to its own topic;
   the server only serializes results for widgets someone is actually viewing
 - **Widget types**: Docker containers, Postgres/Redis instances, system
-  resources, HTTP health checks, Traefik router status, bookmarks, search
+  resources, HTTP health checks, combined docker+API service widgets
+  (Gitea, Coolify, Immich, n8n, Umami, Headscale, Traefik), bookmarks, search
 - **Optional label-based auto-discovery** - containers carrying
   `traefik.enable=true` can be turned into dashboard widgets automatically;
   manual `config.yml` entries always take precedence
@@ -64,13 +69,20 @@ discovery:
     network: falcon_network # only include containers on this docker network
 
 groups:
-  - name: Core Infra
+  - name: Infra
     widgets:
-      - type: docker
+      - type: system
+        interval: 5s
+
+  - name: Services
+    widgets:
+      - type: service
+        service: traefik
         name: Traefik
         containerName: traefik
+        icon: traefik
         href: https://traefik.example.com
-        interval: 10s
+        interval: 15s
 ```
 
 Config errors are **non-destructive**: if `config.yml` fails validation
@@ -93,10 +105,26 @@ reload; never exposed to the client. See `config/.env.example`.
 | `database` | `name`, `containerName`, `engine`   | Thin skin over the same Docker collector - `engine` is `postgres` or `redis`, used for icon/label only. `interval` default `10s`. |
 | `system`   | -                                    | Host CPU/mem/disk/network via `systeminformation`. Optional `name` (default `System`), `interval` (default `5s`). |
 | `http`     | `name`, `url`                        | HTTP health check with latency and consecutive-failure tracking. Optional `method` (default `GET`), `timeout` (default `5s`), `interval` (default `30s`), `expect.status` (default `200`). |
-| `traefik`  | `apiUrl`                             | Router/entrypoint/middleware status from Traefik's own API (`--api.dashboard=true` must be enabled). Optional `name` (default `Traefik`), `interval` (default `15s`). |
+| `service`  | `name`, `containerName`, `service`   | Docker health/CPU/mem (same collector as `docker`) merged with a stat pulled from the service's own API. `service` picks the variant (see below) and its extra fields. A failed API call surfaces as a non-fatal `statError` on the card without hiding docker health. Optional `href`, `icon`, `showStats` (default `true`), `interval` (default `15s`). |
 
 `interval`/`timeout` values are duration strings: `500ms`, `5s`, `1m`, `1h`.
 
+#### `service` variants
+
+Each `service` widget calls its target container directly by name on the
+docker network (`http://<containerName>:<port>`), not through Traefik/TLS -
+no `apiUrl` field needed.
+
+| `service`   | Extra fields                              | Stat shown |
+|-------------|--------------------------------------------|------------|
+| `gitea`     | `username` (default `Valknar`), `apiToken` | Repository count |
+| `coolify`   | `apiToken`                                  | Project count, resource count |
+| `immich`    | `apiKey`                                    | Photo count, video count |
+| `n8n`       | `apiKey`                                    | Workflow count |
+| `umami`     | `username`, `password`, `websiteId`         | Active visitors (login-and-cache, self-hosted has no static API key) |
+| `headscale` | `apiToken`                                  | User count, node count |
+| `traefik`   | -                                            | HTTP router count (needs `--api.insecure=true` or a dashboard entrypoint reachable on the docker network) |
+
 `icon` on `docker`/`bookmark` widgets is a key into `lib/brand-icons.ts` (currently
 `traefik`, `coolify`, `gitea`, `docker`, `immich`, `n8n`, `passbolt`, `umami`,
 `postgresql`, `redis`, `headscale`), rendered monochrome so it doesn't compete
@@ -147,8 +175,10 @@ server.ts              custom server: http + WebSocket (/ws) + collector schedul
 app/                   Next.js App Router pages and API routes
 components/widgets/    one folder per widget type (Widget.tsx + shared Skeleton/StatusDot)
 components/layout/     Dashboard shell, theme toggle, brand mark
-lib/config/            schema (zod), loader (parse/interpolate/watch), effective (+ discovery merge)
-lib/collectors/        docker, system, http, traefik collectors + the scheduler
+lib/config/            schema (zod), loader (parse/interpolate/watch), effective (+ discovery merge),
+                       public.ts (strips secrets before the config reaches the browser)
+lib/collectors/        docker, system, http collectors, service.ts (docker+API merge) with
+                       one collector per service under services/, + the scheduler
 lib/discovery/         traefik-label auto-discovery
 lib/ws/                WebSocket server (topics) and the browser-side subscription hooks
 ```
@@ -162,3 +192,7 @@ lib/ws/                WebSocket server (topics) and the browser-side subscripti
   runs in - for true host-level stats rather than the container's own view,
   mount `/proc` and `/sys` from the host and run with `pid: host` (not
   configured by default).
+
+## License
+
+[MIT](LICENSE)

app/globals.css

@@ -133,8 +133,22 @@ body {
   animation: pulse-glow 2s ease-in-out infinite;
 }
 
+@keyframes pulse-glow-down {
+  0%,
+  100% {
+    box-shadow: 0 0 0 0 color-mix(in srgb, var(--pn-status-down) 55%, transparent);
+  }
+  50% {
+    box-shadow: 0 0 0 4px color-mix(in srgb, var(--pn-status-down) 0%, transparent);
+  }
+}
+.status-pulse-down {
+  animation: pulse-glow-down 2s ease-in-out infinite;
+}
+
 @media (prefers-reduced-motion: reduce) {
   .status-pulse,
+  .status-pulse-down,
   .pn-toast,
   .pn-spin-in {
     animation: none;
@@ -155,7 +169,4 @@ body {
     grid-column: 1 / -1 !important;
     grid-row: auto !important;
   }
-  .pn-live-label {
-    display: none !important;
-  }
 }

app/not-found.tsx

@@ -0,0 +1,55 @@
+import Link from "next/link";
+import type { Metadata } from "next";
+
+export const metadata: Metadata = {
+  title: "Not Found",
+  description: "No pulse on this route.",
+};
+
+export default function NotFound() {
+  return (
+    <main className="flex min-h-screen flex-col items-center justify-center gap-8 px-6 text-center">
+      <svg
+        width="320"
+        height="64"
+        viewBox="0 0 320 64"
+        fill="none"
+        aria-hidden="true"
+        className="w-full max-w-[320px]"
+      >
+        <polyline
+          points="0,32 30,32 40,10 50,54 60,24 72,32 140,32"
+          fill="none"
+          stroke="var(--pn-accent)"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+        <line
+          x1="140"
+          y1="32"
+          x2="300"
+          y2="32"
+          stroke="var(--pn-status-down)"
+          strokeWidth="2"
+          strokeLinecap="round"
+          opacity="0.55"
+        />
+        <circle cx="300" cy="32" r="4" fill="var(--pn-status-down)" className="status-pulse-down" />
+      </svg>
+
+      <div className="flex flex-col gap-3">
+        <p className="font-display text-7xl font-semibold tracking-tight text-fg">404</p>
+        <p className="text-base font-medium text-fg">No pulse on this route.</p>
+        <p className="text-sm text-fg-muted">Nothing here is being monitored.</p>
+      </div>
+
+      <Link
+        href="/"
+        className="rounded-md border border-border px-4 py-2 text-sm font-medium text-fg transition-colors hover:border-accent hover:text-accent"
+      >
+        Back to dashboard
+      </Link>
+    </main>
+  );
+}

components/widgets/BrandIcon.tsx

@@ -1,7 +1,20 @@
+import { GlobeSimple } from "@phosphor-icons/react/ssr";
 import { BRAND_ICON_PATHS } from "@/lib/brand-icons";
 
+// Generic (non-brand) icons that don't belong in BRAND_ICON_PATHS - for
+// widgets that link to something with no single logo of its own.
+const GENERIC_ICONS = {
+  globe: GlobeSimple,
+};
+
 export function BrandIcon({ slug, size = 18 }: { slug?: string; size?: number }) {
   if (!slug) return null;
+
+  const GenericIcon = GENERIC_ICONS[slug as keyof typeof GENERIC_ICONS];
+  if (GenericIcon) {
+    return <GenericIcon size={size} className="shrink-0 text-fg-muted" aria-hidden />;
+  }
+
   const path = BRAND_ICON_PATHS[slug];
   if (!path) return null;
 

components/widgets/bookmark/Widget.tsx

@@ -6,6 +6,37 @@ import { BrandIcon } from "@/components/widgets/BrandIcon";
 type BookmarkWidget = Extract<Widget, { type: "bookmark" }>;
 
 export function BookmarkWidget({ widget }: { widget: BookmarkWidget }) {
+  if (widget.links && widget.links.length > 0) {
+    return (
+      <div className={PN_CARD_CLASS} style={{ gridColumn: "span 4", gridRow: "span 2" }}>
+        <div className="flex items-center gap-2">
+          <BrandIcon slug={widget.icon} />
+          <span className="min-w-0 flex-1 truncate text-[15px] font-medium text-fg">{widget.name}</span>
+        </div>
+        {widget.description && <span className="text-xs text-fg-muted">{widget.description}</span>}
+        <div className="-mx-1 flex min-h-0 flex-1 flex-col divide-y divide-border overflow-y-auto">
+          {widget.links.map((link) => (
+            <a
+              key={link.href}
+              href={link.href}
+              target="_blank"
+              rel="noreferrer"
+              className="group flex items-center gap-2 px-1 py-1.5 text-sm text-fg-muted no-underline hover:text-accent"
+            >
+              <BrandIcon slug={link.icon} size={14} />
+              <span className="min-w-0 flex-1 truncate">{link.name}</span>
+              <ArrowUpRight
+                size={13}
+                className="shrink-0 text-accent opacity-0 group-hover:opacity-100"
+                aria-hidden
+              />
+            </a>
+          ))}
+        </div>
+      </div>
+    );
+  }
+
   return (
     <a
       href={widget.href}

components/widgets/service/Widget.tsx

@@ -60,15 +60,6 @@ export function ServiceWidget({ widget, widgetId }: { widget: ServiceWidget; wid
               ))}
             </div>
           )}
-          {data.detail && data.detail.length > 0 && (
-            <div className="flex flex-wrap gap-1.5">
-              {data.detail.map((entry) => (
-                <StatusTag key={entry} tone="neutral">
-                  {entry}
-                </StatusTag>
-              ))}
-            </div>
-          )}
           {data.statError && <StatusTag tone="degraded">{data.statError}</StatusTag>}
           {widget.showStats && data.docker.cpuPercent !== null && memPercent !== null && (
             <div className="mt-0.5 flex gap-4">

lib/collectors/scheduler.ts

@@ -7,6 +7,9 @@ import { collectSystem } from "./system";
 import { collectHttp } from "./http";
 import { collectService } from "./service";
 import type { WidgetResult } from "@/lib/types/widget-result";
+import { createLogger } from "@/lib/logger";
+
+const log = createLogger("scheduler");
 
 const httpLimit = pLimit(8);
 
@@ -122,6 +125,12 @@ class CollectorScheduler {
 
       if (existing) clearInterval(existing.timer);
 
+      log.debug(existing ? "job replaced" : "job added", {
+        widgetId: instance.id,
+        type: instance.widget.type,
+        intervalMs,
+      });
+
       const run = () => this.runJob(instance.id);
       const timer = setInterval(run, intervalMs);
       this.jobs.set(instance.id, { widget: instance.widget, intervalMs, timer, consecutiveFailures: 0 });
@@ -130,16 +139,20 @@ class CollectorScheduler {
 
     for (const [id, job] of this.jobs) {
       if (!seen.has(id)) {
+        log.debug("job removed", { widgetId: id, type: job.widget.type });
         clearInterval(job.timer);
         this.jobs.delete(id);
         this.lastResults.delete(id);
       }
     }
+
+    log.info("reconciled", { jobs: this.jobs.size });
   }
 
   stop(): void {
     for (const job of this.jobs.values()) clearInterval(job.timer);
     this.jobs.clear();
+    log.info("scheduler stopped");
   }
 
   private async runJob(id: string): Promise<void> {
@@ -150,10 +163,37 @@ class CollectorScheduler {
     try {
       result = await collect(job.widget);
       if (result.type === "http") {
+        const wasFailing = job.consecutiveFailures > 0;
         job.consecutiveFailures = result.data.up ? 0 : job.consecutiveFailures + 1;
         result = { type: "http", data: { ...result.data, consecutiveFailures: job.consecutiveFailures } };
+        if (!result.data.up) {
+          log.warn("http check failed", {
+            widgetId: id,
+            url: (job.widget as { url?: string }).url,
+            statusCode: result.data.statusCode,
+            attempt: job.consecutiveFailures,
+          });
+        } else if (wasFailing) {
+          log.info("http check recovered", { widgetId: id, url: (job.widget as { url?: string }).url });
+        }
+      } else {
+        if (job.consecutiveFailures > 0) {
+          log.info("collector recovered", {
+            widgetId: id,
+            type: job.widget.type,
+            afterFailures: job.consecutiveFailures,
+          });
+        }
+        job.consecutiveFailures = 0;
       }
     } catch (err) {
+      job.consecutiveFailures += 1;
+      log.error("collector failed", {
+        widgetId: id,
+        type: job.widget.type,
+        attempt: job.consecutiveFailures,
+        error: (err as Error).message,
+      });
       result = { type: "error", message: (err as Error).message };
     }
 

lib/collectors/service.ts

@@ -8,8 +8,11 @@ import { collectN8n } from "./services/n8n";
 import { collectUmami } from "./services/umami";
 import { collectHeadscale } from "./services/headscale";
 import { collectTraefikStat } from "./services/traefik";
+import { createLogger } from "@/lib/logger";
 
-function collectServiceStat(widget: ServiceWidget): Promise<{ stats: ServiceStat[]; detail?: string[] }> {
+const log = createLogger("service");
+
+function collectServiceStat(widget: ServiceWidget): Promise<{ stats: ServiceStat[] }> {
   switch (widget.service) {
     case "gitea":
       return collectGitea(widget);
@@ -34,10 +37,11 @@ export async function collectService(widget: ServiceWidget): Promise<ServiceWidg
   // A failed service-API call (bad token, service down) must not take out the
   // docker health readout too - the two are independent failure modes and
   // merging them into one card should not let one mask the other.
-  const statPromise = collectServiceStat(widget).catch((err) => ({
-    stats: [] as ServiceStat[],
-    statError: (err as Error).message,
-  }));
+  const statPromise = collectServiceStat(widget).catch((err) => {
+    const message = (err as Error).message;
+    log.warn("service API call failed", { service: widget.service, containerName: widget.containerName, error: message });
+    return { stats: [] as ServiceStat[], statError: message };
+  });
 
   const [docker, statResult] = await Promise.all([dockerPromise, statPromise]);
   return { docker, ...statResult };

lib/collectors/services/coolify.ts

@@ -2,12 +2,6 @@ import type { CoolifyServiceWidget } from "@/lib/config/schema";
 import type { ServiceStat } from "@/lib/types/service-result";
 import { serviceBaseUrl } from "./base-url";
 
-const DETAIL_LIMIT = 5;
-
-interface CoolifyProject {
-  name: string;
-}
-
 async function fetchCoolify<T>(base: string, path: string, apiToken: string): Promise<T> {
   const response = await fetch(`${base}${path}`, {
     headers: { Authorization: `Bearer ${apiToken}` },
@@ -19,22 +13,17 @@ async function fetchCoolify<T>(base: string, path: string, apiToken: string): Pr
   return (await response.json()) as T;
 }
 
-export async function collectCoolify(
-  widget: CoolifyServiceWidget
-): Promise<{ stats: ServiceStat[]; detail?: string[] }> {
+export async function collectCoolify(widget: CoolifyServiceWidget): Promise<{ stats: ServiceStat[] }> {
   const base = serviceBaseUrl(widget);
   const [projects, resources] = await Promise.all([
-    fetchCoolify<CoolifyProject[]>(base, "/api/v1/projects", widget.apiToken),
+    fetchCoolify<unknown[]>(base, "/api/v1/projects", widget.apiToken),
     fetchCoolify<unknown[]>(base, "/api/v1/resources", widget.apiToken),
   ]);
-  const names = projects.slice(0, DETAIL_LIMIT).map((p) => p.name);
-  if (projects.length > DETAIL_LIMIT) names.push(`+${projects.length - DETAIL_LIMIT} more`);
 
   return {
     stats: [
       { label: "Projects", value: String(projects.length) },
       { label: "Resources", value: String(resources.length) },
     ],
-    detail: names.length > 0 ? names : undefined,
   };
 }

lib/config/effective.ts

@@ -1,6 +1,9 @@
 import { configStore } from "./loader";
 import { discoverDockerWidgets } from "@/lib/discovery/traefik-labels";
 import type { Config, Widget } from "./schema";
+import { createLogger } from "@/lib/logger";
+
+const log = createLogger("discovery");
 
 const DISCOVERY_INTERVAL_MS = 60_000;
 
@@ -53,11 +56,15 @@ class EffectiveConfigStore {
     try {
       const next = await discoverDockerWidgets(configStore.get());
       if (!sameDiscoveredSet(this.discovered, next)) {
+        log.info("discovered widget set changed", {
+          previous: this.discovered.length,
+          current: next.length,
+        });
         this.discovered = next;
         this.emit();
       }
     } catch (err) {
-      console.error(`[discovery] ${(err as Error).message}`);
+      log.error("discovery scan failed", { error: (err as Error).message });
     }
   }
 

lib/config/loader.ts

@@ -5,11 +5,18 @@ import chokidar, { type FSWatcher } from "chokidar";
 import { parse as parseYaml } from "yaml";
 import { configSchema, type Config } from "./schema";
 import { interpolateEnv } from "./interpolate";
+import { createLogger } from "@/lib/logger";
+
+const log = createLogger("config");
 
 const CONFIG_DIR = path.join(process.cwd(), "config");
 const CONFIG_PATH = path.join(CONFIG_DIR, "config.yml");
 const ENV_PATH = path.join(CONFIG_DIR, ".env");
 
+function widgetCount(config: Config): number {
+  return config.groups.reduce((sum, group) => sum + group.widgets.length, 0);
+}
+
 export class ConfigError extends Error {}
 
 function loadEnv(): Record<string, string | undefined> {
@@ -62,6 +69,7 @@ class ConfigStore {
 
   load(): Config {
     this.current = readConfig();
+    log.info("config loaded", { groups: this.current.groups.length, widgets: widgetCount(this.current) });
     return this.current;
   }
 
@@ -85,7 +93,11 @@ class ConfigStore {
       awaitWriteFinish: { stabilityThreshold: 200, pollInterval: 50 },
       ignoreInitial: true,
     });
-    this.watcher.on("all", () => this.reload());
+    this.watcher.on("all", (event) => {
+      log.debug("watched file changed", { event });
+      this.reload();
+    });
+    log.info("watching config files", { paths: [CONFIG_PATH, ENV_PATH] });
   }
 
   stop(): void {
@@ -97,10 +109,11 @@ class ConfigStore {
     try {
       const next = readConfig();
       this.current = next;
+      log.info("config reloaded", { groups: next.groups.length, widgets: widgetCount(next) });
       for (const listener of this.listeners) listener(next);
     } catch (err) {
       const configError = err instanceof ConfigError ? err : new ConfigError((err as Error).message);
-      console.error(`[config] ${configError.message}`);
+      log.error("config reload failed", { error: configError.message });
       for (const listener of this.errorListeners) listener(configError);
     }
   }

lib/config/schema.ts

@@ -6,12 +6,19 @@ const durationSchema = z
   .string()
   .regex(/^\d+(ms|s|m|h)$/, 'Expected a duration like "500ms", "5s", "1m", or "1h"');
 
+export const bookmarkLinkSchema = z.object({
+  name: z.string(),
+  href: z.string().url(),
+  icon: z.string().optional(),
+});
+
 export const bookmarkWidgetSchema = z.object({
   type: z.literal("bookmark"),
   name: z.string(),
-  href: z.string().url(),
+  href: z.string().url().optional(),
   description: z.string().optional(),
   icon: z.string().optional(),
+  links: z.array(bookmarkLinkSchema).optional(),
 });
 
 export const searchWidgetSchema = z.object({

lib/logger.ts

@@ -0,0 +1,47 @@
+type LogLevel = "debug" | "info" | "warn" | "error";
+type LogFields = Record<string, unknown>;
+
+const LEVEL_ORDER: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3 };
+
+function resolveMinLevel(): LogLevel {
+  const configured = process.env.LOG_LEVEL?.toLowerCase();
+  if (configured === "debug" || configured === "info" || configured === "warn" || configured === "error") {
+    return configured;
+  }
+  return process.env.NODE_ENV === "production" ? "info" : "debug";
+}
+
+const MIN_LEVEL = resolveMinLevel();
+
+function formatFields(fields?: LogFields): string {
+  if (!fields) return "";
+  const parts = Object.entries(fields)
+    .filter(([, value]) => value !== undefined)
+    .map(([key, value]) => `${key}=${typeof value === "string" ? value : JSON.stringify(value)}`);
+  return parts.length > 0 ? ` ${parts.join(" ")}` : "";
+}
+
+function write(level: LogLevel, scope: string, message: string, fields?: LogFields): void {
+  if (LEVEL_ORDER[level] < LEVEL_ORDER[MIN_LEVEL]) return;
+  const line = `${new Date().toISOString()} ${level.toUpperCase().padEnd(5)} [${scope}] ${message}${formatFields(fields)}`;
+  if (level === "error") console.error(line);
+  else if (level === "warn") console.warn(line);
+  else console.log(line);
+}
+
+export interface Logger {
+  debug(message: string, fields?: LogFields): void;
+  info(message: string, fields?: LogFields): void;
+  warn(message: string, fields?: LogFields): void;
+  error(message: string, fields?: LogFields): void;
+}
+
+/** Scoped logger. `scope` is the bracketed tag, e.g. createLogger("scheduler") -> "[scheduler]". */
+export function createLogger(scope: string): Logger {
+  return {
+    debug: (message, fields) => write("debug", scope, message, fields),
+    info: (message, fields) => write("info", scope, message, fields),
+    warn: (message, fields) => write("warn", scope, message, fields),
+    error: (message, fields) => write("error", scope, message, fields),
+  };
+}

lib/types/service-result.ts

@@ -8,6 +8,5 @@ export interface ServiceStat {
 export interface ServiceWidgetResult {
   docker: DockerContainerResult;
   stats: ServiceStat[];
-  detail?: string[];
   statError?: string;
 }

lib/ws/server.ts

@@ -6,6 +6,9 @@ import { effectiveConfigStore } from "@/lib/config/effective";
 import { toPublicConfig } from "@/lib/config/public";
 import type { Config } from "@/lib/config/schema";
 import type { WidgetResult } from "@/lib/types/widget-result";
+import { createLogger } from "@/lib/logger";
+
+const log = createLogger("ws");
 
 type Envelope =
   | { topic: string; type: "result"; ts: number; data: WidgetResult }
@@ -22,6 +25,8 @@ export function attachWebSocketServer(httpServer: HttpServer): WebSocketServer {
   const wss = new WebSocketServer({ noServer: true });
   const subscriptions = new Map<string, Set<WebSocket>>();
   const allSockets = new Set<WebSocket>();
+  const connectionIds = new WeakMap<WebSocket, number>();
+  let nextConnectionId = 1;
 
   function subscribe(socket: WebSocket, widgetId: string): void {
     let set = subscriptions.get(widgetId);
@@ -46,12 +51,16 @@ export function attachWebSocketServer(httpServer: HttpServer): WebSocketServer {
   }
 
   wss.on("connection", (socket) => {
+    const connectionId = nextConnectionId++;
+    connectionIds.set(socket, connectionId);
     allSockets.add(socket);
+    log.info("client connected", { connectionId, clients: allSockets.size });
 
     try {
       const config = effectiveConfigStore.get();
       send(socket, { topic: "config", type: "config:update", ts: Date.now(), data: toPublicConfig(config) });
-    } catch {
+    } catch (err) {
+      log.debug("no valid config to send on connect", { connectionId, error: (err as Error).message });
       // no valid config loaded yet; client keeps its SSR-seeded config until one arrives
     }
 
@@ -59,18 +68,27 @@ export function attachWebSocketServer(httpServer: HttpServer): WebSocketServer {
       let message: { action?: string; widgetId?: string };
       try {
         message = JSON.parse(raw.toString());
-      } catch {
+      } catch (err) {
+        log.warn("received malformed message", { connectionId, error: (err as Error).message });
         return;
       }
       if (message.action === "subscribe" && typeof message.widgetId === "string") {
+        log.debug("client subscribed", { connectionId, widgetId: message.widgetId });
         subscribe(socket, message.widgetId);
       } else if (message.action === "unsubscribe" && typeof message.widgetId === "string") {
+        log.debug("client unsubscribed", { connectionId, widgetId: message.widgetId });
         unsubscribe(socket, message.widgetId);
       }
     });
 
-    socket.on("close", () => cleanupSocket(socket));
-    socket.on("error", () => cleanupSocket(socket));
+    socket.on("close", (code) => {
+      log.info("client disconnected", { connectionId, code, clients: allSockets.size - 1 });
+      cleanupSocket(socket);
+    });
+    socket.on("error", (err) => {
+      log.error("socket error", { connectionId, error: err.message });
+      cleanupSocket(socket);
+    });
   });
 
   collectorScheduler.onResult((widgetId, result) => {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulsenode",
-  "version": "0.3.0",
+  "version": "0.4.8",
   "private": true,
   "scripts": {
     "dev": "tsx watch server.ts",

scripts/extract-brand-icons.py

@@ -26,6 +26,7 @@ ICONS = {
     "postgresql": "postgresql",
     "redis": "redis",
     "headscale": "tailscale",
+    "coder": "coder",
 }
 
 ROOT = Path(__file__).resolve().parent.parent

server.ts

@@ -4,6 +4,9 @@ import { attachWebSocketServer } from "./lib/ws/server";
 import { configStore } from "./lib/config/loader";
 import { effectiveConfigStore } from "./lib/config/effective";
 import { collectorScheduler } from "./lib/collectors/scheduler";
+import { createLogger } from "./lib/logger";
+
+const log = createLogger("server");
 
 const port = Number(process.env.PORT ?? 3000);
 const hostname = process.env.HOSTNAME ?? "0.0.0.0";
@@ -14,6 +17,7 @@ const handle = app.getRequestHandler();
 
 async function main(): Promise<void> {
   await app.prepare();
+  log.info("next.js prepared", { dev });
   const upgradeHandler = app.getUpgradeHandler();
 
   configStore.load();
@@ -21,6 +25,7 @@ async function main(): Promise<void> {
   await effectiveConfigStore.start();
   collectorScheduler.start(effectiveConfigStore.get());
   effectiveConfigStore.onUpdate((config) => collectorScheduler.reconcile(config));
+  log.info("collector scheduler started");
 
   const httpServer = createServer((req, res) => {
     handle(req, res);
@@ -39,23 +44,30 @@ async function main(): Promise<void> {
     void upgradeHandler(req, socket, head);
   });
 
-  function shutdown(): void {
+  function shutdown(signal: NodeJS.Signals): void {
+    log.info("shutting down", { signal });
     collectorScheduler.stop();
     effectiveConfigStore.stop();
     configStore.stop();
-    httpServer.close(() => process.exit(0));
-    setTimeout(() => process.exit(0), 5_000).unref();
+    httpServer.close(() => {
+      log.info("http server closed");
+      process.exit(0);
+    });
+    setTimeout(() => {
+      log.warn("shutdown timed out, forcing exit");
+      process.exit(0);
+    }, 5_000).unref();
   }
 
-  process.on("SIGTERM", shutdown);
-  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
 
   httpServer.listen(port, () => {
-    console.log(`> PulseNode listening on http://${hostname}:${port}`);
+    log.info("listening", { url: `http://${hostname}:${port}` });
   });
 }
 
 main().catch((err) => {
-  console.error(err);
+  log.error("fatal startup error", { error: (err as Error).message, stack: (err as Error).stack });
   process.exit(1);
 });