@xpufx/paseo-slash 0.1.0

package/server/vendor/paseo-plugin-helper/custom-pills.ts

@@ -0,0 +1,344 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseJsonc } from "./jsonc";
+import { safeExec } from "./process";
+import type { PluginLogger } from "./logger";
+import {
+  CustomPillDefinitionSchema,
+  type CustomPillDefinition,
+  type CustomPillState,
+  resolveCustomPillStatus,
+  parseNumericPillValue,
+  formatPillDisplay,
+} from "../../../shared/vendor/paseo-plugin-helper/custom-pills";
+
+
+/**
+ * Discovers and validates all custom pill configuration files (.json / .jsonc)
+ * from a directory (e.g. ~/.paseo/top/pills or ~/.paseo/custom-pills).
+ */
+export async function discoverCustomPillConfigs(
+  dirPath: string,
+  logger?: PluginLogger,
+): Promise<CustomPillDefinition[]> {
+  try {
+    if (!fs.existsSync(dirPath)) {
+      return [];
+    }
+
+    const entries = await fs.promises.readdir(dirPath, { withFileTypes: true });
+    const configs: CustomPillDefinition[] = [];
+
+    for (const entry of entries) {
+      if (
+        !entry.isFile() ||
+        (!entry.name.endsWith(".json") && !entry.name.endsWith(".jsonc"))
+      ) {
+        continue;
+      }
+
+      const filePath = path.join(dirPath, entry.name);
+      try {
+        const rawContent = await fs.promises.readFile(filePath, "utf-8");
+        const parsed = parseJsonc(rawContent);
+
+        const result = CustomPillDefinitionSchema.safeParse(parsed);
+        if (result.success) {
+          configs.push({ ...result.data, sourceFile: filePath });
+        } else {
+          logger?.warn(
+            `Invalid custom pill config in ${entry.name}: ${result.error.issues.map((i) => i.message).join(", ")}`,
+          );
+        }
+      } catch (err) {
+        logger?.warn(
+          `Failed to read custom pill config from ${entry.name}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+
+    return configs;
+  } catch (err) {
+    logger?.warn(
+      `Error reading custom pills directory ${dirPath}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return [];
+  }
+}
+
+export interface CustomPillPollerOptions {
+  /**
+   * Initial list of custom pill definitions.
+   */
+  pills?: CustomPillDefinition[];
+
+  /**
+   * Optional directory to discover .json / .jsonc configs from.
+   */
+  configDir?: string;
+
+  /**
+   * Custom environment variables passed to all executed commands
+   * (e.g. PASEO_AGENT_ID, PASEO_WORKSPACE_ID).
+   */
+  env?: Record<string, string>;
+
+  /**
+   * Working directory for executed commands. Defaults to process.cwd().
+   */
+  cwd?: string;
+
+  /**
+   * Optional structured logger.
+   */
+  logger?: PluginLogger;
+
+  /**
+   * Callback fired whenever any custom pill state changes.
+   */
+  onUpdate?: (states: CustomPillState[]) => void;
+}
+
+/**
+ * Managed server poller for user-defined declarative custom metric pills.
+ * Periodically executes shell commands, computes statuses via thresholds,
+ * and maintains reactive live state.
+ */
+export class CustomPillPoller {
+  private pills = new Map<string, CustomPillDefinition>();
+  private states = new Map<string, CustomPillState>();
+  private timers = new Map<string, ReturnType<typeof setTimeout>>();
+  private inFlight = new Set<string>();
+  private running = false;
+  private options: CustomPillPollerOptions;
+
+  constructor(options: CustomPillPollerOptions = {}) {
+    this.options = options;
+    if (options.pills) {
+      for (const pill of options.pills) {
+        this.pills.set(pill.id, pill);
+      }
+    }
+  }
+
+  /**
+   * Starts the polling loops for all configured custom pills.
+   */
+  async start(): Promise<void> {
+    if (this.running) return;
+    this.running = true;
+
+    if (this.options.configDir) {
+      const discovered = await discoverCustomPillConfigs(
+        this.options.configDir,
+        this.options.logger,
+      );
+      for (const pill of discovered) {
+        this.pills.set(pill.id, pill);
+      }
+    }
+
+    for (const pill of this.pills.values()) {
+      if (pill.enabled) {
+        this.schedulePill(pill, 0);
+      }
+    }
+  }
+
+  /**
+   * Manually triggers an immediate execution of a single custom pill.
+   */
+  async pollPill(pillId: string): Promise<CustomPillState | undefined> {
+    const pill = this.pills.get(pillId);
+    if (!pill) return undefined;
+    if (this.inFlight.has(pillId)) {
+      return this.states.get(pillId);
+    }
+
+    this.inFlight.add(pillId);
+    try {
+      const result = await safeExec(pill.command, {
+        timeoutMs: pill.timeoutMs,
+        env: { ...process.env, ...this.options.env },
+        cwd: this.options.cwd,
+      });
+
+      const rawValue = result.stdout || result.stderr || "";
+      const numericValue = parseNumericPillValue(rawValue);
+      const status = resolveCustomPillStatus(numericValue, pill.thresholds);
+      const displayValue = formatPillDisplay(rawValue, pill.prefix, pill.suffix);
+
+      const state: CustomPillState = {
+        id: pill.id,
+        title: pill.title,
+        compactTitle: pill.compactTitle,
+        icon: pill.icon,
+        compactIcon: pill.compactIcon,
+        rawValue,
+        displayValue,
+        numericValue,
+        status,
+        lastUpdated: Date.now(),
+        sourceFile: pill.sourceFile,
+        modalTitle: pill.modal?.title ?? pill.title,
+        modalDescription: pill.modal?.description,
+      };
+
+      this.states.set(pill.id, state);
+      this.notifyUpdate();
+      return state;
+    } catch (err) {
+      const errorMsg = err instanceof Error ? err.message : String(err);
+      this.options.logger?.warn(`Custom pill '${pill.id}' execution failed: ${errorMsg}`);
+
+      const previous = this.states.get(pill.id);
+      const state: CustomPillState = {
+        id: pill.id,
+        title: pill.title,
+        compactTitle: pill.compactTitle,
+        icon: pill.icon,
+        compactIcon: pill.compactIcon,
+        rawValue: previous?.rawValue ?? "ERR",
+        displayValue: previous?.displayValue ?? "ERR",
+        status: "danger",
+        lastUpdated: Date.now(),
+        error: errorMsg,
+        sourceFile: pill.sourceFile,
+        modalTitle: pill.modal?.title ?? pill.title,
+        modalDescription: pill.modal?.description,
+      };
+
+      this.states.set(pill.id, state);
+      this.notifyUpdate();
+      return state;
+    } finally {
+      this.inFlight.delete(pillId);
+    }
+  }
+
+  /**
+   * Executes the on-demand drilldown command configured in pill.modal.command.
+   */
+  async runModalCommand(
+    pillId: string,
+  ): Promise<{ output?: string; error?: string }> {
+    const pill = this.pills.get(pillId);
+    if (!pill) {
+      return { error: `Custom pill '${pillId}' not found` };
+    }
+
+    const commandToRun = pill.modal?.command ?? pill.command;
+    try {
+      const result = await safeExec(commandToRun, {
+        timeoutMs: pill.timeoutMs,
+        env: { ...process.env, ...this.options.env },
+        cwd: this.options.cwd,
+      });
+
+      const output = result.stdout || result.stderr || "No output";
+      const existing = this.states.get(pillId);
+      if (existing) {
+        existing.modalOutput = output;
+        existing.modalLastUpdated = Date.now();
+        delete existing.modalError;
+        this.notifyUpdate();
+      }
+
+      return { output };
+    } catch (err) {
+      const errorMsg = err instanceof Error ? err.message : String(err);
+      const existing = this.states.get(pillId);
+      if (existing) {
+        existing.modalError = errorMsg;
+        this.notifyUpdate();
+      }
+      return { error: errorMsg };
+    }
+  }
+
+  /**
+   * Updates or reconciles the list of pill definitions dynamically.
+   */
+  updatePills(newPills: CustomPillDefinition[]): void {
+    const nextIds = new Set(newPills.map((p) => p.id));
+
+    // Remove obsolete pills
+    for (const [id, timer] of this.timers.entries()) {
+      if (!nextIds.has(id)) {
+        clearTimeout(timer);
+        this.timers.delete(id);
+        this.pills.delete(id);
+        this.states.delete(id);
+      }
+    }
+
+    // Add or update pills
+    for (const pill of newPills) {
+      this.pills.set(pill.id, pill);
+      const currentTimer = this.timers.get(pill.id);
+      if (currentTimer) {
+        clearTimeout(currentTimer);
+        this.timers.delete(pill.id);
+      }
+
+      if (this.running && pill.enabled) {
+        this.schedulePill(pill, 0);
+      }
+    }
+
+    this.notifyUpdate();
+  }
+
+  /**
+   * Returns live state for a single custom pill.
+   */
+  getState(pillId: string): CustomPillState | undefined {
+    return this.states.get(pillId);
+  }
+
+  /**
+   * Returns live states for all custom pills.
+   */
+  getAllStates(): CustomPillState[] {
+    return Array.from(this.states.values());
+  }
+
+  /**
+   * Stops all active polling loops and clears resources.
+   */
+  stop(): void {
+    this.running = false;
+    for (const timer of this.timers.values()) {
+      clearTimeout(timer);
+    }
+    this.timers.clear();
+    this.inFlight.clear();
+  }
+
+  private schedulePill(pill: CustomPillDefinition, delayMs: number): void {
+    if (!this.running) return;
+
+    // @ts-ignore
+    const timer = setTimeout(async () => {
+      await this.pollPill(pill.id);
+      if (this.running && this.pills.has(pill.id)) {
+        const nextPill = this.pills.get(pill.id);
+        if (nextPill?.enabled) {
+          this.schedulePill(nextPill, nextPill.intervalMs);
+        }
+      }
+    }, delayMs as any);
+
+    this.timers.set(pill.id, timer);
+  }
+
+  private notifyUpdate(): void {
+    if (this.options.onUpdate) {
+      try {
+        this.options.onUpdate(this.getAllStates());
+      } catch {
+        // Prevent callback errors from disrupting poller
+      }
+    }
+  }
+}

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

@@ -0,0 +1,18 @@
+export * from "./storage";
+export * from "./settings";
+export * from "./shared-settings";
+export * from "./jsonc";
+export * from "./redact";
+export * from "./process";
+export * from "./system";
+export * from "./logger";
+export * from "./version";
+export * from "./network";
+export * from "./task";
+export * from "./mcp-config";
+export * from "./mcp-injection";
+export * from "./plugins";
+export * from "./custom-pills";
+export * from "./rpc-guard";
+export * from "./agent";
+export * from "./workspace-beacon";

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

@@ -0,0 +1,78 @@
+/**
+ * Strips single-line and multi-line comments and trailing commas from a JSONC string
+ * without altering strings or URLs.
+ */
+export function stripJsonComments(text: string): string {
+  let insideString = false;
+  let stringDelimiter = "";
+  let isEscaped = false;
+  let result = "";
+
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i];
+    const nextChar = text[i + 1];
+
+    if (insideString) {
+      result += char;
+      if (isEscaped) {
+        isEscaped = false;
+      } else if (char === "\\") {
+        isEscaped = true;
+      } else if (char === stringDelimiter) {
+        insideString = false;
+      }
+      continue;
+    }
+
+    if (char === '"' || char === "'") {
+      insideString = true;
+      stringDelimiter = char;
+      result += char;
+      continue;
+    }
+
+    // Line comment
+    if (char === "/" && nextChar === "/") {
+      while (i < text.length && text[i] !== "\n" && text[i] !== "\r") {
+        i++;
+      }
+      if (i < text.length) result += text[i];
+      continue;
+    }
+
+    // Block comment
+    if (char === "/" && nextChar === "*") {
+      i += 2;
+      while (i < text.length - 1 && !(text[i] === "*" && text[i + 1] === "/")) {
+        i++;
+      }
+      i++; // Skip closing '/'
+      continue;
+    }
+
+    result += char;
+  }
+
+  // Remove trailing commas before } or ]
+  return result.replace(/,\s*([}\]])/g, "$1");
+}
+
+/**
+ * Safely parses a JSONC (JSON with comments and trailing commas) string.
+ */
+export function parseJsonc<T = unknown>(text: string): T {
+  const sanitized = stripJsonComments(text.trim());
+  return JSON.parse(sanitized) as T;
+}
+
+/**
+ * Safely parses a JSONC string without throwing errors.
+ * Returns the provided fallback value if parsing fails.
+ */
+export function tryParseJsonc<T>(text: string, fallback: T): T {
+  try {
+    return parseJsonc<T>(text);
+  } catch {
+    return fallback;
+  }
+}

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

