@xpufx/paseo-forges 0.1.0

package/server/vendor/paseo-plugin-helper/shared-settings.ts

@@ -0,0 +1,243 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { ZodType } from "zod";
+import { defineSettingsContract, type SettingsContract } from "../../../shared/vendor/paseo-plugin-helper/settings";
+import { PluginStorage } from "./storage";
+import {
+  createSettingsHandlers,
+  registerSettingsRpc,
+  type HandleableServerContext,
+  type RegisterSettingsRpcOptions,
+} from "./settings";
+
+export interface SharedPluginSettingsOptions<TSettings extends Record<string, any>> {
+  suite: string;
+  filename?: string;
+  schema: ZodType<TSettings> & { partial?: () => ZodType<Partial<TSettings>> };
+  defaultData?: Partial<TSettings>;
+  contract?: SettingsContract<TSettings>;
+  contractName?: string;
+  description?: string;
+  namespace?: string;
+  baseDir?: string;
+  watchDebounceMs?: number;
+}
+
+export type SharedSettingsListener<TSettings> = (settings: TSettings) => void;
+
+export interface SharedPluginSettings<TSettings extends Record<string, any>> {
+  readonly suite: string;
+  readonly contract: SettingsContract<TSettings>;
+  readonly storage: PluginStorage<TSettings>;
+  readonly filePath: string;
+  get(): Promise<TSettings>;
+  update(patch: Partial<TSettings>): Promise<TSettings>;
+  reset(): Promise<TSettings>;
+  read(): TSettings;
+  reload(): TSettings;
+  subscribe(listener: SharedSettingsListener<TSettings>): () => void;
+  watch(listener: SharedSettingsListener<TSettings>): () => void;
+  register(
+    context: HandleableServerContext,
+    options?: RegisterSettingsRpcOptions<TSettings>,
+  ): void;
+  createHandlers(options?: RegisterSettingsRpcOptions<TSettings>): {
+    get: () => Promise<TSettings>;
+    update: (input: unknown) => Promise<TSettings>;
+    reset: () => Promise<TSettings>;
+  };
+  dispose(): void;
+}
+
+function safeSerialize(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Creates a suite-scoped settings store shared across independent sibling plugins.
+ * Every plugin in the suite points at the same file
+ * (`~/.paseo/plugin-data/xpufx/<suite>/<filename>`) through an atomic PluginStorage,
+ * so an update written by Plugin A is immediately readable by Plugin B.
+ */
+export function createSharedPluginSettings<TSettings extends Record<string, any>>(
+  options: SharedPluginSettingsOptions<TSettings>,
+): SharedPluginSettings<TSettings> {
+  const {
+    suite,
+    filename = "settings.json",
+    schema,
+    defaultData,
+    description,
+    namespace,
+    baseDir,
+    watchDebounceMs = 25,
+  } = options;
+  const contractName = options.contractName ?? `${suite}.shared-settings`;
+
+  const contract =
+    options.contract ??
+    defineSettingsContract({
+      name: contractName,
+      schema,
+      ...(defaultData !== undefined ? { defaultData } : {}),
+      ...(description !== undefined ? { description } : {}),
+    });
+
+  const storage = new PluginStorage<TSettings>(suite, filename, {
+    ...(namespace !== undefined ? { namespace } : {}),
+    ...(baseDir !== undefined ? { baseDir } : {}),
+    schema: contract.schema,
+    defaultData: contract.defaultSettings,
+  });
+
+  const listeners = new Set<SharedSettingsListener<TSettings>>();
+  let watcher: fs.FSWatcher | null = null;
+  let debounceTimer: NodeJS.Timeout | null = null;
+  let lastSnapshot = "";
+
+  function snapshot(): string {
+    return safeSerialize(storage.read());
+  }
+
+  function emitIfChanged(): void {
+    const next = storage.read();
+    const nextSnapshot = safeSerialize(next);
+    if (nextSnapshot !== lastSnapshot) {
+      lastSnapshot = nextSnapshot;
+      for (const listener of [...listeners]) {
+        try {
+          listener(next);
+        } catch {
+          // Listener errors must not break sibling notification fan-out
+        }
+      }
+    }
+  }
+
+  function scheduleEmit(): void {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    // @ts-ignore
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null;
+      try {
+        emitIfChanged();
+      } catch {
+        // Disk reads may race atomic renames; next event retries
+      }
+    }, watchDebounceMs);
+  }
+
+  function ensureWatcher(): void {
+    if (watcher) return;
+    const dir = path.dirname(storage.filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    lastSnapshot = snapshot();
+    watcher = fs.watch(dir, (_event, watchedFile) => {
+      if (watchedFile && watchedFile.toString() !== path.basename(storage.filePath)) return;
+      scheduleEmit();
+    });
+    watcher.on("error", () => {});
+    if (typeof (watcher as unknown as { unref?: () => void }).unref === "function") {
+      (watcher as unknown as { unref: () => void }).unref();
+    }
+  }
+
+  function disposeWatcher(): void {
+    if (debounceTimer) {
+// @ts-ignore
+    clearTimeout(debounceTimer);
+      debounceTimer = null;
+    }
+    if (watcher) {
+      try {
+        watcher.close();
+      } catch {}
+      watcher = null;
+    }
+  }
+
+  function subscribe(listener: SharedSettingsListener<TSettings>): () => void {
+    listeners.add(listener);
+    try {
+      ensureWatcher();
+    } catch {
+      // Watching is best-effort; polling via reload() still works
+    }
+    return () => {
+      listeners.delete(listener);
+      if (listeners.size === 0) disposeWatcher();
+    };
+  }
+
+  return {
+    suite,
+    contract,
+    storage,
+    filePath: storage.filePath,
+
+    async get(): Promise<TSettings> {
+      return storage.readAsync();
+    },
+
+    async update(patch: Partial<TSettings>): Promise<TSettings> {
+      const updated = await storage.updateAsync((current) => ({
+        ...current,
+        ...patch,
+      }));
+      lastSnapshot = safeSerialize(updated);
+      for (const listener of [...listeners]) {
+        try {
+          listener(updated);
+        } catch {}
+      }
+      return updated;
+    },
+
+    async reset(): Promise<TSettings> {
+      storage.reset();
+      const fresh = await storage.readAsync();
+      lastSnapshot = safeSerialize(fresh);
+      for (const listener of [...listeners]) {
+        try {
+          listener(fresh);
+        } catch {}
+      }
+      return fresh;
+    },
+
+    read(): TSettings {
+      return storage.read();
+    },
+
+    reload(): TSettings {
+      const next = storage.read();
+      lastSnapshot = safeSerialize(next);
+      return next;
+    },
+
+    subscribe,
+    watch: subscribe,
+
+    register(
+      context: HandleableServerContext,
+      rpcOptions: RegisterSettingsRpcOptions<TSettings> = {},
+    ): void {
+      registerSettingsRpc(context, contract, storage, rpcOptions);
+    },
+
+    createHandlers(rpcOptions: RegisterSettingsRpcOptions<TSettings> = {}) {
+      return createSettingsHandlers(contract, storage, rpcOptions);
+    },
+
+    dispose(): void {
+      listeners.clear();
+      disposeWatcher();
+    },
+  };
+}

