feat: scaffold PulseNode dashboard (M1)

Next.js 16 + TypeScript + Tailwind v4 app with a YAML-driven config
system: schema validation (zod), .env interpolation, and a widget
registry rendering bookmark/search/group widgets. CSS custom
properties (--pn-*) drive theming and are overridable from
config.yml's theme.variables. Config load errors surface as a
readable error page instead of crashing the app.

Hot reload, docker/system/http collectors, and the WebSocket push
layer land in later milestones per the approved plan.

lib/config/interpolate.ts

@@ -0,0 +1,13 @@
+const VAR_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)(:-([^}]*))?\}/g;
+
+export function interpolateEnv(
+  raw: string,
+  env: Record<string, string | undefined>
+): string {
+  return raw.replace(VAR_PATTERN, (_match, name: string, hasDefault: string | undefined, fallback: string | undefined) => {
+    const value = env[name];
+    if (value !== undefined) return value;
+    if (hasDefault !== undefined) return fallback ?? "";
+    throw new Error(`Missing environment variable "${name}" referenced in config.yml`);
+  });
+}

lib/config/loader.ts

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import dotenv from "dotenv";
+import chokidar, { type FSWatcher } from "chokidar";
+import { parse as parseYaml } from "yaml";
+import { configSchema, type Config } from "./schema";
+import { interpolateEnv } from "./interpolate";
+
+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");
+
+export class ConfigError extends Error {}
+
+function loadEnv(): Record<string, string | undefined> {
+  if (!existsSync(ENV_PATH)) return { ...process.env };
+  const parsed = dotenv.parse(readFileSync(ENV_PATH));
+  return { ...process.env, ...parsed };
+}
+
+export function readConfig(): Config {
+  if (!existsSync(CONFIG_PATH)) {
+    throw new ConfigError(`Config file not found at ${CONFIG_PATH}`);
+  }
+
+  const raw = readFileSync(CONFIG_PATH, "utf-8");
+  const env = loadEnv();
+
+  let interpolated: string;
+  try {
+    interpolated = interpolateEnv(raw, env);
+  } catch (err) {
+    throw new ConfigError((err as Error).message);
+  }
+
+  let parsedYaml: unknown;
+  try {
+    parsedYaml = parseYaml(interpolated);
+  } catch (err) {
+    throw new ConfigError(`Failed to parse config.yml: ${(err as Error).message}`);
+  }
+
+  const result = configSchema.safeParse(parsedYaml);
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((issue) => `  - ${issue.path.join(".") || "(root)"}: ${issue.message}`)
+      .join("\n");
+    throw new ConfigError(`config.yml failed validation:\n${issues}`);
+  }
+
+  return result.data;
+}
+
+type ConfigListener = (config: Config) => void;
+type ConfigErrorListener = (error: ConfigError) => void;
+
+class ConfigStore {
+  private current: Config | null = null;
+  private watcher: FSWatcher | null = null;
+  private readonly listeners = new Set<ConfigListener>();
+  private readonly errorListeners = new Set<ConfigErrorListener>();
+
+  load(): Config {
+    this.current = readConfig();
+    return this.current;
+  }
+
+  get(): Config {
+    return this.current ?? this.load();
+  }
+
+  onUpdate(listener: ConfigListener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  onError(listener: ConfigErrorListener): () => void {
+    this.errorListeners.add(listener);
+    return () => this.errorListeners.delete(listener);
+  }
+
+  watch(): void {
+    if (this.watcher) return;
+    this.watcher = chokidar.watch([CONFIG_PATH, ENV_PATH], {
+      awaitWriteFinish: { stabilityThreshold: 200, pollInterval: 50 },
+      ignoreInitial: true,
+    });
+    this.watcher.on("all", () => this.reload());
+  }
+
+  stop(): void {
+    this.watcher?.close();
+    this.watcher = null;
+  }
+
+  private reload(): void {
+    try {
+      const next = readConfig();
+      this.current = 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}`);
+      for (const listener of this.errorListeners) listener(configError);
+    }
+  }
+}
+
+export const configStore = new ConfigStore();

lib/config/schema.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+
+const searchEngineSchema = z.enum(["duckduckgo", "google", "bing"]);
+
+export const bookmarkWidgetSchema = z.object({
+  type: z.literal("bookmark"),
+  name: z.string(),
+  href: z.string().url(),
+  description: z.string().optional(),
+});
+
+export const searchWidgetSchema = z.object({
+  type: z.literal("search"),
+  engines: z.array(searchEngineSchema).min(1).default(["duckduckgo"]),
+  defaultEngine: searchEngineSchema.optional(),
+});
+
+export const widgetSchema = z.discriminatedUnion("type", [
+  bookmarkWidgetSchema,
+  searchWidgetSchema,
+]);
+
+export const groupSchema = z.object({
+  name: z.string(),
+  widgets: z.array(widgetSchema),
+});
+
+export const themeSchema = z
+  .object({
+    mode: z.enum(["dark", "light", "auto"]).default("dark"),
+    variables: z.record(z.string(), z.string()).default({}),
+    customCssPath: z.string().optional(),
+  })
+  .default({ mode: "dark", variables: {} });
+
+export const settingsSchema = z
+  .object({
+    title: z.string().default("PulseNode"),
+  })
+  .default({ title: "PulseNode" });
+
+export const configSchema = z.object({
+  theme: themeSchema,
+  settings: settingsSchema,
+  groups: z.array(groupSchema).default([]),
+});
+
+export type Config = z.infer<typeof configSchema>;
+export type Widget = z.infer<typeof widgetSchema>;
+export type Group = z.infer<typeof groupSchema>;
+export type SearchEngine = z.infer<typeof searchEngineSchema>;