@@ -0,0 +1,210 @@
+import { redactSecrets } from "./redact";
+import { resolvePluginVersion } from "./version";
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+const LEVEL_SEVERITY: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+};
+
+function isLogLevel(value: unknown): value is LogLevel {
+  return (
+    value === "debug" || value === "info" || value === "warn" || value === "error"
+  );
+}
+
+/**
+ * Resolves the minimum log level from the environment. Precedence:
+ * `PASEO_PLUGIN_LOG_LEVEL` > `PASEO_LOG_LEVEL` > `PASEO_DEBUG=1` (debug).
+ * Returns undefined when nothing is set so callers can apply their default.
+ */
+export function resolveMinLevelFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): LogLevel | undefined {
+  const raw = env.PASEO_PLUGIN_LOG_LEVEL ?? env.PASEO_LOG_LEVEL;
+  if (typeof raw === "string" && isLogLevel(raw.trim().toLowerCase())) {
+    return raw.trim().toLowerCase() as LogLevel;
+  }
+  const debugFlag = env.PASEO_DEBUG ?? env.PASEO_PLUGIN_DEBUG;
+  if (
+    typeof debugFlag === "string" &&
+    ["1", "true", "yes", "debug"].includes(debugFlag.trim().toLowerCase())
+  ) {
+    return "debug";
+  }
+  return undefined;
+}
+
+/**
+ * True when running in production. Retained for callers that need a
+ * production check; note the default log level no longer keys off this.
+ */
+export function isProductionEnv(env: NodeJS.ProcessEnv = process.env): boolean {
+  return (env.NODE_ENV ?? "").trim().toLowerCase() === "production";
+}
+
+/**
+ * True only when `NODE_ENV` is explicitly a development value
+ * (`development`/`dev`). Unset, empty, `production`, and anything else
+ * (e.g. `test`) all count as quiet, so a shipped plugin defaults to info
+ * without any env var set.
+ */
+export function isDevelopmentEnv(env: NodeJS.ProcessEnv = process.env): boolean {
+  const nodeEnv = (env.NODE_ENV ?? "").trim().toLowerCase();
+  return nodeEnv === "development" || nodeEnv === "dev";
+}
+
+/**
+ * Default rule (documented for operators):
+ * explicit `PASEO_PLUGIN_LOG_LEVEL`/`PASEO_LOG_LEVEL`/`PASEO_DEBUG` always wins;
+ * otherwise quiet (`info`) — including when no env var is set at all, so a
+ * shipped plugin never emits debug logs by default. Debug only when `NODE_ENV`
+ * is explicitly a development value (`development`/`dev`).
+ */
+export function resolveDefaultMinLevel(
+  env: NodeJS.ProcessEnv = process.env,
+): LogLevel {
+  return resolveMinLevelFromEnv(env) ?? (isDevelopmentEnv(env) ? "debug" : "info");
+}
+
+export interface PluginLoggerOptions {
+  /**
+   * Version of the plugin.
+   * If omitted, automatically resolves from `package.json` (augmented by git tag/hash).
+   */
+  version?: string;
+
+  /**
+   * Whether to emit a formatted startup banner on initialization.
+   * Defaults to `true`.
+   */
+  banner?: boolean;
+
+  /**
+   * Subsystem or module tag within the plugin (e.g. "poller", "mcp-client").
+   */
+  subsystem?: string;
+
+  /**
+   * Minimum log level to print. Defaults to resolveDefaultMinLevel():
+   * info unless NODE_ENV is explicitly development (or an explicit level is set).
+   */
+  minLevel?: LogLevel;
+
+  /**
+   * Optional custom metadata key-values to include in the startup banner.
+   */
+  meta?: Record<string, string | number | boolean>;
+}
+
+export interface PluginLogger {
+  debug(message: string, data?: unknown): void;
+  info(message: string, data?: unknown): void;
+  warn(message: string, data?: unknown): void;
+  error(message: string, data?: unknown): void;
+  /** Surfaces a caught/suppressed error at debug level so it reaches the plugin log. */
+  suppressed(context: string, error: unknown): void;
+  child(subsystemOrOptions: string | Partial<PluginLoggerOptions>): PluginLogger;
+}
+
+function formatData(data: unknown): string {
+  if (data === undefined) return "";
+  if (data instanceof Error) {
+    return `error="${data.message}"${data.stack ? `\n${data.stack}` : ""}`;
+  }
+
+  const sanitized = redactSecrets(data);
+  if (typeof sanitized === "object" && sanitized !== null && !Array.isArray(sanitized)) {
+    const pairs = Object.entries(sanitized as Record<string, unknown>).map(
+      ([k, v]) => `${k}=${typeof v === "object" ? JSON.stringify(v) : String(v)}`,
+    );
+    return pairs.join(" ");
+  }
+
+  return typeof sanitized === "string" ? sanitized : JSON.stringify(sanitized);
+}
+
+/**
+ * Creates a structured logger for Paseo plugins.
+ * By default, displays the plugin name and version in startup logs and tags each line
+ * for Paseo's log stream without fragmented multi-line JSON.
+ *
+ * If `options.version` is omitted, it automatically resolves the version from `package.json`
+ * augmented with git metadata.
+ */
+export function createPluginLogger(
+  pluginId: string,
+  options: PluginLoggerOptions = {},
+): PluginLogger {
+  const resolvedVer = options.version ?? resolvePluginVersion({ fallback: "" });
+  const {
+    banner = true,
+    subsystem,
+    minLevel = resolveDefaultMinLevel(),
+    meta = {},
+  } = options;
+
+  const minSeverity = LEVEL_SEVERITY[minLevel];
+
+  // Prefix format: "[name vX.Y.Z]" or "[name]" or "[name vX.Y.Z:subsystem]"
+  const versionTag = resolvedVer ? ` v${resolvedVer}` : "";
+  const subTag = subsystem ? `:${subsystem}` : "";
+  const baseTag = `[${pluginId}${versionTag}${subTag}]`;
+
+  if (banner) {
+    const bannerDetails = [
+      `pid ${process.pid}`,
+      `node ${process.version}`,
+      ...Object.entries(meta).map(([k, v]) => `${k} ${v}`),
+    ].join(", ");
+
+    // Emit startup banner directly to stdout
+    console.log(`${baseTag} Initializing plugin (${bannerDetails})`);
+  }
+
+  function emit(level: LogLevel, message: string, data?: unknown) {
+    if (LEVEL_SEVERITY[level] < minSeverity) return;
+
+    const levelTag = `[${level.toUpperCase()}]`;
+    const formattedData = formatData(data);
+    const line = formattedData
+      ? `${baseTag} ${levelTag} ${message} ${formattedData}`
+      : `${baseTag} ${levelTag} ${message}`;
+
+    if (level === "error" || level === "warn") {
+      console.error(line);
+    } else {
+      console.log(line);
+    }
+  }
+
+  return {
+    debug(message: string, data?: unknown) {
+      emit("debug", message, data);
+    },
+    info(message: string, data?: unknown) {
+      emit("info", message, data);
+    },
+    warn(message: string, data?: unknown) {
+      emit("warn", message, data);
+    },
+    error(message: string, data?: unknown) {
+      emit("error", message, data);
+    },
+    suppressed(context: string, error: unknown) {
+      const detail = error instanceof Error ? error.message : String(error);
+      emit("debug", `${context}: ${detail}`, error);
+    },
+    child(subsystemOrOptions: string | Partial<PluginLoggerOptions>): PluginLogger {
+      const childOptions: PluginLoggerOptions =
+        typeof subsystemOrOptions === "string"
+          ? { ...options, version: resolvedVer, banner: false, subsystem: subsystemOrOptions }
+          : { ...options, version: resolvedVer, banner: false, ...subsystemOrOptions };
+
+      return createPluginLogger(pluginId, childOptions);
+    },
+  };
+}