@xpufx/paseo-mcp-tools 0.1.3

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

@@ -0,0 +1,169 @@
+import { z } from "zod";
+import type { StatusVariant } from "./types";
+
+export const CustomPillThresholdsSchema = z.object({
+  warning: z.number().optional(),
+  danger: z.number().optional(),
+  /**
+   * If true, lower values trigger warnings/dangers instead of higher values
+   * (e.g. disk space remaining, battery percentage).
+   */
+  invert: z.boolean().optional(),
+});
+
+export const CustomPillModalSchema = z.object({
+  title: z.string().optional(),
+  description: z.string().optional(),
+  command: z.string().optional(),
+  /**
+   * Whether to format command output as monospace preformatted text (default: true).
+   */
+  preformatted: z.boolean().default(true),
+});
+
+export const CustomPillDefinitionSchema = z.object({
+  /**
+   * Unique identifier for the custom pill (e.g. "gpu-util", "docker-count").
+   */
+  id: z.string().min(1),
+
+  /**
+   * Title shown in the composer trackbar (e.g. "GPU", "Docker").
+   */
+  title: z.string().min(1),
+
+  /**
+   * Compact title shown when layout is compact (e.g. "G"). Defaults to title.
+   */
+  compactTitle: z.string().optional(),
+
+  /**
+   * Lucide icon name (e.g. "Cpu", "Flame", "HardDrive", "Layers").
+   */
+  icon: z.string().optional(),
+
+  /**
+   * Optional compact icon name. Defaults to icon.
+   */
+  compactIcon: z.string().optional(),
+
+  /**
+   * Shell command executed periodically to produce the pill's value.
+   * Can use session environment variables like $PASEO_AGENT_ID, $PASEO_WORKSPACE_ID.
+   */
+  command: z.string().min(1),
+
+  /**
+   * Optional prefix prepended to the output value (e.g. "$", "#").
+   */
+  prefix: z.string().optional(),
+
+  /**
+   * Optional suffix appended to the output value (e.g. "%", "ms", "GB").
+   */
+  suffix: z.string().optional(),
+
+  /**
+   * Polling interval in milliseconds. Minimum 500ms, defaults to 5000ms.
+   */
+  intervalMs: z.number().min(500).default(5000),
+
+  /**
+   * Execution timeout in milliseconds. Defaults to 10000ms.
+   */
+  timeoutMs: z.number().min(500).default(10000),
+
+  /**
+   * Optional threshold rules to automatically transition badge color to warning or danger.
+   */
+  thresholds: CustomPillThresholdsSchema.optional(),
+
+  /**
+   * Optional modal configuration shown when the pill is pressed.
+   */
+  modal: CustomPillModalSchema.optional(),
+
+  /**
+   * Whether this custom pill is enabled. Defaults to true.
+   */
+  enabled: z.boolean().default(true),
+
+  /**
+   * Absolute path to the config file that defined this pill (e.g.
+   * ~/.paseo/top/pills/disk-usage.jsonc). Injected at discovery time; not
+   * intended to be authored in the config file itself.
+   */
+  sourceFile: z.string().optional(),
+});
+
+export type CustomPillDefinition = z.infer<typeof CustomPillDefinitionSchema>;
+export type CustomPillThresholds = z.infer<typeof CustomPillThresholdsSchema>;
+export type CustomPillModal = z.infer<typeof CustomPillModalSchema>;
+
+export interface CustomPillState {
+  id: string;
+  title: string;
+  compactTitle?: string;
+  icon?: string;
+  compactIcon?: string;
+  rawValue: string;
+  displayValue: string;
+  numericValue?: number;
+  status: StatusVariant;
+  lastUpdated: number;
+  error?: string;
+  sourceFile?: string;
+  modalTitle?: string;
+  modalDescription?: string;
+  modalOutput?: string;
+  modalError?: string;
+  modalLastUpdated?: number;
+}
+
+/**
+ * Extracts a numeric value from the raw command output string (e.g. "45.2%" -> 45.2).
+ */
+export function parseNumericPillValue(rawValue: string): number | undefined {
+  const match = rawValue.match(/-?\d+(\.\d+)?/);
+  if (!match) return undefined;
+  const num = parseFloat(match[0]);
+  return Number.isNaN(num) ? undefined : num;
+}
+
+/**
+ * Resolves the status variant based on numeric value and thresholds.
+ */
+export function resolveCustomPillStatus(
+  numericValue: number | undefined,
+  thresholds?: CustomPillThresholds,
+): StatusVariant {
+  if (numericValue === undefined || !thresholds) {
+    return "neutral";
+  }
+
+  const { warning, danger, invert } = thresholds;
+
+  if (invert) {
+    if (danger !== undefined && numericValue <= danger) return "danger";
+    if (warning !== undefined && numericValue <= warning) return "warning";
+    return "success";
+  }
+
+  if (danger !== undefined && numericValue >= danger) return "danger";
+  if (warning !== undefined && numericValue >= warning) return "warning";
+  return "neutral";
+}
+
+/**
+ * Formats the raw output string with optional prefix and suffix.
+ */
+export function formatPillDisplay(
+  rawValue: string,
+  prefix?: string,
+  suffix?: string,
+): string {
+  const cleaned = rawValue.trim();
+  const pre = prefix ?? "";
+  const suf = suffix ?? "";
+  return `${pre}${cleaned}${suf}`;
+}

