@xpufx/paseo-twofado 0.1.0

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,
+    },
+  };
+}

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

@@ -0,0 +1,116 @@
+import { createPluginLogger, type PluginLogger } from "./logger";
+
+export interface PeriodicTaskOptions {
+  intervalMs: number;
+  task: () => Promise<void> | void;
+  onError?: (err: unknown, failureCount: number) => void;
+  runImmediately?: boolean;
+  maxBackoffMs?: number;
+  /**
+   * Logger for suppressed failures. Defaults to a level-gated
+   * `periodic-task` logger so debug lines stay silent unless debug is enabled.
+   */
+  logger?: PluginLogger;
+}
+
+export interface PeriodicTaskHandle {
+  stop: () => void;
+  isRunning: () => boolean;
+  triggerNow: () => Promise<void>;
+}
+
+/**
+ * Creates a resilient periodic background task loop for Paseo plugin daemons.
+ * Implements exponential backoff on consecutive failures and safe teardown hooks.
+ */
+export function createPeriodicTask(options: PeriodicTaskOptions): PeriodicTaskHandle {
+  const {
+    intervalMs,
+    task,
+    onError,
+    runImmediately = false,
+    maxBackoffMs = 60000,
+  } = options;
+
+  let timer: any = null;
+  let running = true;
+  let inFlight = false;
+  let failureCount = 0;
+
+  let taskLogger: PluginLogger | undefined;
+  function taskLog(): PluginLogger {
+    taskLogger ??= options.logger
+      ? options.logger.child("periodic-task")
+      : createPluginLogger("periodic-task", { banner: false });
+    return taskLogger;
+  }
+
+  async function execute() {
+    if (!running || inFlight) return;
+    inFlight = true;
+
+    try {
+      await task();
+      failureCount = 0;
+    } catch (err) {
+      failureCount++;
+      if (onError) {
+        try {
+          onError(err, failureCount);
+        } catch (suppressed) {
+          // Prevent onError handler from breaking task loop, but stay visible in dev logs.
+          taskLog().debug(
+            `onError handler failed: ${suppressed instanceof Error ? suppressed.message : String(suppressed)}`,
+          );
+        }
+      } else {
+        taskLog().debug(
+          `suppressed error (failure ${failureCount}): ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    } finally {
+      inFlight = false;
+      if (running) {
+        scheduleNext();
+      }
+    }
+  }
+
+  function scheduleNext() {
+    if (!running) return;
+    if (timer) clearTimeout(timer);
+
+    let delay = intervalMs;
+    if (failureCount > 0) {
+      // Exponential backoff with ceiling
+      const backoff = intervalMs * Math.pow(1.5, Math.min(failureCount, 8));
+      delay = Math.min(backoff, maxBackoffMs);
+    }
+
+    timer = setTimeout(execute, delay);
+  }
+
+  if (runImmediately) {
+    execute();
+  } else {
+    scheduleNext();
+  }
+
+  return {
+    stop: () => {
+      running = false;
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    },
+    isRunning: () => running,
+    triggerNow: async () => {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      await execute();
+    },
+  };
+}

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

@@ -0,0 +1,153 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+
+export interface ResolveVersionOptions {
+  /**
+   * Root directory of the plugin (defaults to `process.cwd()`).
+   */
+  cwd?: string;
+
+  /**
+   * Whether to augment development versions with git commit short hash
+   * (e.g. "0.1.0-dev.bfe901a" if not an exact tag).
+   * Defaults to `true`.
+   */
+  includeGit?: boolean;
+
+  /**
+   * Fallback string if neither package.json nor git metadata can be found.
+   * Defaults to "0.0.0".
+   */
+  fallback?: string;
+}
+
+/**
+ * Finds the nearest package.json starting from directory and moving up.
+ */
+function findPackageJson(startDir: string): { version?: string; name?: string } | null {
+  let current = path.resolve(startDir);
+  const root = path.parse(current).root;
+
+  while (current !== root) {
+    const pkgPath = path.join(current, "package.json");
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const raw = fs.readFileSync(pkgPath, "utf8");
+        return JSON.parse(raw);
+      } catch {
+        return null;
+      }
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+
+  return null;
+}
+
+/**
+ * Resolves the plugin version from `package.json`, augmented by Git tag / commit hash.
+ *
+ * Precedence:
+ * 1. Exact Git tag on current commit (e.g. "v0.1.2" or "0.1.2")
+ * 2. `package.json` version (augmented with "-dev.hash" if in git and not on an exact release tag)
+ * 3. Git commit short hash fallback (e.g. "dev-bfe901a")
+ * 4. Fallback string (defaults to "0.0.0")
+ */
+export function resolvePluginVersion(options: ResolveVersionOptions = {}): string {
+  const {
+    cwd = process.cwd(),
+    includeGit = true,
+    fallback = "0.0.0",
+  } = options;
+
+  let pkgVersion: string | undefined;
+
+  // 1. Read package.json
+  const pkg = findPackageJson(cwd);
+  if (pkg?.version) {
+    pkgVersion = pkg.version;
+  }
+
+  if (!includeGit) {
+    return pkgVersion || fallback;
+  }
+
+  // 2. Check if git is available and on an exact tag
+  try {
+    const gitTag = execSync("git describe --tags --exact-match 2>/dev/null", {
+      cwd,
+      encoding: "utf8",
+      timeout: 1000,
+    }).trim();
+
+    if (gitTag) {
+      // Strip leading 'v' if present for clean semantic format (e.g. "v0.1.2" -> "0.1.2")
+      return gitTag.startsWith("v") ? gitTag.slice(1) : gitTag;
+    }
+  } catch {
+    // Not on an exact tag or git not installed
+  }
+
+  // 3. If package.json has a version, check if we should add git short commit
+  try {
+    const gitHash = execSync("git rev-parse --short HEAD 2>/dev/null", {
+      cwd,
+      encoding: "utf8",
+      timeout: 1000,
+    }).trim();
+
+    if (gitHash) {
+      if (pkgVersion) {
+        return `${pkgVersion}+${gitHash}`;
+      }
+      return `0.0.0+${gitHash}`;
+    }
+  } catch {
+    // Not a git repository
+  }
+
+  return pkgVersion || fallback;
+}
+
+export interface StampVersionOptions extends ResolveVersionOptions {
+  /**
+   * Destination TypeScript / JavaScript file path.
+   * Defaults to "./version.ts" or "./src/version.ts".
+   */
+  targetFile?: string;
+}
+
+/**
+ * Build-time utility to stamp the resolved version into a TypeScript file (e.g. `version.ts`),
+ * allowing client code (React Native) to import `PLUGIN_VERSION` directly without
+ * needing `node:fs` or `process.cwd()` at runtime.
+ */
+export function stampVersion(options: StampVersionOptions = {}): {
+  version: string;
+  targetFile: string;
+  updated: boolean;
+} {
+  const cwd = options.cwd ?? process.cwd();
+  const targetFile = options.targetFile
+    ? path.resolve(cwd, options.targetFile)
+    : path.resolve(cwd, "version.ts");
+
+  const version = resolvePluginVersion(options);
+  const content = `// Auto-generated by paseo-plugin-helper. Do not edit.\nexport const PLUGIN_VERSION = "${version}";\n`;
+
+  let existing = "";
+  if (fs.existsSync(targetFile)) {
+    existing = fs.readFileSync(targetFile, "utf8");
+  }
+
+  if (existing !== content) {
+    fs.mkdirSync(path.dirname(targetFile), { recursive: true });
+    fs.writeFileSync(targetFile, content, "utf8");
+    return { version, targetFile, updated: true };
+  }
+
+  return { version, targetFile, updated: false };
+}