package/server/vendor/paseo-plugin-helper/storage.ts

@@ -0,0 +1,244 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import type { ZodType } from "zod";
+
+export interface PluginStorageOptions<T> {
+  defaultData?: T;
+  /**
+   * Base directory override. When provided, storage is located at path.join(baseDir, pluginId).
+   * When omitted, defaults to path.join(os.homedir(), ".paseo", namespace ?? "plugin-data/xpufx", pluginId).
+   */
+  baseDir?: string;
+  /**
+   * Namespace directory under ~/.paseo. Defaults to "plugin-data/xpufx".
+   */
+  namespace?: string;
+  /**
+   * Optional Zod schema to validate and parse data on read/write, automatically applying defaults.
+   */
+  schema?: ZodType<T>;
+}
+
+export interface StorageStats {
+  path: string;
+  fileCount: number;
+  totalBytes: number;
+  lastModified: Date | null;
+}
+
+export const DEFAULT_NAMESPACE_README = `# Paseo Plugins Storage (xpufx)
+
+This directory is managed by \`paseo-plugin-helper\` to store persistent settings, cached metrics, and state for plugins.
+- Safe to inspect or backup.
+- Avoid editing files manually while the Paseo daemon is active.
+`;
+
+/**
+ * Scoped, atomic filesystem-backed document storage for Paseo daemon plugins.
+ * Automatically handles directory creation, atomic temporary file swaps,
+ * schema validation, default state fallback, and isolated namespace auditing.
+ * State lives under ~/.paseo/plugin-data/xpufx/<pluginId>/ by default.
+ */
+export class PluginStorage<T extends Record<string, any>> {
+  readonly pluginId: string;
+  readonly filename: string;
+  readonly pluginDir: string;
+  readonly filePath: string;
+  readonly namespaceDir: string | null;
+  readonly defaultData?: T;
+  readonly schema?: ZodType<T>;
+
+  constructor(pluginId: string, filename = "state.json", options: PluginStorageOptions<T> = {}) {
+    this.pluginId = pluginId;
+    this.filename = filename;
+    this.defaultData = options.defaultData;
+    this.schema = options.schema;
+
+    const namespace = options.namespace ?? "plugin-data/xpufx";
+    if (options.baseDir) {
+      this.namespaceDir = options.baseDir;
+      this.pluginDir = path.join(options.baseDir, pluginId);
+    } else {
+      this.namespaceDir = path.join(os.homedir(), ".paseo", namespace);
+      this.pluginDir = path.join(this.namespaceDir, pluginId);
+    }
+
+    this.filePath = path.join(this.pluginDir, filename);
+  }
+
+  private ensureDir(): void {
+    if (this.namespaceDir && !fs.existsSync(this.namespaceDir)) {
+      fs.mkdirSync(this.namespaceDir, { recursive: true });
+    }
+    if (this.namespaceDir) {
+      const readmePath = path.join(this.namespaceDir, "README.md");
+      if (!fs.existsSync(readmePath)) {
+        try {
+          fs.writeFileSync(readmePath, DEFAULT_NAMESPACE_README, "utf8");
+        } catch {
+          // Non-fatal if filesystem is read-only
+        }
+      }
+    }
+    const dir = path.dirname(this.filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  private getDefault(): T {
+    if (this.schema) {
+      const result = this.schema.safeParse(this.defaultData ?? {});
+      if (result.success) {
+        return result.data;
+      }
+    }
+    return this.defaultData ? (JSON.parse(JSON.stringify(this.defaultData)) as T) : ({} as T);
+  }
+
+  private parseData(raw: unknown): T {
+    if (this.schema) {
+      const result = this.schema.safeParse(raw);
+      if (result.success) {
+        return result.data;
+      }
+      return this.getDefault();
+    }
+    return raw as T;
+  }
+
+  /**
+   * Checks if the backing state file exists.
+   */
+  exists(): boolean {
+    return fs.existsSync(this.filePath);
+  }
+
+  /**
+   * Reads data synchronously. If file does not exist, returns defaultData.
+   */
+  read(): T {
+    try {
+      if (!fs.existsSync(this.filePath)) {
+        return this.getDefault();
+      }
+      const raw = fs.readFileSync(this.filePath, "utf8");
+      return this.parseData(JSON.parse(raw));
+    } catch {
+      return this.getDefault();
+    }
+  }
+
+  /**
+   * Reads data asynchronously.
+   */
+  async readAsync(): Promise<T> {
+    try {
+      if (!fs.existsSync(this.filePath)) {
+        return this.getDefault();
+      }
+      const raw = await fs.promises.readFile(this.filePath, "utf8");
+      return this.parseData(JSON.parse(raw));
+    } catch {
+      return this.getDefault();
+    }
+  }
+
+  /**
+   * Writes data atomically using a temporary file and atomic rename.
+   */
+  write(data: T): void {
+    const validated = this.parseData(data);
+    this.ensureDir();
+    const tempPath = `${this.filePath}.tmp.${process.pid}.${Date.now()}`;
+    const serialized = JSON.stringify(validated, null, 2);
+    fs.writeFileSync(tempPath, serialized, "utf8");
+    fs.renameSync(tempPath, this.filePath);
+  }
+
+  /**
+   * Writes data atomically using async filesystem operations.
+   */
+  async writeAsync(data: T): Promise<void> {
+    const validated = this.parseData(data);
+    this.ensureDir();
+    const tempPath = `${this.filePath}.tmp.${process.pid}.${Date.now()}`;
+    const serialized = JSON.stringify(validated, null, 2);
+    await fs.promises.writeFile(tempPath, serialized, "utf8");
+    await fs.promises.rename(tempPath, this.filePath);
+  }
+
+  /**
+   * Updates state synchronously using an updater function.
+   */
+  update(updater: (prev: T) => T): T {
+    const current = this.read();
+    const updated = updater(current);
+    const validated = this.parseData(updated);
+    this.write(validated);
+    return validated;
+  }
+
+  /**
+   * Updates state asynchronously using an updater function.
+   */
+  async updateAsync(updater: (prev: T) => Promise<T> | T): Promise<T> {
+    const current = await this.readAsync();
+    const updated = await updater(current);
+    const validated = this.parseData(updated);
+    await this.writeAsync(validated);
+    return validated;
+  }
+
+  /**
+   * Removes the state file if it exists.
+   */
+  reset(): void {
+    if (fs.existsSync(this.filePath)) {
+      try {
+        fs.unlinkSync(this.filePath);
+      } catch {}
+    }
+  }
+
+  /**
+   * Audits storage consumption, returning path, fileCount, totalBytes, and lastModified.
+   */
+  async getStorageStats(): Promise<StorageStats> {
+    const stats: StorageStats = {
+      path: this.pluginDir,
+      fileCount: 0,
+      totalBytes: 0,
+      lastModified: null,
+    };
+
+    if (!fs.existsSync(this.pluginDir)) {
+      return stats;
+    }
+
+    try {
+      const entries = await fs.promises.readdir(this.pluginDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isFile()) {
+          stats.fileCount++;
+          const target = path.join(this.pluginDir, entry.name);
+          const st = await fs.promises.stat(target);
+          stats.totalBytes += st.size;
+          if (!stats.lastModified || st.mtime > stats.lastModified) {
+            stats.lastModified = st.mtime;
+          }
+        }
+      }
+    } catch {}
+
+    return stats;
+  }
+
+  /**
+   * Alias for getStorageStats()
+   */
+  async getStats(): Promise<StorageStats> {
+    return this.getStorageStats();
+  }
+}

package/server/vendor/paseo-plugin-helper/system.ts

@@ -0,0 +1,128 @@
+import os from "node:os";
+
+export interface CpuCoreMetrics {
+  model: string;
+  speed: number;
+  usagePercent: number;
+}
+
+export interface SystemMetrics {
+  hostname: string;
+  platform: NodeJS.Platform;
+  arch: string;
+  uptimeSeconds: number;
+  cpu: {
+    model: string;
+    cores: number;
+    usagePercent: number;
+    loadAverage: [number, number, number];
+  };
+  memory: {
+    totalBytes: number;
+    freeBytes: number;
+    usedBytes: number;
+    usedPercent: number;
+  };
+}
+
+interface CpuTickSample {
+  idle: number;
+  total: number;
+}
+
+/**
+ * Samples CPU ticks and calculates delta usage percentage over time.
+ */
+export class CpuSampler {
+  private lastSample: CpuTickSample[] | null = null;
+
+  constructor() {
+    this.lastSample = this.getTicks();
+  }
+
+  private getTicks(): CpuTickSample[] {
+    const cpus = os.cpus();
+    return cpus.map((cpu) => {
+      const times = cpu.times;
+      const total =
+        times.user + times.nice + times.sys + times.idle + times.irq;
+      return { idle: times.idle, total };
+    });
+  }
+
+  /**
+   * Computes the CPU usage delta since the previous sample (or between two samples).
+   * Returns average usage percentage (0 - 100) and per-core breakdown.
+   */
+  sample(): { usagePercent: number; perCore: number[] } {
+    const current = this.getTicks();
+    if (!this.lastSample || this.lastSample.length !== current.length) {
+      this.lastSample = current;
+      return { usagePercent: 0, perCore: current.map(() => 0) };
+    }
+
+    const perCore: number[] = [];
+    let totalActive = 0;
+    let totalTime = 0;
+
+    for (let i = 0; i < current.length; i++) {
+      const prev = this.lastSample[i];
+      const cur = current[i];
+
+      const deltaTotal = cur.total - prev.total;
+      const deltaIdle = cur.idle - prev.idle;
+      const deltaActive = Math.max(0, deltaTotal - deltaIdle);
+
+      const corePercent =
+        deltaTotal > 0 ? (deltaActive / deltaTotal) * 100 : 0;
+      perCore.push(Math.round(corePercent * 10) / 10);
+
+      totalActive += deltaActive;
+      totalTime += deltaTotal;
+    }
+
+    this.lastSample = current;
+
+    const usagePercent =
+      totalTime > 0 ? (totalActive / totalTime) * 100 : 0;
+
+    return {
+      usagePercent: Math.round(usagePercent * 10) / 10,
+      perCore,
+    };
+  }
+}
+
+const defaultSampler = new CpuSampler();
+
+/**
+ * Returns instant system resources and metrics (CPU, RAM, load averages, uptime).
+ */
+export function getSystemMetrics(sampler: CpuSampler = defaultSampler): SystemMetrics {
+  const cpus = os.cpus();
+  const totalmem = os.totalmem();
+  const freemem = os.freemem();
+  const usedmem = totalmem - freemem;
+  const cpuModel = cpus[0]?.model || "Unknown CPU";
+
+  const { usagePercent } = sampler.sample();
+
+  return {
+    hostname: os.hostname(),
+    platform: process.platform,
+    arch: process.arch,
+    uptimeSeconds: Math.floor(os.uptime()),
+    cpu: {
+      model: cpuModel,
+      cores: cpus.length,
+      usagePercent,
+      loadAverage: os.loadavg() as [number, number, number],
+    },
+    memory: {
+      totalBytes: totalmem,
+      freeBytes: freemem,
+      usedBytes: usedmem,
+      usedPercent: Math.round((usedmem / totalmem) * 1000) / 10,
+    },
+  };
+}