package/shared/vendor/paseo-plugin-helper/forge.ts

@@ -0,0 +1,110 @@
+/**
+ * Shared forge brand-mark resolution.
+ *
+ * One host/kind -> mark table for every plugin that shows forge iconography,
+ * so plugins never carry their own per-forge icon maps. The client-side
+ * `<ForgeIcon>` renders this descriptor; server/shared code can consume the
+ * pure resolver without pulling in React.
+ *
+ * GitHub and GitLab resolve to their Lucide marks; Codeberg, Forgejo and Gitea
+ * have no Lucide equivalent and resolve to helper-drawn official mono marks.
+ */
+
+export type ForgeKind =
+  | "github"
+  | "gitlab"
+  | "codeberg"
+  | "forgejo"
+  | "gitea"
+  | "generic";
+
+export interface ResolvedForgeMark {
+  /** Stable forge identity. */
+  kind: ForgeKind;
+  /** Human-readable forge name for labels and accessibility. */
+  label: string;
+  /** Host Lucide icon name; the exact mark on hosts with SVG support, the closest fallback otherwise. */
+  lucideName: string;
+  /** True when `<ForgeIcon>` draws the official mark instead of delegating to the host icon set. */
+  custom: boolean;
+}
+
+export interface ForgeMarkInput {
+  /** Forge hostname, e.g. `codeberg.org` or `forge.example.com`. */
+  host?: string | null;
+  /** Explicit forge identity; wins over host detection when it names a known forge. */
+  kind?: ForgeKind | string | null;
+}
+
+const FORGE_MARKS: Record<ForgeKind, ResolvedForgeMark> = {
+  github: { kind: "github", label: "GitHub", lucideName: "Github", custom: false },
+  gitlab: { kind: "gitlab", label: "GitLab", lucideName: "Gitlab", custom: false },
+  codeberg: { kind: "codeberg", label: "Codeberg", lucideName: "Mountain", custom: true },
+  forgejo: { kind: "forgejo", label: "Forgejo", lucideName: "Hammer", custom: true },
+  gitea: { kind: "gitea", label: "Gitea", lucideName: "Coffee", custom: true },
+  generic: { kind: "generic", label: "Git forge", lucideName: "Globe", custom: false },
+};
+
+const FORGE_KINDS: ForgeKind[] = [
+  "github",
+  "gitlab",
+  "codeberg",
+  "forgejo",
+  "gitea",
+  "generic",
+];
+
+/**
+ * Reduce a remote URL, `owner/repo` slug or bare hostname to a lowercase
+ * hostname without scheme, userinfo, port, path or a leading `www.`.
+ */
+export function normalizeForgeHost(host: string | null | undefined): string | null {
+  if (!host || typeof host !== "string") return null;
+  let value = host.trim().toLowerCase();
+  if (!value) return null;
+  value = value.replace(/^[a-z][a-z0-9+.-]*:\/\//, "");
+  value = value.replace(/^[^@/]+@/, "");
+  value = value.split("/")[0]!.split("?")[0]!.split("#")[0]!;
+  // Cuts both `host:port` and SCP-style `host:owner/repo` tails.
+  value = value.split(":")[0]!;
+  value = value.replace(/^www\./, "").replace(/\.$/, "");
+  return value || null;
+}
+
+// Ordered: the first match wins. Self-hosted instances routinely carry the
+// project name in their hostname (e.g. `forgejo.example.com`); everything else
+// is an unknown forge and gets the generic fallback.
+const HOST_KIND_RULES: Array<{ matches: (host: string) => boolean; kind: ForgeKind }> = [
+  { matches: (h) => h === "github.com" || h.endsWith(".github.com"), kind: "github" },
+  { matches: (h) => h === "gitlab.com" || h.endsWith(".gitlab.com"), kind: "gitlab" },
+  { matches: (h) => h === "codeberg.org" || h.endsWith(".codeberg.org"), kind: "codeberg" },
+  { matches: (h) => h === "forgejo.org" || h.endsWith(".forgejo.org") || h.includes("forgejo"), kind: "forgejo" },
+  { matches: (h) => h === "gitea.com" || h === "gitea.io" || h.includes("gitea"), kind: "gitea" },
+];
+
+export function isForgeKind(value: unknown): value is ForgeKind {
+  return typeof value === "string" && FORGE_KINDS.includes(value as ForgeKind);
+}
+
+export function forgeKindFromHost(host: string | null | undefined): ForgeKind {
+  const normalized = normalizeForgeHost(host);
+  if (!normalized) return "generic";
+  for (const rule of HOST_KIND_RULES) {
+    if (rule.matches(normalized)) return rule.kind;
+  }
+  return "generic";
+}
+
+/**
+ * Resolve a forge descriptor from a hostname and/or explicit kind. Accepts a
+ * bare host string for the common host-only case.
+ */
+export function resolveForgeMark(
+  input: ForgeMarkInput | string | null | undefined,
+): ResolvedForgeMark {
+  const { host, kind } =
+    input !== null && typeof input === "object" ? input : { host: input, kind: null };
+  const explicit = typeof kind === "string" ? kind.trim().toLowerCase() : null;
+  const resolved = isForgeKind(explicit) ? explicit : forgeKindFromHost(host);
+  return FORGE_MARKS[resolved];
+}

package/shared/vendor/paseo-plugin-helper/formatters.ts

@@ -0,0 +1,271 @@
+import type { StatusVariant } from "./types";
+
+export interface FormatBytesOptions {
+  /**
+   * Number of decimal places (default: 1).
+   */
+  decimals?: number;
+
+  /**
+   * If true, produces compact format with no space and single-character suffix
+   * (e.g. "5.3G", "320M", "1.2K"). Ideal for width-constrained composer pills.
+   */
+  compact?: boolean;
+
+  /**
+   * Fixes output unit (e.g. "GB" or "MB") regardless of value size.
+   */
+  fixedUnit?: "B" | "KB" | "MB" | "GB" | "TB";
+}
+
+/**
+ * Formats a raw byte count into a human-readable string.
+ * Supports standard ("1.5 GB", "320 KB") and compact ("1.5G", "320K") formats.
+ */
+export function formatBytes(
+  bytes: number,
+  optionsOrDecimals: FormatBytesOptions | number = 1,
+): string {
+  if (!Number.isFinite(bytes) || bytes <= 0) return "0 B";
+
+  const options: FormatBytesOptions =
+    typeof optionsOrDecimals === "number"
+      ? { decimals: optionsOrDecimals }
+      : optionsOrDecimals;
+
+  const { decimals = 1, compact = false, fixedUnit } = options;
+  const k = 1024;
+  const dm = decimals < 0 ? 0 : decimals;
+  const sizes = ["B", "KB", "MB", "GB", "TB", "PB"];
+  const compactSizes = ["B", "K", "M", "G", "T", "P"];
+
+  let unitIndex = Math.floor(Math.log(bytes) / Math.log(k));
+  if (fixedUnit) {
+    const found = sizes.indexOf(fixedUnit);
+    if (found !== -1) unitIndex = found;
+  }
+
+  const clampedIndex = Math.max(0, Math.min(unitIndex, sizes.length - 1));
+  const value = bytes / Math.pow(k, clampedIndex);
+
+  if (compact) {
+    return `${value.toFixed(dm)}${compactSizes[clampedIndex]}`;
+  }
+
+  return `${value.toFixed(dm)} ${sizes[clampedIndex]}`;
+}
+
+export interface MetricThresholds {
+  /**
+   * Threshold for warning status (default: 75).
+   */
+  warning?: number;
+
+  /**
+   * Threshold for danger status (default: 90).
+   */
+  danger?: number;
+
+  /**
+   * Inverts logic: lower values become worse (e.g. battery level, disk free space).
+   */
+  invert?: boolean;
+}
+
+/**
+ * Evaluates a numeric percentage metric (0 - 100) against warning and danger thresholds.
+ */
+export function resolveMetricStatus(
+  value: number,
+  thresholds: MetricThresholds = {},
+): StatusVariant {
+  const { warning = 75, danger = 90, invert = false } = thresholds;
+
+  if (!invert) {
+    if (value >= danger) return "danger";
+    if (value >= warning) return "warning";
+    return "success";
+  } else {
+    if (value <= danger) return "danger";
+    if (value <= warning) return "warning";
+    return "success";
+  }
+}
+
+/**
+ * Formats uptime seconds into concise human-readable duration (e.g. "3d 4h 12m", "45m").
+ */
+export function formatUptime(seconds: number): string {
+  if (!Number.isFinite(seconds) || seconds <= 0) return "0m";
+  const days = Math.floor(seconds / 86400);
+  const hours = Math.floor((seconds % 86400) / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+  const secs = Math.floor(seconds % 60);
+
+  if (days > 0) return `${days}d ${hours}h ${minutes}m`;
+  if (hours > 0) return `${hours}h ${minutes}m`;
+  if (minutes > 0) return `${minutes}m`;
+  return `${secs}s`;
+}
+
+/**
+ * Formats milliseconds into human-readable latency or duration (e.g. "45ms", "1.2s", "3m 12s").
+ */
+export function formatDuration(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 0) return "0ms";
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  const seconds = ms / 1000;
+  if (seconds < 60) return `${seconds.toFixed(1)}s`;
+  return formatUptime(Math.round(seconds));
+}
+
+/**
+ * Formats a number with comma separators (e.g. 1,234,567).
+ */
+export function formatNumber(num: number): string {
+  if (!Number.isFinite(num)) return "0";
+  return new Intl.NumberFormat("en-US").format(num);
+}
+
+export interface FormatCompactNumberOptions {
+  /** Number of decimal places when abbreviated (default: 1). */
+  decimals?: number;
+  /** Minimum threshold before abbreviating with K/M/B suffixes (default: 1000). */
+  threshold?: number;
+}
+
+/**
+ * Formats a count or token number into a compact string (e.g. 950 -> "950", 1250 -> "1.3k", 1450000 -> "1.5M").
+ * Ideal for pills, vitals chips, and narrow timeline badges.
+ */
+export function formatCompactNumber(
+  num: number,
+  options: FormatCompactNumberOptions = {},
+): string {
+  if (!Number.isFinite(num)) return "0";
+  const { decimals = 1, threshold = 1000 } = options;
+  const abs = Math.abs(num);
+  if (abs < threshold) return `${Math.round(num)}`;
+  const sign = num < 0 ? "-" : "";
+  if (abs >= 1_000_000_000) {
+    const val = (abs / 1_000_000_000).toFixed(decimals);
+    return `${sign}${val.replace(/\.0$/, "")}B`;
+  }
+  if (abs >= 1_000_000) {
+    const val = (abs / 1_000_000).toFixed(decimals);
+    return `${sign}${val.replace(/\.0$/, "")}M`;
+  }
+  const val = (abs / 1_000).toFixed(decimals);
+  return `${sign}${val.replace(/\.0$/, "")}k`;
+}
+
+export interface TruncateOptions {
+  /** Ellipsis token to insert. Default: "…" */
+  ellipsis?: string;
+}
+
+export interface TruncatePathOptions extends TruncateOptions {
+  /** Directory separator. Default: "/" */
+  separator?: string;
+  /** Keep leading path segments (e.g. 1 keeps the root/first folder). Default: 1 */
+  keepLeading?: number;
+  /** Keep trailing path segments (e.g. 1 keeps the filename). Default: 1 */
+  keepTrailing?: number;
+}
+
+/**
+ * Safely truncates a string with an ellipsis if it exceeds maxLength.
+ */
+export function truncate(text: string, maxLength: number, suffix = "…"): string {
+  if (!text || text.length <= maxLength) return text;
+  return text.slice(0, Math.max(0, maxLength - suffix.length)) + suffix;
+}
+
+/**
+ * Truncates a string in the middle, preserving distinct head and tail characters.
+ * Ideal for UUIDs, commit SHAs, hashes, cryptographic keys, and long identifiers.
+ *
+ * Example: `truncateMiddle("0359a72f-5b58-453b-a35b-956a3f6908ba", 16)` => `"0359a72…6908ba"`
+ */
+export function truncateMiddle(text: string, maxLength: number, options?: TruncateOptions): string {
+  if (!text || text.length <= maxLength) return text;
+  const ellipsis = options?.ellipsis ?? "…";
+  if (maxLength <= ellipsis.length) return ellipsis.slice(0, maxLength);
+
+  const available = maxLength - ellipsis.length;
+  const headLength = Math.floor(available / 2);
+  const tailLength = available - headLength;
+
+  const head = text.slice(0, headLength);
+  const tail = tailLength > 0 ? text.slice(-tailLength) : "";
+  return `${head}${ellipsis}${tail}`;
+}
+
+/**
+ * Truncates file system and URL paths intelligently, preserving the leaf filename
+ * and root directory while compressing intermediate parent directories.
+ *
+ * Example: `truncatePath("~/code/paseo-plugin-helper/src/client/approvals.tsx", 35)`
+ *       => `"~/code/…/src/client/approvals.tsx"`
+ */
+export function truncatePath(filePath: string, maxLength: number, options?: TruncatePathOptions): string {
+  if (!filePath || filePath.length <= maxLength) return filePath;
+
+  const sep = options?.separator ?? "/";
+  const ellipsis = options?.ellipsis ?? "…";
+  let keepLeading = options?.keepLeading ?? 1;
+  const keepTrailing = options?.keepTrailing ?? 1;
+
+  // If path starts with separator (e.g. /home/...), parts[0] is empty, so adjust keepLeading
+  if (filePath.startsWith(sep) && keepLeading === 1) {
+    keepLeading = 2; // Keep ["", "home"] which joins to "/home"
+  }
+
+  const parts = filePath.split(sep);
+  // If no path separators or very few segments, fallback to truncateMiddle
+  if (parts.length <= keepLeading + keepTrailing) {
+    return truncateMiddle(filePath, maxLength, { ellipsis });
+  }
+
+  const prefixParts = parts.slice(0, keepLeading);
+  const suffixParts = parts.slice(parts.length - keepTrailing);
+  let middleParts = parts.slice(keepLeading, parts.length - keepTrailing);
+
+  // Progressive compression: drop elements from start of middle until it fits
+  while (middleParts.length > 0) {
+    const candidate = [...prefixParts, ellipsis, ...middleParts, ...suffixParts].join(sep);
+    if (candidate.length <= maxLength) {
+      return candidate;
+    }
+    middleParts.shift();
+  }
+
+  // If still too long with full ellipsis, just join prefix + ellipsis + suffix
+  const minimalCandidate = [...prefixParts, ellipsis, ...suffixParts].join(sep);
+  if (minimalCandidate.length <= maxLength) {
+    return minimalCandidate;
+  }
+
+  // If even prefix + ellipsis + filename exceeds maxLength, middle-truncate the filename
+  const filename = suffixParts.join(sep);
+  const prefix = prefixParts.join(sep);
+  const availableForFile = maxLength - prefix.length - sep.length - ellipsis.length - sep.length;
+  if (availableForFile > 4) {
+    return `${prefix}${sep}${ellipsis}${sep}${truncateMiddle(filename, availableForFile, { ellipsis })}`;
+  }
+
+  return truncateMiddle(filePath, maxLength, { ellipsis });
+}
+
+/**
+ * Strips ANSI escape sequences (colors, text formatting, cursor controls) from terminal output strings.
+ */
+export function stripAnsi(text: string): string {
+  if (!text) return "";
+  // Matches 7-bit ASCII and 8-bit ANSI escape codes
+  return text.replace(
+    // eslint-disable-next-line no-control-regex
+    /[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g,
+    ""
+  );
+}