@xpufx/paseo-forges 0.1.0

package/server/settings.ts

@@ -0,0 +1,52 @@
+import {
+  PluginStorage,
+  createPluginLogger,
+  createSettingsHandlers,
+} from "paseo-plugin-helper/server";
+import {
+  FORGES_PLUGIN_ID,
+  activeForgeForDirectory,
+  forgeSettingsContract,
+  type ForgeSettings,
+} from "../shared/issues.js";
+
+export const log = createPluginLogger(FORGES_PLUGIN_ID);
+
+export const forgeStorage = new PluginStorage<ForgeSettings>(
+  FORGES_PLUGIN_ID,
+  "settings.json",
+  { schema: forgeSettingsContract.schema },
+);
+
+export const settingsHandlers = createSettingsHandlers(
+  forgeSettingsContract,
+  forgeStorage,
+  {
+    onUpdate: (newSettings) => {
+      log.info("Forge settings updated via RPC:", newSettings);
+    },
+    onReset: () => {
+      log.info("Forge settings reset to default values");
+    },
+  },
+);
+
+/**
+ * Explicit forge target selected for a workspace directory, if any. Reflects
+ * the per-workspace `activeForgeByDirectory` choice, falling back to the legacy
+ * single remote override when no selection was ever made (issue #137).
+ */
+export async function storedForgeSelection(
+  directory: string | undefined,
+): Promise<string | undefined> {
+  if (!directory) return undefined;
+  const settings = await forgeStorage.readAsync();
+  return activeForgeForDirectory(settings, directory) ?? undefined;
+}
+
+/** Daemon-side API token for a forge host. Never leaves the server. */
+export async function tokenForHost(host: string): Promise<string | undefined> {
+  const settings = await forgeStorage.readAsync();
+  const token = settings.tokensByHost?.[host];
+  return typeof token === "string" && token.trim() ? token.trim() : undefined;
+}

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

@@ -0,0 +1,85 @@
+import { safeExec } from "./process";
+
+export interface AgentIdentity {
+  id?: string;
+  name?: string;
+  model?: string;
+  provider?: string;
+  repo?: string;
+  branch?: string;
+  envelopeText?: string;
+}
+
+export interface AgentIdentityOptions {
+  timeoutMs?: number;
+  envelopeCommand?: string;
+}
+
+const ENV_KEYS = [
+  "AGENT_ID",
+  "AGENT_NAME",
+  "AGENT_MODEL",
+  "AGENT_PROVIDER",
+  "PASEO_AGENT_ID",
+] as const;
+
+function readEnvIdentity(env: NodeJS.ProcessEnv = process.env): AgentIdentity | null {
+  const id = env.PASEO_AGENT_ID || env.AGENT_ID || undefined;
+  const name = env.AGENT_NAME || undefined;
+  const model = env.AGENT_MODEL || undefined;
+  const provider = env.AGENT_PROVIDER || undefined;
+  if (!id && !name && !model && !provider) return null;
+  return { id, name, model, provider };
+}
+
+function normalizeEnvelopeJson(raw: unknown): AgentIdentity | null {
+  if (!raw || typeof raw !== "object") return null;
+  const o = raw as Record<string, unknown>;
+  const str = (v: unknown): string | undefined =>
+    typeof v === "string" && v.length > 0 ? v : undefined;
+  const identity: AgentIdentity = {
+    id: str(o.id) ?? str(o.agentId),
+    name: str(o.name) ?? str(o.agentName),
+    model: str(o.model),
+    provider: str(o.provider),
+    repo: str(o.repo) ?? str(o.workspace),
+    branch: str(o.branch),
+    envelopeText: str(o.envelopeText) ?? str(o.envelope),
+  };
+  if (!identity.id && !identity.name && !identity.model && !identity.provider && !identity.repo && !identity.branch) return null;
+  return identity;
+}
+
+export async function getAgentIdentity(
+  options: AgentIdentityOptions = {},
+): Promise<AgentIdentity | null> {
+  const timeoutMs = options.timeoutMs ?? 5000;
+  const command = options.envelopeCommand ?? "xpufx-tool envelope --format json";
+  const envIdentity = readEnvIdentity();
+  void ENV_KEYS;
+  try {
+    const result = await safeExec(command, { timeoutMs });
+    if (result.code !== 0) return envIdentity;
+    const text = result.stdout.trim();
+    if (!text) return envIdentity;
+    try {
+      const parsed: unknown = JSON.parse(text);
+      const cliIdentity = normalizeEnvelopeJson(parsed);
+      if (!cliIdentity) return envIdentity;
+      if (!envIdentity) return cliIdentity;
+      return {
+        id: envIdentity.id ?? cliIdentity.id,
+        name: envIdentity.name ?? cliIdentity.name,
+        model: envIdentity.model ?? cliIdentity.model,
+        provider: envIdentity.provider ?? cliIdentity.provider,
+        repo: cliIdentity.repo,
+        branch: cliIdentity.branch,
+        envelopeText: cliIdentity.envelopeText,
+      };
+    } catch {
+      return envIdentity;
+    }
+  } catch {
+    return envIdentity;
+  }
+}

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